%%% grafdoc.tex
%%% part of mfpic 0.4.0 2000/08/31
%%%

\input header
%\magnification1200
\paperheight 11 truein
\paperwidth 8.5 truein

\hsize 5.4166 in
\vsize 7.4166 in

\voffset=\paperheight
\advance \voffset -\vsize
\divide \voffset by 2
\advance \voffset -1 truein

\hoffset\paperwidth
\advance \hoffset -\hsize
\divide \hoffset by 2
\advance \hoffset -1 truein

%{\tt\global\hyphenchar\font=-1}

\def\makefootline{\baselineskip30pt \lineskiplimit0pt\line{\the\footline}}
\def\_{{\tt\char`\_}} % For \tt only
% metacode macro
\let\texmacro=\macro

\centerline{\bf MFpic's \MF{} and \MP{} macros}
\centerline{\file{grafbase.mf} and \file{grafbase.mp}}
\centerline{Version:  \mfpicversion, Date:  \mfpicdate}
\centerline{Document Author:  Geoffrey Tobin (\mail{G.Tobin@latrobe.edu.au})}
\centerline{Updates by:  Daniel H. Luecking (\mail{luecking@comp.uark.edu})}


\head{Background}

\vskip\myskip
\MF{} or \MP{} should be moderately familiar to anyone who is serious
about understanding \file{grafbase.mf} or \file{grafbase.mp}.

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{}.

For \MP\ specific information (as well as some basic \MF\ information),
the \MP\ documentation by John Hobby is invaluable. It is contained in
the file \file{mpman.ps}, available with most distributions of \MP.

\head{Assumed Variables}

\vskip\myskip
The file \file{grafbase.mf} assumes that the \MF{} variables \gbc {w\_},
\gbc {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 \prog{grafbase} macro \mfc{beginmfpic}. By
contrast, the four graph extents variables, \gbc {xneg}, \gbc {xpos},
\gbc {yneg} and \gbc {ypos} must be set externally. \mfc{beginmfpic}
also sets the numeric variables \mfc{w} and \mfc{h} to \gbc{w\_} and
\gbc{h\_}, respectively. The user may use \mfc{w} and \mfc{h} (indeed,
is encouraged to) but internally \prog{grafbase} uses the underscored
variants to guard against a user accidentally redefining the simpler
ones (as the author of once did from \prog{mfpic} using
\macro{mfobj}[h]).

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


\head{Preliminaries}

\vskip\myskip
metapost.

\prog{grafbase}
uses the \mfc{boolean} variables \gbc{METAPOST} and \gbc{METAFONT} to
record whether it thinks it's being used with \MP{} or \MF{}.  Since
\MF{} has no colors, it seems reasonable that the presence of \mfc{blue}
is a reliable sign of \MP{}, so \prog{grafbase} tests for \mfc{blue} is
known.

At present, no \prog{grafbase} code involves these booleans, relying on
the different files to contain program specific code: if \mfc{input
grafbase} occurs in a file, then \MF\ will input \file{grafbase.mf} and
\MP\ will take \file{grafbase.mp}. Moreover, if \MP\ cannot find
\file{grafbase.mp} and tries to input the other, the results will be
disastrous. Perhaps in the future the two files can be merged, with
differences controlled by these booleans.

The files \file{grafbase.mf/p} need the \file{plain.mf/p} macros.
Usually, these will be available automatically, but if by any ill chance
they are not, then \prog{grafbase} will attempt to load the appropriate
file.

In \file{grafbase.mf}, 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.

Such font related items are not available (or needed) in \MP, so
\file{grafbase.mp} ignores modes, font identifiers and coding schemes.


\head{Common Global Variables}

\vskip\myskip
{\it
debug,
grafbase;
mftitle (macro);
deg, radian, pi;
unitlen, xscale, yscale,
xneg, xpos, yneg, ypos;
penwd, drawpen,
hatchwd, hatchpen;
shadewd;
store (macro);
ClipOn,\brk ClipPath.
Triangle, Square, Diamond, Circle, Star, Plus, Cross,
SolidTriangle,\brk SolidSquare, SolidDiamond, SolidCircle.
curvetension, functiontension.}

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

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

The \gbc {mftitle} macro is frequently used by \prog{mfpic}, but not in
\prog{grafbase} 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. Of course \gbc{pi} is set to \gbc{3.1415926} and \gbc{radian}
is set with \gbc{pi*radian = 180 deg;}.

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 (or the bounding box in
the EPS files that \MP\ 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 or the
bounding box of the EPS file.

The initial values of these seven dimensioning variables are: \gbc
{unitlen := 1pt\#}, 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{} or \MP\ 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 {device} coordinates, is
determined by the \mfc{internal} variable \gbc {penwd}, which
\prog{grafbase} initialises to \mfc {0.5pt}. (See the Coordinate
Conversion section below for a description of `device coordinates'.)

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

The \gbc {store ($f_s$) $f$ } macro is for the purpose of storing a
\mfc{path} expression $f$, which may be quite complex, into a \mfc{path}
variable $f_s$. 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}).

\gbc{Triangle}, $\ldots$, \gbc{SolidCircle} are paths in the obvious
shape. They have approximately the diameter 1 in device coordinates so
they would normally be drawn \mfc{scaled} to appropriate dimensions.
Despite the names, only the last four (\gbc{Solid...}) are closed paths.
(For example, \gbc{SolidTriangle} is just \gbc{Triangle \& cycle}.) They
are used by \gbc{doplot} and \gbc{plotsymbol}, but are available for
other uses.

The numeric \gbc{curvetension} is the tension used between nodes of the
path created by \gbc{mksmooth}. It is initialized to 1 (\MF's default).

The numeric \gbc{functiontension} is a tension-like quantity used by
\gbc{mkcontrolledfcn}.

\subhead{\MP\ Color Variables}

\vskip\myskip
(Colors are only valid in the \MP\ version of \prog{grafbase}.)

{\it
drawcolor, fillcolor, hatchcolor, headcolor;
cyan, magenta, yellow;
\file{dvipsnam.mp}. (file)}

In \MP, \mfc{red}, \mfc{green}, \mfc{blue}, \mfc{white}, and \mfc{black}
are predefined colors. \file{grafbase.mp} adds definitions for the
constant colors \gbc{cyan}, \gbc{magenta} and \gbc{yellow}.

In addition \file{grafbase.mp} maintains the color variables
\gbc{drawcolor}, \gbc{fillcolor}, \gbc{hatchcolor} and \gbc{headcolor}.
\gbc{drawcolor} is used by \gbc{shpath} and \gbc{safedraw}, the basic
curve drawing routines called by almost every function that draws a
curve. Similarly, \gbc{fillcolor} is used for filling, \gbc{hatchcolor}
for hatching, and \gbc{headcolor} for drawing arrowheads. These were
chosen because these are the basic drawing operations of \prog{mfpic}
macros: drawing curves, filling interiors of curves, hatching interiors,
and adding arrowheads to curves. All four are initialized to
\mfc{black}.

Finally, the auxilliary file \file{dvipsnam.mp} contains definitions of
all the color names defined in \LaTeX's \file{dvipsnam.def}. It is
normally input by files created by \prog{mfpic} when the \opt{metapost}
option is selected, so all these colors are available to \prog{mfpic}
users.

\iffalse

\head{Frank Michielsen's macros}

% Frank's macros have been superseded.
% pathlength was only called by dashlist and
% dotlist. Much of its calculations were repeated anew in
% timelist, also only called by dashlist and dotlist.
% Currently a single macro, gendashed, is used for both dashing and
% dotting of curves. It does the pathlength/timelist calculations
% itself, removing redundant code. This more than doubled the speed
% of drawing a dashed line, allowing a more elaborate macro that
% can repeat arbitrary dash/dot patterns.

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

\fi

\head{Utility Macros}

\vskip\myskip
{\it
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 \prog{grafbase}, 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. Lists are
generally used in \mfc{for} preambles, so for each item $i$ in $t$,
$m(i)$ should normally be a single object. If $m(i)$ expands to some
arbitrary \MF{} code, some symbols can cause problems (e.g., `\mfc{:}'
can terminate a \mfc{for} preamble prematurely).

\gbc {maparr (proc) ($p$) } applies \gbc {proc}, which should be a \emph
{procedure} (a sequence of statements that does not return any value)
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}

\vskip\myskip
{\it
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}.  Device independent lengths are specified in sharp units:
for example, \gbc{unitlen}.

The third describes the \emph {device}  coordinates. In \MF\ these are
\emph{pixel} coordinates, refering to units 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 \mfc{beginmfpic}, and in its
manipulations of \MF{} \mfc{picture} variables.

Below, we will use the term `device coordinates' somewhat loosely,
meaning units such as \mfc{pt} and \mfc{cm} (not \mfc{pt\#} or
\mfc{cm\#}). These have already been set equal to some number of
\emph{horizontal} pixels by \mfc{mode\_setup}. The user \emph{could}
calculate a number of pixels and use that also. However, the user should
\emph{not} adjust for nonsquare pixels using \mfc{aspect\_ratio}. That
is already done by the \prog{grafbase} drawing commands.

The user can normally ignore the sharp coordinates, except for
\gbc{unitlen}. As for graph or device coordinates: when a
\prog{grafbase} function requires parameters in \emph{graph} coordinates
simply use pure numerics, and when \emph{device} coordinates are
required, use pure numeric multiples of \mfc{pt} or \mfc{cm} or (inside
a \gbc{beginmfpic} group) of \gbc{w} or \gbc{h}, which have already been
established as a certain number of pixels. Or use \gbc{zconv} and
\gbc{vconv} to convert from graph to device coordinates.

In \MP, device coordinates are the same as sharp coordinates. \PS\
devices should perform the conversion from absolute lengths to pixels
internally.

\iffalse
Ideally, the facility to clip a drawing made using \prog {grafbase}
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.
\fi

In \MF{} and \MP, 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). 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 in general the former depend on the absolute
position, whereas the latter act independently of it. Therefore we need
a separate set 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 {device} coordinates.

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

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

\gbc {zconv $(a)$ } returns the \emph {device} 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 {device} vector corresponding to
the \emph {graph} vector $a$.

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


\head{Initial Setup}

\vskip\myskip
{\it
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}}

\vskip\myskip
{\it fpicenv, 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.

The behavior of \file{grafbase.mp} with such old file has never been
examined, so no compatibility is claimed.

\head{Character Wrapper}

\vskip\myskip
{\it beginmfpic, endmfpic.}

In \file{grafbase.mf}, \gbc {beginmfpic (ch)} is mostly a convenient
abbreviation for the typical use of \mfc {beginchar} with
\file{grafbase.mf}. However, to shield internal commands from users who
might inadvertantly set variables \mfc{d}, \mfc{h} or \mfc{w}, it also
sets \mfc{d\_}, \mfc{h\_} or \mfc{w\_} to the same values for internal
use. (These values are in device units)

In \file{grafbase.mp}, \gbc{beginmfpic} is similar to \mfc{beginfig}.
The variables \mfc{d}, \mfc{h}, \mfc{w}, \mfc{d\_}, \mfc{h\_}, \mfc{w\_}
are set just as in the \MF\ version.

\gbc {endmfpic} functions like \mfc {endchar} or \mfc{endfig}, but is
meant to match \gbc {beginmfpic}. Moreover, when boolean \mfc{clipall}
is set, \mfc{endmfpic} clips the picture to be shipped out to the
nominal dimensions. The \MP\ version also responds to the \mfc{truebbox}
boolean: If this is \mfc{true}, the bounding box in the output \EPS{}
file will reflect the actual extent of the figure, if it is \mfc{false},
the bounding box will be forced to the nominal dimensions.


\head{Extra Trigonometric and Hyperbolic Functions}

\vskip\myskip
{\it
tand, cotd, secd, cscd, acos, asin, atan;
sin, cos, tan, cot, sec, csc, invcos, invsin, invtan;
exp, ln, cosh, sinh, tanh, acosh, asinh, atanh;
Arg, zexp, cis.}

\gbc {tand $(x)$}, \gbc {cotd $(x)$}, \gbc {secd $(x)$} and \gbc {cscd
$(x)$ } are the tangent, cotangent, secant and cosecant of $x$, where $x$
is in degrees;

\gbc {sin $(x)$}, \gbc {cos $(x)$}, \gbc {tan $(x)$}, \gbc {cot $(x)$},
\gbc {sec $(x)$}, and \gbc {csc $(x)$ } are the the various trig
functions, where $x$ is in radians. That is, \mfc{cos (x)} is the same
as \mfc{cosd (x*radian)}.

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

\gbc{invsin}, \gbc{invsin } and \gbc{ invtan } return angles in radians:
\gbc{ invsin (x) } is the same as \gbc{ (asin (x))/radian}.

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

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

\gbc {cosh $(x)$}, \gbc {sinh $(x)$ } and \gbc{ tanh $(x)$ } are the
hyperbolic cosine, the hyperbolic sine and the hyperbolic tangent of
$x$.

\gbc {acosh $(y)$}, \gbc {asinh $(y)$ } and \gbc{ atanh $(y)$ } are their
inverses.

For complex variables we have:
\gbc{ Arg $z$ } returns the angle in radians of the pair $z = (x,y)$.
\gbc{ zexp $z$ } returns the pair $e^x(\cos y, \sin y)$ where $z =
(x,y)$. This corresponding to complex exponentiation. Finally
\gbc { cis $\theta$ }
returns $(cos \theta, sin \theta)$.

\head{Coordinate Systems and Transformations}

\vskip\myskip
\subhead{Coordinate Nesting}

\vskip\myskip
{\it
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 \prog
{grafbase} 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}

\vskip\myskip
{\it apply\_t.
xslant, yslant, zslant, xyswap, boost.}

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

\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}

\vskip\myskip
{\it rotatedpath.}

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


\head{Bitmaps, Clipping and Rendering}

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

\vskip\myskip
{\it mono.
andto, picand;
orto, picor;
xorto, picxor;
subto, picsub.}

(None of these pixel oriented operations is available in \MP.)

\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.

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{Color operations}

\vskip\myskip
(None of these color operations is available in \MF.)

{\it rgb, RGB, cmyk, gray, named.}

\gbc{rgb $(r, g, b)$ } is basically a no-op. It takes three numeric
parameters $r$, $g$ and $b$, and after a little error checking, returns
the color $(r,g,b)$.

\gbc{RGB $(R,G,B)$ } essentially divides $(R,G,B)$ by 255 to return a
color triple.

\gbc{cmyk$(c,m,y,k)$ } returns the \MP\ color triple equivalent of a cmyk
color quadruple.

\gbc{gray $(g)$ } returns the color triple $(g,g,g)$, i.e., gray.
\gbc{gray(0)} is \mfc{black} and \gbc{gray(1)} is \mfc{white}.

All the above commands truncate the color components to the range
$[0,1]$.

\gbc{named $(n)$ } returns $n$ if $n$ is a known \MP\ color expression,
otherwise \mfc{black}. Normally $n$ would be a variable name.

Many of the \prog{grafbase} drawing commands are implemented in
\file{grafbase.mp} as in the following example: The command
\gbc{safedraw} expands to \gbc{colorsafedraw (drawcolor)}, where
\gbc{colorsafedraw} has a definition almost identical to that of the
command \gbc{safedraw} in \file{grafbase.mf}, except for the addition of
a color parameter, used with the drawing option \gbc{withcolor ...}$\,$.
Such differences account for the ability to set the drawing color with
\gbc{drawcolor}, the fill color with \gbc{fillcolor}, etc. These extra
\gbc{color...} commands will not be mentioned in the exposition of the
basic \prog{grafbase} commands late. Search the file \file{grafbase.mp}
for commands beginning with ``\mfc{color}'' to get the whole story.


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

\vskip\myskip
{\it
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 picture operations are derived from the preceding ones.
The \emph {contours} are described in \emph {device} 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$.  In
\MP, \mfc{clip} is a primative command, so this operation is named \gbc
{clipped}. Note: in \file {grafbase.mf}, a side effect of \gbc{clip} is
that \mfc{v} is operated on by \gbc{mono}.

\gbc {picfill $(v)$ $c$ } changes \mfc{picture} $v$ by \emph {filling}
the interior of \emph {contour} $c$. In \MP, the color used is
\gbc{fillcolor}.

\gbc {picunfill $(v)$ $c$ } changes \mfc{picture} $v$ by \emph
{unfilling} (making all pixels zero in) the interior of \emph {contour}
$c$.  In \MP, this simply fills with the color
\mfc{background}, which is set equal to \mfc{white} in \file{plain.mp}

\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. In \MP, this is a little different. What it
does is fill the contour $c$ with \gbc{fillcolor} and then draw $v$ on
top of that in white. What makes this different is that \PS\ makes a
distinction between something that is drawn in white and regions that
were white because nothing was drawn there. For example, if $v$ is
created by filling a large square and unfilling a smaller square inside
it, then the entire square is still filled, but part of it is filled
with \gbc{white}. If you \gbc{ picneg $(v)$ $c\,$}, you just get a large
white square inside $c$.


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

\vskip\myskip
{\it
shpath.
minpenwd;
picpath;
picdraw.
safedraw, safefill, safeunfill;
drawn, filled, unfilled.}

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

In \MP, several of these have variants that can specify a color.

\gbc {shpath $(v, q, f)$ } \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 {device} 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 {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$.  In \MP{} this means filling with white.


\head{Note}

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


\head{Shading and Hatching}

\vskip\myskip
{\it
setdot;
onedot, picdot.
showbox, 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 {setdot ($f, s$) } returns a \mfc {picture} consisting of the \gbc
{interior} of the \mfc {path} $f$ scaled $s$ if $f$ is a closed \mfc
{path}, otherwise it returns a drawing of $f$.

\prog {grafbase} sets \gbc {onedot} to \gbc{ setdot (dotpath, 0.5pt)},
\gbc{shadedot } to \gbc{ setdot (dotpath, shadewd)}, and \gbc{
thepolkadot }
to \gbc{ setdot (dotpath, polkadotwd)}.

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

For debugging purposes, \prog {grafbase} 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 {device} 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 {device} coordinates.

In \file{grafbase.mf},
\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$. This is faster than \gbc{tightbbox} and is used when all
one needs is an enclosing rectangle (for example, the hatching commands
hatch this loose rectangle and then clip to $g$).

\MP{} already has a \mfc{bbox} command in \file{plain.mp} which is
incompatible with the above command. Moreover, \gbc{tightbbox} simply
calls the \MP{} primatives \mfc{llcorner} and \mfc{urcorner}. If using
\file{grafbase.mp}, simply use \gbc{tightbbox} where one might use
\gbc{bbox} in \file{grafbase.mf}.

\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 first
drawn on a rectangle determined by \gbc{ll} and \gbc{ur} calculated from
\gbc{bbox ($f$, ll, ur)}. They are positioned on a pixel grid in this
rectangle, and then clipped to $f$. \gbc { shade (sp) $f$ } returns $f$.

In \MP, \gbc{shade} merely computes a level of gray from \gbc{sp} and
\gbc{shadewd} and then calls \gbc{colorsafefill} with that level of gray.

\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}.

In \MP, an additional color parameter comes between $v_c$ and \gbc{CT}.

\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 {device} 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. In \MP, these hatch in
\gbc{hatchcolor}.

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

\head{Tiles}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
DASHED (dashed), dotted;
doplot, gendashed;
dashpat.}

\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 {device} coordinates, and $f$ is in
\emph {graph} coordinates. In \MP, \mfc{dashed} is a primative, which is
why \gbc{DASHED} is used instead. In \MF, \gbc{dashed} is provided as an
alias for \gbc{DASHED}. \gbc{DASHED} does nothing but call \gbc{dashpat}
and then \gbc{gendashed}.

\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 {device} coordinates, and $f$ is in \emph
{graph} coordinates. \gbc{dotted} merely calls the more general
\gbc{doplot} macro.

\gbc{doplot (sym, sc, dgap) $f$ } plots the curve $f$ (in graph
coordinates) using symbol \gbc{sym}, scaled by \gbc{sc}, spaced apart by
\gbc{dgap}. Both \gbc{sc} and \gbc{dgap} should be in device
coordinates. \gbc{doplot} initializes \gbc{dotpath} to \gbc{sym}, sets
\gbc{dotscale} to \gbc{sc}, calls \gbc{ dashpat (dots) (0, dgap) } and then
\gbc{ gendashed (dots) $f\,$}. \gbc{sym} should be a path, and it should be
closed if a solid (i.e., filled) shape is desired.

\gbc{dashpat (pat) ($t$) } takes a text list of dimensions $t$ and a
suffix \gbc{pat} and creates three numeric arrays: \gbc{pat.start[]},
\gbc{pat.rep[]}, and \gbc{pat.finish[]}. The main one is \gbc{pat.rep}
which is used by \gbc{gendashed} to draw the repeating pattern of dashes
along a curve. It is just the text $t$ copied to a numeric array. The
other two are an initial and final part of this pattern. These are used
by \gbc {gendashed} to draw the start and end of a curve.

\gbc{gendashed (pat) $f$ } uses the arrays \gbc {pat.start[]}, \gbc
{pat.rep[]}, and \gbc {pat.finish[]}. The odd positions of each array give
the length of a dash (in device coordinates), while the even positions
give the length of a space (there must be an even number of positions
except in \gbc{pat.finish}, which ends with a dash). A dash of length 0
is drawn as a dot. The size and shape of the dot are \gbc{dotscale} and
\gbc{dotpath}, which may be reset for special effects. If \gbc{pat} is
created by \gbc {dashpat}, the curve will start with half of the first
dash in \gbc{pat.rep} and end with half of the same dash, with a whole
number of repeated patterns in between. For special effects at the start
and end, \gbc{pat.start} and \gbc{pat.finish} can be defined
independently.


\head{Points}

\vskip\myskip
{\it
bpoint,
pointd,
plotsymbol.}

\gbc {bpoint ($w$, $a$) } returns a \mfc{path} that represents a point
with diameter $w$ in \emph{device} coordinates and location $a$ in
\emph{devive} 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 {device} coordinates. If the \mfc{boolean} value
$b$ is \mfc{true}, then the disc is filled, otherwise it is white with a
boundary. In \MP, when the disc is filled, \gbc{fillcolor} is used, and
when not filled, the boundary is drawn in \gbc{drawcolor}.

\gbc{plotsymbol $(s, d, t)$ } draws the symbol $s$ with ``diameter'' $d$
in \emph{device} units at the points given by \emph{graph} coordinate
pairs in the text list $t$. As the symbols are not all round, $d$ is a
sort of average diameter. A ``symbol'' is either one of the predefined
paths \gbc{Triangle}, etc., listed in Common Global Variables, or a user
defined path which should have roughly diameter 1 and be roughly
centered at the origin. If the symbol is a closed path, the symbol is
filled (in \gbc{fillcolor} in \MP), otherwise it is simply drawn (in
\gbc{drawcolor}).

\head{Arrows}

\vskip\myskip
{\it
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} (in \gbc{headcolor}), otherwise
they'll be simply drawn (in \gbc{headcolor}). If unfilled, and arrowhead
is simply two barbs; the ends of the barbs are not connected.

\prog {grafbase} 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} but if
\mfc{false} causes the arrowhead to be simply drawn.

\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{headpath returns the
path $f$}.

\gbc {arrowdraw $(l, f)$ } \emph{draws} $f$ and then adds the arrowhead
(essentially the same as \gbc{headpath $(l, 0, 0$pt$)$ $f$}, but without
returning $f$).


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

\vskip\myskip
{\it
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
{device} 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 {device} 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 {device} 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}

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


\head{Upright Rectangles}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
mkpath.}

\gbc {mkpath $(s, c, p)$ } returns the smooth 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}

\vskip\myskip
{\it
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$\mfc{[]}, 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}

\vskip\myskip
{\it
mksmooth, curve
mkcontrolledfcn, functioncurve,
openqbs, closedqbs.\brk
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. The curve is defined to have tension (in the \MF\ sense of
tension) between each pair of points equal to the \gbc{curvetension}, a
global numeric parameter.

\gbc {curve $(T, 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. The
curve is defined to have tension $T$.

\gbc{mkcontrolledfcn $(p)$ } returns a smooth curve through the points
given by the array of pairs $p$. The curve is ``controlled'' by a
numeric parameter \gbc{functiontension}. If \gbc{functiontension} is
greater than or equal to 1, \emph{and\/} the x coordinates of the points
in $p$ are increasing, then the x coordinates of the curve are
guaranteed to increase. Therefore, the curve will be the graph of a
function. The parameter \gbc{functiontension} is not strictly a tension
in the \MF\ sense, but functions similarly to influence the location of
control points.

\gbc{functioncurve $(T, t)$ } sets \gbc{functiontension} to $T$, converts
the text list of pairs $t$ to an array $p$, and then calls
\gbc{mkcontrolledfcn $(p)$}.

\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}

\vskip\myskip
{\it
lclosed;
sclosed;
bclosed;
uclosed;
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}. The curve returned by \gbc {sclosed $f$} may
differ in shape from $f$, due to \MF\ optimization of control points
over the whole of a curve.

\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{uclosed $f$ } closes $f$ in a smooth manner, but unlike the previous
two operations, does not change the shape of $f$.

\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}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
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. (How
old do you have to be to remember ``turtle graphics''?)


\head{Sectors}

\vskip\myskip
{\it
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}

\vskip\myskip
{\it
id.}

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


\head{Functions and paths}

\vskip\myskip
{\it
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. The step $d$ will be adjusted if necessary so that a whole
number of steps takes place, and the curve ends with $v$ precisely equal
to $b$.

\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$. If the \mfc{boolean} $s$ is \mfc{true},
then the \mfc{path} is a smooth curve, otherwise it is a polyline.
\gbc{parafcn} uses the text $pf_t$ to define a function $pf$ and then
calls \gbc{mkfcn}.

\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. This
\gbc{xfcn} merely calls \gbc{mkfcn} with $pf$ defined by
$pf(x)=(x,f(x))$.

\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{function} uses the text $f_x$ to define $pf$ and then calls
\gbc{mkfcn}.

\gbc {rfcn $(s, a, b, d, f)$ } returns a \mfc{path} passing through the X
and Y coordinate \mfc{pair}s $f(t) * (\mfc {dir\ } 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.  \gbc{rfcn} constructs a pair-valued
function as described and then calls \gbc{mkfcn}.

\gbc {plrfcn $(s, a, b, d, f_t)$} returns a \mfc{path} passing through
the X and Y coordinate \mfc{pair}s $f_t * (\mfc {dir\ } t)$,
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. \gbc{plrfcn} constructs a pair-valued function as described
and then calls \gbc{mkfcn}.

\head{Text labels (\MP{} only)}

\vskip\myskip
{\it gblabel}

\nobreak
\gbc{gblabel $(l,r,b,t, a)$ $(s,p)$ } places the label $s$ at the point
$p$, positioned according to the information in $(l,r,b,t,a)$. If $L$,
$R$, are the x-coordinates of the left and right end of the bounding box
of $s$, and $B$, and $T$ are the y-coordinates of the bottom and top,
then the text is shifted so the point $(lL + rR, bB + tT)$ is at the
origin (normally the leftmost point of the baseline is at the origin),
then rotated by angle $a$, then shifted to the point $p$. For example,
to place the lower left corner of $s$ at $p$, use $(1,0,1,0,a)$. To
place the center point of the baseline of $s$ at $p$, use
$(1/2,1/2,0,0,a)$. Note: One can think of $l,r,b,t$ as selecting a new
reference point, after which the text is rotated about it and then moved
so the reference point is at $p$.

The text $s$ should be either of type string or picture. The most common
example would be a \mfc{ btex $\ldots$ etex } expression (which is
syntactically a picture expression). If $s$ is a string, it is converted
to a picture with \gbc{ $s$ infont defaultfont scaled defaultscale}.


\head{Overlays}

\vskip\myskip
Global Parameters:  {\it
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
%%%
