he unpack code for ICO/CUR file handling could extend 32-bit unsigned values to 64...
[imager.git] / fileformatdocs / bmp.txt
CommitLineData
66614d6e
TC
1BITMAPFILEHEADER [3.0]
2
3Bitmap File Information
4The BITMAPFILEHEADER data structure contains information about the type,
5size, and layout of a device-independent bitmap (DIB) file.
6
7typedef struct tagBITMAPFILEHEADER {
8 WORD bfType;
9 DWORD bfSize;
10 WORD bfReserved1;
11 WORD bfReserved2;
12 DWORD bfOffBits;
13} BITMAPFILEHEADER;
14
15The BITMAPFILEHEADER data structure contains the following fields:
16
17Field Description
18bfType Specifies the type of file. It must be BM.
19bfSize Specifies the size in DWORDs of the file.
20bfReserved1 Is reserved and must be set to zero.
21bfReserved2 Is reserved and must be set to zero.
22bfOffBits Specifies in bytes the offset from the BITMAPFILEHEADER
23 of the actual bitmap in the file.
24
25Comments A BITMAPINFO or BITMAPCOREINFO data structure immediately
26follows the BITMAPFILEHEADER structure in the DIB file.
27
28
29BITMAPINFO [3.0]
30
31Device-Indpendent Bitmap Information
32The BITMAPINFO structure fully defines the dimensions and color
33information for a Windows 3.0 device-independent bitmap.
34
35typedef struct tagBITMAPINFO {
36 BITMAPINFOHEADER bmiHeader;
37 RGBQUAD bmiColors[1];
38} BITMAPINFO;
39
40The BITMAPINFO structure contains the following fields:
41
42Field Description
43bmiHeader Specifies a BITMAPINFOHEADER data structure that
44 contains information about the dimensions and color format of a device-independent bitmap.
45bmiColors Specifies an array of RGBQUAD data structures that
46 define the colors in the bitmap.
47
48Comments: A Windows 3.0 device-independent bitmap consists of two
49distinct parts: a BITMAPINFO data structure that describes the dimensions
50and colors of the bitmap, and an array of bytes that define the pixels of
51the bitmap. The bits in the array are packed together, but each scan line
52must be zero-padded to end on a LONG boundary. Segment boundaries can
53appear anywhere in the bitmap, however. The origin of the bitmap is the
54lower-left corner.
55
56The biBitCount field of the BITMAPINFOHEADER structure determines the
57number of bits which define each pixel and the maximum number of colors
58in the bitmap. This field may be set to any of the following values:
59
60Value Meaning
611 The bitmap is monochrome, and the bmiColors field must
62 contain two entries. Each bit in the bitmap array represents a
63 pixel. If the bit is clear, the pixel is displayed with the
64 color of the first entry in the bmiColors table; if the bit is
65 set, the pixel has the color of the second entry in the table.
664 The bitmap has a maximum of 16 colors, and the bmiColors
67 field contains up to 16 entries. Each pixel in the bitmap is
68 represented by a four-bit index into the color table.
69 For example, if the first byte in the bitmap is 0x1F, then the
70 byte represents two pixels. The first pixel contains the color
71 in the second table entry, and the second pixel contains the
72 color in the 16th table entry.
738 The bitmap has a maximum of 256 colors, and the bmiColors
74 field contains up to 256 entries. In this case, each byte in the
75 array represents a single pixel.
7624 The bitmap has a maximum of 2^24 colors. The bmiColors
77 field is NULL, and each three bytes in the bitmap array
78 represents the relative intensities of red, green, and blue,
79 respectively, of a pixel.
80
81The biClrUsed field of the BITMAPINFOHEADER structure specifies the number
82of color indexes in the color table actually used by the bitmap. If the
83biClrUsed field is set to 0, the bitmap uses the maximum number of colors
84corresponding to the value of the biBitCount field.
85
86The colors in the bmiColors table should appear in order of importance.
87
88Alternatively, for functions that use device-independent bitmaps, the
89bmiColors field can be an array of 16-bit unsigned integers that specify
90an index into the currently realized logical palette instead of explicit
91RGB values. In this case, an application using the bitmap must call
92device-independent bitmap functions with the wUsage parameter set to
93DIB_PAL_COLORS.
94
95Note: The bmiColors field should not contain palette indices if the
96bitmap is to be stored in a file or transferred to another application.
97Unless the application uses the bitmap exclusively and under its complete
98control, the bitmap color table should contain explicit RGB values.
99
100BITMAPINFOHEADER [3.0]
101
102Device-Independent Bitmap Format Information
103The BITMAPINFOHEADER structure contains information about the dimensions
104and color format of a Windows 3.0 device-independent bitmap.
105
106typedef struct tagBITMAPINFOHEADER{
107 DWORD biSize;
108 DWORD biWidth;
109 DWORD biHeight;
110 WORD biPlanes;
111 WORD biBitCount
112 DWORD biCompression;
113 DWORD biSizeImage;
114 DWORD biXPelsPerMeter;
115 DWORD biYPelsPerMeter;
116 DWORD biClrUsed;
117 DWORD biClrImportant;
118} BITMAPINFOHEADER;
119
120The BITMAPINFOHEADER structure has the following fields:
121
122Field Description
123biSize Specifies the number of bytes required by the
124 BITMAPINFOHEADER structure.
125biWidth Specifies the width of the bitmap in pixels.
126biHeight Specifies the height of the bitmap in pixels.
127biPlanes Specifies the number of planes for the target device and
128 must be set to 1.
129biBitCount Specifies the number of bits per pixel. This value must
130 be 1, 4, 8, or 24.
131biCompression Specifies the type of compression for a compressed
132 bitmap. It can be one of the following values:.
133 Value Meaning
134 BI_RGB Specifies that the bitmap is not
135 compressed.
136 BI_RLE8 Specifies a run-length encoded format
137 for bitmaps with 8 bits per pixel. The
138 compression format is a two-byte
139 format consisting of a count byte
140 followed by a byte containing a color
141 index. See the following 'Comments'
142 section for more information.
143 BI_RLE4 Specifies a run-length encoded format
144 for bitmaps with 4 bits per pixel. The
145 compression format is a two-byte
146 format consisting of a count byte
147 followed by two word-length color
148 indexes. See the following 'Comments'
149 section for more information.
150biSizeImage Specifies the size in bytes of the image.
151biXPelsPerMeter Specifies the horizontal resolution in pixels per meter of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device. biYPelsPerMeter Specifies the vertical resolution in pixels per meter of the target device for the bitmap.
152biClrUsed Specifies the number of color indexes in the color table
153 actually used by the bitmap. If this value is 0, the
154 bitmap uses the maximum number of colors corresponding
155 to the value of the biBitCount field. See the
156 description of the BITMAPINFO data structure earlier in
157 this chapter for more information on the maximum sizes
158 of the color table. If biClrUsed is nonzero, then the
159 biClrUsed field specifies the actual number of colors
160 which the graphics engine or device driver will access
161 if the biBitCount field is less than 24. If the
162 biBitCount field is set to 24, the biClrUsed field
163 specifies the size of the reference color table used to
164 optimize performance of Windows color palettes.
165 If the bitmap is a 'packed' bitmap (that is, a bitmap in
166 which the bitmap array immediately follows the
167 BITMAPINFO header and which is referenced by a single
168 pointer), the biClrUsed field must be set to 0 or to the
169 actual size of the color table.
170biClrImportant Specifies the number of color indexes that are considered
171 important for displaying the bitmap. If this value is 0,
172 then all colors are important.
173
174Comments: The BITMAPINFO data structure combines the
175BITMAPINFOHEADER structure and a color table to provide a complete
176definition of the dimensions and colors of a Windows 3.0
177device-independent bitmap. See the description of the BITMAPINFO data
178structure for more information about specifying a Windows 3.0
179device-independent bitmap.
180
181An application should use the information stored in the biSize field to
182locate the color table in a BITMAPINFO data structure with a method such
183as the following:
184
185pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo -> biSize))
186
187Bitmap Compression Formats Windows supports formats for compressing
188bitmaps that define their colors with 8 bits per pixel and with 4 bits
189per pixel. Compression reduces the disk and memory storage required for
190the bitmap. The following paragraphs describe these formats.
191
192When the biCompression field is set to BI_RLE8, the bitmap is compressed
193using a run-length encoding format for an 8-bit bitmap. This format may
194be compressed in either of two modes:
195
1967 Encoded
1977 Absolute
198
199
200Both modes can occur anywhere throughout a single bitmap.
201
202Encoded mode consists of two bytes: the first byte specifies the number
203of consecutive pixels to be drawn using the color index contained in the
204second byte. In addition, the first byte of the pair can be set to zero
205to indicate an escape that denotes an end of line, end of bitmap, or a
206delta. The interpretation of the escape depends on the value of the
207second byte of the pair. The following list shows the meaning of the
208second byte:
209
210Second Byte
211Of Escape
212 Meaning
2130 End of line.
2141 End of bitmap.
2152 Delta. The two bytes following the escape contain
216 unsigned values indicating the horizontal and vertical
217 offset of the next pixel from the current position.
218
219Absolute mode is signalled by the first byte set to zero and the second
220byte set to a value between 03H and FFH. In absolute mode, the second
221byte represents the number of bytes which follow, each of which contains
222the color index of a single pixel. When the second byte is set to 2 or
223less, the escape has the same meaning as in encoded mode.
224In absolute mode, each run must be aligned on a word boundary.
225
226The following example shows the hexadecimal values of an 8-bit compressed
227bitmap:
228
22903 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01
23002 78 00 00 09 1E 00 01
231
232This bitmap would expand as follows (two-digit values represent a color
233index for a single pixel):
234
23504 04 04
23606 06 06 06 06
23745 56 67
23878 78
239move current position 5 right and 1 down
24078 78
241end of line
2421E 1E 1E 1E 1E 1E 1E 1E 1E
243end of RLE bitmap
244
245When the biCompression field is set to BI_RLE4, the bitmap is compressed
246using a run-length encoding format for a 4-bit bitmap, which also uses
247encoded and absolute modes. In encoded mode, the first byte of the pair
248contains the number of pixels to be drawn using the color indexes in the
249second byte. The second byte contains two color indexes, one in its
250high-order nibble (that is, its low-order four bits) and one in its
251low-order nibble. The first of the pixels is drawn using the color
252specified by the high-order nibble, the second is drawn using the color
253in the low-order nibble, the third is drawn with the color in the
254high-order nibble, and so on, until all the pixels specified by the
255first byte have been drawn.
256
257In absolute mode, the first byte contains zero, the second byte contains
258the number of color indexes that follow, and subsequent bytes contain
259color indexes in their high- and low-order nibbles, one color index for
260each pixel. In absolute mode, each run must be aligned on a word boundary.
261The end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4.
262
263The following example shows the hexadecimal values of a 4-bit compressed
264bitmap:
265
26603 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01
26704 78 00 00 09 1E 00 01
268
269This bitmap would expand as follows (single-digit values represent a
270color index for a single pixel):
271
2720 4 0
2730 6 0 6 0
2744 5 5 6 6 7
2757 8 7 8
276move current position 5 right and 1 down
2777 8 7 8
278end of line
2791 E 1 E 1 E 1 E 1
280end of RLE bitmap
281
282RGBQUAD [3.0]
283
284RGB Color Structure
285The RGBQUAD data structure describes a color consisting of relative
286intensities of red, green, and blue. The bmiColors field of the
287BITMAPINFO data structure consists of an array of RGBQUAD data structures.
288
289typedef struct tagRGBQUAD {
290 BYTE rgbBlue;
291 BYTE rgbGreen;
292 BYTE rgbRed;
293 BYTE rgbReserved;
294} RGBQUAD;
295
296The RGBQUAD structure contains the following fields:
297
298Field Description
299rgbBlue Specifies the intensity of blue in the color.
300rgbGreen Specifies the intensity of green in the color.
301rgbRed Specifies the intensity of red in the color.
302rgbReserved Is not used and must be set to zero.
303
304
305
306#define BI_RGB 0L
307#define BI_RLE8 1L
308#define BI_RLE4 2L
309
310BITMAPCOREINFO [3.0]
311
312Device-Indpendent Bitmap Information
313The BITMAPCOREINFO structure fully defines the dimensions and color
314information for a device-independent bitmap that is compatible with
315Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 bitmaps.
316
317typedef struct _BITMAPCOREINFO {
318 BITMAPCOREHEADER bmciHeader;
319 RGBTRIPLE bmciColors[];
320} BITMAPCOREINFO;
321
322The BITMAPCOREINFO structure contains the following fields:
323
324Field Description
325bmciHeader Specifies a BITMAPCOREHEADER data structure that
326 contains information about the dimensions and color
327 format of a device-independent bitmap.
328bmciColors Specifies an array of RGBTRIPLE data structures that
329 define the colors in the bitmap.
330
331Comments An OS/2 Presentation Manager device-independent bitmap
332consists of two distinct parts: a BITMAPCOREINFO data structure that
333describes the dimensions and colors of the bitmap, and an array of bytes
334which define the pixels of the bitmap. The bits in the array are packed
335together, but each scan line must be zero-padded to end on a LONG
336boundary. Segment boundaries can appear anywhere in the bitmap, however.
337The origin of the bitmap is the lower-left corner.
338
339The bcBitCount field of the BITMAPCOREHEADER structure determines the
340number of bits which define each pixel and the maximum number of colors
341in the bitmap. This field may be set to any of the following values:
342
343Value Meaning
3441 The bitmap is monochrome, and the bmciColors field must
345 contain two entries. Each bit in the bitmap array represents a
346 pixel. If the bit is clear, the pixel is displayed with the
347 color of the first entry in the bmciColors table; if the bit is
348 set, the pixel has the color of the second entry in the table.
3494 The bitmap has a maximum of 16 colors, and the bmciColors
350 field contains 16 entries. Each pixel in the bitmap is represented
351 by a four-bit index into the color table.
352 For example, if the first byte in the bitmap is 0x1F, then the
353 byte represents two pixels. The first pixel contains the color in
354 the second table entry, and the second pixel contains the color
355 in the 16th table entry.
3568 The bitmap has a maximum of 256 colors, and the bmciColors
357 field contains 256 entries. In this case, each byte in the array
358 represents a single pixel.
35924 The bitmap has a maximum of 2^24 colors. The bmciColors
360 field is NULL, and each three bytes in the bitmap array
361 represents the relative intensities of red, green, and blue,
362 respectively, of a pixel.
363
364The colors in the bmciColors table should appear in order of importance.
365
366Alternatively, for functions that use device-independent bitmaps, the
367bmciColors field can be an array of 16-bit unsigned integers that
368specify an index into the currently realized logical palette instead of
369explicit RGB values. In this case, an application using the bitmap must
370call device-independent bitmap functions with the wUsage parameter
371set to DIB_PAL_COLORS.
372
373Note The bmciColors field should not contain palette indexes if the
374bitmap is to be stored in a file or transferred to another application.
375Unless the application uses the bitmap exclusively and under its
376complete control, the bitmap color table should contain explicit
377RGB values.
378
379
380
381BITMAPCOREHEADER [3.0]
382
383Device-Independent Bitmap Format Information
384The BITMAPCOREHEADER structure contains information about the dimensions
385and color format of a device-independent bitmap that is compatible with
386Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 bitmaps.
387
388typedef struct tagBITMAPCOREHEADER {
389 DWORD bcSize;
390 WORD bcWidth;
391 WORD bcHeight;
392 WORD bcPlanes;
393 WORD bcBitCount;
394} BITMAPCOREHEADER;
395
396The BITMAPCOREHEADER structure has the following fields:
397
398Field Description
399bcSize Specifies the number of bytes required by the BITMAPCOREHEADER
400 structure.
401bcWidth Specifies the width of the bitmap in pixels.
402bcHeight Specifies the height of the bitmap in pixels.
403bcPlanes Specifies the number of planes for the target device and
404 must be set to 1.
405bcBitCount Specifies the number of bits per pixel. This value must
406 be 1, 4, 8, or 24.
407
408Comments The BITMAPCOREINFO data structure combines the
409BITMAPCOREHEADER structure and a color table to provide a complete
410definition of the dimensions and colors of a device-independent bitmap.
411See the description of the BITMAPCOREINFO data structure for more
412information about specifying a device-independent bitmap.
413
414An application should use the information stored in the bcSize field to
415locate the color table in a BITMAPCOREINFO data structure with a method
416such as the following:
417
418pColor = ((LPSTR) pBitmapCoreInfo + (WORD) (pBitmapCoreInfo -> bcSize))
419
420
421
422RGBTRIPLE [3.0]
423
424RGB Color Structure
425The RGBTRIPLE data structure describes a color consisting of relative
426intensities of red, green, and blue. The bmciColors field of the
427BITMAPCOREINFO data structure consists of an array of RGBTRIPLE data
428structures.
429
430typedef struct tagRGBTRIPLE {
431 BYTE rgbtBlue;
432 BYTE rgbtGreen;
433 BYTE rgbtRed;
434} RGBTRIPLE;
435
436The RGBTRIPLE structure contains the following fields:
437
438Field Description
439rgbtBlue Specifies the intensity of blue in the color.
440rgbtGreen Specifies the intensity of green in the color.
441rgbtRed Specifies the intensity of red in the color.
442
443
444
445-----------------------------------------------------------------------
446
447 Non official comments
448
449How to distinguish between BITMAPINFO and BITMAPCOREINFO when reading
450in a BMP file.
451
452After reading the BITMAPFILEHEADER read the next DWORD from the file.
453If it is 12 you are reading a BITMAPCOREHEADER, if it is 40 you are
454reading a BITMAPINFOHEADER.