home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / msbmp / spec / bmp.txt next >
Text File  |  1994-06-01  |  40KB  |  1,044 lines
  1. Microsoft Windows Bitmap Format
  2.  
  3.  
  4.  
  5. Note: the constants BI_RGB, BI_RLE8, and BI_RLE4 have the values 0, 1, and 2,
  6.     respectively.
  7.  
  8. =============================================================================
  9. Graphics File Formats
  10.  
  11. This topic describes the graphics-file formats used by the Microsoft Windows
  12. operating system. Graphics files include bitmap files, icon-resource files,
  13. and cursor-resource files.
  14.  
  15. Bitmap-File Formats
  16.  
  17. Windows bitmap files are stored in a device-independent bitmap (DIB) format
  18. that allows Windows to display the bitmap on any type of display device. The
  19. term "device independent" means that the bitmap specifies pixel color in a
  20. form independent of the method used by a display to represent color. The
  21. default filename extension of a Windows DIB file is .BMP.
  22.  
  23. Bitmap-File Structures
  24.  
  25. Each bitmap file contains a bitmap-file header, a bitmap-information header,
  26. a color table, and an array of bytes that defines the bitmap bits. The file
  27. has the following form:
  28.  
  29. BITMAPFILEHEADER bmfh;
  30. BITMAPINFOHEADER bmih;
  31. RGBQUAD          aColors[];
  32. BYTE             aBitmapBits[];
  33.  
  34. The bitmap-file header contains information about the type, size, and layout
  35. of a device-independent bitmap file. The header is defined as a
  36. BITMAPFILEHEADER structure.
  37.  
  38. The bitmap-information header, defined as a BITMAPINFOHEADER structure,
  39. specifies the dimensions, compression type, and color format for the bitmap.
  40.  
  41. The color table, defined as an array of RGBQUAD structures, contains as many
  42. elements as there are colors in the bitmap. The color table is not present
  43. for bitmaps with 24 color bits because each pixel is represented by 24-bit
  44. red-green-blue (RGB) values in the actual bitmap data area. The colors in the
  45. table should appear in order of importance. This helps a display driver
  46. render a bitmap on a device that cannot display as many colors as there are
  47. in the bitmap. If the DIB is in Windows version 3.0 or later format, the
  48. driver can use the biClrImportant member of the BITMAPINFOHEADER structure to
  49. determine which colors are important.
  50.  
  51. The BITMAPINFO structure can be used to represent a combined
  52. bitmap-information header and color table.  The bitmap bits, immediately
  53. following the color table, consist of an array of BYTE values representing
  54. consecutive rows, or "scan lines," of the bitmap. Each scan line consists of
  55. consecutive bytes representing the pixels in the scan line, in left-to-right
  56. order. The number of bytes representing a scan line depends on the color
  57. format and the width, in pixels, of the bitmap. If necessary, a scan line
  58. must be zero-padded to end on a 32-bit boundary. However, segment boundaries
  59. can appear anywhere in the bitmap. The scan lines in the bitmap are stored
  60. from bottom up. This means that the first byte in the array represents the
  61. pixels in the lower-left corner of the bitmap and the last byte represents
  62. the pixels in the upper-right corner.
  63.  
  64. The biBitCount member of the BITMAPINFOHEADER structure determines the number
  65. of bits that define each pixel and the maximum number of colors in the
  66. bitmap. These members can have any of the following values:
  67.  
  68. Value    Meaning
  69.  
  70. 1    Bitmap is monochrome and the color table contains two entries. Each
  71. bit in the bitmap array represents a pixel. If the bit is clear, the pixel is
  72. displayed with the color of the first entry in the color table. If the bit is
  73. set, the pixel has the color of the second entry in the table.
  74.  
  75. 4    Bitmap has a maximum of 16 colors. Each pixel in the bitmap is
  76. represented by a 4-bit index into the color table. For example, if the first
  77. byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel
  78. contains the color in the second table entry, and the second pixel contains
  79. the color in the sixteenth table entry.
  80.  
  81. 8    Bitmap has a maximum of 256 colors. Each pixel in the bitmap is
  82. represented by a 1-byte index into the color table. For example, if the first
  83. byte in the bitmap is 0x1F, the first pixel has the color of the
  84. thirty-second table entry.
  85.  
  86. 24    Bitmap has a maximum of 2^24 colors. The bmiColors (or bmciColors)
  87. member is NULL, and each 3-byte sequence in the bitmap array represents the
  88. relative intensities of red, green, and blue, respectively, for a pixel.
  89.  
  90. The biClrUsed member of the BITMAPINFOHEADER structure specifies the number
  91. of color indexes in the color table actually used by the bitmap. If the
  92. biClrUsed member is set to zero, the bitmap uses the maximum number of colors
  93. corresponding to the value of the biBitCount member.  An alternative form of
  94. bitmap file uses the BITMAPCOREINFO, BITMAPCOREHEADER, and RGBTRIPLE
  95. structures.
  96.  
  97. Bitmap Compression
  98.  
  99. Windows versions 3.0 and later support run-length encoded (RLE) formats for
  100. compressing bitmaps that use 4 bits per pixel and 8 bits per pixel.
  101. Compression reduces the disk and memory storage required for a bitmap.
  102.  
  103. Compression of 8-Bits-per-Pixel Bitmaps
  104.  
  105. When the biCompression member of the BITMAPINFOHEADER structure is set to
  106. BI_RLE8, the DIB is compressed using a run-length encoded format for a
  107. 256-color bitmap. This format uses two modes: encoded mode and absolute mode.
  108. Both modes can occur anywhere throughout a single bitmap.
  109.  
  110. Encoded Mode
  111.  
  112. A unit of information in encoded mode consists of two bytes. The first byte
  113. specifies the number of consecutive pixels to be drawn using the color index
  114. contained in the second byte.  The first byte of the pair can be set to zero
  115. to indicate an escape that denotes the end of a line, the end of the bitmap,
  116. or a delta. The interpretation of the escape depends on the value of the
  117. second byte of the pair, which must be in the range 0x00 through 0x02.
  118. Following are the meanings of the escape values that can be used in the
  119. second byte:
  120.  
  121. Second byte    Meaning
  122.  
  123. 0    End of line. 
  124. 1    End of bitmap. 
  125. 2    Delta. The two bytes following the escape contain unsigned values
  126. indicating the horizontal and vertical offsets of the next pixel from the
  127. current position.
  128.  
  129. Absolute Mode
  130.  
  131. Absolute mode is signaled by the first byte in the pair being set to zero and
  132. the second byte to a value between 0x03 and 0xFF. The second byte represents
  133. the number of bytes that follow, each of which contains the color index of a
  134. single pixel. Each run must be aligned on a word boundary.  Following is an
  135. example of an 8-bit RLE bitmap (the two-digit hexadecimal values in the
  136. second column represent a color index for a single pixel):
  137.  
  138. Compressed data        Expanded data
  139.  
  140. 03 04            04 04 04 
  141. 05 06            06 06 06 06 06 
  142. 00 03 45 56 67 00    45 56 67 
  143. 02 78            78 78 
  144. 00 02 05 01        Move 5 right and 1 down 
  145. 02 78            78 78 
  146. 00 00            End of line 
  147. 09 1E            1E 1E 1E 1E 1E 1E 1E 1E 1E 
  148. 00 01            End of RLE bitmap 
  149.  
  150. Compression of 4-Bits-per-Pixel Bitmaps
  151.  
  152. When the biCompression member of the BITMAPINFOHEADER structure is set to
  153. BI_RLE4, the DIB is compressed using a run-length encoded format for a
  154. 16-color bitmap. This format uses two modes: encoded mode and absolute mode.
  155.  
  156. Encoded Mode
  157.  
  158. A unit of information in encoded mode consists of two bytes. The first byte
  159. of the pair contains the number of pixels to be drawn using the color indexes
  160. in the second byte.
  161.  
  162. The second byte contains two color indexes, one in its high-order nibble
  163. (that is, its low-order 4 bits) and one in its low-order nibble.
  164.  
  165. The first pixel is drawn using the color specified by the high-order nibble,
  166. the second is drawn using the color in the low-order nibble, the third is
  167. drawn with the color in the high-order nibble, and so on, until all the
  168. pixels specified by the first byte have been drawn.
  169.  
  170. The first byte of the pair can be set to zero to indicate an escape that
  171. denotes the end of a line, the end of the bitmap, or a delta. The
  172. interpretation of the escape depends on the value of the second byte of the
  173. pair. In encoded mode, the second byte has a value in the range 0x00 through
  174. 0x02. The meaning of these values is the same as for a DIB with 8 bits per
  175. pixel.
  176.  
  177. Absolute Mode
  178.  
  179. In absolute mode, the first byte contains zero, the second byte contains the
  180. number of color indexes that follow, and subsequent bytes contain color
  181. indexes in their high- and low-order nibbles, one color index for each pixel.
  182. Each run must be aligned on a word boundary.
  183.  
  184. Following is an example of a 4-bit RLE bitmap (the one-digit hexadecimal
  185. values in the second column represent a color index for a single pixel):
  186.  
  187. Compressed data        Expanded data
  188.  
  189. 03 04            0 4 0 
  190. 05 06            0 6 0 6 0 
  191. 00 06 45 56 67 00    4 5 5 6 6 7 
  192. 04 78            7 8 7 8 
  193. 00 02 05 01        Move 5 right and 1 down 
  194. 04 78            7 8 7 8 
  195. 00 00            End of line 
  196. 09 1E            1 E 1 E 1 E 1 E 1 
  197. 00 01            End of RLE bitmap 
  198.  
  199. Bitmap Example
  200.  
  201. The following example is a text dump of a 16-color bitmap (4 bits per pixel):
  202.  
  203. Win3DIBFile
  204.               BitmapFileHeader
  205.                   Type       19778
  206.                   Size       3118
  207.                   Reserved1  0
  208.                   Reserved2  0
  209.                   OffsetBits 118
  210.               BitmapInfoHeader
  211.                   Size            40
  212.                   Width           80
  213.                   Height          75
  214.                   Planes          1
  215.                   BitCount        4
  216.                   Compression     0
  217.                   SizeImage       3000
  218.  
  219.                   XPelsPerMeter   0
  220.                   YPelsPerMeter   0
  221.                   ColorsUsed      16
  222.                   ColorsImportant 16
  223.               Win3ColorTable
  224.                   Blue  Green  Red  Unused
  225. [00000000]        84    252    84   0
  226. [00000001]        252   252    84   0
  227. [00000002]        84    84     252  0
  228. [00000003]        252   84     252  0
  229. [00000004]        84    252    252  0
  230. [00000005]        252   252    252  0
  231. [00000006]        0     0      0    0
  232. [00000007]        168   0      0    0
  233. [00000008]        0     168    0    0
  234. [00000009]        168   168    0    0
  235. [0000000A]        0     0      168  0
  236. [0000000B]        168   0      168  0
  237. [0000000C]        0     168    168  0
  238. [0000000D]        168   168    168  0
  239. [0000000E]        84    84     84   0
  240. [0000000F]        252   84     84   0
  241.               Image
  242.     .
  243.     .                                           Bitmap data
  244.     .
  245.  
  246. Icon-Resource File Format
  247.  
  248. An icon-resource file contains image data for icons used by Windows
  249. applications. The file consists of an icon directory identifying the number
  250. and types of icon images in the file, plus one or more icon images. The
  251. default filename extension for an icon-resource file is .ICO.
  252.  
  253. Icon Directory
  254.  
  255. Each icon-resource file starts with an icon directory. The icon directory,
  256. defined as an ICONDIR structure, specifies the number of icons in the
  257. resource and the dimensions and color format of each icon image. The ICONDIR
  258. structure has the following form:
  259.  
  260.  
  261.  
  262. typedef struct ICONDIR {
  263.     WORD          idReserved;
  264.     WORD          idType;
  265.     WORD          idCount;
  266.     ICONDIRENTRY  idEntries[1];
  267. } ICONHEADER;
  268.  
  269. Following are the members in the ICONDIR structure: 
  270.  
  271. idReserved    Reserved; must be zero. 
  272. idType        Specifies the resource type. This member is set to 1. 
  273. idCount        Specifies the number of entries in the directory. 
  274. idEntries    Specifies an array of ICONDIRENTRY structures containing
  275. information about individual icons. The idCount member specifies the number
  276. of structures in the array.
  277.  
  278. The ICONDIRENTRY structure specifies the dimensions and color format for an
  279. icon. The structure has the following form:
  280.  
  281.  
  282.  
  283. struct IconDirectoryEntry {
  284.     BYTE  bWidth;
  285.     BYTE  bHeight;
  286.     BYTE  bColorCount;
  287.     BYTE  bReserved;
  288.     WORD  wPlanes;
  289.     WORD  wBitCount;
  290.     DWORD dwBytesInRes;
  291.     DWORD dwImageOffset;
  292. };
  293.  
  294. Following are the members in the ICONDIRENTRY structure: 
  295.  
  296. bWidth        Specifies the width of the icon, in pixels. Acceptable values
  297. are 16, 32, and 64.
  298.  
  299. bHeight        Specifies the height of the icon, in pixels. Acceptable
  300. values are 16, 32, and 64.
  301.  
  302. bColorCount    Specifies the number of colors in the icon. Acceptable values
  303. are 2, 8, and 16.
  304.  
  305. bReserved    Reserved; must be zero. 
  306. wPlanes        Specifies the number of color planes in the icon bitmap. 
  307. wBitCount    Specifies the number of bits in the icon bitmap. 
  308. dwBytesInRes    Specifies the size of the resource, in bytes. 
  309. dwImageOffset    Specifies the offset, in bytes, from the beginning of the
  310. file to the icon image.
  311.  
  312. Icon Image
  313.  
  314. Each icon-resource file contains one icon image for each image identified in
  315. the icon directory. An icon image consists of an icon-image header, a color
  316. table, an XOR mask, and an AND mask. The icon image has the following form:
  317.  
  318.  
  319.  
  320. BITMAPINFOHEADER    icHeader;
  321. RGBQUAD             icColors[];
  322. BYTE                icXOR[];
  323. BYTE                icAND[];
  324.  
  325. The icon-image header, defined as a BITMAPINFOHEADER structure, specifies the
  326. dimensions and color format of the icon bitmap. Only the biSize through
  327. biBitCount members and the biSizeImage member are used. All other members
  328. (such as biCompression and biClrImportant) must be set to zero.
  329.  
  330. The color table, defined as an array of RGBQUAD structures, specifies the
  331. colors used in the XOR mask. As with the color table in a bitmap file, the
  332. biBitCount member in the icon-image header determines the number of elements
  333. in the array. For more information about the color table, see Section 1.1,
  334. "Bitmap-File Formats."
  335.  
  336. The XOR mask, immediately following the color table, is an array of BYTE
  337. values representing consecutive rows of a bitmap. The bitmap defines the
  338. basic shape and color of the icon image. As with the bitmap bits in a bitmap
  339. file, the bitmap data in an icon-resource file is organized in scan lines,
  340. with each byte representing one or more pixels, as defined by the color
  341. format. For more information about these bitmap bits, see Section 1.1,
  342. "Bitmap-File Formats."
  343.  
  344. The AND mask, immediately following the XOR mask, is an array of BYTE values,
  345. representing a monochrome bitmap with the same width and height as the XOR
  346. mask. The array is organized in scan lines, with each byte representing 8
  347. pixels.
  348.  
  349. When Windows draws an icon, it uses the AND and XOR masks to combine the icon
  350. image with the pixels already on the display surface. Windows first applies
  351. the AND mask by using a bitwise AND operation; this preserves or removes
  352. existing pixel color.  Windows then applies the XOR mask by using a bitwise
  353. XOR operation. This sets the final color for each pixel.
  354.  
  355. The following illustration shows the XOR and AND masks that create a
  356. monochrome icon (measuring 8 pixels by 8 pixels) in the form of an uppercase
  357. K:
  358.  
  359. Windows Icon Selection
  360.  
  361. Windows detects the resolution of the current display and matches it against
  362. the width and height specified for each version of the icon image. If Windows
  363. determines that there is an exact match between an icon image and the current
  364. device, it uses the matching image. Otherwise, it selects the closest match
  365. and stretches the image to the proper size.
  366.  
  367. If an icon-resource file contains more than one image for a particular
  368. resolution, Windows uses the icon image that most closely matches the color
  369. capabilities of the current display. If no image matches the device
  370. capabilities exactly, Windows selects the image that has the greatest number
  371. of colors without exceeding the number of display colors. If all images
  372. exceed the color capabilities of the current display, Windows uses the icon
  373. image with the least number of colors.
  374.  
  375.  
  376.  
  377. Cursor-Resource File Format
  378.  
  379. A cursor-resource file contains image data for cursors used by Windows
  380. applications. The file consists of a cursor directory identifying the number
  381. and types of cursor images in the file, plus one or more cursor images. The
  382. default filename extension for a cursor-resource file is .CUR.
  383.  
  384. Cursor Directory
  385.  
  386. Each cursor-resource file starts with a cursor directory. The cursor
  387. directory, defined as a CURSORDIR structure, specifies the number of cursors
  388. in the file and the dimensions and color format of each cursor image. The
  389. CURSORDIR structure has the following form:
  390.  
  391.  
  392. typedef struct _CURSORDIR {
  393.     WORD           cdReserved;
  394.     WORD           cdType;
  395.     WORD           cdCount;
  396.     CURSORDIRENTRY cdEntries[];
  397. } CURSORDIR;
  398.  
  399. Following are the members in the CURSORDIR structure: 
  400.  
  401. cdReserved    Reserved; must be zero. 
  402. cdType        Specifies the resource type. This member must be set to 2. 
  403. cdCount        Specifies the number of cursors in the file. 
  404. cdEntries    Specifies an array of CURSORDIRENTRY structures containing
  405. information about individual cursors. The cdCount member specifies the number
  406. of structures in the array.
  407.  
  408. A CURSORDIRENTRY structure specifies the dimensions and color format of a
  409. cursor image. The structure has the following form:
  410.  
  411.  
  412.  
  413. typedef struct _CURSORDIRENTRY {
  414.     BYTE  bWidth;
  415.     BYTE  bHeight;
  416.     BYTE  bColorCount;
  417.     BYTE  bReserved;
  418.     WORD  wXHotspot;
  419.     WORD  wYHotspot;
  420.     DWORD lBytesInRes;
  421.     DWORD dwImageOffset;
  422. } CURSORDIRENTRY;
  423.  
  424. Following are the members in the CURSORDIRENTRY structure: 
  425.  
  426. bWidth        Specifies the width of the cursor, in pixels. 
  427. bHeight        Specifies the height of the cursor, in pixels. 
  428. bColorCount    Reserved; must be zero. 
  429. bReserved    Reserved; must be zero. 
  430. wXHotspot    Specifies the x-coordinate, in pixels, of the hot spot. 
  431. wYHotspot    Specifies the y-coordinate, in pixels, of the hot spot. 
  432. lBytesInRes    Specifies the size of the resource, in bytes. 
  433. dwImageOffset    Specifies the offset, in bytes, from the start of the file to
  434. the cursor image.
  435.  
  436. Cursor Image
  437.  
  438. Each cursor-resource file contains one cursor image for each image identified
  439. in the cursor directory. A cursor image consists of a cursor-image header, a
  440. color table, an XOR mask, and an AND mask. The cursor image has the following
  441. form:
  442.  
  443.  
  444.  
  445. BITMAPINFOHEADER    crHeader;
  446. RGBQUAD             crColors[];
  447. BYTE                crXOR[];
  448. BYTE                crAND[];
  449.  
  450. The cursor hot spot is a single pixel in the cursor bitmap that Windows uses
  451. to track the cursor. The crXHotspot and crYHotspot members specify the x- and
  452. y-coordinates of the cursor hot spot. These coordinates are 16-bit integers.
  453.  
  454. The cursor-image header, defined as a BITMAPINFOHEADER structure, specifies
  455. the dimensions and color format of the cursor bitmap. Only the biSize through
  456. biBitCount members and the biSizeImage member are used. The biHeight member
  457. specifies the combined height of the XOR and AND masks for the cursor. This
  458. value is twice the height of the XOR mask. The biPlanes and biBitCount
  459. members must be 1. All other members (such as biCompression and
  460. biClrImportant) must be set to zero.
  461.  
  462. The color table, defined as an array of RGBQUAD structures, specifies the
  463. colors used in the XOR mask. For a cursor image, the table contains exactly
  464. two structures, since the biBitCount member in the cursor-image header is
  465. always 1.
  466.  
  467. The XOR mask, immediately following the color table, is an array of BYTE
  468. values representing consecutive rows of a bitmap. The bitmap defines the
  469. basic shape and color of the cursor image. As with the bitmap bits in a
  470. bitmap file, the bitmap data in a cursor-resource file is organized in scan
  471. lines, with each byte representing one or more pixels, as defined by the
  472. color format. For more information about these bitmap bits, see Section 1.1,
  473. "Bitmap-File Formats."
  474.  
  475. The AND mask, immediately following the XOR mask, is an array of BYTE values
  476. representing a monochrome bitmap with the same width and height as the XOR
  477. mask. The array is organized in scan lines, with each byte representing 8
  478. pixels.
  479.  
  480. When Windows draws a cursor, it uses the AND and XOR masks to combine the
  481. cursor image with the pixels already on the display surface. Windows first
  482. applies the AND mask by using a bitwise AND operation; this preserves or
  483. removes existing pixel color.  Window then applies the XOR mask by using a
  484. bitwise XOR operation. This sets the final color for each pixel.
  485.  
  486. The following illustration shows the XOR and the AND masks that create a
  487. cursor (measuring 8 pixels by 8 pixels) in the form of an arrow:
  488.  
  489. Following are the bit-mask values necessary to produce black, white,
  490. inverted, and transparent results:
  491.  
  492. Pixel result    AND mask    XOR mask
  493.  
  494. Black        0        0 
  495. White        0        1 
  496. Transparent    1        0 
  497. Inverted    1        1 
  498.  
  499. Windows Cursor Selection
  500.  
  501. If a cursor-resource file contains more than one cursor image, Windows
  502. determines the best match for a particular display by examining the width and
  503. height of the cursor images.
  504.  
  505.  
  506. ==============================================================================
  507.  
  508.  
  509. BITMAPFILEHEADER (3.0)
  510.  
  511.  
  512.  
  513. typedef struct tagBITMAPFILEHEADER {    /* bmfh */
  514.     UINT    bfType;
  515.     DWORD   bfSize;
  516.     UINT    bfReserved1;
  517.     UINT    bfReserved2;
  518.     DWORD   bfOffBits;
  519. } BITMAPFILEHEADER;
  520.  
  521. The BITMAPFILEHEADER structure contains information about the type, size, and
  522. layout of a device-independent bitmap (DIB) file.
  523.  
  524. Member        Description
  525.  
  526. bfType        Specifies the type of file. This member must be BM. 
  527. bfSize        Specifies the size of the file, in bytes. 
  528. bfReserved1    Reserved; must be set to zero. 
  529. bfReserved2    Reserved; must be set to zero. 
  530. bfOffBits    Specifies the byte offset from the BITMAPFILEHEADER structure
  531. to the actual bitmap data in the file.
  532.  
  533. Comments
  534.  
  535. A BITMAPINFO or BITMAPCOREINFO structure immediately follows the
  536. BITMAPFILEHEADER structure in the DIB file.
  537.  
  538. See Also
  539.  
  540. BITMAPCOREINFO, BITMAPINFO 
  541.  
  542.  
  543. ==============================================================================
  544. BITMAPINFO (3.0)
  545.  
  546.  
  547.  
  548. typedef struct tagBITMAPINFO {  /* bmi */
  549.     BITMAPINFOHEADER    bmiHeader;
  550.     RGBQUAD             bmiColors[1];
  551. } BITMAPINFO;
  552.  
  553. The BITMAPINFO structure fully defines the dimensions and color information
  554. for a Windows 3.0 or later device-independent bitmap (DIB).
  555.  
  556. Member        Description
  557.  
  558. bmiHeader    Specifies a BITMAPINFOHEADER structure that contains
  559. information about the dimensions and color format of a DIB.
  560.  
  561. bmiColors    Specifies an array of RGBQUAD structures that define the
  562. colors in the bitmap.
  563.  
  564. Comments
  565.  
  566. A Windows 3.0 or later DIB consists of two distinct parts: a BITMAPINFO
  567. structure, which describes the dimensions and colors of the bitmap, and an
  568. array of bytes defining the pixels of the bitmap. The bits in the array are
  569. packed together, but each scan line must be zero-padded to end on a LONG
  570. boundary. Segment boundaries, however, can appear anywhere in the bitmap. The
  571. origin of the bitmap is the lower-left corner.
  572.  
  573. The biBitCount member of the BITMAPINFOHEADER structure determines the number
  574. of bits which define each pixel and the maximum number of colors in the
  575. bitmap. This member may be set to any of the following values:
  576.  
  577. Value    Meaning
  578.  
  579. 1    The bitmap is monochrome, and the bmciColors member must contain two
  580. entries. Each bit in the bitmap array represents a pixel. If the bit is
  581. clear, the pixel is displayed with the color of the first entry in the
  582. bmciColors table. If the bit is set, the pixel has the color of the second
  583. entry in the table.
  584.  
  585. 4    The bitmap has a maximum of 16 colors, and the bmciColors member
  586. contains 16 entries. Each pixel in the bitmap is represented by a four-bit
  587. index into the color table.
  588.  
  589. For example, if the first byte in the bitmap is 0x1F, the byte represents two
  590. pixels. The first pixel contains the color in the second table entry, and the
  591. second pixel contains the color in the sixteenth table entry.
  592.  
  593. 8    The bitmap has a maximum of 256 colors, and the bmciColors member
  594. contains 256 entries. In this case, each byte in the array represents a
  595. single pixel.
  596.  
  597. 24    The bitmap has a maximum of 2^24 colors. The bmciColors member is
  598. NULL, and each 3-byte sequence in the bitmap array represents the relative
  599. intensities of red, green, and blue, respectively, of a pixel.
  600.  
  601. The biClrUsed member of the BITMAPINFOHEADER structure specifies the number
  602. of color indexes in the color table actually used by the bitmap. If the
  603. biClrUsed member is set to zero, the bitmap uses the maximum number of colors
  604. corresponding to the value of the biBitCount member.
  605.  
  606. The colors in the bmiColors table should appear in order of importance.
  607. Alternatively, for functions that use DIBs, the bmiColors member can be an
  608. array of 16-bit unsigned integers that specify an index into the currently
  609. realized logical palette instead of explicit RGB values. In this case, an
  610. application using the bitmap must call DIB functions with the wUsage
  611. parameter set to DIB_PAL_COLORS.
  612.  
  613. Note:    The bmiColors member should not contain palette indexes if the bitmap
  614. is to be stored in a file or transferred to another application. Unless the
  615. application uses the bitmap exclusively and under its complete control, the
  616. bitmap color table should contain explicit RGB values.
  617.  
  618. See Also
  619.  
  620. BITMAPINFOHEADER, RGBQUAD 
  621.  
  622. ==============================================================================
  623. BITMAPINFOHEADER (3.0)
  624.  
  625.  
  626.  
  627. typedef struct tagBITMAPINFOHEADER {    /* bmih */
  628.     DWORD   biSize;
  629.     LONG    biWidth;
  630.     LONG    biHeight;
  631.     WORD    biPlanes;
  632.     WORD    biBitCount;
  633.     DWORD   biCompression;
  634.     DWORD   biSizeImage;
  635.     LONG    biXPelsPerMeter;
  636.     LONG    biYPelsPerMeter;
  637.     DWORD   biClrUsed;
  638.     DWORD   biClrImportant;
  639. } BITMAPINFOHEADER;
  640.  
  641. The BITMAPINFOHEADER structure contains information about the dimensions and
  642. color format of a Windows 3.0 or later device-independent bitmap (DIB).
  643.  
  644. Member        Description
  645.  
  646. biSize        Specifies the number of bytes required by the
  647. BITMAPINFOHEADER structure.
  648.  
  649. biWidth        Specifies the width of the bitmap, in pixels. 
  650. biHeight    Specifies the height of the bitmap, in pixels. 
  651.  
  652. biPlanes    Specifies the number of planes for the target device. This
  653. member must be set to 1.
  654.  
  655. biBitCount    Specifies the number of bits per pixel. This value must be 1,
  656. 4, 8, or 24.
  657.  
  658. biCompression    Specifies the type of compression for a compressed bitmap. It
  659. can be one of the following values:
  660.  
  661. Value        Meaning
  662.  
  663. BI_RGB        Specifies that the bitmap is not compressed. 
  664.  
  665. BI_RLE8        Specifies a run-length encoded format for bitmaps with 8 bits
  666. per pixel. The compression format is a 2-byte format consisting of a count
  667. byte followed by a byte containing a color index.  For more information, see
  668. the following Comments section.
  669.  
  670. BI_RLE4        Specifies a run-length encoded format for bitmaps with 4 bits
  671. per pixel. The compression format is a 2-byte format consisting of a count
  672. byte followed by two word-length color indexes.  For more information, see
  673. the following Comments section.
  674.  
  675. biSizeImage    Specifies the size, in bytes, of the image. It is valid to
  676. set this member to zero if the bitmap is in the BI_RGB format.
  677.  
  678. biXPelsPerMeter    Specifies the horizontal resolution, in pixels per meter, of
  679. the target device for the bitmap. An application can use this value to select
  680. a bitmap from a resource group that best matches the characteristics of the
  681. current device.
  682.  
  683. biYPelsPerMeter    Specifies the vertical resolution, in pixels per meter, of
  684. the target device for the bitmap.
  685.  
  686. biClrUsed    Specifies the number of color indexes in the color table
  687. actually used by the bitmap. If this value is zero, the bitmap uses the
  688. maximum number of colors corresponding to the value of the biBitCount member.
  689. For more information on the maximum sizes of the color table, see the
  690. description of the BITMAPINFO structure earlier in this topic.
  691.  
  692. If the biClrUsed member is nonzero, it specifies the actual number of colors
  693. that the graphics engine or device driver will access if the biBitCount
  694. member is less than 24. If biBitCount is set to 24, biClrUsed specifies the
  695. size of the reference color table used to optimize performance of Windows
  696. color palettes.  If the bitmap is a packed bitmap (that is, a bitmap in which
  697. the bitmap array immediately follows the BITMAPINFO header and which is
  698. referenced by a single pointer), the biClrUsed member must be set to zero or
  699. to the actual size of the color table.
  700.  
  701. biClrImportant    Specifies the number of color indexes that are considered
  702. important for displaying the bitmap. If this value is zero, all colors are
  703. important.
  704.  
  705. Comments
  706.  
  707. The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color
  708. table to provide a complete definition of the dimensions and colors of a
  709. Windows 3.0 or later DIB. For more information about specifying a Windows 3.0
  710. DIB, see the description of the BITMAPINFO structure.
  711.  
  712. An application should use the information stored in the biSize member to
  713. locate the color table in a BITMAPINFO structure as follows:
  714.  
  715. pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo->bmiHeader.biSize))
  716.  
  717. Windows supports formats for compressing bitmaps that define their colors
  718. with 8 bits per pixel and with 4 bits per pixel. Compression reduces the disk
  719. and memory storage required for the bitmap. The following paragraphs describe
  720. these formats.
  721.  
  722. BI_RLE8
  723.  
  724. When the biCompression member is set to BI_RLE8, the bitmap is compressed
  725. using a run-length encoding format for an 8-bit bitmap. This format may be
  726. compressed in either of two modes: encoded and absolute. Both modes can occur
  727. anywhere throughout a single bitmap.
  728.  
  729. Encoded mode consists of two bytes: the first byte specifies the number of
  730. consecutive pixels to be drawn using the color index contained in the second
  731. byte. In addition, the first byte of the pair can be set to zero to indicate
  732. an escape that denotes an end of line, end of bitmap, or a delta. The
  733. interpretation of the escape depends on the value of the second byte of the
  734. pair. The following list shows the meaning of the second byte:
  735.  
  736. Value    Meaning
  737.  
  738. 0    End of line. 
  739. 1    End of bitmap. 
  740. 2    Delta. The two bytes following the escape contain unsigned values
  741. indicating the horizontal and vertical offset of the next pixel from the
  742. current position.
  743.  
  744. Absolute mode is signaled by the first byte set to zero and the second byte
  745. set to a value between 0x03 and 0xFF. In absolute mode, the second byte
  746. represents the number of bytes that follow, each of which contains the color
  747. index of a single pixel. When the second byte is set to 2 or less, the escape
  748. has the same meaning as in encoded mode. In absolute mode, each run must be
  749. aligned on a word boundary.  The following example shows the hexadecimal
  750. values of an 8-bit compressed bitmap:
  751.  
  752.  
  753.  
  754. 03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01
  755. 02 78 00 00 09 1E 00 01
  756.  
  757. This bitmap would expand as follows (two-digit values represent a color index
  758. for a single pixel):
  759.  
  760.  
  761.  
  762. 04 04 04
  763. 06 06 06 06 06
  764. 45 56 67
  765. 78 78
  766. move current position 5 right and 1 down
  767. 78 78
  768. end of line
  769. 1E 1E 1E 1E 1E 1E 1E 1E 1E
  770. end of RLE bitmap
  771.  
  772. BI_RLE4
  773.  
  774. When the biCompression member is set to BI_RLE4, the bitmap is compressed
  775. using a run-length encoding (RLE) format for a 4-bit bitmap, which also uses
  776. encoded and absolute modes. In encoded mode, the first byte of the pair
  777. contains the number of pixels to be drawn using the color indexes in the
  778. second byte. The second byte contains two color indexes, one in its
  779. high-order nibble (that is, its low-order four bits) and one in its low-order
  780. nibble. The first of the pixels is drawn using the color specified by the
  781. high-order nibble, the second is drawn using the color in the low-order
  782. nibble, the third is drawn with the color in the high-order nibble, and so
  783. on, until all the pixels specified by the first byte have been drawn.  In
  784. absolute mode, the first byte contains zero, the second byte contains the
  785. number of color indexes that follow, and subsequent bytes contain color
  786. indexes in their high- and low-order nibbles, one color index for each pixel.
  787. In absolute mode, each run must be aligned on a word boundary. The
  788. end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4.
  789.  
  790. The following example shows the hexadecimal values of a 4-bit compressed
  791. bitmap:
  792.  
  793.  
  794.  
  795. 03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01
  796. 04 78 00 00 09 1E 00 01
  797.  
  798. This bitmap would expand as follows (single-digit values represent a color
  799. index for a single pixel):
  800.  
  801.  
  802.  
  803. 0 4 0
  804. 0 6 0 6 0
  805. 4 5 5 6 6 7
  806. 7 8 7 8
  807. move current position 5 right and 1 down
  808. 7 8 7 8
  809. end of line
  810. 1 E 1 E 1 E 1 E 1
  811. end of RLE bitmap
  812.  
  813. See Also
  814.  
  815. BITMAPINFO 
  816.  
  817. ==============================================================================
  818. RGBQUAD (3.0)
  819.  
  820.  
  821.  
  822. typedef struct tagRGBQUAD {     /* rgbq */
  823.     BYTE    rgbBlue;
  824.     BYTE    rgbGreen;
  825.     BYTE    rgbRed;
  826.     BYTE    rgbReserved;
  827. } RGBQUAD;
  828.  
  829. The RGBQUAD structure describes a color consisting of relative intensities of
  830. red, green, and blue. The bmiColors member of the BITMAPINFO structure
  831. consists of an array of RGBQUAD structures.
  832.  
  833. Member        Description
  834.  
  835. rgbBlue        Specifies the intensity of blue in the color. 
  836. rgbGreen    Specifies the intensity of green in the color. 
  837. rgbRed        Specifies the intensity of red in the color. 
  838. rgbReserved    Not used; must be set to zero. 
  839.  
  840. See Also
  841.  
  842. BITMAPINFO 
  843.  
  844. ==============================================================================
  845. RGB (2.x)
  846.  
  847. COLORREF RGB(cRed, cGreen, cBlue)
  848.  
  849. BYTE cRed;    /* red component of color    */
  850. BYTE cGreen;    /* green component of color    */
  851. BYTE cBlue;    /* blue component of color    */
  852.  
  853.  
  854. The RGB macro selects an RGB color based on the parameters supplied and the
  855. color capabilities of the output device.
  856.  
  857. Parameter    Description
  858.  
  859. cRed    Specifies the intensity of the red color field. 
  860. cGreen    Specifies the intensity of the green color field. 
  861. cBlue    Specifies the intensity of the blue color field. 
  862.  
  863. Returns
  864.  
  865. The return value specifies the resultant RGB color. 
  866.  
  867. Comments
  868.  
  869. The intensity for each argument can range from 0 through 255. If all three
  870. intensities are specified as zero, the result is black. If all three
  871. intensities are specified as 255, the result is white.
  872.  
  873. Comments
  874.  
  875. The RGB macro is defined in WINDOWS.H as follows: 
  876.  
  877.  
  878.  
  879. #define RGB(r,g,b)   ((COLORREF)(((BYTE)(r)|((WORD)(g)<<8))| \
  880.     (((DWORD)(BYTE)(b))<<16)))
  881.  
  882. See Also
  883.  
  884. GetBValue, GetGValue, GetRValue, PALETTEINDEX, PALETTERGB 
  885.  
  886. ==============================================================================
  887. BITMAPCOREINFO (3.0)
  888.  
  889.  
  890.  
  891. typedef struct tagBITMAPCOREINFO {  /* bmci */
  892.     BITMAPCOREHEADER bmciHeader;
  893.     RGBTRIPLE        bmciColors[1];
  894. } BITMAPCOREINFO;
  895.  
  896. The BITMAPCOREINFO structure fully defines the dimensions and color
  897. information for a device-independent bitmap (DIB).  Windows applications
  898. should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever
  899. possible.
  900.  
  901. Member        Description
  902.  
  903. bmciHeader    Specifies a BITMAPCOREHEADER structure that contains
  904. information about the dimensions and color format of a DIB.
  905.  
  906. bmciColors    Specifies an array of RGBTRIPLE structures that define the
  907. colors in the bitmap.
  908.  
  909. Comments
  910.  
  911. The BITMAPCOREINFO structure describes the dimensions and colors of a bitmap.
  912. It is followed immediately in memory by an array of bytes which define the
  913. pixels of the bitmap. The bits in the array are packed together, but each
  914. scan line must be zero-padded to end on a LONG boundary. Segment boundaries,
  915. however, can appear anywhere in the bitmap. The origin of the bitmap is the
  916. lower-left corner.
  917.  
  918. The bcBitCount member of the BITMAPCOREHEADER structure determines the number
  919. of bits that define each pixel and the maximum number of colors in the
  920. bitmap. This member may be set to any of the following values:
  921.  
  922. Value    Meaning
  923.  
  924. 1    The bitmap is monochrome, and the bmciColors member must contain two
  925. entries. Each bit in the bitmap array represents a pixel. If the bit is
  926. clear, the pixel is displayed with the color of the first entry in the
  927. bmciColors table. If the bit is set, the pixel has the color of the second
  928. entry in the table.
  929.  
  930. 4    The bitmap has a maximum of 16 colors, and the bmciColors member
  931. contains 16 entries. Each pixel in the bitmap is represented by a four-bit
  932. index into the color table.
  933.  
  934. For example, if the first byte in the bitmap is 0x1F, the byte represents two
  935. pixels. The first pixel contains the color in the second table entry, and the
  936. second pixel contains the color in the sixteenth table entry.
  937.  
  938. 8    The bitmap has a maximum of 256 colors, and the bmciColors member
  939. contains 256 entries. In this case, each byte in the array represents a
  940. single pixel.
  941.  
  942. 24    The bitmap has a maximum of 2^24 colors. The bmciColors member is
  943. NULL, and each 3-byte sequence in the bitmap array represents the relative
  944. intensities of red, green, and blue, respectively, of a pixel.
  945.  
  946. The colors in the bmciColors table should appear in order of importance.
  947. Alternatively, for functions that use DIBs, the bmciColors member can be an
  948. array of 16-bit unsigned integers that specify an index into the currently
  949. realized logical palette instead of explicit RGB values. In this case, an
  950. application using the bitmap must call DIB functions with the wUsage
  951. parameter set to DIB_PAL_COLORS.
  952.  
  953. Note:    The bmciColors member should not contain palette indexes if the
  954. bitmap is to be stored in a file or transferred to another application.
  955. Unless the application uses the bitmap exclusively and under its complete
  956. control, the bitmap color table should contain explicit RGB values.
  957.  
  958. See Also
  959.  
  960. BITMAPINFO, BITMAPCOREHEADER, RGBTRIPLE 
  961.  
  962.  
  963. ==============================================================================
  964. BITMAPCOREHEADER (3.0)
  965.  
  966.  
  967.  
  968. typedef struct tagBITMAPCOREHEADER {    /* bmch */
  969.     DWORD   bcSize;
  970.     short   bcWidth;
  971.     short   bcHeight;
  972.     WORD    bcPlanes;
  973.     WORD    bcBitCount;
  974. } BITMAPCOREHEADER;
  975.  
  976. The BITMAPCOREHEADER structure contains information about the dimensions and
  977. color format of a device-independent bitmap (DIB). Windows applications
  978. should use the BITMAPINFOHEADER structure instead of BITMAPCOREHEADER
  979. whenever possible.
  980.  
  981. Member        Description
  982.  
  983. bcSize        Specifies the number of bytes required by the
  984. BITMAPCOREHEADER structure.
  985.  
  986. bcWidth        Specifies the width of the bitmap, in pixels. 
  987. bcHeight    Specifies the height of the bitmap, in pixels. 
  988.  
  989. bcPlanes    Specifies the number of planes for the target device. This
  990. member must be set to 1.
  991.  
  992. bcBitCount    Specifies the number of bits per pixel. This value must be 1,
  993. 4, 8, or 24.
  994.  
  995. Comments
  996.  
  997. The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a
  998. color table to provide a complete definition of the dimensions and colors of
  999. a DIB. See the description of the BITMAPCOREINFO structure for more
  1000. information about specifying a DIB.
  1001.  
  1002. An application should use the information stored in the bcSize member to
  1003. locate the color table in a BITMAPCOREINFO structure with a method such as
  1004. the following:
  1005.  
  1006.  
  1007.  
  1008. lpColor = ((LPSTR) pBitmapCoreInfo + (UINT) (pBitmapCoreInfo->bcSize))
  1009.  
  1010. See Also
  1011.  
  1012. BITMAPCOREINFO, BITMAPINFOHEADER, BITMAPINFOHEADER 
  1013.  
  1014. =============================================================================
  1015. RGBTRIPLE (3.0)
  1016.  
  1017.  
  1018.  
  1019. typedef struct tagRGBTRIPLE {   /* rgbt */
  1020.     BYTE    rgbtBlue;
  1021.     BYTE    rgbtGreen;
  1022.     BYTE    rgbtRed;
  1023. } RGBTRIPLE;
  1024.  
  1025. The RGBTRIPLE structure describes a color consisting of relative intensities
  1026. of red, green, and blue. The bmciColors member of the BITMAPCOREINFO
  1027. structure consists of an array of RGBTRIPLE structures.  Windows applications
  1028. should use the BITMAPINFO structure instead of BITMAPCOREINFO whenever
  1029. possible. The BITMAPINFO structure uses an RGBQUAD structure instead of the
  1030. RGBTRIPLE structure.
  1031.  
  1032. Member    Description
  1033.  
  1034. rgbtBlue    Specifies the intensity of blue in the color. 
  1035. rgbtGreen    Specifies the intensity of green in the color. 
  1036. rgbtRed        Specifies the intensity of red in the color. 
  1037.  
  1038. See Also
  1039.  
  1040. BITMAPCOREINFO, BITMAPINFO, RGBQUAD 
  1041.  
  1042. ==============================================================================
  1043.  
  1044.