Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d3xx/d359/abridge.lha/ABridge/ABridge.doc

Text File | 1990-06-12 | 24KB | 633 lines

                           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 <animfile.name>'


--------------------------------------------------------------------
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 <path:animfile.name>'


--------------------------------------------------------------------
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 <filename>' 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     [phone]

Usenet                             [e-mail]