GpiFloodFill

This function fills an area bounded by a given color, or while on a given color.

Syntax

GpiFloodFill(hps, lOptions, lColor)

Parameters

hps (HPS) - input

Presentation-space handle.

lOptions (LONG) - input

Flood fill options.

This parameter can have one of the following values:

• FF_BOUNDARY Fills up to the specified color devaldesc.
• FF_SURFACE Fills while on the specified color.

lColor (LONG) - input

Color.

The boundary or surface color, depending on the value of lOptions.

This is either a logical color index, or an RGB value, depending on the state of the color table.

Return Code

lHits (LONG) - returns

Correlation and error indicators.

• GPI_OK Successful
• GPI_HITS Correlate hits
• GPI_ERROR Error.

Errors

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F)

An invalid presentation-space handle was specified.

PMERR_PS_BUSY (0x20F4)

An attempt was made to access the presentation space from more than one thread simultaneously.

PMERR_FUNCTION_NOT_SUPPORTED (0x1641)

The function is not supported.

PMERR_INV_FLOOD_FILL_OPTIONS (0x210D)

Invalid flood fill parameters were specified.

PMERR_INV_IN_AREA (0x2085)

An attempt was made to issue a function invalid inside an area bracket. This can be detected while the actual drawing mode is draw or draw-and-retain or during segment drawing or correlation functions.

PMERR_INV_IN_PATH (0x208B)

An attempt was made to issue a function invalid inside a path bracket.

PMERR_INV_COLOR_ATTR (0x2053)

An invalid color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask.

PMERR_INSUFFICIENT_MEMORY (0x203E)

The operation terminated through insufficient memory.

PMERR_START_POINT_CLIPPED (0x2113)

The starting point specified for flood fill is outside the current clipping path or region.

PMERR_NO_FILL (0x2114)

No flood fill occurred because either the starting point color was the same as the input color when a boundary fill was requested, or the starting point color was not the same as the input color when a surface fill was requested.

Remarks

The seed point is current position, which is unchanged by this function.

The area attributes define the fill.

DevQueryCaps (CAPS_RASTER_FLOOD_FILL) indicates whether GpiFloodFill is supported on any particular device. The results produced by this function are highly device-dependent.

When the drawing mode is draw, if the presentation space is partially obscured by an overlying window an incorrect fill can result. You can get correct results if your application is in the foreground and no windows or dialogs owned by your application are visible during flood-fill operations.

When filling over a pattern or a dithered color, the individual color of each pel is taken into account.

Note: This function must not be used when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

Example Code

This function uses GpiFloodFill to fill an area bounded by a given color, or while on a given color. The example assumes the color table is in index mode; it fills up to the boundary where the color represented by index 1 appears.

#define INCL_GPIBITMAPS /* Bit map functions */
#include <os2.h>

LONG     lHits;      /* correlation/error indicator */
HPS      hps;        /* Presentation-space handle */
LONG     lOptions;   /* flood fill options */
LONG     lColor;     /* color */

/* fill up to the boundaries of the color */
lOptions = FF_BOUNDARY;

/* use color corresponding to index 1 */
lColor = 1;

lHits = GpiFloodFill(hps, lOptions, lColor);

Related Functions

• GpiBeginArea
• GpiBeginPath
• GpiFillPath
• GpiSetPel