-------------------------------------------------------------------------
| ANIMTOOL is copyright (c) 1991 by Martin Packer. All rights reserved. |
|                                                                       |
| Permission is granted for unrestriced non-commercial use and          |
| distribution by individuals, public domain libraries and BBS's.       |
| With the condition that it must be accompanied by this file.          |
|                                                                       |
| If you find any bugs, have any suggestions for improvements, feel     |
| the urge to send me large quantities of money, or just want to say    |
| hi! Please write to me:                                               |
|                                                                       |
|         Martin Packer                                                 |
|         81B Preston Road                                              |
|         Brighton                                                      |
|         East Sussex                                                   |
|         U.K.                                                          |
-------------------------------------------------------------------------
ANIMTOOL is a utility for stringing a sequence of low-res image files 
together into an animation. It uses delta compression (only storing the 
differences between frames) to reduce the size and increase the playback 
speed of the animation files it generates.

The original command line version of ANIMTOOL came about because I wanted 
to animate some scenes I'd generated using David Buck's DKBTrace Ray-
Tracer. You should find some examples of animated DKBTrace output with 
this program.

There are two versions of ANIMTOOL:

ANIMTOOL.PRG
Is a version with a nice GEM front-end which allows animations to be 
loaded, played, manipulated in memory and saved.

ANIMTOOL.TTP
Is a single pass command line version which can play an animation or 
carry out one of the manipulation operations. Because it only carries out 
one operation at a time (and because the program itself is quite a lot 
smaller), it uses a lot less memory than the GEM version, so it can be 
used to build and play larger animations if memory is getting tight. This 
version can also be renamed ANIMTOOL.PRG and placed in an auto folder, 
where it will attempt to load and play the animation SEQUENCE.TAT in the 
root directory of the boot disk.


               A Quick Guide to the Features of ANIMTOOL:

ANIMTOOL.PRG is controlled from a single full screen dialogue. Here's 
what the various bits mean:

Current Animation:

     Filename:           The name of the current animation. The default 
                         animation file is SEQUENCE.TAT. When you run 
                         ANIMTOOL this file will be loaded if it exists.

     Number of Frames:   The total number of frames in the animation.

     Default Speed:      When you load a new animation into ANIMTOOL.PRG, 
                         the playback speed will be set to the 
                         animation's default value. This is also the 
                         speed it will normally run at when played by 
                         ANIMTOOL.TTP.

     Repeat:             Animations can be set to repeat indefinitely 
                         when played. This is the default setting which 
                         works in the same way as the default speed.

     Load:               Click here to load an animation. If you want to 
                         create a new animation, click here and type the 
                         name into the file selector.

     Save:               Click here to save the current animation.

     Save As:            Click here to save the current animation with a 
                         different file name.


Workspace:

     When you run ANIMTOOL it will grab the largest chunk of memory it 
     can find to use as its workspace. This tells you how many bytes 
     you've used and how much you've got left.


Show Frame Info:

     A "frame" is actually the stored differences between one screen 
     image in the animation and the next. A frame consists of one or two 
     records. If the two screen palettes differ, the frame will contain a 
     palette record. If the screen images are similar, with no large-
     scale differences, then the frame will contain a delta record, which 
     contains only the differences between the images. If the screen 
     images are too dissimilar for a delta record to be worthwhile, the 
     frame will contain a screen dump record, which contains all 32000 
     bytes of the new screen image. By entering a frame number here, or 
     selecting it using the + and - buttons, and clicking on "Show Frame 
     Info" you can find out which records are present in a frame and how 
     many bytes the frame occupies.


Play Animation:

     Clicking here plays the current animation. Press escape at any time 
     to stop.

     Speed:              Selects the playback speed of the animation. The 
                         number here indicates how long each image in the 
                         animation will be displayed for, in VBL's 
                         (vertical blanks - the time taken for the 
                         television/monitor display to be refreshed - on 
                         UK systems, one VBL is 1/50th of a second). With 
                         a complicated animation (where the delta frames 
                         are larger than about 12K) it may not be 
                         possible to play the animation at maximum speed 
                         (1 VBL/frame). It's possible to get an idea of 
                         the maximum playing speed for an animation by 
                         setting the speed to 0. If you do this the 
                         animation will be played at maximum possible 
                         speed without it being sychronised with the 
                         screen refresh. The currently set speed will be 
                         saved as the default speed when you save an 
                         animation.

     To Frame:           If a number is entered here the animation will 
                         only play up to the frame indicated. In 
                         combination with "Pause" this lets you isolate 
                         and view a single frame.

     Repeat:             If "Yes" is selected the animation will repeat 
                         indefinitely when played. This feature should 
                         only be used if the first frame of the animation 
                         contains a dump record (it usually does). If it 
                         doesn't, strange things will happen because the 
                         animation routines assume that the screen starts 
                         off cleared to colour 0 and the first frame (if 
                         it contains a delta record) will depend on this. 
                         The current repeat state will be saved as the 
                         default when you save an animation.

     Pause:              If "Yes" is selected, after playing an 
                         animation, the computer will wait for a keypress 
                         before returning to the control screen.

     Step:               If "Yes" is selected, the computer will wait for 
                         a keypress between each frame of the animation.


Add Degas Image Frame:

     Click here to add the indicated degas image to the animation.

     FileName:           Click here and select the file containing the 
                         image you want to append to your animation.

     Dump Frame:         When "Add Degas Image Frame" is selected, 
                         ANIMTOOL will usually try to generate a delta 
                         record for the new image. You can force a screen 
                         dump record to be generated by selecting this 
                         button.


Add Loop Frame:

     Usually the animation will progress in sequence from one image to 
     the next. This feature allows you to build loops into your 
     animation. Loop frames can be used to repeat short sequences, repeat 
     the whole animation or repeat (effectively pause on) a single frame. 
     A loop frame is the same as any other frame. A delta (or screen 
     dump) record and possibly a palette record must be generated holding 
     the differences between the current last image in the animation and 
     the one you're looping to. Animation loops can be 'nested' inside 
     one another to any depth. The "dump frame" button has the same 
     effect when adding loop frames as with image frames.

     Loop To:            Select the frame you wan't to loop back to here.

     Loop Count:         Select the number of times the animation should 
                         loop back before continuing. This number should 
                         be one less than the number of times you want 
                         the loop repeated (it will have played once 
                         already). If you enter a count of 0 the looping  
                         will continue indefinitely.


Delete Last Frame:

     Clicking here removes the last frame from the animation.



ANIMTOOL.TTP can do everything that ANIMTOOL.PRG can except deleting the 
last frame. As mentioned earlier, it uses less memory than ANIMTOOL.PRG 
but it can only carry out one operation per pass. So it's a pretty slow 
way to do things if you're loading the animation from a floppy disk each 
time. I usually write a CLI batch file which uses ANIMTOOL.TTP to build 
my animations.

Usage: ANIMTOOL <filename> <options>

Options:

     /H              Display help screen.
     /I<filename>    Degas (PI1) image to append.
     /S<speed>       Playback speed (VBLs/frame).
     +/-R            Repeat/don't repeat animation.
     /L<frame no.>   Append a loop back to this frame
     /C<count>       Used with /L to define the loop count
     /D              Force new frame to be a screen dump

If filename is not given the default SEQUENCE.TAT is used.

