R T A G Ray Tracing Animation Generator A "shareware" program Phillip H. Sherrod Member, Association of Shareware Professionals (ASP) RTAG is a program to facilitate the generation of ray traced animations. RTAG is not a ray tracing program; rather, it enables you to generate the appropriate position of objects to produce an animation using the ray tracing program of your choice. RTAG compiles a programming language designed for animation generation. This programming language contains full arithmetic expressions, conditional control, looping, I/O, and a rich set of library functions including spline path generation. The output of RTAG is a set of files that can be used to drive ray tracing programs such as POV-Ray, or other ray tracers, to produce an image for each frame. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Ray Tracing Driver Files . . . . . . . . . . . . . . . . . 1 1.2 Files Produced by RTAG . . . . . . . . . . . . . . . . . . 3 1.3 Auxiliary Programs . . . . . . . . . . . . . . . . . . . . 4 2. Running RTAG . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1 Command Line Options . . . . . . . . . . . . . . . . . . . 6 2.2 The RTAG Animation Control File . . . . . . . . . . . . . . 7 2.3 Arithmetic and Logical Expressions . . . . . . . . . . . . 8 2.3.1 Numeric Constants . . . . . . . . . . . . . . . . . . . 9 2.3.2 Built-in Constant . . . . . . . . . . . . . . . . . . . 10 2.4 Built in Functions . . . . . . . . . . . . . . . . . . . . 10 2.4.1 Notes on the SPLINE and LINEAR Functions . . . . . . . 13 3. The Animation Control Language . . . . . . . . . . . . . . . . 15 3.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.2 Basic Statement Syntax . . . . . . . . . . . . . . . . . . 15 3.3 Declaration of Variables (The VAR Statatement) . . . . . . 15 3.4 Output File Declarations . . . . . . . . . . . . . . . . . 17 3.5 Assignment Statement . . . . . . . . . . . . . . . . . . . 18 3.6 IF Statement . . . . . . . . . . . . . . . . . . . . . . . 18 3.7 WHILE Statement . . . . . . . . . . . . . . . . . . . . . . 19 3.8 DO Statement . . . . . . . . . . . . . . . . . . . . . . . 19 3.9 FOR Statement . . . . . . . . . . . . . . . . . . . . . . . 20 3.10 BREAK Statement . . . . . . . . . . . . . . . . . . . . . 20 3.11 CONTINUE Statement . . . . . . . . . . . . . . . . . . . . 21 3.12 STOP Statement . . . . . . . . . . . . . . . . . . . . . . 21 3.13 WRITE Statements . . . . . . . . . . . . . . . . . . . . . 21 3.14 SUBCHAR Statement . . . . . . . . . . . . . . . . . . . . 22 3.15 NEXTFRAME Statement . . . . . . . . . . . . . . . . . . . 23 3.16 EPILOG Statement . . . . . . . . . . . . . . . . . . . . . 23 3.17 Self-continuing Batch Files . . . . . . . . . . . . . . . 23 3.18 Auxiliary Data Files . . . . . . . . . . . . . . . . . . . 24 3.18.1 Opening a File for Reading . . . . . . . . . . . . . . 24 3.18.2 Creating an Output File . . . . . . . . . . . . . . . 24 3.18.3 Closing an Auxiliary File . . . . . . . . . . . . . . 25 3.18.4 Reading from an Auxiliary File . . . . . . . . . . . . 25 3.18.5 Writing to an Auxiliary File . . . . . . . . . . . . . 26 3.19 Notes About The System Variables . . . . . . . . . . . . . 26 4. Animation And Time Control . . . . . . . . . . . . . . . . . . 28 5. Example Animations . . . . . . . . . . . . . . . . . . . . . . 29 6. Use And Distribution of RTAG . . . . . . . . . . . . . . . . . 30 6.1 Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . 31 i Contents ii 7. Other Software . . . . . . . . . . . . . . . . . . . . . . . . 32 7.1 Mathplot -- Mathematical Function Plotting Program . . . . 32 7.2 Nonlin -- Linear & Nonlinear Statistical Regression . . . . 32 7.3 TSX-32 -- Multi-User Operating System . . . . . . . . . . . 33 8. Software Order Form . . . . . . . . . . . . . . . . . . . . 35 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Chapter 1 Introduction An animation is composed of a sequence of individual images, called "frames," which are displayed rapidly to give the illusion of motion. Anyone who sets out to create an animation must deal with two design issues: (1) the generation of the basic scene (objects, colors, lights, etc.), and (2) the changing position of the objects between frames. RTAG deals with the second of these issues -- object motion. The first issue, basic scene design and rendering, is carred out by the ray tracing program of your choice (POV-Ray, Polyray, BOB, etc.). RTAG reads an animation control file that you create and generates one or more files that automate the rendering of individual frames and the construction of the animation sequence. The animation control file is the focus of this manual. RTAG implements an animation language with a syntax similar to C. Although simple in comparison to full featured languages such as C and Pascal, the RTAG language is far from trivial. It provides full arithmetic and logical expressions, control statements (IF), loop statement (FOR, WHILE, and DO), a rich set of library functions (trig, log, roots, spline, etc.), and statements for writing commands to the output files which will be used to generate the frames. Using the RTAG language you can perform realistic simulations of physical processes such as accelerations, falling objects, and interactions between objects. RTAG also can be used as a general purpose programming language. 1.1 Ray Tracing Driver Files The basic purpose of RTAG is to produce a set of files which will cause ray tracing programs such as POV-Ray, Polyray, Vivid, BOB, and other ray tracers to generate the sequence of frames for an animation. All ray tracers accept some sort of scene description file in which you specify the position of objects, colors, textures, camera angle, etc. With rare exeception, one run of a ray tracer with one scene description produces one image file. In order to produce an animation you must run the ray tracer once for each frame and vary the position of the objects and/or camera between frames to produce the illusion of motion. This means that the scene description file must be different for each frame. 1 Chapter 1. Introduction 2 Fortunately, all good ray tracers provide a facility for including one or more external files while processing the scene description. In the case of POV-Ray this is accomplished with the "#include" statement. Other tracers have similar statements. Using this facility you can have a common scene description file and place only the commands to describe the positions of moving objects in a separate file that is included in the scene. For example, consider this simple POV-Ray scene description file: #include "colors.inc" #include "shapes.inc" #include "move.inc" camera { location <.5 1 -22> direction <0 0 1.5> up <0 1 0> right <1.33 0 0> look_at <0 4 0> } object { light_source { <6 15 -4> color White} } object { sphere { .5} texture { color red .9 green 0 blue .1 ambient .8 } } This scene has a camera, a single light source, and a ball. The position of the ball is specified as "" but note that xpos and ypos are not defined in the file. Rather, the values of xpos and ypos are defined in a separate file named "move.inc" that in included in this scene. Typical statements in move.inc are as follows: #declare xpos = 3 #declare ypos = 4 To simulate motion of the ball you would prepare a separate move.inc file for each frame with slightly altered values for xpos and ypos. Since there will be an include file for each frame, they are typically given names containing the frame numbers such as "MOVE001.INC", "MOVE002.INC", etc. A primary purpose of RTAG is to automate the generation of these include files. In addition to a scene description file and a separate include file for each frame, you also need a DOS batch file to cause the ray tracing program to be run for each frame. RTAG also helps you produce this file. For each frame, the batch file will contain commands to perform the following operations: (1) make the appropriate include file the current include file for the next image generation; (2) execute the ray tracing program which will generate an image based on frame-dependent data in the current include file; (3) additional commands to delete intermediate files or pack together the frame files. Typical commands written to the batch file for a frame are: COPY MOVE001.INC MOVE.INC POVRAY +iMOVE.POV +oMOVE.TGA Chapter 1. Introduction 3 Rather than having RTAG produce a separate include file for each frame (which can end up being a lot of files), it is also possible to write commands to the batch file to cause the include file to be created just before it is needed by the ray tracing program. To do this, use the DOS ECHO command with the ">" redirection operator to create the file and the ">>" operator to add additional commands to the file. The following is an example of commands that create an include file named MOVE.INC, write two commands into it, and then call POV-Ray to render the image: ECHO #declare xpos = 2.5 > move.inc ECHO #declare ypos = 8.6 >> move.inc POVRAY +iMOVE.POV +oMOVE.TGA Note that the ">" redirection operator creates a new file so it should be used with the first ECHO command for each frame. The ">>" redirection operator appends to the end of a file so it should be used for additional ECHO commands for the frame. To summarize, there are two methods for producing the include file for a frame: (1) have RTAG generate a separate file with a unique name that is copied (or renamed) to the name used by the #include statement; or (2) use ECHO commands in the batch file to generate the include file just before invoking the ray tracing program for the frame. 1.2 Files Produced by RTAG Include files -- If you wish to have RTAG generate a separate include file for each frame, you must use an OFILE command to declare the file name. The name must include one or more '#' characters which are replaced by the frame number to generate the actual include file name. The NEXTFRAME statement increments the frame number and opens the next include file being created. OWRITE commands are used to write information to the currently open include file. If you create the include file by writing ECHO commands to the batch file, then you will NOT use the OFILE and OWRITE statements which cause RTAG to generate a separate include file for each frame. Batch file -- This is a DOS batch (.BAT) file containing the commands to perform the following operations for each frame: 1. make the appropriate include file the current include file for the next image generation (or generate the include file); 2. execute the ray tracing program which will generate an image based on frame-dependent data in the current include file; Chapter 1. Introduction 4 3. additional commands to delete intermediate files or pack together the frame files. Use BWRITE statements in your control file to write to the batch file. The BFILE statement declares the name of the batch file. This file is not created unless you use the BFILE and BWRITE commands. Auxiliary files -- RTAG includes statements for opening, creating, reading from, and writing to auxiliary files. Auxiliary input files can be used to transfer animation data from other programs to RTAG. One use of an auxiliary output file is to store the names of the generated targa or GIF files so that a subsequent program such as DTA can read this file to determine which files to string together in the final animation file. Listing file -- This file has the same name as the animation control file but an extension of ".LST". It contains the same output displayed by RTAG on the screen during an animation generation run. You can use PRINT statements within your control file to write output to the screen and the listing file. 1.3 Auxiliary Programs RTAG is one component in the set of programs needed to produce and display an animation. In addition to RTAG you will need the following programs: Ray Tracing Program -- There are several excellent ray tracing programs available as freeware or shareware. Three programs with which I am familiar are POV-Ray (freeware) by Drew Wells and the POV team (CompuServe 73767,1244); Polyray (shareware) by Alexander R. Enzmann (CompuServe 70323,2461); and BOB by Christopher Watkins, Stephen Coy, and Mark Finlay (included with the excellent book "Photorealism and Ray Tracing in C"). GIF generator -- Most ray tracing programs output "targa" files which contain higher resolution images than usually can be displayed. These targa files must be converted into GIF or other image formats before they can be displayed. One fine freeware program for doing this is Piclab by Lee Daniel Crocker and the Stone Soup Group (CompuServe 73407,2030). Scene viewer -- When designing a scene you will need a program to display the TGA or GIF file for an individual frame of the animation. There are many programs available to do this. A popular shareware choice is CSHOW by Bob Berry (CompuServe 76555,167). Animation sequencer -- Once the individual frame images have been generated, they must be combined into a single file that can be displayed rapidly. A shareware program which I use for this is DTA by David K. Mason (CompuServe 76546,1321). DTA reads the targa or GIF files produced by the ray tracer and Chapter 1. Introduction 5 produces a .FLI (flick) file that can be displayed as an animation. Animation display -- This program reads the finished animation file and displays it on your screen. A popular shareware program for displaying .FLI files is PLAY.EXE by Trilobyte (CompuServe 72330,3276). These programs, and many others related to ray tracing and animation, are available in the libraries of the CompuServe GRAPHDEV forum. This is also an excellent place for posting messages or getting help regarding ray tracing and animation. Two bulletin boards which specialize in graphics development are "You Can Call Me Ray," 708-358-5611; and "The Graphics Alternative," 510-524-2780. Chapter 2 Running RTAG Once you create an RTAG control file, you can use RTAG to compile and execute it by issuing a DOS command of the form: RTAG control_file [option1] [option2]... where "control_file" is the name of the control file. If no file extension is specified, ".RTA" is used by default. 2.1 Command Line Options Following the control file name you may specify the options described below. If more than one option is provided, they must be separated by spaces. The option letters are not case sensitive. Values specified with command line options override the corresponding values specified in the control file. /B=file -- Specifies the name of the batch file. The batch file name can also be specified using a BFILE statement in your control file. The default extension is ".BAT". /F=number -- Specifies the first frame that is to produce output. Output generated with the BWRITE and OWRITE functions is discarded for frames prior to this number. The default value is 1. /L=number -- Specifies the last frame that is to produce output. Output generated with the BWRITE and OWRITE functions is discarded for frames following this number. By default, there is no last frame (i.e., all frames are output). /N -- Specifies that no output is to be written to the batch and include files. This is useful when you are debugging an animation control file and want to test it without generating the output files. Output generated by PRINTF and WRITE functions always is written, even if this option is specified. /O=file -- Specifies the name of the include files generated during the run. Include file names must include the string '###' (1 to 5 '#' characters) which is replaced by the frame number. The output file names can also be specified by an OFILE statement in your control file. The default extension is ".INC". 6 Chapter 2. Running RTAG 7 /P -- Causes the entire control file to be listed on the screen and written to the listing file. Normally only error messages and output generated by PRINTF statements are displayed. /S=number -- Specifies the number of steps between frames whose output is to be generated. Output is discarded for frames between the step frames if a value other than 1 is specified. The default value is 1. If stepping is enabled, the first frame is generated and then frames are skipped up to first+step. The sequence continues with subsequent frames. This option is useful for producing an abbreviated set of frames for evaluation and debugging purposes. /T -- Specifies that each source statement is to be displayed before it is executed. This is useful for debugging purposes. 2.2 The RTAG Animation Control File RTAG reads an animation control file that you create, compiles the commands, and executes the resulting program. The commands in the control file are formed from the RTAG animation language which is described in the sections that follow. However, before getting into a detailed discussion of the animation language, let's look at a simple example to get a feeling for the language. This example is a complete RTAG command file which will generate the appropriate commands to move an object on a spline path that passes through a specified set of x,y,z coordinates: Chapter 2. Running RTAG 8 // Simple animation example. // Declare variables var lastframe = 60; // Generate 60 frames var x,y,z; // Declare files bfile "move"; // Batch file MOVE.BAT // Begin main animation loop to generate 60 frames. while (curframe < lastframe) { // Begin the next frame (this increments curframe) nextframe; // Use spline function to compute x,y,z position. x = spline(curframe, 1,-8, 20,0, 40,5, 60,8); y = spline(curframe, 1,1, 20,5, 40,5, 60,1); z = spline(curframe, 1,0, 20,4, 40,6, 60,10); // Report the position printf("At frame `curframe`, x=`x`, y=`y`, z=`z`\n"); // Write commands to the batch file. // These commands create a move.inc include file. bwrite("ECHO #declare xpos = `x` > move.inc\n"); bwrite("ECHO #declare ypos = `y` >> move.inc\n"); bwrite("ECHO #declare zpos = `z` >> move.inc\n"); // Generate command to render the image. bwrite("call render move move`###`\n"); } // Write batch command that runs DTA to build the animation. epilog; bwrite("call dta move\n"); 2.3 Arithmetic and Logical Expressions Much of the power of RTAG comes from its ability to perform mathematical calculations. This is important for any type of animation generation, but is especially critical for physical system simulations. This section explains the arithmetic operators and built in functions that may be used in arithmetic expressions. The following arithmetic operators may be used in expressions: ++ add 1 to a variable -- subtract 1 from a variable + addition - subtraction or unary minus * multiplication / division % modulo ** or ^ exponentiation The "++" and "--" operators may be used either immediately before or after a variable name. If they are used before the name, the increment or decrement is performed before the value of the variable is used in the expression. If they are used after the name, the value of the variable before being modified is used in Chapter 2. Running RTAG 9 the expression and then the increment or decrement takes place. For example, the sequence: a = 3; b = 3; x = ++a; y = b++; assigns the value 4 to x and 3 to y. At the end of the sequence, both a and b have the value 4. The following assignment operators can be used in expressions: variable = expression; // Assign expression to variable variable += expression; // Add expression to variable variable -= expression; // Subtract expression from variable variable *= expression; // Multiply variable by expression variable /= expression; // Divide variable by expression The following operators compare two values and produce a value of 1 if the comparison is true, or 0 if the comparison is false: == Equal != Not equal <= Less than or equal >= Greater than or equal < Less than > Greater than The following logical operators may be used: ! Logical NOT (negates true and false) && AND || OR There are two other special operators: "[]" (square brackets) which enclose subscripts on arrays, and "," (comma) which is used to specify left-to-right, sequential evaluation of a list of expressions. Operator precedence, in decreasing order, is as follows: subscript, unary minus, logical NOT, ++ and --, exponentation, multiplication, division and modulo, addition and subtraction, relational (comparison), logical (AND and OR), assignment, comma. Parentheses may be used to group terms. 2.3.1 Numeric Constants Numeric constants may be written in their natural form (1, 0, 1.5, .0003, etc.) or in exponential form, n.nnnEppp, where n.nnn is the base value and ppp is the power of ten by which the base is multiplied. For example, the number 1.5E4 is equivalent to 15000. All numbers are treated as "floating point" values, regardless of whether a decimal point is specified or not. As a convenience for entering time values, if a value contains one or more colons, the Chapter 2. Running RTAG 10 portion to the left of the colon is multiplied by 60. For example, 1:00 is equivalent to 60; 1:00:00 is equivalent to 3600. 2.3.2 Built-in Constant The symbolic name "PI" is equivalent to the value of pi, 3.14159... You may write PI using either upper or lower case. 2.4 Built in Functions The following functions are built into RTAG and may be used in expressions: ABS(x) -- Absolute value of x. ACOS(x) -- Arc cosine of x. Angles are measured in degrees. ASIN(x) -- Arc sine of x. Angles are measured in degrees. ATAN(x) -- Arc tangent of x. Angles are measured in degrees. CEIL(x) -- Ceiling of x (an equivalent name for this function is INT). Returns the smallest integer that is at least as large as x. For example, CEIL(1.5)=2; CEIL(4)=4; CEIL(-2.6)=-2. CLOSE(file) -- Close the specified file. COS(x) -- Cosine of x. Angles are measured in degrees. COSH(x) -- Hyperbolic cosine of x. COT(x) -- Cotangent of x. (COT(x) = 1/TAN(x)). Angle in degrees. CREATE("file name") -- Create a new auxiliary data file. The value returned by this function is a file number that can be used with subsequent WRITE functions. See the description of auxiliary file I/O for additional information. CSC(X) -- Cosecant of x. (CSC(x) = 1/SIN(x)). Angle in degrees. DEG(x) -- Converts an angle, x, measured in radians to the equivalent number of degrees. EXP(x) -- e (base of natural logarithms) raised to the x power. FAC(x) -- x factorial (x!). The FAC function is computed using the GAMMA function (FAC(x)=GAMMA(x+1)) so non-integer argument values may be computed. FLOOR(x) -- Floor of x. Returns the largest integer that is less than or equal to x. For example, FLOOR(2.5)=2; FLOOR(4)=4; FLOOR(-3.6)=-4. Chapter 2. Running RTAG 11 GAMMA(x) -- Gamma function. Note, GAMMA(x+1) = x! (x factorial). INT(x) -- Ceiling of x (an equivalent name for this function is CEIL). Returns the smallest integer that is at least as large as x. For example, INT(1.5)=2; INT(4)=4; INT(-2.6)=-2. LINEAR(t, t1,x1, t2,x2, ... tn,xn) -- Perform linear interpolation between a set of points. If the value of a function is x1 at some point t1, x2 at t2, etc., this function determines the value at some arbitrary point, t, where t falls in the range (t1,tn). The first argument to the LINEAR function is the value t at which the interpolation is to be performed. The remaining arguments are (ti,xi) data pairs. For example, consider the function LINEAR(t, 0,0, 1,6, 2,4). This specifies that when t is 0, the value of the function is 0, when t is 1, the value is 6, and when t is 2 the value is 4. If this function is called with a t value of 0.5, the returned value of the function will be 3. If the function is called with a t value of 1.5, the returned value will be 5. You can use expressions as arguments to this function. For example, the following function invocation is valid: LINEAR(t, starttime,basex, starttime+3,midx, endtime,midx*2). If the function is called with a t value that is outside the range (t1,tn) (i.e., beyond either end point), then the nearest end point and the second closest point are used to extrapolate to the specified t value. See also the description of the SPLINE function. LOG(x) -- Natural logarithm of x. LOG10(x) -- Base 10 logarithm of x. MAX(x1,x2) -- Maximum value of x1 or x2. MIN(x1,x2) -- Minimum value of x1 or x2. MOD(x1,x2) -- x1 modulo x2. The MOD function calculates the floating-point remainder, f, of x1/(i*x2) such that x1=i*x2+f, where i is an integer; f has the same sign as x1, and the absolute value of f is less than the absolute value of x2. The % operator perform the same operation. MOREDATA(file) -- This function checks to see if there is another data record available in the external file whose file number is specified as the argument. If there is a record available, this function returns the value true (1), if not, it returns false (0). This function does not consume any data in the file, you must use the READ statement to actually read the next record. You can call MOREDATA any number of times without disturbing the next record in the file. See the section on auxiliary file I/O for additional information. NPD(x,mean,std) -- Normal probability distribution of x with specified mean and standard deviation. X is in units of standard deviations from the mean. Chapter 2. Running RTAG 12 OPEN("file name") -- Open an existing file for reading. The value returned by this function is a file number that can be used with subsequent READ functions. See the description of auxiliary file I/O for additional information. PAREA(x) -- Area under the normal probability distribution curve from -infinity to x. (i.e., integral from -infinity to x of NORMAL(x)). PRINTF("format"[,expression1,expression2,...]) -- Evaluate the expressions (if any) and write the values with the specified formatting string to the console and the listing file. PULSE(a,x,b) -- Pulse function. If the value of x is less than a or greater than b, the value of the function is 0. If x is greater than or equal to a and less than or equal to b, the value of the function is 1. In other words, it is 1 for the domain (a,b) and zero elsewhere. If you need a function that is zero in the domain (a,b) and 1 elsewhere, use the expression (1-PULSE(a,x,b)). RAD(x) -- Converts an angle measured in degrees to the equivalent number of radians. RANDOM() -- Returns a random value uniformly distributed in the range 0 to 1. You can use the srand system variable to specify a starting seed. READ(file,variable1,variable2,...) -- Read one line from the specified file, scan the input line for values, and assign the values to the specified variables. ROUND(x) -- Rounds x to the nearest integer. For example, ROUND(1.1)=1; ROUND(1.8)=2; ROUND(-2.8)=-3; SEC(x) -- Secant of x. (SEC(x) = 1/COS(x)). Angle in degrees. SEL(a1,a2,v1,v2) -- If a1 is less than a2 then the value of the function is v1. If a1 is greater than or equal to a2, then the value of the function is v2. SIN(x) -- Sine of x. Angles are measured in degrees. SINH(x) -- Hyperbolic sine of x. SPLINE(t, t1,x1, t2,x2, ... tn,xn) -- Perform a cubic spline interpolation between a set of points. A spline is a smooth path (continuous first and second derivatives) that passes through a set of points. The SPLINE function is very useful in animations because it allows you to easily construct a smooth path for the motion of some object (or the camera). If the value of a function is x1 at some point t1, x2 at t2, etc., this function determines the value at some arbitrary point, t, where t falls in the range (t1,tn). The first Chapter 2. Running RTAG 13 argument to the SPLINE function is the value t at which the interpolation is to be performed. The remaining arguments are (ti,xi) data pairs. You can use expressions as arguments to this function. For example, the following function invocation is valid: SPLINE(t, starttime,basex, starttime+3,midx, endtime,midx*2). If the function is called with a t value that is outside the range (t1,tn) (i.e., beyond either end point), then the value of the function at the nearest end point and the slope of the function at that point are used to extrapolate in a linear fashion to the specified t value. See also the description of the LINEAR function. SQRT(x) -- Square root of x. STEP(a,x) -- Step function. If x is less than a, the value of the function is 0. If x is greater than or equal to a, the value of the function is 1. If you need a function which is 1 up to a certain value and then 0 beyond that value, use the expression STEP(x,a). TAN(x) -- Tangent of x. Angles are measured in degrees. TANH(x) -- Hyperbolic tangent of x. WRITE(file,"format"[,expression1,expression2,...]) -- Evaluate the expressions (if any) and write the values with the specified formatting string to auxiliary output file whose file number is specified as the first argument. 2.4.1 Notes on the SPLINE and LINEAR Functions RTAG includes two library functions for performing interpolation: LINEAR and SPLINE. If you have two pairs of values, (t1,x1) and (t2,x2), these functions determine the value of x that corresponds to some value of t between t1 and t2. If you have more than two pairs, the function determines the value of x that is on the segment that spans the specified value of t. The function parameters, t and x, can represent any type of value. However, in animations t is usually a time value or frame number, and x is a position (either in the X, Y, or Z dimension). If you want an object to follow a path through a set of three dimensional points, you have to use three statements, each with an interpolation function. For example, if at frame 1 you want an object to be at (-8,0,-3), frame 20 to be at (0,5,-1), frame 40 to be at (2,2,0), and frame 60 to be at (7,4,2), then you could use the following statements: while (curframe <= 60) { nextframe; x = spline(curframe, 1,-8, 20,0, 40,2, 60,7); y = spline(curframe, 1,0, 20,5, 40,2, 60,4); z = spline(curframe, 1,-3, 20,-1, 40,0, 60,2); << other statements >> } Chapter 2. Running RTAG 14 The spline function will force the object to be at the specified x,y,z coordinate at frames 1, 20, 40, and 60, and will generate intermediate positions between these frames. While the method explained above of specifying absolute frame numbers works well, you will have to change the values in the function specification if you change the total number of frames in the animation. A better approach is to use the percentage of the total animation as the control values and use the expression (100*(curframe-1)/(lastframe-1)) to specify the position along the path. Note that the a value must be specified for lastframe. The following program illustrates this approach: var x,y,z,position; var lastframe = 50; // Animation will have 50 frames while (curframe < lastframe) { nextframe; // This increments curframe position = 100*(curframe-1)/(lastframe-1); x = spline(position, 0,-8, 40,0, 60,2, 100,7); y = spline(curframe, 0,0, 40,5, 60,2, 100,4); z = spline(curframe, 0,-3, 40,-1, 60,0, 100,2); statements to output position >> } If the path described by a spline function completes a closed circuit, a smoother transition can be accomplished by specifying an extra point beyond either end which matches the next point on the path. The following statements illustrate this for forming a roughly circular path (a better way to do this would be to use sin and cos functions): position = 100*(curframe-1)/(lastframe-1); x = spline(position, -20,0.3, 0,1.0, 20,0.3, 40,-0.8, 60,-0.8, 80,0.3, 100,1.0, 120,0.3); y = spline(position, -20,-1.0, 0,0.0, 20,1.0, 40,0.6, 60,-0.6, 80,-1.0, 100,0.0, 120,1.0); Note that the first point specified (-20) and the last point (120) will never be reached since the value of position ranges from 0 to 100. However, because the spline function depends not only on the current position but also on the points on either side, specifying these points smooths out the transition near the end points. This trick does not apply to spline curves that are not closed on themselves. Chapter 3 The Animation Control Language The RTAG animation control language is similar to other modern programming languages such as C. It provides the tools you need to easily perform animation simulations and generate the necessary output files to drive the ray tracing and auxiliary programs. 3.1 Comments The beginning of a comment is denoted with "//" (two consecutive slash characters). Everything from the "//" sequence to the end of the line is treated as a comment. Comments may be on lines by themselves or on the ends of other statements. You can also specify a comment by beginning the comment with the "/*" character sequence. All characters following this are treated as comments up to the matching "*/" sequence. The following lines illustrate both types of comments: // Begin main simulation loop y = y + timestep * yvelocity; // Advance y position /* * This is a comment. */ z = y / 5; /* This is a comment too */ 3.2 Basic Statement Syntax The RTAG language has a syntax that is very similar to C: statements are terminated with a semicolon, and brace characters ("{" and "}") are used to group statements. 3.3 Declaration of Variables (The VAR Statatement) All variables used in your animation control file must be declared before they are used. This is done using the VAR statement which may optionally assign an initial value to the variable. If no initial value is specified, 0 is used by default. VAR is a declarative statement: that is, it declares the existance of the variable and assigns an initial value, it does not reassign the value to the variable if the VAR statement appears in a loop. 15 Chapter 3. The Animation Control Language 16 Variable names may be up to 30 characters long. They ARE case sensitive. Keywords (FOR, WHILE, VAR, etc.) and library function names (SIN, COS, ABS, etc.) are NOT case sensitive. All variables are double precision (64 bit) floating point values. The syntax of the VAR statement is: VAR variable1[=value], variable2[=value], ...; You may use as many VAR statements as you need. The following are examples of this statement: var x, y, speed = 5; var Acceleration = 2.5; In addition to simple scalar variables, RTAG also allows you to use one-dimensional array variables. To declare an array variable, follow the name of the variable with the number of elements enclosed in square brackets. For example, the following command declares a variable named speeds that will have 20 values: var speeds[20]; If you wish to assign initial values to an array, enclose the list of values in braces. For example, var xpos[3] = {1.2, 2.7, 4.6}; Subscripts follow the C convention of being 0 based. That is, the first element of an array is referenced using a subscript value of 0. For example, if the variable x is declared with three elements (var x[3]) then the elements would be referenced as x[0], x[1], and x[2]. The expression x[3] would NOT be valid. In addition to your own variables, RTAG provides several system variables. If you do not provide VAR statements for these variables, they are defined automatically at the start of a run and RTAG assigns their values. Variable Default Meaning ---------- ------- ------------------------------------------- curframe 0 The current frame number. Set by NEXTFRAME. firstframe 1 The first frame that will generate output. lastframe 999999 The last frame that will generate output. stepinc 1 The step increment between frames. srand 1 Seed for random number generator. These variables may be used in your animation control file just like ordinary variables. If you want to set different default values for firstframe, lastframe, stepinc or srand, use a VAR statement and specify an initial value. For example, the following commands would cause frames 20 through 40 to be output: var firstframe = 20; var lastframe = 40; Chapter 3. The Animation Control Language 17 The default values, or the values specified by VAR statements, can be overridden by qualifiers on the command line. /F sets firstframe, /L sets lastframe, and /S sets stepinc. The srand system variable is used to set a starting "seed" value for the RANDOM() function. The default value for srand is 1. For a given starting seed value, the pseudorandom sequence is always the same. 3.4 Output File Declarations RTAG is capable of producing multiple files during each run. Most of these files are optional and will only be produced if you include the appropriate statements in your control file. The listing file is always produced. It has the same name as the animation control file but with an extension of ".LST". Most RTAG runs will produce a batch file to drive the ray tracing program. The batch file may contain commands to generate the appropriate include file for each frame or you may choose to have RTAG generate the full set of include files separate from the batch file. If you wish to generate a batch file you must place a command of the following form in your control file: BFILE "name"; where 'name' is the name of the batch file. The default extension is ".BAT". Note that the file name must be enclosed on quote marks. The batch file normally contains a set of commands to render each frame. Typically, the commands for each frame perform the following actions: 1. Generate an include file with object position information. 2. Run the ray tracer using the current include file. The BWRITE function is used to write to the batch file. The batch file is optional and is generated only if you use a BFILE statement. If you wish to have RTAG generate a set of include files, you must use the following command to declare the names of the files: OFILE "name"; If the OFILE statement is used, one output file is generated for each frame. The output file name must include a string of one to seven '#' characters. These characters are replaced by the current frame number when the file is opened. For example, consider the following command: Chapter 3. The Animation Control Language 18 ofile "bounc###.inc"; Then for frame 27 the name of the created file will be BOUNC027.INC. The default extension is ".INC". The NEXTFRAME command closes the current output file, increments the frame number, and opens the next output file (assuming the OFILE statement was specified). The last output file is closed when the program stops. The OWRITE function writes lines to the currently open output file. RTAG can also create or read from auxiliary data files. This is described in a subsequent section. 3.5 Assignment Statement The assignment statement is an executable statement that evaluates an expression and assigns its value to a variable. The syntax for an assignment statement is: variable = expression; // Assign expression to variable variable += expression; // Add expression to variable variable -= expression; // Subtract expression from variable variable *= expression; // Multiply variable by expression variable /= expression; // Divide variable by expression where "variable" is a previously declared variable which may be subscripted and "expression" is a valid arithmetic or logical expression following the rules explained earlier. If the expression involves a relational comparison operator (e.g., <, >, >=, etc.) or a logical operation (&&, ||, !), the value 1 is used for true and 0 for false. 3.6 IF Statement The form of the IF statement is: IF (expression) statement1 [ELSE statement2] If the expression is true (not zero) statement1 is executed, if the expression is false (0) and the ELSE clause is specified, statement2 is executed. The ELSE clause and the second set of controlled statements are optional. You may control groups of statements by enclosing them in braces. The following are examples of valid IF statements: if (x > bigx) bigx = x; Chapter 3. The Animation Control Language 19 if (x <= 10) { y = linear(x, 0,0, 10,6); z = .5 * x; } else { y = y + yspeed * timestep; z = .3 * x; } 3.7 WHILE Statement The WHILE statement loops until the controlling expression becomes false (0) or a BREAK statement is executed within the loop. The form of the WHILE statement is: WHILE (expression) { << controlled statements >> } Each time around the loop the expression is evaluated. If it is true (non zero) the controlled statements are executed and then the process repeats until the expression becomes false. If a BREAK statement is executed within the loop, execution of the loop terminates and control is transferred to the first statement beyond the end of the loop. If a CONTINUE statement is executed in the loop, control is transferred to the conditional test at the top of the loop. The following is an example of a WHILE statement: while (x < 5) { x = x + xmove; y = y + ymove; } 3.8 DO Statement The DO statement is very similar to the WHILE statement except the control expression is evaluated at the end of the loop rather than the beginning. This causes the loop always to be executed at least once. The form of the DO statement is: DO { << controlled statements >> WHILE (expression); For each iteration of the loop the controlled statements are executed and then the conditional expression is evaluated. If it is true (non-zero) control transfers to the first controlled statement at the top of the loop. A BREAK statement may be used to terminate the loop before the conditional expression is evaluated. A CONTINUE statement can be used to cause control to be transferred from within the loop to the point where the conditional expression is evaluated. The following is an example of a DO statement: Chapter 3. The Animation Control Language 20 do { read(infile,lastflag,x[numpoints++]); } while (!lastflag); 3.9 FOR Statement The FOR statement is a looping control statement similar to the WHILE statement; however, the FOR statement also allows you to specify initialization expressions that are executed once at the beginning of the loop, and loop-end expressions that are executed at the end of each loop cycle. The form of the FOR statement is: FOR (expression1; expression2; expression3) statement Execution of a FOR statement proceeds as follows: 1. Evaluate expression1. Typically this expression will include assignment operators ("=") to set initial values for loop variables. If you need more than one initial expression, specify them as a list separated by commas. 2. Evaluate expression2. If its value is false (0) terminate the FOR statement and transfer control to the statement that follows the controlled statement. If expression2 is true, proceed to the next step. 3. Execute the controlled statement. If more than one statement is to be controlled, enclose them with brace characters ("{" "}"). 4. Evaluate expression3. This expression will typically contain operators such as "++", "+=", "--", or "-=" to modify the value of a loop variable. 5. Transfer control to step 2, where expression2 is once again evaluated. The following is an example of a FOR statement: for (time=starttime; time> } 3.10 BREAK Statement The BREAK statement can be used in FOR, WHILE, and DO loops to terminate the loop and cause control to transfer to the statement beyond the end of the loop. The following is an example of a BREAK statement: Chapter 3. The Animation Control Language 21 time = 0; x = 0; while (time < endtime) { x += delta * xspeed; if (x > 10) break; } 3.11 CONTINUE Statement The CONTINUE statement can be used in FOR, WHILE, and DO loops to terminate the current iteration and begin the next one. When CONTINUE is executed in a WHILE or DO statement, control is transferred to the point in the loop where the loop control expression is evaluated. When CONTINUE is executed in a FOR statement, control is transferred to the bottom of the loop where expression3 is evaluated (which normally augments the values of the loop variables for the next iteration). 3.12 STOP Statement The STOP statement terminates the execution of RTAG and closes all output files. An implicit STOP occurs if you "fall through" the bottom of your animation control file. The following is an example of the STOP statement: while (curframe < 60) { << controlled statements >> if (xposition1 >= xposition2) stop; } 3.13 WRITE Statements RTAG has three functions for writing output to standard files. These functions and the files they write to are as follows: PRINTF -- Listing file (also displayed on screen). OWRITE -- Output file (OFILE). BWRITE -- Batch file (BFILE). Since the form for these functions is the same (except for the keyword), the PRINTF statement will be used in the illustrations. The form of the function is: printf("string"[,expression1, expression2,...]) where "string" is a quoted text string that may including variable and expression replacement operators. You can cause the current value of a variable to be substituted into a string by inserting the variable name in the string enclosed by "`" characters. Note, this is not the apostrophe, it is the accent character that is on Chapter 3. The Animation Control Language 22 the same key as the tilde on most keyboards. You can use the SUBCHAR statement (see below) to change the character used to mark a variable value substitution. For example, the following statement prints the values of the xpos and ypos variables: printf("X position is `xpos`, and Y position is `ypos`\n"); When this statement is executed `xpos` and `ypos` are replaced by the current values of the xpos and ypos variables. Following the C model, control characters are placed in the string by prededing the character with a backslash. The following table indicates each of the valid control sequences: \a -- Bell character (0x07). \b -- Backspace (0x08). \f -- Form feed (0x0C); \n -- End of print line (carriage-return, line-feed). \r -- Carriage return only. \" -- Quote character. \\ -- Literal backslash character (i.e., replace "\\" with "\"). \xddd -- Hexadecimal value 0xddd. If the sequence `###` (1 to 7 '#' characters enclosed by "`" characters) appears in the string, the pound signs are replaced by the current frame number with leading zeros. If the sequence `+++` (1 to 7 '+' characters) appears in the string, the plus signs are replaced by a value equal to the current frame number plus 1. In addition, the strings `ofile` and `bfile` are replaced by the names of the output file, and batch file respectively. The string `file` is replaced by the name of the input animation command file with any device, directory, and extension removed. You can also substitute the values of expressions. To do this, use the C programming notation "%w.dlf" where 'w' is the overall field width and 'd' is the number of decimal places. For example, the following statement prints the value of an expression: printf("The diagonal distance is %5.1lf\n", sqrt(xd^2 + yd^2)); 3.14 SUBCHAR Statement The SUBCHAR statement specifies which character is to be used in write strings to enclose the names of variables whose values are to be substituted in the string. The default character is "`" -- the accent character which is usually on the same key as the tilde character. The form of the statement is: Chapter 3. The Animation Control Language 23 SUBCHAR "char"; where "char" is a single character that must be included in quote marks. For example, the following statement declares dollar sign to be the substitution marker character: subchar "$"; 3.15 NEXTFRAME Statement The NEXTFRAME statement performs the following actions: (1) close the currently open output file, if any; (2) increment the current frame number (and curframe variable); (3) if an OFILE statement was used, open a new output file with the current frame number substituted for the "###" characters in the file name. You must execute a NEXTFRAME statement before you can use an OWRITE function. PRINT, BWRITE and WRITE functions can be executed before the first NEXTFRAME command. The last output file is closed when your program stops. 3.16 EPILOG Statement The EPILOG statement (which may also be spelled EPILOGUE) informs RTAG that the last frame has been completed and that subsequent BWRITE function calls are unconditionally to generate output regardless of the setting of the firstframe, lastframe, and stepinc values. Otherwise BWRITE functions do not generate output if they occur after the last frame, or between frames if stepinc is not 1. Commonly statements using the BWRITE function are used after EPILOG to write some "end-of-all-frames" termination statements to the batch file, such as commands to run DTA to build the animation sequence. 3.17 Self-continuing Batch Files Because so much computer time is required to create ray traced animations, it is sometimes necessary to produce the frames using a series of runs rather than in a single run. Using RTAG it is easy to produce BAT files that automatically will restart with the first frame that does not exist. This is done by generating "IF EXIST...GOTO" commands as part of the batch file. For each frame you cause the BAT file to check if the TGA file exists; if so, control skips to the test for the next file. The following is a skeleton of an RTAG program to generate these statements. Note the use of the `###` sequence to substitute the current frame number and the `+++` sequence to substitute the next frame number. Chapter 3. The Animation Control Language 24 while (curframe < lastframe) { nextframe; bwrite(":do`###`\n"); bwrite("if exist tour`###`.tga goto do`+++`\n"); << other commands to write info for this frame >> } epilog; bwrite(":do`+++`\n"); bwrite("call dodta TOUR /S8\n"); The commands written to the BAT file for each frame have the following form: :do001 if exist tour001.tga goto do002 << commands to generate frame 1 >> :do002 if exist tour002.tga goto do003 << commands to generate frame 2 >> :do003 3.18 Auxiliary Data Files RTAG provides functions to open, close, read from, and write to auxiliary data files. This is useful if some other program has computed object positions or other data that affects the animation. Up to 30 auxiliary data files can be open at once. The files are identified by numbers (also called file "handles") that are assigned by RTAG at the time that the file is opened. The file numbers can be reused by closing and reopening files. You must use the VAR statement to declare variables to hold the file numbers. 3.18.1 Opening a File for Reading The form of the statement used to open an existing file for reading is: variable = open("file name"); where 'variable' is a varible you have previously declared with a VAR statement. When RTAG opens the file it generates a unique file number and assignes it to the variable on the left of the equal sign. This file number can be used subsequently in READ functions. An example of this statement is infile = open("spiral.dat"); Chapter 3. The Animation Control Language 25 3.18.2 Creating an Output File The form of the statement used to create an auxiliary output file is variable = create("file name"); When RTAG creates the file it assignes a unique file number to the specified variable. This file number can be used subsequently in WRITE functions. An example of this statement is outfile = create("trace.dat"); 3.18.3 Closing an Auxiliary File The function used to close an auxiliary file is: close(file) where 'file' is a variable that has a file number. For example: close(outfile); Any open files are closed automatically when your program terminates. 3.18.4 Reading from an Auxiliary File You may read data from an open auxiliary file by using a READ function of the following form: read(file,variable1,variable2,...); Where 'file' is a file number assigned by a previously executed OPEN function. Each READ function call reads the next line of data from the file and assigns numeric values to the list of variables you specify. There must be at least as many data values on the line as the number of variables specified with the READ function (additional values are ignored). The data values may be separated by spaces, tabs, and/or commas. Numeric values may be specified in the same form as numbers within an RTAG animation control file (natural, exponential, or dd:dd:dd). The MOREDATA function can be used to control how many records are read from the file. The value of MOREDATA(file) is true (1) if there is another, unread, record available in the file; its value is false (0) if there is no more data available in the file. MOREDATA does not consume any data, it just checks for the availability of data. The following statements would read all data in a file and generate a frame file for each record: Chapter 3. The Animation Control Language 26 var f,xpos,ypos; f = open("indata.dat"); while (moredata(f)) { nextframe; read(f,xpos,ypos); owrite("#declare xpos=`xpos`\n"); owrite("#declare ypos=`ypos`\n"); } 3.18.5 Writing to an Auxiliary File The form of the function used to write to an auxiliary file is: WRITE(file,"string"[,expression1,expression2,...]); where 'file' is a variable containing a file number assigned by a previously executed CREATE function. "string" is a quoted string of the same form as described for the PRINT, OWRITE and BWRITE functions. The string may include variable and expression replacement operators. Expression1, expression2, etc. are optional expressions whose values are to be substituted into the string where "%w.dlf" sequences occur. The following statements illustrate the use of the WRITE function: var f,x,y; f = create("sine.out"); for (x=0; x<360; x+=2) { y = sin(x); write(f,"x=`x`, y=`y`\n"); } close(f); 3.19 Notes About The System Variables There are four system variables that affect frame generation: curframe, firstframe, lastframe, and stepinc. Curframe has the current frame number. Its initial value is 0 before the first frame is started. The NEXTFRAME statement closes the output file (OFILE) if it is open, increments the value of curframe by 1, and opens a new output file (if an OFILE statement was specified). The following loop would be appropriate to generate an animation with 60 frames: while (curframe < 60) { nextframe; << commands to generate frame >> } By default, firstframe has a value of 1, lastframe has a value of 999999, and stepinc has a value of 1. There are two ways to assign different values to these variables: the VAR statement or with command line options (/F, /L, and /S). The main reason for setting firstframe and stepinc to something other than 1 is to make an abbreviated animation which will give you an idea of how Chapter 3. The Animation Control Language 27 objects will move without spending the time rending all of the images for a full animation. The following example shows a command file that will generate images for frames 10 through 60, stepping 5 between the frames: var firstframe = 10; var lastframe = 60; var stepinc = 5; while (curframe < lastframe) { nextframe; << commands to generate frame >> } The effect of setting firstframe to something other than 1 may be different than what you expect. The current frame number (curframe) ALWAYS starts at 0 and increments by 1. If firstframe is set to something other than 1, the OWRITE and BWRITE functions have no effect until the frame number reaches the firstframe value (i.e., when executed they do not write anything to a file). The reason that firstframe works like this is that when performing a simulation the state of the system usually depends on previous iterations (e.g., the position of a falling ball depends on how long it has been dropping and whether it has already hit the floor). Because of this it is necessary to start at the beginning each time. However, by cancelling the actions of the OWRITE and BWRITE functions prior to firstframe, you can save the expense of rendering frames before the one of interest. There are two exceptions to this rule. BWRITE functions always generate output before the first execution of the NEXTFRAME statement regardless of the value of firstframe, lastframe, and stepinc. This is done so that initialization statements can be generated before the frame generation iteration begins. BWRITE functions also always generate output after the execution of an EPILOG statement. This is done so that you can write cleanup and termination commands to the batch and auxiliary files. PRINTF and WRITE functions generate output regardless of the value of firstframe. The effect of stepinc is similar to firstframe. The NEXTFRAME statement ALWAYS increments the frame number by 1. If stepinc is not 1, OWRITE and BWRITE functions are disabled between the steps. BWRITE always generates output before the execution of the first NEXTFRAME statement and after execution of an EPILOG statement. Chapter 4 Animation And Time Control Time is an essential component of any animation. Except for special effects, time advances by a constant amount between frames. Most RTAG animation control files will have an outer loop advancing through either frames or time. For simple animations it is usually easier to loop through frames, calculating the simulated time as a function of the frame number. For example, the following statements would move an object along a sinusoidal (wavey) path using the frame number as an argument to the SIN function: while (curframe < 60) { nextframe; x = -6 + (curframe / 5); y = 3 * sin(curframe * 12); << other statements to generate output >> } This approach works well for simple animations where the position of the objects can be calculated as a direct function of the frame number. However, for more complex animations, especially those involving acceleration and interactions between objects, it may be necessary to perform the simulation with smaller time steps than the time between frames. In other words, the outer loop should advance the simulation time and frames should be generated at periodic intervals to take "snapshots" of the objects. The following statements illustrate this approach: for (time=0; time> // See if it is time to generate a frame if (time >= frametime) { // Generate a frame nextframe; << statements to write to files >> // Calculate when next frame should be generated frametime = frametime + sampletime; } } 28 Chapter 5 Example Animations The RTAG distribution comes with several example files which are explained below. For each example there is an ".RTA" animation command file and a ".POV" POV-Ray scene description file. TOUR -- There is a simulated "city" (would you believe a village with high rise buildings?). The camera begins from the distance, sweeps down and along "Main Street", circles a dome structure at the end, and then climbs while still keeping the buildings in view as it moves away. The SPLINE function is used both to control the position of the camera and also the location that the camera is looking at. This 120-frame animation takes about 6 hours to render in 320x200 size with anti-aliasing turned on running on a 486/33 using POV-Ray. BOUNC -- Bouncing ball simulation. A ball rolls down a ramp, falls, bounces twice, and ends up in landing in a can. This is a good example of a simulation where time is advanced in small steps and frames are generated periodically as "snapshots" of the scene. The position of the ball is calculated using elementary physics: The speed of an accelerating object at the end of a time interval is equal to its speed at the beginning plus the acceleration multiplied by the time interval. The position at the end of an interval is equal to the position at the start of the interval plus the speed multiplied by the time interval. An animation with 60 to 70 frames seems to work best with this example. ORBIT -- Orbital simulation. Three planets move in elliptical orbits around a sun. One of the planets has a moon in a circular orbit. The orbital speeds of the planets follow Kepler's laws. If you look closely you can see the shadow as one planet eclipes another. The 200 frame sequence takes about 4 hours to render on a 386/25 with coprocessor. 29 Chapter 6 Use And Distribution of RTAG You are welcome to make copies of this program and pass them on to friends or post this program on bulletin boards or distribute it via disk catalog services provided the entire RTAG distribution is included in its original, unmodified form. A distribution fee may be charged for the cost of the diskette, shipping and handling. However, RTAG may not be sold, or incorporated in another product that is sold, without the permission of Phillip H. Sherrod. Vendors are encouraged to contact the author to get the most recent version of RTAG. As a shareware product, you are granted a no-cost, trial period of 30 days during which you may evaluate RTAG. If you find RTAG to be useful, educational, and/or entertaining, and continue to use it beyond the 30 day trial period, you are required to compensate the author by sending the registration form printed at the end of this document (and in REGISTER.DOC) with the appropriate registration fee to help cover the development and support of RTAG. In return for registering, you will be authorized to continue using RTAG beyond the trial period and you will receive the most recent version of the program, a laser-printed, bound manual, and three months of support via telephone, mail, or CompuServe. Your registration fee will be refunded if you encounter a serious bug that cannot be corrected. You are welcome to contact the author: Phillip H. Sherrod 4410 Gerald Place Nashville, TN 37205-3806 USA 615-292-2881 (evenings) CompuServe: 76166,2640 Internet: 76166.2640@compuserve.com Both the RTAG program and documentation are copyright (c) 1993 by Phillip H. Sherrod. You are not authorized to modify the program. "RTAG" is a trademark. This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the 30 Chapter 6. Use And Distribution of RTAG 31 member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 7007,3536. 6.1 Disclaimer RTAG is provided "as is" without warranty of any kind, either expressed or implied. This program may contain "bugs" and inaccuracies, and its results should not be assumed to be correct unless they are verified by independent means. The author assumes no responsibility for the use of RTAG and will not be responsible for any damage resulting from its use. Chapter 7 Other Software If you like RTAG, you should check out the following programs by the same author. 7.1 Mathplot -- Mathematical Function Plotting Program Mathplot allows you to specify complicated mathematical functions using ordinary algebraic expressions and immediately plot them. Four types of functions may be specified: cartesian (Y=f(X)); parametric cartesian (Y=f(T) and X=f(T)); polar (Radius=f(Angle)); and parametric polar (Radius=f(T) and Angle=f(T)). Up to four functions may be plotted simultaneously. Scaling is automatic. Options are available to control axis display and labeling as well as grid lines. Hard copy output may be generated as well as screen display. Mathplot is an ideal tool for engineers, scientists, math and science teachers, and anyone else who needs to quickly visualize mathematical functions. 7.2 Nonlin -- Linear & Nonlinear Statistical Regression Nonlin performs linear and nonlinear statistical regression analysis. What is regression analysis? Regression analysis is a mathematical technique for determining the best values of parameters to fit an equation to a set of data points. For example, you might want to develop an equation of the form price = p0 + p1*age + p2*miles to predict the price of a used car based on its age and the number of miles driven. With Nonlin you can collect data from car ads and then perform the analysis using the following set of commands: VARIABLES PRICE,AGE,MILES PARAMETERS P0,P1,P2 FUNCTION PRICE = P0 + P1*AGE + P2*MILES DATA Nonlin will analyze the data and determine the best values of the parameters P0, P1, and P2 to fit the data values. Ordinary linear regression programs can only determine parameter values for linear (straight line) equations. Nonlin, on the other 32 Chapter 7. Other Software 33 hand, can handle multivariate, linear, polynomial, and general nonlinear equations. For example, using Nonlin you can easily determine the best values for the parameters Offset, Amplitude, and Frequency for an equation of the form: Y = Offset + Amplitude * sin(Frequency * X) Nonlin uses the same expression evaluator as Mathplot so you can model complicated equations using the full set of operators and library functions available in Mathplot. Nonlin comes with a 48 page manual that explains regression analysis and gives many examples. Nonlin is in use at many universities and research labs around the world. 7.3 TSX-32 -- Multi-User Operating System If you have a need for a multi-user, multi-tasking operating system, you should look into TSX-32. TSX-32 is a full-featured, high performance, multi-user operating system for the 386 and 486 that provides both 32-bit and 16-bit program support. With facilities such as multitasking and multisessions, networking, virtual memory, X-Windows, background batch queues, data caching, file access control, real-time, and dial-in support, TSX-32 provides a solid environment for a wide range of applications. A two user, shareware version of TSX-32 called TSX-Lite is also available. TSX is particularly valuable for ray tracing and animation generation which can take a long time to run. These jobs can execute as background "batch" jobs while you perform interactive operations with virtually no degredation from the batch execution. TSX-32 is not a limited, 16-bit, multi-DOS add-on. Rather, it is a complete 32-bit operating system which makes full use of the hardware's potential, including protected mode execution, virtual memory, and demand paging. TSX-32 sites range from small systems with 2-3 terminals to large installations with more than 100 terminals on a single 486. In addition to supporting most popular 16-bit DOS programs, TSX-32 also provides a 32-bit "flat" address space with both Phar Lap and DPMI compatible modes of execution. Since the DOS file structure is standard for TSX-32, you can directly read and write DOS disks. And, you can run DOS part of the time and TSX-32 the rest of the time on the same computer. TSX-32 allows each user to control up to 10 sessions. Programs can also "fork" subtasks for multi-threaded applications. The patented Adaptive Scheduling Algorithm provides consistently good response time under varying conditions. Chapter 7. Other Software 34 The TSX-32 network option provides industry standard TCP/IP networking through Ethernet and serial lines. Programs can access files on remote machines as easily as on their own machine. The SET HOST command allows a user on one machine to log onto another computer in the network. FTP, Telnet, and NFS are available for interoperability with other systems. TSX-32 is, quite simply, the best and most powerful operating system available for the 386 and 486. For additional information contact: S&H Computer Systems, Inc. 1027 17th Avenue South Nashville, TN 37212 USA 615-327-3670 (voice) 615-321-5929 (fax) CompuServe: 71333,27 Internet: 71333.27@compuserve.com =============================================================== Software Order Form =============================================================== Name ______________________________________________________ Address ___________________________________________________ City _______________________ State _______ Zip ___________ Country ____________________ Telephone ___________________ CompuServe account (optional) _____________________________ RTAG version ______________________________________________ Bulletin board where you found RTAG _______________________ Comments __________________________________________________ Check the boxes which indicate your order type: ___ I wish to register RTAG ($20). ___ I wish to order Mathplot ($20). ___ I wish to order Nonlin ($25) Add $5 to the total amount of the order if the software is being shipped out of the United States. I cannot accept checks from non-US banks. Visa, MasterCard and American Express credit card charges are accepted but a check, money order, or cash is preferred. If you wish to use a credit card specify the billing name, address, card number, and expiration date. In return for registering, you will receive the most recent version of the program, a laser-printed, bound copy of the manual, and three months of telephone or CompuServe support. Your registration fee will be refunded if you find a serious bug that cannot be corrected. Distribution disk choice (check one): 3.50" HD (1.4 MB) ______ 5.25" HD (1.2 MB) ______ 5.25" DD (360 KB) ______ Send this form with the amount indicated to the author: Phillip H. Sherrod 4410 Gerald Place Nashville, TN 37205-3806 USA 615-292-2881 (evenings) CompuServe: 76166,2640 Internet: 76166.2640@compuserve.com Index 36 ABS function, 10 FLOOR function, 10 ACOS function, 10 FOR statement, 20 AND operator, 9 GAMMA function, 11 Arithmetic operators, 8 GRAPHDEV forum, 5 Array variables, 16 IF statement, 18 ASIN function, 10 #include statement, 1 ASP, 30 INT function, 11 Assignment operator, 18 Internet, 34 Assignment operators, 9 /L option, 6, 17 ATAN function, 10 lastframe variable, 16, 26 Auxiliary data files, 24 LINEAR function, 11, 13 /B option, 6 Listing file, 17 Batch file, 17 LOG function, 11 Batch jobs, 33 LOG10 function, 11 Berry, Bob, 4 Logical operators, 9 BFILE statement, 17 Mason, David K., 4 BOB, 4 Mathplot, 32 BOUNC.POV example, 29 MAX function, 11 BREAK statement, 19, 20 MIN function, 11 Bulletin boards, 5 MOD function, 11 BWRITE function, 17, 21, 27 MOREDATA function, 11, 25 CEIL function, 10 Multi-user operating system, CLOSE function, 10, 25 33 Comments, 15 /N option, 6 Comparison operators, 9 Networking, 34 CompuServe, 34 NEXTFRAME statement, 18, 23, Constants, 9 26, 27 CONTINUE statement, 19, 21 Nonlin, 32 Copyright notice, 30 Nonlinear regression, 32 COS function, 10 NOT operator, 9 Cosecant function, 10 NPD function, 11 COSH function, 10 Numeric constants, 9 COT function, 10 /O option, 6 Coy, Stephen, 4 OFILE statement, 17, 23, 26 CREATE function, 10, 25, 26 OPEN function, 12, 24 Crocker, Daniel, 4 Operators CSC function, 10 arithmetic, 8 CSHOW, 4 assignment, 9 curframe variable, 16, 26 comparison, 9 Curve fitting, 32 logical, 9 DEG function, 10 precedence of, 9 Disclaimer, 31 OR operator, 9 DO statement, 19 ORBIT.POV example, 29 DPMI support, 33 Order form, 35 DTA, 4 OWRITE function, 21, 27 Enzmann, Alexander R., 4 /P option, 7 EPILOG statement, 23, 27 PAREA function, 12 Example animations, 29 PI constant, 10 EXP function, 10 Piclab, 4 Exponential, 10 PLAY.EXE, 5 /F option, 6, 17 Polyray, 4 FAC function, 10 POV-Ray, 4 Finlay, Mark, 4 Precedence of operators, 9 firstframe variable, 16, 26 PRINTF function, 12, 21, 27 FLI file, 4 PULSE function, 12 Index 37 RAD function, 12 RANDOM function, 12, 17 READ function, 12, 25 Real-time, 33 Redirection operator, 3 Registering RTAG, 30 Registration form, 35 Regression analysis, 32 Relational operators, 9 ROUND function, 12 /S option, 7, 17 S&H Computer Systems, Inc., 34 SEC function, 12 SEL function, 12 Sherrod, Phillip H., 30 SIN function, 12 SINH function, 12 SPLINE function, 12, 13, 14 SQRT function, 13 srand variable, 16, 17 STEP function, 13 stepinc variable, 16, 26, 27 Stone Soup Group, 4 STOP statement, 21 SUBCHAR statement, 22 Subscripts, 16 Syntax, 15 /T option, 7 TAN function, 13 TANH function, 13 Targa files, 4 TCP/IP, 34 Time control, 28 TOUR.POV example, 29 Trilobyte, 5 TSX-32, 33 TSX-Lite, 33 VAR statement, 15 Warranty, 31 Watkins, Christopher, 4 Wells, Drew, 4 WHILE statement, 19 WRITE function, 13, 26, 27 X windows, 33