GpiQueryBitmapBits
This function transfers data from a bit map to application storage.
Syntax
lScansReturned = GpiQueryBitmapBits(hps, lScanStart, lScans, pbBuffer, pbmiInfoTable);
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lScanStart (LONG) - input
- Starting line number.
- Scan-line number at which the data transfer is to start, counting from zero as the bottom line. It must be greater or equal to 0.
- lScans (LONG) - input
- Number of scan lines to be returned.
- It must be greater or equal to 0.
- pbBuffer (PBYTE) - output
- Data area.
- Data area into which the bit-map data is copied.
- pbmiInfoTable (PBITMAPINFO2) - in/out
- Bit-map information table.
- Storage must be provided for the associated color table.
Return Code
- lScansReturned (LONG) - returns
- Number of scan lines actually returned.
- >=0 : Number of scan lines actually returned
- GPI_ALTERROR : Error.
Errors
Possible returns from WinGetLastError
- PMERR_INV_HPS (0x207F)
- An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_INV_LENGTH_OR_COUNT (0x2092)
- An invalid length or count parameter was specified.
- PMERR_INV_INFO_TABLE (0x208F)
- An invalid bit-map info table was specified with a bit-map operation.
- PMERR_NO_BITMAP_SELECTED (0x20E4)
- An attempt has been made to operate on a memory device context that has no bit map selected.
- PMERR_INV_SCAN_START (0x20C4)
- An invalid scanstart parameter was specified with a bit-map function.
- PMERR_INCORRECT_DC_TYPE (0x203C)
- An attempt was made to perform a bit-map operation on a presentation space associated with a device context of a type that is unable to support bit-map operations.
Remarks
The presentation space must be currently associated with a memory device context, which has a bit map currently selected.
The pbmiInfoTable must be initialized by the application with the values of cbFix , and also cPlanes and cBitCount , set to the format required. The standard bit-map formats are supported, plus any known to be supported by the device (see GpiQueryDeviceBitmapFormats).
Each of the following fields must also be set by the application before issuing the call (unless the BITMAPINFO2 structure is truncated and the field is not present):
- ulCompression
- usReserved
- usRecording
- usRendering
- ulColorEncoding
This function returns the values of cx , cy (plus any other information, apart from that set by the application, for which space is available in the BITMAPINFO2 structure), and the color table array filled in by the system.
The bit-map data is converted where necessary. pbBuffer 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
GpiQueryBitmapParameters and using the returned values in the following formula:
((bitcount*bitmapwidth + 31)/32)*planes*4 bytes
The storage required for the entire bit map is this value multiplied by cy .
Example Code
This example uses GpiQueryBitmapBits to copy the image data of a bit map from a presentation space associated with a memory device context.
#define INCL_GPIBITMAPS /* GPI Bit-map functions */
#define INCL_DOSMEMMGR /* DOS Memory Manager Functions */
#include <os2.h>
HPS hps; /* presentation space handle */
BITMAPINFOHEADER2 bmp = { 16, 640, 350, 1, 1 }; /* info struct */
ULONG cbBuffer, cbBitmapInfo; /* buffer lengths */
PBYTE pbBuffer; /* bit-map data buffer */
PBITMAPINFO2 pbmi; /* info structure */
/*
* Compute the size of the image-data buffer and the bit map
* information structure.
*/
cbBuffer = (((bmp.cBitCount * bmp.cx) + 31) / 32)
* 4 * bmp.cy * bmp.cPlanes;
cbBitmapInfo = sizeof(BITMAPINFO2) +
(sizeof(RGB2) * (1 << bmp.cBitCount));
/*
* Allocate memory for the image data-buffer and the bit map
* information structure.
*/
DosAllocMem((VOID *)pbBuffer,cbBuffer,
PAG_COMMIT | PAG_READ | PAG_WRITE);
DosAllocMem((VOID *)pbmi,cbBitmapInfo,
PAG_COMMIT | PAG_READ | PAG_WRITE);
/* Copy the image data. */
pbmi->cbFix = 16L;
pbmi->cPlanes = 1;
pbmi->cBitCount = 1;
GpiQueryBitmapBits(hps, 0L, (LONG) bmp.cy, pbBuffer, pbmi);
