CHUNKMASTER 1.0: Easy manipulation of all IFF files! ---------------- by Frédéric DELACROIX. DISTRIBUTION This program is released as shareware,if you find it useful and decide to keep it,send a small contribution (I suggest $10 or equivalent) to: Frédéric DELACROIX 5 rue d'Artres 59269 QUERENAING FRANCE This should in particular help me to get the Kickstart 2.0 system and pro- gram even better utilities. Every suggestion,bug report,comment,etc is welcome. ChunkMaster is freely distributable provided that: - No profit is made beyond minimal copy fees - This documentation,the program and the icons are distributed to- gether. - No change is done in any way to these files (except crunching) Of course,I accept no responsability regarding the use or misuse of this program. INTRODUCTION The IFF format should enable all programs that share a same data type to easily understand each other. Most of these programs only use one type of data: pictures,sounds,animations,text...,but none to my knowledge does allow direct handling of all these files at the lowest level,that is to say the very constitution of FORMs and CHUNKs.That's the goal of ChunkMaster. THE IFF FORMAT Here follows a brief description of the constitution of a generic IFF file, without any type discrimination. An IFF file is composed by FORMs and chunks. It can also contain other structures (PROPs,LISTs) but they are very scarce and no documentation can be found. Generally,only one FORM composes an IFF file,but it is not forbidden for an IFF file to contain more. A FORM is a bit similar to a directory: it can contain either chunks,which is the more frequent case,or other FORMs,which is the case in animation or text files. A FORM is identified by the word "FORM" at the beginning,followed by a longword containing the length of the FORM.Then comes the FORM type,also coded on 4 bytes:ILBM (InterLeaved BitMap) is the most frequent for graphics,8SVX for digitized sounds,FTXT for text,ANIM for animations,etc... There can exit an infinity of types. Then come the chunks thempselves.A chunk is constituted as follows:An iden- tifier,again coded on 4 bytes,indicates the type of the data. They can be annotations (ANNO),a name (NAME),a copyright notice ((C) ),but above all BODY for the main data,CMAP for a color palette,and the list is very long. The 4 next bytes give the length of the data (Identifier and length exclu- ded).Then the data.At the end of the data,a zero byte may come,so that the next chunk begins on an even offset.This byte then is NOT counted in the length of the chunk. Then comes the next chunk,and so on until the end of the FORM.Then can come another FORM and so on... Here is a diagram summing all this on a particular file,which describes a picture: FORM $3106 ; beginning of the first FORM,it is 12550 ($3106 hexadecimal) ; bytes long.The length is counted from the next byte. ILBM ; Means InterLeaved BitMap,this FORM describes a picture. Here begin the chunks contained in that FORM: BMHD $14 ; 1st CHUNK: it is a BMHD (BitMap HeaDer) structure,which ; represents the constitution of the picture.The standard ; length is 20 bytes. Here begin the data of this chunk: $0140 ; Width : 320 pixels ($140 hexa) $0100 ; Height: 256 pixels ($100 hexa) $0000 ; X Coordinate of the picture:0 pixel from the left edge $0000 ; Y Coordinate of the picture:0 pixel from the upper edge $03 ; Depth:3 planes,which give 8 colors $00 ; Masking: no mask $01 ; Compression: the picture was compressed (only affects the ; BODY chunk) $00 ; Fill byte,only used to have the next word on an even offset $0007 ; Transparent color: color 7,which isn't taken in account as ; the making flag doesn't indicate such a thing. $0A ; xAspect: Width/Height relation $0B ; yAspect $0140 ; Width of the page:320 pixels $0100 ; Height of the page:200 pixels Another CHUNK: CMAP $18 ; 2nd Chunk:gives the color palette (Color MAP) for this ; picture. The length is adjusted to the number of colors ; Here,it is 24 bytes: 24=8 colors * 3 components (red,green ; blue) The palette data come here: $000 ; Color 0,in RGB format: Red-Green-Blue Then come the next colors. Another one: CAMG $4 ; 3rd Chunk:gives the view modes of the picture on the amiga ; (Commodore AMiGa).Its length is always 4 bytes,although ; only 2 of them are used. And its data: $00004000 Last chunk: BODY $30B1 ; Body (BODY) of the picture.It contains the points themselves ; that compose the picture.Note that this is an odd length, ; therefore there will be a fill byte at the end. Let's verify that all this matches the length of the FORM: we must add to each chunk length 8 bytes corresponding to the chunk identifier and its len- gth,and 4 more bytes for the FORM identifier (ILBM),and the fill byte of the BODY chunk: $3106 = 4 + $14 + 8 + $18 + 8 + $4 + 8 + $30B1 + 1 + 8 FORM =ID + BMHD + CMAP + CAMG + BODY This is in fact the most simple IFF file that exists. It can be seen that the IFF format enables a powerful data storage,with many complementary info,but also that it is very tedious to use and it's very difficult for a beginner to find back his data. ChunkMaster's goal is just to EASILY handle that type of structure. INSTALLATION: ChunkMaster is not demanding at all.In its current version,it doesn't need other libraries than those that are in ROM. ChunkMaster has been tested with success on many configurations,but if a compatibility problem was to rise,let me know. ChunkMaster can be started either for CLI or from Work- bench. As soon as it's launched,ChunkMaster searches for a configuration file named S:ChunkMaster.prefs. If it doesn't exist,ChunkMaster uses the default settings That file may be created by ChunkMaster itself. FUNCTIONS OF THE PROGRAM: 1) About... Accessible by chosing in the Project menu or clicking the title.A window opens with my address and the amount of enable memory. 2) Quit ChunkMaster can be left either by clicking the gadget at the bottom,or by chosing the proper menu. It is to be signaled that all the work that hasn't been saved will be lost. A window asking for confirmation will ap- pear if the "Confirm" flag is set (see later).Be careful! 3) Load IFF file: With this function,accessible by the menu or the gadgets,you can load an IFF file into memory. A FileRequester (see later on) appears and asks for the file to load.Click on cancel to cancel... Warning: loading an IFF file will destroy any file that is currently in me- mory.Once more:be careful! Once loaded,the file is analyzed,in order to detect FORMs and chunks.If it isn't a valid IFF file,the program says so and unloads it. Once the analysis finished,the program displays the structure of the file on the screen,it is made like that: - All this happens on the central part of the main screen. - You are at the level 0,that is to say that the detail of the FORM isn't seen yet.The main FORM(s) are displayed (in white),with their identifier, their length and the number of chunk contained in them. - To select a FORM,just click on it with the mouse.The FORM,and generally speaking the chunk, that has been selected appears on blue background. - To "enter" a selected FORM,you click on the right arrow.The chunks con- tained in the FORM are then displayed. A double-click on the FORM would have produced the same effect.To come back,click on the left arrow. between these two arrows,a digit indicated the current level.0 is the base level,and for a level higher than 10,a + sign is displayed. - Such a selection,as described above,will be necessary for many functions. - If there are more than 16 chunks,you can scroll through the list by clicking on the up and down arrows.Between these two arrows,there is a position indicator.If you click on it,a cursor appears and you can en- ter the position via the keyboard.That number is the position of the first displayed chunk.0 is the first Chunk,and to go to the end of the list, just enter a large number. For the Load IFF function,you are at level 0 after the loading,and generally there is only one FORM. 4) Save IFF file: This function is accessible by the gadgets on the right or by the menu. It is used to save the IFF file you are currently working with. All alte- rations you have made will be recorded. The program displays a FileRequester asking you the name of the file.Click on cancel to cancel the save operation. The file is saved in IFF format,and if the modifications you have made are coherent (you are not expected to put anything in a file),the file will be able to be loaded used to edit that particular type of file (a paint pro- gram,a music program...). 5) Delete File: This function is very simple and dangerous.It simply deletes a file on a disk.Click on cancel if you made a mistake.The program may ask for con- firmation (see the PREFERENCES chapter) before deleting.Warning:there is no way to recover the deleted file! Accessible by gadget and menu. 6) Append File: Accessible by gadget and menu.This function is used to fusion two IFF files into one.Here is what you have to do. First,you must have an IFF file al- ready in memory (else this function acts just like Load IFF).Place your- self in the wished FORM,at the wished level.It is indeed possible to inclu- de the file into an already existing FORM.Then click on Append File and the FileRequester appears.Tell it what file to load.The file is then loaded into memory (provided that it's an IFF file) and the new FORM(s) are added to the end of the list,on the current level.You will be able to move them using Cut Chunk. This function may be very useful when working on animations (ANIM) and texts from publishing programs (FTXT). 7) Cut Chunk: This function needs to have a chunk already selected,like explained above. The selected chunk is deleted from the list (the length of the current FORM is recalculated),and placed into a special buffer. The buffer acts like buffers in text editors. It's just a temporary memory,if it contained something before,it is destroyed,so be careful! The buffer of course WON'T be saved if you save your file.So the chunk vanishes from the screen but it is not lost. That function acts on chunks as well as on FORMs. 8) Copy Chunk: This function acts exactly as the previous one,except that the selected chunk doesn't vanish from the list,it is only copied.The new chunk (the copy) is then stored in the buffer the same was as Cut Chunk.The only visible result is the chunk deselecting.Warning:the function needs memory, and can thus fail.Moreover,it only acts on chunks,NOT on FORMs. An attempt in copying a FORM will result in an error message and the abandon of the operation. The copy of FORMs could in fact be programmed but it would be too complex for a minor interest.I'll maybe include it in a future version if someone is missing it (keep me informed!). 9) Paste Chunk: This function is used in conjunction with the two previous ones.It enables to paste the previously cut (Cut chunk) or copied (Copy chunk) chunk in the buffer.So you need of course to have executed one of theses two functions first. Warning:contrary to text-editors,the buffer isn't copied:the chunk contained in the buffer is itself inserted in the list and the buffer is cleared.To make multiple copies,it is thus necessary to make multiple Copy chunk. The operation is done as follows: Click on Paste Chunk.The program checks if the buffer is empty (if so,there is nothing to paste),then dis- plays a requester that asks for the position of the chunk to insert (see chapter NUMBER REQUESTER).Type in the required position.If it is too high the chunk is inserted at the end of the list. Very easy isn't it ? 10) Delete Chunk: This function is very simple in its principle (a bit less when programming but who cares?):deleting a chunk from the list.You must first select a chunk then click on the gadget (or chose the menu) Delete Chunk.The program may ask for confirmation and then the chunk is deleted from the list.There is no way to recover it so be careful. It is also possible to delete FORMs.If the selected FORM is empty,Chunk- Master deletes it without asking anything.If it isn't,it asks for confirma- tion (maybe) berore erasing it:that operation will destroy every chunk con- tained in the FORM. 11) Save Chunk: This function is used to save the contents of a chunk or a FORM.You must have selected an object before clicking the gadget. If the object is a chunk,its contents are saved without any format (RAW). If the object is a FORM,it is saved as a whole IFF file.For example,if your main file is an ANIM file:normally,in that type of file,there is first a FORM ILBM.By selecting this FORM and clicking the gadget,you will get a new picture file ILBM corresponding to the first frame of the animation, which ca be loaded in a paint program. The use of this function is thus very easy.A FileRequester appears,asking you the name of the file to save.Cancel cancels the whole thing,but you're used to that now. 12) Add Chunk: This function is used to add a chunk or a FORM to the list.First Click on the Add Chunk gadget (or chose the right menu). A small window will then open,waiting for you to set the attributes of the new chunk. There are first 2 big gadgets: FORM and CHUNK.Clicking on one deselects the other. This selects the type of the new object: FORM or CHUNK. Further down there is a string gadget,that will contain the identifier of the FORM (ex:ILBM,8SVX, SMUS...) or the chunk (ex:BODY,CAMG,CMAP...). An identifier should always be of 4 uppercase letters. Although ChunkMaster tolerates lowercase letters, it will add spaces if the ID is too short. There is below another string gadget corresponding to the length of the new chunk.If the object is a FORM,that value is ignored.Indeed,a chunk or a FORM added by this function is empty.For a chunk,the allocated memory is filled with a number of 0 corresponding to that value,but for a FORM,whose reason to be is to contain chunks that don't exist at the moment,its length is only 4 bytes,that are in fact occupied by the identifier.You can't alter them directly. The length can be entered either in decimal or in hexadecimal (use a dollar sign!). The new chunks can be handled just like others. 13) Edit Chunk: That's the most complex function of the program.It's used to directly modi- fy the contents of a chunk,ie its own data. The function is effectless on FORMs. You must select a chunk and click "Edit Chunk".This operation requires extra memory as you won't be editing the chunk itself but a copy,that will replace the original chunk later on.This enables a step back for security. You can also invoke it by double-clicking on a chunk name in the list. A big window will open with all that the chunk contains.At the top of the display there is the string gadget indicating the identifier of the chunk.You can alter it by clicking the gadget or pressing Right Amiga+nu- meric keypad 5.A cursor appears and you can erase the old ID and replace it. Further right is the position gadget.It always indicates the position in the chunk of the first displayed byte.You can change its value,thus moving the cursor,by clicking in it or pressing ENTER (numeric keypad).The value can be entered either in decimal or hexadecimal (in that case,put a $ (dol- lar) sign before the hex value). The display is then refreshed so that the cursor matches the right position. Right is an indicator of the size of the chunk.This is NOT a gadget,clic- king in it will have no effect.It is only the current size of the chunk, that can be altered by other means (suspense!). On the right edge is a gadget named HELP.Click on it to get the summary of all keyboard assignments. Pressing the HELP key has the same effect. Below that first line of gadgets is a big border,divided into several co- lumns that are,from left to right: - The offset,indicating the position in the chunk of the next byte, - the first longword,made of four bytes - the second,third and fourth longwords. So there are 4 longwords,i.e 16 bytes, per line. - the displayable ASCII characters that correspond to these bytes (16 chars per line). On one of the lines,you can see a blue square,this is the CURSOR (no joke!). In fact,there are two cursors:one for the hexa display and one for the ASCII display.How to move the cursor,first by the keyboard: Arrows right: Next byte (next column) left: Previous byte (previous column) up: 16 bytes before (previous line) bas: 16 bytes after (next line) Alt+Arrows right: Next longword left: Previous longword up: Previous page down: Next page Shift+Arrows right: End of line left: Beginning of line up: Top of chunk down: End of chunk TAB: Next longword Shift+TAB: Previous longword Right Amiga+9 Numeric Keypad: Previous page Right Amiga+3 Numeric Keypad: Next page Right Amiga+7 Numeric Keypad: Top of page Right Amiga+1 Numeric Keypad: End of page Right Amiga+8 Numeric Keypad: Scroll one line up Right Amiga+2 Numeric Keypad: Scroll one line down Right Amiga+4 Numeric Keypad: Previous byte Right Amiga+6 Numeric Keypad: Next byte RETURN: Next line,column 0 F1-F10: Go to marker. Shift+F1-F10: Set a marker. The cursor can be moved by directly clicking at the place where you want it to go,either on a byte in the hexa display or in the ASCII display. The goal of this function is of course altering the contents of the chunk. There are two modes of editing:ASCII editing and hexa editing. The ASCII editing: it is done by typing characters directly on the keyboard, just like in a text-editor,the CAPS LOCK key being OFF.Everything you type is displayed "as is" in the ASCII zone.The hexa display is also refreshed. The cursor is move one byte right for each character typed. Hexa-editing is selected by lighting the CAPS LOCK key. You enter then the hexadecimal value on the keyboard.Two digits are necessary.Only the numbers 0-9 and the letters A-F are accepted.Like ASCII-editing,the cursors moves one byte forward for each byte edited. The Backspace key (back arrow) clears the the previous byte (it is set to 0) and moves the cursor 1 byte back.The DEL key clears the byte under the cursor. Under the big border,there is a bunch of gadget.The first one is Done. Click on it when you want to exit the edit function.Warning:the changes you may have done will be definitive.The program may ask to confirm. The second gadget is Undo.It invalidates all the changes that have been made since Edit Chunk has been called.It affects the chunk identifier and its size as well as the chunk data. It destroys any change made to them. There (fortunately) exist a means to exit Edit chunk without making a change. It consists in clicking first on Undo then on Done. An equivalent and faster means is to click on the close gadget on the window,in the top left corner. The third gadget is Insert.It is used to add bytes to the chunk.First place the cursor where you want bytes to be inserted and click on Insert (or press Right Amiga+0 Numeric Keypad).A requester will then ask the number of bytes to insert.Answer or cancel.The given number of 0 is then inserted at the location the cursor is,and the chunk size is modified. Warning:such an operation may require a large amount of memory. The fourth gadget is named Delete. It is the opposite of the previous function.First place the cursor where you want bytes to be deleted and click on Delete,or press Right Amiga+. Numeric Keypad. A requester asks you how many bytes are to be deleted.The given number of bytes are deleted and the chunk size is modified.That operation may also require a large amount of memory. The fifth gadget is named Add,it has exactly the same function than Insert, except that the new bytes are added at the end of the Chunk,wherever the cursor may be.For the rest,do like Insert. The next two gadgets are not enigmatic:Page up to go back to the previous page,and page down do go to the next page. There is one gadget left,Load Raw,which is an interesing funtion. It ena- bles to load a file directly into the chunk.If you click on it,a new win- dow opens,asking for the type of the loading to be performed.Chose: - Replace: the contents of the chunk will be litterally replaced by those of the file.The size of the chunk is modified to match the file size. The only way to recover the lost contents is 'Undo'. - Append: The contents of the file are added at the end of the chunk data. The chunk size is expanded. - Insert: The file is inserted at the very cursor location,the size is ex- panded. - Overwrite: The file overwrite the old data in the chunk on all its length, from the cursor location.If the chunk isn't big enough to contain the whole file,ChunkMaster will expand it. - If you made a mistake,click on Cancel. This ends the description of this big Edit function,and of all the functions of ChunkMaster. THE PREFERENCES MENU 1) Confirm Requests That option will tell ChunkMaster whether he must warn the user every time he is able to do something wrong,like quit ChunkMaster,or delete a chunk. If the checkmark is displayed,ChunkMaster will do so. Last thing:for these requesters,I have respected the convention from commodore that consists in putting the "yes" gadget on the left and the "no" gadget on the right. To satisfy such a requester,you can also press Y for the positive gadget and N for the negative gadget. For the warnings (single-gadgeted requesters,like DOS errors),pressing any key will replace clicking on the gadget. 2) FileRequester devices All amiga owners don't own of course the same configuration.So,whereas the device gadgets in the FileRequester are perfect for my configuration, they might not fit for yours. In order to solve that problem without ris- king my mental health exploring the dos.library,I decided to make those gadgets programmable. All you need is to chose this menu.A window appears with a bunch of gadgets. As you might have noticed,the first line is made of the gadgets from the FileRequester. Normally,on entering the function,the first gadget is selected. Clicking one gadget deselects the others. below,a string gadget contains the title of the selected gadget.You can alter it,its name mustn't exceed 7 Characters,colon included.If the colon isn't there,ChunkMaster adds it. Further down are three boolean gadgets.Okay valids all changes and keeps the FileRequester informed.Undo All cancels the changes,all the display is brought back to what it was on entering the function (all changes are lost),and Cancel exits the function without confirming any change.Clicking on the window close gadget has the same effect,like in most cases. 3) Change Colors That menu pops up a window,which is in fact a palette requester,to make ChunkMaster match your tastes.There are 4 big gadgets that represent the 4 colors on ChunkMaster's screen.Clicking on one of them deactivates the others. 3 proportionnal gadgets,fortunately named R,G,B,correspond to the red, green and blue components of the selected color.You can move them,thus changing one of the screen colors.The hexadecimal value is displayed on the left. At last,2 complementary gadgets:Okay to exit and confirm changes,and Cancel to exit while canceling them. 4) Save Prefs This function saves all environment settings in ChunkMaster.The destination file is named S:ChunkMaster.prefs. If it doesn't exist,it is created,and if it exists,the older one is killed and replaced by the newer one. This configuration file contains: - The screen colors, - The "confirm requests" flag status as well as the status of the "Hide .info" flag in the FileRequester, - The programmable devices of the FileRequester, - The current directory of the FileRequester. That file will be loaded into memory on the next calling of ChunkMaster. THE FILEREQUESTER No doubt it is the first thing you will see in ChunkMaster.Its use is very simple and very traditionnal for a FileRequester.Its goal is to ask the user the name of a file,existing or not,in such a way that he has a good idea on how his disks are organized.It is a window with gadgets spread all over it.Let's see them in order. 1) The file list It is the list of all files in the current directory.While the program is reading it,the user still has access to all functions of the FileRe- quester.But there is one advantage of letting the FileRequester finish that task before closing; Once the list integrally read,it is not necessary to read it again on the next calling of the FileRequester. 10 files can be seen simultaneously on screen,by name and size (for a file) or the dir mention (for a directory).Files are displayed in black and direc- tories in white.The files are sorted alphabetically,with files first and then directories.The sorting job is done only when reading is finished or when the user scrolls the list. It is of course possible to see more than 10 files:to move through the list, you can use the up and down arrows (the gadgets,not the keyboard),or the proportionnal gadget.It is quite obvious. Moreover,it is possible to hide certain files,the famous .info files con- taining the worbench icons.They are useless for ChunkMaster,but if,for some strange reason,want to see then,click on Hide .info to deselect the gadget. 2) Selection: the string gadgets There are two of them.The first one contains the name of the current direc- tory,and the other is the name of the selected file. For the directory,you can either click and type the whole path on the keyboard,and the given di- rectory,if it exist,will be read as soon as you press return.You can also chose a directory in the the displayed list,which has the same effect.The boolean gadget on right of the string gadget forces the program to re-read the directory.Indeed,some files may have been added since the last time... There are many gadgets below,which you already know if you have read the preferences chapter. Clicking on one of them replaces the contents of the string gadget by the corresponding device (DF0:,RAM:,etc...),and the rea- ding of the new directory begins. These gadgets may be personalized like indicated above.There is also the Parent gadget,which is used to read the ascendant directory of the one currently read.Try it to make it clear. The file gadget is easier to use.You can enter a name by the keyboard,then pressing RETURN will be equivalent to clicking on Okay. Clicking a filename in the list will copy the name into the string gadget.If you double-clicked it,an "Okay" will be done. 2 more gadgets remain: Okay and Cancel.The former is used to close the FileRequester while accepting the selection (the filename is considered valid and given to the main program),whereas the latter cancels the whole operation.The requester closes and no action is done. NUMBER REQUESTER Two words for this easy to use requester.Its goal is to ask the user for a number.It's a window with a string gadget and two boolean gadgets. The string gadget is used to enter the number.You can either type it in decimal format or hexadecimal. If you chose hexadecimal,a $ (dollar) sign must preceed the number. The boolean gadgets are Okay to satisfy the requester,and Cancel to close it and cancel the current operation.The close gadget is the same as Cancel. FUTURE IMPROVEMENTS: This program is only version 1.0,there are many improvements to be made. If the success justifies it,there will be many other versions! Among them: - Use of a more sophisticated FileRequester - Different editing routines for known chunk types,an a default routine for unknown ones. - Recognition and use of crunching routines like ByteRun 1. - Perhaps a powerpacker.library interface - Why not an ARexx port ? - Recognition of other IFF "objects":CATS,PROP,LIST... - ... For many subjects (like ARexx), what lacks is the technical documentation, but above all,what I need is YOUR support,you the amiga community... This program demanded much time (it was written completely in assembly), so think about me for contributions,suggestions (I really need them),com- ments,and everything that comes to your mind: Frédéric DELACROIX 5 rue d'Artres 59269 QUERENAING FRANCE Thanks !!! FINAL NOTE: The principle of ChunkMaster is quite simple,but quite complex to realize. I used recursive algorithms and many horrible things like that. I tried to stay lucid and keep a 'clean' programming:ChunkMaster will free all alloca- ted memory,close everything that was opened...,not like some programs (there still exist some) that load a file at an absolute address without taking care of what was there before! But some hidden bugs might remain.The best way to discover and smash them is that you give me an EXACT description of the problem,so that I may reproduce it and solve it. For this version,I prefer to keep the source code because I don't want to many different versions of ChunkMaster to be.Maybe later... THANKS: Quick greetings and thanks to: P.Dussart,Y.Quiquempois,B.Buirette,M.Truffin,S.Laffra,B.Wa'aloun,X.Ratayzyk, F.Jacobs,B.Bar,E.Hot,A.Camerlync,C.Descamps,D.Richez, ...and you who found the courage to read this far ! THE END: It's high time I finish this already too long doc ! Good night !! THE AUTHOR: Frédéric D.