reverted my open watcom to 1.9 an recompiled everything~

[16.git] / 16 / PCGPE10 / BMP.TXT

Graphics File Formats\r
\r
This topic describes the graphics-file formats used by the Microsoft Windows\r
operating system. Graphics files include bitmap files, icon-resource files,\r
and cursor-resource files.\r
\r
Bitmap-File Formats\r
\r
Windows bitmap files are stored in a device-independent bitmap (DIB) format\r
that allows Windows to display the bitmap on any type of display device. The\r
term "device independent" means that the bitmap specifies pixel color in a\r
form independent of the method used by a display to represent color. The\r
default filename extension of a Windows DIB file is .BMP.\r
\r
Bitmap-File Structures\r
\r
Each bitmap file contains a bitmap-file header, a bitmap-information header,\r
a color table, and an array of bytes that defines the bitmap bits. The file\r
has the following form:\r
\r
BITMAPFILEHEADER bmfh;\r
BITMAPINFOHEADER bmih;\r
RGBQUAD          aColors[];\r
BYTE             aBitmapBits[];\r
\r
The bitmap-file header contains information about the type, size, and layout\r
of a device-independent bitmap file. The header is defined as a\r
BITMAPFILEHEADER structure.\r
\r
The bitmap-information header, defined as a BITMAPINFOHEADER structure,\r
specifies the dimensions, compression type, and color format for the bitmap.\r
\r
The color table, defined as an array of RGBQUAD structures, contains as many\r
elements as there are colors in the bitmap. The color table is not present\r
for bitmaps with 24 color bits because each pixel is represented by 24-bit\r
red-green-blue (RGB) values in the actual bitmap data area. The colors in the\r
table should appear in order of importance. This helps a display driver\r
render a bitmap on a device that cannot display as many colors as there are\r
in the bitmap. If the DIB is in Windows version 3.0 or later format, the\r
driver can use the biClrImportant member of the BITMAPINFOHEADER structure to\r
determine which colors are important.\r
\r
The BITMAPINFO structure can be used to represent a combined\r
bitmap-information header and color table.  The bitmap bits, immediately\r
following the color table, consist of an array of BYTE values representing\r
consecutive rows, or "scan lines," of the bitmap. Each scan line consists of\r
consecutive bytes representing the pixels in the scan line, in left-to-right\r
order. The number of bytes representing a scan line depends on the color\r
format and the width, in pixels, of the bitmap. If necessary, a scan line\r
must be zero-padded to end on a 32-bit boundary. However, segment boundaries\r
can appear anywhere in the bitmap. The scan lines in the bitmap are stored\r
from bottom up. This means that the first byte in the array represents the\r
pixels in the lower-left corner of the bitmap and the last byte represents\r
the pixels in the upper-right corner.\r
\r
The biBitCount member of the BITMAPINFOHEADER structure determines the number\r
of bits that define each pixel and the maximum number of colors in the\r
bitmap. These members can have any of the following values:\r
\r
Value   Meaning\r
\r
1       Bitmap is monochrome and the color table contains two entries. Each\r
bit in the bitmap array represents a pixel. If the bit is clear, the pixel is\r
displayed with the color of the first entry in the color table. If the bit is\r
set, the pixel has the color of the second entry in the table.\r
\r
4       Bitmap has a maximum of 16 colors. Each pixel in the bitmap is\r
represented by a 4-bit index into the color table. For example, if the first\r
byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel\r
contains the color in the second table entry, and the second pixel contains\r
the color in the sixteenth table entry.\r
\r
8       Bitmap has a maximum of 256 colors. Each pixel in the bitmap is\r
represented by a 1-byte index into the color table. For example, if the first\r
byte in the bitmap is 0x1F, the first pixel has the color of the\r
thirty-second table entry.\r
\r
24      Bitmap has a maximum of 2^24 colors. The bmiColors (or bmciColors)\r
member is NULL, and each 3-byte sequence in the bitmap array represents the\r
relative intensities of red, green, and blue, respectively, for a pixel.\r
\r
The biClrUsed member of the BITMAPINFOHEADER structure specifies the number\r
of color indexes in the color table actually used by the bitmap. If the\r
biClrUsed member is set to zero, the bitmap uses the maximum number of colors\r
corresponding to the value of the biBitCount member.  An alternative form of\r
bitmap file uses the BITMAPCOREINFO, BITMAPCOREHEADER, and RGBTRIPLE\r
structures.\r
\r
Bitmap Compression\r
\r
Windows versions 3.0 and later support run-length encoded (RLE) formats for\r
compressing bitmaps that use 4 bits per pixel and 8 bits per pixel.\r
Compression reduces the disk and memory storage required for a bitmap.\r
\r
Compression of 8-Bits-per-Pixel Bitmaps\r
\r
When the biCompression member of the BITMAPINFOHEADER structure is set to\r
BI_RLE8, the DIB is compressed using a run-length encoded format for a\r
256-color bitmap. This format uses two modes: encoded mode and absolute mode.\r
Both modes can occur anywhere throughout a single bitmap.\r
\r
Encoded Mode\r
\r
A unit of information in encoded mode consists of two bytes. The first byte\r
specifies the number of consecutive pixels to be drawn using the color index\r
contained in the second byte.  The first byte of the pair can be set to zero\r
to indicate an escape that denotes the end of a line, the end of the bitmap,\r
or a delta. The interpretation of the escape depends on the value of the\r
second byte of the pair, which must be in the range 0x00 through 0x02.\r
Following are the meanings of the escape values that can be used in the\r
second byte:\r
\r
Second byte     Meaning\r
\r
0       End of line. \r
1       End of bitmap. \r
2       Delta. The two bytes following the escape contain unsigned values\r
indicating the horizontal and vertical offsets of the next pixel from the\r
current position.\r
\r
Absolute Mode\r
\r
Absolute mode is signaled by the first byte in the pair being set to zero and\r
the second byte to a value between 0x03 and 0xFF. The second byte represents\r
the number of bytes that follow, each of which contains the color index of a\r
single pixel. Each run must be aligned on a word boundary.  Following is an\r
example of an 8-bit RLE bitmap (the two-digit hexadecimal values in the\r
second column represent a color index for a single pixel):\r
\r
Compressed data         Expanded data\r
\r
03 04                   04 04 04 \r
05 06                   06 06 06 06 06 \r
00 03 45 56 67 00       45 56 67 \r
02 78                   78 78 \r
00 02 05 01             Move 5 right and 1 down \r
02 78                   78 78 \r
00 00                   End of line \r
09 1E                   1E 1E 1E 1E 1E 1E 1E 1E 1E \r
00 01                   End of RLE bitmap \r
\r
Compression of 4-Bits-per-Pixel Bitmaps\r
\r
When the biCompression member of the BITMAPINFOHEADER structure is set to\r
BI_RLE4, the DIB is compressed using a run-length encoded format for a\r
16-color bitmap. This format uses two modes: encoded mode and absolute mode.\r
\r
Encoded Mode\r
\r
A unit of information in encoded mode consists of two bytes. The first byte\r
of the pair contains the number of pixels to be drawn using the color indexes\r
in the second byte.\r
\r
The second byte contains two color indexes, one in its high-order nibble\r
(that is, its low-order 4 bits) and one in its low-order nibble.\r
\r
The first pixel is drawn using the color specified by the high-order nibble,\r
the second is drawn using the color in the low-order nibble, the third is\r
drawn with the color in the high-order nibble, and so on, until all the\r
pixels specified by the first byte have been drawn.\r
\r
The first byte of the pair can be set to zero to indicate an escape that\r
denotes the end of a line, the end of the bitmap, or a delta. The\r
interpretation of the escape depends on the value of the second byte of the\r
pair. In encoded mode, the second byte has a value in the range 0x00 through\r
0x02. The meaning of these values is the same as for a DIB with 8 bits per\r
pixel.\r
\r
Absolute Mode\r
\r
In absolute mode, the first byte contains zero, the second byte contains the\r
number of color indexes that follow, and subsequent bytes contain color\r
indexes in their high- and low-order nibbles, one color index for each pixel.\r
Each run must be aligned on a word boundary.\r
\r
Following is an example of a 4-bit RLE bitmap (the one-digit hexadecimal\r
values in the second column represent a color index for a single pixel):\r
\r
Compressed data         Expanded data\r
\r
03 04                   0 4 0\r
05 06                   0 6 0 6 0 \r
00 06 45 56 67 00       4 5 5 6 6 7 \r
04 78                   7 8 7 8 \r
00 02 05 01             Move 5 right and 1 down \r
04 78                   7 8 7 8 \r
00 00                   End of line \r
09 1E                   1 E 1 E 1 E 1 E 1 \r
00 01                   End of RLE bitmap \r
\r
Bitmap Example\r
\r
The following example is a text dump of a 16-color bitmap (4 bits per pixel):\r
\r
Win3DIBFile\r
              BitmapFileHeader\r
                  Type       19778\r
                  Size       3118\r
                  Reserved1  0\r
                  Reserved2  0\r
                  OffsetBits 118\r
              BitmapInfoHeader\r
                  Size            40\r
                  Width           80\r
                  Height          75\r
                  Planes          1\r
                  BitCount        4\r
                  Compression     0\r
                  SizeImage       3000\r
\r
                  XPelsPerMeter   0\r
                  YPelsPerMeter   0\r
                  ColorsUsed      16\r
                  ColorsImportant 16\r
              Win3ColorTable\r
                  Blue  Green  Red  Unused\r
[00000000]        84    252    84   0\r
[00000001]        252   252    84   0\r
[00000002]        84    84     252  0\r
[00000003]        252   84     252  0\r
[00000004]        84    252    252  0\r
[00000005]        252   252    252  0\r
[00000006]        0     0      0    0\r
[00000007]        168   0      0    0\r
[00000008]        0     168    0    0\r
[00000009]        168   168    0    0\r
[0000000A]        0     0      168  0\r
[0000000B]        168   0      168  0\r
[0000000C]        0     168    168  0\r
[0000000D]        168   168    168  0\r
[0000000E]        84    84     84   0\r
[0000000F]        252   84     84   0\r
              Image\r
    .\r
    .                                           Bitmap data\r
    .\r
\r
Icon-Resource File Format\r
\r
An icon-resource file contains image data for icons used by Windows\r
applications. The file consists of an icon directory identifying the number\r
and types of icon images in the file, plus one or more icon images. The\r
default filename extension for an icon-resource file is .ICO.\r
\r
Icon Directory\r
\r
Each icon-resource file starts with an icon directory. The icon directory,\r
defined as an ICONDIR structure, specifies the number of icons in the\r
resource and the dimensions and color format of each icon image. The ICONDIR\r
structure has the following form:\r
\r
\r
\r
typedef struct ICONDIR {\r
    WORD          idReserved;\r
    WORD          idType;\r
    WORD          idCount;\r
    ICONDIRENTRY  idEntries[1];\r
} ICONHEADER;\r
\r
Following are the members in the ICONDIR structure:\r
\r
idReserved      Reserved; must be zero. \r
idType          Specifies the resource type. This member is set to 1. \r
idCount         Specifies the number of entries in the directory. \r
idEntries       Specifies an array of ICONDIRENTRY structures containing\r
information about individual icons. The idCount member specifies the number\r
of structures in the array.\r
\r
The ICONDIRENTRY structure specifies the dimensions and color format for an\r
icon. The structure has the following form:\r
\r
\r
\r
struct IconDirectoryEntry {\r
    BYTE  bWidth;\r
    BYTE  bHeight;\r
    BYTE  bColorCount;\r
    BYTE  bReserved;\r
    WORD  wPlanes;\r
    WORD  wBitCount;\r
    DWORD dwBytesInRes;\r
    DWORD dwImageOffset;\r
};\r
\r
Following are the members in the ICONDIRENTRY structure: \r
\r
bWidth          Specifies the width of the icon, in pixels. Acceptable values\r
are 16, 32, and 64.\r
\r
bHeight         Specifies the height of the icon, in pixels. Acceptable\r
values are 16, 32, and 64.\r
\r
bColorCount     Specifies the number of colors in the icon. Acceptable values\r
are 2, 8, and 16.\r
\r
bReserved       Reserved; must be zero. \r
wPlanes         Specifies the number of color planes in the icon bitmap. \r
wBitCount       Specifies the number of bits in the icon bitmap. \r
dwBytesInRes    Specifies the size of the resource, in bytes. \r
dwImageOffset   Specifies the offset, in bytes, from the beginning of the\r
file to the icon image.\r
\r
Icon Image\r
\r
Each icon-resource file contains one icon image for each image identified in\r
the icon directory. An icon image consists of an icon-image header, a color\r
table, an XOR mask, and an AND mask. The icon image has the following form:\r
\r
\r
\r
BITMAPINFOHEADER    icHeader;\r
RGBQUAD             icColors[];\r
BYTE                icXOR[];\r
BYTE                icAND[];\r
\r
The icon-image header, defined as a BITMAPINFOHEADER structure, specifies the\r
dimensions and color format of the icon bitmap. Only the biSize through\r
biBitCount members and the biSizeImage member are used. All other members\r
(such as biCompression and biClrImportant) must be set to zero.\r
\r
The color table, defined as an array of RGBQUAD structures, specifies the\r
colors used in the XOR mask. As with the color table in a bitmap file, the\r
biBitCount member in the icon-image header determines the number of elements\r
in the array. For more information about the color table, see Section 1.1,\r
"Bitmap-File Formats."\r
\r
The XOR mask, immediately following the color table, is an array of BYTE\r
values representing consecutive rows of a bitmap. The bitmap defines the\r
basic shape and color of the icon image. As with the bitmap bits in a bitmap\r
file, the bitmap data in an icon-resource file is organized in scan lines,\r
with each byte representing one or more pixels, as defined by the color\r
format. For more information about these bitmap bits, see Section 1.1,\r
"Bitmap-File Formats."\r
\r
The AND mask, immediately following the XOR mask, is an array of BYTE values,\r
representing a monochrome bitmap with the same width and height as the XOR\r
mask. The array is organized in scan lines, with each byte representing 8\r
pixels.\r
\r
When Windows draws an icon, it uses the AND and XOR masks to combine the icon\r
image with the pixels already on the display surface. Windows first applies\r
the AND mask by using a bitwise AND operation; this preserves or removes\r
existing pixel color.  Windows then applies the XOR mask by using a bitwise\r
XOR operation. This sets the final color for each pixel.\r
\r
The following illustration shows the XOR and AND masks that create a\r
monochrome icon (measuring 8 pixels by 8 pixels) in the form of an uppercase\r
K:\r
\r
Windows Icon Selection\r
\r
Windows detects the resolution of the current display and matches it against\r
the width and height specified for each version of the icon image. If Windows\r
determines that there is an exact match between an icon image and the current\r
device, it uses the matching image. Otherwise, it selects the closest match\r
and stretches the image to the proper size.\r
\r
If an icon-resource file contains more than one image for a particular\r
resolution, Windows uses the icon image that most closely matches the color\r
capabilities of the current display. If no image matches the device\r
capabilities exactly, Windows selects the image that has the greatest number\r
of colors without exceeding the number of display colors. If all images\r
exceed the color capabilities of the current display, Windows uses the icon\r
image with the least number of colors.\r
\r
\r
\r
Cursor-Resource File Format\r
\r
A cursor-resource file contains image data for cursors used by Windows\r
applications. The file consists of a cursor directory identifying the number\r
and types of cursor images in the file, plus one or more cursor images. The\r
default filename extension for a cursor-resource file is .CUR.\r
\r
Cursor Directory\r
\r
Each cursor-resource file starts with a cursor directory. The cursor\r
directory, defined as a CURSORDIR structure, specifies the number of cursors\r
in the file and the dimensions and color format of each cursor image. The\r
CURSORDIR structure has the following form:\r
\r
\r
typedef struct _CURSORDIR {\r
    WORD           cdReserved;\r
    WORD           cdType;\r
    WORD           cdCount;\r
    CURSORDIRENTRY cdEntries[];\r
} CURSORDIR;\r
\r
Following are the members in the CURSORDIR structure: \r
\r
cdReserved      Reserved; must be zero. \r
cdType          Specifies the resource type. This member must be set to 2. \r
cdCount         Specifies the number of cursors in the file. \r
cdEntries       Specifies an array of CURSORDIRENTRY structures containing\r
information about individual cursors. The cdCount member specifies the number\r
of structures in the array.\r
\r
A CURSORDIRENTRY structure specifies the dimensions and color format of a\r
cursor image. The structure has the following form:\r
\r
\r
\r
typedef struct _CURSORDIRENTRY {\r
    BYTE  bWidth;\r
    BYTE  bHeight;\r
    BYTE  bColorCount;\r
    BYTE  bReserved;\r
    WORD  wXHotspot;\r
    WORD  wYHotspot;\r
    DWORD lBytesInRes;\r
    DWORD dwImageOffset;\r
} CURSORDIRENTRY;\r
\r
Following are the members in the CURSORDIRENTRY structure: \r
\r
bWidth          Specifies the width of the cursor, in pixels. \r
bHeight         Specifies the height of the cursor, in pixels. \r
bColorCount     Reserved; must be zero. \r
bReserved       Reserved; must be zero.\r
wXHotspot       Specifies the x-coordinate, in pixels, of the hot spot. \r
wYHotspot       Specifies the y-coordinate, in pixels, of the hot spot. \r
lBytesInRes     Specifies the size of the resource, in bytes. \r
dwImageOffset   Specifies the offset, in bytes, from the start of the file to\r
the cursor image.\r
\r
Cursor Image\r
\r
Each cursor-resource file contains one cursor image for each image identified\r
in the cursor directory. A cursor image consists of a cursor-image header, a\r
color table, an XOR mask, and an AND mask. The cursor image has the following\r
form:\r
\r
\r
\r
BITMAPINFOHEADER    crHeader;\r
RGBQUAD             crColors[];\r
BYTE                crXOR[];\r
BYTE                crAND[];\r
\r
The cursor hot spot is a single pixel in the cursor bitmap that Windows uses\r
to track the cursor. The crXHotspot and crYHotspot members specify the x- and\r
y-coordinates of the cursor hot spot. These coordinates are 16-bit integers.\r
\r
The cursor-image header, defined as a BITMAPINFOHEADER structure, specifies\r
the dimensions and color format of the cursor bitmap. Only the biSize through\r
biBitCount members and the biSizeImage member are used. The biHeight member\r
specifies the combined height of the XOR and AND masks for the cursor. This\r
value is twice the height of the XOR mask. The biPlanes and biBitCount\r
members must be 1. All other members (such as biCompression and\r
biClrImportant) must be set to zero.\r
\r
The color table, defined as an array of RGBQUAD structures, specifies the\r
colors used in the XOR mask. For a cursor image, the table contains exactly\r
two structures, since the biBitCount member in the cursor-image header is\r
always 1.\r
\r
The XOR mask, immediately following the color table, is an array of BYTE\r
values representing consecutive rows of a bitmap. The bitmap defines the\r
basic shape and color of the cursor image. As with the bitmap bits in a\r
bitmap file, the bitmap data in a cursor-resource file is organized in scan\r
lines, with each byte representing one or more pixels, as defined by the\r
color format. For more information about these bitmap bits, see Section 1.1,\r
"Bitmap-File Formats."\r
\r
The AND mask, immediately following the XOR mask, is an array of BYTE values\r
representing a monochrome bitmap with the same width and height as the XOR\r
mask. The array is organized in scan lines, with each byte representing 8\r
pixels.\r
\r
When Windows draws a cursor, it uses the AND and XOR masks to combine the\r
cursor image with the pixels already on the display surface. Windows first\r
applies the AND mask by using a bitwise AND operation; this preserves or\r
removes existing pixel color.  Window then applies the XOR mask by using a\r
bitwise XOR operation. This sets the final color for each pixel.\r
\r
The following illustration shows the XOR and the AND masks that create a\r
cursor (measuring 8 pixels by 8 pixels) in the form of an arrow:\r
\r
Following are the bit-mask values necessary to produce black, white,\r
inverted, and transparent results:\r
\r
Pixel result    AND maskXOR mask\r
\r
Black           0               0 \r
White           0               1 \r
Transparent     1               0 \r
Inverted1               1 \r
\r
Windows Cursor Selection\r
\r
If a cursor-resource file contains more than one cursor image, Windows\r
determines the best match for a particular display by examining the width and\r
height of the cursor images.\r
\r
\r
==============================================================================\r
\r
\r
BITMAPFILEHEADER (3.0)\r
\r
\r
\r
typedef struct tagBITMAPFILEHEADER {    /* bmfh */\r
    UINT    bfType;\r
    DWORD   bfSize;\r
    UINT    bfReserved1;\r
    UINT    bfReserved2;\r
    DWORD   bfOffBits;\r
} BITMAPFILEHEADER;\r
\r
The BITMAPFILEHEADER structure contains information about the type, size, and\r
layout of a device-independent bitmap (DIB) file.\r
\r
Member          Description\r
\r
bfType          Specifies the type of file. This member must be BM. \r
bfSize          Specifies the size of the file, in bytes. \r
bfReserved1     Reserved; must be set to zero. \r
bfReserved2     Reserved; must be set to zero.\r
bfOffBits       Specifies the byte offset from the BITMAPFILEHEADER structure\r
to the actual bitmap data in the file.\r
\r
Comments\r
\r
A BITMAPINFO or BITMAPCOREINFO structure immediately follows the\r
BITMAPFILEHEADER structure in the DIB file.\r
\r
See Also\r
\r
BITMAPCOREINFO, BITMAPINFO \r
\r
\r
==============================================================================\r
BITMAPINFO (3.0)\r
\r
\r
\r
typedef struct tagBITMAPINFO {  /* bmi */\r
    BITMAPINFOHEADER    bmiHeader;\r
    RGBQUAD             bmiColors[1];\r
} BITMAPINFO;\r
\r
The BITMAPINFO structure fully defines the dimensions and color information\r
for a Windows 3.0 or later device-independent bitmap (DIB).\r
\r
Member          Description\r
\r
bmiHeader       Specifies a BITMAPINFOHEADER structure that contains\r
information about the dimensions and color format of a DIB.\r
\r
bmiColors       Specifies an array of RGBQUAD structures that define the\r
colors in the bitmap.\r
\r
Comments\r
\r
A Windows 3.0 or later DIB consists of two distinct parts: a BITMAPINFO\r
structure, which describes the dimensions and colors of the bitmap, and an\r
array of bytes defining the pixels of the bitmap. The bits in the array are\r
packed together, but each scan line must be zero-padded to end on a LONG\r
boundary. Segment boundaries, however, can appear anywhere in the bitmap. The\r
origin of the bitmap is the lower-left corner.\r
\r
The biBitCount member of the BITMAPINFOHEADER structure determines the number\r
of bits which define each pixel and the maximum number of colors in the\r
bitmap. This member may be set to any of the following values:\r
\r
Value   Meaning\r
\r
1       The bitmap is monochrome, and the bmciColors member must contain two\r
entries. Each bit in the bitmap array represents a pixel. If the bit is\r
clear, the pixel is displayed with the color of the first entry in the\r
bmciColors table. If the bit is set, the pixel has the color of the second\r
entry in the table.\r
\r
4       The bitmap has a maximum of 16 colors, and the bmciColors member\r
contains 16 entries. Each pixel in the bitmap is represented by a four-bit\r
index into the color table.\r
\r
For example, if the first byte in the bitmap is 0x1F, the byte represents two\r
pixels. The first pixel contains the color in the second table entry, and the\r
second pixel contains the color in the sixteenth table entry.\r
\r
8       The bitmap has a maximum of 256 colors, and the bmciColors member\r
contains 256 entries. In this case, each byte in the array represents a\r
single pixel.\r
\r
24      The bitmap has a maximum of 2^24 colors. The bmciColors member is\r
NULL, and each 3-byte sequence in the bitmap array represents the relative\r
intensities of red, green, and blue, respectively, of a pixel.\r
\r
The biClrUsed member of the BITMAPINFOHEADER structure specifies the number\r
of color indexes in the color table actually used by the bitmap. If the\r
biClrUsed member is set to zero, the bitmap uses the maximum number of colors\r
corresponding to the value of the biBitCount member.\r
\r
The colors in the bmiColors table should appear in order of importance.\r
Alternatively, for functions that use DIBs, the bmiColors member can be an\r
array of 16-bit unsigned integers that specify an index into the currently\r
realized logical palette instead of explicit RGB values. In this case, an\r
application using the bitmap must call DIB functions with the wUsage\r
parameter set to DIB_PAL_COLORS.\r
\r
Note:   The bmiColors member should not contain palette indexes if the bitmap\r
is to be stored in a file or transferred to another application. Unless the\r
application uses the bitmap exclusively and under its complete control, the\r
bitmap color table should contain explicit RGB values.\r
\r
See Also\r
\r
BITMAPINFOHEADER, RGBQUAD \r
\r
==============================================================================\r
BITMAPINFOHEADER (3.0)\r
\r
\r
\r
typedef struct tagBITMAPINFOHEADER {    /* bmih */\r
    DWORD   biSize;\r
    LONG    biWidth;\r
    LONG    biHeight;\r
    WORD    biPlanes;\r
    WORD    biBitCount;\r
    DWORD   biCompression;\r
    DWORD   biSizeImage;\r
    LONG    biXPelsPerMeter;\r
    LONG    biYPelsPerMeter;\r
    DWORD   biClrUsed;\r
    DWORD   biClrImportant;\r
} BITMAPINFOHEADER;\r
\r
The BITMAPINFOHEADER structure contains information about the dimensions and\r
color format of a Windows 3.0 or later device-independent bitmap (DIB).\r
\r
Member          Description\r
\r
biSize          Specifies the number of bytes required by the\r
BITMAPINFOHEADER structure.\r
\r
biWidth         Specifies the width of the bitmap, in pixels. \r
biHeightSpecifies the height of the bitmap, in pixels. \r
\r
biPlanesSpecifies the number of planes for the target device. This\r
member must be set to 1.\r
\r
biBitCount      Specifies the number of bits per pixel. This value must be 1,\r
4, 8, or 24.\r
\r
biCompression   Specifies the type of compression for a compressed bitmap. It\r
can be one of the following values:\r
\r
Value           Meaning\r
\r
BI_RGB          Specifies that the bitmap is not compressed. \r
\r
BI_RLE8         Specifies a run-length encoded format for bitmaps with 8 bits\r
per pixel. The compression format is a 2-byte format consisting of a count\r
byte followed by a byte containing a color index.  For more information, see\r
the following Comments section.\r
\r
BI_RLE4         Specifies a run-length encoded format for bitmaps with 4 bits\r
per pixel. The compression format is a 2-byte format consisting of a count\r
byte followed by two word-length color indexes.  For more information, see\r
the following Comments section.\r
\r
biSizeImage     Specifies the size, in bytes, of the image. It is valid to\r
set this member to zero if the bitmap is in the BI_RGB format.\r
\r
biXPelsPerMeter Specifies the horizontal resolution, in pixels per meter, of\r
the target device for the bitmap. An application can use this value to select\r
a bitmap from a resource group that best matches the characteristics of the\r
current device.\r
\r
biYPelsPerMeter Specifies the vertical resolution, in pixels per meter, of\r
the target device for the bitmap.\r
\r
biClrUsed       Specifies the number of color indexes in the color table\r
actually used by the bitmap. If this value is zero, the bitmap uses the\r
maximum number of colors corresponding to the value of the biBitCount member.\r
For more information on the maximum sizes of the color table, see the\r
description of the BITMAPINFO structure earlier in this topic.\r
\r
If the biClrUsed member is nonzero, it specifies the actual number of colors\r
that the graphics engine or device driver will access if the biBitCount\r
member is less than 24. If biBitCount is set to 24, biClrUsed specifies the\r
size of the reference color table used to optimize performance of Windows\r
color palettes.  If the bitmap is a packed bitmap (that is, a bitmap in which\r
the bitmap array immediately follows the BITMAPINFO header and which is\r
referenced by a single pointer), the biClrUsed member must be set to zero or\r
to the actual size of the color table.\r
\r
biClrImportant  Specifies the number of color indexes that are considered\r
important for displaying the bitmap. If this value is zero, all colors are\r
important.\r
\r
Comments\r
\r
The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color\r
table to provide a complete definition of the dimensions and colors of a\r
Windows 3.0 or later DIB. For more information about specifying a Windows 3.0\r
DIB, see the description of the BITMAPINFO structure.\r
\r
An application should use the information stored in the biSize member to\r
locate the color table in a BITMAPINFO structure as follows:\r
\r
pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo->bmiHeader.biSize))\r
\r
Windows supports formats for compressing bitmaps that define their colors\r
with 8 bits per pixel and with 4 bits per pixel. Compression reduces the disk\r
and memory storage required for the bitmap. The following paragraphs describe\r
these formats.\r
\r
BI_RLE8\r
\r
When the biCompression member is set to BI_RLE8, the bitmap is compressed\r
using a run-length encoding format for an 8-bit bitmap. This format may be\r
compressed in either of two modes: encoded and absolute. Both modes can occur\r
anywhere throughout a single bitmap.\r
\r
Encoded mode consists of two bytes: the first byte specifies the number of\r
consecutive pixels to be drawn using the color index contained in the second\r
byte. In addition, the first byte of the pair can be set to zero to indicate\r
an escape that denotes an end of line, end of bitmap, or a delta. The\r
interpretation of the escape depends on the value of the second byte of the\r
pair. The following list shows the meaning of the second byte:\r
\r
Value   Meaning\r
\r
0       End of line. \r
1       End of bitmap. \r
2       Delta. The two bytes following the escape contain unsigned values\r
indicating the horizontal and vertical offset of the next pixel from the\r
current position.\r
\r
Absolute mode is signaled by the first byte set to zero and the second byte\r
set to a value between 0x03 and 0xFF. In absolute mode, the second byte\r
represents the number of bytes that follow, each of which contains the color\r
index of a single pixel. When the second byte is set to 2 or less, the escape\r
has the same meaning as in encoded mode. In absolute mode, each run must be\r
aligned on a word boundary.  The following example shows the hexadecimal\r
values of an 8-bit compressed bitmap:\r
\r
\r
\r
03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01\r
02 78 00 00 09 1E 00 01\r
\r
This bitmap would expand as follows (two-digit values represent a color index\r
for a single pixel):\r
\r
\r
\r
04 04 04\r
06 06 06 06 06\r
45 56 67\r
78 78\r
move current position 5 right and 1 down\r
78 78\r
end of line\r
1E 1E 1E 1E 1E 1E 1E 1E 1E\r
end of RLE bitmap\r
\r
BI_RLE4\r
\r
When the biCompression member is set to BI_RLE4, the bitmap is compressed\r
using a run-length encoding (RLE) format for a 4-bit bitmap, which also uses\r
encoded and absolute modes. In encoded mode, the first byte of the pair\r
contains the number of pixels to be drawn using the color indexes in the\r
second byte. The second byte contains two color indexes, one in its\r
high-order nibble (that is, its low-order four bits) and one in its low-order\r
nibble. The first of the pixels is drawn using the color specified by the\r
high-order nibble, the second is drawn using the color in the low-order\r
nibble, the third is drawn with the color in the high-order nibble, and so\r
on, until all the pixels specified by the first byte have been drawn.  In\r
absolute mode, the first byte contains zero, the second byte contains the\r
number of color indexes that follow, and subsequent bytes contain color\r
indexes in their high- and low-order nibbles, one color index for each pixel.\r
In absolute mode, each run must be aligned on a word boundary. The\r
end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4.\r
\r
The following example shows the hexadecimal values of a 4-bit compressed\r
bitmap:\r
\r
\r
\r
03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01\r
04 78 00 00 09 1E 00 01\r
\r
This bitmap would expand as follows (single-digit values represent a color\r
index for a single pixel):\r
\r
\r
\r
0 4 0\r
0 6 0 6 0\r
4 5 5 6 6 7\r
7 8 7 8\r
move current position 5 right and 1 down\r
7 8 7 8\r
end of line\r
1 E 1 E 1 E 1 E 1\r
end of RLE bitmap\r
\r
See Also\r
\r
BITMAPINFO \r
\r
==============================================================================\r
RGBQUAD (3.0)\r
\r
\r
\r
typedef struct tagRGBQUAD {     /* rgbq */\r
    BYTE    rgbBlue;\r
    BYTE    rgbGreen;\r
    BYTE    rgbRed;\r
    BYTE    rgbReserved;\r
} RGBQUAD;\r
\r
The RGBQUAD structure describes a color consisting of relative intensities of\r
red, green, and blue. The bmiColors member of the BITMAPINFO structure\r
consists of an array of RGBQUAD structures.\r
\r
Member          Description\r
\r
rgbBlue         Specifies the intensity of blue in the color. \r
rgbGreenSpecifies the intensity of green in the color. \r
rgbRed          Specifies the intensity of red in the color. \r
rgbReserved     Not used; must be set to zero. \r
\r
See Also\r
\r
BITMAPINFO \r
\r
==============================================================================\r
RGB (2.x)\r
\r
COLORREF RGB(cRed, cGreen, cBlue)\r
\r
BYTE cRed;      /* red component of color       */\r
BYTE cGreen;    /* green component of color     */\r
BYTE cBlue;     /* blue component of color      */\r
\r
\r
The RGB macro selects an RGB color based on the parameters supplied and the\r
color capabilities of the output device.\r
\r
Parameter       Description\r
\r
cRed    Specifies the intensity of the red color field. \r
cGreen  Specifies the intensity of the green color field. \r
cBlue   Specifies the intensity of the blue color field. \r
\r
Returns\r
\r
The return value specifies the resultant RGB color. \r
\r
Comments\r
\r
The intensity for each argument can range from 0 through 255. If all three\r
intensities are specified as zero, the result is black. If all three\r
intensities are specified as 255, the result is white.\r
\r
Comments\r
\r
The RGB macro is defined in WINDOWS.H as follows: \r
\r
\r
\r
#define RGB(r,g,b)   ((COLORREF)(((BYTE)(r)|((WORD)(g)<<8))| \\r
    (((DWORD)(BYTE)(b))<<16)))\r
\r
See Also\r
\r
GetBValue, GetGValue, GetRValue, PALETTEINDEX, PALETTERGB\r
\r
==============================================================================\r
BITMAPCOREINFO (3.0)\r
\r
\r
\r
typedef struct tagBITMAPCOREINFO {  /* bmci */\r
    BITMAPCOREHEADER bmciHeader;\r
    RGBTRIPLE        bmciColors[1];\r
} BITMAPCOREINFO;\r
\r
The BITMAPCOREINFO structure fully defines the dimensions and color\r
information for a device-independent bitmap (DIB).  Windows applications\r
should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever\r
possible.\r
\r
Member          Description\r
\r
bmciHeader      Specifies a BITMAPCOREHEADER structure that contains\r
information about the dimensions and color format of a DIB.\r
\r
bmciColors      Specifies an array of RGBTRIPLE structures that define the\r
colors in the bitmap.\r
\r
Comments\r
\r
The BITMAPCOREINFO structure describes the dimensions and colors of a bitmap.\r
It is followed immediately in memory by an array of bytes which define the\r
pixels of the bitmap. The bits in the array are packed together, but each\r
scan line must be zero-padded to end on a LONG boundary. Segment boundaries,\r
however, can appear anywhere in the bitmap. The origin of the bitmap is the\r
lower-left corner.\r
\r
The bcBitCount member of the BITMAPCOREHEADER structure determines the number\r
of bits that define each pixel and the maximum number of colors in the\r
bitmap. This member may be set to any of the following values:\r
\r
Value   Meaning\r
\r
1       The bitmap is monochrome, and the bmciColors member must contain two\r
entries. Each bit in the bitmap array represents a pixel. If the bit is\r
clear, the pixel is displayed with the color of the first entry in the\r
bmciColors table. If the bit is set, the pixel has the color of the second\r
entry in the table.\r
\r
4       The bitmap has a maximum of 16 colors, and the bmciColors member\r
contains 16 entries. Each pixel in the bitmap is represented by a four-bit\r
index into the color table.\r
\r
For example, if the first byte in the bitmap is 0x1F, the byte represents two\r
pixels. The first pixel contains the color in the second table entry, and the\r
second pixel contains the color in the sixteenth table entry.\r
\r
8       The bitmap has a maximum of 256 colors, and the bmciColors member\r
contains 256 entries. In this case, each byte in the array represents a\r
single pixel.\r
\r
24      The bitmap has a maximum of 2^24 colors. The bmciColors member is\r
NULL, and each 3-byte sequence in the bitmap array represents the relative\r
intensities of red, green, and blue, respectively, of a pixel.\r
\r
The colors in the bmciColors table should appear in order of importance.\r
Alternatively, for functions that use DIBs, the bmciColors member can be an\r
array of 16-bit unsigned integers that specify an index into the currently\r
realized logical palette instead of explicit RGB values. In this case, an\r
application using the bitmap must call DIB functions with the wUsage\r
parameter set to DIB_PAL_COLORS.\r
\r
Note:   The bmciColors member should not contain palette indexes if the\r
bitmap is to be stored in a file or transferred to another application.\r
Unless the application uses the bitmap exclusively and under its complete\r
control, the bitmap color table should contain explicit RGB values.\r
\r
See Also\r
\r
BITMAPINFO, BITMAPCOREHEADER, RGBTRIPLE \r
\r
\r
==============================================================================\r
BITMAPCOREHEADER (3.0)\r
\r
\r
\r
typedef struct tagBITMAPCOREHEADER {    /* bmch */\r
    DWORD   bcSize;\r
    short   bcWidth;\r
    short   bcHeight;\r
    WORD    bcPlanes;\r
    WORD    bcBitCount;\r
} BITMAPCOREHEADER;\r
\r
The BITMAPCOREHEADER structure contains information about the dimensions and\r
color format of a device-independent bitmap (DIB). Windows applications\r
should use the BITMAPINFOHEADER structure instead of BITMAPCOREHEADER\r
whenever possible.\r
\r
Member          Description\r
\r
bcSize          Specifies the number of bytes required by the\r
BITMAPCOREHEADER structure.\r
\r
bcWidth         Specifies the width of the bitmap, in pixels. \r
bcHeightSpecifies the height of the bitmap, in pixels. \r
\r
bcPlanesSpecifies the number of planes for the target device. This\r
member must be set to 1.\r
\r
bcBitCount      Specifies the number of bits per pixel. This value must be 1,\r
4, 8, or 24.\r
\r
Comments\r
\r
The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a\r
color table to provide a complete definition of the dimensions and colors of\r
a DIB. See the description of the BITMAPCOREINFO structure for more\r
information about specifying a DIB.\r
\r
An application should use the information stored in the bcSize member to\r
locate the color table in a BITMAPCOREINFO structure with a method such as\r
the following:\r
\r
\r
\r
lpColor = ((LPSTR) pBitmapCoreInfo + (UINT) (pBitmapCoreInfo->bcSize))\r
\r
See Also\r
\r
BITMAPCOREINFO, BITMAPINFOHEADER, BITMAPINFOHEADER \r
\r
=============================================================================\r
RGBTRIPLE (3.0)\r
\r
\r
\r
typedef struct tagRGBTRIPLE {   /* rgbt */\r
    BYTE    rgbtBlue;\r
    BYTE    rgbtGreen;\r
    BYTE    rgbtRed;\r
} RGBTRIPLE;\r
\r
The RGBTRIPLE structure describes a color consisting of relative intensities\r
of red, green, and blue. The bmciColors member of the BITMAPCOREINFO\r
structure consists of an array of RGBTRIPLE structures.  Windows applications\r
should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever\r
possible. The BITMAPINFO structure uses an RGBQUAD structure instead of the\r
RGBTRIPLE structure.\r
\r
Member  Description\r
\r
rgbtBlueSpecifies the intensity of blue in the color. \r
rgbtGreen       Specifies the intensity of green in the color. \r
rgbtRed         Specifies the intensity of red in the color.\r
\r
See Also\r
\r
BITMAPCOREINFO, BITMAPINFO, RGBQUAD\r
\r
==============================================================================\r