GreDeviceInvalidateVisRegion

GreDeviceInvalidateVisRegion notifies the presentation driver that the visible region and DC region of one or more DCs has changed, and that the affected DCs must revalidate their visible regions before drawing in them.

Simulation support: This function is mandatory for display drivers. For other drivers, it is simulated by a handling routine in the graphics engine.

Syntax

GreDeviceInvalidateVisRegion(hdc, cArray, paBlock, pInstance, lFunction)

Parameters

hdc (HDC) - input

The device context handle.

cArray (LONG) - input

The number of elements in the array.

paBlock (PDC_BLOCK) - input

A pointer to an array of DC_BLOCK structures:

hdc A device context handle.

pDcI A pointer to instance data.

pInstance (PVOID) - input: A pointer to instance data.
lFunction (ULONG) - input: High-order WORD=flags; low-order WORD=NGreDeath.

Returns

fSuccess (BOOL) - returns

Return codes.

On completion, the handling routine must return BOOLEAN (fSuccess).

TRUE Successful
FALSE Error

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

PMERR_DEV_FUNC_NOT_INSTALLED

Sample

#define INCL_GRE_DEVMISC2
#include <os2.h>

HDC          hdc;        /*  The device context handle. */
LONG         cArray;     /*  The number of elements in the array. */
PDC_BLOCK    paBlock;
PVOID        pInstance;  /*  A pointer to instance data. */
ULONG        lFunction;  /*  High-order WORD=flags; low-order WORD=NGreDeath. */
BOOL         fSuccess;   /*  Return codes. */

fSuccess = GreDeviceInvalidateVisRegion(hdc,
             cArray, paBlock, pInstance, lFunction);

Remarks

The array identified by paBlock contains a series of structures, each of which identifies a DC and supplies the pointer (pInstance) to its instance data. The display driver responds by setting a flag (HDC_IS_DIRTY) in the instance data of each DC identified in the array. The handling routines for all drawing functions should check the HDC_IS_DIRTY flag before drawing. If the flag is set, VisRegionNotify must be called to revalidate the DC's visible region.

This function allows the system to defer the calculations caused by visible region changes. This enables menus and dialogs to perform more efficiently.