% -*- Mode:TeX -*-
\chapter{The plane editor}\label{pledit}

The bits of information that make up the state of the \cam\ universe are
arranged in four arrays of size 256\by256 called {\sl
bit-planes}\index{Bit-plane}.  Normally, each of the bit-planes is
wrapped around\index{Bit-plane/edges} so that its left edges
adjoins the left edge, and similarly for top and bottom edges (but cf.\
Section \ref{gluing} and Chapter \ref{user}).

A number of \cxp\ commands are available for editing the contents of the
\cam\ planes, in order, for instance, to construct a given initial state
for the cellular automaton.  We shall refer to this subset of \cxp\
commands as the {\sl plane editor}.\index{Plane editor} The plane editor
is interactive, in the sense that whatever changes you make to the
contents of \cam's planes is immediately displayed on the \cam\
monitor.\footnote
        {Provided that an appropriate color map is being used.  This will be
explained in a moment.}

The \cam\ plane editor is a quite different object from the Forth {\sl screen editor}
(Chapter \ref{editor}), which is used for interactively editing Forth programs on the
\pc\ monitor.  (In this context, `screen' is a Forth technical term; it refers to a
block\index{Forth/block} of Forth text residing on disk, or to the same block as displayed in the screen
editor's window.) In brief, the plane editor allows one to manipulate some of \cam's
contents as {\em graphic} material, displayed on the \cam\ monitor, while the screen
editor allows one to manipulate some of the \pc's contents as {\sl text} material, displayed
on the \pc\ monitor.

\section{The state of the universe and its representation}

The bits of information that make up the state of the \cam\ universe
are arranged in four arrays of size 256\by256 called {\sl
bit-planes}. Thus, each of the 256\by256 sites or ``cells'' of the
cellular automaton contains four bits, one from each bit-plane. 

\medskip

Treating the state of a cell as a collection of four bits is
convenient for programming purposes. For display purposes, it is
better to represent each cell by a colored dot, or {\sl pixel}, on the
screen. The color, of course, will correspond to the cell's state
according to a definite assignment: the table that decides which color
has been assigned to each of the 16 possible cell states is called the
{\sl color map}.\index{Color map} In \cam, the contents of the color map can be
specified by the user to suit the requirements of each experiment.

We'll explain later how to build different color maps and how to use
them for different purposes. For the moment we'll use a color map that
establishes a {\sl one-to-one correspondence} between the contents of
a cell and the color of the corresponding pixel, so that the picture
on the screen provides an unambiguous representation of the
bit-planes' contents.\footnote
    {A color map may assign the same color to two or more different
cell values; in this case one cannot unambiguously reconstruct the
contents of a cell from its color on the screen.}
  In this way, nothing is hidden from view: if you change a bit in one
of the planes something will change on the screen.

 \begin{equation}\label{eq.irgb}
  \begin{tabular}{|c|c|c|c||c|c|c|c|l|}
   \multicolumn{9}{l}{Color map: {\tt IRGB-MAP}} \\
   \hline
   \multicolumn{4}{|c||}{Plane}  & \multicolumn{4}{c|}{Monitor line} & Pixel  \hfill Color\\\cline{1-8}
    0  & 1  & 2  & 3  & I       & R       & G       & B       & color         \hfill code\\\hline\hline
   \tt0&\tt0&\tt0&\tt0&         &         &         &         & black         \hfill\tt 0\\\hline
   \tt0&\tt0&\tt0&\tt1&         &         &         &$\bullet$& blue          \hfill\tt 1\\\hline
   \tt0&\tt0&\tt1&\tt0&         &         &$\bullet$&         & green         \hfill\tt 2\\\hline
   \tt0&\tt0&\tt1&\tt1&         &         &$\bullet$&$\bullet$& cyan          \hfill\tt 3\\\hline
   \tt0&\tt1&\tt0&\tt0&         &$\bullet$&         &         & red           \hfill\tt 4\\\hline
   \tt0&\tt1&\tt0&\tt1&         &$\bullet$&         &$\bullet$& magenta       \hfill\tt 5\\\hline
   \tt0&\tt1&\tt1&\tt0&         &$\bullet$&$\bullet$&         & yellow        \hfill\tt 6\\\hline
   \tt0&\tt1&\tt1&\tt1&         &$\bullet$&$\bullet$&$\bullet$& white         \hfill\tt 7\\\hline
   \tt1&\tt0&\tt0&\tt0&$\bullet$&         &         &         & gray          \hfill\tt 8\\\hline
   \tt1&\tt0&\tt0&\tt1&$\bullet$&         &         &$\bullet$& bright blue    \hfill\tt 9\\\hline
   \tt1&\tt0&\tt1&\tt0&$\bullet$&         &$\bullet$&         & bright green   \hfill\tt A\\\hline
   \tt1&\tt0&\tt1&\tt1&$\bullet$&         &$\bullet$&$\bullet$& bright cyan    \hfill\tt B\\\hline 
   \tt1&\tt1&\tt0&\tt0&$\bullet$&$\bullet$&         &         & bright red     \hfill\tt C\\\hline
   \tt1&\tt1&\tt0&\tt1&$\bullet$&$\bullet$&         &$\bullet$& bright magenta \hfill\tt D\\\hline
   \tt1&\tt1&\tt1&\tt0&$\bullet$&$\bullet$&$\bullet$&         & bright yellow  \hfill\tt E\\\hline 
   \tt1&\tt1&\tt1&\tt1&$\bullet$&$\bullet$&$\bullet$&$\bullet$& bright white   \hfill\tt F\\\hline
  \end{tabular}
 \end{equation}

\section{The {\sl IRGB\/} color map}\label{irgb}

The color map we are going to use for editing practice is called {\sl
IRGB}.  These four letters stand for the four input lines of the color
monitor, namely {\sl Intensity}, {\sl Red}, {\sl Green}, and {\sl
Blue}.\index{Monitor/beams} The last three signals separately drive
the \pc\ monitor's three color beams, while the first adds some extra
white light by increasing the intensity of {\sl all three} beams.  This
color map (defined by the Forth word \iprog{IRGB-MAP}) establishes a
direct link between the contents of the four bit-planes and these four
signals, as shown in Table (\ref{eq.irgb}).\index{Color map/IRGB}
For instance, the blue beam will be turned
on for a given pixel on the screen if in the corresponding cell the bit
of plane 3 is ``on'' (i.e., has value 1).  If more than one bit is on,
the overall pixel color will be a superposition of the corresponding
primary colors, plus intensity if present.

\section{Editing practice}\label{plane-arg}

To start a tutorial editing session\index{Plane editor/tutorial}, where you will be able to
immediately practice the commands of this chapter as they are
introduced, it will be convenient to initialize \cam\ to an agreed
upon state; in particular, to get a sample pattern into the planes
and to load the color-map table with \iprog{IRGB-MAP}.

To this purpose, type \keyL\targ{irgb}\footnote
    {Don't forget to hit \keyreturn\ at the end of the string argument.}
and wait for the happy-face prompt.
    This loads a ``dummy experiment'' that (a) specifies
\iprog{IRGB-MAP} as the color map---so that all the editing you do on
the bit-planes will be clearly visible on the \cam\ screen---and (b)
specifies {\sl identity} as the rule for the cellular automaton (this is
a ``do nothing'' rule)---so that even if you inadvertently hit the {\sl
Step} or {\sl Run} keys (cf.\ Section \ref{run-keys}) the pattern on the
screen will not change.  Now type \keyG\targ{sample} to get a sample
pattern contained in the file \iprog{SAMPLE.PAT} and copy it into \cam's
bit planes; this pattern will appear on the screen (cf.\ Section
\ref{first-exp} if you have any problems here).

\medskip

As explained in Section \ref{typing}, many \cxp\ commands may be
preceded by a numeric argument.\index{Control panel/numeric argument}
For most of the commands that make up the plane editor this argument is
used to specify on which plane (or planes) the command itself should
operate.  Planes are numbered 0 through 3, and the available options for
a ``plane'' argument are:

 \begin{description}
  \item[0--3]: Select only the specified bit-plane (0 through 3).
  \item[4]: Select plane pair 0--1 (i.e., both planes 0 and 1).
  \item[5]: Selects plane pair 2--3 (i.e., both planes 2 and 3).
  \item[No argument]: The command is carried out on all four planes.
 \end{description}

All keys which take a ``plane'' argument follow this
convention (with only one exception, namely the \keyd\ key, which will be
explained when we come to it).

 For example, the command \keyz\ is defined as follows in Table
(\ref{eq.fill}) below:
 $$
  \begin{tabular}{|r|p{8cm}|} \hline
   \keyz & {\sl Zero}. Fill plane(s) with 0s (``clear'' the planes).\\\hline
  \end{tabular}
 $$
 \noindent Thus, typing \keyz\ will clear all four planes;
\narg{0}\keyz\ will clear only plane 0; \narg{4}\keyz\ will
clear planes 0 {\sl and} 1; etc. 

\section{Color filters}

It is possible from the \cp\ to temporarily modify the color map
currently in use so that one or more of the inputs to the color monitor
are cut off.\index{Color map/disabling a beam}\index{Color filters} This
is occasionally useful while debugging an experiment:  if the current
color map is one that directly routes the contents of the four planes to
the four monitor inputs (as does the {\sl IRGB} color map), then
cutting off one of the beams is equivalent to {\sl hiding from view} the
corresponding plane---without actually affecting its contents.

The relevant commands are\index{Color map/IRGB}
 \begin{equation}
  \begin{tabular}{|l|p{8cm}|} \hline
    \icp\keyfn2 & {\sl IRGB map}. Use \id|IRGB-MAP| as the color map, and restore
any beams that are cut off. This ``faithful'' map is useful
for debugging purposes.\\\hline 
    \icp\keyfn4 & {\sl Intensity}. Whatever color map is in use, toggle ``intensity'' beam on or off. \\ \hline
    \icp\keyfn6 & {\sl Red}. Similarly, toggle red beam on or off. \\ \hline
    \icp\keyfn8  & {\sl Green}. Toggle green beam on or off. \\ \hline
    \icp\keyfn{10} & {\sl Blue}. Toggle blue beam on or off. \\ \hline
  \end{tabular}
 \end{equation} Note that \keyfn2\ reactivates any beams that were
turned off by \keyfn4--\keyfn{10}.  Practice the above commands right
away (if the pattern \prog{SAMPLE.PAT} has been destroyed by the
previous practice session, get it again from disk using the \keyG\
command); then type \keyfn2\ to restore full view of the planes.

\medskip

The following commands are also available\index{Color map/standard}
 \begin{equation}
  \begin{tabular}{|l|p{8cm}|} \hline
    \icp\keyFn2 & {\sl Standard map}.  Use \id|STD-MAP| as the color
map, and restore any beams that are cut off.  This is the default or
{\sl standard} color map, discussed in Section \ref{std-map}.  \\ \hline
    \icp\keyFn4 & {\sl Restore intensity}. Restore intensity beam, if cut off by \keyfn4.\\\hline
    \icp\keyFn6 & {\sl Restore red}. Restore red beam.\\ \hline
    \icp\keyFn8  & {\sl Restore green}. Restore green beam. \\ \hline
    \icp\keyFn{10} & {\sl Restore blue}. Restore blue beam. \\ \hline
  \end{tabular}
 \end{equation}

For sake of reference, we shall list here the following
 \begin{equation}
  \begin{tabular}{|l|p{8cm}|} \hline
    \icp\altfn2 & ({\sl Custom map}).  As all {\tt Alt-} commands, this
\cxp\ command is initially undefined.  However, a custom color map
defined by the user for a given experiment should preferably be attached
(cf.\ Sections \ref{attach}, \ref{color-map}) to this key, for
convenience in locating it.\\\hline
  \end{tabular}
 \end{equation}


\section{Shift, hold}\label{shifts}

The following commands use the {\sl numeric keypad} section of the
keyboard (briefly, the ``arrow keys,''\index{Keyboard/arrow keys} even though
only four of these keys are actually marked by arrows).\index{Control-panel commands/shift}  They are used
to shift all or some of the four bit-planes in any of eight directions.
 \begin{equation}
  \begin{tabular}{|l|p{8cm}|} \hline
   \icp\keyup & {\sl Shift} plane(s) up. \\ \hline
   \icp\keydown & {\sl Shift} plane(s) down. \\ \hline
   \icp\keyleft & {\sl Shift} plane(s) left. \\ \hline
   \icp\keyright & {\sl Shift} plane(s) right. \\ \hline
   \icp\keypgup & {\sl Shift} plane(s) up-right. \\ \hline
   \icp\keypgdn & {\sl Shift} plane(s) down-right. \\ \hline
   \icp\keyhome & {\sl Shift} plane(s) up-left. \\ \hline
   \icp\keyend & {\sl Shift} plane(s) down-left. \\ \hline
  \end{tabular}
 \end{equation}

For instance, pressing the ``right arrow'' key \keyright\ will make the
screen pattern shift rightwards, wrapping around from the right edge to
the left one.   The pattern will keep shifting as long as you keep the
key pressed. If you just hit the key momentarily, the pattern will shift by
an amount determined by the shift-size register (see below),
with initial default of eight pixels.

For these commands, the optional numeric argument specifies the amount
of shift in pixel units (thus, it is not interpreted as a ``plane''
argument). Thus, if you type \narg{4}\keyright\ the pattern
will shift by {\sl four} pixels, and every subsequent shift operation
will also move the pattern by a multiple of four pixels---until you again give a
shift command preceded by an argument.  In fact, the eight {\sl Shift}
commands share a single {\sl shift-size} register, which is initially
set to 8 but is modified when you give an explicit argument to any of
these commands.  This argument can be any number in the range
0--511 (other numbers are reduced modulo 512). To go back to
eight-pixel shifts, type \narg{8}\keyright.\footnote
    {Since this will execute an eight-pixel shift, you may follow it
with \narg{8}\keyleft\ if you want to reset the shift size
to 8 but leave the pattern in its original position.}

\bigskip

Sometimes it is desirable to shift only {\sl some} of the planes and
leave the others fixed in place.\index{Control-panel commands/hold}  Each bit-plane can be held fixed or
made free to shift.  The following commands can be used to obtain any possible
combination of ``free-to-shift'' and ``fixed-in-place'' bit-planes:
 \begin{equation}
  \begin{tabular}{|r|p{8cm}|} \hline
   \icp\keyh & {\sl Hold}. Make plane(s) fixed. \\ \hline
   \icp\keyH & {\sl Unhold}. Make plane(s) free to shift. \\ \hline
  \end{tabular}
 \end{equation}
 \noindent These commands take an optional ``plane'' argument.  As
explained in Section \ref{plane-arg}, this means that \keyh\ by itself will
hold all planes; \narg{0}\keyh\ will hold only plane 0;
\narg{4}\keyh\ will hold plane pair 0--1; etc.

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \keyright\ to shift all planes eight cells to the right.
  \item Type \keyleft\ to put the planes back to their original
position.
  \item Type \narg{64}\keyright\ to move the planes right
by 64 pixels.
  \item Now, simply type
\icp\keyleft\ to put the planes back to their original position.
  \item Type \narg{8}\keyup\ \keydown\ to restore the 
shift-size register to its ``default'' value of 8.
    \item Type \narg{1}\keyh\ to hold plane 1 fixed. All subsequent
shift operations will affect only planes 0, 2, and 3 (try some!).
  \item Type \keyH\ to set all planes free (in this case, to release
plane 1).
  \item Type \keyh\ \narg{1}\keyH\ to hold all planes except plane 1.
  \item Type \keyH\ to return to the default state (all planes free).
 \end{itemize}

\section{Rotate, reflect}\label{rotate}

Six commands are available to perform rotations or reflections on the
bit-planes.  They accept an optional ``plane''
argument.\index{Control-panel commands/rotate, reflect}

\begin{equation}
 \begin{tabular}{|r|p{8cm}|} \hline
  \icp\keyr & {\sl Rotate} plane a quarter-turn
clockwise. \\ \hline
  \icp\keyR & {\sl Rotate} a quarter-turn counter-clockwise. \\ \hline
  \icp\keybackslash & {\sl Reflect} about the principal diagonal (which
runs from the upper-left corner to the bottom-right one). \\ \hline
  \icp\keyslash & {\sl Reflect} about the secondary diagonal. \\ \hline

  \icp\keyunder & {\sl Reflect} about the horizontal midline.  \\ \hline
  \icp\keybar & {\sl Reflect} about the vertical midline.  \\ \hline
 \end{tabular}
\end{equation}
        The best way to understand these commands is to see them at work.

\medskip

{\small Since they involve much data movement between \cam\ and the \pc,
the first four of these commands take a little time to execute; this time is
proportional to the number of planes involved. It is wise to
use a numeric argument in order to restrict a command to just
the planes you are interested in.

}

\section{Fill, complement}\label{fill}

Commands are
available for {\sl filling} a plane with all \id|0|s or all \id|1|s, and for
{\sl complementing} a plane (i.e., turning all \id|0|s to \id|1|s and vice
versa, realizing the logic-{\sc not} function).\index{Control-panel commands/fill, complement}
 \begin{equation}\label{eq.fill}
  \begin{tabular}{|r|p{8cm}|} \hline
   \icp\keyz & {\sl Zero}. Fill plane(s) with \id|0|s. \\ \hline
   \icp\keyZ & {\sl Unzero}. Fill plane(s) with \id|1|s. \\ \hline
   \icp\keyminus & {\sl Negate}. Complement plane(s). \\ \hline
  \end{tabular}
 \end{equation} 

\noindent As usual, a numeric argument is used to select individual
planes or plane-pairs.

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \narg{3}\keyminus\ to complement plane 3.
  \item Type \keyz\ to clear all planes.
  \item Type \narg{5}\keyZ\ to fill planes 2 and 3 with \id|1|s.
 \end{itemize}


\section{Random}\label{random}

Random initial conditions\index{Random pattern} are useful in many
experiments.  The command\index{Control-panel commands/random} \keysemicolon\
generates a random pattern where \id|1|s appear with a certain
probability $p$ on a background of \id|0|s (the value of $p$ is
specified by the commands \keycolon\ or \keypercent, as explained
below).

With no argument, all planes are filled with the {\sl same} random
pattern. As usual, a numeric argument restricts the command to the
specified plane or plane pair. Every time you use \keysemicolon\ a {\sl new}
pattern is generated.

\medskip

Without a numeric argument, the command \keycolon\ resets
the value $p$ of the {\sl probability register}\index{Probability register} to a default
value of 1/2.  When preceded by a numeric argument $n$ in the range
0--65536, this command sets $p$ to the value
 $$
 p={n\over65536}.
 $$
 \noindent Since the size of a plane is 256\by256 (=65536),
$n$ corresponds to the {\sl expected} number of \id|1|s: for example,
once you've typed \narg{100}\keycolon, the command
\keysemicolon\ will produce patterns containing approximately one-hundred
\id|1|s (and averaging precisely one-hundred over many patterns).

It is often convenient to think in terms of a percentage $f$ rather
than a number $n$ of cells.  The command \icp\keypercent\ preceded by a
numeric argument $f$ in the range 0--100 sets $p$ to $f/100$, so
that, after typing \narg{33}\keypercent, the command \keysemicolon\ will produce
approximately 33\% of \id|1|s.

 \begin{equation}
  \begin{tabular}{|r|p{8cm}|} \hline
    \icp\keysemicolon & {\sl Random}. Fill the selected plane(s) with a
random pattern using the current value of $p$. \\ \hline
    \icp\keycolon & {\sl Set random count}. The value of the argument (range
0--65536) specifies the expected {\sl number} of \id|1|s. With no
argument, $p=$1/2.  \\ \hline
    \icp\keypercent & {\sl Set random percentage}. The value of the argument
(range 0--100) specifies the expected {\sl percentage} of \id|1|s. With no
argument, $p$=1/2. \\ \hline
    \icp\keyi\ or \icp\keyI & {\sl Initialize seed}. An argument in the range
of 0--65536 is used to generate a 272-bit seed for the random number
generator.  If no argument is given, a default value is used for the seed.
 \\ \hline
  \end{tabular}
 \end{equation}

{\small The random bits are generated by a deterministic, ``pseudo-random''
algorithm. In certain experiments, to make significant comparisons it
is necessary to use the {\sl same} sequence of random patterns as was
used for a previous run of the experiment.  The command \keyi\
re-initializes the random-number generator with a ``seed''
specified by a numeric argument in the range from 0 to $2^{16}${}$-$1:
from the same seed you get the same sequence, while different values
of the seed yield different sequences.

The generator is always initialized with the same default seed upon
entering the \prog{CAM} program.  \keyi\ or \keyI\ without an argument
re-initialize the generator to this default seed.\par}

\medskip

When $p$=1/2, a planeful of random bits is generated in a very short
time; for other values of $p$ the process is somewhat longer.

\medskip
{\bf \noindent Examples:}
 \nobreak
 \begin{itemize}
  \item Type \keysemicolon\ to get a random pattern with 50\% of \id|1|s and
50\% of \id|0|s, identical for the four bit-planes.
  \item Type \narg{10}\keypercent\ \keysemicolon\ to do the same with only 10\%
of \id|1|s.
  \item Type \narg{34901}\keyi\ to initialize the random-number generator
with the seed 34901. This seed can be used as a label to identify
a repeatable sequence of random patterns.
  \item Type \narg{100}\keycolon\ \narg{0}\keysemicolon\ to have about one-hundred
\id|1|s in bit-plane 0.
  \item Type \keycolon\ (or \keypercent, or \narg{50}\keypercent) to reset 
$p$ to its default value of 1/2.
  \item Type \narg{0}\keysemicolon\ \narg{1}\keysemicolon\
\narg{2}\keysemicolon\ \narg{3}\keysemicolon\ to obtain four {\sl different} 50\%
patterns on the four planes.
 \end{itemize}

\section{Magnify screen}\label{magnify}

The individual pixels on the screen are rather small, and it's hard to
discern the fine details of a pattern---especially on monitors that
have poor resolution or are poorly aligned. Moreover, dot operations
(cf.\ Section \ref{dot}) are more easily performed under magnification.

An ``expanded screen'' mode is provided in \cam. When this mode is on, the
screen is expanded both horizontally and vertically by a factor of four, and each
cell appears as a 3\by3-pixel square surrounded by a 1-pixel-wide
black frame. Also, in this mode a positioning grid becomes available,
so that one can count cell positions even when many adjacent cells are
empty.

The commands to control the above features are:\index{Control-panel commands/expand, grid}
 \begin{equation}
  \begin{tabular}{|r|p{8cm}|} \hline
    \icp\keyx & {\sl Expand}. Toggle between normal and expanded mode. \\ \hline
    \icp\keyX & {\sl Unexpand}. Turn off expanded mode. \\ \hline
    \icp\keyrtquote & {\sl Grid}. Toggle the grid on and off. \\ \hline
    \icp\keyquote & {\sl Ungrid}. Turn off the grid. \\ \hline
  \end{tabular}
 \end{equation}

In the expanded mode, only 64\by64 cells are visible on the
screen, instead of the usual 256\by256.  To show a close-up of
a portion of the screen one must move this portion close to the
center by shifting the whole screen pattern in the appropriate direction.
The expanded mode may be used even while the simulation is running
(all \cxp\ commands remain available in this mode) but it
will slow it down.  
\noteskip

{\small The grid is visible only in the expanded mode.  It consists of dots
placed at the intersections of the horizontal and vertical black lines
that separate pixels.  Note that the spacing between grid dots, either
horizontally or vertically, is {\sl two} cells (rather than one), so that each
square of the grid encompasses a 2\by2 block of cells.  This
makes counting rows and columns easier, and is also useful when one uses
special rules or neighborhoods where at any particular step it makes a
difference whether a cell lies on an even or an odd row (or column) of
the array (cf.\ Section \ref{spatial phases}).\index{Spatial grid}

}
\section{Dot graphics}\label{dot}

The {\sl dot} mode\index{Dot mode} is used to set or reset single bits
of the bit-planes.  Only one plane (the ``target'' plane) is accessible
at any given time.

The commands available for this mode of operation are:\index{Control-panel commands/dot, insert}
 \begin{equation}
  \begin{tabular}{|l|p{8cm}|} \hline
    \icp\keyd & {\sl Dot}. Toggle dot mode on or off. If a plane
number is given as an argument (range 0--3), that plane
becomes the target, superseding the previous target.
At start-up, plane 0 is the target. \\ \hline
    \icp\keyD & {\sl Undot}. Turn off dot mode. \\ \hline
    \icp\keyo & {\sl Cursor to origin}. Move the dot cursor to its
initial position at the center of the screen (coordinates $\langle 128,128\rangle$,
whereas the upper-left corner has coordinates $\langle 0,0\rangle$). \\\hline
    \icp\keyO & {\sl Shift to origin}. Shift the screen and the cursor as a whole
until the cursor comes to the center of the screen.\\\hline
    \icp\keyins & {\sl Insert}. Complement bit at cursor. \\ \hline
  \end{tabular}
 \end{equation}
        When in dot mode, a cursor is displayed on the screen,
centered on the target cell; the arrow keys (cf.\ Section
\ref{shifts}) are now used to move the cursor rather than shift the
planes. 

\medskip

In dot mode, the selected plane is only affected when you press the
\keyins\ key: this complements the value of the target bit.  If the
\keyins\ key is kept pressed and the cursor is moved using the arrow
keys, the cursor will toggle all the bits it finds on its path; in this
way one can draw continuous lines and complex shapes.

When you leave the dot mode, the current cursor position and target
plane are remembered. Though the cursor is invisible,
the \keyins, \keyo, and \keyO\ keys remain active.

\noteskip

{\small On certain keyboards, pressing \keyins\ inhibits the 
autorepeat feature of one or more of the numeric-keypad keys.
In this case, use \keycapslock\ or \keyscrolllock\ as a replacement
for \keyins.

}

\noteskip

The dot mode also supports an optional ``mouse'' (see Section \ref{mouse})
as a pointing device: the cursor on the screen will track the mouse's
movements.

When using the mouse, bits are only toggled while one of the mouse
buttons (or the \keyins\ key)\ is pressed.  The right button is used for
drawing horizontal and vertical lines: while the right button is held
down, mouse motion will be interpreted as either horizontal or
vertical, but never diagonal.  Similarly, the left button is used for
drawing diagonal lines.  The middle button (if your mouse has three
buttons, rather than just two) is a convenient duplicate of the \keyins\ key.

\medskip

When in dot mode, the screen shows the contents of the planes as
usual. The planes may already contain complex patterns, and some care
is needed to tell whether the bit to be toggled is a \id|0| that will
become a \id|1| or vice versa.  To help in this, the target cell itself
will blink: during each blinking cycle, the pixel spends one-third of
the time in its proper color (which reflects the {\sl current} state
of the cell's four bits as specified by the color map) and two-thirds of
the time in the color it would have if it were toggled.
In this way, one has a {\sl preview} of the change that \keyins\
would make.

\medskip

The normal cursor is a crosshair.  When the expanded mode is on at
the same time as the dot mode, the crosshair disappears and the
position of the cursor is represented only by the target cell's
blinking.

If the cursor is outside the 64\by64-cell central area when you
enter the expanded mode, the cursor will be moved into this area.

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \keyz\ to clear all planes; the empty planes will look {\sl
black} under the \prog{IRGB} color map (cf.\ Section \ref{eq.irgb}).  Now type
\keyd, and the cursor will appear, with the target
cell blinking {\sl gray} at a 2/3 duty-cycle. In fact,
toggling the target bit will put a \id|1| in plane 0 (the ``gray'' plane
under \prog{IRGB}).
  \item Type \keyins\ to toggle the target bit; the bit becomes a \id|1|, and
correspondingly its duty-cycle becomes  1/3 gray and 2/3 black). Type \keyd\
to exit the dot mode, leaving a single gray pixel on the screen.
  \item Type \keyins\ to turn the bit off.
  \item Type \keyd, and use the arrow keys\ to move
the cursor around.  Now, while holding the \keyins\ key pressed, use
the keypad keys to draw some lines.\footnote
    {If while drawing a line you happen to cross another line the pixel
at the intersection will be toggled off again: intersecting
lines are {\sc xor}ed with one another.}
    Type \keyz\ to clear the screen.
  \item Type \narg{2}\keyd\ \keyins\ \keyd\ to get a single green pixel,
corresponding to a single \id|1| in plane 2.
  \item Type \keyz\ \keyd\ \keyx\ to clear the planes and have the
blinking green cursor on the expanded screen. While holding the
\keyins\ key pressed use the arrow keys to draw some
lines.  Now type \keyd\ \keyx\ to turn off both the dot mode and the
expanded mode. The screen will show the final result of your
graphics editing.
 \end{itemize}

\section{Plane buffers}\label{buffers}

The contents of one or more planes can be temporarily saved to memory
buffers in the \pc, and retrieved from there.\index{Plane buffers}  Each plane has an
associated buffer.  Here we shall discuss mere data movements between
planes and buffers.  Logic operations involving planes
and buffers are available too; they are discussed in Section~\ref{logical}.

The operations described in this section work with a modified
meaning when the {\sl cage} feature is turned on (see Section~\ref{cage}).

 \begin{equation} \begin{tabular}{|r|p{8cm}|} \hline
  \icp\keyp & {\sl Put to buffer}. Save plane(s) to corresponding
buffer(s).  \\ \hline
   \icp\keyP & {\sl Put to disk}. Save plane(s) to a specified file
(see Section \ref{disk-io}). \\ \hline
  \icp\keyg & {\sl Get from buffer}. Retrieve plane(s) from corresponding
buffer(s). \\ \hline
   \icp\keyG & {\sl Get from disk}. Retrieve plane(s) from a
specified file (see Section \ref{disk-io}). \\ \hline
  \icp\keyasterisk & {\sl Exchange}. Exchange
contents of plane(s) and corresponding buffer(s).
 \\ \hline \end{tabular} 
 \end{equation}
        With a numeric argument, the command affects only the specified plane
(or plane pair) and the corresponding buffer(s). 

Note that the names of all plane operations imply as a syntactical
object the image on the screen.  Thus, to remember the data direction of
a {\sl Put} operation in the present context, verbalize ``put the
plane.'' When the cage is active (cf.\ next section), verbalize ``put
the cage.''

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \keyG\targ{sample} to load pattern file \prog{SAMPLE.PAT};
type \keyp\ to save all four \cam\ planes to the buffers. If you clear the
screen typing \keyz, you can restore the previous image by typing \icp\keyg. 
  \item Type \keyz\ to clear the screen and then \narg{0}\keyg\ to
restore only the contents of plane 0.
  \item Type \keysemicolon\ to put the same random pattern on all four
planes. Now each time you type \keyasterisk\ you exchange the
contents of the planes and buffers. Try \narg{0}\keyasterisk\ a
few times.
 \end{itemize}

\section{The cage}\label{cage}

It is useful to be able to copy a small portion of a screen pattern and
move it to some other place on the screen; to prepare a ``rubber
stamp'' with a certain picture and drop copies of this picture in
several places on the screen; to apply commands such as {\sl Zero} and
{\sl Random} only to a limited portion of the screen; etc.\index{Cage}\index{Control-panel commands/cage}

The {\sl cage} is a collection of four mini-buffers\index{Cage/buffers} (one per plane)
that can be used for operations of this kind. The horizontal size and
the vertical size of the cage can be independently specified (in
multiples of eight pixels, and up to a maximum size of 64\by64
pixels). When the cage is active, it is visible as an overlay in the
middle of the screen, on top of the planes.  While the cage is
visible, all operations that take a plane argument apply to the cage:
the cage takes on the role of the screen, and the part of the screen
hidden under it takes on the role of the buffers.  Thus \keyg\ gets an
image into the cage from the middle of the planes, and \keyp\ puts the
image in the cage into the middle of the planes;  \keysemicolon\ puts
randomness into the cage, and rotations and flips will apply to the
cage rather than to the whole screen.

In other words, one may visualize three ``levels'' of storage, namely
$$
\begin{tabular}{|c|}\hline
 cage \\ \hline
 planes \\ \hline
 buffers \\ \hline \end{tabular} 
$$
\noindent and the operations normally defined in terms of the two
bottom levels shift their meaning ``one level up'' when the cage is
active.

\medskip

Since the cage always appears in the middle of the screen, to
``position the cage'' one actually has to move the planes relative to
the cage, using the usual {\sl Shift} and {\sl Hold} commands (which
retain their usual meaning).  The cage is of course used in exactly
the same way in normal or expanded mode---the maximum-sized cage
completely fills the expanded view.

The commands to select the cage are:

\begin{equation}
 \begin{tabular}{|r|p{8cm}|} \hline
  \icp\keyc & {\sl Cage}. Toggle cage mode on or off.
  A numeric argument consisting of one digit in the range 1--8 specifies
the size of the cage (the argument is multiplied by 8); with a two-digit
argument, the first digit denotes the horizontal size, the second digit
the vertical size.  Whenever an argument is given, the previous cage is
discarded and replaced by a brand new one.
 \\ \hline
  \icp\keyC & {\sl Uncage}. Turn off cage mode. \\ \hline
 \end{tabular}
\end{equation}

When the cage is active its outline is shown by four blinking corners.
If the cage is empty (all \id|0|s in each of the four mini-buffers) it
looks ``transparent'' (you can see the \cam\ planes underneath), and a
solid frame with blinking corners indicates its extent.  (The cage's
extent includes the frame itself; the frame is drawn by showing the
plane's bits as complemented.)  On the other hand, if as much as a
single bit in the cage is set (a symptom of this is that the solid frame
disappears) the cage's contents (whether \id|0|s or \id|1|s) will
entirely hide from view the underlying portion of the planes.

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \keyG\targ{sample} to get the pattern \prog{SAMPLE.PAT},
and \narg{46}\keyc\ to activate a cage of horizontal size 32
(=4\by8) and vertical size 48 (=6\by8).  You'll see a hollow
rectangular shape with flashing corners: a new cage is empty, and the
pattern underneath will show through.
  \item Choose a particular feature in the plane pattern, and
use the arrow keys\ to bring it underneath the cage.
  \item Type \keyZ\ to fill the cage; now that feature is hidden
behind the cage.
  \item Use the arrow keys\ to move the planes until the feature
reappears from behind the cage: the \cam\ planes were not affected by
activating the cage or writing something to it.
  \item Type \keyc\ or \keyC\ to deactivate the cage. The cage disappears
from view, but its contents are not lost; type \keyc\ again to get the cage
back on the screen. 
  \item Now type \keyp: the rubber stamp is lowered on the planes
(the normal meaning of \icp\keyp, namely ``put plane to buffer,'' is
modified to ``put cage to plane'') which receive its imprint. Turn off
the cage by typing \icp\keyc: the cage disappears, but its imprint on
the planes remains. In a similar way, by typing \icp\keyg\ in cage mode
you can ``capture'' into the cage a fragment of the planes, creating a new
rubber stamp.
  \item Type \keyz\ to clear the cage---the pattern underneath will
again show through. Shift the pattern by means of the arrow keys, and
capture some interesting piece of it using \keyg.  Use \keyr,
\keybar, \keyunder, etc. to rotate or flip the captured piece.\footnote
    {If the cage is not square, rotations or diagonal reflections acting on all four planes
will affect its {\sl format} as well as its contents (for example,
a quarter-turn will turn a 3\by2 cage into a 2\by3 one); if you try to do that on a single
plane you get an error message.}
    Use this piece as a stamp, making several copies of it in different positions of the bit-planes
by ``lowering'' the stamp with \keyp\ and moving the planes around with the
arrow keys.
  \item Make a smaller cage by typing \narg{2}\keyc\ (this is the
same as typing \narg{22}\keyc); fill the cage
with random data (identical for the four mini-buffers) by typing
\keysemicolon. Now stamp copies of this random template here and there
on the planes. Do the same using a numeric argument for \keyp,
so that only a certain plane will be affected by the rubber stamp.
 \end{itemize}

\section{Logic operations}\label{logical}

\index{Control-panel commands/logic operations}The plane editor provides
commands for performing logic operations between planes and buffers;
these operations are performed in parallel on all the sites of the
array.  For example, \narg{0}\keyampersand\ will replace the contents of
plane 0 with the logic-{\sc and} (see below) of this plane and the
corresponding buffer.  All the logic operations described take two
inputs and return one output: the two inputs are a plane and the
corresponding buffer, and the output is put in the same plane.\footnote
    {In addition to these {\sl dyadic} logic operations, we have
already encountered the {\sl monadic} (``one-input'') operation
\icp\keyminus\ (logic-{\sc not}), which takes a specified plane as input and
puts the result in the same plane, and the 0-adic operations \keyz\
(``set to {\tt 0}'') and \keyZ\ (``set to {\tt 1}''), which take no input and put the
result in a specified plane.}
    As usual, these commands are carried out
on all four planes unless a numeric argument
restricts their application to a single plane or plane-pair:
\keyampersand\ will {\sc and} each of the four buffers
onto the corresponding plane.

\medskip

The commands that perform logic operations are
 \begin{equation}
  \begin{tabular}{|r|p{8cm}|} \hline
   \icp\keyampersand & {\sl And}. Logic-{\sc and} buffer(s) to plane(s). \\ \hline 
   \icp\keyplus & {\sl Or}. Logic-{\sc or} buffer(s) to plane(s).\\ \hline
   \icp\keydollar & {\sl Xor}. Logic-{\sc xor} buffer(s) to plane(s).\\ \hline
  \end{tabular}
 \end{equation}

As a reminder, {\sc and}, {\sc or}, and {\sc xor} are defined
as follows:
 $$
 \begin{array}{c}
  \hbox{\sc and} \\[0.5ex]
  00\mapsto0 \\
  01\mapsto0 \\
  10\mapsto0 \\
  11\mapsto1 
 \end{array},
 \qquad
 \begin{array}{c}
  \hbox{\sc or} \\
  00\mapsto0 \\
  01\mapsto1 \\
  10\mapsto1 \\
  11\mapsto1 
 \end{array},
 \qquad
 \begin{array}{c}
  \hbox{\sc xor} \\
  00\mapsto0 \\
  01\mapsto1 \\
  10\mapsto1 \\
  11\mapsto0 
 \end{array}.
 $$

{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \narg{0}\keyG\targ{circle} to load the pattern
\prog{CIRCLE.PAT} in plane 0, and \narg{0}\keyp\ to save this pattern (a
disk-shaped mask) in buffer 0.  Now type \narg{0}\keysemicolon\ to put
randomness in plane 0.  Finally, type \narg{0}\keyampersand\ to {\sc and}
the buffer with the plane's contents.  The randomness that lies outside
the circle will be ``masked out.''
 \end{itemize}

\section{Disk Read/Write}\label{disk-io}

It is possible to store on a disk file or retrieve from a disk file a
verbatim image of one or more \cam\ bit-planes. We shall call such
files {\sl pattern} files. The default extension for a pattern
file is \iprog{PAT}.
The two basic commands are\index{Control-panel commands/plane saving and loading}
 \begin{equation}
  \begin{tabular}{|r|p{8cm}|} \hline 
   \icp\keyP & {\sl Put to disk}. Save plane(s) to a specified file. Each
plane contributes 8192 bytes to the file. \\ \hline
   \icp\keyG & {\sl Get from disk}. Retrieve plane(s) from a
specified file. \\ \hline
  \end{tabular}
 \end{equation}

\noindent After the command keystroke, the \cp\ prompts
you to type the name of a file. If no extension is given, \iprog{PAT}
is assumed.

With no numeric argument, all four planes are saved or retrieved.
If the command is preceded by a numeric argument,
only the specified planes are affected.

If one tries to read from a file that doesn't have enough data, the
file is ``wrapped around.'' For example, if one tries to read all four
planes from a file that only contains two, the remaining two planes
are read starting again from the beginning of the file.  

\medskip

If the file name contains either `\verb}*}' or `\verb}?}', no data is
transferred.  Instead, the \cp\ prints a directory listing of all disk
files whose names match the given string under the DOS naming
conventions; after this, the \cp\ prompts you again for a file name.
Typing \keyreturn\ without a file name produces a listing of all the
files with extension \iprog{PAT}.  This is handy if you don't remember
what pattern files are present, or the exact name of a
file.\index{Wild-card characters}

If you change your mind, you can (as always) exit the prompt loop
and abort the command by hitting the \icp\keyesc\ key.

\medskip
{\bf \noindent Examples:}
 \begin{itemize}
  \item Type \keyG\targ{sample} to load all four screens
with the contents of the file \prog{SAMPLE.PAT}.
  \item Type \keyz\ to clear all planes.
Type \narg{2}\keyG\targ{sample} to load only plane 2 from
the file \prog{SAMPLE.PAT}, leaving the other three planes clear.
  \item Type \keyP\targ{scrap.tmp} to save all four planes to
file \prog{SCRAP.TMP}.
\item Type \narg{4}\keyP\targ{scrap.tmp} to save planes 0 and 1 to file
\prog{SCRAP.TMP}; the system warns you that you are about to
overwrite an existing file, and gives you a chance to abort the
command (by answering with \prog{n} to the question ``\prog{Overwrite existing
file? (Y/N)}'').
  \item Type \keyG\ \keyreturn\ to have a directory listing of all the files
with extension \prog{PAT}. After that, type the desired
file name, or \keyesc\ to return to the \cp.
 \end{itemize}

\section{Other forms of bit-plane editing}\label{halo}

Bit-plane configurations suitable for a given experiment can of course
be produced in a variety of ways other than through the \cam\ plane
editor.  One way is to generate the desired pattern in a
\pc\ memory buffer, using Forth for this purpose as an ordinary programming
language, and then copy this buffer to a \cam\ plane (see
\prog{BUF>PDAT}\index{BUF.PDAT{\tt BUF>PDAT}} in the glossary).

\medskip

Another possibility, especially for free-hand drawing of more
complex figures, is to use a separate graphics editor and convert
its output to the format of a \cam\ \id|PAT| file.\index{External editors}

For example, the enclosed program \iprog{HALOPAT.EXE} converts output
files generated by ``Doctor Halo II''---a graphics editor that
accompanies the {\sc mouse systems} mouse (Section \ref{dot})---to \id|PAT|
files.\index{Dr.\ Halo} Type
        \begin{verbatim}
  HALOPAT source-file dest-file\end{verbatim}
        The
file names must not include the extensions: the default extension \id|PIC|
is provided for the source file, and \id|PAT| for the destination.
If the second argument is missing, the destination file will have the same name as
the source.

The resolution of ``Doctor Halo II'' is 320\by200 pixels.  As \cam\ bit-planes are
256\by256, only the leftmost portion of the Dr.\ Halo picture is converted, and the
last 56 lines are left empty.  To avoid losing the portion of the picture located
under the Dr.\ Halo menus, move them to the upper-right position of the screen (as
explained in the Dr.\ Halo manual).
