Arexx Scripting for Time Machine

Time Machine is written entirely in Arexx, with the `Gui` program being used to construct the toolbars and menus. Pressing a button or choosing a menu item runs an Arexx script which in most cases just saves some information about filenames, postions, script names etc.

Because the program uses multiple scripts, rather than all being inside one master script all the variables are stored on the cliplist, so that any script can get access to them. This means that there is information automatically stored by TM that you can use in your own scripts.

The Cliplist

To use these variables requires a knowledge of the getclip() and setclip() commands, which are as follows:

At the start of Time Machine you are prompted for the total number of frames in your project. The code for this looks like:
-----------------------
requestnumber `"Total Frames"` 1
parse var result frames
if rc~=0 then exit
call setclip(`TM_TotalFrames`,frames)
-----------------------

Line 1 is the standard IFX requester for a number, with the default being 1.
Line 2 examines the user input and makes a variable called "frames" which is the number supplied.
Line 3 says exit if the user cancels.
Line 4 is the interesting bit. The syntax for the setclip command is setclip(<clipname>,[value]), so we have made a variable on the cliplist whose name is TM_TotalFrames, and whose value is the amount entered in the number requster. Please remember the following; the clipname is CaSe SeNsItIvE, and must be enclosed in quotes. Also the setclip() command must be preceeded by "call" command.

This variable is accessible from scripts by use of the getclip() command.  For example, the final load/save/render loop in Time Machine starts:

do i = 1 to getclip(`TM_TotalFrames`)

which means repeat the code that follows for as many times as there are frames in the project. So to use the variables on the clip list replace any variable in your script with getclip(`Clipname`).

How is this helpful?

Below is a list of variables that Time Machine stores that may be of use:

TM_TotalFrames=Number of frames in the project
TM_Renderframe=The frame number currently being processed by the render script.
Example: The animation of the fire hook is generated by the line

hook fire increment getclip(`TM_Renderframe`) file getclip(`TM_FireScript`LayerNum)

which means that the increment variable is equal to the current frame number.

TM_Loadpath=The last directory used to load a layer
TM_TotalLayers=The number of layers in the project

No, really, how is this helpful??

Well, let`s consider the following example. Imagine that we have a project with two layers of the same size, and we want to "wipe" the top layer off to the right in exactly the same number of steps as there are frames. What do we need to know? Firstly, how far the buffer has to travel, and secondly how long it has to do it. I`ve chosen the example of two identically sized buffers to avoid any offset distance problems. The top layer starts at layer offset (0,0) and will end up at layer offset (bufferwidth,0).

To get the buffer size we can use the getmain command;
getmain
parse var result name width height

If we write out the calculation that needs to be done on each frame longhand we get:

Distance travelled across the buffer on frame x = width of buffer*(current frame-1)/(total frames-1)
(I`m using the frame number -1 so that the buffer starts at 0. On Frame 1 distance=width*0/totalframes-1=0)

As we`ve seen above the current frame is stored as the clip TM_Renderframe, and the total frame count is stored as TM_TotalFrames, so our final script looks like:

-----------------------
/***************
Wipe Right script for Time Machine
**************/
options results
getmain
parse var result name width height
layeroffset (width*(getclip(`TM_Renderframe`)-1)/(getclip(`TM_TotalFrames`)-1)) 0
----------------------

Once this script is written it is a case of re-thinking the maths and slightly editing it to also calculate a wipe from right to left, top to bottom etc., and these scripts will work with any project where the layer being moved has the same dimensions as the background, and starts from the offset of (0,0). (or, more precisely, it will start at 0,0 when you run the script).

Once this concept is grasped it`s only a short step to having scripts to fade a layer out/in across a project and so on.

Hopefully this has given you an insight into what is possible with some simple scripting within Time Machine. Happy typing!