FILL.BIN - a fast and flexible Spectrum program to draw filled shapes.

The file FILL.BIN is a 3294-byte CODE file (supplied as raw data with no
header).  It may be loaded in at any address, which will be written "fill",
as in:

  LOAD "FILL.BIN" CODE fill .

To try out the program, try this:

  10 PRINT USR fill
  20 CIRCLE 128,88,50
  30 CONTINUE

A filled circle should appear on the screen.

A typical use of the fill program looks like this:

   PRINT USR fill
   <draw a shape>
   CONTINUE .

In this way, the program is able to learn the border of the shape without
actually drawing it on the screen.  This makes the fill much faster than
an ordinary "flood fill".  Almost any BASIC instruction is allowed within
the code that draws the shape, but note that PLOT is equivalent to a MOVE
instruction and does not actually plot a pixel.  Although the end points
of all lines and curves must be on the screen, it is possible for curves
and circles to be partially off the screen.  For example, "CIRCLE 5,5,10"
will be allowed and will produce a circle with slices cut off the side and
bottom.

When the CONTINUE instruction is reached, the program draws the requested
filled shape if it can and then the BASIC program continues normally.  The
areas which will be filled are precisely those about which the given path
has an odd winding number.  Another way of putting this is the following.
Take any point and draw a straight line away from that point until it is
well away from the shape.  If that line crosses the shape an odd number
of times, then the point will be filled, and otherwise it will not be
filled.

If the shape is not closed, then one of two things will happen.  If it can,
the program will add a single straight line to close the shape and then fill
it.  Otherwise, the program will refuse to fill the shape.  For example:

   PRINT USR fill                       PRINT USR FILL
   PLOT 30,50: DRAW 20,0                PLOT 30,50: DRAW 20,0
   PLOT 50,30: DRAW 0,20                PLOT 50,20: DRAW 0,20
   CONTINUE                             CONTINUE
   REM this program draw a triangle     REM this program draws nothing

It is possible to find out whether the program filled a shape or not by
testing the value of the variable "rc" after the CONTINUE instruction.
If rc<0 then nothing was drawn.  A more detailed description of rc appears
later.

The fill program can also draw patterned fills with or without a border.
The extra information is supplied on the USR instruction, for example:

   PRINT USR fill;"@0"; INK 5

(which will fill the shape in cyan with "@" signs and not draw a border).
The parameters which are allowed on the USR instruction are (in any
order):

   the fill pattern
   whether a border is required
   the INK/PAPER/BRIGHT/FLASH/OVER attributes.

The fill pattern can be any single printable character (including graphics)
or a pre-defined pattern.  The pre-defined patterns are accessed by typing
CHR$ x, where x<16.  If the pattern is not given, it defaults to CHR$ 0. The
16 patterns are arranged as follows:

   0-8  patterns of decreasing density, from solid down to one pixel in 64
     9  vertical lines
    10  horizontal lines
    11  45-degree diagonal lines going from bottom left to top right
    12  30-degree diagonal lines going from bottom left to top right
    13  45-degree diagonal lines going from top left to bottom right
    14  30-degree diagonal lines going from top left to bottom right
    15  blank.

A border is usually drawn, and will also be drawn if the character "1" is
given in the parameters.  If the character "0" is given, then a border
will not be drawn.  Note: in order to use either of the characters "0"
or "1" as a fill pattern, you must specify the border first.  The first
occurrence of "0" or "1" will be taken as the border specifier, and the
second occurrence will be taken as a fill pattern.

The attributes (that is, INK, PAPER, BRIGHT and FLASH) will normally be
taken from the permanent attributes which are in force at the time when the
USR instruction is reached, except that PAPER 8 will normally be used.  They
may be given on the USR instruction, or they may appear within the code that
draws the pattern.  Any instruction which contains colours such as

    PRINT INK 6;
or  PLOT PAPER 5;128,88
or  BRIGHT 0

will change the colour of the filled shape.  The final colour will be that
which was specified last while the shape was being drawn.  Note that the
whole shape will only be in one colour, even if several colour instructions
appeared in the program.

The OVER attribute is special.  It may only be placed on the USR
instruction; any other OVER commands are ignored.  The parameter may
be 0, 1, 2 or 3, with the default being 0. Their meanings are:

     0  overpaint mode
     1  OR mode
     2  XOR mode (similar to the Spectrum's "OVER 1")
     3  erase mode.

In overpaint mode, any pixel falling within the shape will be plotted or
unplotted according to whether the fill pattern has "ink" or "paper" in
that position, thus obliterating anything on the screen that falls under
the shape.  In the other three modes only the "ink" pixels matter, while
the screen is left alone in places where the fill pattern has "paper".  In
OR mode, the "ink" pixels are plotted, while in XOR mode they are changed
(pixels that are already plotted will be unplotted, and pixels that are not
plotted will be plotted), and in erase mode they are unplotted.

Errors that occur while the parameters are being interpreted will be treated
as minor errors, and the shape will be filled with some default parameters.
Errors that occur while the shape is being drawn will be treated as major
errors, and the shape will not be drawn.  As long as BASIC does not report
some error (such as "Integer out of range" which occurs when the end point
of a line is off the screen), the program will set rc (which stands for
"return code") to indicate what sort of an error occurred.  A return code of
zero indicates that the fill completed successfully.  A positive return code
indicates that a minor error occurred, and a negative return code indicates
that a major error occurred.  The possible return codes are:

   -2  The shape was too complex (a maximum of 255 lines or curves is
       allowed.  Each circle counts as two curves).
   -1  The shape was not closed and could not be closed by a single line.
    0  The shape was filled successfully.
    1  More than one fill pattern was found.
    2  An invalid character (such as one with code >=165) was found in the
       parameters.
    3  The value given for OVER was out of range.

BUGS

The program cannot draw any curve whose radius of curvature is greater than
255, and approximates such curves with straight lines.

AUTHOR

Ian Collier <imc@comlab.oxford.ox.ac.uk>