prevent an unsigned overflow in FT1 has_chars() implementation
[imager.git] / fileformatdocs / bmp.txt
1 BITMAPFILEHEADER  [3.0]
2
3 Bitmap File Information
4 The BITMAPFILEHEADER data structure contains information about the type, 
5 size, and layout of a device-independent bitmap (DIB) file.
6
7 typedef struct tagBITMAPFILEHEADER {
8         WORD    bfType;
9         DWORD   bfSize;
10         WORD    bfReserved1;
11         WORD    bfReserved2;
12         DWORD   bfOffBits;
13 } BITMAPFILEHEADER;
14
15 The BITMAPFILEHEADER data structure contains the following fields:
16
17 Field           Description
18 bfType          Specifies the type of file. It must be BM.
19 bfSize          Specifies the size in DWORDs of the file. 
20 bfReserved1     Is reserved and must be set to zero. 
21 bfReserved2     Is reserved and must be set to zero. 
22 bfOffBits       Specifies in bytes the offset from the BITMAPFILEHEADER 
23                 of the actual bitmap in the file. 
24
25 Comments        A BITMAPINFO or BITMAPCOREINFO data structure immediately 
26 follows the BITMAPFILEHEADER structure in the DIB file.
27
28
29 BITMAPINFO  [3.0]
30
31 Device-Indpendent Bitmap Information
32 The BITMAPINFO structure fully defines the dimensions and color 
33 information for a Windows 3.0 device-independent bitmap.
34
35 typedef struct tagBITMAPINFO { 
36    BITMAPINFOHEADER    bmiHeader;
37    RGBQUAD             bmiColors[1];
38 } BITMAPINFO;
39
40 The BITMAPINFO structure contains the following fields:
41
42 Field   Description
43 bmiHeader       Specifies a BITMAPINFOHEADER data structure that 
44                 contains information about the dimensions and color                             format of a device-independent bitmap. 
45 bmiColors       Specifies an array of RGBQUAD data structures that 
46                 define the colors in the bitmap.  
47
48 Comments:       A Windows 3.0 device-independent bitmap consists of two 
49 distinct parts: a BITMAPINFO data structure that describes the dimensions 
50 and colors of the bitmap, and an array of bytes that define the pixels of 
51 the bitmap. The bits in the array are packed together, but each scan line 
52 must be zero-padded to end on a LONG boundary. Segment boundaries can 
53 appear anywhere in the bitmap, however. The origin of the bitmap is the 
54 lower-left corner.
55
56 The biBitCount field of the BITMAPINFOHEADER structure determines the 
57 number of bits which define each pixel and the maximum number of colors 
58 in the bitmap. This field may be set to any of the following values:
59
60 Value   Meaning
61 1       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.
66 4       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.
73 8       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.
76 24      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
81 The biClrUsed field of the BITMAPINFOHEADER structure specifies the number
82 of color indexes in the color table actually used by the bitmap. If the 
83 biClrUsed field is set to 0, the bitmap uses the maximum number of colors 
84 corresponding to the value of the biBitCount field.
85
86 The colors in the bmiColors table should appear in order of importance.
87
88 Alternatively, for functions that use device-independent bitmaps, the 
89 bmiColors field can be an array of 16-bit unsigned integers that specify 
90 an index into the currently realized logical palette instead of explicit 
91 RGB values. In this case, an application using the bitmap must call 
92 device-independent bitmap functions with the wUsage parameter set to 
93 DIB_PAL_COLORS.
94
95 Note:   The bmiColors field should not contain palette indices if the 
96 bitmap is to be stored in a file or transferred to another application. 
97 Unless the application uses the bitmap exclusively and under its complete 
98 control, the bitmap color table should contain explicit RGB values.
99
100 BITMAPINFOHEADER  [3.0]
101
102 Device-Independent Bitmap Format Information
103 The BITMAPINFOHEADER structure contains information about the dimensions 
104 and color format of a Windows 3.0 device-independent bitmap.
105
106 typedef 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
120 The BITMAPINFOHEADER structure has the following fields:
121
122 Field           Description
123 biSize          Specifies the number of bytes required by the 
124                 BITMAPINFOHEADER structure. 
125 biWidth         Specifies the width of the bitmap in pixels. 
126 biHeight        Specifies the height of the bitmap in pixels. 
127 biPlanes        Specifies the number of planes for the target device and
128                 must be set to 1. 
129 biBitCount      Specifies the number of bits per pixel. This value must 
130                 be 1, 4, 8, or 24. 
131 biCompression   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.
150 biSizeImage     Specifies the size in bytes of the image. 
151 biXPelsPerMeter 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. 
152 biClrUsed       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. 
170 biClrImportant  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
174 Comments:       The BITMAPINFO data structure combines the 
175 BITMAPINFOHEADER structure and a color table to provide a complete 
176 definition of the dimensions and colors of a Windows 3.0 
177 device-independent bitmap. See the description of the BITMAPINFO data 
178 structure for more information about specifying a Windows 3.0 
179 device-independent bitmap.
180
181 An application should use the information stored in the biSize field to 
182 locate the color table in a BITMAPINFO data structure with a method such 
183 as the following:
184
185 pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo -> biSize))
186
187 Bitmap Compression Formats      Windows supports formats for compressing 
188 bitmaps that define their colors with 8 bits per pixel and with 4 bits 
189 per pixel. Compression reduces the disk and memory storage required for 
190 the bitmap. The following paragraphs describe these formats.
191
192 When the biCompression field is set to BI_RLE8, the bitmap is compressed 
193 using a run-length encoding format for an 8-bit bitmap. This format may 
194 be compressed in either of two modes:
195
196 7       Encoded
197 7       Absolute
198
199
200 Both modes can occur anywhere throughout a single bitmap.
201
202 Encoded mode consists of two bytes:  the first byte specifies the number 
203 of consecutive pixels to be drawn using the color index contained in the 
204 second byte. In addition, the first byte of the pair can be set to zero 
205 to indicate an escape that denotes an end of line, end of bitmap, or a 
206 delta. The interpretation of the escape depends on the value of the 
207 second byte of the pair. The following list shows the meaning of the 
208 second byte:
209
210 Second Byte
211 Of Escape       
212                 Meaning
213 0               End of line.
214 1               End of bitmap.
215 2               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
219 Absolute mode is signalled by the first byte set to zero and the second 
220 byte set to a value between 03H and FFH. In absolute mode, the second 
221 byte represents the number of bytes which follow, each of which contains
222 the color index of a single pixel. When the second byte is set to 2 or 
223 less, the escape has the same meaning as in encoded mode. 
224 In absolute mode, each run must be aligned on a word boundary.
225
226 The following example shows the hexadecimal values of an 8-bit compressed 
227 bitmap:
228
229 03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01 
230 02 78 00 00 09 1E 00 01
231
232 This bitmap would expand as follows (two-digit values represent a color 
233 index for a single pixel):
234
235 04 04 04
236 06 06 06 06 06
237 45 56 67
238 78 78
239 move current position 5 right and 1 down
240 78 78
241 end of line
242 1E 1E 1E 1E 1E 1E 1E 1E 1E 
243 end of RLE bitmap
244
245 When the biCompression field is set to BI_RLE4, the bitmap is compressed 
246 using a run-length encoding format for a 4-bit bitmap, which also uses 
247 encoded and absolute modes. In encoded mode, the first byte of the pair 
248 contains the number of pixels to be drawn using the color indexes in the 
249 second byte. The second byte contains two color indexes, one in its 
250 high-order nibble (that is, its low-order four bits) and one in its 
251 low-order nibble. The first of the pixels is drawn using the color 
252 specified by the high-order nibble, the second is drawn using the color 
253 in the low-order nibble, the third is drawn with the color in the 
254 high-order nibble, and so on, until all the pixels specified by the 
255 first byte have been drawn.
256
257 In absolute mode, the first byte contains zero, the second byte contains 
258 the number of color indexes that follow, and subsequent bytes contain 
259 color indexes in their high- and low-order nibbles, one color index for 
260 each pixel. In absolute mode, each run must be aligned on a word boundary.
261 The end-of-line, end-of-bitmap, and delta escapes also apply to BI_RLE4.
262
263 The following example shows the hexadecimal values of a 4-bit compressed 
264 bitmap:
265
266 03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01 
267 04 78 00 00 09 1E 00 01
268
269 This bitmap would expand as follows (single-digit values represent a 
270 color index for a single pixel):
271
272 0 4 0
273 0 6 0 6 0 
274 4 5 5 6 6 7
275 7 8 7 8
276 move current position 5 right and 1 down
277 7 8 7 8
278 end of line
279 1 E 1 E 1 E 1 E 1
280 end of RLE bitmap
281
282 RGBQUAD  [3.0]
283
284 RGB Color Structure
285 The RGBQUAD data structure describes a color consisting of relative 
286 intensities of red, green, and blue. The bmiColors field of the 
287 BITMAPINFO data structure consists of an array of RGBQUAD data structures.
288
289 typedef struct tagRGBQUAD {
290    BYTE    rgbBlue;
291    BYTE    rgbGreen;
292    BYTE    rgbRed;
293    BYTE    rgbReserved;
294 } RGBQUAD;
295
296 The RGBQUAD structure contains the following fields:
297
298 Field           Description
299 rgbBlue         Specifies the intensity of blue in the color. 
300 rgbGreen        Specifies the intensity of green in the color. 
301 rgbRed          Specifies the intensity of red in the color. 
302 rgbReserved     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
310 BITMAPCOREINFO  [3.0]
311
312 Device-Indpendent Bitmap Information
313 The BITMAPCOREINFO structure fully defines the dimensions and color 
314 information for a device-independent bitmap that is compatible with 
315 Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 bitmaps.
316
317 typedef struct _BITMAPCOREINFO {
318         BITMAPCOREHEADER  bmciHeader;
319         RGBTRIPLE         bmciColors[];
320 } BITMAPCOREINFO;
321
322 The BITMAPCOREINFO structure contains the following fields:
323
324 Field   Description
325 bmciHeader      Specifies a BITMAPCOREHEADER data structure that 
326                 contains information about the dimensions and color 
327                 format of a device-independent bitmap. 
328 bmciColors      Specifies an array of RGBTRIPLE data structures that 
329                 define the colors in the bitmap.  
330
331 Comments        An OS/2 Presentation Manager device-independent bitmap 
332 consists of two distinct parts:  a BITMAPCOREINFO data structure that 
333 describes the dimensions and colors of the bitmap, and an array of bytes 
334 which define the pixels of the bitmap. The bits in the array are packed 
335 together, but each scan line must be zero-padded to end on a LONG 
336 boundary. Segment boundaries can appear anywhere in the bitmap, however. 
337 The origin of the bitmap is the lower-left corner.
338
339 The bcBitCount field of the BITMAPCOREHEADER structure determines the 
340 number of bits which define each pixel and the maximum number of colors 
341 in the bitmap. This field may be set to any of the following values:
342
343 Value   Meaning
344 1       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.
349 4       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.
356 8       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.
359 24      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
364 The colors in the bmciColors table should appear in order of importance.
365
366 Alternatively, for functions that use device-independent bitmaps, the 
367 bmciColors field can be an array of 16-bit unsigned integers that 
368 specify an index into the currently realized logical palette instead of 
369 explicit RGB values. In this case, an application using the bitmap must 
370 call device-independent bitmap functions with the wUsage parameter 
371 set to DIB_PAL_COLORS.
372
373 Note    The bmciColors field should not contain palette indexes if the 
374 bitmap is to be stored in a file or transferred to another application. 
375 Unless the application uses the bitmap exclusively and under its 
376 complete control, the bitmap color table should contain explicit 
377 RGB values.
378
379
380
381 BITMAPCOREHEADER  [3.0]
382
383 Device-Independent Bitmap Format Information
384 The BITMAPCOREHEADER structure contains information about the dimensions 
385 and color format of a device-independent bitmap that is compatible with 
386 Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 bitmaps.
387
388 typedef struct tagBITMAPCOREHEADER {
389         DWORD   bcSize;
390         WORD    bcWidth;
391         WORD    bcHeight;
392         WORD    bcPlanes;
393         WORD    bcBitCount;
394 } BITMAPCOREHEADER;
395
396 The BITMAPCOREHEADER structure has the following fields:
397
398 Field           Description
399 bcSize          Specifies the number of bytes required by the BITMAPCOREHEADER 
400                 structure. 
401 bcWidth         Specifies the width of the bitmap in pixels. 
402 bcHeight        Specifies the height of the bitmap in pixels. 
403 bcPlanes        Specifies the number of planes for the target device and 
404                 must be set to 1. 
405 bcBitCount      Specifies the number of bits per pixel. This value must 
406                 be 1, 4, 8, or 24. 
407
408 Comments        The BITMAPCOREINFO data structure combines the 
409 BITMAPCOREHEADER structure and a color table to provide a complete 
410 definition of the dimensions and colors of a device-independent bitmap. 
411 See the description of the BITMAPCOREINFO data structure for more 
412 information about specifying a device-independent bitmap.
413
414 An application should use the information stored in the bcSize field to 
415 locate the color table in a BITMAPCOREINFO data structure with a method 
416 such as the following:
417
418 pColor = ((LPSTR) pBitmapCoreInfo + (WORD) (pBitmapCoreInfo -> bcSize))
419
420
421
422 RGBTRIPLE  [3.0]
423
424 RGB Color Structure
425 The RGBTRIPLE data structure describes a color consisting of relative 
426 intensities of red, green, and blue. The bmciColors field of the 
427 BITMAPCOREINFO data structure consists of an array of RGBTRIPLE data 
428 structures.
429
430 typedef struct tagRGBTRIPLE {
431         BYTE    rgbtBlue;
432         BYTE    rgbtGreen;
433         BYTE    rgbtRed;
434 } RGBTRIPLE;
435
436 The RGBTRIPLE structure contains the following fields:
437
438 Field           Description
439 rgbtBlue        Specifies the intensity of blue in the color. 
440 rgbtGreen       Specifies the intensity of green in the color. 
441 rgbtRed         Specifies the intensity of red in the color. 
442
443
444
445 -----------------------------------------------------------------------
446
447         Non official comments
448
449 How to distinguish between BITMAPINFO and BITMAPCOREINFO when reading
450 in a BMP file.
451
452 After reading the BITMAPFILEHEADER read the next DWORD from the file. 
453 If it is 12 you are reading a BITMAPCOREHEADER, if it is 40 you are
454 reading a BITMAPINFOHEADER.