%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This file is part of the MPATTERN package
%
% Author: Piotr Bolek
% version: 0.2 (Sep 25, 1998)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Description
===========

Package MPATTERN gives ability to define and use patterns in
MetaPost. It uses Pattern Color Space available in PostScript Level 2.

Package contains four files:
- mpattern.mp: MetaPost macros for defining and using patterns.
- mpp: perl script invoking MetaPost program and postprocessing
  postscript output files of pictures in which patterns were used.
- README: short description in English.
- README.PL: short description in Polish.
- test.mp, test.tex, test.ps: usage examples.

Using package
=============

In order to use patterns for filling areas in MetaPost pictures the
script mpp from package should be used for processing input MetaPost
files instead direct invocation of MetaPost program. This script
invokes MetaPost program and later modifies its output files in which
patterns were used.

User Interface
==============

Defining pattern
----------------

Patterns are defined using the following construct:

beginpattern(<name_of_pattern>);
...
endpattern;

Parameter <name_of_pattern> is the name by which the pattern is
identified. This name can contain letters and underscore characters
"_" but not digits. This name should NOT be given in quotes.

One or more of the following macros can be invoked in any place
inside pattern definition (between beginpattern and endpattern):
- patternbbox(<pair>,<pair>)
- patternbbox((<numeric>,<numeric>,<numeric>,<numeric>) 
  Explicit coordinates of bounding box of pattern cell

- patternxstep(<numeric>)
- patternystep(<numeric>)
- patternstep(<numeric>,<numeric>)
- patternstep(<pair>)
  Pattern spacing

- patterntransform(<transform>)
  Transformation of pattern shape

- patterncolor(0<= <numeric> <= 1)
  Explicit color replaced later by pattern

Each pattern is temporarily written as picture with big number
(default is 999) but when user will use this number for his own
picture then for temporal storing of next patterns the greatest free
number less then 999 will be used.

Using patterns
--------------

Already defined pattern can be used for filling objects with
two argument withpattern macro. It is used as follows:

<path> withpattern <name_of_pattern>;

where <path> is any valid expression defining closed path and
<name_of_pattern> is the name given in definition of the pattern.

Example
-------

Here is code to draw two circles filled with different checker
patterns.

input mpattern;

beginpattern(checker);
 d:=4mm;
 fill unitsquare scaled d;
 fill unitsquare scaled d shifted (d,d);
 patternbbox(0,0,2d,2d);
endpattern;

beginpattern(rotated_checker);
 fill unitsquare scaled 4mm rotated 45 withcolor .7white;
endpattern;

beginfig(11);
 path p;
 z1=(1cm,1cm);
 p=fullcircle scaled 3cm;
 fill p withpattern checker;
 unfill p shifted z1;
 fill p shifted z1 withpattern rotated_checker;
endfig;

Distribution of the package
===========================

The package MPATTERN belongs to the public domain.

Contact with author
===================

e-mail: P.Bolek@ia.pw.edu.pl