| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: stream position &key border-color
Changes an arbitrary contiguous set of pixels of stream to the current foreground-color of stream, by starting at the pixel specified by position and changing the color of that pixel and its immediately neighboring pixels (vertical and horizontal only) when their current colors meet certain criteria. Whenever a pixel is changed, additional branches of the search consider that pixel's immediate neighbors as well. The activity stops only when every branch of the search either has encountered a pixel that should not change color or has already been considered, or has gone off the edge of the stream or its current clipping-box.
If border-color is nil
(which is the default), then only pixels that are the same color as
the pixel at position are changed. Intuitively,
the area that is currently a single color and includes the pixel at
position is changed to the current foreground-color of the
stream. If the pixel at position is already the
current foreground, then nothing is done.
If border-color is instead an RGB color object (see make-rgb), then all pixels except those that are the specified border color are changed. Intuitively, this fills an area that is completely surrounded by the border color and contains the pixel at position, if there is such a boundary, and otherwise changes all of the stream's pixels except those that are of the border color (or in areas bounded by the border color) to the foreground color.
Use with-foreground-color around a call to flood-fill to change the pixels to some arbitrary color.
position should be a position (see make-position).
stream
should be a cg-stream
.
For streams other than bitmap-pane
s, nothing will be done
if the initial position is not currently visible or is otherwise
outside of the stream's current clipping-box, and filling will
never proceed through an area that is clipped to continue on another
visible area of the window. This is not an issue when filling a
bitmap-pane
,
bitmap-stream
,
printer
, or
the screen unless an explicit clipping-box has been set.
(Drawing on the screen requires a with-device-context wrapper.)
Note that this Common Graphics function directly calls a function
supplied by the operating system, and Common Graphics has no control
over the subtle choices in the implementation of this algorithm. In
Windows, this function is ExtFloodFill
. The
documentation for this function implies that there may be cases where
the operation will not complete, which are possibly due to the stack
being depleted by a huge fill. Also, one small difference with the
Common Graphics function is that when no boundary color is specified,
flood-fill always
uses the current color of the pixel at position
as the color to change, rather than requiring that the application
specify this color and then doing nothing if a different color is
specified.
This function is not implemented on the GTK platform. It is probably
not feasible to implement it in Common Graphics without a GTK hook
into the display adapter's functionality for doing the drawing with
adequate speed. Calling the function on GTK will simply invoke
the *gtk-compatibility-warning-action*
.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |