%%% File: mf-revu.tex
%%% A part of mfpic 0.6 2002/09/12
%%%
%  Review of some aspects of Metafont
\input header

% For "12pt":
%\magnification=\magstep1

% Paper size: {width}{height}
\setpapersize{8.5truein}{11 truein}

% Text size: {width}{height}
\setpagegeometry{5.4167 in}{7.4166 in}

% A depiction of the MF "--" permitting
% a linebreak on either side:
\def\pj{\hskip 0pt plus 3pt minus 0pt{\tt --}\hskip 0pt plus 3pt minus 0pt}

% HEADING:
\centerline{\bf A Review of \MF{} Programming}
\centerline{Geoffrey Tobin ({\tt G.Tobin@latrobe.edu.au}) Thu 18 Jan
1996\footnote{$^*$}{Comments about \MP{} by Daniel Luecking ({\tt
luecking@uark.edu}) Tue 24 Jul 2001}}

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

The only available {\it references} for \MP{} are the files
\file{mpintro.ps}, \file{mpman.ps} and \file{mpgraph.ps} accompanying
most \MP{} distributions. However, the books, {The \LaTeX{} Graphics
Companion} by M.~Goosens, S.~Rahtz and F.~Mittelbach, Addison-Wesley,
1997, and Alan Hoenigs {\it \TeX{} Unbound}, Oxford University Press,
1998, both contain some useful supplemental material on \MP.

This document gives reminders of some facets of \MF{} and \MP.

\head{Types}

\MF{} has nine ($9$) types of expression:  {\tt boolean}, {\tt numeric},
{\tt pair}, {\tt path}, {\tt pen}, {\tt picture}, {\tt string},
{\tt transform}, and {\it vacuous}.  The first eight ($8$) are
{\it named} types; their names can be used to declare variables (for
example, {\tt string surname;}), or to test the type of a variable or
expression (as in {\tt message "x is " \& if pair x: "indeed" else:
"not" fi \& " a pair";}).  Every undeclared \MF{} variable is
of type {\tt numeric}.

Statements can be treated as expressions of the {\it vacuous} type.
Expressions of {\tt boolean} type are either {\tt true} or {\tt false},
whereas {\it vacuous} expressions have only one possible value.
The allowed values of all the types, and the range of expressions
available in \MF{}, are described in {\it The \MF{}book}.

\MP{} has an additional expression type, {\tt color}, with a
corresponding boolean test.

\head{Groups}

A {\it group} is an {\it compound} expression of the form
{\tt begingroup A; B; C; D endgroup} which may contain several
statements; its value is that of its last expression, so
{\tt begingroup message "hello"; 123.45 endgroup}
has the value of $123.45$, which is {\tt numeric}.
If the group is empty, or if its last item is a semicolon,
then the group has the {\it vacuous} type.

\head{Macros}

{\it Macros} are the \MF{} equivalent of functions and procedures.
There are two broad classes of macro:  untyped ({\tt def}) and typed
({\tt vardef}).  Typed macros are permitted to have the {\it vacuous}
type: an example is {\tt vardef fred = message "I am called Fred";
enddef;} .  In fact, {\tt vardef A = B enddef;} may be seen as a
shorthand for {\tt def A = begingroup B endgroup enddef;} .

\head{Numerics}

\subhead{\MF{} Numeric Operations}

The arithmetic operators {\tt +}, {\tt -}, {\tt *}, {\tt /} are
primitives in \MF{}.  So are Pythagorean addition ({\tt ++}) and
subtraction ({\tt +-+}):  $x \mathbin{{+}{+}} y = \sqrt {x^2 + y^2}$ and
$x \mathbin{{+}{-}{+}} y = \sqrt {x^2 - y^2}$.

Plain \MF{} defines exponentiation ({\tt **}), remainder ({\tt mod})
and integer division ({\tt div}).

\subhead{\MF{} Numeric Relations}

Numeric expressions can be compared:  relations include equality,
({\tt =}), and inequalities ({\tt <>}, {\tt >}, {\tt <}, {\tt >=},
{\tt <=}).

\subhead{\MF{} Numeric Functions}

\MF{} has some useful numeric functions built-in.  These
include:  length, sqrt, sind, cosd, mlog, mexp, floor, angle,
uniformdeviate, normaldeviate.

{\bf length $x$} is the absolute value of $x$.\footnote{$^*$}{If
$x$ is of type {\tt numeric}. But {\bf length $(x,y) = \sqrt{x^2 + y^2}$}
and the {\bf length} of an expression of type {\tt path} is the number
of segments in the path.}

{\bf sqrt $x$} is the square root of $x$.

{\bf sind $x$} is the sine of $x$ degrees.

{\bf cosd $x$} is the cosine of $x$ degrees.

{\bf angle $(x, y)$} is the angle between the line from the origin to
$(x,y)$ and the positive x-axis. It is positive for points above the
x-axis and negative for those below. On the negative x-axis it is 180.
With the obvious exceptional cases {\bf angle~$(x,y) =
{y\over|y|}\arccos(x/\sqrt{x^2 + y^2})$}

{\bf mlog $x$} is $256 \hbox{\tt ln} x$, where {\tt ln} is the
logarithm to the base $e$.

{\bf mexp $x$} is $e^{x/256}$.

{\bf floor $x$} is the largest integer less than or equal to $x$.

{\bf uniformdeviate $x$} is a uniformly distributed random number
between $0$ and $x$.

{\bf normaldeviate} is a normally distributed random number with mean
$0$ and standard deviation $1$.

The random number generators can be restarted at a given stage by
assigning a numeric value to the primitive internal variable
{\bf randomseed}.

Plain \MF{} defines {\bf ceiling}, {\bf abs} (same as {\bf length}),
{\bf round}, {\bf min} and {\bf max}, among other functions.

\head{Pairs}

Subsequently, we often speak of {\it points} in the graphical sense.
These are represented in \MF{} by values of type {\tt pair}.
Constants of type {\tt pair} have the form $(x, y)$,
where $x$ and $y$ are both numeric constants.
A variable $p$ of type {\tt pair} is equal to the
pair expression ({\tt xpart} $p$, {\tt ypart} $p$).

\head{Paths}

A path represents a type of continuous curve called a
{\bf B\'ezier}, which is comprised of a chain of {\bf segments}.
Each segment has a shape determined by four {\bf control points}.
Two of the control points, the {\it key} points, are the segment's
endpoints; often we let \MF{} determine the other two, as in the
{\tt path} expression $p_1..p_2..p_3$, which has two segments,
from $p_1$ to $p_2$, and from $p_2$ to $p_3$.

\head{Pens}

Pens are a distinctive feature of \MF{}, whereby quite refined
figures can be drawn.  Pens are filled convex shapes that
are moved along paths, to alter picture pixel values in
often complicated ways.

Two pens are initially present in MF{}, {\tt nullpen} and
{\tt pencircle}.  Since {\tt nullpen} is the single point $(0,0)$,
which contains no pixels, it cannot be seen, so it can be used
for filling a region without fuzzing its boundary.  By contrast,
{\tt pencircle} is circular, with the points $(\pm0.5, 0)$ and
$(0, \pm0.5)$ on its circumference.

Other pens are constructed as convex polygons via {\tt makepen $c$},
where $c$ is a closed path; the key points of $c$ become the
vertices of the pen.

Now, {\tt pencircle} and {\tt makepen $c$} are called {\it future}
pens.  They are continuous, whereas pictures are discrete, so pens,
like pairs and paths, must be {\it rendered} discrete before being
applied to a picture.

By contrast, {\tt nullpen}, all pen variables (after they have been
assigned a value), and any pen expression in parentheses, are already
{\it discrete} pens.

{\it Future} pens can be transformed by scaling, translating, and so on,
just as pairs and paths can; but {\it discrete} pens
cannot.\footnote{$^*$}{Well, they can, but you usually won't get what
you expect, and the result is a \emph{future} pen!}
An example of an elliptical future pen is {\tt pencircle xscaled 30
yscaled 20}, the discrete pen for which is illustrated on page 148 of
{\it The \MF{}book}.

While \MP{} has pens, it has exhibited some rather odd bugs when they
are other than elliptical. This no doubt has to do with the fact that
\PS{} normally deals only with linear transformations of circular pens.
Moreover, discretization never occurs in \MP, so there is no distinction
between pens and future pens.

\head{Colors \rm(\MP{} only)}

A expression of type {\tt color} is a triple $(r,g,b)$, where each
component is a numeric expression. A variable $c$ of type {\tt color} is
equal to the expression ({\tt redpart} $c$, {\tt greenpart} $c$, {\tt
bluepart} $c$). Colors may be added together and multiplied by numeric
expressions.

When a color is actually used (see {\tt withcolor} in the section {\it
Pictures\/}~(\MP)) the components are truncated to lie between $0$
and $1$, and interpreted as a level of intensity of the corresponding
color component in the rgb color model. The color {\tt red} is defined
to be $(1,0,0)$, producing red at maximum intensity. A color variable
{\tt OddRed} with value $(2,-2,-1)$ will produce the same result as {\tt
red}. Between such uses, however, {\tt red} and {\tt OddRed} will be
unequal in any test.

\head{Pictures\/ \rm(\MF)}

\MF{} pictures contain pixels arranged as a regular grid of squares.
One of the pixels has as its boundary the {\it unit square}, which is
the path {\tt $(0,0)$\pj$(0,1)$\pj$(1,1)$\pj$(1,0)$\pj cycle}.
Pictures are built up from the {\tt nullpicture}, which has all pixels
zero ($0$), using {\tt addto}, and their pixels are trimmed using {\tt
cull}.

Picture variables can be assigned:  $v := W;$  where $v$ is a
picture variable, and $W$ is a picture expression
such as $u + w$, $u - w$, $+u$, $-u$, or combinations of these.
Picture $v$ can have picture $w$ added to it by
{\tt addto $v$ also $w$}, which {\it The MF{}book, page 118} explains
is faster and uses less memory than {\tt $v := v + w$} but is
otherwise the same.

The meaning of $v + w$, for example, is a picture in which each pixel is
the sum of the two pixels that occupy the same position in pictures $v$
and $w$ respectively.  The effects on pixel values of filling and
drawing are much less predictable, and depend greatly on which pen is
used.

Filling a {\it closed} path $c$ in a picture $v$ uses {\tt addto $v$
contour $c$ \<with list\>},

Drawing the outline of a path $f$ uses {\tt addto $v$ doublepath $c$
\<with list\>}. A \<with list\> can be empty, or it can be one or both
of the phrases {\tt withpen \<pen expression\>} and {\tt withweight
\<numeric expression\>}. By choosing different pens, drawing is refined,
as in calligraphy. Weights are weighting factors for pixels.

To change all pixels in a picture variable $v$ that have values between
$2$ and $4$ (inclusive) into $-5$, and all other pixels to zero, use:
{\tt cull $v$ keeping $(2,4)$ withweight $-5$}. To zero all pixels with
values between $-3$ and $1$ (inclusive), and to change all other pixels
into $2$, use: {\tt cull $v$ dropping $(-3,1)$ withweight $2$}, If the
{\tt withweight} phrase is omitted, then the surviving pixels have value
one ($1$). {\it Beware} of attempting to change zero-valued pixels to
nonzero, as zero-valued pixels extend to infinity in all directions.

\head{Pictures\/ \rm(\MP)}

\MP{} is intended to produce \PS{} output, and \PS{} code is mainly a
set of path definitions, which are then filled, or stroke, or dashed,
etc. Thus \MP{} stores pictures not as pixel values but as a list of
{\it objects}, such as stroked paths, filled paths, text strings, etc.
Rasterization into pixels happens in the \PS{} interpreter, such as
\GS{} or possibly one resident in your \PS{} printer.

One feature of \PS{} is that ``ink'', once laid down cannot be removed.
Thus the plain \MP{} macro \mfc{unfill} does not zero any pixels as in
\MF{}, but merely fills with white (more precisely, with the color named
\mfc{background}, which is initialized to \mfc{white}). A consequence of
the \PS{} model is that the {\tt cull} operations and the {\tt
withweight} modifier are unknown in \MP.

The {\tt addto} primative is available, but addition $+$ and subtraction
$-$ are not. The effect of {\tt addto $A$ also $B$} is to add the object
$B$ to the picture $A$. A useful way to visualize this is to think of
$B$ as being rendered on a transparent sheet with opaque ink and then
laid on top of $A$.

In \MP{} a \<with list\> may contain the following additional modifiers:
{\tt withcolor $c$} and {\tt dashed $p$}, where $c$ is a color
expression and $p$ is a picture expression. {\tt withcolor} can follow
any element being added to a picture, but {\tt dashed} must follow a
{\it path} and results in the path being rendered as a dashed curve. The
method by which the picture $p$ is translated to a dashing pattern is
rather arcane, but the {\tt plain.mp} macro {\tt dashpattern \<on-off
list\>}, which returns an appropriate picture, is all a user needs to
know. The \<on-off list\> consists of any number of repetitions of
``{\tt on \<len$_1$\>}'' and ``{\tt off \<len$_2$\>}'', in any order.
The \<on-off list\> denotes in an obvious way the lengths of dashes and
spaces.

A new primative picture operation is {\tt clip $p$ to $c$}, where $p$ is
a picture and $c$ is a closed path. It modifies $p$ to show only the
part interior to $c$. (Actually, it simply adds a clipping path
component to the internal representation of the picture.)

The list of objects in a picture $A$ can be accessed with a for-loop of
the form {\tt for $x$ within $A$: $\ldots$ endfor}. This operation
ignores the top level clipping path and the bounding path (added by {\tt
setbounds}) but otherwise accesses all components. Several boolean
operations can be used to test these components. For a complete
discussion, see the last section of \file{mpgraph.ps}.

\head{Transforms}

Affine transforms are the natural transformations of Euclidean geometry:
the linear transformations augmented by translation. In two dimensions,
transforms are completely specified by their action on three
non-collinear points in the plane.  If $T$ is a variable of type {\tt
transform}, and $p$ is a pair, then $T$ maps $p$ onto this pair:  $p$
{\tt transformed} $T$.  Thus \MF{} can construct any affine transform:
for example, plain \MF{} defines the {\bf identity} transform.  Plain
\MF{} also defines a macro named {\bf inverse} which processes a
transform $T$ such that {\bf inverse $T$ transformed $T$ $=$ identity}.

Each transform $T$ has six components, and can be expressed as a linear
transformation followed by a translation.  The translation components of
$T$ are {\tt xpart $T$} and {\tt ypart $T$}, and the four linear
components are {\tt xxpart $T$}, {\tt xypart $T$}, {\tt yxpart $T$} and
{\tt yypart $T$}.  Employing the obvious notation, $T$ is applied as:

$$
   \left(
     \matrix{t_x \cr t_y}
     \left|
       \vphantom{\matrix{t_xy \cr t_yy}}
     \right.
     \matrix{ t_{xx} & t_{yx} \cr t_{xy} & t_{yy}}
   \right)
   \pmatrix{x \cr y}
   =
   \pmatrix{t_x + t_{xx} x + t_{xy} y \cr
            t_y + t_{yx} x + t_{yy} y}
$$

\MF{} also provides seven primitive transforms, listed on page 141 of
{\it The \MF{}book}:

\halign
{\indent#\hfil&\quad#\hfil\cr
$(x,y)$ {\tt shifted} $(a,b)$   & $ = (x+a, y+b) $  \cr
$(x,y)$ {\tt scaled}  $s$       & $ = s (x, y) $   \cr
$(x,y)$ {\tt xscaled} $s$       & $ = (sx, y) $    \cr
$(x,y)$ {\tt yscaled} $s$       & $ = (x, sy) $    \cr
$(x,y)$ {\tt slanted} $s$       & $ = (x,y) + s (y, 0) $   \cr
$(x,y)$ {\tt rotated} $\theta$  & $ = (x \cos \theta - y \sin \theta,
                                 x \sin \theta + y \cos \theta) $ \cr
$(x,y)$ {\tt zscaled} $(u,v)$   & $ = (xu - yv, xv + yu) $ \cr
}

These operations are taught in secondary school mathematics; for
example, {\tt slanted} is skewing parallel to the X axis. Interpreting a
pair as a complex number in Cartesian coordinates, {\tt zscaled} is
complex multiplication.

One can also transform pictures (in addition to pairs and paths).
However, in \MF{} one is limited in what transforms are permitted: one
can only transform by a combination of translation by integer multiples
of one pixel, rotation by integer multiples of 90 degrees, and scale by
integers. All other transformations of a picture result in a message:
``that transformation is too hard''. In fact, transforming pictures is
so limited that one usually has to transform just paths and points, and
commit them to a picture only when no further transformations are
required.

In \MP{} there are no restrictions on transforming pictures.


\head{Composite Variables}

\MF{} allows {\it composite} variables --- homogeneous {\it arrays},
heterogeneous {\it suffixes}, and arbitrary combinations of those. One
can declare composite variables, and test whether they {\it contain} a
given structure.  However, these are not fully-fledged types, since
every expression has one of the nine {\it simple} types. For example,
after declaring {\tt path p[];} then {\tt p1} and {\tt p[1+3]} are of
type {\tt path}, but of what type is {\tt p} ? It's {\tt numeric}!

Moreover, \MF{} {\it lacks} pointers.  It is not possible for a macro to
return a value that has not one of the nine {\it simple} types. The
allowed syntax {\tt vardef b[] = $\cdots$ enddef;} may suggest that this
macro returns an array, but in fact {\tt b[3]} {\it expands} to the
whole {\it replacement text} of the macro.

Here is a macro that is useful for testing the type of a variable,
suffix or expression:

\myverbatim#
    def type suffix x =
      message str x & " is "
        &
        if     known x:     "a known "
        else:               "an unknown "
        fi
        &
        if     boolean x:   "boolean"
        elseif numeric x:   "numeric"
        elseif pair x:      "pair"
        elseif path x:      "path"
        elseif pen x:       "pen"
        elseif picture x:   "picture"
        elseif string x:    "string"
        elseif transform x: "transform"
        else:               "vacuous"
        fi;
      enddef;
@endmyverbatim

\bye

