GreDeviceCreateBitmap

From EDM2
Jump to: navigation, search

GreDeviceCreateBitmap creates a bit map and obtains its handle.

This function must be supported by the presentation driver. GreDeviceCreateBitmap is called from GreCreateBitmap, which is one of the graphics engine internal device support functions.

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

Syntax

GreDeviceCreateBitmap(hdc, pInfoHd, flUsage, pBitmap, pInfo, pInstance, lFunction)

Parameters

hdc (HDC) - input 
Device context handle.
pInfoHd (PBITMAPINFOHEADER) - input 
Pointer to data structure.
Pointer to a BITMAPINFOHEADER or BITMAPINFOHEADER2 data structure that defines the new bit map.
flUsage (ULONG) - input
Additional information used when creating a new bit map. The only valid flag is:
CBM_INIT - When set, the pBitmap and paInfo parameters are used to initialize the newly created bit map. It is assumed that enough data is passed to initialize the whole bit map.
Other flags are reserved and must be ignored by the handling routine.
pBitmap (PBYTE) - input
Pointer to bit-map initialization data.
Pointer to bit-map initialization data, starting on a DWORD-aligned address. 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=NGreDeviceCreateBitmap.

Returns

rc (ULONG) - returns
Return Code.
On completion, the handling routine must return the bit-map handle (hbm), or GPI_ERROR if an error is detected.

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_DEV_FUNC_NOT_INSTALLED
  • PMERR_INSUFFICIENT_MEMORY
  • PMERR_INV_BITMAP_DIMENSION
  • PMERR_INV_HDC
  • 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. */
PBITMAPINFOHEADER   pInfoHd;    /* Pointer to data structure. */
ULONG               flUsage;
PBYTE               pBitmap;    /* Pointer to bit-map initialization data. */
PBITMAPINFO         pInfo;      /* Pointer to BITMAPINFO or BITMAPINFO2 structure. */
PVOID               pInstance;  /* Pointer to instance data. */
ULONG               lFunction;  /* High-order WORD=flags; low-order WORD=NGreDeviceCreateBitmap. */
ULONG               rc;         /* Return Code. */

rc = GreDeviceCreateBitmap(hdc, pInfoHd, flUsage,
       pBitmap, pInfo, pInstance, lFunction);

Remarks

Bit-map size is limited by available memory. The maximum width and height are 64KB. Typically, the following standard bit-map formats are used:

Bitcount Planes
1 1
4 1
8 1
24 1

All presentation drivers must be able to create and use all of the standard formats. However, presentation drivers for two-color devices will lose the color information.

The device context handle supplied to this function must never be NULL, because bit maps always belong to some device. The bit map is created on the device specified and can be selected to a different device later because the graphics engine can handle transfer of bits from one device to the other. When a presentation driver supports only a single color format, requests for other color bit-map formats are mapped to the supported function. No error is returned.