%%%
%%%  File: grafdoc.tex
%%%

\magnification=\magstep1

\input header

% metacode macro
\let\texmacro=\macro

\centerline{\bf MFpic's \file{grafbase.mf} \MF{} macros}
\centerline{\file{grafbase.mf} Version:  0.2.10.2 alfa}
\centerline{\file{grafbase.mf} Date:  Tue 23 Jan 1996}
\centerline{Document Author:  Geoffrey Tobin (\mail{G.Tobin@latrobe.edu.au})}
\centerline{Document Version:  0.2.10.3 alfa}
\centerline{Document Date:  Tue 6 Feb 1996}


\head{Background}

\MF{} should be moderately familiar to anyone who is serious about
understanding \file{grafbase.mf}.

The best reference for \MF{} programming is undoubtedly Professor
Donald E.~Knuth's \MFbook{}, first published by
Addison-Wesley and copyrighted by the American Mathematical Society
in 1986, ISBN 0-201-13445-4.

However, the file \file {mf-revu.tex} contains reminders of some facets
of \MF{}.


\head{Assumed Variables}

The file \file{grafbase.mf} assumes that the \MF{} variables
\mfc {w}, \mfc {h},
\gbc {xneg}, \gbc {xpos}, \gbc {yneg} and \gbc {ypos}
are all \mfc {numeric} and \mfc {known}.
The values of \mfc{w} and \mfc{h} are set by the plain \MF{} macro
\mfc{beginchar}.
By contrast, the four graph extents variables, \gbc {xneg},
\gbc {xpos}, \gbc {yneg} and \gbc {ypos} must be set externally.

In practice, we would most often use \file{grafbase.mf} together with
\file{mfpic.tex}, in which case \prog{mfpic} writes a \MF{} file that
inputs \file{grafbase.mf} and automatically sets the four extents, as
well as determining \mfc{w} and \mfc{h} in the customary plain \MF{}
way via \mfc{beginchar}.
The information for all six values is taken from the arguments
to the \texmacro{mfpic} macro from \file{mfpic.tex}.


\head{Preliminaries}

metapost.

It would be good if \file{grafbase.mf} could be used with \MP{} as
well as with \MF{}.  As a step toward that goal, \file{grafbase.mf}
uses the \mfc{boolean} variable \gbc{metapost} to record whether it
thinks it's being used with \MP{}.  Since \MF{} has no colors, it
seems reasonable that the presence of \mfc{blue} is a reliable sign of
\MP{}, so \file{grafbase.mf} tests for \mfc{blue} is known.

\MP{} lacks many of the plain \MF{} definitions, so for
\file{grafbase.mf} to stand a chance of working with \MP{}, the plain
\MF{} consistency macros file \mfc{mfplain.mp} must be loaded.  If it
seems that it has not been loaded, then \file{grafbase.mf} attempts to
load it.

If \MP{} is evidently not being used, the \file{grafbase.mf} will need
the \file{plain.mf} macros.  Usually, this will be so, but if by any
ill chance it's not, then \file{grafbase.mf} will attempt to load that
file% lift that bale :-)
.

To be frank, I have no idea what to do about \MF{} modes when \MP{} is
being used.  However, in an approximation of reasonableness, I chose
the very common `cx' mode.  Does this work with \MP{} ?

Before calling \mfc{mode\_setup}, it seems reasonable, given the
purpose of \prog{mfpic} and \file{grafbase.mf}, to require an explicit
mode when calling \MF{}, instead of the frequently vexing, silent,
default of using \mfc{proof} mode, which \file{plain} \MF{} falls back
on when no mode is specified.  So in that case, \file{grafbase.mf}
preempts the default with an error message.

The \mfc{font\_identifier} is set to \gbc {"MFpic graphics"}, to make
the origin of the PK file obvious.  Since there can be no generally
useful coding scheme for graphics, the \mfc{font\_coding\_scheme} is
set to \gbc {"Arbitrary"}.

It would be agreeable if \mfc{designsize} could be the same as that
used for the \TeX{} text labels in \prog{mfpic}, say \mfc{10pt\#} or
thereabouts.  Unfortunately, the limited wisdom of \MF{} limits
dimensions to a small multiple of \mfc{designsize}, so
\file{grafbase.mf} has to set \mfc{designsize} to be much larger.
The value chosen (\mfc{128pt\#}) is a power-of-two number of TeX
points, and is large enough to avoid this limitation.


\head{Global Variables}

debug,
grafbase;
mftitle (macro);
deg;
unitlen, xscale, yscale,
xneg, xpos, yneg, ypos;
penwd, drawpen,
hatchwd, hatchpen;
store (macro);
ClipOn, ClipPath.

The \mfc{boolean} variable \gbc {debug} is present mainly for
experimentation with \file{grafbase.mf}, so that any diagnostics
can be turned on or off a little more conveniently.

If the \mfc{boolean} variable \gbc {grafbase} is known, then
\file{grafbase.mf} has been loaded more than once, which is an error.

The \gbc {mftitle} macro is frequently used by \prog{mfpic}, but not
in \file{grafbase.mf} itself.  Its purpose is to create a title (see
\MFbook{} chapter 22: Strings, page 187, paragraph 3), and to display
that title as a message.

So that users can refer to angular quantities in a self-evident way,
the \mfc{numeric} variable \gbc {deg} is set to \mfc{1}.  Thus,
instead of \mfc{45}, one may write \mfc{45 deg} or \mfc{45deg},
to make the meaning obvious.

The dimensions of the drawing are governed by seven variables:
\gbc {unitlen, xscale, yscale, xneg, xpos, yneg, ypos}.
The first three determine the scale of the units used in drawing,
called the \emph {graph} units, while the last four describe the
nominal boundary of the drawing.

\gbc {unitlen} is provided in order to set the most convenient
physical unit, since that may possibly not be one of the units
provided by plain \MF{} (\mfc {bp#, cc#, cm#, dd#, in#, mm#, pc#,
pt#}).  Note that \gbc {unitlen} must, like all
\emph {mode-independent} units, be expressed in \emph {sharp} units.

By contrast \gbc {xscale} and \gbc {yscale} provide \mfc {numeric}
scaling factors for the \emph {graph} units along the horizontal
and vertical coordinate axes (relative to the natural orientation of
the printed paper).

The nominal drawing boundary is the region that \TeX{} will perceive
as the (rectangular) boundary of the character, according to the
\file {TFM} file for the font that \MF{} will produce.
\gbc {xneg, xpos, yneg, ypos} are the coordinates in \emph {graph}
units of the left, right, bottom, and top edges of that boundary.
Normally, the origin of the drawing \emph {differs} from the reference
point of the \file {TFM} file.

The initial values of these seven dimensioning variables are:  \gbc
{unitlen := 1 p{}t#}, one \TeX{} point in absolute (\emph {sharp})
units; {xscale := yscale := 7.227}, so as to make the X and Y scale
drawing units $ 1/10 $ inch each; while \gbc {xneg, xpos, yneg, ypos}
are initialised to $ 0, 10, 0, 10 $, so that both axes extend from
$ 0 $ to $ 10 $ \emph {graph} units.

However, the initial dimensions are not intended to be retained, and
should be altered according to the needs of the drawing.  When
generating the \MF{} file by using \TeX{} or \LaTeX{} with the
\file {mfpic.tex} macros, this is what the arguments of the
\macro {mfpic} environment in \file {mfpic.tex} are for.
To set \gbc {unitlen}, one uses the \macro {mfpicunit} macro of
\file {mfpic.tex}.

When drawing, the \mfc{pen} variable \gbc {drawpen} is used,
which is a circular \mfc{pen}.  Its diameter, in \emph {sharp}
coordinates, is determined by the \mfc{internal} variable
\gbc {penwd}, which \file{grafbase.mf} initialises to
\mfc {0.5{}p{}t}.
(See the Coordinate Conversion section below for a description
of `sharp coordinates'.)

For hatching, the \mfc{pen} variable \gbc {hatchpen} is used,
which is a circular \mfc{pen}.  Its diameter, in \emph {sharp}
coordinates, is determined by the \mfc{internal} variable
\gbc {hatchwd}, which \file{grafbase.mf} initialises to
\mfc {1{}p{}t}.

The \gbc {store ($f_s$) $f$} macro is for the purpose of storing a
\mfc{path} expression, which may be quite complex, into a \mfc{path}
variable.
This is remarkably useful to \prog{mfpic}.

The \mfc{internal} numeric variable \gbc {ClipOn} is zero when
clipping of the current \gbc {active\_plane} is disabled, and nonzero
when such clipping is enabled.

The current clipping region is specified by the \mfc{path} array
\gbc {ClipPath}.  The \mfc {numeric} value of \gbc {ClipPath} equals
the number of \mfc{path}s in the array, which are numbered from one
upwards:  \gbc {ClipPath[1]$\ldots$ClipPath[ClipPath]} (\emph{sic}).


\head{Frank Michielsen's macros}

Macros:  list, pathlength, timelist, dashlist, dotlist.
Global parameters:  segmentsplit, dashsize, dashgap, dashstart,
dashfinish, dotgap.

\subhead {Updating of Explanation by Frank Michielsen
(\mail{e-mail:   frankmih@sun.mcs.clarkson.edu})
of his macros and their global parameters.}

\beginverbatim


Macros:


  list          -  assigns the list contained in its second argument
                   to its first argument.

  pathlength    -  calculates the approximated length of a path.

  timelist      -  takes a list of pathlengths as its second argument,
                   a path as its third argument, and assigns the
                   list of times corresponding to the pathlengths to
                   its first argument.

  dashlist      -  takes a path as its second argument, creates an
                   appropriate dashpattern for it, and assigns a list
                   of subpaths corresponding to this dashpattern
                   to its first argument.

  dotlist       -  takes a path as second argument, creates a dot
                   pattern for it, and assigns the list of
                   dot-positions to its first argument.


Global Parameters:

  
  segmentsplit  -  the number of pieces in which to divide segments
                   of the MF path.

  dashsize      -  the length of a dash.
  dashgap       -  the spacing between two dashes.
  dashstart     -  the relative length of the first dash.
  dashfinish    -  the relative length of the last dash.

  dotgap        -  the distance between two dots.


Example of use:


  pair ps[];
  path p,dp[];

  list(ps)( (0pt,0pt), (10pt,20pt), (30pt,5pt), (40pt,0pt) );
  p:= ps[1] .. ps[2] .. ps[3] .. ps[4];

  dashlist(dp)(p);
  pickup pencircle scaled .5pt;
 
  for i=1 upto dp: 
    draw dp[i];
  endfor


\endverbatim


\head{Utility Macros}

map, maparr;
textpairs;
floorpair, ceilingpair, hroundpair;
minpair, maxpair.

As noted in the source, \mfc {text} arguments, which are used in many
of the macros in \file{grafbase.mf}, are perilous in a high degree,
because they can easily cause naming conflicts with local variables in
macros that use them.  This typically produces obscure error messages.

However, \mfc {text} arguments are very useful, and \MF{} has no
useful alternative, as it lacks a sense of lists as a fully fledged
data structure.  Few language designers seem to learn from this
excellent core feature of Lisp, so we can only muse on what might have
been.

\gbc {map $(m) (t)$} generates a new list from a text list $t$
of one or more items, by applying the macro $m$ to each item
in turn.  This macro $m$ is a \emph {procedure} in the \prog{Pascal}
sense; that is, it should \emph {not} return any value.

\gbc {maparr (proc) ($p$)} applies \gbc {proc}, which should be a
\emph {procedure} with one argument, to each member of the array
$p[]$.  The items in the array may be of any types that \gbc {proc}
can process.

\gbc {textpairs $(p, t)$} converts a text list $t$ of \mfc{pair}s
into an array $p$ of \mfc{pair}s.

\gbc {chpair (proc) ($p$)} applies \mfc {proc} to each \emph {part} of
the \mfc{pair} $p$, then it returns the \mfc{pair} consisting of each
of these two results:  \mfc {(proc (xpart $p$), proc (ypart $p$))}.
Here \mfc {proc} must be a macro with one \mfc {numeric} argument and
which returns one \mfc {numeric} value.  We describe such a macro by
this mathematical notation:
    $\mfc {proc} : \mfc {numeric} \mapsto \mfc {numeric}$.

\gbc {floorpair $(p)$} returns a \mfc{pair} comprising the floors
(rounded-down integer parts) of the X and Y \emph {parts} of the
\mfc{pair} $p$.

\gbc {ceilingpair $(p)$} returns a \mfc{pair} comprising the ceilings
(rounded-up integer parts) of the X and Y \emph {parts} of the
\mfc{pair} $p$.

\gbc {hroundpair $(p)$} returns a \mfc{pair} comprising the hrounds of
(ie, the nearest integers to) the X and Y \emph {parts} of the
\mfc{pair} $p$.

\gbc {minpair $(t)$} returns a \mfc{pair} comprising the minimum X and
Y \emph {parts} of all the \mfc{pair}s in the text list $t$.

\gbc {maxpair $(t)$} returns a \mfc{pair} comprising the maximum X and
Y \emph {parts} of all the \mfc{pair}s in the text list $t$.


\head{Coordinate Conversion}

ztr, invztr,
setztr,
zconv, invzconv;
vconv, invvconv.

\file{grafbase.mf} employs three main (classes of) coordinate systems.
The first describes \emph {graph} coordinates; this is the user's
coordinate system, in which graphs, function plots, the orientation
of axis tic marks, and many other features are described.  The graph
coordinate system can be shifted, rotated, magnified, slanted, and
flipped.  Graph coordinates are device \emph {independent}.

The second is determined by the \emph {sharp} units of \MFbook{};
these represent an upright Cartesian system in which one millimetre
means one millimetre --- in any direction.  Sharp coordinates are
device \emph {independent}.  Quantities that must have a fixed size
are specified in sharp units: for example, the sizes of dots in
shading, spacings between lines in hatching, the dimensions of arrow
heads, and the thicknesses of drawn lines.

The third describes the \emph {pixel} coordinates, which are those of
the pixel grid in the bitmaps formed by \mfc {picture} variables and
written into the GF font file that \MF{} writes; pixels are upright,
but they may not be square, as \MF{}'s modes cater for output devices
(for example, various screens and printers) with differing aspect
ratios --- among other properties that affect how an image is
rendered.  Naturally, pixel coordinates are device \emph {dependent}.
The grafbase macros refer to pixel coordinates through plain \MF{}'s
\mfc {.t\_} construct, through the \mfc{w} and \mfc{h} quantities
calculated by plain \MF{}'s \mfc{beginchar}, and in its manipulations
of \MF{} \mfc{picture} variables.

Ideally, the facility to clip a drawing made using \file {grafbase.mf}
should apply before the bitmap is formed (ie, before the drawing is
rendered), because this would use memory much more efficiently.
However, the details of how to do this have not been thoroughly
thought out, so the coordinate conversion macros, which are affected
by this, are in a state of flux for the foreseeable future.

In \MF{}, the \mfc {transform} data type represents \emph {affine
transforms}, which are the familiar Euclidean transforms formed by
translation (shifting), rotation (turning), mirror reflection
(flipping), scaling (magnifying), and skewing (slanting, obliquing).
In the absence of translation, the operations performed are called
\emph {linear transforms}.  

There is a significant difference between affine transformations,
which are used to transform coordinates, and vector (displacement)
transformations, because the in general the former depend on the
absolute position, whereas the latter act independently of it.
Therefore we need a separate pair of \mfc{transform}s for when
\mfc {pair}s are interpreted as vectors.

\gbc {ztr} is a \mfc{transform} variable describing the conversion
from \emph {graph} to \emph {sharp} coordinates.

\gbc {invztr} is the inverse of \gbc {ztr}.

\gbc {setztr} sets \gbc {ztr}.

\gbc {zconv $(a)$} returns the \emph {sharp} coordinate \mfc {pair}
corresponding to the \emph {graph} coordinate \mfc{pair} $a$.

\gbc {invzconv $(v)$} is the inverse of \gbc {zconv}.

\gbc {vconv $(a)$} returns the \emph {sharp} vector corresponding to
the \emph {graph} vector $a$.

\gbc {invvconv $(v)$} is the inverse of \gbc {vconv}.


\head{Initial Setup}

active\_plane.
initpic.

\gbc {active\_plane} is the active drawing plane, initially defined as
the plain \MF{} \mfc {picture} variable \mfc {currentpicture} which is
\emph {not known} until the call to \mfc {clearit} in
\mfc {beginchar}.

\gbc {initpic} calls \gbc {setztr}, initialises \gbc {active\_plane},
and picks up a circular \mfc{pen} of diameter \gbc {penwd}.


\head{Compatibility with older \file {graphbase.mf}}

mfpicenv, endmfpicenv, bounds.

For compatibility with files produced for older versions of the graph
base, usually named \file {graphbase.mf}, three definitions are
provided.

\gbc {mfpicenv} and \gbc {endmfpicenv} are defined as empty
definitions.

\gbc {bounds (a, b, c, d)} assigns \gbc {xneg, xpos, yneg, ypos}
to \gbc {a, b, c, d} respectively.


\head{Character Wrapper}

beginmfpic, endmfpic.

\gbc {beginmfpic (ch)} is a convenient abbreviation for the typical
use of \mfc {beginchar} with \file{grafbase.mf}.

\gbc {endmfpic} is essentaiialy the same as \mfc {endchar}, but is
meant to match \gbc {beginmfpic}.


\head{Extra Trigonometric and Hyperbolic Functions}

tand, cotd, acos, asin,
exp, ln, cosh, sinh, acosh, asinh.

\gbc {tand $(x)$} is the tangent, in degrees, of $x$.

\gbc {cotd $(x)$} is the cotangent, in degrees, of $x$.

\gbc {acos $(x)$} is the arccosine, in degrees, of $x$.
Evidently, $x$ must be between -1 and +1.

\gbc {asin $(y)$} is the arcsine, in degrees, of $y$;
$y$ must be between -1 and +1.

\gbc {exp $(x)$} is the value of $e^x$.

\gbc {ln $(x)$} is the natural logarithm of $x$.

\gbc {cosh $(x)$} is the hyperbolic cosine of $x$.

\gbc {sinh $(x)$} is the hyperbolic sine of $x$.

\gbc {acosh $(x)$} is the inverse hyperbolic cosine of $x$.

\gbc {asinh $(y)$} is the inverse hyperbolic sine of $y$.


\head{Coordinate Systems and Transformations}

\subhead{Coordinate Nesting}

T\_stack,
T\_push, T\_pop;
bcoords, ecoords.

In order to allow local coordinate systems to be nested without
destructively interfering with each other, we define a stack of
(affine) \mfc {transform}s.

\gbc {T\_stack[]} is an array of \mfc {transform}s, which
\file {grafbase.mf} uses to implement its stack of local coordinate
systems.  Users should avoid using \gbc {T\_stack} by name, as its
security depends on its being used only by the \gbc {bccords} and
\gbc {ecoords} macros.  The same avoidance rule applies to all macros
that have an underscore \gbc{\_} in their name.  This rule is a naming
convention laid down by Knuth.

\gbc {T\_push ($T$)} pushes \mfc {transform} $T$ onto the stack
\gbc {T\_stack}.

\gbc {T\_pop ($T$)} pops the stack \gbc {T\_stack}, and stores its
erstwhile top element in \mfc {transform} $T$.

The purpose of \gbc {bcoords} and \gbc {ecoords} is to enclose a local
coordinate system.  Thus compound objects can be built and
manipulated.

\gbc {bcoords} preserves the value of \mfc {currenttransform}.

\gbc {ecoords} restores the value of \mfc {currenttransform} that was
preserved by the most recent \gbc {bccords}.


\subhead{Coordinate Changes}

apply\_t.
xslant, yslant, zslant, xyswap, boost.

\gbc {apply\_t $(T)$} changes the coordinate system: it replaces
\gbc {currenttransform} by \mfc{transform} $T$ followed by the
\gbc {currenttransform}.

\gbc {xslant $s$} is the same as the \MF{} primitive
\gbc {slanted $s$}:  a point $(x,y)$ maps onto $(x,y) + s(y,0)$.

\gbc {yslant $s$} nicely complements \gbc {xslant} by mapping
a point $(x,y)$ onto $(x,y) + s(0,x)$.

\gbc {zslant $p$}, where $p = (u,v)$, maps $(x,y)$ onto
$(xu+yv, xv+yu)$.  (This complements the \MF{} primitive
\gbc {zscaled $p$} which maps $(x,y)$ onto $(xu-yv,xv+yu)$.)

\gbc {xyswap} swaps the X and Y coordinates:  $(x,y) \mapsto (y,x)$.

\gbc {boost $\chi$} is the same as
\gbc {zslant $(\hbox{\mfc{cosh}} \chi, \hbox{\mfc{sinh}} \chi)$},
which is the formula for a boost (the hyperbolic equivalent of
a rotation) in special relativity.

\subhead{Path Rotation}

rotatepath.

\gbc {rotatedpath $(p, \theta)$ $f$} returns the \emph {sharp}
coordinate \mfc{path} formed by rotating the emph {sharp} coordinate
\mfc{path} $f$ by $\theta$ (\emph {graph} coordinate) degrees around
the point described by the \emph {graph} cooordinate \mfc{pair} $p$.


\head{Bitmaps, Clipping and Rendering}

\subhead{Bitmap to Bitmap --- Bitwise Operations}

mono.
andto, picand;
orto, picor;
xorto, picxor;
subto, picsub.

\MF{}'s \mfc{picture} variables are not pure bitmaps; each pixel is a
negative, zero or positive weight.  When the \mfc{shipout} primitive
is called, as in \mfc{shipout $v$;} where $v$ is a \mfc{picture}
variable, the pixels of positive weight in $v$ are interpreted as
value one ($1$), and those of zero or negative weight are interpreted
as zero ($0$).  The \file {GF} font file uses run-length encoding to
efficiently record the positions of the pixels of value one ($1$).

When \MF{} draws pixels in a \mfc{picture} variable, it does so via
one of the forms of the \mfc {addto} primitive.  The result of this
\emph {rendering} are pixels of various weights, as mentioned above.

In order to perform certain \mfc{picture} manipulation tasks, such as
clipping to a given boundary curve, it is highly beneficial that
pixels be either one or zero --- in other words, \mfc{picture}s should
be pure bitmaps.

Of course, the possible use of \MP{} presents a problem, as \MP{}
entirely lacks bitmaps.  It's not yet decided how to handle the
bitmap operations in the context of \MP{}.  For the moment, I just
turn \MF{}'s \mfc {keeping} and \mfc {cull} operations off, as \MP{}
has never heard of them --- not even in its \prog {mfplain} macros.


The operation \gbc {mono $(v)$} changes \mfc{picture} $v$ so that all
positive pixels are replaced by one ($1$) and all negative or zero
pixels by zero ($0$).

\gbc {andto} ($v, w$) replaces \mfc{picture} $v$ by the bitwise
\emph {and} of $v$ and $w$.

$v$ \gbc {picand} $w$ returns the \mfc{picture} formed by the bitwise
\emph {and} of $v$ and $w$.

\gbc {orto} ($v, w$) replaces \mfc{picture} $v$ by the bitwise
\emph {or} of $v$ and $w$.

$v$ \gbc {picor} $w$ returns the \mfc{picture} formed by the bitwise
inclusive \emph {or} of $v$ and $w$.

\gbc {xorto} ($v, w$) replaces \mfc{picture} $v$ by the bitwise
\emph {exclusive or} of $v$ and $w$.

$v$ \gbc {picxor} $w$ returns the \mfc{picture} formed by the bitwise
\emph {exclusive or} of $v$ and $w$.

\gbc {subto} ($v, w$) replaces \mfc{picture} $v$ by the bitwise
\emph {subtraction} of $w$ from $v$.

$v$ \gbc {picsub} $w$ returns the \mfc{picture} formed by the
\emph {bitwise subtraction} of $w$ from $v$.
\emph {Note:}  $0-1=0$ here, as in Boolean algebra.


\subhead{Contour to Bitmap --- Clipping and Filling}

interior, interiors.
clipto, clipsto, clip.
picfill, picunfill, picneg.

\gbc {interior $c$} returns the \mfc{picture} comprising the
\emph {filled} interior of the closed curve (aka \emph {contour}) $c$,
where $c$ is described in \emph {graph} coordinates.
\emph {Note:}  \gbc {interior} is adapted from \MFbook{}'s
\mfc {safefill} macro.

\gbc {interiors $cc$} returns the \mfc{picture} comprising the
\emph {filled} interiors of the \emph {contours}) in the \mfc{path}
array $cc$, which are described in \emph {graph} coordinates.

The remaining bitmap operations are derived from the preceding ones.
The \emph {contours} are described in \emph {graph} coordinates.

\gbc {clipto $(v)$ $c$} clips \mfc{picture} $v$ to the interior of
\emph {contour} $c$.

\gbc {clipsto $(v)$ $cc$} clips \mfc{picture} $v$ to the interiors of
the \emph {contours} in the \mfc{path} array $cc$.

\gbc {clip $(v)$ $c$} returns the \mfc{picture} formed by
\emph {clipping} \mfc{picture} $v$ to the interior of \mfc{contour}
$c$.

\gbc {picfill $(v)$ $c$} changes \mfc{picture} $v$ by \emph {filling}
the interior of \emph {contour} $c$.

\gbc {picunfill $(v)$ $c$} changes \mfc{picture} $v$ by
\emph {unfilling} (making all pixels white in) the interior of
\emph {contour} $c$.

\gbc {picneg $(v)$ $c$} returns the \mfc{picture} of the reverse video
of \mfc{picture} $v$ as constrained within the interior of
\emph {contour} $c$.
\emph {Note:}  An unrestricted reverse video is not possible because
that would require replacing all white pixels, out to infinity,
by black pixels.


\subhead{Rendering Paths --- Drawing and Filling}

shpath.
minpenwd;
picpath;
picdraw.
safedraw, safefill, safeunfill;
ourdraw, ourfill, ourunfill;
drawn, filled, unfilled.

All \mfc{path}s in this section are in \emph {graph} coordinates.

\gbc {shpath $(f, q, v)$} \emph {draws} \mfc{path} $f$ in
\mfc{picture} $v$ using \mfc{pen} $q$.
(The `sh' in its name refers to the initials of `shade' and `hatch',
where \gbc {shpath} is used.)

\gbc {minpenwd} is an \mfc{internal} variable storing the smallest
allowed diameter for a \mfc{pen} that's to be used in \gbc {picdraw}
(see below).
\gbc {minpenwd} is initially \mfc {0.01{}p{}t}.

The following series of commands take a \mfc{path} argument that is
given in \emph {pixel} coordinates.

\gbc {picpath $d$} returns a \mfc{picture} containing a (robust)
\emph {drawing} of \mfc{path} $d$.

\gbc {picdraw $(v)$ $d$} \emph {draws} a \mfc{path} $d$ in
\mfc{picture} $v$.  It is designed to be more robust than
plain \MF{}'s \mfc {draw} macro.

\gbc {safedraw $d$} \emph {draws} \mfc{path} $d$ in the \mfc{picture}
\gbc {active\_plane}.

\gbc {safefill $c$} \emph {fills} the interior of \emph {contour} $c$
in \gbc {active\_plane}.  
\emph {Note:}  This is different from the \mfc {safefill} in
\MFbook{}.

\gbc {safeunfill $c$} \emph {unfills} the interior of \emph {contour}
$c$ in \gbc {active\_plane}.

The next group of commands take a \mfc{path} argument that is given in
\emph {graph} coordinates.

\gbc {ourdraw $d$} \emph {draws} the \mfc{path} $d$ in
\gbc {active\_plain}.

\gbc {ourfill $c$} \emph {fills} the interior of the
\emph {contour} $c$ in \gbc {active\_plane}.  

\gbc {ourunfill $c$} \emph {unfills} the interior of the
\emph {contour} $c$ in \gbc {active\_plane}.

\gbc {drawn $f$} \emph {draws} the \mfc{path} $f$ (in
\gbc {active\_plane}), and returns $f$.

\gbc {filled $c$} \emph {fills} the \emph {contour} $c$, and returns
$c$.

\gbc {unfilled $c$} \emph {unfills} the \emph {contour} $c$, and
returns $c$.


\head{Note}

In subsequent sections of this document, \emph {drawing} and
\emph {filling} write to \gbc {active\_plane}.


\head{Shading and Hatching}

setdotpath, setdot;
onedot, picdot, ourdot.
showbox, tightbbox, tbbox, bbox;
shade;
thatchf, thatch,
hhatch, vhatch, lhatch, rhatch, xhatch.

\emph {Note:}  Shading and hatching macros \emph {fill} closed
\mfc{path}s, but \emph {draw} open \mfc{path}s.

\gbc {setdotpath (shape, factor)} declares the \mfc{path}
\gbc {dotpath} unless it's already defined as a \mfc{path}.
In either case, it sets the value of \gbc {dotpath} to the path
\gbc {shape} scaled by the ceiling of the given \gbc {factor}.

\file {grafbase.mf} calls \gbc {setdotpath} to initialise
\gbc {dotpath} to a circle of diameter \mfc {0.5{}p{}t}.

\gbc {setdot ($f$)} sets the \mfc {picture} \gbc {onedot} to be the
\gbc {interior} of the \mfc {path} $f$ if $f$ is a closed \mfc {path},
otherwise it sets \gbc {onedot} to the \gbc {picpath} drawing of $f$.

\file {grafbase.mf} calls \gbc {setdot} to set \gbc {onedot} to be the
\mfc {picture} of \gbc {dotpath}.

\gbc {picdot ($v$, $w$, $p$)} superimposes the \mfc {picture} $w$ at
the \emph {pixel} position given by \mfc {pair} $p$ in the picture $v$.

\gbc {ourdot ($p$)} draws \gbc {onedot} at \emph {graph} position $p$
in \gbc {active\_plane}.

For debugging purposes, \file {grafbase.mf} defines a \mfc{boolean}
variable \gbc {showbox} which determines whether bounding boxes are
shown.  Normally, \gbc {showbox} is set to \mfc {false}.

\gbc {tightbbox ($g$, ll, ur)} sets the \mfc{pair} variables \gbc {ll}
and \gbc {ur} to the lower left and upper right corners, respectively,
of the \emph{tight} bounding box of the \mfc{path} $g$.  All three
arguments are described in \emph {pixel} coordinates.

\gbc {tbbox ($g$, ll, ur)} sets the \mfc{pair} variables \gbc {ll}
and \gbc {ur} to the lower left and upper right corners, respectively,
of the \emph{tight} bounding box containing the array $g[]$ of
\mfc{path}s.
All three arguments are described in \emph {pixel} coordinates.

\gbc {bbox ($g$, ll, ur)} sets the \mfc{pair} variables \gbc {ll} and
\gbc {ur} to the lower left and upper right corners, respectively,
of the \emph {loose} bounding box defined by the control points of the
\mfc{path} $g$.

\gbc {shade (sp) $f$} shades the interior of \gbc {path} $f$
(described in \emph {graph} coordinates) using dots
of a shape and size detrmined by the \gbc {setdot} macro,
spaced \gbc {sp} \emph {pixel} units apart.
Successive rows are offset by half of \gbc {sp}.
The dots are positioned on a grid with its origin at the \mfc{picture}
origin, $(0,0)$ in \emph {pixel} coordinates, in \gbc {active\_plane}.
\gbc {shade (sp) $f$} returns $f$.

\gbc {thatchf ($v_c$, CT, sp, xa, xb, ya, yb)} hatches the
interior of the upright box defined by the X and Y boundaries
\gbc {xa, xb, ya, yb},
using lines that are horizontal
and spaced \gbc {sp} units apart,
where all five dimensions are measured
in the coordinate system determined by the affine transform \gbc {CT}.
The hatched drawing is added to the \mfc {picture} $v_c$.
The line thickness is determined by \gbc {hatchpen}.

\gbc {thatch (sp, $\theta$)  $f$} hatches the interior of \mfc{path}
$f$ (described in \emph {graph} coordinates)
with lines at angle $\theta$,
spaced sp apart in \emph {pixel} coordinates,
and adds the drawing to \gbc {active\_plane}.

\gbc {hhatch (sp) $f$} (horizontal hatching),
\gbc {vhatch (sp) $f$} (vertical hatching),
\gbc {lhatch (sp) $f$} (left hatching),
and
\gbc {rhatch (sp) $f$} (right hatching)
are special cases of \gbc {thatch} where the angle $\theta$ is $0$,
$90$, $-45$ and $45$ degrees, respectively.

\gbc {xhatch (sp) $f$} is a cross-hatch that combines left and right
hatching.

\head{Tiles}

tile, endtile;
is\_tile;
tess.

\gbc {tile (atile, unit, width, height, clipon)} $\ldots$
\gbc {endtile}
provides an environment in which the tile \gbc {atile} can be defined.
Within this environment, \gbc {active\_plane} means the tile, and the
unit of length is \gbc {unit}.
The nominal boundary of the tile is specified by the given
\gbc {width} and \gbc {height},
with the other two sides being at $X=0$ and $Y=0$.
The tile is clipped to the boundary if the
\mfc {boolean} expression \gbc {clip} is true.

\gbc {is\_tile (atile)} returns \mfc {true} if \gbc {atile} is of the
correct data type to be a tile, otherwise it returns \mfc {false}.

\gbc {tess (atile) $c$} tiles (tesselates) the interior of closed
\mfc{path} $c$ with an array of copies of the tile \gbc {atile},
then returns $c$.
The \mfc{path} $c$ is described in \emph {graph} coordinates.


\head{Dots and Dashes}

dashed,
dotted.

\gbc {dashed $(d, s)$ $f$} \emph {draws} a series of dashes along
\mfc{path} $f$, with dash length $d$ and dash space $s$,
and returns $f$.
Here $d$ and $s$ are in \emph {pixel} coordinates,
and $f$ is in \emph {graph} coordinates.

\gbc {dotted $(d, s)$ $f$} \emph {draws} a series of dots along
\mfc{path} $f$, with dot size $d$ and dot space $s$,
and returns $f$.
Here $d$ and $s$ are in \emph {pixel} coordinates,
and $f$ is in \emph {graph} coordinates.


\head{Points}

bpoint,
pointd.

\gbc {bpoint ($w$, $a$)} returns a \mfc{path} that represents a point
with diameter $w$ in \emph{pixel} coordinates and location $a$ in
\emph{pixel} coordinates.

\gbc {pointd $(d, b, t)$} \emph {draws} a point at each of the
\emph {graph} coordinate \mfc{pair}s given by the text list $t$.
Each disc has diameter $d$ in \emph {sharp} coordinates.
If the \mfc{boolean} value $b$ is \mfc{true}, then the disc is black,
otherwise it is white with a black boundary.


\head{Arrows}

hdwdr, hdten, hfilled.
headshape, head, headpath.
arrowdraw.

\gbc {hdwdr} is an internal variable giving the ratio of the width
of the arrowhead divided by its length.

\gbc {hdten} is an internal variable giving the tension on the curved
sides, or \emph {barbs}, of the arrowhead.  This controls the
curvature of the \emph {barbs}.

\gbc {hfilled} is a \mfc{boolean} variable.  If it's \mfc{true}, then
arrowheads will be \emph {filled} black, otherwise they'll be
\emph {filled} white but \emph {outlined} (that is, \emph {drawn})
in black.

\gbc {headshape $(w, t, f)$} sets the arrowhead's shape by setting
\gbc {hdwdr} to $w$, \gbc {hdten} to $t$, and \gbc {hfilled} to $f$.

\file {grafbase.mf} initialises \gbc {hdwdr} to 1, \gbc {hdten} to 1,
and \gbc {hfilled} to false.

\gbc {headshape (wr, tens, fil)} sets the global parameters
\gbc {hdwdr, hdten, hfilled} to \gbc {wr, tens, fil} respectively.
The initial arrowhead shape is set by \gbc {headshape (1, 1, false)}.

\gbc {head (front, back, width, tens, filled)} \emph {draws} the
arrowhead.
The argument \gbc {front} is a \mfc{pair} giving the position (in
\emph {graph} coordinates) of the tip of the arrowhead,
\gbc {back} is a \mfc{pair} giving the position of the base of the
arrowhead,
\gbc {width} is a \mfc{numeric} value giving the ratio of the width to
the length of the arrowhead,
\gbc {tens} is a \mfc{numeric} value giving the tension of the
\emph {barbs},
and \gbc {filled} is a \mfc{boolean} value which if \mfc{true} means
that the arrowhead is \emph {filled} black but if \mfc{false} causes
the arrowhead to be \emph {filled} white and \emph {outlined} in
black.

\gbc {headpath $(l, \theta, b)$ $f$} \emph {draws} an arrowhead on the
path $f$.
The arrowhead has length equal to $l$ \emph {graph} units,
it is rotated by $\theta$ degrees,
and is set back from the last point of $f$ by $b$ \emph {graph} units.
The \gbc {width}, \gbc {tens} and \gbc {filled} values of the
arrowhead are set by the global variables \gbc {hdwdr}, \gbc {hdten},
and \gbc {hfilled}.

\gbc {arrowdraw $(t, h, l)$} \emph {draws} a straight line arrow with
its tail at $t$ and tip at $h$, both in \emph {graph} coordinates,
and arrowhead length equal to $l$ \emph {sharp} units.


\head{Axes, Axis Tic Marks, and Grid}

axes;
xmarks, ymarks;
grid.

\gbc {axes $(l)$} \emph {draws} the X axis from \emph {graph}
coordinate \gbc {xneg} to \gbc {xpos},
and the Y axis from \emph {graph} coordinate \gbc {yneg} to
\gbc {ypos},
both with arrowheads of length $l$ \emph {sharp} units.

\gbc {xmarks $(l, t)$} \emph {draws} tic marks along the X axis,
at the X values (in \emph {graph} coordinates) given by the text list
$t$.
Each tic extends $l/2$ \emph {sharp} units above and below the X axis.

\gbc {ymarks $(l, t)$} \emph {draws} tic marks along the Y axis,
at the Y values (in \emph {graph} coordinates) given by the text list
$t$.
Each tic extends $l/2$ \emph {sharp} units left and right of the 
axis.

\gbc {grid $(x_s, y_s)$} draws dots at each grid coordinate at
X spacings $x_s$ and Y spacings $y_s$, in \emph {graph} coordinates.


\head{Note}

Unless or until otherwise indicated, subsequent graphics commands are
coordinate-independent.


\head{Upright Rectangles}

rect.

\gbc {rect (ll, ur)} returns the rectangular \mfc{path} that has
the \mfc{pair} \gbc {ll} as its lower left corner, and the \mfc{pair}
\gbc {ur} as it supper right corner.


\head{Path Construction}

mkpath.

\gbc {mkpath $(s, c, p)$} returns the smooth \mfc{path}
\gbc {mksmooth $(c, p)$} if the \mfc{boolean} value $s$ is \mfc{true},
otherwise it returns the polyline \gbc {mkpoly $(c, p)$}.


\head{Polylines, including Polygons}

mkpoly, polyline.

\gbc {mkpoly $(c, p)$} returns a polyline \mfc{path} with vertices
given by the array of \mfc{pair}s $p$.  The \mfc{numeric} variable $p$
contains the number of elements in $p[]$, numbered from $1$ to $p$.
If the \mfc{boolean} value $c$ is \mfc{true},
then the \mfc{path} is a closed polygon,
otherwise it is an open polyline.

\gbc {polyline $(c, t)$} returns the polyline \mfc {path} that has the
vertices specified in the list $t$.
If the \mfc{boolean} value $c$ is \mfc{true},
then the \mfc{path} is a closed polygon,
otherwise it is an open polyline.


\head{Smooth Curves}

mksmooth, curve.
openqbs, closedqbs.
mkopencbs, opencbs, mkclosedcbs, closedcbs.

\gbc {mksmooth $(c, p)$} returns a smooth curve passing through
the points given by the array of \mfc{pair}s $p$.  If the
\mfc{boolean} value $c$ is \mfc{true}, then the curve is smoothly
closed, otherwise it is open.

\gbc {curve $(c, t)$} returns a smooth, curved \mfc{path} that passes
through the \mfc{pair}s given in the text list $t$.
If $c$ is \mfc{true}, then the \mfc{path} is closed, otherwise it is
open.

\gbc {openqbs $(t)$} returns an open quadratic B-spline \mfc{path}
governed by the \mfc{pair} list in the text $t$.

\gbc {closedqbs $(t)$} returns a closed quadratic B-spline \mfc{path}
governed by the \mfc{pair} list in the text $t$.

\gbc {mkopencbs $(b)$} returns an open cubic B-spline \mfc{path}
governed by the \mfc{pair} array $b$.

\gbc {opencbs $(t)$} returns an open cubic B-spline \mfc{path}
governed by the \mfc{pair} list in the text $t$.

\gbc {mkclosedcbs $(b)$} returns a closed cubic B-spline \mfc{path}
governed by the \mfc{pair} array $b$.

\gbc {closedcbs $(t)$} returns a closed cubic B-spline \mfc{path}
governed by the \mfc{pair} list in the text $t$.


\head{Path Closure}

lclosed;
sclosed;
bclosed;
ztob, cbclosed.

If $f$ is a closed \mfc{path}, then \gbc {lclosed $f$} returns $f$;
otherwise it returns the closure of $f$ by a straight line.

\gbc {sclosed $f$} returns the result of closing \mfc{path} $f$
in the manner of \gbc {mksmooth}.

\gbc {bclosed $f$} is like \gbc {lclosed $f$}, except that it closes
using a \MF{} B\'ezier curve.
\emph {Note:}  The curve returned by \gbc {bclosed $f$} may differ
in shape from $f$, due to the \mfc{tension} exerted by the B\'ezier.

\gbc {ztob $(z, b)$} converts the four B\'ezier segment key points in
the \mfc{pair} array $z$ into four cubic B-spline control points
in the \mfc{pair} array $b$.

\gbc {cbclosed $f$} returns the \mfc{path} formed by closing the
given \mfc{path} $f$ by a cubic B-spline.  (This macro uses
\gbc {ztob}.)


\head{Circles and Ellipses}

ellipse, circle.

\gbc {ellipse $(c, r_x, r_y, \theta)$} returns an ellipse with
center at the \emph {graph} coordinate \mfc{pair} $c$,
`X' radius $r_x$,
`Y' radius $r_y$,
and with its `X' radius angled at $\theta$ degrees from
the \emph {graph} coordinate system's X axis.

\gbc {circle $(c, r)$} returns a circle with center at the
\emph {graph} coordinate \mfc{pair} $c$ and radius $r$.


\head{Circular Arcs}

arc;
arccenter;
arcpps, arcplr, arccps, arcppp.

\gbc {arc $(c, p_1, \theta)$} returns a \mfc{path} describing
a circular arc for a circle with center at the point $c$,
starting point at $p_1$, and sweep angle $\theta$ in degrees.

\gbc {arccenter $(p_1, p_2, \theta)$} returns the \mfc{pair} defining
the center of the circle that has the points $p_1$ and $p_2$
on its circumference separated by an angle of $\theta$ degrees.

\gbc {arcpps $(p_1, p_2, \theta)$} returns a \mfc{path} describing
the arc that has starting point $p_1$, finishing point $p_2$,
and sweep angle $\theta$ degrees.

\gbc {arcplr $(c, \theta_1, \theta_2, r)$} returns a \mfc{path}
describing the arc that has center point $c$, starting direction
$\theta_1$, finishing direction $\theta_2$, and radius $r$.

\gbc {arccps $(c, p_1, \theta)$} returns a \mfc{path} describing
the arc that has center point $c$, starting point $p_1$,
and sweep angle $\theta$ degrees.

\gbc {arcppp $(p_1, p_2, p_3)$} returns a \mfc{path} describing
the arc that has the given starting point $p_1$, finishing
point $p_3$, and that passes through the point $p_2$.


\head{Polar Coordinates}

polar.

\gbc {polar ($p$)} returns the rectangular (cartesian) coordinate
\mfc{pair} $(x,y)$ equivalent to the polar coordinate \mfc{pair}
$p = (r,\theta)$.


\head{Turtle}

turtle.

\gbc {turtle ($p_0, v_1, v_2, \ldots$)}
returns a \mfc{path} that starts at the point $p_0$, then
moves by $v_1$, then by $v_2$, and so on.


\head{Sectors}

sector.

\gbc {sector $(c, r, \theta_1, \theta_2)$}
returns a \mfc{path}
describing a circular sector boundary
with center point $c$,
radius $r$,
starting angle $\theta_1$,
and finishing angle $\theta_2$.


\head{Utility Functions}

id.

\gbc {id ($x$)} returns $x$.  This is the identity function for the
next topic.


\head{Functions and paths}

mkfcn, tfcn, parafcn;
xfcn, function;
rfcn, plrfcn.

\emph {Note:}  Functions may be user-defined.

\gbc {mkfcn $(s, a, b, d, pf)$} returns a \mfc{path} passing through
the X and Y coordinate \mfc{pair}s traced out by $pf(v)$
for each value $v$ from $a$ to $b$ stepping by $d$.
Here $pf$ may be any \MF{} \mfc{pair} function of one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.

\gbc {tfcn} is a synonym for \gbc {mkfcn}.

\gbc {parafcn $(s, a, b, d, pf_t)$} returns a \mfc{path} passing through
the X and Y coordinate \mfc{pair}s traced out by the text $pf_t$,
which is a \emph {literal expression} in $t$,
for each value $t$ from $a$ to $b$ stepping by $d$.
Here $pf$ may be any \MF{} \mfc{pair} function of one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.

\gbc {xfcn $(s, a, b, d, f)$} returns a \mfc{path}
passing through the X and Y coordinate \mfc{pair}s $(x, f(x))$
for each value $x$ from $a$ to $b$ stepping by $d$.
Here $f$ may be any \MF{} \mfc{numeric} function of one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.

\gbc {function $(s, a, b, d, f_x)$} returns a \mfc{path}
passing through the X and Y coordinate \mfc{pair}s $(x, f_x)$,
where the text $f_x$ is a \emph {literal expression} in $x$,
for each value $x$ from $a$ to $b$ stepping by $d$.
Here $f$ may be any \MF{} \mfc{numeric} function of one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.

\gbc {rfcn $(s, a, b, d, f)$} returns a \mfc{path} passing through
the X and Y coordinate \mfc{pair}s
\centerline {$f(t) * (\hbox{\mfc {dir\ }} t)$}
\noindent
for each value $t$ from $a$ to $b$ stepping by $d$.
(\emph {Note:}  \mfc {dir $t$ $=$ (cosd ($t$), sind ($t$))}.)
Here $f$ may be any \MF{} \mfc{numeric} function in one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.

\gbc {plrfcn $(s, a, b, d, f_t)$} returns a \mfc{path} passing through
the X and Y coordinate \mfc{pair}s
\centerline {$f_t * (\hbox{\mfc {dir\ }} t)$}
\noindent
where the text $f_t$ is a \emph {literal expression} in $t$,
for each value $t$ from $a$ to $b$ stepping by $d$.
(\emph {Note:}  \mfc {dir $t$ $=$ (cosd ($t$), sind ($t$))}.)
Here $f$ may be any \MF{} \mfc{numeric} function in one \mfc {numeric}
argument.
If the \mfc{boolean} $s$ is \mfc{true}, then the \mfc{path} is a
smooth curve, otherwise it is a polyline.


\head{Overlays}

\noindent
Global Parameters:  totalpicture, totalnull, currentnull. \brk
Macros:  clearit, keepit, addto\_currentpicture, mergeit, shipit,
showit\_, show\_.

Essentially these redefine the middle-level plain \MF{} macros for
the formation of the current font character, so that typing
\gbc {keepit;} will preserve work-to-date from being destroyed
by subsequent erasures on subsequent parts of the same character.

The parameters are for bookkeeping and should not be touched
by users.  Those macros intended for public use are
\gbc {clearit, keepit, mergeit, and shipit}.  Of these, only
\gbc {keepit} is new; the others behave in a similar way to their
descriptions in \MFbook{}.

For a more detailed description of these overlay macros
(devised by Bruce Leban), see \MFbook{} page 295.

\end

%%%
%%%  end  grafdoc.tex
%%%