.TH xanim "" "" "X Application"
.PC "Run animation programs under X"
\fBxanim [ [+|-]\fIoption\fB ...] \fIanimfile\fB [ [ [-\fIoptions \fB] \fIanimfile \fB] ... ]\fR
.PP
.B xanim
displays various types of animations in an X11
environment.
The intent is to make it fairly easy to add new animation types as
they are developed.
.PP
.B xanim
can display the following types of animation files:
.IP \fB1.\fR 0.3i
FLI animation files.
.IP \fB2.\fR
IFF type 3, 5, J, and l (lower-case `L') animation files.
.IP \fB3.\fR
IFF color cycling.
.IP \fB4.\fR
IFF images (EHB included, but HAM shown as 332).
.IP \fB5.\fR
GIFs, including those with multiple images.
.IP \fB6.\fR
A text file that lists GIFs and the order in which to shown them.
.IP \fB7.\fR
Any combination of the above.
.SH "Command-Line Options"
.B xanim
recognizes the following command-line options.
With the exception of options
.BR f ,
.BR j ,
and
.BR l ,
an `+' turns an option on, and an `-' turns it off.
.IP \fBb\fR 0.3i
Uncompress animations up front.
.B xanim
automatically uncompresses GIF files.
It does not support uncompress uncompressing IFF type J animations.
Note that this flag can eat up a lot of memory.
.IP \fBc\fR
Tell
.B xanim
that an IFF type 3 or 5 animation is non-looping and therefore needs
different treatment.
If an IFF type 3 or 5 animationlooks right the first time
but is distorted on the second loop,
use this flag.
.IP \fBd\fR
Debug.
.B xanim
prints to the standard error lots of text that describes what it is doing.
.IP \fBf\fIdelay\fR
Add fading between animation files.
The color map fades to black in 16 frames.
.I delay
is the delay between frames.
.BR \-f0
turns off fading.
.IP \fBi\fR
Scale the image vertically by half.
.B xanim
does not display odd-numbered display lines.
.IP \fBj\fImilliseconds\fR
Delay
.I milliseconds
between frames.
The default is 17 milliseconds,
unless specified inside the animation itself.
.IP \fBl\fItimes\fR
Loop
.I times
before moving on to the next file.
The default is one.
.IP \fBo\fR
Turn on optimizations.
Turning this off is useful only if you are buffering the animation
file and wish to run it backwards.
The default is on.
.IP \fBr\fR
Turn off color cycling for IFF cycling images.
.IP \fBs\fR
Prevent window from resizing to match image size.
Window is the size of largest image.
Default is on.
.IP \fBu\fR
When single stepping,
the animation is played until image is updated or changed.
A new cmap is not considered an update.
Default is on.
.IP \fBv\fR
Verbose mode.
.B xanim
tells you the size of images, number of deltas, etc.
.SH "Keyboard Commands"
.B xanim
recognizes the following commands when typed from the keyboard.
.IP \fBg\fR 0.3i
Move to animation file after a cycling IFF image.
.IP \fBq\fR
Quit.
.IP \fBr\fR
Restore original color once stopped.
.IP \fBs\fR
Stop color cycling, if started.
.IP \fB<space>\fR
Toggle:
start/stop animation.
.IP \fB,\fR
Go back one frame within file.
.IP \fB.\fR
Go forward one frame within file
.IP \fB<\fR
Return to beginning of previous file.
.IP \fB>\fR
Proceed to beginning of next file.
.SH "Varieties of Animation Files"
The following gives some details about the formats of animation files that
.B xanim
recognizes.
.IP "\fBFLI Animations\fR"
FLI is a format produced by Autodesk Animator for the PC.
Support is for 320\(mu256 images.
The file consists of a series of images and deltas, (a
.I delta
being data that generates the next image given a previous image)
to be played in sequence.
An FLI animation can also change the color map during animation.
.IP "\fBIFF Animations and Images\fR"
IFF files were developed for the Amiga.
They can also include sound chunks, which
.B xanim
ignores.
.IP
Animation files are double-buffered.
The deltas refer not to the
previous image, but the image that preceded the previous.
.B xanim
can handle compress modes
.BR 3 ,
.BR 5 ,
and
.B J
(of the known types
.BR 1 ,
.BR 2 ,
.BR 3 ,
.BR 4 ,
.BR 5 ,
and
.BR J ).
The type-J compression usually has an ANSI chunk at the end
that sets the order in which the deltas are to be applied.
Deltas can be used more than once.
IFF animations can be looping and non-looping.
``Looping'' means that the last two deltas
produce images that are the same as the first two images.
To loop continuously, the animation jumps back to the second image,
instead of to the beginning.
To loop non-looping animations, you must jump to the first
image.
There is no way to know ahead of time whether an animation loops or not,
so the default is to loop.
If you have a non-looping animation, use the switch
.BR \-c .
.IP
The Amiga has a couple of weird display modes, EHB and HAM.
.B xanim
fully supports EHB animations.
HAM can produce 4,096 colors (four bits each for red, green, and blue);
.B xanim
displays HAM animations as 332 (three bits each for red and green,
and two bits for blue).
Surprisingly enough, the appearance is not too bad.
.IP
IFF supports a color-cycling chunk (or chunks)
that specifies color ranges to be cycled at specified intervals.
Because there's no obvious end to this type of animation,
.B xanim
displays it continually until you press the key `G'.
.IP
.B xanim
also supports IFF images using
either no compression or compression type 1.
.IP "\fBGIF Images/Animations\fR"
A GIF file consists of a screen color map followed by a series of images,
each of which can have its own color map.
The images are not required to be at the origin,
and can be any size smaller than the screen size.
This permits GIF animations to update only the part of the screen that changes,
which permits them to be smaller yet run smoothly.
.B xanim
automatically uncompresses GIF images when read in.
.SH "Text Files"
.B xanim
can read an ASCII text file that names GIF files to display.
You can also specify the order in which to display them.
Comments are not supported.
The following diagram shows the layout of such a file:
.DS
.ta 0.5i 1.5i
	\fBtxt91\fR	\(<- Header so XAnim knows what kind of file it is
	\fB4\fR	\(<- Number of GIF filenames that follow
	\fBa.gif\fR	\(<- GIF file to be read in: first file is number 0
	\fBb.gif\fR
	\fBc.gif\fR
	\fBd.gif\fR
	\fB6\fR	\(<- Number of frames that follow
	\fB0 1 2 3\fR	\(<- Display images in this order
	\fB2 1\fR
.DE
.PP
The the above text file displays the GIF files in the following sequence:
.DS
.B
	a.gif
	b.gif
	c.gif
	d.gif
	c.gif
	b.gif
.DE
.PP
Most likely, this animation will be looped, and the last
.B b.gif
will flow smoothly into
.B a.gif
as it starts over.
.SH Examples
To display a single animation, use the command:
.DM
	xanim iff3.anim
.DE
.PP
To display a nonlooping IFF animation, type:
.DM
	xanim +c iff3.anim
.DE
.PP
To display file
.B A.fli
three times,
files
.B B.anim
and
.B C.movie
twice each, and file
.B D.fli
once before repeating, type:
.DM
	xanim -l3 A.fli -l2 B.anim C.movie -l1 D.fli
.DE
.PP
or:
.DM
	xanim +l3 A.fli +l2 B.anim C.movie +l1 D.fli
.DE
.PP
To fade to black after
.BR A.fli ,
.BR B.fli ,
and
.BR C.fli ,
but not after
.BR D.fli ,
type:
.DM
	xanim +f3 A.fli B.fli C.fli +f0 D.fli
.DE
.PP
To run
.B A.anim
very slowly, type:
.DM
	xanim +j50 A.anim
.DE
.PP
To display title image for a while, then fade into an animation at
normal speed, type:
.DM
	xanim +f3 +j200 title.gif +j0 anim.gifanim
.DE
.PP
To show the first animation unbuffered at half height and the second
animation buffered at full height, type:
.DM
	xanim +i first.anim -i+b second.anim
.DE
.PP
or:
.DM
	xanim +i first.anim -i +b second.anim
.DE	
.PP
To display a series of GIF files, type any of the following commands:
.DM
	xanim im_0.gif im_1.gif im_2.gif ... im_36.gif
	xanim im_*.gif
	xanim im.gifanim
.DE
.PP
where
.B im.gifanim
is one file composed of
.B im_0.gif
through
.BR im_36.gif .
.SH "See Also"
.B
X applications
.R
.SH Notes
.II "Morrison, Jerry"
.II "Shaw, Steve"
.B xanim
uses the public-domain unpacker routine written
by Jerry Morrison and Steve Shaw.
See the source module
.BR unpacker.c .
.PP
.II "Podlipec, Mark"
.B xanim
was written by
Mark Podlipec.
Copyright \(co 1992 by Mark Podlipec.
.PP
This software may be freely copied, modified and redistributed
without fee provided that this copyright notice is preserved
intact on all copies and modified copies.
There is no warranty or other guarantee of fitness of this software.
It is provided solely ``as is''.
The author disclaims all
responsibility and liability with respect to this software's usage
or its effect upon hardware or computer systems.
