GrePolyScanline

GrePolyScanline fills an area lying between polyshortline pairs by using the current pattern attribute.

This function must be supported by all presentation drivers except those that hook the GreDrawRLE, GreEndArea, and GreFillPath functions. All function calls to GrePolyScanline come from the GreDrawRLE, GreEndArea, or GreFillPath handling routines in the graphics engine. GrePolyScanline is not called by any specific function. However, it is likely to be accessed by any area-filling functions.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GrePolyScanline(hdc, pScanData, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

pScanData (PSCANDATA) - input

Pointer to a SCANDATA structure:

• pslFirstLeft Pointer to the left end of the first polyshortline
• pslLastLeft Pointer the left end of the last polyshortline
• pslFirstRight Pointer to right edge of first polyshortline
• pslLastRight Pointer to right edge of last polyshortline
• c Number of scan lines
• rclBound RECTL structure defining the bounding rectangle

Notice that a polyshortline consists of a list of linked SHORTLINE structures:

slh SHORTLINEHEADER structure:

• ulStyle Line style
• ulFormat Line format
• ptlStart (X,Y) position of start
• ptlStop (X,Y) position of end
• lxLeft Left edge of bounding rectangle
• lxRight Right edge of bounding rectangle
• pslhNext Pointer to next shortline
• pslhPrev Pointer to previous shortline

This structure is a discrete representation of a curve that starts at point (x0,y0) and ends at point (x1,y1). For each of the (y1-y0+1) rows, there is exactly one X value contained in the X array. The final point in the series is not drawn.

ax Array of X values as screen coordinates.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGrePolyScanline.

Return Code

rc (LONG) - returns

Return Code.

On completion, the handling routine must return an integer (cHits) indicating, where appropriate, whether correlation hits were detected:

• GPI_OK Successful
• GPI_HITS Successful with correlate hit (returned by display drivers when the correlate flag is ON, and a hit is detected)
• GPI_ERROR Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

• PMERR_BITMAP_NOT_SELECTED
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_HDC_BUSY
• PMERR_INV_COLOR_DATA
• PMERR_INV_COLOR_INDEX
• PMERR_INV_COORD_SPACE
• PMERR_INV_COORDINATE
• PMERR_INV_HDC
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_PICK_APERTURE_POSN
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

The calling function uses the driver's CAPS_ADDITIONAL_GRAPHICS / CAPS_CLIP_FILLS field, which is queried during the first instance of DevOpenDC. If it is set, the data delivered to GrePolyScanline has already been clipped and the COM_PRECLIP flag will be set in the flags WORD of the function number; otherwise, they will be passed as unclipped screen coordinates. Filling is inclusive at the left boundaries and exclusive at the right boundaries. The scan lines are ordered from bottom to top and from left to right.

The handling routine can assume that the two polyshortlines do not cross and both polyshortlines have the same height.

Declaration

#define INCL_GRE_SCANS
#include <os2.h>

HDC          hdc;        /*  Device context handle. */
PSCANDATA    pScanData;  /*  Pointer to a SCANDATA structure. */
PVOID        pInstance;  /*  Pointer to instance data. */
ULONG        lFunction;  /*  High-order WORD=flags; low-order WORD=NGrePolyScanline. */
LONG         rc;         /*  Return Code. */

rc = GrePolyScanline(hdc, pScanData, pInstance, lFunction);