ISL.doc - Copyright (c) 1992 John T. Grieggs, last modified 10-28-92 Current ISL version - 1.0. ISL, the Imagine Staging Language, is a language created to make the generation and manipulation of Imagine 2.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). Back? Good. When you first create a Project in Imagine 2.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 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 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 CAMERA "CAMERA" POSITION FRAMES 1 1 XYZ 160.000000 -320.000000 160.000000 ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 0.000000 SIZE FRAMES 1 1 XYZ 320.000000 640.000000 233.333328 GLOBALS "GLOBALS" ACTOR FRAMES 1 1 BRUSH "" 0 BACKDROP "" 0 AMBIENT RGB 0.000000 0.000000 0.000000 HORIZON RGB 0.000000 0.000000 0.000000 +ZENITH RGB 0.000000 0.000000 0.000000 -ZENITH RGB 0.000000 0.000000 0.000000 FOG BTL 0.000000 0.000000 0.000000 FOG RGB 0.000000 0.000000 0.000000 STARFIELD 0.000000 TRANSITION 0 SKYBLEND 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 from the far left-hand column of the Action editor entry (CAMERA "CAMERA" or GLOBALS "GLOBALS", 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 and MAXFRAMES clause, 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" ACTOR FRAMES 1 40 NAME "Portal.imp/objects/Portal" CYCLE 0.000000 0.000000 TRANSITION 0 ACTOR FRAMES 41 60 NAME "Portal.imp/objects/Prtal" CYCLE 0.000000 0.000000 TRANSITION 0 ACTOR FRAMES 61 100 NAME "Portal.imp/objects/Prtl" CYCLE 0.000000 0.000000 TRANSITION 0 POSITION FRAMES 1 40 PATH "PATH" ACCEL 0 0.000000 DECEL 0 0.000000 POSITION FRAMES 41 100 XYZ 0.000000 -1000.000000 0.000000 ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 0.000000 ALIGN FRAMES 2 20 XYZ 0.000000 180.000000 0.000000 ALIGN FRAMES 21 39 XYZ 0.000000 360.000000 0.000000 SIZE FRAMES 1 1 XYZ 32.000000 32.000000 32.000000 Again, we start with the object name, 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" ACTOR FRAMES 1 12 NAME "Emerald.imp/objects/emerald2.obj" CYCLE 0.000000 0.000000 TRANSITION 0 POSITION FRAMES 1 1 XYZ 0.000000 0.000000 0.000000 ALIGN FRAMES 1 1 XYZ 0.000000 0.000000 3.750000 SIZE FRAMES 1 1 XYZ 5.000000 5.000000 6.500000 EFFECT 1 FRAMES 1 12 Rotate2.0 "Effects/Rotate2.0" ZAXIS DEGREES 45.000000 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 Rotate2.0 - 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 the extra stuff in the distribution? Oh, yeah. frames.c is 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. ArexxISL.lha contains two sample Arexx scripts written by one of my beta testers to manipulate ISL programs. Read his readme files to see what they are and how to use them.