flood-fill

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-panes, 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.

GTK Note

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.