home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 1: Collection A / 17Bit_Collection_A.iso / files / 61.dms / 61.adf / iff.text / ilbm < prev    next >
Text File  |  1986-03-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 bytes */
  176.  
  177. typedef ColorRegister ColorMap[n];    /* size = 3n bytes */
  178.  
  179. The color components red, green, and blue represent fractional intensity 
  180. values in the range 0 through 255 256ths. White is (255, 255, 255) 
  181. and black is (0, 0, 0). If your machine has less color resolution, 
  182. use the high order bits. Shift each field right on reading (or left 
  183. on writing) and assign it to (from) a field in a local packed format 
  184. like Color4, below. This achieves automatic conversion of images across 
  185. environments with different color resolutions. On reading an ILBM, 
  186. use defaults if the color map is absent or has fewer color registers 
  187. than you need. Ignore any extra color registers.
  188.  
  189. The example type Color4 represents the format of a color register 
  190. in working memory of an Amiga computer, which has 4 bit video DACs. 
  191. (The ":4" tells the C compiler to pack the field into 4 bits.)
  192.  
  193. typedef struct {
  194.     unsigned pad1 :4, red :4, green :4, blue :4;
  195.     } Color4;    /* Amiga RAM format. Not filed. */
  196.  
  197. Remember that every chunk must be padded to an even length, so a color 
  198. map with an odd number of entries would be followed by a 0 byte, not 
  199. included in the ckSize.
  200.  
  201. GRAB
  202.  
  203. The optional property "GRAB" locates a "handle" or "hotspot" of the 
  204. image relative to its upper left corner, e.g. when used as a mouse 
  205. cursor or a "paint brush". A GRAB chunk contains a Point2D.
  206.  
  207. typedef struct {
  208.     WORD x, y;    /* relative coordinates (pixels) */
  209.     } Point2D;
  210.  
  211. DEST
  212.  
  213. The optional property "DEST" is a way to say how to scatter zero or 
  214. more source bitplanes into a deeper destination image. Some readers 
  215. may ignore DEST.
  216.  
  217. The contents of a DEST chunk is DestMerge structure:
  218.  
  219. typedef struct {
  220.     UBYTE depth;    /* # bitplanes in the original source    */
  221.     UBYTE pad1;    /* unused; for consistency put 0 here    */
  222.     UWORD planePick; /* how to scatter source bitplanes into destination */
  223.     UWORD planeOnOff;    /* default bitplane data for planePick    */
  224.     UWORD planeMask;    /* selects which bitplanes to store into */
  225.     } DestMerge;
  226.  
  227. The low order depth number of bits in planePick, planeOnOff, and planeMask 
  228. correspond one-to-one with destination bitplanes. Bit 0 with bitplane 
  229. 0, etc. (Any higher order bits should be ignored.) "1" bits in planePick 
  230. mean "put the next source bitplane into this bitplane", so the number 
  231. of "1" bits should equal nPlanes. "0" bits mean "put the corresponding 
  232. bit from planeOnOff into this bitplane". Bits in planeMask gate writing 
  233. to the destination bitplane: "1" bits mean "write to this bitplane" 
  234. while "0" bits mean "leave this bitplane alone". The normal case (with 
  235. no DEST property) is equivalent to planePick = planeMask = 2nPlanesJ- 
  236. 1.
  237.  
  238. Remember that color numbers are formed by pixels in the destination 
  239. bitmap (depth planes deep) not in the source bitmap (nPlanes planes 
  240. deep).
  241.  
  242. SPRT
  243.  
  244. The presence of an "SPRT" chunk indicates that this image is intended 
  245. as a sprite. It's up to the reader program to actually make it a sprite, 
  246. if even possible, and to use or overrule the sprite precedence data 
  247. inside the SPRT chunk:
  248.  
  249. typedef UWORD SpritePrecedence; /* relative precedence, 0 is the highest */
  250.  
  251. Precedence 0 is the highest, denoting a sprite that is foremost.
  252.  
  253. Creating a sprite may imply other setup. E.g. a 2 plane Amiga sprite 
  254. would have transparentColor = 0. Color registers 1, 2, and 3 in the 
  255. CMAP would be stored into the correct hardware color registers for 
  256. the hardware sprite number used, while CMAP color register 0 would 
  257. be ignored.
  258.  
  259. CAMG
  260.  
  261. A "CAMG" chunk is specifically for the Commodore Amiga computer. It 
  262. stores a LONG "viewport mode". This lets you specify Amiga display 
  263. modes like "dual playfield" and "hold and modify".
  264. 3. Standard Data Chunk
  265.  
  266. Raster Layout
  267.  
  268. Raster scan proceeds left-to-right (increasing X) across scan lines, 
  269. then top-to-bottom (increasing Y) down columns of scan lines. The 
  270. coordinate system is in units of pixels, where (0,0) is the upper 
  271. left corner.
  272.  
  273. The raster is typically organized as bitplanes in memory. The corresponding 
  274. bits from each plane, taken together, make up an index into the color 
  275. map which gives a color value for that pixel. The first bitplane, 
  276. plane 0, is the low order bit of these color indexes.
  277.  
  278. A scan line is made of one "row" from each bitplane. A row is one 
  279. planesU bits for one scan line, but padded out to a word (2 byte) 
  280. boundary (not necessarily the first word boundary). Within each row, 
  281. successive bytes are displayed in order and the most significant bit 
  282. of each byte is displayed first.
  283.  
  284. A "mask" is an optional "plane" of data the same size (w, h) as a 
  285. bitplane.  It tells how to "cut out" part of the image when painting 
  286. it onto another image."One" bits in the mask mean "copy the corresponding 
  287. pixel to the destination" while "zero" mask bits mean "leave this 
  288. destination pixel alone". In other words, "zero" bits designate transparent 
  289. pixels.
  290.  
  291. The rows of the different bitplanes and mask are interleaved in the 
  292. file (see below). This localizes all the information pertinent to 
  293. each scan line. It makes it much easier to transform the data while 
  294. reading it to adjust the image size or depth. It also makes it possible 
  295. to scroll a big image by swapping rows directly from the file without 
  296. random-accessing to all the bitplanes.
  297.  
  298. BODY
  299.  
  300. The source raster  is stored in a "BODY" chunk. This one chunk holds 
  301. all bitplanes and the optional mask, interleaved by row.
  302.  
  303. The BitMapHeader, in a BMHD property chunk, specifies the raster's 
  304. dimensions w, h, and nPlanes. It also holds the masking field which 
  305. indicates if there is a mask plane and the compression field which 
  306. indicates the compression algorithm used. This information is needed 
  307. to interpret the BODY chunk, so the BMHD chunk must appear first. 
  308. While reading an ILBM's BODY, a program may convert the image to another 
  309. size by filling (with transparentColor) or clipping.
  310.  
  311. The BODY's content is a concatenation of scan lines. Each scan line 
  312. is a concatenation of one row of data from each plane in order 0 through 
  313. nPlanes-1 followed by one row from the mask (if masking = hasMask 
  314. ). If the BitMapHeader field compression is cmpNone, all h rows are 
  315. exactly Ceiling(w/16) words wide. Otherwise, every row is compressed 
  316. according to the specified algorithm and their stored widths depend 
  317. on the data compression.
  318.  
  319. Reader programs that require fewer bitplanes than appear in a particular 
  320. ILBM file can combine planes or drop the high-order (later) planes. 
  321. Similarly, they may add bitplanes and/or discard the mask plane.
  322.  
  323. Do not compress across rows and don't forget to compress the mask 
  324. just like the bitplanes. Remember to pad any BODY chunk that contains 
  325. an odd number of bytes.
  326. 4. Nonstandard Data Chunk
  327.  
  328. The following data chunk was defined after various programs began 
  329. using FORM ILBM so it's a "nonstandard" chunk. That means there's 
  330. some slight chance of name collisions.
  331.  
  332. CRNG
  333.  
  334. A "CRNG" chunk contains "color register range" information. It's used 
  335. by Electronic Arts' Deluxe Paint program to identify a contiguous 
  336. range of color registers for a "shade range" and color cycling. There 
  337. can be zero or more CRNG chunks in an ILBM, but all should appear 
  338. before the BODY chunk. Deluxe Paint normally writes 4 CRNG chunks 
  339. in an ILBM when the user asks it to "Save Picture".
  340.  
  341. typedef struct {
  342.     WORD  pad1;    /* reserved for future use; store 0 here    */
  343.     WORD  rate;    /* color cycle rate    */
  344.     WORD  active;    /* nonzero means cycle the colors    */
  345.     UBYTE low, high; /* lower and upper color registers selected    */
  346.     } CRange;
  347.  
  348. The fields low and high indicate the range of color registers (color 
  349. numbers) selected by this CRange.
  350.  
  351. The field active indicates whether color cycling is on or off. Zero 
  352. means off.
  353.  
  354. The field rate determines the speed at which the colors will step 
  355. when color cycling is on. The units are such that a rate of 60 steps 
  356. per second is represented as 214 = 16384. Slower rates can be obtained 
  357. by linear scaling: for 30 steps/second, rate = 8192; for 1 step/second, 
  358. rate = 16384/60 E 273.
  359.  
  360. CCRT
  361.  
  362. Commodore's Graphicraft program uses a similar chunk "CCRT" (for Color 
  363. Cyling Range and Timing). This chunk contains a CycleInfo structure.
  364.  
  365. typedef struct {
  366.     WORD  direction; /* 0 = don't cycle. 1 = cycle forwards (1, 2, 3).
  367.                * -1 = cycle backwards (3, 2, 1)    */
  368.     UBYTE start, end;  /* lower and upper color registers selected    */
  369.     LONG  seconds;       /* # seconds between changing colors    */
  370.     LONG  microseconds;    /* # microseconds between changing colors */ 
  371.     WORD  pad;        /* reserved for future use; store 0 here  */ 
  372.     } CycleInfo;
  373.  
  374. This is pretty similar to a CRNG chunk. A program would probably only 
  375. use one of these two methods of expressing color cycle data. You could 
  376. write out both if you want to communicate this information to both 
  377. Deluxe Paint and Graphicraft.
  378.  
  379. A CCRT chunk expresses the color cycling rate as a number of seconds 
  380. plus a number of microseconds.
  381.  
  382.  
  383.  
  384. Appendix A. ILBM Regular Expression
  385.  
  386. Here's a regular expression summary of the FORM ILBM syntax. This 
  387. could be an IFF file or a part of one.
  388.  
  389. ILBM ::= "FORM" #{    "ILBM" BMHD [CMAP] [GRAB] [DEST] [SPRT] [CAMG]
  390.     CRNG* CCRT* [BODY]    }
  391.  
  392. BMHD ::= "BMHD" #{    BitMapHeader    }
  393. CMAP ::= "CMAP" #{    (red green blue)*    } [0]
  394. GRAB ::= "GRAB" #{    Point2D    }
  395. DEST ::= "DEST" #{    DestMerge    }
  396. SPRT ::= "SPRT" #{    SpritePrecendence    }
  397. CAMG ::= "CAMG" #{    LONG    }
  398.  
  399. CRNG ::= "CRNG" #{    CRange    }
  400. CCRT ::= "CCRT" #{    CycleInfo    }
  401. BODY ::= "BODY" #{    UBYTE*    } [0]
  402.  
  403. The token "#" represents a ckSize LONG count of the following {braced} 
  404. data bytes. E.g. a BMHD's "#" should equal sizeof(BitMapHeader). Literal 
  405. strings are shown in "quotes", [square bracket items] are optional, 
  406. and "*" means 0 or more repetitions. A sometimes-needed pad byte is 
  407. shown as "[0]".
  408.  
  409. The property chunks (BMHD, CMAP, GRAB, DEST, SPRT, and CAMG) and any 
  410. CRNG and CCRT data chunks may actually be in any order but all must 
  411. appear before the BODY chunk since ILBM readers usually stop as soon 
  412. as they read the BODY. If any of the 6 property chunks are missing, 
  413. default values are "inherited" from any shared properties (if the 
  414. ILBM appears inside an IFF LIST with PROPs) or from the reader program's 
  415. defaults. If any property appears more than once, the last occurrence 
  416. before the BODY is the one that counts since that's the one that modifies 
  417. the BODY.
  418.  
  419.  
  420.  
  421. Appendix B. ILBM Box Diagram
  422.  
  423. Here's a box diagram for a simple example: an uncompressed image 320 
  424. x 200 pixels x 3 bitplanes. The text to the right of the diagram shows 
  425. the outline that would be printed by the IFFCheck utility program 
  426. for this particular file.
  427.  
  428.  
  429.         +-----------------------------------+
  430.         |'FORM'         24070               |   FORM 24070 IBLM
  431.         +-----------------------------------+
  432.         |'ILBM'                             |
  433.         +-----------------------------------+
  434.         | +-------------------------------+ |
  435.         | | 'BMHD'      20                | |   .BMHD  20
  436.         | | 320, 200, 0, 0, 3, 0, 0, ...  | |
  437.         | + ------------------------------+ |
  438.         | | 'CMAP'      21                | |   .CMAP  21
  439.         | | 0, 0, 0; 32, 0, 0; 64,0,0; .. | |
  440.         | +-------------------------------+ |
  441.         | 0                                 |
  442.         +-----------------------------------+
  443.         |'BODY'         24000               |   .BODY 24000
  444.         |0, 0, 0, ...                       |
  445.         +-----------------------------------+
  446.  
  447.  
  448.  
  449. The "0" after the CMAP chunk is a pad byte.
  450.  
  451.  
  452.  
  453. Appendix C. ByteRun1 Run Encoding
  454.  
  455. The run encoding scheme byteRun1 is best described by psuedo code 
  456. for the decoder Unpacker (called UnPackBits in the Macintosh* toolbox):
  457.  
  458. UnPacker:
  459.     LOOP until produced the desired number of bytes
  460.         Read the next source byte into n
  461.         SELECT n FROM
  462.             [0..127]    => copy the next n+1 bytes literally
  463.             [-1..-127]    => replicate the next byte -n+1 times
  464.             -128    => noop
  465.             ENDCASE;
  466.         ENDLOOP;
  467.  
  468. In the inverse routine Packer, it's best to encode a 2 byte repeat 
  469. run as a replicate run except when preceded and followed by a literal 
  470. run, in which case it's best to merge the three into one literal run. 
  471. Always encode 3 byte repeats as replicate runs.
  472.  
  473. Remember that each row of each scan line of a raster is separately 
  474. packed.
  475.  
  476.  
  477.  
  478. Appendix D. Standards Committee
  479.  
  480. The following people contributed to the design of this FORM ILBM standard:
  481.  
  482. Bob "Kodiak" Burns, Commodore-Amiga
  483. R. J. Mical, Commodore-Amiga
  484. Jerry Morrison, Electronic Arts
  485. Greg Riker, Electronic Arts
  486. Steve Shaw, Electronic Arts
  487. Dan Silva, Electronic Arts
  488. Barry Walsh, Commodore-Amiga
  489.