********************************************************* IFF Editor V1.01 Written by Alexis WILKE (c) 1994 ********************************************************* *** SUMMARY 1. INTRODUCTION 2. INSTALLATION 3. GETTING STARTED 4. EDIT A FILE 4.1 THE BUTTONS 4.2 THE MENU 5. EDIT A CHUNK 6. CHUNK STRUCTURES 7. KNOWN BUGS 8. COPYRIGHTS 9. ABOUT MY OTHER PRODUCTS 10. CONTACTS *** 1. INTRODUCTION This tool was created because while making a new file format, one must usually change it often. This editor allows the user to edit and adjust the file data easily, without complex programming which would result in lost time. *** 2. INSTALLATION To install the IFF Editor, copy the file 'iffed' into a directory which is in your list of PATHs and the file 'iff.stc' into 'S:'. The file 'iff.stc' is optional, but when missing, you are prompted. The file 'iff.stc' can be copied in your current directory only (i.e. if you want to test this tool). Note that IFFEd checks the current directory first. *** 3. GETTING STARTED The use is very interface-like. The tool can be loaded from the Workbench, or from your CLI like most tools I create. The data file 'iff.stc' contains some known chunk structure definition. All those structures can be modified by anyone. New releases will probably contain more structures. The structures are declared mostly like in C language. Below, you will see the definition of the available instructions and specific keywords or names. To load the file, you can select the IFF file icon on your Workbench and then double click on IFFEd. Alternately, from the CLI you can type 'IFFEd '. (A file requester will appear if you start IFFEd without file name or selected icon.) Only one file can be edited at a time. At any moment, you can load a new file by clicking on the 'Load New File' button. Clicking on the 'New' button from the file requester will allow you to create a new IFF file from nothing. The file name will have to be supplied later, also you do not have to bother naming the file if you decide to click 'New'. *** 4. EDIT A FILE After you started IFFEd, you automatically are editing the file. At this time the following options are available to you: 4.1 THE BUTTONS . New (Note: Not the 'New' button from the file requester) Creates a new chunk. The chunk will be empty and will receive the name '???'. The new chunk is inserted before the current selection. If there is no selection, the new chunk is appended at the end. . Del Deletes the selected chunk. The chunk can be restored by: o the 'Undo All' button if it was in the original file o 'Undo' -> 'All Possible Hunks' menu item if it was new . Undo When not disabled, the currently selected chunk has been modified from the original file, or is a new chunk. New chunks can't be undone. So, a click on the "Undo" button will restore the chunk to the way it was last saved. Changes made after saving don't enter the undo buffer, and clicking "Undo" returns the chunk to its last saved condition. . Edit Enables you to edit the selected chunk for you to modify it as you wish. For more information about editing a chunk, see EDIT A CHUNK. . Size display and Valid acknowledge When you select a new chunk from the list, the actual size of the chunk is displayed in the box at the bottom of the window. Then if the chunk is "known" (if it as been defined in the 'iff.stc' file,) the text "Valid" or "Bd Size" appear on the right of the list. Note that a structure with a variable size will usually display "Bd Size," but it does not mean the chunk is invalid. . IFF Type The IFF type definition is also found into the 'iff.stc' file. If IFFEd is able to find a definition which fits the file contains, then it will be displayed. For instance, ILBM is defined as "Picture." . IFF Name This text box editor enables you to modify the name of the IFF file. This is the name defined at the very beginning of the file like: ILBM, 8SVX, CTLG... . Undo All Restores all chunks as present into the original file. The new chunks will be deleted and the others will be restored with their original size and data. You should not apply "Undo All" on a new file, because nothing is original. . Save Saves the file with current information. A file name will have to be supplied if a new file has been created. If you need to modify the name of the file before to save it, use the "Save as ..." from the menu. . Load New File As mentioned before, this button will enable you to load another file. If the active file has been modified, you will be prompted about whether you want to save the file or forget all the modifications. . Quit (or the Close Window button) This button will make you quit the IFFEd tool. 4.1 THE MENU The menu is hidden from you. You have to click on the right mouse button to make it appear. The menu uses layers and is also very quick, but this usually results in a bad refresh of the other windows. To have a refresh, just move a window (Note: this is one more hidden function which has not been defined in intuition.library!!!) However any other tasks can be running at the same time on the Workbench. To select a menu item, move the mouse as usual. Menus which have an arrow (->) have sub-menus. You will have to wait up to two seconds for the sub-menu to appear. A description of each menu item follows: . Menu: About Displays a little window with the copyright and version of IFFEd. . Menu: Load new file This is an equivalent of the "Load New File" button. . Menu: Save This is an equivalent of the "Save" button. . Menu: Save as ... This is also explained in the "Save as" button. It enables you to save your file with a different name. The file requester is displayed for you to defined the new name. . Menu: Structures -> Print This menu item will print all structures into the output. This may not work if you use the Workbench. It should be use only by people wishing to edit the 'iff.stc' file. It is useless for anyone else. . Menu: Structures -> 'int' type is 4 bytes The type 'int' in C might be 2 or 4 bytes. By default it is set to 2 bytes. However if you use structures with 4 bytes integers, select this menu item. A check mark appear which let you know you use four bytes integers. Select it again to restore the size of 2 bytes. . Menu: Quit This is an equivalent of the "Quit" button. . Menu: Chunk ... Each point under 'Chunk' is just a copy of the button presents on the right of the chunk list. . Menu: Undo All -> Original file This is an equivalent of the "Undo All" button. . Menu: Undo All -> All possible chunks This is explained under the "Undo All" button. It will restore the data and size of all chunks. All deleted chunks are restored as well, new or not. *** 5. EDIT A CHUNK You will have the "Edit Chunk Data" window opened when a chunk is selected and the "Edit" button is clicked. The edit window has the following buttons and functions: . The list Chunk data will appear in the list box. If a structure definition exists from the "iff.stc" file, then the name (and size when available,) of that structure are displayed on the first line, then the fields will follow on next lines. If the chunk data buffer is smaller than the structure, a line will be inserted at the end of the list to inform you about the problem. Then you can redefine the size with the "Resize" button. If the size is larger than the structure the last fields will be inserted with a different color. If you are missing a chunk definition, you will have to quit IFFEd, edit the file 'iff.stc' to add the definition and then restart IFFEd. IFFEd loads the definitions when it starts and will not know if 'iff.stc' has been modified while you are using it. When a structure is not defined, the default internal definition is used instead: char *ary[8]; . Field Edit Box Click on a line from the list to edit its contents. The data are copied into the field box under the list. When several values are defined on the same line, each must be separated with a space and should be supllied. If more values than necessary are defined the last are ignored. If less values than necessary are supplied, the last values are supposedly null and the end of the buffer will be cleared. The parser understands decimal, hexadecimal, binary and octal values. Decimcal values must contain only digits (0-9). Hexadecimal are defined with digits (0-9) and letters (A-F,) to force a hexadecimal value, the sign '$' should preceed the value or an H should follow the value. A value is also recognized as hexadecimal if it contains a letter (A-F), however "B" may generate confusion. The binary value must start with a sign '%' or finish with a B if it is at the end. The octal values will finish with an O. The parser is case insensitive, so letters may be typed in lower case. . Chunk Name Edit Box The chunk name is defined at the top-right of the "Edit Chunk Data" window. If you modify it, the list will be modified to reflect the correct structure (if such a structure exists.) A null name is not valid. . Use Button Click on this button when you are done. The modifications will be saved and the chunk will be noted as modified. You will not be able to click on the "Use" button if no name is supplied for the chunk (available in the edit box at the top-right corner.) If no modifications have been made, a click on "Use" is equivalent to a click on "Cancel". The keys Shift-Return can be used instead. . Size Box and Resize Button The size box shows you the current size of the chunk. If the structure of chunk is defined, then expected size will be displayed between parentheses and in a special color. If it is not the size you wanted, click on the "Resize" button and type the new desired size. . Cancel (and the Close Window button) This button will close the "Edit Chunk Data" window and forget about any modification. You should use this button if you were editing the chunk just to have a look at it. *** 6. CHUNK STRUCTURES The following is the language description for the 'iff.stc' file. The basic definition is like C. An 'iff.stc' file is given with this tool as example (??and first start). There are no restriction about the size of the 'iff.stc' file. The structure file actually contains 4 different types of definitions: . typedef (generates new types) The 'typedef' instruction can be used to generate new types and then avoid the definition of a 'complex' type repeatedly. There is an example of typedef: typedef unsigned char uchar; typedef unsigned short ushort; typedef unsigned int uint; typedef unsigned long ulong; . struct (generates user types) The structures (which may contain structures as necessary) will be used to define user defined types. There is an example for BitMapHeader structure: struct BitMapHeader { ushort width; ushort height; ushort xPos; ushort yPos; uchar nPlanes; uchar masking; uchar compression; char PAD; short transparentColor; uchar xAspect; uchar yAspect; ushort pageWidth; ushort pageHeight; }; or with multiple structure definitions: struct Point { short x; short y; }; struct BitMapHeader { struct Point size; struct Point pos; uchar nPlanes; uchar masking; uchar compression; char PAD; short transparentColor; uchar xAspect; uchar yAspect; struct Point pageSize; }; . type (defines IFF type names) The IFF file types are defined like variables that receive a value (a string pointer.) Those definitions have to start with the type 'char *' or an equivalent 'typedef,' have the name of the IFF type to define (Like ILBM, 8SVX, MAP, ...) and be followed by the string. The special type '????' is by default used as the unknown type. Here is an example for the ILBM type: char *ILBM = "Picture"; . variable (defines the relation between the chunk and the data) The variables define the link between an IFF file type and the name of a chunk. They should not have a value assigned to them. When a chunk can be found in any IFF file, you can define the IFF type as '*'. There are two examples, the BitMapHeader is a chunk specific to the ILBM type and the BODY is found is most files containing one block of data: struct BitMapHeader *ILBMBMHD; char "*BODY"[]; As you can see, both variables are pointers. It is necessary; otherwise an error will be generated. The BODY definition is set between quotes to be sure that the '*' is part of the name, not a pointer sign. Note that a name which contains very special characters or which starts with a digit will be defined between quotes ("8SVX" or "(c) " are two examples). If you have several IFF files types which are very similar and you want all of them to know about a chunk. You may use the sign '?' rather than a specific letter. For instance if you had 'MAP0' and 'MAP1' which both have a chunk named 'GDIR' the following can be used: char *"MAP?GDIR"; The use of a single pointer (defined by '*') and the use of an array (defined by '[]') defines one occurance of the given type, or any number of occurance of the given type respectively. A specific number of occurance can as well be defined with []. The following is a complete definition of the language. This definition includes a special syntax: [ ... ] optional informations < ... > refer to a rule { ... } repeat as many times as necessary '?' you must type the character(s) ? in your file . basic types (referenced as: ) Byte Type Definition(s) Size 1 I 'char', 'signed char' 1 I 'unsigned char' 2 I 'short', 'signed short', 'short int', 'signed short int' 2 I 'unsigned short', 'unsigned short int' 2/4 I 'int', 'signed int' 2/4 I 'unsigned int' 4 I 'long', 'signed long', 'long int', 'signed long int' 4 I 'unsigned long', 'unsigned long int' 4 F 'float', 'signed float' 8 F 'double', 'signed double', 'long float', 'signed long float' 0 S 'void' I- integer, F- float, S- special . typedef definition (the becomes a ) 'typedef' {',' } ';' . structure definition ('struct' becomes a ) 'struct' '{' { {',' } ';' } { ':' {',' ':' } ';' } '};' Note: field definitions are not yet supported. Because a structure is a type by itself it can be used anywhere a type is required (in a 'typedef' or a 'struct' definition for instance.) . the variables [ '=' '"' '"' ] { ',' [ '=' '"' '"' ] } ';' . a string (referenced as: ) a string is a list of any character defined between " and ". . an identifier (referenced as: ) An identifier is a list of character, it can include any letter (case sensitive) and digits. However it can't start with a digit. The characters '@', '_' and '?' can be defined within an identifier. If you need to use anything which is forbidden as previously defined, you can define the identifier between " and " like in "8SVX" or "(c) ". *** 7. KNOWN BUGS I know there are some bugs into my interface handler which is only linked to the IFF editor code itself. I still have a hard time to be able to find out were the bugs are. One of those bugs is when you double click on a chunk name to edit that chunk, the list remains active and may appear into the new opened window. *** 8. COPYRIGHTS This product is a copyright of Alexis WILKE. This program is a FreeWare, however donations and post cards are welcome at (tell me which tool(s) you've got from my production): Alexis WILKE 1511, S.W. Park Ave #615 Portland, OR 97201 U.S.A. This program is protected by the law of Copyrights. His author is the only one to have the right to decide if this tool can be sold. No authorization will be given until a written consent has been signed by Alexis WILKE. *** 9. ABOUT MY OTHER PRODUCTS There is a list of my other products: . Overdrive When I first came in America, I praticipated to the elaboration of a game named 'Overdrive'. This game uses three disks and is available on request (address your request to me.) ftp.cdrom.com:/pub/aminet/game/demo/Overdrive2.lha ftp.cdrom.com:/pub/aminet/game/demo/Overdrive2.readme . lk lk is a powerful linker, with no bugs. It will replace your very old SLINK 6.5 and after you tried it, you will not even think about BLINK any version or ALINK. The last version of DICE as changed a lot and it is not garanteed that lk will be able to link 'dcc' object files. This tool is a shareware ($15) and a free demo version is available on your AmiNET: ftp.cdrom.com:/pub/aminet/dev/misc/LK_V1.??.lha ftp.cdrom.com:/pub/aminet/dev/misc/LK_V1.??.readme . make I wrote my own make, because assemblers does not come with file makers, this wasn't a bad idea. This make is very similar to make available on Unix machines. This tool is a freeware and can be found on your AmiNET: ftp.cdrom.com:/pub/aminet/dev/c/amake_v1.??.lha ftp.cdrom.com:/pub/aminet/dev/c/amake_v1.??.readme . IFF Editor IFF Editor is also on your AmiNET. If you want to take the last version of it you can search for it: ftp.cdrom.com:/pub/aminet/util/edit/iffed_v1.??.lha ftp.cdrom.com:/pub/aminet/util/edit/iffed_v1.??.readme *** 10. CONTACTS If you need some help for anything that you can't firgue out alone or if you have comments and suggestions, all are welcome at: alexis@netcom.com or at: Alexis WILKE 1511, S.W. Park Avenue #615 Portland, OR 97201 U.S.A Phone: (503) 248-5607 *********************************************************