DrvSaveScreenBits

ULONG DrvSaveScreenBits(

IN SURFOBJ *pso,
IN ULONG iMode,
IN ULONG ident,
IN RECTL *prcl
);

DrvSaveScreenBits causes a display driver to save or restore a given rectangle of the displayed image.

Parameters

pso

Points to a SURFOBJ structure that describes the surface.

iMode

Specifies the operation to perform. The iMode parameter can be one of the following values:

Value	Meaning
SS_SAVE	Saves data from the rectangle defined by prcl. The driver is responsible for managing this data in its off-screen memory. An identifier is returned that identifies this saved data. (The driver can return a handle or even a pointer to its off-screen memory.) The ident parameter is ignored. The return value is an identifier, which can be a handle or a pointer, if the function is successful. Otherwise, it is zero.
SS_RESTORE	Restores the data identified by ident to the rectangle prcl on the display. The driver can assume that the rectangle at prcl has exactly the same size as the rectangle that was saved. The data should be discarded after this call. The return value is TRUE if the data has been restored to the display, or FALSE if the data cannot be restored.
SS_FREE	Indicates that the data identified by ident is no longer needed and can be freed. The rectangle at prcl has the same size as the rectangle that was saved. The return value is TRUE.

ident

Specifies an identifier returned by a previous call to DrvSaveScreenBits, if iMode is SS_RESTORE or SS_FREE. Otherwise, this parameter is ignored.

prcl

Points to a RECTL structure that defines the portion of the screen to be saved or restored.

Return Value

The return value is dependent on the value of the iMode parameter.

Comments

Some display drivers might be able to move data to or from off-screen device memory much faster than the area can be redrawn. This might be useful when the window manager must display a menu or dialog box.

DrvSaveScreenBits is optional for graphics drivers.

See Also

SURFOBJ