get_device_independent_bitmap_bits


int get_device_independent_bitmap_bits(handle device,
                                       handle bitmap,
                                       unsigned start,
                                       unsigned lines,
                                       void* bits,
                                       bitmap_information* information,
                                       unsigned usage)

This function copies bitmap bit data to a buffer (optionally performing a color format conversion).

Parameters

handle device

The handle of a device context. This member is used only if colors::palette is specified for the parameter Usage.

handle bitmap

The handle of the bitmap from which data is obtained.

unsigned start

The first scan line to obtain.

unsigned lines

The number of scan lines to obtain.

void* bits

A pointer to memory to which data is written. If null is specified, the dimensions and format of the bitmap are written to the buffer supplied by the next parameter.

bitmap_information* information

A pointer to an object specifying the desired format for the device independent bitmap (DIB) data.

unsigned usage

A flag indicating whether a color table is present in the bitmap and, if so, the format of the color table in the associated bitmap information structure. valid values are:

colors::red_green_blue The associated color table contains the actual red, green, blue values.
colors::palette The associated color table consists of 16 bit indices into the currently realized logical color palette.

Return

int

Zero The function failed.
Other The number of scanlines written to the given buffer (when the buffer is non-null) or a non-zero value when information was written to the bitmap information structure (only).

Notes

When the internal format of the bitmap being queried is the same as that found in the supplied bitmap information structure (see bitmap_bits), the red, green, blue values are copied.

When the internal format of the bitmap differs from that found in the bitmap information structure, a color conversion is performed and a color table is created. The form of the created color table is as follows.

1 bits/pixel A color table containing two entries - black and white.
4 bits/pixel A color table containing the 16 standard VGA colors is formed.
8 bits/pixel A color table containing the 256 entries is formed. The 20 colors found in the default logical color palette are included.
24 bits/pixel No color table is returned.

If the parameter bits is a valid pointer, the first six members of the bitmap information class must be initialized to specify the size and format of the device independent bitmap.

Depending upon version, any of the following bitmap information structures may be used:

A bottom-up device independent bitmap is specified by setting the height to a positive number. A top-down device independent bitmap is specified by setting the height to a negative number. The color table is appended to the bitmap information structure. The origin for a bottom-up device independent bitmap is the lower-left corner of the bitmap. The origin for a top-down device independent bitmap is the upper-left corner.

If bits is null, this function examines the first member of the object pointed to by information. This member must specify the size (in bytes) of an object of class bitmap_core or a bitmap information structure. The function uses the specified size to determine how the remaining members should be initialized.

If bits is null and the bit count member of bitmap_information is initialized to zero, this function fills the bitmap information or bitmap core object without the color table. This technique can be used to query the attributes of a bitmap.

For the operation to perform correctly, the bitmap cannot be selected into a device context.