GreRestoreScreenBits

GreRestoreScreenBits restores a rectangle of bits to a screen rectangle and can also free the handle of the saved bits.

Simulation support

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

Syntax

GreRestoreScreenBits(hdc, hsbBits, prclRect, flOptions, pInstance, lFunction)

Parameters

hdc (HDC) - input

The device context handle.

hsbBits (ULONG) - input

The handle to screen bits to be restored.

prclRect (PRECTL) - input

A pointer to a screen rectangle defined in screen coordinates.

flOptions (ULONG) - input

Option flags, valid values are:

• RSB_FREE 1 (free the save bits handle)
• RSB_RESTORE 2 (restore the bits to the screen)

pInstance (PVOID) - input

A pointer to instance data.

lFunction (ULONG) - input

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

Return Code

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. Error codes for conditions that the handling routine is expected to check include:

• PMERR_BASE_ERROR
• PMERR_BITMAP_IS_SELECTED
• PMERR_BITMAP_NOT_SELECTED
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_HBITMAP_BUSY
• PMERR_HDC_BUSY
• PMERR_HUGE_FONTS_NOT_SUPPORTED
• PMERR_INCOMPATIBLE_BITMAP
• PMERR_INCORRECT_DC_TYPE
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_BACKGROUND_COL_ATTR
• PMERR_INV_BACKGROUND_MIX_ATTR
• PMERR_INV_BITBLT_MIX
• PMERR_INV_BITBLT_STYLE
• PMERR_INV_BITMAP_DIMENSION
• PMERR_INV_CHAR_DIRECTION_ATTR
• PMERR_INV_CHAR_MODE_ATTR
• PMERR_INV_CHAR_SET_ATTR
• PMERR_INV_CHAR_SHEAR_ATTR
• PMERR_INV_CODEPAGE
• PMERR_INV_COLOR_ATTR
• PMERR_INV_COLOR_DATA
• PMERR_INV_COLOR_FORMAT
• PMERR_INV_COLOR_INDEX
• PMERR_INV_COLOR_OPTIONS
• PMERR_INV_COLOR_START_INDEX
• PMERR_INV_COORD_SPACE
• PMERR_INV_COORDINATE
• PMERR_INV_DC_DATA
• PMERR_INV_DC_TYPE
• PMERR_INV_DRIVER_NAME
• PMERR_INV_GEOM_LINE_WIDTH_ATTR
• PMERR_INV_HBITMAP
• PMERR_INV_HDC
• PMERR_INV_HRGN
• PMERR_INV_ID
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_INFO_TABLE
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_LINE_END_ATTR
• PMERR_INV_LINE_JOIN_ATTR
• PMERR_INV_LINE_TYPE_ATTR
• PMERR_INV_LINE_WIDTH_ATTR
• PMERR_INV_MARKER_SET_ATTR
• PMERR_INV_MARKER_SYMBOL_ATTR
• PMERR_INV_MIX_ATTR
• PMERR_INV_PATTERN_REF_PT_ATTR
• PMERR_INV_PATTERN_SET_ATTR
• PMERR_INV_PATTERN_SET_FONT
• PMERR_INV_PICK_APERTURE_POSN
• PMERR_INV_PRIMITIVE_TYPE
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL
• PMERR_INV_SCAN_START
• PMERR_INV_SETID
• PMERR_INV_USAGE_PARM
• PMERR_REALIZE_NOT_SUPPORTED
• PMERR_UNSUPPORTED_ATTR
• PMERR_UNSUPPORTED_ATTR_VALUE

Remarks

Clipping is done on the restored bits, as necessary.

Sample Code

#define INCL_GRE_BITMAPS
#include <os2.h>

HDC       hdc;        /*  The device context handle. */
ULONG     hsbBits;    /*  The handle to screen bits to be restored. */
PRECTL    prclRect;
ULONG     flOptions;
PVOID     pInstance;  /*  A pointer to instance data. */
ULONG     lFunction;
BOOL      fSuccess;   /*  Return codes. */

fSuccess = GreRestoreScreenBits(hdc, hsbBits,
             prclRect, flOptions, pInstance, lFunction);