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