GpiFloodFill

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

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 colour devaldesc.
• FF_SURFACE Fills while on the specified colour.

lColor (LONG) - input

Colour.

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

This is either a logical colour index, or an RGB value, depending on the state of the colour 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 colour 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 colour was the same as the input colour when a boundary fill was requested, or the starting point colour was not the same as the input colour when a surface fill was requested.

Remarks

The seed point is the 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 colour, the individual colour 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 colour, or while on a given colour. The example assumes the colour table is in index mode; it fills up to the boundary where the colour 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