ISL.doc - Copyright (c) 1994 Grizzly Bear Labs, last modified 11-01-94

ISL, the Imagine Staging Language, is a language created to make the
generation and manipulation of Imagine 3.0 staging files a whole lot
easier.  If you have ever used the Action editor in earnest, you know
that certain types of operations are easy (such as adding a single
light) while others are not (such as adding more frames and causing
your existing objects to appear in them).

ISL provides an alternative interface to the Action editor.  With ISL,
you can create your stage using the Stage and Action editors as needed,
then convert it to a fairly straightforward ASCII format, edit it as
desired using your favorite text editor, then put it back!  This is of
course the simplest way of using ISL - you could also create stages
programatically.  I have done this myself.

To use ISL productively, it is first necessary to understand a bit about
how Imagine works.  Quite a bit.  I would not attempt to use this package
if you are not comfortable with Imagine.  If you are struggling, I would
recommend that you purchase Steve Worley's excellent book on the topic,
"Understanding Imagine 2.0", read it, then come back (plug).  Even though
it doesn't support Imagine 3.0 directly, it is still highly relevant.

Back?  Good.  When you first create a Project in Imagine 3.0, Imagine
creates a staging file in your whatever.imp directory.  This staging
file, run through the ISL de-compiler destage, looks like this:

	STAGE
	MAXFRAMES 1
	LOOP 0

The command to generate this file or one like it is:

	destage binarystage asciistage

where binarystage is the Imagine staging file and asciistage is where you
want to put the ISL.

The ISL compiler will indeed eat this simple stage format.  Let's say you
just want to add some frames.  You would then have something like this:

	STAGE
	MAXFRAMES 100
	LOOP 0

The command to make this into a valid Imagine stage is:

	restage asciistage binarystage

where asciistage is your modified ISL source file and binarystage is where
you want to put the new Imagine stage.  A word of caution:  it never hurts
to make a backup copy of a staging file before stomping it!

That was too easy.  Onto ISL complexity level two.  :-)  If you bring up the
Action editor and save the stage, without touching it, it will magically
grow into something like this:

	STAGE
	MAXFRAMES 1
	LOOP 0

	CAMERA "CAMERA" LAYER 0
	POSITION FRAMES 1 1 XYZ 160. -320. 160. VELOCITY 1. 1. SPLINE
	ALIGN FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1.
	SIZE FRAMES 1 1 XYZ 320. 640. 233.333328 VELOCITY 1. 1.

	GLOBALS "GLOBALS" LAYER 0
	ACTOR FRAMES 1 1 BRUSH "" 0 BACKDROP "" 0 AMBIENT RGB 0. 0.
	0. HORIZON RGB 0. 0. 0. +ZENITH RGB 0.
	0. 0. -ZENITH RGB 0. 0. 0. FOG BTL
	0. 0. 0. FOG RGB 0. 0. 0.
	STARFIELD 0. TRANSITION 0

Note the addition of a CAMERA clause and a GLOBALS clause.  Some detail is
called for at this point.  ISL sentences generally correspond one-for-one
to Action editor entries.  There will be one line containing the name and
layer from the far left-hand column of the Action editor entry (CAMERA
"CAMERA" LAYER 0 or GLOBALS "GLOBALS" LAYER 0, etc.) followed by one line
for each line or line segment in the Action editor.

So, for this simple stage, we have three clumps - the stagehdr, containing
the STAGE, MAXFRAMES and LOOP clauses, the CAMERA clump, containing the name
clause, a position clause, an alignment clause, and a size clause, and the
globals clump, containg the name and the actor info.

Here is an ISL object entry, showing what happens when you swap three
physical objects while changing their position and alignment:

OBJECT "PORTAL" LAYER 0
ACTOR FRAMES 1 40 NAME "Portal.imp/objects/Portal" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
ACTOR FRAMES 41 60 NAME "Portal.imp/objects/Prtal" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
ACTOR FRAMES 61 100 NAME "Portal.imp/objects/Prtl" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
POSITION FRAMES 1 40 PATH "PATH" ACCEL 0 0. DECEL 0 0.
POSITION FRAMES 41 100 XYZ 0. -1000. 0. VELOCITY 1. 1. SPLINE
ALIGN FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1.
ALIGN FRAMES 2 20 XYZ 0. 180. 0. VELOCITY 1. 1.
ALIGN FRAMES 21 39 XYZ 0. 360. 0. VELOCITY 1. 1.
SIZE FRAMES 1 1 XYZ 32. 32. 32. VELOCITY 1. 1.

Again, we start with the object name and layer, then follow it with one ISL line
for each Action editor line or line segment.  Note that there are two types of
POSITION line here - the first follows a path "PATH", and the second is
a tween position.  This example is from my flying Portal logo anim.

Here is another ISL object entry, showing an object with a SPFX clause:

OBJECT "EMERALD" LAYER 0
ACTOR FRAMES 1 12 NAME "Emerald.imp/objects/emerald2.obj" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
POSITION FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1. SPLINE
ALIGN FRAMES 1 1 XYZ 0. 0. 3.750000 VELOCITY 1. 1.
SIZE FRAMES 1 1 XYZ 5. 5. 6.500000 VELOCITY 1. 1.
EFFECT 1 FRAMES 1 12 Rotate20 "Effects/Rotate20" ZAXIS DEGREES 45.

Each Special Effect has it's own syntax.  Use EFFECT 1 for SF/X 1, EFFECT 2
for SF/X 2.  The individual syntax for each effect is documented in ISL.BNF.
Note that an effect is actually recognized by the fifth word, which in this
case is Rotate20 - this following clause is the filename in quotes, so that
your effects can live anywhere.

I think this ought to be enough to get started using ISL.  The actual syntax
of the language is documented in the included ISL.BNF file.  The easiest way
to get started would probably be to try destage-ing, modifying, and restage-
ing your own files.  I'd stay out of ISL.BNF until you are pretty familiar
with ISL or are stuck.

Hey, wait a minute, what about frames.c?  Oh, yeah.  It's a little stage
generator I whipped up.  It's written in c, and produces a bunch of frames
ready to be averaged together (for motion blur, of course).  Take it not as
an example of sheer programming elegance, but rather as an idea of how to
programmatically generate an ISL stage.