View source for GreGetBitmapBits

GreGetBitmapBits can be called for two reasons. If the pointer to application storage (pBitmap) is not NULL, the function transfers bit-map data from a bit map to application storage. If pBitmap is NULL, this function must only fill in the RGB values in the BITMAPINFO or BITMAPINFO2 data structure, which is pointed to by pInfo, and then return the value 0. 

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

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

== Syntax == 
 GreGetBitmapBits(hdc, hbm, lScanStart, cScanCount, pBitmap, pInfo, pInstance, lFunction);

== Parameters ==
; hdc (HDC) - input : Device context handle. 

; hbm (HBITMAP) - input : Bit-map handle. 

If 0, the DC bit map is used. 

; lScanStart (LONG) - input : Scan line number from where data transfer starts. 

0 is the first scan line number. 

; cScanCount (LONG) - input : Number of scan lines to be transferred. 

; pBitmap (PBYTE) - input : Pointer to bit-map data or NULL. 

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 0s 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. This value is updated by the handling routine. 
cy Bit-map height. This value is updated by the handling routine. 
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 (default), all the indexes are used. If it is not 0, 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, but 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 Half-toning algorithm used to record bit-map data that has been digitally half-toned: 

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 no errors are 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. 

argbColor[] Color table array of RGB2 structures: 

bBlue   
bGreen   
bRed   
fcOptions Reserved. Must be 0. 

; pInstance (PVOID) - input : Pointer to instance data. 

; lFunction (ULONG) - input : High-order WORD=flags; low-order WORD=NGreGetBitmapBits. 

== Returns ==
; rc (LONG) - returns : Return Code. 

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 ==
<pre>

#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 or NULL. */
PBITMAPINFO    pInfo;       /*  Pointer to BITMAPINFO or BITMAPINFO2 structure. */
PVOID          pInstance;   /*  Pointer to instance data. */
ULONG          lFunction;   /*  High-order WORD=flags; low-order WORD=NGreGetBitmapBits. */
LONG           rc;          /*  Return Code. */

rc = GreGetBitmapBits(hdc, hbm, lScanStart,
       cScanCount, pBitmap, pInfo, pInstance,
       lFunction);
</pre>

== Remarks ==
The bit map can be specified by a bit-map handle, or (if this is NULL) a DC handle, in which case the device context must be a memory DC with a bit map currently selected. 

When the bit-map handle is NULL, the DC must be a memory DC with a bit map currently selected. Otherwise, the DC handle must be valid for that device. The BITMAPINFO or BITMAPINFO2 structure must be initialized with the values of cPlanes and cBitcount for the format of data required. This must be one of the standard formats or a device-specific format that matches the DC. On return, cx, cy, and argbColors are supplied by the system. Conversion of the bit-map data is carried out, if necessary. 

pBitmap must point to a storage area large enough to contain data for the requested number of scan lines. The amount of storage required for one scan line can be determined by calling GetBitmapParameters: 

 ((cBitcount * cx + 31)/32) * cPlanes * 4 bytes


[[Category:Gre]]