BITMAPINFO2

Bit-map information structure.

Each bit plane logically contains (cx * cy * cBitCount) bits, although the actual length can be greater because of padding.

Note

Many functions can accept either this structure or the BITMAPINFO structure. Where possible, BITMAPINFO2 should be used.

The cbFix field is used to find the color table, if any, that goes with the information in this structure. A color table is an array of color (RGB2) values. If there are N bits per pel (N = cPlanes * cBitCount), the array contains 2**N color values. However, if N = 24, the color table is not required (because the standard-format bit map, with 24 bits per pel, is assumed to contain RGB values), unless either cclrUsed or cclrImportant is non-zero.

typedef struct _BITMAPINFO2 {
 ULONG   cbFix;           /* Length of fixed portion of structure. */
 ULONG   cx;              /* Bit-map width in pels. */
 ULONG   cy;              /* Bit-map height in pels. */
 USHORT  cPlanes;         /* Number of bit planes. */
 USHORT  cBitCount;       /* Number of bits per pel within a plane. */
 ULONG   ulCompression;   /* Compression scheme used to store the bit map. */
 ULONG   cbImage;         /* Length of bit-map storage data, in bytes. */
 ULONG   cxResolution;    /* Horizontal component of the resolution of target device. */
 ULONG   cyResolution;    /* Vertical component of the resolution of the target device. */
 ULONG   cclrUsed;        /* Number of color indexes used. */
 ULONG   cclrImportant;   /* Minimum number of color indexes for satisfactory appearance of the bit map. */
 USHORT  usUnits;         /* Units of measure. */
 USHORT  usReserved;      /* Reserved. */
 USHORT  usRecording;     /* Recording algorithm. */
 USHORT  usRendering;     /* Halftoning algorithm. */
 ULONG   cSize1;          /* Size value 1. */
 ULONG   cSize2;          /* Size value 2. */
 ULONG   ulColorEncoding; /* Color encoding. */
 ULONG   ulIdentifier;    /* Reserved for application use. */
 RGB2    argbColor[1];    /* Array of RGB values. */
} BITMAPINFO2;

typedef BITMAPINFO2 *PBITMAPINFO2;

Fields

cbFix (ULONG)

Length of fixed portion of structure.

The structure can be truncated after cBitCount or any subsequent field.

The length does not include the length of the color table. Where the color table is present, it is at an offset of cbFix from the start of the BITMAPINFO2 structure.

This length can range from 16 (BITMAPINFOHEADER through field cBitCount) up to sizeof(BITMAPINFOHEADER2) bytes.

cx (ULONG)

Bitmap width in pels.

cy (ULONG)

Bitmap height in pels.

cPlanes (USHORT)

Number of bit planes.

cBitCount (USHORT)

Number of bits per pel within a plane.

ulCompression (ULONG)

Compression scheme used to store the bit map.

BCA_UNCOMP

Bit map is uncompressed.

BCA_HUFFMAN1D

The bit map is compressed by a modified Huffman encoding. This is valid for a bi-level (one bit per pel) bit map.

BCA_RLE4

The bit map is a 4-bit per pel run-length encoded bit map. See the following section, "Format of Compressed Data," for a description of the format of the compressed data.

BCA_RLE8

The bit map is an 8-bit per pel run-length encoded bit map. See the following section, "Format of Compressed Data," for a description of the format of the compressed data.

BCA_RLE24

The bit map is a 24-bit per pel run-length encoded bit map. See the following section, "Format of Compressed Data," for a description of the format of the compressed data.

Format of Compressed Data

Encoding a run length

Run-length encoded bit maps are encoded in the buffer in a controlled format. In all cases, if the first byte is non-zero, it is the length of a run of pels of a particular color or, in the case of a BCA_RLE4 bit map, a run of a length of pels of alternating colors.

   1st-byte       pel repetition count >= 1
   2nd-4th bytes  (BCA_RLE24 only) RGB value of pel.
   2nd-byte       (BCA_RLE8) color index of pel to be repeated
                  (BCA_RLE4) the second byte contains 2 4-bit
                  color indexes.  The repetition count is
                  completed by alternately choosing the high-order
                  nibble followed by the low-order nibble for the
                  succeeding pels until the count is exhausted.

Unencoded run

An unencoded run is a string of pels to be placed in consecutive positions in the destination bit map.

   1st-byte     0
   2nd-byte     COUNT = a multiple of 3 for BCA_RLE24 bit maps, or
                COUNT >= 3 (for BCA_RLE4 and BCA_RLE8 bit maps).

followed by the bytes as follows:

BCA_RLE24

A string of bytes specifying the RGB color values of succeeding pels. If COUNT is odd, it must be padded by a zero byte for an even length overall.

BCA_RLE8

A string of bytes specifying color indexes for succeeding pels. If COUNT is odd, it must be padded by a zero byte for an even length overall.

BCA_RLE4

A string of bytes, each byte providing two color indexes, with the high-order nibble specifying the index of the pel preceding the low-order nibble. The COUNT specifies the number of indexes. The overall length of the string must be an even number of bytes, and thus may be padded with a zero byte, and the low order nibble of the last significant byte may also be zero and not used.

Delta record

A delta record indicates a shift in position in the destination bit map before the next record is decoded.

   1st-byte        0
   2nd-byte        2
   3rd-byte        Delta-x (unsigned)
   4th-byte        Delta-y (unsigned)

This is a relative jump record. It implies that the next record is to be decoded into a position in the destination bit map at an offset from the current position, determined by changing the horizontal and vertical positions by Delta-x and Delta-y, respectively.

End-of-line record

The end-of-line record signifies that the data for the current scan line is complete and that decoding of the next record should begin at the start of the next scan line.

   1st-byte        0
   2nd-byte        0

End-of-RLE record

The end-of-RLE record signifies the end of the data in the RLE compressed bit map.

   1st-byte        0
   2nd-byte        1

cbImage (ULONG)

Length of bitmap storage data, in bytes.

If the bit map is uncompressed, zero (default) can be specified for this.

cxResolution (ULONG)

Horizontal component of the resolution of target device.

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 (ULONG)

Vertical component of the resolution of the target device.

See the description of cxResolution.

cclrUsed (ULONG)

Number of color indexes used.

The number of color indexes from the color table that are used by the bit map. If it is zero (the default), all the indexes are used. If it is non-zero, only the first cclrUsed entries in the table are accessed by the system, and further entries can be omitted.

For the standard formats with a cBitCount of 1, 4, or 8 (and cPlanes equal to 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 (ULONG)

Minimum number of color indexes for satisfactory appearance of the bit map.

More colors may be used in the bit map, but it is not necessary to assign them to the device palette. These additional colors may be mapped to the nearest colors available.

Zero (the default) means that all entries are important.

For a 24-bitcount standard format bit map, the cclrImportant colors are also listed in the color table following the BITMAPINFO2 structure.

usUnits (USHORT)

Units of measure.

Units of measure of the horizontal and vertical components of resolution, cxResolution and cyResolution.

BRU_METRIC

Pels per meter. This is the default value.

usReserved (USHORT)

Reserved.

This is a reserved field.

usRecording (USHORT)

Recording algorithm.

The format in which the bit map data is recorded.

BRA_BOTTOMUP

Scan lines are recorded bottom to top. This is the default value.

usRendering (USHORT)

Halftoning algorithm.

The algorithm used to record bit map data that has been digitally halftoned.

BRH_NOTHALFTONED

Bitmap data is not halftoned. This is the default value.

BRH_ERRORDIFFUSION

Error Diffusion or Damped Error Diffusion algorithm.

BRH_PANDA

Processing Algorithm for Non-coded Document Acquisition.

BRH_SUPERCIRCLE

Super Circle algorithm.

cSize1 (ULONG)

Size value 1.

If BRH_ERRORDIFFUSION is specified in usRendering, cSize1 is the error damping as a percentage in the range 0 through 100. A value of 100% indicates no damping, and a value of 0% indicates that any errors are not diffused.

If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize1 is the x dimension of the pattern used, in pels.

cSize2 (ULONG)

Size value 2.

If BRH_ERRORDIFFUSION is specified in usRendering, this parameter is ignored.

If BRH_PANDA or BRH_SUPERCIRCLE is specified, cSize2 is the y dimension of the pattern used, in pels.

ulColorEncoding (ULONG)

Color encoding.

BCE_RGB

Each element in the color array is an RGB2 datatype. This is the default value.

ulIdentifier (ULONG)

Reserved for application use.

argbColor[1] (RGB2)

Array of RGB values.

This is a packed array of 24-bit RGB values. If there are N bits per pel (N = cPlanes * cBitCount), the array contains 2**N RGB values. However, if N = 24, the bit map does not need the color array because the standard-format bit map, with 24 bits per pel, is assumed to contain RGB values.