Clipping (Justin Fletcher, 20 Jul 2000)
========

The clipping implemented in Draw has for a very long time been restricted to
that of the graphics window. As an experiment, I've added clipping of one
path against another. This is very experimental code. It is, in the default
build, disabled - if you want it you MUST turn it on (file Version, option
ClippedFills needs setting to TRUE).


Principles
----------
Draw works by flattening a path from curves into lots of short lines. This
new path is then scanned for horizontal lines which can be plotted to the
screen. These are placed in an array and plotted using the hline routine
(from OS_ReadVduVariables) - ie no code actually writes to the screen in
Draw.

In an ideal world, the clipping code would take two paths and clip them
against one another to generate a further path that would be the one that
was plotted. This is not the way that clipping has been implemented.

For clipped paths, the clipping path is passed to the processor and scan
lines that would be plotted are 'remembered'. The main path is then passed
to the processor and only those scan lines which fall within the entries in
the array are actually plotted. This is very inefficient. Some of the
optimisations that could be applied to this, such as sorting the list are
not fully implemented.

Bugs
----
There is a bug in Draw in that it will pass in a large x coordinates to the
hline routine - something like RMA pointers accidentally. These are
'potentially' safe whilst RMA is in high memory, but if it ever moves to a
point that the screen x coordinates lives in, then it will need fixing.

API
---
To make clipping a number of regions simple, and because of the lack of
registers passed into the SWI call, the clipping path is described in a
description block :
  +0 pointer to path to clip against
  +4 fill style for path
  +8 pointer to transformation matrix, or 0 for identity

SWI Draw_FillClipped
 => R0 = pointer to path to plot
    R1 = fill style for path to plot, or 0 for default
    R2 = pointer to transformation matrix for path to plot, or 0 for identity
    R3 = flatness
    R4 = pointer to clip description block

Fill the path specified, clipping it against the clip description block (3
word block describing the clipping area).


SWI Draw_StrokeClipped
 => R0 = pointer to path to plot
    R1 = fill style for path to plot
    R2 = pointer to transformation matrix for path to plot, or 0 for identity
    R3 = flatness
    R4 = thickness
    R5 = pointer to join/cap block
    R6 = pointer to dashing pattern, or 0 for default
    R7 = pointer to clip description block

Stroke (draw the outline) of the specified, clipping it against the clip
description block (3 word block describing the clipping area).
