GreDeviceCreateBitmap: Difference between revisions

Latest revision as of 02:10, 24 March 2020

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.

@@ Line 1: / Line 1: @@
 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.
+;Simulation support: None. This function is mandatory for all drivers.
 == Syntax ==
-  GreDeviceCreateBitmap(hdc, pInfoHd, flUsage, pBitmap, pInfo, pInstance, lFunction);
+  GreDeviceCreateBitmap(hdc, pInfoHd, flUsage, pBitmap, pInfo, pInstance, lFunction)
 == Parameters ==
-; hdc (HDC) - input : Device context handle.
+;hdc (HDC) - input : Device context handle.
+;pInfoHd (PBITMAPINFOHEADER) - input : Pointer to data structure.
-; pInfoHd (PBITMAPINFOHEADER) - input : Pointer to data structure.
+:Pointer to a [[BITMAPINFOHEADER]] or [[BITMAPINFOHEADER2]] data structure that defines the new bit map.
-: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.
-:The BITMAPINFOHEADER data structure contains the following fields:
+:Other flags are reserved and must be ignored by the handling routine.
+;pBitmap (PBYTE) - input: Pointer to bit-map initialization data.
-:cbFix Length of this structure in bytes
+: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.
-:cx Bit-map width
+;pInfo (PBITMAPINFO) - input: Pointer to [[BITMAPINFO]] or [[BITMAPINFO2]] structure.
-:cy Bit-map height
+;pInstance (PVOID) - input: Pointer to instance data.
-:cPlanes Number of color planes; 1 if standard format
+;lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGreDeviceCreateBitmap.
-:cBitCount Number of adjacent color bits per pel Notice that each plane has ((cx*cBitCount+31)/32*4*cy) bytes.
-: The BITMAPINFOHEADER2 data structure contains the following fields:
-: cbFix Length in bytes of this structure
-: cx Bit-map width
-: cy Bit-map height
-: cPlanes Number of color planes; 1 if standard format
-: cBitCount Number of adjacent color bits per pel
-: ulCompression Compression scheme used to store the bit map:
-:::BCA_UNCOMP Bit map is uncompressed (the only valid value).
-::cbImage Length of bit-map storage data in bytes. If the bit map is uncompressed, 0 (default) can be specified for this.
-::cxResolution Horizontal component of the resolution of the target device. That is, the resolution of the device the bit map is intended for in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.
-::cyResolution Vertical component of the resolution of the target device. That is, the resolution of the device the bit map is intended for in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.
-::cclrUsed The number of color indexes from the color table that are used by the bit map. If it is 0 (the default), all the indexes are used. If it is nonzero, only the first cclrUsed entries in the table are accessed by the system. Further entries can be omitted.
-::For standard formats with a cBitCount of one, four, or eight (and cPlanes=1), any indexes beyond cclrUsed are not valid. For example, a bit map with 64 colors can use the 8-bitcount format without having to supply the other 192 entries in the color table. For the 24-bitcount standard format, cclrUsed is the number of colors used by the bit map.
-::cclrImportant Minimum number of color indexes for satisfactory appearance of the bit map. More colors can be used in the bit map, however, it is not necessary to assign them to the device palette. These additional colors can be mapped to the nearest colors available. Zero (the default) means that all entries are important. For a 24-bitcount standard format, the cclrImportant colors are also listed in the color table relating to this bit map.
-::usUnits Units of measure of the horizontal and vertical components of resolution:
-:::BRU_METRIC (Default) Pels per meter
-::usReserved Reserved field. If present, it must be 0.
-::usRecording Recording algorithm, the format in which bit-map data is recorded:
-:::BRA_BOTTOMUP (Default) Scan lines are recorded from bottom to top
-::usRendering Halftoning algorithm used to record bit-map data that has been digitally halftoned:
-:::BRH_NOTHALFTONED (Default) Bit-map data not halftoned.
-:::BRH_ERRORDIFFUSION Error diffusion or damped error diffusion algorithm
-:::BRH_PANDA Processing algorithm for noncoded document acquisition
-:::BRH_SUPERCIRCLE Super circle algorithm
-::cSize1 Size value 1. If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as a percentage in the range 0-100. A value of 100% indicates no damping. A value of 0% indicates that any errors are not diffused.
-::If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the X-dimension of the pattern used in pels.
-::cSize2 Size value 2. If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the Y-dimension of the pattern used in pels.
-::ulColorEncoding Color encoding:
-:::BCE_RGB (Default) Each element in the color array is an RGB2 data type.
-::ulIdentifier Reserved for application use
-; 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.
-:Pointer to either a BITMAPINFO structure:
-::cbFix Length of structure
-::cx Bit-map width
-::cy Bit-map height
-::cPlanes Number of color planes; 1 if standard format
-::cBitCount Number of adjacent color bits per pel
-::argbColor[ ] Color table array of RGB structures:
-:::bBlue
-:::bGreen
-:::bRed
-:or pointer to a BITMAPINFO2 structure:
-::cbFix Length of structure
-::cx Bit-map width
-::cy Bit-map height
-::cPlanes Number of color planes, 1 if standard format
-::cBitCount Number of adjacent color bits per pel
-::ulCompression Compression scheme used to store the bit map:
-:::BCA_UNCOMP Bit map is uncompressed (the only valid value).
-::cbImage Length of bit-map storage data in bytes. If the bit map is uncompressed, 0 (default) can be specified for this.
-::cxResolution Horizontal component of the resolution of the target device. That is, the resolution of the device the bit map is intended for in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.
-::cyResolution Vertical component of the resolution of the target device. That is, the resolution of the device the bit map is intended for in the units specified by usUnits. This information enables an application to select from a resource group the bit map that best matches the characteristics of the current output device.
-::cclrUsed The number of color indexes from the color table that are used by the bit map. If it is 0 (the default), all the indexes are used. If it is nonzero, only the first cclrUsed entries in the table are accessed by the system. Further entries can be omitted.
-::For standard formats with a cBitCount of 1, 4, or 8 (and cPlanes=1), any indexes beyond cclrUsed are not valid. For example, a bit map with 64 colors can use the 8-bitcount format without having to supply the other 192 entries in the color table. For the 24-bitcount standard format, cclrUsed is the number of colors used by the bit map.
-::cclrImportant Minimum number of color indexes for satisfactory appearance of the bit map. More colors can be used in the bit map, however, it is not necessary to assign them to the device palette. These additional colors can be mapped to the nearest colors available. Zero (default) means that all entries are important. For a 24-bitcount standard format, the cclrImportant colors are also listed in the color table relating to this bit map.
-::usUnits Units of measure of the horizontal and vertical components of resolution:
-:::BRU_METRIC (Default) Pels per meter.
-::usReserved Reserved field. If present, it must be 0.
-::usRecording Recording algorithm, the format in which bit-map data is recorded:
-:::BRA_BOTTOMUP (Default) Scan lines are recorded from bottom to top.
-::usRendering Halftoning algorithm used to record bit-map data that has been digitally halftoned:
-:::BRH_NOTHALFTONED (Default) Bit-map data not halftoned.
-:::BRH_ERRORDIFFUSION Error diffusion or damped error diffusion algorithm
-:::BRH_PANDA Processing algorithm for noncoded document acquisition
-:::BRH_SUPERCIRCLE Super circle algorithm
-::cSize1 Size value 1. If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as a percentage in the range 0-100. A value of 100% indicates no damping. A value of 0% indicates that any errors are not diffused.
-::If the BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the X-dimension of the pattern used in pels.
-::cSize2 Size value 2. If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored. If the BRH_PANDA or :::BRH_SUPERCIRCLE is specified, cSize2 is the X-dimension of the pattern used in pels.
-::ulColorEncoding Color encoding:
-:::BCE_RGB (Default) Each element in the color array is an RGB2 data type.
-::ulIdentifier Reserved for application use
-::argbColor[] Color table array of RGB2 structures:
-:::bBlue
-:::bGreen
-:::bRed
-:::fcOptions Reserved
-; pInstance (PVOID) - input : Pointer to instance data.
-; lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGreDeviceCreateBitmap.
 == Returns ==
-; rc (ULONG) - returns : Return Code.
+;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.
-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
-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_INSUFFICIENT_MEMORY
+* PMERR_INV_BITMAP_DIMENSION
-* PMERR_DEV_FUNC_NOT_INSTALLED
+* PMERR_INV_HDC
-* PMERR_INSUFFICIENT_MEMORY
+* PMERR_INV_INFO_TABLE
-* PMERR_INV_BITMAP_DIMENSION
+* PMERR_INV_LENGTH_OR_COUNT
-* PMERR_INV_HDC
+* PMERR_INV_SCAN_START
-* PMERR_INV_INFO_TABLE
+Refer to the "Error Explanations" section in the ''Presentation Manager Programming Reference'' for further explanation.
-* 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 ==
@@ Line 141: / Line 39: @@
 #include <os2.h>
-HDC                  hdc;        /*  Device context handle. */
+HDC                 hdc;        /* Device context handle. */
-PBITMAPINFOHEADER    pInfoHd;    /*  Pointer to data structure. */
+PBITMAPINFOHEADER   pInfoHd;    /* Pointer to data structure. */
-ULONG                flUsage;
+ULONG               flUsage;
-PBYTE                pBitmap;    /*  Pointer to bit-map initialization data. */
+PBYTE               pBitmap;    /* Pointer to bit-map initialization data. */
-PBITMAPINFO          pInfo;      /*  Pointer to BITMAPINFO or BITMAPINFO2 structure. */
+PBITMAPINFO         pInfo;      /* Pointer to BITMAPINFO or BITMAPINFO2 structure. */
-PVOID                pInstance;  /*  Pointer to instance data. */
+PVOID               pInstance;  /* Pointer to instance data. */
-ULONG                lFunction;  /*  High-order WORD=flags; low-order WORD=NGreDeviceCreateBitmap. */
+ULONG               lFunction;  /* High-order WORD=flags; low-order WORD=NGreDeviceCreateBitmap. */
-ULONG                rc;         /*  Return Code. */
+ULONG               rc;         /* Return Code. */
 rc = GreDeviceCreateBitmap(hdc, pInfoHd, flUsage,
@@ Line 155: / Line 53: @@
 == 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.
-== Related Functions ==
+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.
-*
 [[Category:Gre]]