GreDeviceCreateBitmap
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.
Contents
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.