ANIMATION BRIDGE by Ron Tarrant The software, manual and all related materials for Animation Bridge (ABridge) are copyright © 1990 by Ron Tarrant and Mythra-mations Animation and Software 902 West 17th Ave. Vancouver, B.C. Canada V5Z-1V4 CONTENTS line # Introduction.........................................61 Crossing the Bridge.................................106 What's Across the Water?............................136 DPaint III Specifics................................158 AniMagic Specifics..................................178 The Director Specifics..............................197 Movie 2.0 Specifics.................................209 Animation: Editor (pre - 1.12 release) Specifics....215 Animation Station Specifics.........................229 Operation...........................................252 Screen Layout.......................................261 Accessing Program Functions.........................286 Program Functions................................298 FILES MENU....................................305 OUTPUT FORMAT MENU............................400 AREXX MENU....................................458 Filename Extentions.................................486 ARexx Scripting for Animation Bridge................517 Tips For Maximum Compatability......................584 Toll Gate...........................................610 INTRODUCTION Although there is a standard for IFF animation files now (referred to by most people as ANIM-5 or Anim opt 5) a lot of reader programs and editor/special-effects packages have problems with the variations of the format. For instance, some readers allow changing the colour map 'on the fly' while the animation is playing; others tend to abort or (even worse) crash if they find more than one colour map in a single animation file. Although these problems WILL eventually be cleared up by the companies who've released these products, in the meantime animators still have deadlines to meet and can't waste time pulling animations apart and reassembling them in order to get from one program to another. Enter, Animation Bridge, the interim solution. When you're working on an animation that starts, say, in a 3-D rendering package, goes into a combination paint/animation package for some touch-ups, and then goes into another program to have some special effects added, it can be frustrating for you as an animator when one of these programs will not load your animation file or won't do the work required because of some bit of information that is either missing or extraneous. Animation Bridge addresses these problems of going between the various readers/editors of animation files that try very hard to adhere to the Anim-5 standard but, for one reason or another, don't... yet. In time, all these programs will have gone through upgrades or bug-fixes and will have no more problems loading and dealing with 'stranger' animation files. "Animation: Editor" (from Hash Enterprises Ltd.) is an example of one program that has had these problems addressed and the latest version (1.12 at this writing) will load all comers and deal with them more effectively. As we will mention again further on in this manual, Animation Editor is supported by Animation Bridge for versions older that 1.12, just in case you haven't got your upgrade yet. When the rest of the animation readers/editors have been upgraded and distributed, our program - Animation Bridge - will no longer be needed and it can become just another blank disk in your collection. Until then Animation Bridge serves as an interim solution to these problems. Animation Bridge was designed to detect problems mainly with OVERSCAN anim files. Crossing the Bridge We are going to assume that you know how to use your Amiga, get either a shell, CLI or WorkBench running and that you know the meaning of such terms as 'menu selection', 'gadget selection', 'stack size' and 'keyboard equivalents'. This will minimize the "hand-holding" and cut down on how much documentation you have to wade through. If you aren't familiar with such things, please refer to the manual that comes with your Amiga. Animation Bridge, if run from a shell or CLI, needs a minimum stack size of 4000 bytes to operate without a stack overflow. Since this is the default size for a stack you should have no problems. If you run Animation Bridge from the Workbench the stack size is taken care of for you, so you won't have to worry about it. The program opens on it's own screen with front/back gadgets to make it simple to go from Animation Bridge to whatever other applications you may have running. Multi-tasking should be no problem and Animation Bridge should peacefully co-exist with anything else you might have going on at the same time. We haven't, of course, tested Animation Bridge with all possible system configurations and PD utilities (running concurrently) so we naturally can't guarantee that it will work correctly under all conditions, but if you find you have problems of this type let us know and we'll do what we can to help solve them. Please see the contact information at the end of this file. What's Across the Water? The first thing Animation Bridge will do for you upon loading an animation file is to tell you pertinent information about the file. This information will appear at the top of the Animation Bridge screen in the appropriate string gadgets. Here are the details Animation Bridge will reveal: 1 - Name of the file 2 - default name of the file after conversion (this can be changed) 3 - Screen Width, Height, and depth (number of bitplanes) 4 - number of frames in the anim file (actual number, including looping frames if any) 5 - which program generated the anim file (DPaint III, Videoscape, etc.) The last item should indicate to you just how much difference there can be between two anim files depending on which programs generated them. Nearly every format I looked at had a unique chunk or unique data within a common chunk. DPaint III Specifics Another thing Animation Bridge can do for you is strip out excess data from a DPaint III anim file. DPaint III sometimes saves large amounts of data that (I think) have to do with environment (possibly stencils, locked backgrounds or what-have-you). I haven't yet figured out what this extra data is, but stripping it out has absolutely NO affect on the playback of the anim file. The advantage is that the file takes up less space on a disk. One anim file that was tested by Scott Busse during beta-testing was over 900k before being processed by Animation Bridge. After doing a conversion to DPaint III format (effectively "converting" to the same format we started with) the file was just over 700k. Animation Bridge had found and stripped out over 250k of unneeded data! If you try to load an anim file from Videoscape 1.0 into DPaint III you will be presented with an error message. Likewise, AniMagic files will cause problems for DPaint III, although the error encountered is different. Both of these problems are corrected by Animation Bridge. AniMagic Specifics There are two "levels" of compatability that AniMagic expects. I'll explain... If you simply want to chop a frame or two from an anim file, copy an anim from one buffer to another, or most other operations that don't involve using the "special effects" features of AniMagic (referred to as "DVE Effects" in the manual), AniMagic encounters very few problems and will deal quite effectively with any variation of the Anim-5 format. Beyond these simple operations, AniMagic is very demanding as to the structure of the anim file you present it with. Sometimes AniMagic will crash during the processing of a DVE Effect or "hang" for hours on end (if you let it continue). This happens not only with "stranger" variations to the Anim-5 format, it also happens with anim files generated by AniMagic itself. The only variation on the Anim-5 format that seems to work without a hitch in AniMagic is that of Sculpt-Animate 4D (v2.09c, ANIM-5 option) so to correct these problems, the SA4D variation is emulated when you choose "AniMagic" as an output format. The Director Specifics The Director is a good solid program in that when it encounters something within an anim file that it can't deal with, it aborts instead of crashing. What The Director currently expects is a very clean and simple anim file with no extra chunks such as those included in an anim file by Photon Paint 2.0 and DPaint III. I've heard rumours that The Director is going to be upgraded very soon so these problems will be taken care of by the author, Keith Doyle. Until he can get the new version out there, though, Animation Bridge will clean out all the unwanted chunks for you. Movie 2.0 (included with SA4D) Specifics Like The Director, Movie 2.0 expects a very clean and uncluttered anim file. Movie and The Director share a gadget on the Animation Bridge screen because they "have the same taste" in anim files. Animation: Editor (pre - 1.12 release) Specifics Ken Baer at Hash Enterprizes has already updated Animation: Editor and as such the problems I will talk about won't be encountered by anyone having the updated version. I left the "Animation: Editor" gadget in Animation Bridge because I, for one, don't yet have the update and I'm assuming there are others who don't either. Contact Hash Enterprizes for details of how to upgrade Animation: Editor. Until you get your upgrade, you can use Animation Bridge to remove the single problem chunk from an anim file. It seems that some programs write an "extra" ANHD chunk in the first frame of an anim file. This is completely legal to do, just rare. Animation Station Specifics The main problem encountered by Animation Station isn't really a big deal. It's a matter of esthetics. Because Animation Station uses a unique method of designating the x, y offsets of the screen for overscan anim files, all anim files generated by programs other than Animation Station or it's companion utility, AnimBuild, will not be displayed properly. The screen will be shifted to the right and down, leaving a colour zero border on the top and left edges of the screen. Animation Bridge will modify these offsets to faciliate a proper display. There are two other problems encountered by Animation Station. One of these is similar to a problem that DPaint III has with some files, namely that the Source Page X and Y sizes must match the Raster X and Y sizes. This is taken care of also by Animation Bridge. The other problem, which ISN'T delt with by Animation Bridge, is that Animation Station will not properly handle any non-looping animation file. Since I haven't yet worked out an easy method to detect the presence of looping frames (except in Photon Paint 2.0 files) I haven't come up with a reliable way of adding looping frames to an anim. Operation Operation of Animation Bridge is simple: load a file, select an output format, select "Do It". That's it. You're done. Everything else is taken care of by the program. The rest of this chapter is a description of the program and the different ways to access it's functions. Screen Layout The top of the screen has five string gadgets labelled according to the information they will contain when an animation file is loaded. Unlike most string gadgets, these will not let you modify their contents directly. With the exception of the "Filename" gadgets (two of them; one for the "in-file" and one for the "out-file"), if these string gadgets are selected with the mouse a message will appear informing you that the contents of the gadget can't be changed. The "Filename" gadgets being the exceptions to this rule, when selected, will present you with a file requester to help you choose the name of an animation file to load, or a name for the resulting anim file, depending on which gadget you select. More on that in a moment. The bottom of the screen has six gadgets, five for selecting an output format (which will be automatically reflected in the "out-file" name gadget above) and one for starting the job once you've made your selection. In the bottom left corner of the screen you will find the version number and top-centre is the Animation Bridge logo. These are not gadgets, simply images to make the screen easier to look at. Accessing Program Functions Animation Bridge was designed for maximum usage flexibility (MUF). You can chose your favourite method of dealing with the software (mouse and menus, mouse and gadgets, keyboard, or ARexx script) and stick with it throughout most of a session with Animation Bridge. The only exception is that a 'mouse and gadgets' approach doesn't let you quit with an on-screen gadget. This is to prevent accidentally quitting the program before you're finished. Program Functions All functions are accessible from the menus. Each menu item description is followed by the keyboard short-cut, on-screen gadget equivalent and the ARexx syntax for the same function. FILES MENU LOAD ANIM - loads an animation file into memory. The restriction placed on this version of Animation Bridge is that you cannot work with a file that is bigger than the largest chunk of available memory remaining in the system after the program is up and running. Use the "avail" command at any CLI or Shell prompt to find out the size of the largest chunk of RAM in your system. Keyboard Right-Amiga "L" On-Screen Gadget Select the Topmost Filename string gadget (labelled "I"). ARexx 'load ' -------------------------------------------------------------------- INFILE - allows conversion of large anim files from disk so that the size of the anim file can exceed available memory - not yet implemented -------------------------------------------------------------------- CHANGE OUTFILE NAME - When an animation file name is chosen, the outfile name is automatically set to the same name as the original file but with the tag ".XX" appended if no extension such as ".anim" is present, or with the tag imbedded in the name BEFORE the extension if one exists. This helps you later identify the output format you've chosen. The directory in which the new file will be saved is the same as that of the original file. If this naming convention doesn't suit your purposes or if you would like to save the new file to a different directory or disk, the 'out-file' name and path can be changed by selecting this option. A full list of "tags" can be found in the Filename Extensions section of this document. Keyboard Right-Amiga "O" On-Screen Gadget Select the BottomMost Filename gadget (labelled "O"). ARexx 'outfile ' -------------------------------------------------------------------- DO CONVERSION - Starts the process of converting the animation file to a new variation of the Anim-5 format. If a file exists by the same name as the one appearing the the "Filename O" gadget you will be asked if you want to save over it. If the existing filename is protected from deletion you will be asked to select another filename for the save. Keyboard Right-Amiga "D" On-Screen Gadget DO IT ARexx 'convert' -------------------------------------------------------------------- ABOUT - Tells you who we are and where to send your shareware fee. It also tells you who wrote the requester library used by Animation Bridge. Keyboard Right-Amiga "A" On-Screen Gadget None ARexx None -------------------------------------------------------------------- QUIT - Self-explanatory. Keyboard Right-Amiga "Q" On-Screen Gadget None ARexx 'quit' -------------------------------------------------------------------- OUTPUT FORMAT MENU ANIMAGIC - select AniMagic variation of Anim-5. Keyboard Right-Amiga "1" On-Screen Gadget Same name as menu ARexx 'set animagic' -------------------------------------------------------------------- DPAINT III - select DPaint III variation of Anim-5. Keyboard Right-Amiga "2" On-Screen Gadget Same name as menu ARexx 'set dpaint' -------------------------------------------------------------------- ANIMATION STATION - select Animation Station variety of Anim-5. Keyboard Right-Amiga "3" On-Screen Gadget Same name as menu ARexx 'set station' -------------------------------------------------------------------- DIRECTOR/MOVIE2 - Select a variation compatible with either The Director or Movie 2.0 (the latter is a player program included with Sculpt-Animate 4D) Keyboard Right-Amiga "4" On-Screen Gadget Same name as menu ARexx 'set director' -------------------------------------------------------------------- ANIMATION: EDITOR - Select a variation compatible with older versions of Animation: Editor (version 1.11 or earlier) Keyboard Right-Amiga "5" On-Screen Gadget Same name as menu ARexx 'set editor' -------------------------------------------------------------------- AREXX MENU EXECUTE - Brings up a file requester to help you select an ARexx script to execute. Keyboard Right-Amiga "E" On-Screen Gadget None ARexx None (since another script can always be started from within an ARexx script). -------------------------------------------------------------------- FIND AREXX - If you've started a session with Animation Bridge with the intentions of using some of the ARexx functions and you go to select the "ARexx/Execute" menu item only to find it ghosted, simply go to a CLI or shell and start up rexxmast, then come back to the Animation Bridge screen and select "Find ARexx". If ARexx started up alright and is now running, Bridge will find it and un-ghost the "Execute" menu item. -------------------------------------------------------------------- Filename Extentions When an animation file is loaded into Animation Bridge a name very similar to the original is placed in the "Filename O(ut)" gadget. The difference is that a "tag" is added to the name for future identification of the file's Anim-5 output variation. This "tag" will be added to the end of some file names and imbedded in others. How a particular file name will be treated depends on the original name. For example, a name such as "MyAnim" will end up as "MyAnim.DP" if DPaint III was selected as an output variation, while "MyAnim.anim" will become "MyAnim.DP.anim" under the same circumstances. So, where the tag goes depends on whether an "extention" already exists within the original file name. Since filename extensions are, by convention, a few letters preceded by a period (.) Animation Bridge looks for the right-most period in the filename and adds the tag between the period and the left-most portion of the name. If no extention is found Animation Bridge simply adds the tag to the end of the filename. Here is a complete list of the tags used by Animation Bridge: .DP Deluxe Paint III .AM AniMagic .DR The Director and Movie 2.0 (Movie 2.0, as opposed to it's predicessors, WILL play Anim-5 files) .ST Animation Station .ED Animation: Editor v1.11 (or earlier, if there is such a thing) ARexx Scripting for Animation Bridge ARexx scripts can be started from within Animation Bridge by selecting "Execute" from the "ARexx" menu or by using the Right- Amiga "E" keyboard equivalent. An ARexx script can also be started from the CLI, shell or from another program that is capable of starting ARexx scripts. There is no set extension for an ARexx/Animation Bridge script, but I would suggest "rx_ab", just for clarity in case you pass your arexx script files along to others. Here is a summary of the commands Animation Bridge will recognize in an ARexx script: -load loads an animation file -outfile change the name of the output file from the default with an imbedded "tag" identifying the Anim-5 variation -convert start the conversion process -quit stop the program -set choose an Anim-5 variation for the output file. This command must be followed by a space and then the name of the variation you want. The choices are: - animagic - dpaint - station - editor - director Following is a short example of an ARexx script that can be modified and used as a guide for your own scripts: /* test the Animation Bridge / ARexx port */ OPTIONS RESULTS address 'BridgeRxPort' 'load test.anim' 'set animagic' 'convert' 'outfile MyNewAnim.anim' 'load test2.anim' 'set dpaint' 'convert' 'outfile df1:MyOtherNewAnim.anim' 'convert' 'quit' An ARexx script will be impeded in it's execution if you are trying to save over an existing file. If this happens, a small message window will appear informing you of this. The ARexx script will be arrested in it's execution until you answer either "Yes" or "No" to the message in the requester window. If a syntax error exists within a message line that is being sent to Animation Bridge you will be informed. Animation Bridge will cease execution of the script and return to it's normal state. Any file name given in a 'load ' command that doesn't exist will be reported to you and script execution will be halted. Please note that you must use the ADDRESS 'BridgeRxPort' command to tell ARexx where to send the messages. After the final command is sent, if you wish to carry on with sending messages to other applications with ARexx ports, you will have to change the target port again using the ADDRESS command. TIPS FOR MAXIMUM COMPATABILITY Here are a few other things I've learned while moving anim files from one program to another. 1 - After running AniMagic and then quitting, you will need to reboot your computer in order to load an animation into Animation Station. I don't know why this is or which program is causing the problem. What I do know is that while loading an anim file into Animation Station, after AniMagic has been running, the Amiga will crash before the load is complete. 2 - If you want to load an anim file into Photon Paint 2.0 make sure the resolution is 352x480x6 (HAM). 3 - If you want to load an anim file into Animation Station make sure it has looping frames. Otherwise it will crash. 4 - If you are using Videoscape to generate anim files, use Animation Bridge to 'fix' the file so it will be compatible with DPaint III. Then load the file into DPaint III and save it back out. This will translate the file from Anim-3 to Anim-5 and then, if need be, you can use Animation Bridge to take the file into any other program or player. TOLL GATE Animation Bridge is shareware, and of course you know what shareware is by now. If you use this software, especially if you are using it to help you earn money as an animator, please send a $20.00 MONEY ORDER to: Mythra-mations Animation and Software 902 West 17 Ave. Vancouver, BC Canada V5Z-1V4 We'll send you a version that isn't constantly interupted by a message to send money. Sound like a good deal? I thought so, too. Other Contact Information: If you want to report a bug or communicate with us for any other reason you can post messages to Ron Tarrant at the following: RSI-Mindlink in Vancouver BC, Canada (604)576-1214 Usenet a976@Mindlink.UUCP