GreOpenScreenChangeArea

GreOpenScreenChangeArea allocates a data area internal to the display driver, in which the driver will accumulate screen changes. The function returns a 32-bit handle that is required to identify the area in GreGetScreenChangeArea and GreCloseScreenChangeArea calls.

Simulation support: This function is mandatory for display drivers that want to be DCAF-enabled.

Syntax

GreOpenScreenChangeArea(hdc, pdcArg, FunN);

Parameters

hdc (HDC) - input: Any device context handle.

pdcArg (PDC) - input: Pointer to instance data.

FunN (ULONG) - input: High-order word=Flags; Low-order word=NGreOpenScreenChangeArea.

Returns

rc (LONG) - returns: This function returns one of the following:

hsca The handle of the new screen change area (SCA).

GPI_ERROR There was no memory available. The memory allocation failure will have been logged by the memory allocation routine.

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_INV_HDC
PMERR_MEMORY_ALLOCATION_ERR

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

Sample

#define INCL_GRE_SCREEN
#include <os2.h>
#include <pmddi.h>

HDC      hdc;     /*  Any device context handle. */
PDC      pdcArg;  /*  Pointer to instance data. */
ULONG    FunN;    /*  High-order word=Flags; Low-order word=NGreOpenScreenChangeArea. */
LONG     rc;

rc = GreOpenScreenChangeArea(hdc, pdcArg,
       FunN);

Remarks

It is permissible to implement this function by returning 0 (zero) to indicate that the bits were not saved and, therefore, must be saved by the calling routine.

If EnterDriver is successful, GreOpenScreenChangeArea attempts to create a new SCA instance by calling AllocateMemory, a common routine in MEMMAN.C. The new SCA gets initialized to NULL and is added to the SCA linked list.

If the creation is successful and this is the first SCA to be opened, GreSetProcessControl is used to tell the graphics engine to turn on the COM_SCR_BOUND flag and start accumulating screen bounds. Setting this bit causes subsequent screen drawing functions to accumulate the clipped bounds into the active SCAs.

If there is not enough memory to create the SCA, PMERR_MEMORY_ALLOCATION_ERROR is logged and GPI_ERROR is returned.

Before returning either the handle of the new SCA or GPI_ERROR, ExitDriver is called.