DeviceBitmapBits

void DeviceBitmapBits(
  LPPDEVICE lpBitmap, 
  WORD fGet, 
  WORD iStart, 
  WORD cScans, 
  LPSTR lpDIBits, 
  LPBITMAPINFO lpBitmapInfo, 
  LPDRAWMODE lpDrawMode, 
  LPINT lpTranslate
 );

Either copies DIB to a device-specific bitmap or copies a device-specific bitmap to a DIB. The fGet parameter specifies which operation to carry out.

Returns one of these values:

>0	Number of scanlines set or retrieved.
0	Error.
-1	Bits cannot be set or retrieved.

lpBitmap

Address of a PBITMAP structure that specifies a device-specific memory bitmap.

fGet

Flag that specifies whether the function sets or retrieves bitmap bits. If this parameter is zero, the function sets the bits; if the parameter is 1, the function retrieves the bits.

iStart

Starting scan number.

cScans

Number of scans to set or retrieve.

lpDIBits

Address of a buffer that contains or receives the bitmaps bits. If the fGet parameter is zero, the function copies data from the buffer into the bitmap; if fGet is 1, the function copies the bits to the buffer from the bitmap. If this parameter is NULL, the function fills the biSizeImage member in the BITMAPINFO structure pointed to by the lpBitmapInfo parameter, but does not copy bitmap bits.

lpBitmapInfo

Address of a BITMAPINFO structure that specifies the dimensions and format of the DIB.

The function must check the biPlanes and the biBitCount members. If biPlanes is not 1 or biBitCount is not 1, 4, 8, or 24, the function returns an error value.

The function compares the widths of the device-specific bitmap and the DIB. If the widths are not equal, the function clips to the smaller of the two bitmaps.

If the RLE_FORMAT_4 or RLE_FORMAT_8 values are set in the biCompression member of the BITMAPINFO structure, the DIB is in RLE format. In this case, the function must encode each scan line as it copies the scan line data to the buffer pointed to by lpDIBits or the function must decode the data as it retrieves it from the buffer.

lpDrawMode

Address of a DRAWMODE structure that specifies the text (foreground) and background colors to use if color conversion is required.

lpTranslate

Address of an array of color translation values for converting palette colors to actual device colors. This parameter is ignored by devices that do not use color palettes.

The export ordinal for this function is 19.

A graphics driver must export a DeviceBitmapBits function if the RC_DI_BITMAP value is set in the dpRaster member of the driver's GDIINFO structure.

Depending on the operation specified by the fGet parameter, DeviceBitmapBits either converts the bits pointed to by lpDIBits to the format required by the bitmap specified by the lpBitmap parameter or converts the bits pointed to by lpDIBits to the format required by lpBitmap. To convert the bits, the function computes the width and height of the bitmap to copy, determines if color conversion is necessary, and prepares for scan lines that cross the 64K boundaries.

DeviceBitmapBits checks the color formats of the bitmap specified by lpBitmap and the DIB specified by lpBitmapInfo. If the color formats are not the same, the function must convert the bitmap pixels to the same format as the destination. For example, if the function copies a DIB to a monochrome bitmap, the function must convert color pixels to monochrome. In this case, DeviceBitmapBits converts all pixels that match the background color (as specified by the lpDrawMode parameter) to white (1), and converts all other pixels to black (0).

To prepare for color conversion when fGet is zero, the function maps color-table information (if any) provided in the BITMAPINFO structure to the device-specific colors. If the biClrUsed member is zero, the function must use a default color table. The size of the default table depends on the number of bits per pixel (that is, 16 colors for 4 bits-per-pixel, 256 colors for 8 bits-per-pixel, and so on). However, if biClrUsed is nonzero, the member specifies the size of the table; this size cannot be more than the default size. Because the default color table for a bitmap having 24 bits per pixel is exceptionally large, the function carries out the color mapping as it converts the bits rather than generating a table.

To prepare for color conversion when fGet is 1, the function creates the logical-color table and copies it to the BITMAPINFO structure. If the device driver does not support a color palette, the function fills the logical-color table with whatever color it supports and use the corresponding indices in the bitmap. It must also set the number of colors it is using in the biClrUsed member of the BITMAPINFO structure. For example, if the display device is a four-plane device (16 colors) but the request is for a DIB that has 8 bits-per-pixel (256 colors), the function can specify just 16 colors and set the biClrUsed member to 16, or it can set remaining colors (entries 16 through 255) to zero and set the biClrUsed member to zero.

DeviceBitmapBits

See Also