How to use it:
create a state with make-state, or reuse a previous state by calling state-reset on it.
call line-f (or line) to draw each line of one or several closed polygons. It is very important to close them to get a coherent result. Note that nothing is really drawn at this stage (not until the call to cells-sweep.)
finally, call cells-sweep to let it call your own function for each pixels covered by the polygon(s), where the callback function take 3 arguments: x, y, alpha. Pixels are scanned on increasing y, then on increasing x. Optionnaly, cells-sweep can take another callback function as parameter. See its documentation for details.
The alpha value passed to the callback function can be used in various way. Usually you want:
(defun normalize-alpha (alpha) (min 255 (abs alpha)))
to get a normalized alpha value between 0 and 255. But you may also be interested by:
(defun even-odd-alpha (alpha)
(let ((value (mod alpha 512)))
(min 255 (if (< value 256) value (- 512 value)))))
to simulate "even/odd" fill. You can also use the alpha value to render polygons without anti-aliasing by using:
(defun bool-alpha (value) (if (>= (abs value) 128) 255 0))
or, for "even/odd" fill:
(defun bool-even-odd-alpha (value) (if (<= 128 (mod (abs value) 256) 384) 255 0))
But the value can be used in more creative way. You have to understand how the algorithm works for that. I've attempted to explain it later in this documentation.
Note: Drawing direction (clockwise or counter-clockwise) is only important if polygons overlap during a single state. Opposite directions produce hole at the intersection (coverage is canceled), while identical directions does not (coverage overflow.)
Update: The protocol was extended, without breaking compatibility with actual protocol, in the following ways:
calling freeze-state return a list of scanline (a scanline is an object describing a whole line covered by the polygon)
it is possible to get the Y coordinate of each scanlines with scanline-y and to sweep the whole scanline or only a part with scanline-sweep.
it is possible to render only a rectangular region with cells-sweep/rectangle which take advantage of the previously described functions.
Function MAKE-STATE
Syntax:
make-state => state
Arguments and Values:
state -- an aa state
Description:
Create a new empty aa state.
Function STATE-RESET
Syntax:
state-reset state
Arguments and Values:
state -- an aa state
Description:
Reset the state.
Function LINE
Syntax:
line state x1 y1 x2 y2
Arguments and Values:
state -- an aa state
x1 -- an integer
y1 -- an integer
x2 -- an integer
y2 -- an integer
Description:
(..)
Function LINE-F
Syntax:
line-f state x1 y1 x2 y2
Arguments and Values:
state -- an aa state
x1 -- a real number
y1 -- a real number
x2 -- a real number
y2 -- a real number
Description:
(..)
Function FREEZE-STATE
Syntax:
freeze-state state => scanlines
Arguments and Values:
state -- an aa state
scanlines -- a list of scanline
Description:
New in 0.1.3.
Return a list of scanlines. A scanline is an opaque data structure that can be passed as argument to scanline-y and scanline-sweep. (Actually, internally it is a list of cell, but you should not rely on that.)
Function SCANLINE-Y
Syntax:
scanline-y scanline => y
Arguments and Values:
scanline -- a scanline
y -- an integer
Description:
New in 0.1.3.
Return the Y coordinate of the given scanline.
Function SCANLINE-SWEEP
Syntax:
scanline-sweep scanline function function-span &key start end
Arguments and Values:
scanline -- a scanline
function -- a function designator
function-span -- NIL or a function designator
start -- NIL or an integer
end -- NIL or an integer
Description:
Call function for each pixel covered by the polygon at the line corresponding to the scanline, for all x between start (if specified) and end (if specified.) A nil value for start or end mean no corresponding limit.
function-span (if provided) is called for each span of pixels with identical alpha.
Function CELLS-SWEEP/RECTANGLE
Syntax:
cells-sweep/rectangle state x1 y1 x2 y2 function &optional function-span
Arguments and Values:
state -- an aa state
x1 -- an integer
y1 -- an integer
x2 -- an integer
y2 -- an integer
function -- a function designator
function-span -- NIL or a function designator
Description:
Like cells-sweep but limited to the rectangular region (x1,y1)-(x2,y2) (where (x1,y1) is the upper left corner, and (x2,y2) is the bottow right corner.)
Function CELLS-SWEEP
Syntax:
cells-sweep state function &optional function-span
Arguments and Values:
state -- an aa state
function -- a function designator
function-span -- NIL or a function designator
Description:
Functions signatures: function x y alpha and function-span x1 x2 y alpha.
Call function for each pixel covered by the polygon described earlier with line or line-f. The function-span argument, if not null, will be called for each span of identical pixels in a row.