home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsf / ifftext / ILBM < prev    next >
Text File  |  1993-06-21  |  21KB  |  489 lines
  1. "ILBM" IFF Interleaved Bitmap
  2.  
  3. Date:   January 17, 1986
  4. From:   Jerry Morrison, Electronic Arts
  5. Status: Released and in use
  6.  
  7. 1. Introduction
  8.  
  9. "EA IFF 85" is Electronic Arts' standard for interchange format files. 
  10. "ILBM" is a format for a 2 dimensional raster graphics image, specifically 
  11. an InterLeaved bitplane BitMap image with color map. An ILBM is an 
  12. IFF "data section" or "FORM type", which can be an IFF file or a part 
  13. of one. (See the IFF reference.)
  14.  
  15. An ILBM is an archival representation designed for three uses. First, 
  16. a standalone image that specifies exactly how to display itself (resolution, 
  17. size, color map, etc.). Second, an image intended to be merged into 
  18. a bigger picture which has its own depth, color map, and so on. And 
  19. third, an empty image with a color map selection or "palette" for 
  20. a paint program. ILBM is also intended as a building block for composite 
  21. IFF FORMs like "animation sequence" and "structured graphics". Some 
  22. uses of ILBM will be to preserve as much information as possible across 
  23. disparate environments. Other uses will be to store data for a single 
  24. program or highly cooperative programs while maintaining subtle details. 
  25. So we're trying to accomplish a lot with this one format.
  26.  
  27. This memo is the IFF supplement for FORM ILBM. Section 2 defines the 
  28. purpose and format of property chunks bitmap header "BMHD", color 
  29. map "CMAP", hotspot "GRAB", destination merge data "DEST", sprite 
  30. information "SPRT", and Commodore Amiga viewport mode "CAMG". Section 
  31. 3 defines the standard data chunk "BODY". These are the "standard" 
  32. chunks. Section 4 defines the nonstandard color range data chunk "CRNG". 
  33. Additional specialized chunks like texture pattern can be added later. 
  34. The ILBM syntax is summarized in Appendix A as a regular expression 
  35. and in Appendix B as a box diagram. Appendix C explains the optional 
  36. run encoding scheme. Appendix D names the committee responsible for 
  37. this FORM ILBM standard.
  38.  
  39. Details of the raster layout are given in part 3, "Standard Data Chunk". 
  40. Some elements are based on the Commodore Amiga hardware but generalized 
  41. for use on other computers. An alternative to ILBM would be appropriate 
  42. for computers with true color data in each pixel.
  43.  
  44. Reference:
  45.  
  46. "EA IFF 85" Standard for Interchange Format Files describes the underlying 
  47. conventions for all IFF files.
  48.  
  49. Amiga[tm] is a trademark of Commodore-Amiga, Inc.
  50. Electronic Arts[tm] is a trademark of Electronic Arts.
  51. Macintosh[tm] is a trademark licensed to Apple Computer, Inc.
  52. MacPaint[tm] is a trademark of Apple Computer, Inc.
  53.  
  54.  
  55. 2. Standard Properties
  56.  
  57. The required property "BMHD" and any optional properties must appear 
  58. before any "BODY" chunk. (Since an ILBM has only one BODY chunk, any 
  59. following properties are superfluous.) Any of these properties may 
  60. be shared over a LIST of FORMs IBLM by putting them in a PROP ILBM. 
  61. (See the "EA IFF 85" memo.)
  62.  
  63. BMHD
  64.  
  65. The required property "BMHD" holds a BitMapHeader as defined in these 
  66. C declarations and following documentation. It describes the dimensions 
  67. and encoding of the image, including data necessary to understand 
  68. the BODY chunk to follow.
  69.  
  70. typedef UBYTE Masking;  /* Choice of masking technique. */
  71.  
  72. #define mskNone 0
  73. #define mskHasMask      1
  74. #define mskHasTransparentColor  2
  75. #define mskLasso        3
  76.  
  77. typedef UBYTE Compression;      
  78.         /* Choice of compression algorithm applied to the rows of all 
  79.          * source and mask planes. "cmpByteRun1" is the byte run encoding 
  80.          * described in Appendix C. Do not compress across rows! */
  81. #define cmpNone 0
  82. #define cmpByteRun1     1
  83.  
  84. typedef struct {
  85.         UWORD w, h;     /* raster width & height in pixels      */
  86.         WORD  x, y;     /* pixel position for this image        */
  87.         UBYTE nPlanes;  /* # source bitplanes   */
  88.         Masking masking;
  89.         Compression compression;
  90.         UBYTE pad1;     /* unused; for consistency, put 0 here  */
  91.         UWORD transparentColor; /* transparent "color number" (sort of) */
  92.         UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
  93.         WORD  pageWidth, pageHeight;    /* source "page" size in pixels */
  94.         } BitMapHeader;
  95.  
  96. Fields are filed in the order shown. The UBYTE fields are byte-packed.
  97.  
  98. The fields w and h indicate the size of the image rectangle in pixels. 
  99. Each row of the image is stored in an integral number of 16 bit words. 
  100. The number of words per row is Ceiling(w/16). The fields x and y indicate 
  101. the desired position of this image within the destination picture. 
  102. Some reader programs may ignore x and y. A safe default for writing 
  103. an ILBM is (x, y) = (0, 0).
  104.  
  105. The number of source bitplanes in the BODY chunk (see below) is stored 
  106. in nPlanes. An ILBM with a CMAP but no BODY and nPlanes = 0 is the 
  107. recommended way to store a color map.
  108.  
  109. Note: Color numbers are color map index values formed by pixels in 
  110. the destination bitmap, which may be deeper than nPlanes if a DEST 
  111. chunk calls for merging the image into a deeper image.
  112.  
  113. The field masking indicates what kind of masking is to be used for 
  114. this image. The value mskNone designates an opaque rectangular image. 
  115. The value mskHasMask means that a mask plane is interleaved with the 
  116. bitplanes in the BODY chunk (see below). The value mskHasTransparentColor 
  117. indicates that pixels in the source planes matching transparentColor 
  118. are to be considered "transparent". (Actually, transparentColor isn't 
  119. a "color number" since it's matched with numbers formed by the source 
  120. bitmap rather than the possibly deeper destination bitmap. Note that 
  121. having a transparent color implies ignoring one of the color registers. 
  122. See CMAP, below.) The value mskLasso indicates the reader may construct 
  123. a mask by lassoing the image as in MacPaint*. To do this, put a 1 
  124. pixel border of transparentColor around the image rectangle. Then 
  125. do a seed fill from this border. Filled pixels are to be transparent.
  126.  
  127. Issue: Include in an appendix an algorithm for converting a transparent 
  128. color to a mask plane, and maybe a lasso algorithm.
  129.  
  130. A code indicating the kind of data compression used is stored in compression. 
  131. Beware that using data compression makes your data unreadable by programs 
  132. that don't implement the matching decompression algorithm. So we'll 
  133. employ as few compression encodings as possible. The run encoding 
  134. byteRun1 is documented in Appendix C, below.
  135.  
  136. The field pad1 is a pad byte and must be set to 0 for consistency. 
  137. This field could get used in the future.
  138.  
  139. The transparentColor specifies which bit pattern means "transparent".  
  140. This only applies if masking is mskHasTransparentColor or mskLasso 
  141. (see above). Otherwise, transparentColor should be 0.
  142.  
  143. The pixel aspect ratio is stored as a ratio in the two fields xAspect 
  144. and yAspect. This may be used by programs to compensate for different 
  145. aspects or to help interpret the fields w, h, x, y, pageWidth, and 
  146. pageHeight, which are in units of pixels. The fraction xAspect/yAspect 
  147. represents a pixel's width/height. It's recommended that your programs 
  148. store proper fractions in BitMapHeaders, but aspect ratios can always 
  149. be correctly compared with the the test
  150.  
  151. xAspect%yDesiredAspect = yAspect%xDesiredAspect
  152.  
  153. Typical values for aspect ratio are width : height = 10 : 11 (Amiga 
  154. 320 x 200 display) and 1 : 1 (Macintosh*).
  155.  
  156. The size in pixels of the source "page" (any raster device) is stored 
  157. in pageWidth and pageHeight, e.g. (320, 200) for a low resolution 
  158. Amiga display. This information might be used to scale an image or 
  159. to automatically set the display format to suit the image. (The image 
  160. can be larger than the page.)
  161.  
  162. CMAP
  163.  
  164. The optional (but encouraged) property "CMAP" stores color map data 
  165. as triplets of red, green, and blue intensity values. The n color 
  166. map entries ("color registers") are stored in the order 0 through 
  167. n-1, totaling 3n bytes. Thus n is the ckSize/3. Normally, n would 
  168. equal 2nPlanes.
  169.  
  170. A CMAP chunk contains a ColorMap array as defined below. (These typedefs 
  171. assume a C compiler that implements packed arrays of 3-byte elements.)
  172.  
  173. typedef struct {
  174.         UBYTE red, green, blue; /* color intensities 0..255 */
  175.         } ColorRegister;        /* size = 3 b