GreSetBitmapBits

From EDM2
Jump to: navigation, search

GreSetBitmapBits transfers bit-map data from application storage into the specified bit map or DC.

This function must be supported by the presentation driver. GreSetBitmapBits is called from the function GpiSetBitmapBits, and is used to transfer bit-map data from the device context to application storage. This function can be handled by bit-map simulation.

Simulation support
None. This function is mandatory for all drivers.

Syntax

GreSetBitmapBits(hdc, hbm, lScanStart, cScanCount, pBitmap, pInfo, pInstance, lFunction)

Parameters

hdc (HDC) - input
Device context handle.
hbm (HBITMAP) - input
Bit-map handle.
lScanStart (LONG) - input
Scan line number from where data transfer starts.
0 is the first.
cScanCount (LONG) - input
Number of scan lines to be transferred.
pBitmap (PBYTE) - input 
Pointer to bit-map data.
Pointer to the pel data of the bit map. This data is stored in the order that the coordinates appear on a display screen, that is, the pel in the lower-left corner is the first in the bit map. Pels are scanned to the right and upward from that position. The bits of the first pel are stored beginning with the most significant bits of the first byte. The data for pels in each scan line is packed together tightly. However, all scan lines are padded at the end so that each one begins on a ULONG boundary. That is, three bytes of pel data will hold one 24-bit pel, three 8-bit pels, six 4-bit pels, or twenty-four 1-bit pels. If those three bytes are the only pel data for that scan line, one more byte of zeros would be required to pad the line to a ULONG boundary.
pInfo (PBITMAPINFO) - input
Pointer to BITMAPINFO or BITMAPINFO2 structure.
pInstance (PVOID) - input
Pointer to instance data.
lFunction (ULONG) - input
High-order WORD=flags; low-order WORD=NGreSetBitmapBits.

Returns

rc (LONG) - returns 
Return codes.
On completion, the handling routine must return a LONG value (lLines), indicating the number of lines transferred, or GPI_ALTERROR if an error occurred.

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_BITMAP_NOT_SELECTED
  • PMERR_DEV_FUNC_NOT_INSTALLED
  • PMERR_INCORRECT_DC_TYPE
  • PMERR_INV_HBITMAP
  • PMERR_INV_IN_AREA
  • PMERR_INV_IN_PATH
  • PMERR_INV_INFO_TABLE
  • PMERR_INV_LENGTH_OR_COUNT
  • PMERR_INV_SCAN_START

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

Sample

#define INCL_GRE_BITMAPS
#include <os2.h>

HDC            hdc;         /*  Device context handle. */
HBITMAP        hbm;         /*  Bit-map handle. */
LONG           lScanStart;  /*  Scan line number from where data transfer starts. */
LONG           cScanCount;  /*  Number of scan lines to be transferred. */
PBYTE          pBitmap;     /*  Pointer to bit-map data. */
PBITMAPINFO    pInfo;       /*  Pointer to BITMAPINFO or BITMAPINFO2 structure. */
PVOID          pInstance;   /*  Pointer to instance data. */
ULONG          lFunction;   /*  High-order WORD=flags; low-order WORD=NGreSetBitmapBits. */
LONG           rc;          /*  Return codes. */

rc = GreSetBitmapBits(hdc, hbm, lScanStart,
       cScanCount, pBitmap, pInfo, pInstance,
       lFunction);

Remarks

When the bit-map handle is NULL, the DC must be a memory DC with a bit map currently selected. Otherwise, the DC must be valid for that device. When the format of the supplied bit map does not match that of the device, the handling routine must use the supplied BITMAPINFO or BITMAPINFO2 structure to convert it. Only standard formats and device formats that are compatible with the target device are supported.