GreGetClipRects


 * Simulation support: This function is simulated by a handling routine in the graphics engine.

GreGetClipRects fills the buffer indicated by parclRect with a list of (X,Y) coordinate pairs specifying the rectangles, which define the DC region and intersect an optional bounding rectangle (prclRect). The DC region is the intersection of the visible region, clip region, viewing limits, graphics field, and clip path.

Clipping, when performed by the graphics engine, carries a heavy processing overhead. For simple clipping, the presentation driver gains a significant performance advantage by calling this function to enumerate the clip region, and clipping the line to each rectangle in turn.

This function can be used to determine if the banding rectangle is inside, outside, or crossing the device's clip rectangle.


 * Note: If COM_TRANSFORM is set, the rectangle points are returned in device coordinates. If COM_TRANSFORM is not set, the rectangle points are returned in screen coordinates.

This function can be hooked by the presentation driver.

Syntax
fSuccess = GreGetClipRects(hdc, prclBound, pControl, parclRect, pInstance, lFunction);

Parameters

 * hdc (HDC) - input
 * Device context handle.


 * prclBound (PRECTL) - input
 * Pointer to bounding rectangle in device or screen coordinates.

Pointer to a RECTL structure:


 * xLeft Minimum X-coordinate of rectangle
 * yBottom Minimum Y-coordinate
 * xRight Maximum X-coordinate of rectangle
 * yTop Maximum Y-coordinate

Only rectangles intersecting this bounding rectangle are returned. When this pointer is NULL, all rectangles in the region are enumerated. When this pointer is not NULL, each rectangle returned is the intersection of the bounding rectangle with a rectangle in the region.

If COM_TRANSFORM is set, the function expects the bounding rectangle to be in device coordinates. If COM_TRANSFORM is not set, the function expects the bounding rectangle to be in screen coordinates.


 * pControl (PRGNRECT) - input
 * Pointer to a control structure containing additional parameters:

lrcStart The rectangle number to start enumerating (1 indicates start at the beginning).

If parclRect is NULL, this field is always 1.

crc The number of rectangles that can fit into the buffer (at least 1).

If parclRect is NULL and the clip region is completely within prclBoundRect, crc contains the value RRGN_INSIDE.

If parclRect is NULL and the clip region is completely outside prclBoundRect, crc contains the value RRGN_OUTSIDE.

If parclRect is NULL and the clip region spans prclBoundRect, crc contains the value RRGN_PARTIAL.

crcReturned Number of rectangles that were written into the buffer. If less than lrcStart, there are no more rectangles to enumerate.

If parclRect is NULL and the clip region is completely within prclBoundRect, crcReturned contains the value 1.

If parclRect is NULL and the clip region is completely outside prclBoundRect, crcReturned contains the value 0.

If parclRect is NULL and the clip region spans prclBoundRect, crcReturned contains the number of clip rectangles.

usDirection The direction in which the rectangles are listed:


 * RECTDIR_LFRT_TOPBOT Left-to-right, top-to-bottom
 * RECTDIR_RTLF_TOPBOT Right-to-left, top-to-bottom
 * RECTDIR_LFRT_BOTTOP Left-to-right, bottom-to-top
 * RECTDIR_RTLF_BOTTOP Right-to-left, bottom-to-top

If parclRect is NULL, usDirection is not applicable.


 * parclRect (PRECTL) - input
 * Pointer to array of rectangle (RECTL) structures.

All rectangles are inclusive on the left and bottom borders, and exclusive on the right and top borders.


 * pInstance (PVOID) - input
 * Pointer to instance data.


 * lFunction (ULONG) - input
 * High-order WORD=flags; low-order WORD=NGreGetClipRects.

Return Code

 * fSuccess (BOOL) - returns
 * Return codes.

This function returns BOOLEAN (fSuccess).
 * TRUE Successful
 * FALSE 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_DEV_FUNC_NOT_INSTALLED
 * PMERR_HDC_BUSY
 * PMERR_INV_COORDINATE
 * PMERR_INV_HDC
 * PMERR_INV_RECT
 * PMERR_INV_REGION_CONTROL

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

Example Code
HDC        hdc;        /*  Device context handle. */ PRECTL     prclBound;  /*  Pointer to bounding rectangle in device or screen coordinates. */ PRGNRECT   pControl;   /*  Pointer to a control structure containing additional parameters: */ PRECTL     parclRect;  /*  Pointer to array of rectangle (RECTL) structures. */ PVOID      pInstance;  /*  Pointer to instance data. */ ULONG      lFunction;  /*  High-order WORD=flags; low-order WORD=NGreGetClipRects. */ BOOL       fSuccess;   /*  Return codes. */ fSuccess = GreGetClipRects(hdc, prclBound, pControl, parclRect, pInstance, lFunction);
 * 1) define INCL_GRE_CLIP
 * 2) include 