ScriptX Animation Library
Design Document
Description:
The Animation class is an abstract protocol for playing named animation
sequences.
Each Animation object has a set of named sequences it knows how to play.
You can ask it for the names of its actions, tell it to play an action,
find out if an action is playing, wait till an action is finished, cancel
an ongoing action, pause and resume animation, and get notification of actions
starting, flipping frames, and finishing.
Purpose:
The Animation class does not dictate any particular kind of animation, it
just serves as an interface between media specific drivers and title specific
behavior. It hides the drivers from the behavior, so animation of many different
types can play together. The abstract Animation class is the least common
denominator across many different kinds of animation, and does not implement
any presentation itself.
There are many Animation media subclasses that implement different forms
of animation using various media types and algorithms. Each animated object
must inherit from exactly one of those. There are also many optional mixins
that implement higher level behavior, and animated objects can inherit from
any of these they need, as well as title specific mixins that serve as glue
between the title and arbitrary plug-in animations.
ScriptX titles can dynamically import any type of animation at run time,
by binding to the Animation media subclass required to play the particular
media type, and mixing in title specific Animation subclasses, that allow
it to interoperate with other objects in the title.
Usage:
The interface to instantiating new animation objects is consistant across
all media types. There is one required key argument passed into init, which
is "media:", a keyed list (or HashTable), with certain key/value
pairs defined in it, depending on the media type. There is one required
key that tells the name of the required Animation media subclass, that knows
how to interpret the rest of the keys.
Instead of distributing actual instances of Animation subclasses in accessory
containers, you distribute the media table, which contains the name of the
required Animation subclass, and all the information necessary to create
the animation. You do not want to distribute actual instances of the Animation
media subclass in the title container, because then it will be too late
for titles importing the objects to mix other Animation subclasses in with
the Animation media subclass. Instead, you supply the data and the driver,
so titles importing the animations have a chance to mix their own behaviors
in with the drivers at run time before instantiating the animations.
The anim.sxl animation library contains a set of Animation media subclasses,
but the title containers with animation media can contain their own copy
of the required media subclass, to be used in case it's not already defined
in the Animation module. We bind to the Animation media subclass by name,
and check to see if it's already defined in the Animation module first,
only loading it from the container if necessary. This is so if you have
several instances that use the same drivers, they will all share the same
code, and if you have custom drivers that implement certain types of animation
more efficiently (like taking advantage of accellerators), you can load
those in before importing animations, and they will run faster. Dynamically
binding by name to the media class at runtime also allows you to develop
authoring tools by defining editable media driver subclasses that let you
create new animations and save them out as media tables, to be used with
simpler play-only drivers distributed in the animation accessory containers
to be used by customers.
It's good practice to store lower level built-in ScriptX objects in the
animation media table, like bitmaps, arrays, and keyed lists, instead of
instances of your own classes. That way you have more flexability to change
your own classes, and your persistant objects will not be obsoleted because
their classes change from under them. Your Animation media subclasses can
rehydrate those low level object into instances of your own specialized
classes at run-time, dynamically binding to those classes by name, so you
can upgrade them at a later time, without having to rebuild and replace
all your animation containers. This can also result in smaller storage containers
because you're storing fewer high level objects, and just storing the code
to create those objects instead (algorithmic compression).
To be done:
We need conventions for keys and values! The animation library is a start,
but needs to be formalized so other media types can do the same thing and
be handled properly. An accessory container should be a keyed list with
certain well-known keys in it.
Right now I'm using a key called @media to hold the animation media table,
which itself is a keyed list with a key identifying the name of the animation
media subclass, that knows how to deal with rest of the keys. I think the
key in the animation accessory container should be renamed @animationMedia
to be more specific about the format, and we can define other accessory
keys like @bitmapMedia, @audioMedia, or @playerMedia, etc, that have their
own self identifying formats and drivers.
Building the animation library and demos:
Building Overview:
First you must make the animation library by loading "makeanim.sx".
That will make a library container called "anim.sxl". After it
compiles, you must quit ScriptX before building the demos. Next, you may
build the demos of the various animation media subclasses, by loading "makedemo.sx",
or loading the individual "mk*.sx" files in the "demos"
folder. Those will make title containers in the anim directory that you
can load into the Kaleida Media Player, to demostrate the animations.
Because they are so large, all of the media may not be installed or included
with the distribution, so you may not be able to rebuild all of the animation
demo title containers. But the ScriptX files that build them are included
so you can see how they work.
Building the "anim" library:
Load "makeanim.sx" from the "anim" directory into ScriptX,
and it will build "anim.sxl", the animation library, in that same
directory.
Building the animation demos:
Load "makedemo.sx" from the "anim" directory into ScriptX,
and it will build the animation demos from the "anim/demos" directory,
as title containers in the "anim" directory.
Running the animation demos:
Load the title containers "dude.sxt", "eye.sxt", or
"count.sxt" from the "anim" directory into the Kaleida
Media Player, and press the words at the top of the windows to see the animations.
You can drag the animations around with the mouse.
Building the director importer animation demos:
Note that before building, you must have the "dtk" and "dirimp"
directories installed in the right place, the same directory as the ScriptX
application. Copy the "anim.sxl" library from the "anim"
directory to the "dtkanim" directory. Load "makedemo.sx"
from the "dtkanim" directory into ScriptX, and it will build the
musical instrument animation demos from the "anim/demos" directory,
as title containers in the "dtkanim" directory. Copy the title
containers "piano.sxt", "trumpet.sxt", and "violin.sxt"
from the "dtkanim" directory into the "anim" directory.
Running the director importer animation demos:
Load the title containers "piano.sxt", "trumpet.sxt",
or "violin.sxt" from the "dtkanim" directory into the
Kaleida Media Player, and press the words at the top of the windows to see
the animations. You can drag the animations around with the mouse.
Source Code and Media for the Animation Library:
The source code to the latest animation library is available here: anim.sit.Hqx
And the Director Toolkit animation importer demo is here: dtkanim.sit.Hqx
Here are all the files in the anim and animdtk directories, and a short
explaination of their purpose:
anim/makeanim.sx
Load this to build the anim.sxl library.
anim/anim.cls
Defines the abstract Animation class.
anim/actorm.cls
Media class that implements each frame as a group of bitmaps, AnimationActorMedia.
Based on Warren's actor animation class. Good if you have to re-use lots
of bitmaps in each frame, in different positions. Could be smarter about
re-using presenters.
anim/bitmapm.cls
Media class that implements each frame as a bitmap. This is probably the
simplest and easiest kind of animation, though maybe not the most memory
efficient. Dumb and fast.
anim/filmm.cls
Media class that implements all frames as one tall bitmap, like a strip
of film. This is quite memory efficient, since you only have one bitmap
around instead of zillions! The frames of the single tall bitmap are used
by all of the animation actions. Need a related class that represents each
action as a filmstrip, so each can be stored separately, and you don't need
to load all possible frames in at once.
anim/playerm.cls
Media class that implements animations of players driven by their own clock.
When you start an action, it starts the player, and it keeps going until
the player hits the end of the action, however many frames that takes.
anim/pfarmm.cls
Media class that implements playfarm character animations. Ideosynchratic
playfarm behavior, and generic stuff that still needs to be factored out,
like the action queue.
anim/scorem.cls
Media class that implements animations of director score players. This would
better be done as one score player per action, because it's slow to seek
around in score players to play actions, the way this does. Need to modify
the animimp.sx importer to do this.
anim/soundm.cls
Mixin to play a sound and loop an action until the sound's over. Useful
for miming to music (nillie vanilee would love this mixin).
anim/state.cls
Mixin that implements a clickable state machine. Neat way to make specify
interactive behaviors. Needs to be more general, though.
anim/shimmer.cls
Mixin to randomly slow actions (to make playfarm flowers shimmer slowly).
Bizarre but re-useable.
anim/animdemo.cls
Class that implements animation demo, a window with buttons to animate each
action.
anim/mediaimp.sx
Utilities for importing media.
anim/animimp.sx
Classes for importing labeled director scores an named animation sequences,
using the DTK. This is a great example of the cool stuff you can do with
the DTK, interoplating specially formatted director files into custom ScriptX
objects. In this case, you just make a score, containing your animation
action sequences with a label at the beginning of each one, and this will
import them, composite the layers together into a single shrink-wrapped
bitmap, and put it together into the proper format for the AnimationBitmapMedia
class.
anim/anim.sxl
The animation library. This contains the Animation class and a bunch of
animation media subclasses, optional mixins, utilities for importing media,
and a demo class.
anim/makedemo.sx
Load this to build the demos of the animation media classes.
anim/demos
This folder holds the builders and media for the animation demos.
anim/demos/mkcount.sx
Make the counting hand animation demo, that uses the AnimationPlayerMedia
class to play a quicktime movie of a counting hand.
anim/demos/mkdude.sx
Make the playdoh dude head animation demo, that uses the AnimationFilmMedia
class to spin the dude's head.
anim/demos/mkeye.sx
Make the eyeball animation demo, that uses the AnimationBitmapMedia class
to roll the eyeball around.
anim/demos/count.mov
Flattened quicktime movie of a counting hand.
anim/demos/dudefilm.bmp
Tall bitmap with frames of a spinning playdoh dude's head.
anim/demos/eye
A folder full of eyeball bitmaps.
anim/count.sxt
The counting hand animation demo. You can load this into the KMP.
anim/dude.sxt
The playdoh dude head animation demo. You can load this into the KMP.
anim/eye.sxt
The spinning eyeball animation demo. You can load this into the KMP, too!
dtkanim/makedemo.sx
Load this to build the demos of the Animation classes using the Director
Toolkit.
dtkanim/demos
This folder holds the demos of the Animation class and the DTK.
dtkanim/demos/director
This folder holds the director files that are imported as animations using
the DTK.
dtkanim/demos/mkdirect.sx
Load this to build the piano, trumpet, and violin animation demos. You must
have the Director Toolkit installed (including the folders dtk and dirimp
in the folder where ScriptX starts up.)
dtkanim/piano.sxt
The piano animation demo. You can load this into the KMP.
dtkanim/trumpet.sxt
The trumpet animation demo. You can load this into the KMP.
dtkanim/violin.sxt
The violin animation demo. You can load this into the KMP.