]> 4ch.mooo.com Git - 16.git/blob - 16/PCGPE10/IFF.DOC
reverted my open watcom to 1.9 an recompiled everything~
[16.git] / 16 / PCGPE10 / IFF.DOC
1 \r
2 \r
3 "EA IFF 85" Standard for Interchange Format Files\r
4 \r
5 Document Date:          January 14, 1985\r
6 From:                   Jerry Morrison, Electronic Arts\r
7 Status of Standard:     Released and in use\r
8 \r
9 1. Introduction\r
10 \r
11 Standards are Good for Software Developers\r
12 \r
13 As home computer hardware evolves to better and better media machines, \r
14 the demand increases for higher quality, more detailed data. Data \r
15 development gets more expensive, requires more expertise and better \r
16 tools, and has to be shared across projects. Think about several ports \r
17 of a product on one CD-ROM with 500M Bytes of common data!\r
18 \r
19 Development tools need standard interchange file formats. Imagine \r
20 scanning in images of "player" shapes, moving them to a paint program \r
21 for editing, then incorporating them into a game. Or writing a theme \r
22 song with a Macintosh score editor and incorporating it into an Amiga \r
23 game. The data must at times be transformed, clipped, filled out, \r
24 and moved across machine kinds. Media projects will depend on data \r
25 transfer from graphic, music, sound effect, animation, and script \r
26 tools.\r
27 \r
28 Standards are Good for Software Users\r
29 \r
30 Customers should be able to move their own data between independently \r
31 developed software products. And they should be able to buy data libraries \r
32 usable across many such products. The types of data objects to exchange \r
33 are open-ended and include plain and formatted text, raster and structured \r
34 graphics, fonts, music, sound effects, musical instrument descriptions, \r
35 and animation.\r
36 \r
37 The problem with expedient file formats typically memory dumps is \r
38 that they're too provincial. By designing data for one particular \r
39 use (e.g. a screen snapshot), they preclude future expansion (would \r
40 you like a full page picture? a multi-page document?). In neglecting \r
41 the possibility that other programs might read their data, they fail \r
42 to save contextual information (how many bit planes? what resolution?). \r
43 Ignoring that other programs might create such files, they're intolerant \r
44 of extra data (texture palette for a picture editor), missing data \r
45 (no color map), or minor variations (smaller image). In practice, \r
46 a filed representation should rarely mirror an in-memory representation. \r
47 The former should be designed for longevity; the latter to optimize \r
48 the manipulations of a particular program. The same filed data will \r
49 be read into different memory formats by different programs.\r
50 \r
51 The IFF philosophy: "A little behind-the-scenes conversion when programs \r
52 read and write files is far better than NxM explicit conversion utilities \r
53 for highly specialized formats."\r
54 \r
55 So we need some standardization for data interchange among development \r
56 tools and products. The more developers that adopt a standard, the \r
57 better for all of us and our customers.\r
58 \r
59 Here is "EA IFF 1985"\r
60 \r
61 Here is our offering: Electronic Arts' IFF standard for Interchange \r
62 File Format. The full name is "EA IFF 1985". Alternatives and justifications \r
63 are included for certain choices. Public domain subroutine packages \r
64 and utility programs are available to make it easy to write and use \r
65 IFF-compatible programs.\r
66 \r
67 Part 1 introduces the standard. Part 2 presents its requirements and \r
68 background. Parts 3, 4, and 5 define the primitive data types, FORMs, \r
69 and LISTs, respectively, and how to define new high level types. Part \r
70 6 specifies the top level file structure. Appendix A is included for \r
71 quick reference and Appendix B names the committee responsible for \r
72 this standard.\r
73 \r
74 References\r
75 \r
76 American National Standard Additional Control Codes for Use with ASCII, \r
77 ANSI standard 3.64-1979 for an 8-bit character set. See also ISO standard \r
78 2022 and ISO/DIS standard 6429.2.\r
79 \r
80 Amiga[tm] is a trademark of Commodore-Amiga, Inc.\r
81 \r
82 C, A Reference Manual, Samuel P. Harbison and Guy L. Steele Jr., Tartan \r
83 Laboratories. Prentice-Hall, Englewood Cliffs, NJ, 1984.\r
84 \r
85 Compiler Construction, An Advanced Course, edited by F. L. Bauer and \r
86 J. Eickel (Springer-Verlag, 1976). This book is one of many sources \r
87 for information on recursive descent parsing.\r
88 \r
89 DIF Technical Specification (c)1981 by Software Arts, Inc. DIF[tm] is \r
90 the format for spreadsheet data interchange developed by Software \r
91 Arts, Inc.\r
92 DIF[tm] is a trademark of Software Arts, Inc.\r
93 \r
94 Electronic Arts[tm] is a trademark of Electronic Arts.\r
95 \r
96 "FTXT" IFF Formatted Text, from Electronic Arts. IFF supplement document \r
97 for a text format.\r
98 \r
99 Inside Macintosh (c) 1982, 1983, 1984, 1985 Apple Computer, Inc., a \r
100 programmer's reference manual.\r
101 Apple(R) is a trademark of Apple Computer, Inc.\r
102 Macintosh[tm] is a trademark licensed to Apple Computer, Inc.\r
103 \r
104 "ILBM" IFF Interleaved Bitmap, from Electronic Arts. IFF supplement \r
105 document for a raster image format.\r
106 \r
107 M68000 16/32-Bit Microprocessor Programmer's Reference Manual(c) 1984, \r
108 1982, 1980, 1979 by Motorola, Inc.\r
109 \r
110 PostScript Language Manual (c) 1984 Adobe Systems Incorporated.\r
111 PostScript[tm] is a trademark of Adobe Systems, Inc.\r
112 Times and Helvetica(R) are trademarks of Allied Corporation.\r
113 \r
114 InterScript: A Proposal for a Standard for the Interchange of Editable \r
115 Documents (c)1984 Xerox Corporation.\r
116 Introduction to InterScript (c) 1985 Xerox Corporation.\r
117 \r
118 \r
119 \f\r
120 2. Background for Designers\r
121 \r
122 Part 2 is about the background, requirements, and goals for the standard. \r
123 It's geared for people who want to design new types of IFF objects. \r
124 People just interested in using the standard may wish to skip this \r
125 part.\r
126 \r
127 What Do We Need?\r
128 \r
129 A standard should be long on prescription and short on overhead. It \r
130 should give lots of rules for designing programs and data files for \r
131 synergy. But neither the programs nor the files should cost too much \r
132 more than the expedient variety. While we're looking to a future with \r
133 CD-ROMs and perpendicular recording, the standard must work well on \r
134 floppy disks.\r
135 \r
136 For program portability, simplicity, and efficiency, formats should \r
137 be designed with more than one implementation style in mind. (In practice, \r
138 pure stream I/O is adequate although random access makes it easier \r
139 to write files.) It ought to be possible to read one of many objects \r
140 in a file without scanning all the preceding data. Some programs need \r
141 to read and play out their data in real time, so we need good compromises \r
142 between generality and efficiency.\r
143 \r
144 As much as we need standards, they can't hold up product schedules. \r
145 So we also need a kind of decentralized extensibility where any software \r
146 developer can define and refine new object types without some "standards \r
147 authority" in the loop. Developers must be able to extend existing \r
148 formats in a forward- and backward-compatible way. A central repository \r
149 for design information and example programs can help us take full \r
150 advantage of the standard.\r
151 \r
152 For convenience, data formats should heed the restrictions of various \r
153 processors and environments. E.g. word-alignment greatly helps 68000 \r
154 access at insignificant cost to 8088 programs.\r
155 \r
156 Other goals include the ability to share common elements over a list \r
157 of objects and the ability to construct composite objects containing \r
158 other data objects with structural information like directories.\r
159 \r
160 And finally, "Simple things should be simple and complex things should \r
161 be possible."   Alan Kay.\r
162 \r
163 Think Ahead\r
164 \r
165 Let's think ahead and build programs that read and write files for \r
166 each other and for programs yet to be designed. Build data formats \r
167 to last for future computers so long as the overhead is acceptable. \r
168 This extends the usefulness and life of today's programs and data.\r
169 \r
170 To maximize interconnectivity, the standard file structure and the \r
171 specific object formats must all be general and extensible. Think \r
172 ahead when designing an object. It should serve many purposes and \r
173 allow many programs to store and read back all the information they \r
174 need; even squeeze in custom data. Then a programmer can store the \r
175 available data and is encouraged to include fixed contextual details. \r
176 Recipient programs can read the needed parts, skip unrecognized stuff, \r
177 default missing data, and use the stored context to help transform \r
178 the data as needed.\r
179 \r
180 Scope\r
181 \r
182 IFF addresses these needs by defining a standard file structure, some \r
183 initial data object types, ways to define new types, and rules for \r
184 accessing these files. We can accomplish a great deal by writing programs \r
185 according to this standard, but don't expect direct compatibility \r
186 with existing software. We'll need conversion programs to bridge the \r
187 gap from the old world.\r
188 \r
189 IFF is geared for computers that readily process information in 8-bit \r
190 bytes. It assumes a "physical layer" of data storage and transmission \r
191 that reliably maintains "files" as strings of 8-bit bytes. The standard \r
192 treats a "file" as a container of data bytes and is independent of \r
193 how to find a file and whether it has a byte count.\r
194 \r
195 This standard does not by itself implement a clipboard for cutting \r
196 and pasting data between programs. A clipboard needs software to mediate \r
197 access, to maintain a "contents version number" so programs can detect \r
198 updates, and to manage the data in "virtual memory".\r
199 \r
200 Data Abstraction\r
201 \r
202 The basic problem is how to represent information  in a way that's \r
203 program-independent, compiler- independent, machine-independent, and \r
204 device-independent.\r
205 \r
206 The computer science approach is "data abstraction", also known as \r
207 "objects", "actors", and "abstract data types". A data abstraction \r
208 has a "concrete representation" (its storage format), an "abstract \r
209 representation" (its capabilities and uses), and access procedures \r
210 that isolate all the calling software from the concrete representation. \r
211 Only the access procedures touch the data storage. Hiding mutable \r
212 details behind an interface is called "information hiding". What data \r
213 abstraction does is abstract from details of implementing the object, \r
214 namely the selected storage representation and algorithms for manipulating \r
215 it.\r
216 \r
217 The power of this approach is modularity. By adjusting the access \r
218 procedures we can extend and restructure the data without impacting \r
219 the interface or its callers. Conversely, we can extend and restructure \r
220 the interface and callers without making existing data obsolete. It's \r
221 great for interchange!\r
222 \r
223 But we seem to need the opposite: fixed file formats for all programs \r
224 to access. Actually, we could file data abstractions ("filed objects") \r
225 by storing the data and access procedures together. We'd have to encode \r
226 the access procedures in a standard machine-independent programming \r
227 language   la PostScript. Even still, the interface can't evolve freely \r
228 since we can't update all copies of the access procedures. So we'll \r
229 have to design our abstract representations for limited evolution \r
230 and occasional revolution (conversion).\r
231 \r
232 In any case, today's microcomputers can't practically store data abstractions. \r
233 They can do the next best thing: store arbitrary types of data in \r
234 "data chunks", each with a type identifier and a length count. The \r
235 type identifier is a reference by name to the access procedures (any \r
236 local implementation). The length count enables storage-level object \r
237 operations like "copy" and "skip to next" independent of object type.\r
238 \r
239 Chunk writing is straightforward. Chunk reading requires a trivial \r
240 parser to scan each chunk and dispatch to the proper access/conversion \r
241 procedure. Reading chunks nested inside other chunks requires recursion, \r
242 but no lookahead or backup.\r
243 \r
244 That's the main idea of IFF. There are, of course, a few other detailsI\r
245 \r
246 Previous Work\r
247 \r
248 Where our needs are similar, we borrow from existing standards.\r
249 \r
250 Our basic need to move data between independently developed programs \r
251 is similar to that addressed by the Apple Macintosh desk scrap or \r
252 "clipboard" [Inside Macintosh chapter "Scrap Manager"]. The Scrap \r
253 Manager works closely with the Resource Manager, a handy filer and \r
254 swapper for data objects (text strings, dialog window templates, pictures, \r
255 fontsI) including types yet to be designed [Inside Macintosh chapter \r
256 "Resource Manager"]. The Resource Manager is a kin to Smalltalk's \r
257 object swapper.\r
258 \r
259 We will probably write a Macintosh desk accessory that converts IFF \r
260 files to and from the Macintosh clipboard for quick and easy interchange \r
261 with programs like MacPaint and Resource Mover.\r
262 \r
263 Macintosh uses a simple and elegant scheme of 4-character "identifiers" \r
264 to identify resource types, clipboard format types, file types, and \r
265 file creator programs. Alternatives are unique ID numbers assigned \r
266 by a central authority or by hierarchical authorities, unique ID numbers \r
267 generated by algorithm, other fixed length character strings, and \r
268 variable length strings. Character string identifiers double as readable \r
269 signposts in data files and programs. The choice of 4 characters is \r
270 a good tradeoff between storage space, fetch/compare/store time, and \r
271 name space size. We'll honor Apple's designers by adopting this scheme.\r
272 \r
273 "PICT" is a good example of a standard structured graphics format \r
274 (including raster images) and its many uses [Inside Macintosh chapter \r
275 "QuickDraw"]. Macintosh provides QuickDraw routines in ROM to create, \r
276 manipulate, and display PICTs. Any application can create a PICT by \r
277 simply asking QuickDraw to record a sequence of drawing commands. \r
278 Since it's just as easy to ask QuickDraw to render a PICT to a screen \r
279 or a printer, it's very effective to pass them between programs, say \r
280 from an illustrator to a word processor. An important feature is the \r
281 ability to store "comments" in a PICT which QuickDraw will ignore. \r
282 Actually, it passes them to your optional custom "comment handler".\r
283 \r
284 PostScript, Adobe's print file standard, is a more general way to \r
285 represent any print image (which is a specification for putting marks \r
286 on paper) [PostScript Language Manual]. In fact, PostScript is a full-fledged \r
287 programming language. To interpret a PostScript program is to render \r
288 a document on a raster output device. The language is defined in layers: \r
289 a lexical layer of identifiers, constants, and operators; a layer \r
290 of reverse polish semantics including scope rules and a way to define \r
291 new subroutines; and a printing-specific layer of built-in identifiers \r
292 and operators for rendering graphic images. It is clearly a powerful \r
293 (Turing equivalent) image definition language. PICT and a subset of \r
294 PostScript are candidates for structured graphics standards.\r
295 \r
296 A PostScript document can be printed on any raster output device (including \r
297 a display) but cannot generally be edited. That's because the original \r
298 flexibility and constraints have been discarded. Besides, a PostScript \r
299 program may use arbitrary computation to supply parameters like placement \r
300 and size to each operator. A QuickDraw PICT, in comparison, is a more \r
301 restricted format of graphic primitives parameterized by constants. \r
302 So a PICT can be edited at the level of the primitives, e.g. move \r
303 or thicken a line. It cannot be edited at the higher level of, say, \r
304 the bar chart data which generated the picture.\r
305 \r
306 PostScript has another limitation: Not all kinds of data amount to \r
307 marks on paper. A musical instrument description is one example. PostScript \r
308 is just not geared for such uses.\r
309 \r
310 "DIF" is another example of data being stored in a general format \r
311 usable by future programs [DIF Technical Specification]. DIF is a \r
312 format for spreadsheet data interchange. DIF and PostScript are both \r
313 expressed in plain ASCII text files. This is very handy for printing, \r
314 debugging, experimenting, and transmitting across modems. It can have \r
315 substantial cost in compaction and read/write work, depending on use. \r
316 We won't store IFF files this way but we could define an ASCII alternate \r
317 representation with a converter program.\r
318 \r
319 InterScript is Xerox' standard for interchange of editable documents \r
320 [Introduction to InterScript]. It approaches a harder problem: How \r
321 to represent editable word processor documents that may contain formatted \r
322 text, pictures, cross-references like figure numbers, and even highly \r
323 specialized objects like mathematical equations? InterScript aims \r
324 to define one standard representation for each kind of information. \r
325 Each InterScript-compatible editor is supposed to preserve the objects \r
326 it doesn't understand and even maintain nested cross-references. So \r
327 a simple word processor would let you edit the text of a fancy document \r
328 without discarding the equations or disrupting the equation numbers.\r
329 \r
330 Our task is similarly to store high level information and preserve \r
331 as much content as practical while moving it between programs. But \r
332 we need to span a larger universe of data types and cannot expect \r
333 to centrally define them all. Fortunately, we don't need to make programs \r
334 preserve information that they don't understand. And for better or \r
335 worse, we don't have to tackle general-purpose cross-references yet.\r
336 \r
337 \r
338 \f\r
339 3. Primitive Data Types\r
340 \r
341 Atomic components such as integers and characters that are interpretable \r
342 directly by the CPU are specified in one format for all processors. \r
343 We chose a format that's most convenient for the Motorola MC68000 \r
344 processor [M68000 16/32-Bit Microprocessor Programmer's Reference \r
345 Manual].\r
346 \r
347 N.B.: Part 3 dictates the format for "primitive" data types where and \r
348 only where used in the overall file structure and standard kinds of \r
349 chunks (Cf. Chunks). The number of such occurrences will be small \r
350 enough that the costs of conversion, storage, and management of processor-\r
351 specific files would far exceed the costs of conversion during I/O by "foreign" \r
352 programs. A particular data chunk may be specified with a different \r
353 format for its internal primitive types or with processor- or environment-\r
354 speci fic variants if necessary to optimize local usage. Since that hurts \r
355 data interchange, it's not recommended. (Cf. Designing New Data Sections, \r
356 in Part 4.)\r
357 \r
358 Alignment\r
359 \r
360 All data objects larger than a byte are aligned on even byte addresses \r
361 relative to the start of the file. This may require padding. Pad bytes \r
362 are to be written as zeros, but don't count on that when reading.\r
363 \r
364 This means that every odd-length "chunk" (see below) must be padded \r
365 so that the next one will fall on an even boundary. Also, designers \r
366 of structures to be stored in chunks should include pad fields where \r
367 needed to align every field larger than a byte. Zeros should be stored \r
368 in all the pad bytes.\r
369 \r
370 Justification: Even-alignment causes a little extra work for files \r
371 that are used only on certain processors but allows 68000 programs \r
372 to construct and scan the data in memory and do block I/O. You just \r
373 add an occasional pad field to data structures that you're going to \r
374 block read/write or else stream read/write an extra byte. And the \r
375 same source code works on all processors. Unspecified alignment, on \r
376 the other hand, would force 68000 programs to (dis)assemble word and \r
377 long-word data one byte at a time. Pretty cumbersome in a high level \r
378 language. And if you don't conditionally compile that out for other \r
379 processors, you won't gain anything.\r
380 \r
381 Numbers\r
382 \r
383 Numeric types supported are two's complement binary integers in the \r
384 format used by the MC68000 processor high byte first, high word first the \r
385 reverse of 8088 and 6502 format. They could potentially include signed \r
386 and unsigned 8, 16, and 32 bit integers but the standard only uses \r
387 the following:\r
388 \r
389 UBYTE    8 bits unsigned\r
390 WORD    16 bits signed\r
391 UWORD   16 bits unsigned\r
392 LONG    32 bits signed\r
393 \r
394 The actual type definitions depend on the CPU and the compiler. In \r
395 this document, we'll express data type definitions in the C programming \r
396 language. [See C, A Reference Manual.] In 68000 Lattice C:\r
397 \r
398 typedef unsigned char   UBYTE;  /*  8 bits unsigned     */\r
399 typedef short   WORD;   /* 16 bits signed       */\r
400 typedef unsigned short  UWORD;  /* 16 bits unsigned     */\r
401 typedef long    LONG;   /* 32 bits signed       */\r
402 \r
403 Characters\r
404 \r
405 The following character set is assumed wherever characters are used, \r
406 e.g. in text strings, IDs, and TEXT chunks (see below).\r
407 \r
408 Characters are encoded in 8-bit ASCII. Characters in the range NUL \r
409 (hex 0) through DEL (hex 7F) are well defined by the 7-bit ASCII standard. \r
410 IFF uses the graphic group RJS (SP, hex 20) through R~S (hex 7E).\r
411 \r
412 Most of the control character group hex 01 through hex 1F have no \r
413 standard meaning in IFF. The control character LF (hex 0A) is defined \r
414 as a "newline" character. It denotes an intentional line break, that \r
415 is, a paragraph or line terminator. (There is no way to store an automatic \r
416 line break. That is strictly a function of the margins in the environment \r
417 the text is placed.) The control character ESC (hex 1B) is a reserved \r
418 escape character under the rules of ANSI standard 3.64-1979 American \r
419 National Standard Additional Control Codes for Use with ASCII, ISO \r
420 standard 2022, and ISO/DIS standard 6429.2.\r
421 \r
422 Characters in the range hex 7F through hex FF are not globally defined \r
423 in IFF. They are best left reserved for future standardization. But \r
424 note that the FORM type FTXT (formatted text) defines the meaning \r
425 of these characters within FTXT forms. In particular, character values \r
426 hex 7F through hex 9F are control codes while characters hex A0 through \r
427 hex FF are extended graphic characters like  , as per the ISO and \r
428 ANSI standards cited above. [See the supplementary document "FTXT" \r
429 IFF Formatted Text.]\r
430 \r
431 Dates\r
432 \r
433 A "creation date" is defined as the date and time a stream of data \r
434 bytes was created. (Some systems call this a "last modified date".) \r
435 Editing some data changes its creation date. Moving the data between \r
436 volumes or machines does not.\r
437 \r
438 The IFF standard date format will be one of those used in MS-DOS, \r
439 Macintosh, or Amiga DOS (probably a 32-bit unsigned number of seconds \r
440 since a reference point). Issue: Investigate these three.\r
441 \r
442 Type IDs\r
443 \r
444 A "type ID", "property name", "FORM type", or any other IFF identifier \r
445 is a 32-bit value: the concatenation of four ASCII characters in the \r
446 range R S (SP, hex 20) through R~S (hex 7E). Spaces (hex 20) should \r
447 not precede printing characters; trailing spaces are ok. Control characters \r
448 are forbidden.\r
449 \r
450 typedef CHAR ID[4];\r
451 \r
452 IDs are compared using a simple 32-bit case-dependent equality test.\r
453 \r
454 Data section type IDs (aka FORM types) are restriced IDs. (Cf. Data \r
455 Sections.) Since they may be stored in filename extensions (Cf. Single \r
456 Purpose Files) lower case letters and punctuation marks are forbidden. \r
457 Trailing spaces are ok.\r
458 \r
459 Carefully choose those four characters when you pick a new ID. Make \r
460 them mnemonic so programmers can look at an interchange format file \r
461 and figure out what kind of data it contains. The name space makes \r
462 it possible for developers scattered around the globe to generate \r
463 ID values with minimal collisions so long as they choose specific \r
464 names like "MUS4" instead of general ones like "TYPE" and "FILE". \r
465 EA will "register" new FORM type IDs and format descriptions as they're \r
466 devised, but collisions will be improbable so there will be no pressure \r
467 on this "clearinghouse" process. Appendix A has a list of currently \r
468 defined IDs.\r
469 \r
470 Sometimes it's necessary to make data format changes that aren't backward \r
471 compatible. Since IDs are used to denote data formats in IFF, new \r
472 IDs are chosen to denote revised formats. Since programs won't read \r
473 chunks whose IDs they don't recognize (see Chunks, below), the new \r
474 IDs keep old programs from stumbling over new data. The conventional \r
475 way to chose a "revision" ID is to increment the last character if \r
476 it's a digit or else change the last character to a digit. E.g. first \r
477 and second revisions of the ID "XY" would be "XY1" and "XY2". Revisions \r
478 of "CMAP" would be "CMA1" and "CMA2".\r
479 \r
480 Chunks\r
481 \r
482 Chunks are the building blocks in the IFF structure. The form expressed \r
483 as a C typedef is:\r
484 \r
485 typedef struct {\r
486         ID      ckID;\r
487         LONG    ckSize; /* sizeof(ckData) */\r
488         UBYTE   ckData[/* ckSize */];\r
489         } Chunk;\r
490 \r
491 We can diagram an example chunk a "CMAP" chunk containing 12 data \r
492 bytes like this:\r
493                         ----------------\r
494                 ckID:   |    'CMAP'    |\r
495                 ckSize: |      12      |\r
496                 ckData: | 0, 0, 0, 32  |   -------- \r
497                         | 0, 0, 64, 0  |    12 bytes\r
498                         | 0, 0, 64, 0  |   ---------\r
499                         ----------------\r
500 \r
501 The fixed header part means "Here's a type ckID chunk with ckSize \r
502 bytes of data."\r
503 \r
504 The ckID identifies the format and purpose of the chunk. As a rule, \r
505 a program must recognize ckID to interpret ckData. It should skip \r
506 over all unrecognized chunks. The ckID also serves as a format version \r
507 number as long as we pick new IDs to identify new formats of ckData \r
508 (see above).\r
509 \r
510 The following ckIDs are universally reserved to identify chunks with \r
511 particular IFF meanings: "LIST", "FORM", "PROP", "CAT ", and "    \r
512 ". The special ID "    " (4 spaces) is a ckID for "filler" chunks, \r
513 that is, chunks that fill space but have no meaningful contents. The \r
514 IDs "LIS1" through "LIS9", "FOR1" through "FOR9", and "CAT1" through \r
515 "CAT9" are reserved for future "version number" variations. All IFF-compatible \r
516 software must account for these 23 chunk IDs. Appendix A has a list \r
517 of predefined IDs.\r
518 \r
519 The ckSize is a logical block size how many data bytes are in ckData. \r
520 If ckData is an odd number of bytes long, a 0 pad byte follows which \r
521 is not included in ckSize. (Cf. Alignment.) A chunk's total physical \r
522 size is ckSize rounded up to an even number plus the size of the header. \r
523 So the smallest chunk is 8 bytes long with ckSize = 0. For the sake \r
524 of following chunks, programs must respect every chunk's ckSize as \r
525 a virtual end-of-file for reading its ckData even if that data is \r
526 malformed, e.g. if nested contents are truncated.\r
527 \r
528 We can describe the syntax of a chunk as a regular expression with \r
529 "#" representing the ckSize, i.e. the length of the following {braced} \r
530 bytes. The "[0]" represents a sometimes needed pad byte. (The regular \r
531 expressions in this document are collected in Appendix A along with \r
532 an explanation of notation.)\r
533 \r
534 Chunk   ::= ID #{ UBYTE* } [0]\r
535 \r
536 One chunk output technique is to stream write a chunk header, stream \r
537 write the chunk contents, then random access back to the header to \r
538 fill in the size. Another technique is to make a preliminary pass \r
539 over the data to compute the size, then write it out all at once.\r
540 \r
541 Strings, String Chunks, and String Properties\r
542 \r
543 In a string of ASCII text, LF denotes a forced line break (paragraph \r
544 or line terminator). Other control characters are not used. (Cf. Characters.)\r
545 \r
546 The ckID for a chunk that contains a string of plain, unformatted \r
547 text is "TEXT". As a practical matter, a text string should probably \r
548 not be longer than 32767 bytes. The standard allows up to 231 - 1 \r
549 bytes.\r
550 \r
551 When used as a data property (see below), a text string chunk may \r
552 be 0 to 255 characters long. Such a string is readily converted to \r
553 a C string or a Pascal STRING[255]. The ckID of a property must be \r
554 the property name, not "TEXT".\r
555 \r
556 When used as a part of a chunk or data property, restricted C string \r
557 format is normally used. That means 0 to 255 characters followed by \r
558 a NUL byte (ASCII value 0).\r
559 \r
560 Data Properties\r
561 \r
562 Data properties specify attributes for following (non-property) chunks. \r
563 A data property essentially says "identifier = value", for example \r
564 "XY = (10, 200)", telling something about following chunks. Properties \r
565 may only appear inside data sections ("FORM" chunks, cf. Data Sections) \r
566 and property sections ("PROP" chunks, cf. Group PROP).\r
567 \r
568 The form of a data property is a special case of Chunk. The ckID is \r
569 a property name as well as a property type. The ckSize should be small \r
570 since data properties are intended to be accumulated in RAM when reading \r
571 a file. (256 bytes is a reasonable upper bound.) Syntactically:\r
572 \r
573 Property::= Chunk\r
574 \r
575 When designing a data object, use properties to describe context information \r
576 like the size of an image, even if they don't vary in your program. \r
577 Other programs will need this information.\r
578 \r
579 Think of property settings as assignments to variables in a programming \r
580 language. Multiple assignments are redundant and local assignments \r
581 temporarily override global assignments. The order of assignments \r
582 doesn't matter as long as they precede the affected chunks. (Cf. LISTs, \r
583 CATs, and Shared Properties.)\r
584 \r
585 Each object type (FORM type) is a local name space for property IDs. \r
586 Think of a "CMAP" property in a "FORM ILBM" as the qualified ID "ILBM.CMAP". \r
587 Property IDs specified when an object type is designed (and therefore \r
588 known to all clients) are called "standard" while specialized ones \r
589 added later are "nonstandard".\r
590 \r
591 Links\r
592 \r
593 Issue: A standard mechanism for "links" or "cross references" is very \r
594 desirable for things like combining images and sounds into animations. \r
595 Perhaps we'll define "link" chunks within FORMs that refer to other \r
596 FORMs or to specific chunks within the same and other FORMs. This \r
597 needs further work. EA IFF 1985 has no standard link mechanism.\r
598 \r
599 For now, it may suffice to read a list of, say, musical instruments, \r
600 and then just refer to them within a musical score by index number.\r
601 \r
602 File References\r
603 \r
604 Issue: We may need a standard form for references to other files. \r
605 A "file ref" could name a directory and a file in the same type of \r
606 operating system as the ref's originator. Following the reference \r
607 would expect the file to be on some mounted volume. In a network environment, \r
608 a file ref could name a server, too.\r
609 \r
610 Issue: How can we express operating-system independent file refs?\r
611 \r
612 Issue: What about a means to reference a portion of another file? \r
613 Would this be a "file ref" plus a reference to a "link" within the \r
614 target file?\r
615 \r
616 \r
617 \f\r
618 4. Data Sections\r
619 \r
620 The first thing we need of a file is to check: Does it contain IFF \r
621 data and, if so, does it contain the kind of data we're looking for? \r
622 So we come to the notion of a "data section".\r
623 \r
624 A "data section" or IFF "FORM" is one self-contained "data object" \r
625 that might be stored in a file by itself. It is one high level data \r
626 object such as a picture or a sound effect. The IFF structure "FORM" \r
627 makes it self- identifying. It could be a composite object like a \r
628 musical score with nested musical instrument descriptions.\r
629 \r
630 Group FORM\r
631 \r
632 A data section is a chunk with ckID "FORM" and this arrangement:\r
633 \r
634 FORM    ::= "FORM" #{ FormType (LocalChunk | FORM | LIST | CAT)* \r
635 }\r
636 FormType::= ID\r
637 LocalChunk      ::= Property | Chunk\r
638 \r
639 The ID "FORM" is a syntactic keyword like "struct" in C. Think of \r
640 a "struct ILBM" containing a field "CMAP". If you see "FORM" you'll \r
641 know to expect a FORM type ID (the structure name, "ILBM" in this \r
642 example) and a particular contents arrangement or "syntax" (local \r
643 chunks, FORMs, LISTs, and CATs). (LISTs and CATs are discussed in \r
644 part 5, below.) A "FORM ILBM", in particular, might contain a local \r
645 chunk "CMAP", an "ILBM.CMAP" (to use a qualified name).\r
646 \r
647 So the chunk ID "FORM" indicates a data section. It implies that the \r
648 chunk contains an ID and some number of nested chunks. In reading \r
649 a FORM, like any other chunk, programs must respect its ckSize as \r
650 a virtual end-of-file for reading its contents, even if they're truncated.\r
651 \r
652 The FormType (or FORM type) is a restricted ID that may not contain \r
653 lower case letters or punctuation characters. (Cf. Type IDs. Cf. Single \r
654 Purpose Files.)\r
655 \r
656 The type-specific information in a FORM is composed of its "local \r
657 chunks": data properties and other chunks. Each FORM type is a local \r
658 name space for local chunk IDs. So "CMAP" local chunks in other FORM \r
659 types may be unrelated to "ILBM.CMAP". More than that, each FORM type \r
660 defines semantic scope. If you know what a FORM ILBM is, you'll know \r
661 what an ILBM.CMAP is.\r
662 \r
663 Local chunks defined when the FORM type is designed (and therefore \r
664 known to all clients of this type) are called "standard" while specialized \r
665 ones added later are "nonstandard".\r
666 \r
667 Among the local chunks, property chunks give settings for various \r
668 details like text font while the other chunks supply the essential \r
669 information. This distinction is not clear cut. A property setting \r
670 cancelled by a later setting of the same property has effect only \r
671 on data chunks in between. E.g. in the sequence:\r
672 \r
673 prop1 = x  (propN = value)*  prop1 = y\r
674 \r
675 where the propNs are not prop1, the setting prop1 = x has no effect.\r
676 \r
677 The following universal chunk IDs are reserved inside any FORM: "LIST", \r
678 "FORM", "PROP", "CAT ", "JJJJ", "LIS1" through "LIS9", "FOR1" through \r
679 "FOR9", and "CAT1" through "CAT9". (Cf. Chunks. Cf. Group LIST. Cf. \r
680 Group PROP.) For clarity, these universal chunk names may not be FORM \r
681 type IDs, either.\r
682 \r
683 Part 5, below, talks about grouping FORMs into LISTs and CATs. They \r
684 let you group a bunch of FORMs but don't impose any particular meaning \r
685 or constraints on the grouping. Read on.\r
686 \r
687 Composite FORMs\r
688 \r
689 A FORM chunk inside a FORM is a full-fledged data section. This means \r
690 you can build a composite object like a multi-frame animation sequence \r
691 from available picture FORMs and sound effect FORMs. You can insert \r
692 additional chunks with information like frame rate and frame count.\r
693 \r
694 Using composite FORMs, you leverage on existing programs that create \r
695 and edit the component FORMs. Those editors may even look into your \r
696 composite object to copy out its type of component, although it'll \r
697 be the rare program that's fancy enough to do that. Such editors are \r
698 not allowed to replace their component objects within your composite \r
699 object. That's because the IFF standard lets you specify consistency \r
700 requirements for the composite FORM such as maintaining a count or \r
701 a directory of the components. Only programs that are written to uphold \r
702 the rules of your FORM type should create or modify such FORMs.\r
703 \r
704 Therefore, in designing a program that creates composite objects, \r
705 you are strongly requested to provide a facility for your users to \r
706 import and export the nested FORMs. Import and export could move the \r
707 data through a clipboard or a file.\r
708 \r
709 Here are several existing FORM types and rules for defining new ones.\r
710 \r
711 FTXT\r
712 \r
713 An FTXT data section contains text with character formatting information \r
714 like fonts and faces. It has no paragraph or document formatting information \r
715 like margins and page headers. FORM FTXT is well matched to the text \r
716 representation in Amiga's Intuition environment. See the supplemental \r
717 document "FTXT" IFF Formatted Text.\r
718 \r
719 ILBM\r
720 \r
721 "ILBM" is an InterLeaved BitMap image with color map; a machine-independent \r
722 format for raster images. FORM ILBM is the standard image file format \r
723 for the Commodore-Amiga computer and is useful in other environments, \r
724 too. See the supplemental document "ILBM" IFF Interleaved Bitmap.\r
725 \r
726 PICS\r
727 \r
728 The data chunk inside a "PICS" data section has ID "PICT" and holds \r
729 a QuickDraw picture. Issue: Allow more than one PICT in a PICS? See \r
730 Inside Macintosh chapter "QuickDraw" for details on PICTs and how \r
731 to create and display them on the Macintosh computer.\r
732 \r
733 The only standard property for PICS is "XY", an optional property \r
734 that indicates the position of the PICT relative to "the big picture". \r
735 The contents of an XY is a QuickDraw Point.\r
736 \r
737 Note: PICT may be limited to Macintosh use, in which case there'll \r
738 be another format for structured graphics in other environments.\r
739 \r
740 Other Macintosh Resource Types\r
741 \r
742 Some other Macintosh resource types could be adopted for use within \r
743 IFF files; perhaps MWRT, ICN, ICN#, and STR#.\r
744 \r
745 Issue: Consider the candidates and reserve some more IDs.\r
746 \r
747 Designing New Data Sections\r
748 \r
749 Supplemental documents will define additional object types. A supplement \r
750 needs to specify the object's purpose, its FORM type ID, the IDs and \r
751 formats of standard local chunks, and rules for generating and interpreting \r
752 the data. It's a good idea to supply typedefs and an example source \r
753 program that accesses the new object. See "ILBM" IFF Interleaved Bitmap \r
754 for a good example.\r
755 \r
756 Anyone can pick a new FORM type ID but should reserve it with Electronic \r
757 Arts at their earliest convenience. [Issue: EA contact person? Hand \r
758 this off to another organization?] While decentralized format definitions \r
759 and extensions are possible in IFF, our preference is to get design \r
760 consensus by committee, implement a program to read and write it, \r
761 perhaps tune the format, and then publish the format with example \r
762 code. Some organization should remain in charge of answering questions \r
763 and coordinating extensions to the format.\r
764 \r
765 If it becomes necessary to revise the design of some data section, \r
766 its FORM type ID will serve as a version number (Cf. Type IDs). E.g. \r
767 a revised "VDEO" data section could be called "VDE1". But try to get \r
768 by with compatible revisions within the existing FORM type.\r
769 \r
770 In a new FORM type, the rules for primitive data types and word-alignment \r
771 (Cf. Primitive Data Types) may be overriden for the contents of its \r
772 local chunks but not for the chunk structure itself if your documentation \r
773 spells out the deviations. If machine-specific type variants are needed, \r
774 e.g. to store vast numbers of integers in reverse bit order, then \r
775 outline the conversion algorithm and indicate the variant inside each \r
776 file, perhaps via different FORM types. Needless to say, variations \r
777 should be minimized.\r
778 \r
779 In designing a FORM type, encapsulate all the data that other programs \r
780 will need to interpret your files. E.g. a raster graphics image should \r
781 specify the image size even if your program always uses 320 x 200 \r
782 pixels x 3 bitplanes. Receiving programs are then empowered to append \r
783 or clip the image rectangle, to add or drop bitplanes, etc. This enables \r
784 a lot more compatibility.\r
785 \r
786 Separate the central data (like musical notes) from more specialized \r
787 information (like note beams) so simpler programs can extract the \r
788 central parts during read-in. Leave room for expansion so other programs \r
789 can squeeze in new kinds of information (like lyrics). And remember \r
790 to keep the property chunks manageably short let's say 2 256 bytes.\r
791 \r
792 When designing a data object, try to strike a good tradeoff between \r
793 a super-general format and a highly-specialized one. Fit the details \r
794 to at least one particular need, for example a raster image might \r
795 as well store pixels in the current machine's scan order. But add \r
796 the kind of generality that makes it usable with foreseeable hardware \r
797 and software. E.g. use a whole byte for each red, green, and blue \r
798 color value even if this year's computer has only 4-bit video DACs. \r
799 Think ahead and help other programs so long as the overhead is acceptable. \r
800 E.g. run compress a raster by scan line rather than as a unit so future \r
801 programs can swap images by scan line to and from secondary storage.\r
802 \r
803 Try to design a general purpose "least common multiple" format that \r
804 encompasses the needs of many programs without getting too complicated. \r
805 Let's coalesce our uses around a few such formats widely separated \r
806 in the vast design space. Two factors make this flexibility and simplicity \r
807 practical. First, file storage space is getting very plentiful, so \r
808 compaction is not a priority. Second, nearly any locally-performed \r
809 data conversion work during file reading and writing will be cheap \r
810 compared to the I/O time.\r
811 \r
812 It must be ok to copy a LIST or FORM or CAT intact, e.g. to incorporate \r
813 it into a composite FORM. So any kind of internal references within \r
814 a FORM must be relative references. They could be relative to the \r
815 start of the containing FORM, relative from the referencing chunk, \r
816 or a sequence number into a collection.\r
817 \r
818 With composite FORMs, you leverage on existing programs that create \r
819 and edit the components. If you write a program that creates composite \r
820 objects, please provide a facility for your users to import and export \r
821 the nested FORMs. The import and export functions may move data through \r
822 a separate file or a clipboard.\r
823 \r
824 Finally, don't forget to specify all implied rules in detail.\r
825 \r
826 \r
827 \f\r
828 5. LISTs, CATs, and Shared Properties\r
829 \r
830 Data often needs to be grouped together like a list of icons. Sometimes \r
831 a trick like arranging little images into a big raster works, but \r
832 generally they'll need to be structured as a first class group. The \r
833 objects "LIST" and "CAT" are IFF-universal mechanisms for this purpose.\r
834 \r
835 Property settings sometimes need to be shared over a list of similar \r
836 objects. E.g. a list of icons may share one color map. LIST provides \r
837 a means called "PROP" to do this. One purpose of a LIST is to define \r
838 the scope of a PROP. A "CAT", on the other hand, is simply a concatenation \r
839 of objects.\r
840 \r
841 Simpler programs may skip LISTs and PROPs altogether and just handle \r
842 FORMs and CATs. All "fully-conforming" IFF programs also know about \r
843 "CAT ", "LIST", and "PROP". Any program that reads a FORM inside a \r
844 LIST must process shared PROPs to correctly interpret that FORM.\r
845 \r
846 Group CAT\r
847 \r
848 A CAT is just an untyped group of data objects.\r
849 \r
850 Structurally, a CAT is a chunk with chunk ID "CAT " containing a "contents \r
851 type" ID followed by the nested objects. The ckSize of each contained \r
852 chunk is essentially a relative pointer to the next one.\r
853 \r
854 CAT     ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }\r
855 ContentsType    ::= ID  -- a hint or an "abstract data type" ID\r
856 \r
857 In reading a CAT, like any other chunk, programs must respect it's \r
858 ckSize as a virtual end-of-file for reading the nested objects even \r
859 if they're malformed or truncated.\r
860 \r
861 The "contents type" following the CAT's ckSize indicates what kind \r
862 of FORMs are inside. So a CAT of ILBMs would store "ILBM" there. It's \r
863 just a hint. It may be used to store an "abstract data type". A CAT \r
864 could just have blank contents ID ("JJJJ") if it contains more than \r
865 one kind of FORM.\r
866 \r
867 CAT defines only the format of the group. The group's meaning is open \r
868 to interpretation. This is like a list in LISP: the structure of cells \r
869 is predefined but the meaning of the contents as, say, an association \r
870 list depends on use. If you need a group with an enforced meaning \r
871 (an "abstract data type" or Smalltalk "subclass"), some consistency \r
872 constraints, or additional data chunks, use a composite FORM instead \r
873 (Cf. Composite FORMs).\r
874 \r
875 Since a CAT just means a concatenation of objects, CATs are rarely \r
876 nested. Programs should really merge CATs rather than nest them.\r
877 \r
878 Group LIST\r
879 \r
880 A LIST defines a group very much like CAT but it also gives a scope \r
881 for PROPs (see below). And unlike CATs, LISTs should not be merged \r
882 without understanding their contents.\r
883 \r
884 Structurally, a LIST is a chunk with ckID "LIST" containing a "contents \r
885 type" ID, optional shared properties, and the nested contents (FORMs, \r
886 LISTs, and CATs), in that order. The ckSize of each contained chunk \r
887 is a relative pointer to the next one. A LIST is not an arbitrary \r
888 linked list the cells are simply concatenated.\r
889 \r
890 LIST    ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }\r
891 ContentsType    ::= ID\r
892 \r
893 Group PROP\r
894 \r
895 PROP chunks may appear in LISTs (not in FORMs or CATs). They supply \r
896 shared properties for the FORMs in that LIST. This ability to elevate \r
897 some property settings to shared status for a list of forms is useful \r
898 for both indirection and compaction. E.g. a list of images with the \r
899 same size and colors can share one "size" property and one "color \r
900 map" property. Individual FORMs can override the shared settings.\r
901 \r
902 The contents of a PROP is like a FORM with no data chunks:\r
903 \r
904 PROP    ::= "PROP" #{ FormType Property* }\r
905 \r
906 It means, "Here are the shared properties for FORM type <<FormType>."\r
907 \r
908 A LIST may have at most one PROP of a FORM type, and all the PROPs \r
909 must appear before any of the FORMs or nested LISTs and CATs. You \r
910 can have subsequences of FORMs sharing properties by making each subsequence \r
911 a LIST.\r
912 \r
913 Scoping: Think of property settings as variable bindings in nested \r
914 blocks of a programming language. Where in C you could write:\r
915 \r
916 TEXT_FONT text_font = Courier;  /* program's global default     */\r
917 \r
918 File(); {\r
919         TEXT_FONT text_font = TimesRoman;       /* shared setting       */\r
920 \r
921                 {\r
922                 TEXT_FONT text_font = Helvetica;  /* local setting      */\r
923                 Print("Hello ");/* uses font Helvetica  */\r
924                 }\r
925 \r
926                 {\r
927                 Print("there.");/* uses font TimesRoman */\r
928                 }\r
929         }\r
930 \r
931 An IFF file could contain:\r
932 \r
933 LIST {\r
934         PROP TEXT {\r
935                 FONT {TimesRoman}       /* shared setting       */\r
936                 }\r
937 \r
938         FORM TEXT {\r
939                 FONT {Helvetica}/* local setting*/\r
940                 CHRS {Hello }           /* uses font Helvetica  */\r
941                 }\r
942 \r
943         FORM TEXT {\r
944                 CHRS {there.}   /* uses font TimesRoman */\r
945                 }\r
946         }\r
947 \r
948 The shared property assignments selectively override the reader's \r
949 global defaults, but only for FORMs within the group. A FORM's own \r
950 property assignments selectively override the global and group-supplied \r
951 values. So when reading an IFF file, keep property settings on a stack. \r
952 They're designed to be small enough to hold in main memory.\r
953 \r
954 Shared properties are semantically equivalent to copying those properties \r
955 into each of the nested FORMs right after their FORM type IDs.\r
956 \r
957 Properties for LIST\r
958 \r
959 Optional "properties for LIST" store the origin of the list's contents \r
960 in a PROP chunk for the fake FORM type "LIST". They are the properties \r
961 originating program "OPGM", processor family "OCPU", computer type \r
962 "OCMP", computer serial number or network address "OSN ", and user \r
963 name "UNAM". In our imperfect world, these could be called upon to \r
964 distinguish between unintended variations of a data format or to work \r
965 around bugs in particular originating/receiving program pairs. Issue: \r
966 Specify the format of these properties.\r
967 \r
968 A creation date could also be stored in a property but let's ask that \r
969 file creating, editing, and transporting programs maintain the correct \r
970 date in the local file system. Programs that move files between machine \r
971 types are expected to copy across the creation dates.\r
972 \r
973 \r
974 \f\r
975 6. Standard File Structure\r
976 \r
977 File Structure Overview\r
978 \r
979 An IFF file is just a single chunk of type FORM, LIST, or CAT. Therefore \r
980 an IFF file can be recognized by its first 4 bytes: "FORM", "LIST", \r
981 or "CAT ". Any file contents after the chunk's end are to be ignored.\r
982 \r
983 Since an IFF file can be a group of objects, programs that read/write \r
984 single objects can communicate to an extent with programs that read/write \r
985 groups. You're encouraged to write programs that handle all the objects \r
986 in a LIST or CAT. A graphics editor, for example, could process a \r
987 list of pictures as a multiple page document, one page at a time.\r
988 \r
989 Programs should enforce IFF's syntactic rules when reading and writing \r
990 files. This ensures robust data transfer. The public domain IFF reader/writer \r
991 subroutine package does this for you. A utility program "IFFCheck" \r
992 is available that scans an IFF file and checks it for conformance \r
993 to IFF's syntactic rules. IFFCheck also prints an outline of the chunks \r
994 in the file, showing the ckID and ckSize of each. This is quite handy \r
995 when building IFF programs. Example programs are also available to \r
996 show details of reading and writing IFF files.\r
997 \r
998 A merge program "IFFJoin" will be available that logically appends \r
999 IFF files into a single CAT group. It "unwraps" each input file that \r
1000 is a CAT so that the combined file isn't nested CATs.\r
1001 \r
1002 If we need to revise the IFF standard, the three anchoring IDs will \r
1003 be used as "version numbers". That's why IDs "FOR1" through "FOR9", \r
1004 "LIS1" through "LIS9", and "CAT1" through "CAT9" are reserved.\r
1005 \r
1006 IFF formats are designed for reasonable performance with floppy disks. \r
1007 We achieve considerable simplicity in the formats and programs by \r
1008 relying on the host file system rather than defining universal grouping \r
1009 structures like directories for LIST contents. On huge storage systems, \r
1010 IFF files could be leaf nodes in a file structure like a B-tree. Let's \r
1011 hope the host file system implements that for us!\r
1012 \r
1013 Thre are two kinds of IFF files: single purpose files and scrap files. \r
1014 They differ in the interpretation of multiple data objects and in \r
1015 the file's external type.\r
1016 \r
1017 Single Purpose Files\r
1018 \r
1019 A single purpose IFF file is for normal "document" and "archive" storage. \r
1020 This is in contrast with "scrap files" (see below) and temporary backing \r
1021 storage (non-interchange files).\r
1022 \r
1023 The external file type (or filename extension, depending on the host \r
1024 file system) indicates the file's contents. It's generally the FORM \r
1025 type of the data contained, hence the restrictions on FORM type IDs.\r
1026 \r
1027 Programmers and users may pick an "intended use" type as the filename \r
1028 extension to make it easy to filter for the relevant files in a filename \r
1029 requestor. This is actually a "subclass" or "subtype" that conveniently \r
1030 separates files of the same FORM type that have different uses. Programs \r
1031 cannot demand conformity to its expected subtypes without overly restricting \r
1032 data interchange since they cannot know about the subtypes to be used \r
1033 by future programs that users will want to exchange data with.\r
1034 \r
1035 Issue: How to generate 3-letter MS-DOS extensions from 4-letter FORM \r
1036 type IDs?\r
1037 \r
1038 Most single purpose files will be a single FORM (perhaps a composite \r
1039 FORM like a musical score containing nested FORMs like musical instrument \r
1040 descriptions). If it's a LIST or a CAT, programs should skip over \r
1041 unrecognized objects to read the recognized ones or the first recognized \r
1042 one. Then a program that can read a single purpose file can read something \r
1043 out of a "scrap file", too.\r
1044 \r
1045 Scrap Files\r
1046 \r
1047 A "scrap file" is for maximum interconnectivity in getting data between \r
1048 programs; the core of a clipboard function. Scrap files may have type \r
1049 "IFF " or filename extension ".IFF".\r
1050 \r
1051 A scrap file is typically a CAT containing alternate representations \r
1052 of the same basic information. Include as many alternatives as you \r
1053 can readily generate. This redundancy improves interconnectivity in \r
1054 situations where we can't make all programs read and write super-general \r
1055 formats. [Inside Macintosh chapter "Scrap Manager".] E.g. a graphically-\r
1056 annotated musical score might be supplemented by a stripped down 4-voice \r
1057 melody and by a text (the lyrics).\r
1058 \r
1059 The originating program should write the alternate representations \r
1060 in order of "preference": most preferred (most comprehensive) type \r
1061 to least preferred (least comprehensive) type. A receiving program \r
1062 should either use the first appearing type that it understands or \r
1063 search for its own "preferred" type.\r
1064 \r
1065 A scrap file should have at most one alternative of any type. (A LIST \r
1066 of same type objects is ok as one of the alternatives.) But don't \r
1067 count on this when reading; ignore extra sections of a type. Then \r
1068 a program that reads scrap files can read something out of single \r
1069 purpose files.\r
1070 \r
1071 Rules for Reader Programs\r
1072 \r
1073 Here are some notes on building programs that read IFF files. If you \r
1074 use the standard IFF reader module "IFFR.C", many of these rules and \r
1075 details will be automatically handled. (See "Support Software" in \r
1076 Appendix A.) We recommend that you start from the example program \r
1077 "ShowILBM.C". You should also read up on recursive descent parsers. \r
1078 [See, for example, Compiler Construction, An Advanced Course.]\r
1079 \r
1080 %       The standard is very flexible so many programs can exchange \r
1081 data. This implies a program has to scan the file and react to what's \r
1082 actually there in whatever order it appears. An IFF reader program \r
1083 is a parser.\r
1084 \r
1085 %       For interchange to really work, programs must be willing to \r
1086 do some conversion during read-in. If the data isn't exactly what \r
1087 you expect, say, the raster is smaller than those created by your \r
1088 program, then adjust it. Similarly, your program could crop a large \r
1089 picture, add or drop bitplanes, and create/discard a mask plane. The \r
1090 program should give up gracefully on data that it can't convert.\r
1091 \r
1092 %       If it doesn't start with "FORM", "LIST", or "CAT ", it's not \r
1093 an IFF-85 file.\r
1094 \r
1095 %       For any chunk you encounter, you must recognize its type ID \r
1096 to understand its contents.\r
1097 \r
1098 %       For any FORM chunk you encounter, you must recognize its FORM \r
1099 type ID to understand the contained "local chunks". Even if you don't \r
1100 recognize the FORM type, you can still scan it for nested FORMs, LISTs, \r
1101 and CATs of interest.\r
1102 \r
1103 %       Don't forget to skip the pad byte after every odd-length chunk.\r
1104 \r
1105 %       Chunk types LIST, FORM, PROP, and CAT are generic groups. They \r
1106 always contain a subtype ID followed by chunks.\r
1107 \r
1108 %       Readers ought to handle a CAT of FORMs in a file. You may treat \r
1109 the FORMs like document pages to sequence through or just use the \r
1110 first FORM.\r
1111 \r
1112 %       Simpler IFF readers completely skip LISTs. "Fully IFF-conforming" \r
1113 readers are those that handle LISTs, even if just to read the first \r
1114 FORM from a file. If you do look into a LIST, you must process shared \r
1115 properties (in PROP chunks) properly. The idea is to get the correct \r
1116 data or none at all.\r
1117 \r
1118 %       The nicest readers are willing to look into unrecognized FORMs \r
1119 for nested FORM types that they do recognize. For example, a musical \r
1120 score may contain nested instrument descriptions and an animation \r
1121 file may contain still pictures.\r
1122 \r
1123 Note to programmers: Processing PROP chunks is not simple! You'll \r
1124 need some background in interpreters with stack frames. If this is \r
1125 foreign to you, build programs that read/write only one FORM per file. \r
1126 For the more intrepid programmers, the next paragraph summarizes how \r
1127 to process LISTs and PROPs. See the general IFF reader module "IFFR.C" \r
1128 and the example program "ShowILBM.C" for details.\r
1129 \r
1130 Allocate a stack frame for every LIST and FORM you encounter and initialize \r
1131 it by copying the stack frame of the parent LIST or FORM. At the top \r
1132 level, you'll need a stack frame initialized to your program's global \r
1133 defaults. While reading each LIST or FORM, store all encountered properties \r
1134 into the current stack frame. In the example ShowILBM, each stack \r
1135 frame has a place for a bitmap header property ILBM.BMHD and a color \r
1136 map property ILBM.CMAP. When you finally get to the ILBM's BODY chunk, \r
1137 use the property settings accumulated in the current stack frame.\r
1138 \r
1139 An alternate implementation would just remember PROPs encountered, \r
1140 forgetting each on reaching the end of its scope (the end of the containing \r
1141 LIST). When a FORM XXXX is encountered, scan the chunks in all remembered \r
1142 PROPs XXXX, in order, as if they appeared before the chunks actually \r
1143 in the FORM XXXX. This gets trickier if you read FORMs inside of FORMs.\r
1144 \r
1145 Rules for Writer Programs\r
1146 \r
1147 Here are some notes on building programs that write IFF files, which \r
1148 is much easier than reading them. If you use the standard IFF writer \r
1149 module "IFFW.C" (see "Support Software" in Appendix A), many of these \r
1150 rules and details will automatically be enforced. See the example \r
1151 program "Raw2ILBM.C".\r
1152 \r
1153 %       An IFF file is a single FORM, LIST, or CAT chunk.\r
1154 \r
1155 %       Any IFF-85 file must start with the 4 characters "FORM", "LIST", \r
1156 or "CAT ", followed by a LONG ckSize. There should be no data after \r
1157 the chunk end.\r
1158 \r
1159 %       Chunk types LIST, FORM, PROP, and CAT are generic. They always \r
1160 contain a subtype ID followed by chunks. These three IDs are universally \r
1161 reserved, as are "LIS1" through "LIS9", "FOR1" through "FOR9", "CAT1" \r
1162 through "CAT9", and "    ".\r
1163 \r
1164 %       Don't forget to write a 0 pad byte after each odd-length chunk.\r
1165 \r
1166 %       Four techniques for writing an IFF group: (1) build the data \r
1167 in a file mapped into virtual memory, (2) build the data in memory \r
1168 blocks and use block I/O, (3) stream write the data piecemeal and \r
1169 (don't forget!) random access back to set the group length count, \r
1170 and (4) make a preliminary pass to compute the length count then stream \r
1171 write the data.\r
1172 \r
1173 %       Do not try to edit a file that you don't know how to create. \r
1174 Programs may look into a file and copy out nested FORMs of types that \r
1175 they recognize, but don't edit and replace the nested FORMs and don't \r
1176 add or remove them. That could make the containing structure inconsistent. \r
1177 You may write a new file containing items you copied (or copied and \r
1178 modified) from another IFF file, but don't copy structural parts you \r
1179 don't understand.\r
1180 \r
1181 %       You must adhere to the syntax descriptions in Appendex A. E.g. \r
1182 PROPs may only appear inside LISTs.\r
1183 \r
1184 \r
1185 \r
1186 \f\r
1187 Appendix A. Reference\r
1188 \r
1189 Type Definitions\r
1190 \r
1191 The following C typedefs describe standard IFF structures. Declarations \r
1192 to use in practice will vary with the CPU and compiler. For example, \r
1193 68000 Lattice C produces efficient comparison code if we define ID \r
1194 as a "LONG". A macro "MakeID" builds these IDs at compile time.\r
1195 \r
1196 /* Standard IFF types, expressed in 68000 Lattice C.    */\r
1197 \r
1198 typedef unsigned char UBYTE;    /*  8 bits unsigned     */\r
1199 typedef short WORD;     /* 16 bits signed       */\r
1200 typedef unsigned short UWORD;   /* 16 bits unsigned     */\r
1201 typedef long LONG;      /* 32 bits signed       */\r
1202 \r
1203 typedef char ID[4];     /* 4 chars in ' ' through '~'   */\r
1204 \r
1205 typedef struct {\r
1206         ID      ckID;\r
1207         LONG    ckSize; /* sizeof(ckData)       */\r
1208         UBYTE   ckData[/* ckSize */];\r
1209         } Chunk;\r
1210 \r
1211 /* ID typedef and builder for 68000 Lattice C. */\r
1212 typedef LONG ID;        /* 4 chars in ' ' through '~'   */\r
1213 #define MakeID(a,b,c,d) ( (a)<<<<24 | (b)<<<<16 | (c)<<<<8 | (d) )\r
1214 \r
1215 /* Globally reserved IDs. */\r
1216 #define ID_FORM   MakeID('F','O','R','M')\r
1217 #define ID_LIST   MakeID('L','I','S','T')\r
1218 #define ID_PROP   MakeID('P','R','O','P')\r
1219 #define ID_CAT    MakeID('C','A','T',' ')\r
1220 #define ID_FILLER MakeID(' ',' ',' ',' ')\r
1221 \r
1222 Syntax Definitions\r
1223 \r
1224 Here's a collection of the syntax definitions in this document.\r
1225 \r
1226 Chunk   ::= ID #{ UBYTE* } [0]\r
1227 \r
1228 Property::= Chunk\r
1229 \r
1230 FORM    ::= "FORM" #{ FormType (LocalChunk | FORM | LIST | CAT)* \r
1231 }\r
1232 FormType::= ID\r
1233 LocalChunk      ::= Property | Chunk\r
1234 \r
1235 CAT     ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }\r
1236 ContentsType    ::= ID  -- a hint or an "abstract data type" ID\r
1237 \r
1238 LIST    ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }\r
1239 PROP    ::= "PROP" #{ FormType Property* }\r
1240 \r
1241 In this extended regular expression notation, the token "#" represents \r
1242 a ckSize LONG count of the following {braced} data bytes. Literal \r
1243 items are shown in "quotes", [square bracketed items] are optional, \r
1244 and "*" means 0 or more instances. A sometimes-needed pad byte is \r
1245 shown as "[0]".\r
1246 \r
1247 Defined Chunk IDs\r
1248 \r
1249 This is a table of currently defined chunk IDs. We may also borrow \r
1250 some Macintosh IDs and data formats.\r
1251 \r
1252 Group chunk IDs\r
1253         FORM, LIST, PROP, CAT.\r
1254 Future revision group chunk IDs\r
1255         FOR1 I FOR9, LIS1 I LIS9, CAT1 I CAT9.\r
1256 FORM type IDs\r
1257         (The above group chunk IDs may not be used for FORM type IDs.)\r
1258         (Lower case letters and punctuation marks are forbidden in FORM \r
1259 type IDs.)\r
1260         8SVX 8-bit sampled sound voice, ANBM animated bitmap, FNTR raster \r
1261 font, FNTV vector font, FTXT formatted text, GSCR general-use musical \r
1262 score, ILBM interleaved raster bitmap image, PDEF Deluxe Print page \r
1263 definition, PICS Macintosh picture, PLBM (obsolete), USCR Uhuru Sound \r
1264 Software musical score, UVOX Uhuru Sound Software Macintosh voice, \r
1265 SMUS simple musical score, VDEO Deluxe Video Construction Set video.\r
1266 Data chunk IDs\r
1267         "JJJJ", TEXT, PICT.\r
1268 PROP LIST property IDs\r
1269         OPGM, OCPU, OCMP, OSN, UNAM.\r
1270 \r
1271 \r
1272 \f\r
1273 Support Software\r
1274 \r
1275 These public domain C source programs are available for use in building \r
1276 IFF-compatible programs:\r
1277 \r
1278 IFF.H, IFFR.C, IFFW.C   \r
1279 \r
1280                 IFF reader and writer package. \r
1281                 These modules handle many of the details of reliably \r
1282                 reading and writing IFF files.\r
1283 \r
1284 IFFCheck.C      This handy utility program scans an IFF file, checks \r
1285                 that the contents are well formed, and prints an outline \r
1286                 of the chunks.\r
1287 \r
1288 PACKER.H, Packer.C, UnPacker.C  \r
1289 \r
1290                 Run encoder and decoder used for ILBM files.\r
1291 \r
1292 ILBM.H, ILBMR.C, ILBMW.C\r
1293 \r
1294                 Reader and writer support routines for raster image \r
1295                 FORM ILBM. ILBMR calls IFFR and UnPacker. ILBMW calls \r
1296                 IFFW and Packer.\r
1297 \r
1298 ShowILBM.C      \r
1299                 Example caller of IFFR and ILBMR modules. This \r
1300                 Commodore-Amiga program reads and displays a FORM ILBM.\r
1301 Raw2ILBM.C      \r
1302                 Example ILBM writer program. As a demonstration, it \r
1303                 reads a raw raster image file and writes the image \r
1304                 as a FORM ILBM file.\r
1305 ILBM2Raw.C      \r
1306                 Example ILBM reader program.  Reads a FORM ILBM file\r
1307                 and writes it into a raw raster image.\r
1308 \r
1309 REMALLOC.H, Remalloc.c\r
1310 \r
1311                 Memory allocation routines used in these examples.\r
1312 \r
1313 INTUALL.H       generic "include almost everything" include-file\r
1314                 with the sequence of includes correctly specified.\r
1315 \r
1316 READPICT.H, ReadPict.c  \r
1317 \r
1318                 given an ILBM file, read it into a bitmap and \r
1319                 a color map\r
1320 \r
1321 PUTPICT.H, PutPict.c    \r
1322 \r
1323                 given a bitmap and a color map, save it as\r
1324                 an ILBM file.\r
1325 \r
1326 GIO.H, Gio.c    generic I/O speedup package.  Attempts to speed\r
1327                 disk I/O by buffering writes and reads.\r
1328 \r
1329 giocall.c       sample call to gio.\r
1330 \r
1331 ilbmdump.c      reads in ILBM file, prints out ascii representation\r
1332                 for including in C files.\r
1333 \r
1334 bmprintc.c      prints out a C-language representation of data for\r
1335                 a bitmap.\r
1336 \r
1337 \r
1338 \f\r
1339 Example Diagrams\r
1340 \r
1341 Here's a box diagram for an example IFF file, a raster image FORM \r
1342 ILBM. This FORM contains a bitmap header property chunk BMHD, a color \r
1343 map property chunk CMAP, and a raster data chunk BODY. This particular \r
1344 raster is 320 x 200 pixels x 3 bit planes uncompressed. The "0" after \r
1345 the CMAP chunk represents a zero pad byte; included since the CMAP \r
1346 chunk has an odd length. The text to the right of the diagram shows \r
1347 the outline that would be printed by the IFFCheck utility program \r
1348 for this particular file.\r
1349 \r
1350         +-----------------------------------+\r
1351         |'FORM'         24070               |   FORM 24070 IBLM\r
1352         +-----------------------------------+\r
1353         |'ILBM'                             |\r
1354         +-----------------------------------+\r
1355         | +-------------------------------+ |\r
1356         | | 'BMHD'      20                | |   .BMHD  20\r
1357         | | 320, 200, 0, 0, 3, 0, 0, ...  | |\r
1358         | + ------------------------------+ |\r
1359         | | 'CMAP'      21                | |   .CMAP  21\r
1360         | | 0, 0, 0; 32, 0, 0; 64,0,0; .. | |\r
1361         | +-------------------------------+ |\r
1362         | 0                                 |\r
1363         +-----------------------------------+\r
1364         |'BODY'         24000               |   .BODY 24000\r
1365         |0, 0, 0, ...                       |\r
1366         +-----------------------------------+\r
1367 \r
1368 This second diagram shows a LIST of two FORMs ILBM sharing a common \r
1369 BMHD property and a common CMAP property. Again, the text on the right \r
1370 is an outline  a la IFFCheck.\r
1371 \r
1372 \r
1373      +-----------------------------------------+\r
1374      |'LIST'            48114                  |  LIST  48114  AAAA\r
1375      +-----------------------------------------+\r
1376      |'AAAA'                                   |  .PROP  62  ILBM\r
1377      |  +-----------------------------------+  |\r
1378      |  |'PROP'         62                  |  |  \r
1379      |  +-----------------------------------+  |\r
1380      |  |'ILBM'                             |  |\r
1381      |  +-----------------------------------+  |\r
1382      |  | +-------------------------------+ |  |\r
1383      |  | | 'BMHD'      20                | |  |  ..BMHD  20\r
1384      |  | | 320, 200, 0, 0, 3, 0, 0, ...  | |  |\r
1385      |  | | ------------------------------+ |  |\r
1386      |  | | 'CMAP'      21                | |  |  ..CMAP  21\r
1387      |  | | 0, 0, 0; 32, 0, 0; 64,0,0; .. | |  |\r
1388      |  | +-------------------------------+ |  |\r
1389      |  | 0                                 |  |\r
1390      |  +-----------------------------------+  |\r
1391      |  +-----------------------------------+  |\r
1392      |  |'FORM'         24012               |  |  .FORM  24012  ILBM\r
1393      |  +-----------------------------------+  |\r
1394      |  |'ILBM'                             |  |  \r
1395      |  +-----------------------------------+  |\r
1396      |  |  +-----------------------------+  |  |\r
1397      |  |  |'BODY'              24000    |  |  |  ..BODY  24000\r
1398      |  |  |0, 0, 0, ...         |  |  |\r
1399      |  |  +-----------------------------+  |  |\r
1400      |  +-----------------------------------+  |\r
1401      |  +-----------------------------------+  |\r
1402      |  |'FORM'         24012               |  |  .FORM  24012  ILBM\r
1403      |  +-----------------------------------+  |\r
1404      |  |'ILBM'                             |  |\r
1405      |  +-----------------------------------+  |\r
1406      |  |  +-----------------------------+  |  |\r
1407      |  |  |'BODY'              24000    |  |  |  ..BODY  24000\r
1408      |  |  |0, 0, 0, ...         |  |  |\r
1409      |  |  +-----------------------------+  |  |\r
1410      |  +-----------------------------------+  |\r
1411      +-----------------------------------------+\r
1412 \r
1413 \r
1414 \f\r
1415 Appendix B. Standards Committee\r
1416 \r
1417 The following people contributed to the design of this IFF standard:\r
1418 \r
1419 Bob "Kodiak" Burns, Commodore-Amiga\r
1420 R. J. Mical, Commodore-Amiga\r
1421 Jerry Morrison, Electronic Arts\r
1422 Greg Riker, Electronic Arts\r
1423 Steve Shaw, Electronic Arts\r
1424 Barry Walsh, Commodore-Amiga\r