home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 14 Text / 14-Text.zip / BMAPFMT.ZIP / TEXT.TMP
Text File  |  1992-06-27  |  18KB  |  481 lines
  1.  
  2.  The operating system uses the same file format for bit maps, icons, and pointers in 
  3.  resource files.  In the following description, "bit map" refers to bit maps, icons, and 
  4.  pointers unless otherwise specified. 
  5.  
  6.  Two formats are supported. In the first, a single-size version of the bit map is defined. 
  7.  This is used whatever the target device. 
  8.  
  9.  The second format allows multiple versions of the bit map to be defined, including one 
  10.  or more device-independent versions, and a number of device-dependent versions, each 
  11.  intended for use with a particular device. 
  12.  
  13.  In the case of icons and pointers, when more than one version of the bit map exists, the 
  14.  preferred version is one that matches the device size of icon or pointer.  Otherwise the 
  15.  device-independent version is used to scale a bit map to the required size. 
  16.  
  17.  The operating system provides pointers that match the requirements of the display device 
  18.  in use, typically pointers are 32x32 pels, one bit per plane. 
  19.  
  20.  Icons provided with the operating system are designed to match the requirements of the 
  21.  most common display devices.  The following versions of each icon are included in each 
  22.  file: 
  23.  
  24.  32x32 4 bpp (16 color) 
  25.  40x40 4 bpp (16 color) 
  26.  32x32 1 bpp (black and white) 
  27.  20x20 1 bpp (black and white) 
  28.  16x16 1 bpp (black and white) 
  29.  
  30.  The 32x32 versions are designed for VGA displays and for device-independent use. 
  31.  
  32.  The 40x40 version is for 8514/A and XGA displays. 
  33.  
  34.  The 20x20 and 16x16 are half-size icons designed for use as mini-icons. 
  35.  
  36.  For general bit maps, which may be of arbitrary size, the preferred version is one 
  37.  matching the requested bit map size; otherwise one matching the display size is 
  38.  selected.  If neither is available, the device-independent version is used from which to 
  39.  scale a bit map. 
  40.  
  41.  For both formats, the definition consists of two sections.  The first section contains 
  42.  general information about the type, dimensions, and other attributes of the resource.  
  43.  The second section contains data describing the pels that make up the bit map(s), and 
  44.  is in the format specified in Bit-Map Data. 
  45.  
  46.  In the multiple-version format, the first section contains an array of 
  47.  BITMAPARRAYFILEHEADER structures. or BITMAPARRAYFILEHEADER2 structures. The 
  48.  format of these is as follows: 
  49.  
  50.  typedef struct _BITMAPARRAYFILEHEADER {    /* bafh */
  51.      USHORT            usType;
  52.      ULONG             cbSize;
  53.      ULONG             offNext;
  54.      USHORT            cxDisplay;
  55.      USHORT            cyDisplay;
  56.      BITMAPFILEHEADER  bfh;
  57.  } BITMAPARRAYFILEHEADER;
  58.  typedef BITMAPARRAYFILEHEADER *PBITMAPARRAYFILEHEADER;
  59.  
  60.  typedef struct _BITMAPARRAYFILEHEADER2 {    /* bafh */
  61.      USHORT            usType;
  62.      ULONG             cbSize;
  63.      ULONG             offNext;
  64.      USHORT            cxDisplay;
  65.      USHORT            cyDisplay;
  66.      BITMAPFILEHEADER2 bfh2;
  67.  } BITMAPARRAYFILEHEADER2;
  68.  typedef BITMAPARRAYFILEHEADER2 *PBITMAPARRAYFILEHEADER2;
  69.  
  70.  The fields in BITMAPARRAYFILEHEADER and BITMAPARRAYFILEHEADER2 have these 
  71.  meanings: 
  72.  
  73.  usType 
  74.    
  75.     Type of structure. This is: 
  76.  
  77.     BFT_BITMAPARRAY (X'4142' - 'BA' for BITMAPARRAYFILEHEADER or 
  78.     BITMAPARRAYFILEHEADER2) 
  79.  
  80.  cbSize 
  81.    
  82.     Size of the BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 structure in 
  83.     bytes. 
  84.  
  85.  offNext 
  86.    
  87.     Offset of the next BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 
  88.     structure from the start of the file 
  89.  
  90.  cxDisplay, cyDisplay 
  91.    
  92.     pel dimensions of the device for which this version is intended (for example, 640 x 
  93.     480 for VGA). 
  94.  
  95.  The device-independent version must be the first BITMAPARRAYFILEHEADER or 
  96.  BITMAPARRAYFILEHEADER2 defined. 
  97.  
  98.  In the single-size format, the BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 
  99.  structure is not present. The definition consists of one or two BITMAPFILEHEADER or 
  100.  BITMAPFILEHEADER2 structures. 
  101.  
  102.  The format of the BITMAPFILEHEADER and BITMAPFILEHEADER2 structure is : 
  103.  
  104.  typedef struct _BITMAPFILEHEADER {    /* bfh */
  105.      USHORT            usType;
  106.      ULONG             cbSize;
  107.      SHORT             xHotspot;
  108.      SHORT             yHotspot;
  109.      ULONG             offBits;
  110.      BITMAPINFOHEADER  bmp;
  111.  } BITMAPFILEHEADER;
  112.  typedef BITMAPFILEHEADER *PBITMAPFILEHEADER;
  113.  
  114.  typedef struct _BITMAPFILEHEADER2 {    /* bfh2 */
  115.      USHORT            usType;
  116.      ULONG             cbSize;
  117.      SHORT             xHotspot;
  118.      SHORT             yHotspot;
  119.      ULONG             offBits;
  120.      BITMAPINFOHEADER2 bmp2;
  121.  } BITMAPFILEHEADER2;
  122.  typedef BITMAPFILEHEADER2 *PBITMAPFILEHEADER2;
  123.  
  124.  BITMAPINFOHEADER2 is a standard data type (see above, and also 
  125.  BITMAPINFOHEADER2). 
  126.  
  127.  The fields in BITMAPFILEHEADER and BITMAPFILEHEADER2 have these meanings: 
  128.  
  129.  usType 
  130.    
  131.     Type of resource the file contains. The valid values are: 
  132.  
  133.     BFT_BMAP (X'4D42' - 'BM' for bit maps) 
  134.     BFT_ICON (X'4349' - 'IC' for icons) 
  135.     BFT_POINTER (X'5450' - 'PT' for pointers). 
  136.     BFT_COLORICON (X'4943' - 'CI' for color icons). 
  137.     BFT_COLORPOINTER (X'5043' - 'CP' for color pointers). 
  138.  
  139.  cbSize 
  140.    
  141.     Size of the BITMAPFILEHEADER or BITMAPFILEHEADER2 structure in bytes. 
  142.  
  143.  xHotspot, yHotspot 
  144.    
  145.     Coordinates of the hotspot for icons and pointers. This field is ignored for bit maps. 
  146.  
  147.  offBits 
  148.    
  149.     Offset in bytes to the beginning of the bit-map pel data in the file, from the start of 
  150.     the definition. 
  151.  
  152.  For icons and pointers, the cy field in bmp is actually twice the pel height of the image 
  153.  that appears on the screen.  This is because these types actually contain two full 
  154.  bit-map pel definitions. The first bit-map definition is the XOR mask, which contains 
  155.  invert information (0 = no invert, 1 = invert) for the pointer or icon.  The second is the 
  156.  AND mask, which determines whether the pointer or the screen is shown (0 = 
  157.  black/white, 1 = screen/inverse screen). 
  158.  
  159.  For color icons or pointers, there are two bit-maps involved: one that is black and white 
  160.  and consists of an AND and an XOR mask, and one that is color that defines the color 
  161.  content. 
  162.  
  163.  The cy field in the BITMAPINFOHEADER2 structure for the color bit-map must be the real 
  164.  height, that is, half the value specified for the black and white bit-map. The cx fields 
  165.  must be the same. 
  166.  
  167.  The following table shows how these two bit-maps are used for a color icon or pointer: 
  168.  
  169.     XOR     AND     COLOR
  170.      1       1        x       Invert screen
  171.      0       0        x       Use color x
  172.      0       1        x       Transparency
  173.      1       0        x       Use color x
  174.  
  175.  For color icons or pointers, two BITMAPFILEHEADER or BITMAPFILEHEADER2 structures 
  176.  are therefore required: 
  177.  
  178.  BITMAPFILEHEADER2    with usType BFT_COLORICON or BFT_COLORPOINTER
  179.     BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2)
  180.     Color table
  181.  BITMAPFILEHEADER2    with same usType
  182.     BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2)
  183.     Color table
  184.  **
  185.  bits for one bit-map
  186.  **
  187.  **
  188.  bits for other bit-map
  189.  **
  190.  
  191.  The usType for the first BITMAPFILEHEADER2 is either BFT_COLORICON or 
  192.  BFT_COLORPOINTER. This means that a second BITMAPFILEHEADER2 is present as 
  193.  part of the definition of a color icon or pointer. The first BITMAPFILEHEADER2 structure 
  194.  contains the information for the black and white AND and XOR masks, while the second 
  195.  BITMAPFILEHEADER2 structure contains the information for the color part of the pointer 
  196.  or icon. 
  197.  
  198.  BITMAPFILEHEADER and BITMAPINFOHEADER can occur in place of 
  199.  BITMAPFILEHEADER2 and BITMAPINFOHEADER2 in this example. 
  200.  
  201.  For the multiple version format, the file is as follows: 
  202.  
  203.  BITMAPARRAYFILEHEADER2   for device-independent version
  204.     BITMAPFILEHEADER2     (part of BITMAPARRAYFILEHEADER2)
  205.        BITMAPINFOHEADER2  (part of BITMAPFILEHEADER2)
  206.        Color table
  207.  
  208.     BITMAPFILEHEADER2     )
  209.        BITMAPINFOHEADER2  )  only if this is a color icon or pointer
  210.        Color table        )
  211.  
  212.  BITMAPARRAYFILEHEADER2   for first device-dependent version
  213.     BITMAPFILEHEADER2     (part of BITMAPARRAYFILEHEADER2)
  214.        BITMAPINFOHEADER2  (part of BITMAPFILEHEADER2)
  215.        Color table
  216.  
  217.     BITMAPFILEHEADER2     )
  218.        BITMAPINFOHEADER2  )  only if this is a color icon or pointer
  219.        Color table        )
  220.  
  221.  Further BITMAPARRAYFILEHEADER2 groups occur here as required
  222.  for additional device-dependent versions
  223.  
  224.  **
  225.  bits for one bit-map
  226.  **
  227.  **
  228.  bits for next bit-map
  229.  **
  230.  
  231.  And so on for as many bit-maps as necessary.
  232.  
  233.  As before, BITMAPARRAYFILEHEADER, BITMAPFILEHEADER and BITMAPINFOHEADER 
  234.  can occur in place of BITMAPARRAYFILEHEADER2, BITMAPFILEHEADER2 and 
  235.  BITMAPINFOHEADER2.   
  236.  
  237.  
  238.  The operating system uses the same file format for bit maps, icons, and pointers in 
  239.  resource files.  In the following description, "bit map" refers to bit maps, icons, and 
  240.  pointers unless otherwise specified. 
  241.  
  242.  Two formats are supported. In the first, a single-size version of the bit map is defined. 
  243.  This is used whatever the target device. 
  244.  
  245.  The second format allows multiple versions of the bit map to be defined, including one 
  246.  or more device-independent versions, and a number of device-dependent versions, each 
  247.  intended for use with a particular device. 
  248.  
  249.  In the case of icons and pointers, when more than one version of the bit map exists, the 
  250.  preferred version is one that matches the device size of icon or pointer.  Otherwise the 
  251.  device-independent version is used to scale a bit map to the required size. 
  252.  
  253.  The operating system provides pointers that match the requirements of the display device 
  254.  in use, typically pointers are 32x32 pels, one bit per plane. 
  255.  
  256.  Icons provided with the operating system are designed to match the requirements of the 
  257.  most common display devices.  The following versions of each icon are included in each 
  258.  file: 
  259.  
  260.  32x32 4 bpp (16 color) 
  261.  40x40 4 bpp (16 color) 
  262.  32x32 1 bpp (black and white) 
  263.  20x20 1 bpp (black and white) 
  264.  16x16 1 bpp (black and white) 
  265.  
  266.  The 32x32 versions are designed for VGA displays and for device-independent use. 
  267.  
  268.  The 40x40 version is for 8514/A and XGA displays. 
  269.  
  270.  The 20x20 and 16x16 are half-size icons designed for use as mini-icons. 
  271.  
  272.  For general bit maps, which may be of arbitrary size, the preferred version is one 
  273.  matching the requested bit map size; otherwise one matching the display size is 
  274.  selected.  If neither is available, the device-independent version is used from which to 
  275.  scale a bit map. 
  276.  
  277.  For both formats, the definition consists of two sections.  The first section contains 
  278.  general information about the type, dimensions, and other attributes of the resource.  
  279.  The second section contains data describing the pels that make up the bit map(s), and 
  280.  is in the format specified in Bit-Map Data. 
  281.  
  282.  In the multiple-version format, the first section contains an array of 
  283.  BITMAPARRAYFILEHEADER structures. or BITMAPARRAYFILEHEADER2 structures. The 
  284.  format of these is as follows: 
  285.  
  286.  typedef struct _BITMAPARRAYFILEHEADER {    /* bafh */
  287.      USHORT            usType;
  288.      ULONG             cbSize;
  289.      ULONG             offNext;
  290.      USHORT            cxDisplay;
  291.      USHORT            cyDisplay;
  292.      BITMAPFILEHEADER  bfh;
  293.  } BITMAPARRAYFILEHEADER;
  294.  typedef BITMAPARRAYFILEHEADER *PBITMAPARRAYFILEHEADER;
  295.  
  296.  typedef struct _BITMAPARRAYFILEHEADER2 {    /* bafh */
  297.      USHORT            usType;
  298.      ULONG             cbSize;
  299.      ULONG             offNext;
  300.      USHORT            cxDisplay;
  301.      USHORT            cyDisplay;
  302.      BITMAPFILEHEADER2 bfh2;
  303.  } BITMAPARRAYFILEHEADER2;
  304.  typedef BITMAPARRAYFILEHEADER2 *PBITMAPARRAYFILEHEADER2;
  305.  
  306.  The fields in BITMAPARRAYFILEHEADER and BITMAPARRAYFILEHEADER2 have these 
  307.  meanings: 
  308.  
  309.  usType 
  310.    
  311.     Type of structure. This is: 
  312.  
  313.     BFT_BITMAPARRAY (X'4142' - 'BA' for BITMAPARRAYFILEHEADER or 
  314.     BITMAPARRAYFILEHEADER2) 
  315.  
  316.  cbSize 
  317.    
  318.     Size of the BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 structure in 
  319.     bytes. 
  320.  
  321.  offNext 
  322.    
  323.     Offset of the next BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 
  324.     structure from the start of the file 
  325.  
  326.  cxDisplay, cyDisplay 
  327.    
  328.     pel dimensions of the device for which this version is intended (for example, 640 x 
  329.     480 for VGA). 
  330.  
  331.  The device-independent version must be the first BITMAPARRAYFILEHEADER or 
  332.  BITMAPARRAYFILEHEADER2 defined. 
  333.  
  334.  In the single-size format, the BITMAPARRAYFILEHEADER or BITMAPARRAYFILEHEADER2 
  335.  structure is not present. The definition consists of one or two BITMAPFILEHEADER or 
  336.  BITMAPFILEHEADER2 structures. 
  337.  
  338.  The format of the BITMAPFILEHEADER and BITMAPFILEHEADER2 structure is : 
  339.  
  340.  typedef struct _BITMAPFILEHEADER {    /* bfh */
  341.      USHORT            usType;
  342.      ULONG             cbSize;
  343.      SHORT             xHotspot;
  344.      SHORT             yHotspot;
  345.      ULONG             offBits;
  346.      BITMAPINFOHEADER  bmp;
  347.  } BITMAPFILEHEADER;
  348.  typedef BITMAPFILEHEADER *PBITMAPFILEHEADER;
  349.  
  350.  typedef struct _BITMAPFILEHEADER2 {    /* bfh2 */
  351.      USHORT            usType;
  352.      ULONG             cbSize;
  353.      SHORT             xHotspot;
  354.      SHORT             yHotspot;
  355.      ULONG             offBits;
  356.      BITMAPINFOHEADER2 bmp2;
  357.  } BITMAPFILEHEADER2;
  358.  typedef BITMAPFILEHEADER2 *PBITMAPFILEHEADER2;
  359.  
  360.  BITMAPINFOHEADER2 is a standard data type (see above, and also 
  361.  BITMAPINFOHEADER2). 
  362.  
  363.  The fields in BITMAPFILEHEADER and BITMAPFILEHEADER2 have these meanings: 
  364.  
  365.  usType 
  366.    
  367.     Type of resource the file contains. The valid values are: 
  368.  
  369.     BFT_BMAP (X'4D42' - 'BM' for bit maps) 
  370.     BFT_ICON (X'4349' - 'IC' for icons) 
  371.     BFT_POINTER (X'5450' - 'PT' for pointers). 
  372.     BFT_COLORICON (X'4943' - 'CI' for color icons). 
  373.     BFT_COLORPOINTER (X'5043' - 'CP' for color pointers). 
  374.  
  375.  cbSize 
  376.    
  377.     Size of the BITMAPFILEHEADER or BITMAPFILEHEADER2 structure in bytes. 
  378.  
  379.  xHotspot, yHotspot 
  380.    
  381.     Coordinates of the hotspot for icons and pointers. This field is ignored for bit maps. 
  382.  
  383.  offBits 
  384.    
  385.     Offset in bytes to the beginning of the bit-map pel data in the file, from the start of 
  386.     the definition. 
  387.  
  388.  For icons and pointers, the cy field in bmp is actually twice the pel height of the image 
  389.  that appears on the screen.  This is because these types actually contain two full 
  390.  bit-map pel definitions. The first bit-map definition is the XOR mask, which contains 
  391.  invert information (0 = no invert, 1 = invert) for the pointer or icon.  The second is the 
  392.  AND mask, which determines whether the pointer or the screen is shown (0 = 
  393.  black/white, 1 = screen/inverse screen). 
  394.  
  395.  For color icons or pointers, there are two bit-maps involved: one that is black and white 
  396.  and consists of an AND and an XOR mask, and one that is color that defines the color 
  397.  content. 
  398.  
  399.  The cy field in the BITMAPINFOHEADER2 structure for the color bit-map must be the real 
  400.  height, that is, half the value specified for the black and white bit-map. The cx fields 
  401.  must be the same. 
  402.  
  403.  The following table shows how these two bit-maps are used for a color icon or pointer: 
  404.  
  405.     XOR     AND     COLOR
  406.      1       1        x       Invert screen
  407.      0       0        x       Use color x
  408.      0       1        x       Transparency
  409.      1       0        x       Use color x
  410.  
  411.  For color icons or pointers, two BITMAPFILEHEADER or BITMAPFILEHEADER2 structures 
  412.  are therefore required: 
  413.  
  414.  BITMAPFILEHEADER2    with usType BFT_COLORICON or BFT_COLORPOINTER
  415.     BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2)
  416.     Color table
  417.  BITMAPFILEHEADER2    with same usType
  418.     BITMAPINFOHEADER2 (part of BITMAPFILEHEADER2)
  419.     Color table
  420.  **
  421.  bits for one bit-map
  422.  **
  423.  **
  424.  bits for other bit-map
  425.  **
  426.  
  427.  The usType for the first BITMAPFILEHEADER2 is either BFT_COLORICON or 
  428.  BFT_COLORPOINTER. This means that a second BITMAPFILEHEADER2 is present as 
  429.  part of the definition of a color icon or pointer. The first BITMAPFILEHEADER2 structure 
  430.  contains the information for the black and white AND and XOR masks, while the second 
  431.  BITMAPFILEHEADER2 structure contains the information for the color part of the pointer 
  432.  or icon. 
  433.  
  434.  BITMAPFILEHEADER and BITMAPINFOHEADER can occur in place of 
  435.  BITMAPFILEHEADER2 and BITMAPINFOHEADER2 in this example. 
  436.  
  437.  For the multiple version format, the file is as follows: 
  438.  
  439.  BITMAPARRAYFILEHEADER2   for device-independent version
  440.     BITMAPFILEHEADER2     (part of BITMAPARRAYFILEHEADER2)
  441.        BITMAPINFOHEADER2  (part of BITMAPFILEHEADER2)
  442.        Color table
  443.  
  444.     BITMAPFILEHEADER2     )
  445.        BITMAPINFOHEADER2  )  only if this is a color icon or pointer
  446.        Color table        )
  447.  
  448.  BITMAPARRAYFILEHEADER2   for first device-dependent version
  449.     BITMAPFILEHEADER2     (part of BITMAPARRAYFILEHEADER2)
  450.        BITMAPINFOHEADER2  (part of BITMAPFILEHEADER2)
  451.        Color table
  452.  
  453.     BITMAPFILEHEADER2     )
  454.        BITMAPINFOHEADER2  )  only if this is a color icon or pointer
  455.        Color table        )
  456.  
  457.  Further BITMAPARRAYFILEHEADER2 groups occur here as required
  458.  for additional device-dependent versions
  459.  
  460.  **
  461.  bits for one bit-map
  462.  **
  463.  **
  464.  bits for next bit-map
  465.  **
  466.  
  467.  And so on for as many bit-maps as necessary.
  468.  
  469.  As before, BITMAPARRAYFILEHEADER, BITMAPFILEHEADER and BITMAPINFOHEADER 
  470.  can occur in place of BITMAPARRAYFILEHEADER2, BITMAPFILEHEADER2 and 
  471.  BITMAPINFOHEADER2.   
  472.  
  473.  
  474.  The pel data is stored in the bit map in the order that the coordinates appear on a 
  475.  display screen. That is, the pel in the lower-left corner is the first in the bit map. Pels 
  476.  are scanned to the right, and upward, from that position. The bits of the first pel are 
  477.  stored, beginning with the most significant bits of the first byte. The data for pels in 
  478.  each scan line is packed together tightly, but all scan lines are padded at the end, so 
  479.  that each one begins on a ULONG boundary. 
  480.  
  481.