home *** CD-ROM | disk | FTP | other *** search
/ Computerspiele Selbermachen / computerspieleselbermachen.iso / rtag / rtag.doc < prev    next >
Text File  |  1993-04-05  |  96KB  |  2,051 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                       R T A G
  7.  
  8.  
  9.  
  10.                           Ray Tracing Animation Generator
  11.  
  12.                                A "shareware" program
  13.  
  14.  
  15.  
  16.  
  17.                                  Phillip H. Sherrod
  18.  
  19.                 Member, Association of Shareware Professionals (ASP)
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.               RTAG is a program to facilitate the  generation  of  ray
  27.               traced  animations.   RTAG is not a ray tracing program;
  28.               rather, it  enables  you  to  generate  the  appropriate
  29.               position  of  objects  to produce an animation using the
  30.               ray tracing program of your  choice.   RTAG  compiles  a
  31.               programming  language designed for animation generation.
  32.               This  programming  language  contains  full   arithmetic
  33.               expressions,  conditional  control,  looping, I/O, and a
  34.               rich set of  library  functions  including  spline  path
  35.               generation.   The  output of RTAG is a set of files that
  36.               can be used  to  drive  ray  tracing  programs  such  as
  37.               POV-Ray,  or  other ray tracers, to produce an image for
  38.               each frame.
  39.  
  40.  
  41.  
  42.  
  43.  
  44.                                  Table of Contents
  45.  
  46.  
  47.  
  48.          1. Introduction . . . . . . . . . . . . . . . . . . . . . . . .  1
  49.            1.1 Ray Tracing Driver Files  . . . . . . . . . . . . . . . .  1
  50.            1.2 Files Produced by RTAG  . . . . . . . . . . . . . . . . .  3
  51.              1.2.1 Include Files . . . . . . . . . . . . . . . . . . . .  3
  52.              1.2.2 Batch File  . . . . . . . . . . . . . . . . . . . . .  3
  53.              1.2.3 Auxiliary Files . . . . . . . . . . . . . . . . . . .  4
  54.              1.2.4 Listing File  . . . . . . . . . . . . . . . . . . . .  4
  55.            1.3 Auxiliary Programs  . . . . . . . . . . . . . . . . . . .  4
  56.              1.3.1 Ray Tracing Program . . . . . . . . . . . . . . . . .  4
  57.              1.3.2 GIF Generator . . . . . . . . . . . . . . . . . . . .  4
  58.              1.3.3 Scene Viewer  . . . . . . . . . . . . . . . . . . . .  4
  59.              1.3.4 Animation Sequencer . . . . . . . . . . . . . . . . .  5
  60.              1.3.5 Animation Display . . . . . . . . . . . . . . . . . .  5
  61.            1.4 Ray Tracing Bulletin Boards . . . . . . . . . . . . . . .  5
  62.  
  63.          2. Running RTAG . . . . . . . . . . . . . . . . . . . . . . . .  6
  64.            2.1 The RTAG Animation Control File . . . . . . . . . . . . .  7
  65.            2.2 Arithmetic and Logical Expressions  . . . . . . . . . . .  8
  66.              2.2.1 Numeric Constants . . . . . . . . . . . . . . . . . .  9
  67.              2.2.2 Built-in Constant . . . . . . . . . . . . . . . . . . 10
  68.              2.2.3 Built in Functions  . . . . . . . . . . . . . . . . . 10
  69.              2.2.4 Notes on the SPLINE and LINEAR Functions  . . . . . . 13
  70.  
  71.          3. The Animation Control Language . . . . . . . . . . . . . . . 15
  72.            3.1 Comments  . . . . . . . . . . . . . . . . . . . . . . . . 15
  73.            3.2 Basic Statement Syntax  . . . . . . . . . . . . . . . . . 15
  74.            3.3 Declaration of Variables (VAR Statement)  . . . . . . . . 15
  75.            3.4 Output File Declarations  . . . . . . . . . . . . . . . . 17
  76.            3.5 Assignment Statement  . . . . . . . . . . . . . . . . . . 18
  77.            3.6 IF Statement  . . . . . . . . . . . . . . . . . . . . . . 18
  78.            3.7 WHILE Statement . . . . . . . . . . . . . . . . . . . . . 19
  79.            3.8 DO Statement  . . . . . . . . . . . . . . . . . . . . . . 19
  80.            3.9 FOR Statement . . . . . . . . . . . . . . . . . . . . . . 19
  81.            3.10 BREAK Statement  . . . . . . . . . . . . . . . . . . . . 20
  82.            3.11 CONTINUE Statement . . . . . . . . . . . . . . . . . . . 20
  83.            3.12 STOP Statement . . . . . . . . . . . . . . . . . . . . . 21
  84.            3.13 WRITE functions  . . . . . . . . . . . . . . . . . . . . 21
  85.            3.14 SUBCHAR Statement  . . . . . . . . . . . . . . . . . . . 22
  86.            3.15 NEXTFRAME Statement  . . . . . . . . . . . . . . . . . . 22
  87.            3.16 EPILOG Statement . . . . . . . . . . . . . . . . . . . . 23
  88.            3.17 Self-continuing Batch Files  . . . . . . . . . . . . . . 23
  89.            3.18 Auxiliary Data Files . . . . . . . . . . . . . . . . . . 24
  90.              3.18.1 Opening a File for Reading . . . . . . . . . . . . . 24
  91.              3.18.2 Creating an Output File  . . . . . . . . . . . . . . 24
  92.              3.18.3 Closing an Auxiliary File  . . . . . . . . . . . . . 24
  93.              3.18.4 Reading from an Auxiliary File . . . . . . . . . . . 25
  94.              3.18.5 Writing to an Auxiliary File . . . . . . . . . . . . 25
  95.  
  96.  
  97.                                          i
  98.  
  99.          Contents                                                        ii
  100.  
  101.  
  102.            3.19 Notes About the System Variables . . . . . . . . . . . . 26
  103.  
  104.          4. Animation and Time Control . . . . . . . . . . . . . . . . . 28
  105.  
  106.          5. Example Animations . . . . . . . . . . . . . . . . . . . . . 29
  107.  
  108.          6. Use and Distribution of RTAG . . . . . . . . . . . . . . . . 30
  109.            6.1 Copyright Notice  . . . . . . . . . . . . . . . . . . . . 30
  110.            6.2 Disclaimer  . . . . . . . . . . . . . . . . . . . . . . . 31
  111.  
  112.          7. Other Software . . . . . . . . . . . . . . . . . . . . . . . 32
  113.            7.1 Mathplot  . . . . . . . . . . . . . . . . . . . . . . . . 32
  114.            7.2 Nonlin  . . . . . . . . . . . . . . . . . . . . . . . . . 32
  115.            7.3 TSX-32 Operating System . . . . . . . . . . . . . . . . . 32
  116.  
  117.          8. Software Order Form  . . . . . . . . . . . . . . . . . . . . 34
  118.  
  119.          Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                                      Chapter 1
  127.  
  128.                                     Introduction
  129.  
  130.  
  131.  
  132.  
  133.          An animation is composed  of  a  sequence  of  individual  images,
  134.          called  "frames," which are displayed rapidly to give the illusion
  135.          of motion.  Anyone who sets out to create an animation  must  deal
  136.          with  two  design  issues:  (1)  the generation of the basic scene
  137.          (objects, colors, lights, etc.), and (2) the changing position  of
  138.          the  objects  between frames.  RTAG deals with the second of these
  139.          issues -- object motion.  The first issue, basic scene design  and
  140.          rendering,  is  carred  out  by  the  ray  tracing program of your
  141.          choice (POV-Ray, Polyray, BOB, etc.).
  142.  
  143.          RTAG  reads  an  animation  control  file  that  you  create   and
  144.          generates  one  or  more  files  that  automate  the  rendering of
  145.          individual frames and the construction of the animation  sequence.
  146.          The animation control file is the focus of this manual.
  147.  
  148.          RTAG  implements an animation language with a syntax similar to C.
  149.          Although simple in comparison to full featured languages  such  as
  150.          C  and Pascal, the RTAG language is far from trivial.  It provides
  151.          full arithmetic and logical expressions, control statements  (IF),
  152.          loop  statement  (FOR,  WHILE,  and  DO),  a  rich  set of library
  153.          functions (trig, log, roots, spline,  etc.),  and  statements  for
  154.          writing  commands  to  the  output  files  which  will  be used to
  155.          generate the frames.  Using the  RTAG  language  you  can  perform
  156.          realistic    simulations    of    physical   processes   such   as
  157.          accelerations, falling objects, and interactions between  objects.
  158.          RTAG also can be used as a general purpose programming language.
  159.  
  160.          1.1 Ray Tracing Driver Files
  161.  
  162.          The  basic purpose of RTAG is to produce a set of files which will
  163.          cause ray tracing programs such as POV-Ray, Polyray,  Vivid,  BOB,
  164.          and  other  ray  tracers to generate the sequence of frames for an
  165.          animation.
  166.  
  167.          All ray tracers accept some sort  of  scene  description  file  in
  168.          which  you  specify  the  position  of  objects, colors, textures,
  169.          camera angle, etc.  With rare exception, one run of a  ray  tracer
  170.          with  one  scene description produces one image file.  In order to
  171.          produce an animation you must run the ray  tracer  once  for  each
  172.          frame  and  vary the position of the objects and/or camera between
  173.          frames to produce the illusion of motion.   This  means  that  the
  174.          scene   description   file  must  be  different  for  each  frame.
  175.          Fortunately,  all  good  ray  tracers  provide  a   facility   for
  176.  
  177.  
  178.                                          1
  179.  
  180.          Chapter 1. Introduction                                          2
  181.  
  182.  
  183.          including  one  or  more external files while processing the scene
  184.          description.  In the case of POV-Ray  this  is  accomplished  with
  185.          the  "#include" statement.  Other tracers have similar statements.
  186.          Using this facility you can have a common scene  description  file
  187.          and  place  only  the commands to describe the positions of moving
  188.          objects in a separate file that is included  in  the  scene.   For
  189.          example, consider this simple POV-Ray scene description file:
  190.  
  191.              #include "colors.inc"
  192.              #include "shapes.inc"
  193.              #include "move.inc"
  194.              camera {
  195.                  location <.5 1 -22> direction <0 0 1.5>
  196.                  up <0 1 0> right <1.33 0 0> look_at <0 4 0>
  197.              }
  198.              object { light_source { <6 15 -4> color White} }
  199.              object {
  200.                  sphere { <xpos ypos 0> .5}
  201.                  texture { color red .9 green 0 blue .1 ambient .8 }
  202.              }
  203.  
  204.          This  scene  has a camera, a single light source, and a ball.  The
  205.          position of the ball is specified as  "<xpos  ypos  0>"  but  note
  206.          that  xpos  and  ypos  are  not  defined in the file.  Rather, the
  207.          values of xpos and ypos are  defined  in  a  separate  file  named
  208.          "move.inc"  that in included in this scene.  Typical statements in
  209.          move.inc are as follows:
  210.  
  211.              #declare xpos = 3
  212.              #declare ypos = 4
  213.  
  214.          To simulate motion of  the  ball  you  would  prepare  a  separate
  215.          move.inc  file  for  each  frame  with slightly altered values for
  216.          xpos and ypos.  Since there will  be  an  include  file  for  each
  217.          frame,  they  are  typically  given  names  containing  the  frame
  218.          numbers such as  "MOVE001.INC",  "MOVE002.INC",  etc.   A  primary
  219.          purpose  of  RTAG  is  to automate the generation of these include
  220.          files.
  221.  
  222.          In addition to a scene description file  and  a  separate  include
  223.          file  for  each frame, you also need a DOS batch file to cause the
  224.          ray tracing program to be run for each  frame.   RTAG  also  helps
  225.          you produce this file.
  226.  
  227.          For  each  frame,  the batch file will contain commands to perform
  228.          the following operations:
  229.  
  230.            . Make the appropriate include file  the  current  include  file
  231.              for the next image generation.
  232.  
  233.            . Execute  the  ray tracing program which will generate an image
  234.              based on frame-dependent data in the current include file.
  235.  
  236.            . Additional commands  to  delete  intermediate  files  or  pack
  237.              together the frame files.
  238.  
  239.          Chapter 1. Introduction                                          3
  240.  
  241.  
  242.          Typical commands written to the batch file for a frame are:
  243.  
  244.              COPY MOVE001.INC MOVE.INC
  245.              POVRAY +iMOVE.POV +oMOVE.TGA
  246.  
  247.          Rather  than  having RTAG produce a separate include file for each
  248.          frame (which can end  up  being  a  lot  of  files),  it  is  also
  249.          possible  to write commands to the batch file to cause the include
  250.          file to be created just before it is needed  by  the  ray  tracing
  251.          program.   To  do  this,  use  the  DOS  ECHO command with the ">"
  252.          redirection operator to create the file and the ">>"  operator  to
  253.          add  additional commands to the file.  The following is an example
  254.          of commands that create an include file named MOVE.INC, write  two
  255.          commands into it, and then call POV-Ray to render the image:
  256.  
  257.              ECHO #declare xpos = 2.5 > move.inc
  258.              ECHO #declare ypos = 8.6 >> move.inc
  259.              POVRAY +iMOVE.POV +oMOVE.TGA
  260.  
  261.          Note  that  the  ">" redirection operator creates a new file so it
  262.          should be used with the first ECHO command for  each  frame.   The
  263.          ">>"  redirection  operator  appends  to  the  end of a file so it
  264.          should be used for additional ECHO commands for the frame.
  265.  
  266.          To summarize, there are two  methods  for  producing  the  include
  267.          file  for  a  frame: (1) have RTAG generate a separate file with a
  268.          unique name that is copied (or renamed) to the name  used  by  the
  269.          #include  statement; or (2) use ECHO commands in the batch file to
  270.          generate the include file just before  invoking  the  ray  tracing
  271.          program for the frame.
  272.  
  273.          1.2 Files Produced by RTAG
  274.  
  275.          1.2.1 Include Files
  276.  
  277.          If  you  wish  to  have  RTAG generate a separate include file for
  278.          each frame, you must use an OFILE  command  to  declare  the  file
  279.          name.   The name must include one or more '#' characters which are
  280.          replaced by the frame number to generate the actual  include  file
  281.          name.   The  NEXTFRAME  statement  increments the frame number and
  282.          opens the next include file being created.   OWRITE  commands  are
  283.          used to write information to the currently open include file.
  284.  
  285.          If  you  create  the  include file by writing ECHO commands to the
  286.          batch file, then you will NOT use the OFILE and OWRITE  statements
  287.          which  cause  RTAG  to  generate  a separate include file for each
  288.          frame.
  289.  
  290.          1.2.2 Batch File
  291.  
  292.          This is a  DOS  batch  (.BAT)  file  containing  the  commands  to
  293.          perform  the  following  operations  for  each frame: (1) make the
  294.          appropriate include file the current include  file  for  the  next
  295.          image  generation  (or generate the include file); (2) execute the
  296.          ray  tracing  program  which  will  generate  an  image  based  on
  297.  
  298.          Chapter 1. Introduction                                          4
  299.  
  300.  
  301.          frame-dependent  data  in the current include file; (3) additional
  302.          commands to delete intermediate files or pack together  the  frame
  303.          files.   Use  BWRITE  statements  in your control file to write to
  304.          the batch file.  The BFILE statement  declares  the  name  of  the
  305.          batch  file.   This  file  is not created unless you use the BFILE
  306.          and BWRITE commands.
  307.  
  308.          1.2.3 Auxiliary Files
  309.  
  310.          RTAG includes statements for opening, creating, reading from,  and
  311.          writing  to auxiliary files.  Auxiliary input files can be used to
  312.          transfer animation data from other programs to RTAG.  One  use  of
  313.          an  auxiliary  output  file is to store the names of the generated
  314.          targa or GIF files so that a subsequent program such  as  DTA  can
  315.          read  this file to determine which files to string together in the
  316.          final animation file.
  317.  
  318.          1.2.4 Listing File
  319.  
  320.          This file has the same name as the animation control file  but  an
  321.          extension  of  ".LST".   It  contains the same output displayed by
  322.          RTAG on the screen during an animation generation  run.   You  can
  323.          use  PRINT  statements within your control file to write output to
  324.          the screen and the listing file.
  325.  
  326.          1.3 Auxiliary Programs
  327.  
  328.          RTAG is one component in the set of  programs  needed  to  produce
  329.          and  display  an animation.  In addition to RTAG you will need the
  330.          following programs:
  331.  
  332.          1.3.1 Ray Tracing Program
  333.  
  334.          There are several excellent  ray  tracing  programs  available  as
  335.          freeware  or  shareware.   Three programs with which I am familiar
  336.          are POV-Ray (freeware) by Drew Wells and the POV team  (CompuServe
  337.          73767,1244);   Polyray   (shareware)   by  Alexander  R.   Enzmann
  338.          (CompuServe 70323,2461); and BOB by Christopher  Watkins,  Stephen
  339.          Coy,   and   Mark   Finlay   (included  with  the  excellent  book
  340.          "Photorealism and Ray Tracing in C").
  341.  
  342.          1.3.2 GIF Generator
  343.  
  344.          Most ray tracing  programs  output  "targa"  files  which  contain
  345.          higher  resolution  images  than  usually can be displayed.  These
  346.          targa files must be converted into  GIF  or  other  image  formats
  347.          before  they  can  be  displayed.   One  fine freeware program for
  348.          doing this is Piclab by Lee Daniel  Crocker  and  the  Stone  Soup
  349.          Group (CompuServe 73407,2030).
  350.  
  351.          1.3.3 Scene Viewer
  352.  
  353.          When  designing a scene you will need a program to display the TGA
  354.          or GIF file for an individual frame of the animation.   There  are
  355.  
  356.          Chapter 1. Introduction                                          5
  357.  
  358.  
  359.          many  programs  available  to do this.  A popular shareware choice
  360.          is CSHOW by Bob Berry (CompuServe 76555,167).
  361.  
  362.          1.3.4 Animation Sequencer
  363.  
  364.          Once the individual frame images have been  generated,  they  must
  365.          be  combined  into a single file that can be displayed rapidly.  A
  366.          shareware program which I use for  this  is  DTA  (you  also  need
  367.          DTAMEM)  by  David  K.   Mason (CompuServe 76546,1321).  DTA reads
  368.          the targa or GIF files produced by the ray tracer and  produces  a
  369.          .FLI (flick) file that can be displayed as an animation.
  370.  
  371.          1.3.5 Animation Display
  372.  
  373.          This  program reads the finished animation file and displays it on
  374.          your screen.  A popular  shareware  program  for  displaying  .FLI
  375.          files is PLAY.EXE by Trilobyte (CompuServe 72330,3276).
  376.  
  377.          1.4 Ray Tracing Bulletin Boards
  378.  
  379.          These  programs,  and  many  others  related  to  ray  tracing and
  380.          animation, are  available  in  the  libraries  of  the  CompuServe
  381.          GRAPHDEV  forum.   This  is  also  an  excellent place for posting
  382.          messages or getting help regarding ray tracing and animation.
  383.  
  384.          Two bulletin boards which specialize in graphics  development  are
  385.          "You   Can   Call   Me   Ray,"  708-358-5611;  and  "The  Graphics
  386.          Alternative," 510-524-2780.
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                      Chapter 2
  394.  
  395.                                     Running RTAG
  396.  
  397.  
  398.  
  399.  
  400.          Once you create an RTAG control file, you can use RTAG to  compile
  401.          and execute it by issuing a DOS command of the form:
  402.  
  403.              RTAG control_file [option1] [option2]...
  404.  
  405.          where  "control_file" is the name of the control file.  If no file
  406.          extension is specified, ".RTA" is used by default.
  407.  
  408.          Following the control  file  name  you  may  specify  the  options
  409.          described  below.   If more than one option is provided, they must
  410.          be  separated  by  spaces.   The  option  letters  are  not   case
  411.          sensitive.   Values  specified  with command line options override
  412.          the corresponding values specified in the control file.
  413.  
  414.            . /B=file -- Specifies the name of the batch  file.   The  batch
  415.              file  name  can  also  be specified using a BFILE statement in
  416.              your control file.  The default extension is ".BAT".
  417.  
  418.            . /F=number -- Specifies the first  frame  that  is  to  produce
  419.              output.    Output   generated   with  the  BWRITE  and  OWRITE
  420.              functions is discarded for frames prior to this  number.   The
  421.              default value is 1.
  422.  
  423.            . /L=number  --  Specifies  the  last  frame  that is to produce
  424.              output.   Output  generated  with  the   BWRITE   and   OWRITE
  425.              functions  is  discarded for frames following this number.  By
  426.              default,  there  is  no  last  frame  (i.e.,  all  frames  are
  427.              output).
  428.  
  429.            . /N  --  Specifies that no output is to be written to the batch
  430.              and include files.  This is useful when you are  debugging  an
  431.              animation  control file and want to test it without generating
  432.              the output  files.   Output  generated  by  PRINTF  and  WRITE
  433.              functions   always   is   written,  even  if  this  option  is
  434.              specified.
  435.  
  436.            . /O=file -- Specifies the name of the include  files  generated
  437.              during  the  run.   Include file names must include the string
  438.              '###' (1 to 5 '#' characters) which is replaced by  the  frame
  439.              number.   The  output  file  names can also be specified by an
  440.              OFILE statement in your control file.  The  default  extension
  441.              is ".INC".
  442.  
  443.  
  444.  
  445.                                          6
  446.  
  447.          Chapter 2. Running RTAG                                          7
  448.  
  449.  
  450.            . /P  --  Causes  the  entire  control  file to be listed on the
  451.              screen and written to the listing file.  Normally  only  error
  452.              messages   and  output  generated  by  PRINTF  statements  are
  453.              displayed.
  454.  
  455.            . /S=number -- Specifies the  number  of  steps  between  frames
  456.              whose  output  is  to  be  generated.  Output is discarded for
  457.              frames between the step frames if a  value  other  than  1  is
  458.              specified.   The  default value is 1.  If stepping is enabled,
  459.              the first frame is generated and then frames  are  skipped  up
  460.              to   first+step.    The  sequence  continues  with  subsequent
  461.              frames.  This option is useful for  producing  an  abbreviated
  462.              set of frames for evaluation and debugging purposes.
  463.  
  464.            . /T  -- Specifies that each source statement is to be displayed
  465.              before  it  is  executed.   This  is  useful   for   debugging
  466.              purposes.
  467.  
  468.          2.1 The RTAG Animation Control File
  469.  
  470.          RTAG  reads  an  animation  control file that you create, compiles
  471.          the commands, and executes the resulting  program.   The  commands
  472.          in  the  control  file are formed from the RTAG animation language
  473.          which is described in the sections that follow.   However,  before
  474.          getting  into  a  detailed  discussion  of the animation language,
  475.          let's look at a simple example to get a feeling for the  language.
  476.          This  example  is a complete RTAG command file which will generate
  477.          the appropriate commands to move an object on a spline  path  that
  478.          passes through a specified set of x,y,z coordinates:
  479.  
  480.          Chapter 2. Running RTAG                                          8
  481.  
  482.  
  483.              //  Simple animation example.
  484.              //  Declare variables
  485.              var lastframe = 60;      // Generate 60 frames
  486.              var x,y,z;
  487.              //  Declare files
  488.              bfile "move";              // Batch file MOVE.BAT
  489.              //  Begin main animation loop to generate 60 frames.
  490.              while (curframe < lastframe) {
  491.                  //  Begin the next frame (this increments curframe)
  492.                  nextframe;
  493.                  //  Use spline function to compute x,y,z position.
  494.                  x = spline(curframe, 1,-8, 20,0, 40,5, 60,8);
  495.                  y = spline(curframe, 1,1,  20,5, 40,5, 60,1);
  496.                  z = spline(curframe, 1,0,  20,4, 40,6, 60,10);
  497.                  //  Report the position
  498.                  printf("At frame `curframe`, x=`x`, y=`y`, z=`z`\n");
  499.                  //  Write commands to the batch file.
  500.                  //  These commands create a move.inc include file.
  501.                  bwrite("ECHO #declare xpos = `x` > move.inc\n");
  502.                  bwrite("ECHO #declare ypos = `y` >> move.inc\n");
  503.                  bwrite("ECHO #declare zpos = `z` >> move.inc\n");
  504.                  //  Generate command to render the image.
  505.                  bwrite("call render move move`###`\n");
  506.              }
  507.              //  Write final command that runs DTA to build the animation.
  508.              epilog;
  509.              bwrite("call dta move\n");
  510.  
  511.          2.2 Arithmetic and Logical Expressions
  512.  
  513.          Much  of  the  power  of  RTAG  comes  from its ability to perform
  514.          mathematical calculations.  This is  important  for  any  type  of
  515.          animation  generation,  but  is  especially  critical for physical
  516.          system  simulations.   This  section   explains   the   arithmetic
  517.          operators  and  built  in functions that may be used in arithmetic
  518.          expressions.
  519.  
  520.          The following arithmetic operators may be used in expressions:
  521.  
  522.              ++       add 1 to a variable
  523.              --       subtract 1 from a variable
  524.              +        addition
  525.              -        subtraction or unary minus
  526.              *        multiplication
  527.              /        division
  528.              %        modulo
  529.              ** or ^  exponentiation
  530.  
  531.          The "++" and "--" operators may be used either immediately  before
  532.          or  after  a variable name.  If they are used before the name, the
  533.          increment or decrement  is  performed  before  the  value  of  the
  534.          variable  is  used  in the expression.  If they are used after the
  535.          name, the value of the variable before being modified is  used  in
  536.          the  expression  and  then the increment or decrement takes place.
  537.          For example, the sequence:
  538.  
  539.          Chapter 2. Running RTAG                                          9
  540.  
  541.  
  542.              a = 3;
  543.              b = 3;
  544.              x = ++a;
  545.              y = b++;
  546.  
  547.          assigns the value 4 to x and 3 to y.  At the end of the  sequence,
  548.          both a and b have the value 4.
  549.  
  550.          The following assignment operators can be used in expressions:
  551.  
  552.              variable = expression;    // Assign expression to variable
  553.              variable += expression;   // Add expression to variable
  554.              variable -= expression;   // Subtract expression from variable
  555.              variable *= expression;   // Multiply variable by expression
  556.              variable /= expression;   // Divide variable by expression
  557.  
  558.          The  following operators compare two values and produce a value of
  559.          1 if the comparison is true, or 0 if the comparison is false:
  560.  
  561.              ==   Equal
  562.              !=   Not equal
  563.              <=   Less than or equal
  564.              >=   Greater than or equal
  565.              <    Less than
  566.              >    Greater than
  567.  
  568.          The following logical operators may be used:
  569.  
  570.              !    Logical NOT (negates true and false)
  571.              &&   AND
  572.              ||   OR
  573.  
  574.          There are two other  special  operators:  "[]"  (square  brackets)
  575.          which  enclose subscripts on arrays, and "," (comma) which is used
  576.          to specify left-to-right,  sequential  evaluation  of  a  list  of
  577.          expressions.
  578.  
  579.          Operator   precedence,   in   decreasing  order,  is  as  follows:
  580.          subscript, unary minus, logical NOT, ++  and  --,  exponentiation,
  581.          multiplication,  division  and  modulo,  addition and subtraction,
  582.          relational (comparison), logical (AND and OR), assignment,  comma.
  583.          Parentheses may be used to group terms.
  584.  
  585.          2.2.1 Numeric Constants
  586.  
  587.          Numeric  constants  may  be  written  in their natural form (1, 0,
  588.          1.5, .0003, etc.) or in exponential form, n.nnnEppp,  where  n.nnn
  589.          is  the  base  value and ppp is the power of ten by which the base
  590.          is multiplied.  For example, the number  1.5E4  is  equivalent  to
  591.          15000.   All  numbers  are  treated  as  "floating  point" values,
  592.          regardless of whether a decimal point is specified or not.   As  a
  593.          convenience  for  entering time values, if a value contains one or
  594.          more colons, the portion to the left of the  colon  is  multiplied
  595.          by  60.   For  example,  1:00  is  equivalent  to  60;  1:00:00 is
  596.          equivalent to 3600.
  597.  
  598.          Chapter 2. Running RTAG                                         10
  599.  
  600.  
  601.          2.2.2 Built-in Constant
  602.  
  603.          The  symbolic  name  "PI"  is  equivalent  to  the  value  of  pi,
  604.          3.14159...  You may write PI using either upper or lower case.
  605.  
  606.          2.2.3 Built in Functions
  607.  
  608.          The  following  functions  are  built into RTAG and may be used in
  609.          expressions:
  610.  
  611.          ABS(x) -- Absolute value of x.
  612.  
  613.          ACOS(x) -- Arc cosine of x.  Angles are measured in degrees.
  614.  
  615.          ASIN(x) -- Arc sine of x.  Angles are measured in degrees.
  616.  
  617.          ATAN(x) -- Arc tangent of x.  Angles are measured in degrees.
  618.  
  619.          CEIL(x) -- Ceiling of x (an equivalent name for this  function  is
  620.          INT).   Returns  the smallest integer that is at least as large as
  621.          x.  For example, CEIL(1.5)=2; CEIL(4)=4; CEIL(-2.6)=-2.
  622.  
  623.          CLOSE(file) -- Close the specified file.
  624.  
  625.          COS(x) -- Cosine of x.  Angles are measured in degrees.
  626.  
  627.          COSH(x) -- Hyperbolic cosine of x.
  628.  
  629.          COT(x)  --  Cotangent  of  x.   (COT(x)  =  1/TAN(x)).   Angle  in
  630.          degrees.
  631.  
  632.          CREATE("file  name")  --  Create  a  new auxiliary data file.  The
  633.          value returned by this function is a file number that can be  used
  634.          with   subsequent   WRITE   functions.   See  the  description  of
  635.          auxiliary file I/O for additional information.
  636.  
  637.          CSC(X) -- Cosecant of x.  (CSC(x) = 1/SIN(x)).  Angle in degrees.
  638.  
  639.          DEG(x) -- Converts  an  angle,  x,  measured  in  radians  to  the
  640.          equivalent number of degrees.
  641.  
  642.          EXP(x) -- e (base of natural logarithms) raised to the x power.
  643.  
  644.          FAC(x)  --  x  factorial (x!).  The FAC function is computed using
  645.          the GAMMA function  (FAC(x)=GAMMA(x+1))  so  non-integer  argument
  646.          values may be computed.
  647.  
  648.          FLOOR(x)  -- Floor of x.  Returns the largest integer that is less
  649.          than or  equal  to  x.   For  example,  FLOOR(2.5)=2;  FLOOR(4)=4;
  650.          FLOOR(-3.6)=-4.
  651.  
  652.          GAMMA(x)   --   Gamma   function.    Note,  GAMMA(x+1)  =  x!   (x
  653.          factorial).
  654.  
  655.          Chapter 2. Running RTAG                                         11
  656.  
  657.  
  658.          INT(x) -- Ceiling of x (an equivalent name for  this  function  is
  659.          CEIL).   Returns the smallest integer that is at least as large as
  660.          x.  For example, INT(1.5)=2; INT(4)=4; INT(-2.6)=-2.
  661.  
  662.          LINEAR(t,  t1,x1,   t2,x2,   ...    tn,xn)   --   Perform   linear
  663.          interpolation  between  a  set  of  points.   If  the  value  of a
  664.          function is x1 at some point t1, x2 at  t2,  etc.,  this  function
  665.          determines  the value at some arbitrary point, t, where t falls in
  666.          the range (t1,tn).  The first argument to the LINEAR  function  is
  667.          the  value  t  at which the interpolation is to be performed.  The
  668.          remaining  arguments  are  (ti,xi)  data  pairs.    For   example,
  669.          consider  the  function  LINEAR(t, 0,0, 1,6, 2,4).  This specifies
  670.          that when t is 0, the value of the function is 0,  when  t  is  1,
  671.          the  value is 6, and when t is 2 the value is 4.  If this function
  672.          is called with a t  value  of  0.5,  the  returned  value  of  the
  673.          function  will  be 3.  If the function is called with a t value of
  674.          1.5, the returned value will be 5.  You  can  use  expressions  as
  675.          arguments  to  this function.  For example, the following function
  676.          invocation is valid: LINEAR(t, starttime,basex,  starttime+3,midx,
  677.          endtime,midx*2).   If  the  function is called with a t value that
  678.          is outside the range (t1,tn)  (i.e.,  beyond  either  end  point),
  679.          then  the  nearest end point and the second closest point are used
  680.          to  extrapolate  to  the  specified  t  value.    See   also   the
  681.          description of the SPLINE function.
  682.  
  683.          LOG(x) -- Natural logarithm of x.
  684.  
  685.          LOG10(x) -- Base 10 logarithm of x.
  686.  
  687.          MAX(x1,x2) -- Maximum value of x1 or x2.
  688.  
  689.          MIN(x1,x2) -- Minimum value of x1 or x2.
  690.  
  691.          MOD(x1,x2)  --  x1  modulo  x2.   The  MOD function calculates the
  692.          floating-point remainder, f, of  x1/(i*x2)  such  that  x1=i*x2+f,
  693.          where  i  is  an  integer;  f  has  the  same  sign as x1, and the
  694.          absolute value of f is less than the absolute value of x2.  The  %
  695.          operator perform the same operation.
  696.  
  697.          MOREDATA(file)  -- This function checks to see if there is another
  698.          data record available in the external file whose  file  number  is
  699.          specified  as  the argument.  If there is a record available, this
  700.          function returns the value true (1),  if  not,  it  returns  false
  701.          (0).   This  function  does  not consume any data in the file, you
  702.          must use the READ statement to  actually  read  the  next  record.
  703.          You  can  call MOREDATA any number of times without disturbing the
  704.          next record in the file.  See the section on  auxiliary  file  I/O
  705.          for additional information.
  706.  
  707.          NPD(x,mean,std)  --  Normal  probability  distribution  of  x with
  708.          specified mean and standard deviation.  X is in units of  standard
  709.          deviations from the mean.
  710.  
  711.          OPEN("file  name")  --  Open  an  existing  file for reading.  The
  712.          value returned by this function is a file number that can be  used
  713.  
  714.          Chapter 2. Running RTAG                                         12
  715.  
  716.  
  717.          with  subsequent READ functions.  See the description of auxiliary
  718.          file I/O for additional information.
  719.  
  720.          PAREA(x) -- Area under the normal probability  distribution  curve
  721.          from  -infinity  to  x.   (i.e.,  integral  from -infinity to x of
  722.          NORMAL(x)).
  723.  
  724.          PRINTF("format"[,expression1,expression2,...])  --  Evaluate   the
  725.          expressions  (if  any)  and  write  the  values with the specified
  726.          formatting string to the console and the listing file.
  727.  
  728.          PULSE(a,x,b) -- Pulse function.  If the value of x is less than  a
  729.          or  greater  than  b,  the  value  of  the function is 0.  If x is
  730.          greater than or equal to a and less than or equal to b, the  value
  731.          of  the  function  is  1.   In other words, it is 1 for the domain
  732.          (a,b) and zero elsewhere.  If you need a function that is zero  in
  733.          the   domain   (a,b)   and   1   elsewhere,   use  the  expression
  734.          (1-PULSE(a,x,b)).
  735.  
  736.          RAD(x) -- Converts an angle measured in degrees to the  equivalent
  737.          number of radians.
  738.  
  739.          RANDOM()  --  Returns  a random value uniformly distributed in the
  740.          range 0 to 1.  You can use the srand system variable to specify  a
  741.          starting seed.
  742.  
  743.          READ(file,variable1,variable2,...)  --  Read  one  line  from  the
  744.          specified file, scan the input line for  values,  and  assign  the
  745.          values to the specified variables.
  746.  
  747.          ROUND(x)  --  Rounds  x  to  the  nearest  integer.   For example,
  748.          ROUND(1.1)=1; ROUND(1.8)=2; ROUND(-2.8)=-3;
  749.  
  750.          SEC(x) -- Secant of x.  (SEC(x) = 1/COS(x)).  Angle in degrees.
  751.  
  752.          SEL(a1,a2,v1,v2) -- If a1 is less than a2 then the  value  of  the
  753.          function  is  v1.   If a1 is greater than or equal to a2, then the
  754.          value of the function is v2.
  755.  
  756.          SIN(x) -- Sine of x.  Angles are measured in degrees.
  757.  
  758.          SINH(x) -- Hyperbolic sine of x.
  759.  
  760.          SPLINE(t, t1,x1, t2,x2, ...  tn,xn)  --  Perform  a  cubic  spline
  761.          interpolation  between a set of points.  A spline is a smooth path
  762.          (continuous first and second derivatives) that  passes  through  a
  763.          set  of  points.  The SPLINE function is very useful in animations
  764.          because it allows you to easily construct a smooth  path  for  the
  765.          motion of some object (or the camera).
  766.  
  767.          If  the  value  of  a  function  is x1 at some point t1, x2 at t2,
  768.          etc., this function determines the value at some arbitrary  point,
  769.          t,  where t falls in the range (t1,tn).  The first argument to the
  770.          SPLINE function is the value t at which the  interpolation  is  to
  771.          be  performed.   The  remaining  arguments are (ti,xi) data pairs.
  772.  
  773.          Chapter 2. Running RTAG                                         13
  774.  
  775.  
  776.          You can use  expressions  as  arguments  to  this  function.   For
  777.          example,  the  following  function  invocation is valid: SPLINE(t,
  778.          starttime,basex,  starttime+3,midx,   endtime,midx*2).    If   the
  779.          function  is  called  with  a  t  value  that is outside the range
  780.          (t1,tn) (i.e., beyond either end point), then  the  value  of  the
  781.          function  at  the  nearest end point and the slope of the function
  782.          at that point are used to extrapolate in a linear fashion  to  the
  783.          specified  t  value.   See  also  the  description  of  the LINEAR
  784.          function.
  785.  
  786.          SQRT(x) -- Square root of x.
  787.  
  788.          STEP(a,x) -- Step function.  If x is less than  a,  the  value  of
  789.          the  function is 0.  If x is greater than or equal to a, the value
  790.          of the function is 1.  If you need a function which is 1 up  to  a
  791.          certain  value  and  then  0 beyond that value, use the expression
  792.          STEP(x,a).
  793.  
  794.          TAN(x) -- Tangent of x.  Angles are measured in degrees.
  795.  
  796.          TANH(x) -- Hyperbolic tangent of x.
  797.  
  798.          WRITE(file,"format"[,expression1,expression2,...])   --   Evaluate
  799.          the  expressions  (if any) and write the values with the specified
  800.          formatting string to auxiliary output file whose  file  number  is
  801.          specified as the first argument.
  802.  
  803.          2.2.4 Notes on the SPLINE and LINEAR Functions
  804.  
  805.          RTAG  includes two library functions for performing interpolation:
  806.          LINEAR and SPLINE.  If you have two pairs of values,  (t1,x1)  and
  807.          (t2,x2),   these   functions   determine   the  value  of  x  that
  808.          corresponds to some value of t between t1 and  t2.   If  you  have
  809.          more  than  two pairs, the function determines the value of x that
  810.          is on the segment that spans the specified value of t.
  811.  
  812.          The function parameters, t  and  x,  can  represent  any  type  of
  813.          value.   However, in animations t is usually a time value or frame
  814.          number, and x is a position (either in the X, Y, or Z  dimension).
  815.          If  you  want  an  object  to follow a path through a set of three
  816.          dimensional points, you have to use three  statements,  each  with
  817.          an  interpolation  function.   For example, if at frame 1 you want
  818.          an object to be at (-8,0,-3), frame 20 to be  at  (0,5,-1),  frame
  819.          40  to  be  at  (2,2,0),  and  frame 60 to be at (7,4,2), then you
  820.          could use the following statements:
  821.  
  822.              while (curframe <= 60) {
  823.                  nextframe;
  824.                  x = spline(curframe, 1,-8, 20,0,  40,2, 60,7);
  825.                  y = spline(curframe, 1,0,  20,5,  40,2, 60,4);
  826.                  z = spline(curframe, 1,-3, 20,-1, 40,0, 60,2);
  827.                  << other statements >>
  828.              }
  829.  
  830.          Chapter 2. Running RTAG                                         14
  831.  
  832.  
  833.          The spline function will force the object to be at  the  specified
  834.          x,y,z  coordinate  at  frames 1, 20, 40, and 60, and will generate
  835.          intermediate positions between these frames.
  836.  
  837.          While the method explained  above  of  specifying  absolute  frame
  838.          numbers  works  well,  you  will  have to change the values in the
  839.          function specification if you change the total  number  of  frames
  840.          in  the  animation.  A better approach is to use the percentage of
  841.          the total animation as the control values and use  the  expression
  842.          (100*(curframe-1)/(lastframe-1))  to  specify  the  position along
  843.          the path.  Note that the a value must be specified for  lastframe.
  844.          The following program illustrates this approach:
  845.  
  846.              var x,y,z,position;
  847.              var lastframe = 50;     // Animation will have 50 frames
  848.              while (curframe < lastframe) {
  849.                  nextframe;          // This increments curframe
  850.                  position = 100*(curframe-1)/(lastframe-1);
  851.                  x = spline(position, 0,-8, 40,0,  60,2, 100,7);
  852.                  y = spline(curframe, 0,0,  40,5,  60,2, 100,4);
  853.                  z = spline(curframe, 0,-3, 40,-1, 60,0, 100,2);
  854.                  << statements to output position >>
  855.              }
  856.  
  857.          If  the  path  described  by  a spline function completes a closed
  858.          circuit, a smoother transition can be accomplished  by  specifying
  859.          an  extra  point beyond either end which matches the next point on
  860.          the path.  The following statements illustrate this for forming  a
  861.          roughly  circular  path  (a  better way to do this would be to use
  862.          sin and cos functions):
  863.  
  864.              position = 100*(curframe-1)/(lastframe-1);
  865.              x = spline(position, -20,0.3,   0,1.0,   20,0.3,  40,-0.8,
  866.                                    60,-0.8, 80,0.3,  100,1.0, 120,0.3);
  867.              y = spline(position, -20,-1.0,  0,0.0,   20,1.0,  40,0.6,
  868.                                    60,-0.6, 80,-1.0, 100,0.0, 120,1.0);
  869.  
  870.          Note that the first point  specified  (-20)  and  the  last  point
  871.          (120)  will  never  be  reached since the value of position ranges
  872.          from 0 to 100.  However, because the spline function  depends  not
  873.          only  on  the  current  position  but also on the points on either
  874.          side, specifying these points smooths out the transition near  the
  875.          end  points.   This trick does not apply to spline curves that are
  876.          not closed on themselves.
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.                                      Chapter 3
  884.  
  885.                            The Animation Control Language
  886.  
  887.  
  888.  
  889.  
  890.          The RTAG animation control language is  similar  to  other  modern
  891.          programming  languages  such as C.  It provides the tools you need
  892.          to  easily  perform  animation  simulations   and   generate   the
  893.          necessary  output  files  to  drive  the ray tracing and auxiliary
  894.          programs.
  895.  
  896.          3.1 Comments
  897.  
  898.          The beginning of a comment is denoted with "//"  (two  consecutive
  899.          slash  characters).   Everything from the "//" sequence to the end
  900.          of the line is treated as a comment.  Comments may be on lines  by
  901.          themselves  or  on  the  ends  of  other statements.  You can also
  902.          specify  a  comment  by  beginning  the  comment  with  the   "/*"
  903.          character  sequence.  All characters following this are treated as
  904.          comments up to the matching "*/" sequence.   The  following  lines
  905.          illustrate both types of comments:
  906.  
  907.              //  Begin main simulation loop
  908.              y = y + timestep * yvelocity;  //  Advance y position
  909.              /*
  910.               *  This is a comment.
  911.               */
  912.              z = y / 5;                  /* This is a comment too */
  913.  
  914.          3.2 Basic Statement Syntax
  915.  
  916.          The  RTAG  language  has  a  syntax  that  is  very  similar to C:
  917.          statements are terminated with a semicolon, and  brace  characters
  918.          ("{" and "}") are used to group statements.
  919.  
  920.          3.3 Declaration of Variables (VAR Statement)
  921.  
  922.          All  variables  used  in  your  animation  control  file  must  be
  923.          declared before they  are  used.   This  is  done  using  the  VAR
  924.          statement  which  may  optionally  assign  an initial value to the
  925.          variable.  If  no  initial  value  is  specified,  0  is  used  by
  926.          default.   VAR  is  a  declarative statement: that is, it declares
  927.          the existence of the variable and assigns  an  initial  value,  it
  928.          does  not  reassign the value to the variable if the VAR statement
  929.          appears in a loop.
  930.  
  931.          Variable names may be up to 30 characters  long.   They  ARE  case
  932.          sensitive.   Keywords (FOR, WHILE, VAR, etc.) and library function
  933.  
  934.  
  935.                                          15
  936.  
  937.          Chapter 3. The Animation Control Language                       16
  938.  
  939.  
  940.          names  (SIN,  COS,  ABS,  etc.)  are  NOT  case  sensitive.    All
  941.          variables are double precision (64 bit) floating point values.
  942.  
  943.          The syntax of the VAR statement is:
  944.  
  945.              VAR variable1[=value], variable2[=value], ...;
  946.  
  947.          You  may  use  as  many VAR statements as you need.  The following
  948.          are examples of this statement:
  949.  
  950.              var x, y, speed = 5;
  951.              var Acceleration = 2.5;
  952.  
  953.          In addition to simple scalar variables, RTAG also  allows  you  to
  954.          use   one-dimensional   array  variables.   To  declare  an  array
  955.          variable, follow the name of  the  variable  with  the  number  of
  956.          elements  enclosed in square brackets.  For example, the following
  957.          command declares  a  variable  named  speeds  that  will  have  20
  958.          values:
  959.  
  960.              var speeds[20];
  961.  
  962.          If  you  wish  to  assign  initial values to an array, enclose the
  963.          list of values in braces.  For example,
  964.  
  965.              var xpos[3] = {1.2, 2.7, 4.6};
  966.  
  967.          Subscripts follow the C convention of being  0  based.   That  is,
  968.          the  first  element  of  an  array is referenced using a subscript
  969.          value of 0.  For example, if  the  variable  x  is  declared  with
  970.          three  elements  (var  x[3]) then the elements would be referenced
  971.          as x[0], x[1], and x[2].  The expression x[3] would NOT be valid.
  972.  
  973.          In addition to your own variables, RTAG  provides  several  system
  974.          variables.   If  you  do  not  provide  VAR  statements  for these
  975.          variables, they are defined automatically at the start  of  a  run
  976.          and RTAG assigns their values.
  977.  
  978.               Variable   Default               Meaning
  979.              ----------  ------- ------------------------------------------
  980.              curframe       0    The current frame number. Set by NEXTFRAME
  981.              firstframe     1    The first frame that will generate output.
  982.              lastframe    999999 The last frame that will generate output.
  983.              stepinc        1    The step increment between frames.
  984.              srand          1    Seed for random number generator.
  985.  
  986.          These  variables  may  be used in your animation control file just
  987.          like ordinary variables.  If you want  to  set  different  default
  988.          values  for  firstframe,  lastframe,  stepinc  or srand, use a VAR
  989.          statement  and  specify  an  initial  value.   For  example,   the
  990.          following commands would cause frames 20 through 40 to be output:
  991.  
  992.              var firstframe = 20;
  993.              var lastframe = 40;
  994.  
  995.          Chapter 3. The Animation Control Language                       17
  996.  
  997.  
  998.          The  default  values,  or  the values specified by VAR statements,
  999.          can be overridden by qualifiers on  the  command  line.   /F  sets
  1000.          firstframe, /L sets lastframe, and /S sets stepinc.
  1001.  
  1002.          The  srand  system variable is used to set a starting "seed" value
  1003.          for the RANDOM() function.  The default  value  for  srand  is  1.
  1004.          For  a  given  starting  seed  value, the pseudorandom sequence is
  1005.          always the same.
  1006.  
  1007.          3.4 Output File Declarations
  1008.  
  1009.          RTAG is capable of  producing  multiple  files  during  each  run.
  1010.          Most  of these files are optional and will only be produced if you
  1011.          include the appropriate statements in your control file.
  1012.  
  1013.          The listing file is always produced.  It has the same name as  the
  1014.          animation control file but with an extension of ".LST".
  1015.  
  1016.          Most  RTAG runs will produce a batch file to drive the ray tracing
  1017.          program.  The batch file may  contain  commands  to  generate  the
  1018.          appropriate  include file for each frame or you may choose to have
  1019.          RTAG generate the full set of  include  files  separate  from  the
  1020.          batch  file.   If you wish to generate a batch file you must place
  1021.          a command of the following form in your control file:
  1022.  
  1023.              BFILE "name";
  1024.  
  1025.          where  'name'  is  the  name  of  the  batch  file.   The  default
  1026.          extension  is ".BAT".  Note that the file name must be enclosed on
  1027.          quote marks.
  1028.  
  1029.          The batch file normally contains a set of commands to render  each
  1030.          frame.   Typically,  the  commands  for  each  frame  perform  the
  1031.          following actions:
  1032.  
  1033.            . Generate an include file with object position information.
  1034.  
  1035.            . Run the ray tracer using the current include file.
  1036.  
  1037.          The BWRITE function is used to  write  to  the  batch  file.   The
  1038.          batch  file  is  optional and is generated only if you use a BFILE
  1039.          statement.
  1040.  
  1041.          If you wish to have RTAG generate a  set  of  include  files,  you
  1042.          must use the following command to declare the names of the files:
  1043.  
  1044.              OFILE "name";
  1045.  
  1046.          If  the  OFILE statement is used, one output file is generated for
  1047.          each frame.  The output file name must include a string of one  to
  1048.          seven  '#'  characters.   These  characters  are  replaced  by the
  1049.          current frame number  when  the  file  is  opened.   For  example,
  1050.          consider the following command:
  1051.  
  1052.          Chapter 3. The Animation Control Language                       18
  1053.  
  1054.  
  1055.              ofile "bounc###.inc";
  1056.  
  1057.          Then   for  frame  27  the  name  of  the  created  file  will  be
  1058.          BOUNC027.INC.  The default extension  is  ".INC".   The  NEXTFRAME
  1059.          command  closes  the  current  output  file,  increments the frame
  1060.          number, and  opens  the  next  output  file  (assuming  the  OFILE
  1061.          statement  was  specified).   The  last output file is closed when
  1062.          the program stops.   The  OWRITE  function  writes  lines  to  the
  1063.          currently open output file.
  1064.  
  1065.          RTAG  can  also create or read from auxiliary data files.  This is
  1066.          described in a subsequent section.
  1067.  
  1068.          3.5 Assignment Statement
  1069.  
  1070.          The  assignment  statement  is  an   executable   statement   that
  1071.          evaluates  an expression and assigns its value to a variable.  The
  1072.          syntax for an assignment statement is:
  1073.  
  1074.              variable = expression;    // Assign expression to variable
  1075.              variable += expression;   // Add expression to variable
  1076.              variable -= expression;   // Subtract expression from variable
  1077.              variable *= expression;   // Multiply variable by expression
  1078.              variable /= expression;   // Divide variable by expression
  1079.  
  1080.          where "variable" is a previously declared variable  which  may  be
  1081.          subscripted  and  "expression"  is  a  valid arithmetic or logical
  1082.          expression  following  the  rules  explained  earlier.    If   the
  1083.          expression  involves a relational comparison operator (e.g., <, >,
  1084.          >=, etc.) or a logical operation (&&, ||, !), the value 1 is  used
  1085.          for true and 0 for false.
  1086.  
  1087.          3.6 IF Statement
  1088.  
  1089.          The form of the IF statement is:
  1090.  
  1091.              IF (expression) statement1 [ELSE statement2]
  1092.  
  1093.          If  the  expression  is true (not zero) statement1 is executed, if
  1094.          the expression is false (0) and  the  ELSE  clause  is  specified,
  1095.          statement2  is  executed.   The  ELSE clause and the second set of
  1096.          controlled statements are optional.  You  may  control  groups  of
  1097.          statements  by  enclosing  them  in  braces.   The  following  are
  1098.          examples of valid IF statements:
  1099.  
  1100.              if (x > bigx) bigx = x;
  1101.  
  1102.              if (x <= 10) {
  1103.                  y = linear(x, 0,0, 10,6);
  1104.                  z = .5 * x;
  1105.              } else {
  1106.                  y = y + yspeed * timestep;
  1107.                  z = .3 * x;
  1108.              }
  1109.  
  1110.          Chapter 3. The Animation Control Language                       19
  1111.  
  1112.  
  1113.          3.7 WHILE Statement
  1114.  
  1115.          The  WHILE  statement  loops  until  the  controlling   expression
  1116.          becomes  false  (0)  or  a  BREAK statement is executed within the
  1117.          loop.  The form of the WHILE statement is:
  1118.  
  1119.              WHILE (expression) {
  1120.                  << controlled statements >>
  1121.              }
  1122.  
  1123.          Each time around the loop the expression is evaluated.  If  it  is
  1124.          true  (non  zero)  the controlled statements are executed and then
  1125.          the process repeats until the  expression  becomes  false.   If  a
  1126.          BREAK  statement  is  executed  within  the loop, execution of the
  1127.          loop terminates and control is transferred to the first  statement
  1128.          beyond  the  end of the loop.  If a CONTINUE statement is executed
  1129.          in the loop, control is transferred to  the  conditional  test  at
  1130.          the  top  of  the  loop.   The  following is an example of a WHILE
  1131.          statement:
  1132.  
  1133.              while (x < 5) {
  1134.                  x = x + xmove;
  1135.                  y = y + ymove;
  1136.              }
  1137.  
  1138.          3.8 DO Statement
  1139.  
  1140.          The DO statement is very similar to  the  WHILE  statement  except
  1141.          the  control expression is evaluated at the end of the loop rather
  1142.          than the beginning.  This causes the loop always  to  be  executed
  1143.          at least once.  The form of the DO statement is:
  1144.  
  1145.              DO {
  1146.                  << controlled statements >>
  1147.              WHILE (expression);
  1148.  
  1149.          For  each  iteration  of  the  loop  the controlled statements are
  1150.          executed and then the conditional expression is evaluated.  If  it
  1151.          is  true  (non-zero)  control  transfers  to  the first controlled
  1152.          statement at the top of the loop.  A BREAK statement may  be  used
  1153.          to  terminate  the  loop  before  the  conditional  expression  is
  1154.          evaluated.  A CONTINUE statement can be used to cause  control  to
  1155.          be  transferred  from  within  the  loop  to  the  point where the
  1156.          conditional expression is evaluated.  The following is an  example
  1157.          of a DO statement:
  1158.  
  1159.              do {
  1160.                 read(infile,lastflag,x[numpoints++]);
  1161.              } while (!lastflag);
  1162.  
  1163.          3.9 FOR Statement
  1164.  
  1165.          The  FOR  statement  is a looping control statement similar to the
  1166.          WHILE statement; however, the FOR statement  also  allows  you  to
  1167.          specify  initialization  expressions that are executed once at the
  1168.  
  1169.          Chapter 3. The Animation Control Language                       20
  1170.  
  1171.  
  1172.          beginning of the loop, and loop-end expressions that are  executed
  1173.          at the end of each loop cycle.  The form of the FOR statement is:
  1174.  
  1175.              FOR (expression1; expression2; expression3) statement
  1176.  
  1177.          Execution of a FOR statement proceeds as follows:
  1178.  
  1179.          1.   Evaluate expression1.  Typically this expression will include
  1180.          assignment  operators  ("=")  to  set  initial  values  for   loop
  1181.          variables.   If you need more than one initial expression, specify
  1182.          them as a list separated by commas.
  1183.  
  1184.          2.  Evaluate expression2.  If its value  is  false  (0)  terminate
  1185.          the  FOR  statement  and  transfer  control  to the statement that
  1186.          follows  the  controlled  statement.   If  expression2  is   true,
  1187.          proceed to the next step.
  1188.  
  1189.          3.   Execute the controlled statement.  If more than one statement
  1190.          is to be controlled,  enclose  them  with  brace  characters  ("{"
  1191.          "}").
  1192.  
  1193.          4.   Evaluate expression3.  This expression will typically contain
  1194.          operators such as "++", "+=", "--", or "-=" to  modify  the  value
  1195.          of a loop variable.
  1196.  
  1197.          5.   Transfer  control  to step 2, where expression2 is once again
  1198.          evaluated.
  1199.  
  1200.          The following is an example of a FOR statement:
  1201.  
  1202.              for (time=starttime; time<endtime; time+=timestep) {
  1203.                  << controlled statements >>
  1204.              }
  1205.  
  1206.          3.10 BREAK Statement
  1207.  
  1208.          The BREAK statement can be used in FOR, WHILE,  and  DO  loops  to
  1209.          terminate  the loop and cause control to transfer to the statement
  1210.          beyond the end of the loop.  The following  is  an  example  of  a
  1211.          BREAK statement:
  1212.  
  1213.              time = 0;
  1214.              x = 0;
  1215.              while (time < endtime) {
  1216.                  x += delta * xspeed;
  1217.                  if (x > 10) break;
  1218.              }
  1219.  
  1220.          3.11 CONTINUE Statement
  1221.  
  1222.          The  CONTINUE statement can be used in FOR, WHILE, and DO loops to
  1223.          terminate the current iteration and  begin  the  next  one.   When
  1224.          CONTINUE  is  executed  in  a  WHILE  or  DO statement, control is
  1225.          transferred to the point  in  the  loop  where  the  loop  control
  1226.          expression  is  evaluated.   When  CONTINUE  is  executed in a FOR
  1227.  
  1228.          Chapter 3. The Animation Control Language                       21
  1229.  
  1230.  
  1231.          statement, control is transferred to the bottom of the loop  where
  1232.          expression3  is  evaluated  (which normally augments the values of
  1233.          the loop variables for the next iteration).
  1234.  
  1235.          3.12 STOP Statement
  1236.  
  1237.          The STOP statement terminates the execution  of  RTAG  and  closes
  1238.          all  output  files.  An implicit STOP occurs if you "fall through"
  1239.          the bottom of your animation control file.  The  following  is  an
  1240.          example of the STOP statement:
  1241.  
  1242.              while (curframe < 60) {
  1243.                  << controlled statements >>
  1244.                  if (xposition1 >= xposition2) stop;
  1245.              }
  1246.  
  1247.          3.13 WRITE functions
  1248.  
  1249.          RTAG  has  three  functions  for writing output to standard files.
  1250.          These functions and the files they write to are as follows:
  1251.  
  1252.              PRINTF -- Listing file (also displayed on screen).
  1253.              OWRITE -- Output file (OFILE).
  1254.              BWRITE -- Batch file (BFILE).
  1255.  
  1256.          Since the form for these functions is the  same  (except  for  the
  1257.          keyword),  the PRINTF statement will be used in the illustrations.
  1258.          The form of the function is:
  1259.  
  1260.              printf("string"[,expression1, expression2,...])
  1261.  
  1262.          where  "string"  is  a  quoted  text  string  that  may  including
  1263.          variable  and expression replacement operators.  You can cause the
  1264.          current value of a variable to be substituted  into  a  string  by
  1265.          inserting  the  variable  name  in  the  string  enclosed  by  "`"
  1266.          characters.  Note, this is not the apostrophe, it  is  the  accent
  1267.          character  that is on the same key as the tilde on most keyboards.
  1268.          You can use the  SUBCHAR  statement  (see  below)  to  change  the
  1269.          character  used  to  mark  a  variable  value  substitution.   For
  1270.          example, the following statement prints the  values  of  the  xpos
  1271.          and ypos variables:
  1272.  
  1273.              printf("X position is `xpos`, Y position is `ypos`\n");
  1274.  
  1275.          When  this statement is executed `xpos` and `ypos` are replaced by
  1276.          the current values of the xpos and ypos variables.
  1277.  
  1278.          Following the C  model,  control  characters  are  placed  in  the
  1279.          string   by   preceding  the  character  with  a  backslash.   The
  1280.          following table indicates each of the valid control sequences:
  1281.  
  1282.          Chapter 3. The Animation Control Language                       22
  1283.  
  1284.  
  1285.              \a -- Bell character (0x07).
  1286.              \b -- Backspace (0x08).
  1287.              \f -- Form feed (0x0C);
  1288.              \n -- End of print line (carriage-return, line-feed).
  1289.              \r -- Carriage return only.
  1290.              \" -- Quote character.
  1291.              \\ -- Literal backslash character (replace "\\" with "\").
  1292.              \xddd -- Hexadecimal value 0xddd.
  1293.  
  1294.          If the sequence `###` (1 to  7  '#'  characters  enclosed  by  "`"
  1295.          characters)  appears  in  the string, the pound signs are replaced
  1296.          by the current frame number with leading zeros.  If  the  sequence
  1297.          `+++`  (1  to  7  '+'  characters) appears in the string, the plus
  1298.          signs are replaced by a value equal to the  current  frame  number
  1299.          plus  1.   In  addition,  the  strings  `ofile`  and  `bfile`  are
  1300.          replaced  by  the  names  of  the  output  file,  and  batch  file
  1301.          respectively.   The  string  `file` is replaced by the name of the
  1302.          input animation command  file  with  any  device,  directory,  and
  1303.          extension removed.
  1304.  
  1305.          You  can  also  substitute the values of expressions.  To do this,
  1306.          use the C programming notation "%w.dlf" where 'w' is  the  overall
  1307.          field  width  and  'd'  is  the  number  of  decimal  places.  For
  1308.          example,  the  following  statement  prints  the   value   of   an
  1309.          expression:
  1310.  
  1311.              printf("Diagonal distance = %5.1lf\n", sqrt(xd^2 + yd^2));
  1312.  
  1313.          3.14 SUBCHAR Statement
  1314.  
  1315.          The  SUBCHAR  statement specifies which character is to be used in
  1316.          write strings to enclose the names of variables whose  values  are
  1317.          to  be substituted in the string.  The default character is "`" --
  1318.          the accent character which is usually  on  the  same  key  as  the
  1319.          tilde character.  The form of the statement is:
  1320.  
  1321.              SUBCHAR "char";
  1322.  
  1323.          where  "char" is a single character that must be included in quote
  1324.          marks.  For example, the following statement declares dollar  sign
  1325.          to be the substitution marker character:
  1326.  
  1327.              subchar "$";
  1328.  
  1329.          3.15 NEXTFRAME Statement
  1330.  
  1331.          The  NEXTFRAME statement performs the following actions: (1) close
  1332.          the currently open output file, if any; (2) increment the  current
  1333.          frame  number  (and  curframe variable); (3) if an OFILE statement
  1334.          was used, open a new output file with  the  current  frame  number
  1335.          substituted for the "###" characters in the file name.
  1336.  
  1337.          You  must  execute  a  NEXTFRAME  statement  before you can use an
  1338.          OWRITE  function.   PRINT,  BWRITE  and  WRITE  functions  can  be
  1339.  
  1340.          Chapter 3. The Animation Control Language                       23
  1341.  
  1342.  
  1343.          executed  before  the  first  NEXTFRAME  command.  The last output
  1344.          file is closed when your program stops.
  1345.  
  1346.          3.16 EPILOG Statement
  1347.  
  1348.          The EPILOG statement (which may also be spelled EPILOGUE)  informs
  1349.          RTAG  that  the  last frame has been completed and that subsequent
  1350.          BWRITE function  calls  are  unconditionally  to  generate  output
  1351.          regardless  of  the  setting  of  the  firstframe,  lastframe, and
  1352.          stepinc  values.   Otherwise  BWRITE  functions  do  not  generate
  1353.          output  if  they  occur after the last frame, or between frames if
  1354.          stepinc is not 1.  Commonly statements using the  BWRITE  function
  1355.          are   used   after   EPILOG   to  write  some  "end-of-all-frames"
  1356.          termination statements to the batch file, such as commands to  run
  1357.          DTA to build the animation sequence.
  1358.  
  1359.          3.17 Self-continuing Batch Files
  1360.  
  1361.          Because  so  much  computer  time is required to create ray traced
  1362.          animations, it is sometimes necessary to produce the frames  using
  1363.          a  series  of  runs rather than in a single run.  Using RTAG it is
  1364.          easy to produce BAT files that  automatically  will  restart  with
  1365.          the  first  frame that does not exist.  This is done by generating
  1366.          "IF EXIST...GOTO" commands as part of the batch  file.   For  each
  1367.          frame  you  cause the BAT file to check if the TGA file exists; if
  1368.          so, control skips to the test for the next  file.   The  following
  1369.          is  a  skeleton  of  an RTAG program to generate these statements.
  1370.          Note the use of the  `###`  sequence  to  substitute  the  current
  1371.          frame  number  and the `+++` sequence to substitute the next frame
  1372.          number.
  1373.  
  1374.              while (curframe < lastframe) {
  1375.                  nextframe;
  1376.                  bwrite(":do`###`\n");
  1377.                  bwrite("if exist tour`###`.tga goto do`+++`\n");
  1378.                  << other commands to write info for this frame >>
  1379.              }
  1380.              epilog;
  1381.              bwrite(":do`+++`\n");
  1382.              bwrite("call dodta TOUR /S8\n");
  1383.  
  1384.          The commands written to the BAT  file  for  each  frame  have  the
  1385.          following form:
  1386.  
  1387.              :do001
  1388.              if exist tour001.tga goto do002
  1389.              << commands to generate frame 1 >>
  1390.              :do002
  1391.              if exist tour002.tga goto do003
  1392.              << commands to generate frame 2 >>
  1393.              :do003
  1394.  
  1395.          Chapter 3. The Animation Control Language                       24
  1396.  
  1397.  
  1398.          3.18 Auxiliary Data Files
  1399.  
  1400.          RTAG  provides  functions  to open, close, read from, and write to
  1401.          auxiliary data files.  This is useful if some  other  program  has
  1402.          computed   object   positions  or  other  data  that  affects  the
  1403.          animation.
  1404.  
  1405.          Up to 30 auxiliary data files can be open at once.  The files  are
  1406.          identified  by  numbers  (also  called  file  "handles")  that are
  1407.          assigned by RTAG at the time that the file is  opened.   The  file
  1408.          numbers  can  be  reused by closing and reopening files.  You must
  1409.          use the VAR statement  to  declare  variables  to  hold  the  file
  1410.          numbers.
  1411.  
  1412.          3.18.1 Opening a File for Reading
  1413.  
  1414.          The  form  of  the  statement  used  to  open an existing file for
  1415.          reading is:
  1416.  
  1417.              variable = open("file name");
  1418.  
  1419.          where 'variable' is a variable you have previously  declared  with
  1420.          a  VAR  statement.  When RTAG opens the file it generates a unique
  1421.          file number and assignes it to the variable on  the  left  of  the
  1422.          equal  sign.   This  file  number can be used subsequently in READ
  1423.          functions.  An example of this statement is
  1424.  
  1425.              infile = open("spiral.dat");
  1426.  
  1427.          3.18.2 Creating an Output File
  1428.  
  1429.          The form of the statement used to create an auxiliary output  file
  1430.          is
  1431.  
  1432.              variable = create("file name");
  1433.  
  1434.          When  RTAG  creates  the  file it assignes a unique file number to
  1435.          the  specified  variable.   This   file   number   can   be   used
  1436.          subsequently in WRITE functions.  An example of this statement is
  1437.  
  1438.              outfile = create("trace.dat");
  1439.  
  1440.          3.18.3 Closing an Auxiliary File
  1441.  
  1442.          The function used to close an auxiliary file is:
  1443.  
  1444.              close(file)
  1445.  
  1446.          where 'file' is a variable that has a file number.  For example:
  1447.  
  1448.              close(outfile);
  1449.  
  1450.          Any   open  files  are  closed  automatically  when  your  program
  1451.          terminates.
  1452.  
  1453.          Chapter 3. The Animation Control Language                       25
  1454.  
  1455.  
  1456.          3.18.4 Reading from an Auxiliary File
  1457.  
  1458.          You may read data from an open auxiliary  file  by  using  a  READ
  1459.          function of the following form:
  1460.  
  1461.              read(file,variable1,variable2,...);
  1462.  
  1463.          Where  'file'  is  a file number assigned by a previously executed
  1464.          OPEN function.  Each READ function call reads  the  next  line  of
  1465.          data  from  the  file  and  assigns  numeric values to the list of
  1466.          variables you specify.  There  must  be  at  least  as  many  data
  1467.          values  on  the line as the number of variables specified with the
  1468.          READ function (additional values are ignored).   The  data  values
  1469.          may  be  separated by spaces, tabs, and/or commas.  Numeric values
  1470.          may be specified in the  same  form  as  numbers  within  an  RTAG
  1471.          animation control file (natural, exponential, or dd:dd:dd).
  1472.  
  1473.          The  MOREDATA function can be used to control how many records are
  1474.          read from the file.  The value of MOREDATA(file) is  true  (1)  if
  1475.          there  is another, unread, record available in the file; its value
  1476.          is false (0) if there is no  more  data  available  in  the  file.
  1477.          MOREDATA  does  not  consume  any  data,  it  just  checks for the
  1478.          availability of data.  The following  statements  would  read  all
  1479.          data in a file and generate a frame file for each record:
  1480.  
  1481.              var f,xpos,ypos;
  1482.              f = open("indata.dat");
  1483.              while (moredata(f)) {
  1484.                  nextframe;
  1485.                  read(f,xpos,ypos);
  1486.                  owrite("#declare xpos=`xpos`\n");
  1487.                  owrite("#declare ypos=`ypos`\n");
  1488.              }
  1489.  
  1490.          3.18.5 Writing to an Auxiliary File
  1491.  
  1492.          The form of the function used to write to an auxiliary file is:
  1493.  
  1494.              WRITE(file,"string"[,expression1,expression2,...]);
  1495.  
  1496.          where  'file' is a variable containing a file number assigned by a
  1497.          previously executed CREATE function.  "string" is a quoted  string
  1498.          of  the  same  form  as described for the PRINT, OWRITE and BWRITE
  1499.          functions.   The  string  may  include  variable  and   expression
  1500.          replacement   operators.    Expression1,  expression2,  etc.   are
  1501.          optional expressions whose values are to be substituted  into  the
  1502.          string  where  "%w.dlf" sequences occur.  The following statements
  1503.          illustrate the use of the WRITE function:
  1504.  
  1505.          Chapter 3. The Animation Control Language                       26
  1506.  
  1507.  
  1508.              var f,x,y;
  1509.              f = create("sine.out");
  1510.              for (x=0; x<360; x+=2) {
  1511.                  y = sin(x);
  1512.                  write(f,"x=`x`, y=`y`\n");
  1513.              }
  1514.              close(f);
  1515.  
  1516.          3.19 Notes About the System Variables
  1517.  
  1518.          curframe variable There are  four  system  variables  that  affect
  1519.          frame  generation:  curframe,  firstframe, lastframe, and stepinc.
  1520.          Curframe has the current frame number.  Its  initial  value  is  0
  1521.          before  the  first  frame  is  started.   The  NEXTFRAME statement
  1522.          closes the output file (OFILE)  if  it  is  open,  increments  the
  1523.          value  of  curframe by 1, and opens a new output file (if an OFILE
  1524.          statement  was  specified).    The   following   loop   would   be
  1525.          appropriate to generate an animation with 60 frames:
  1526.  
  1527.              while (curframe < 60) {
  1528.                  nextframe;
  1529.                  << commands to generate frame >>
  1530.              }
  1531.  
  1532.          By  default, firstframe has a value of 1, lastframe has a value of
  1533.          999999, and stepinc has a value of  1.   There  are  two  ways  to
  1534.          assign  different  values to these variables: the VAR statement or
  1535.          with command line options (/F, /L, and /S).  The main  reason  for
  1536.          setting  firstframe  and  stepinc  to something other than 1 is to
  1537.          make an abbreviated animation which will give you an idea  of  how
  1538.          objects  will  move  without  spending the time rending all of the
  1539.          images for a  full  animation.   The  following  example  shows  a
  1540.          command  file  that will generate images for frames 10 through 60,
  1541.          stepping 5 between the frames:
  1542.  
  1543.              var firstframe = 10;
  1544.              var lastframe = 60;
  1545.              var stepinc = 5;
  1546.              while (curframe < lastframe) {
  1547.                  nextframe;
  1548.                  << commands to generate frame >>
  1549.              }
  1550.  
  1551.          The effect of setting firstframe to something other than 1 may  be
  1552.          different   than  what  you  expect.   The  current  frame  number
  1553.          (curframe) ALWAYS starts at 0 and increments by 1.  If  firstframe
  1554.          is  set to something other than 1, the OWRITE and BWRITE functions
  1555.          have no effect until  the  frame  number  reaches  the  firstframe
  1556.          value  (i.e., when executed they do not write anything to a file).
  1557.          The  reason  that  firstframe  works  like  this  is   that   when
  1558.          performing  a  simulation  the state of the system usually depends
  1559.          on previous iterations (e.g.,  the  position  of  a  falling  ball
  1560.          depends  on  how  long  it  has  been  dropping and whether it has
  1561.          already hit the floor).  Because of this it is necessary to  start
  1562.          at  the  beginning  each time.  However, by cancelling the actions
  1563.  
  1564.          Chapter 3. The Animation Control Language                       27
  1565.  
  1566.  
  1567.          of the OWRITE and BWRITE functions prior to  firstframe,  you  can
  1568.          save the expense of rendering frames before the one of interest.
  1569.  
  1570.          There  are  two  exceptions to this rule.  BWRITE functions always
  1571.          generate output  before  the  first  execution  of  the  NEXTFRAME
  1572.          statement  regardless  of  the value of firstframe, lastframe, and
  1573.          stepinc.  This is done so that initialization  statements  can  be
  1574.          generated  before  the  frame generation iteration begins.  BWRITE
  1575.          functions also always generate output after the  execution  of  an
  1576.          EPILOG  statement.  This is done so that you can write cleanup and
  1577.          termination commands to the batch  and  auxiliary  files.   PRINTF
  1578.          and  WRITE  functions  generate  output regardless of the value of
  1579.          firstframe.
  1580.  
  1581.          The effect of stepinc is similar  to  firstframe.   The  NEXTFRAME
  1582.          statement  ALWAYS increments the frame number by 1.  If stepinc is
  1583.          not 1, OWRITE  and  BWRITE  functions  are  disabled  between  the
  1584.          steps.   BWRITE  always  generates  output before the execution of
  1585.          the first NEXTFRAME statement and after  execution  of  an  EPILOG
  1586.          statement.
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.                                      Chapter 4
  1594.  
  1595.                              Animation and Time Control
  1596.  
  1597.  
  1598.  
  1599.  
  1600.          Time  is  an  essential  component  of  any animation.  Except for
  1601.          special effects,  time  advances  by  a  constant  amount  between
  1602.          frames.   Most  RTAG  animation  control  files will have an outer
  1603.          loop  advancing  through  either  frames  or  time.   For   simple
  1604.          animations   it   is   usually  easier  to  loop  through  frames,
  1605.          calculating the simulated time as a function of the frame  number.
  1606.          For  example,  the following statements would move an object along
  1607.          a sinusoidal (wavey) path using the frame number  as  an  argument
  1608.          to the SIN function:
  1609.  
  1610.              while (curframe < 60) {
  1611.                  nextframe;
  1612.                  x = -6 + (curframe / 5);
  1613.                  y = 3 * sin(curframe * 12);
  1614.                  << other statements to generate output >>
  1615.              }
  1616.  
  1617.          This  approach works well for simple animations where the position
  1618.          of the objects can be calculated  as  a  direct  function  of  the
  1619.          frame  number.   However,  for more complex animations, especially
  1620.          those involving acceleration and interactions between objects,  it
  1621.          may  be  necessary  to  perform  the  simulation with smaller time
  1622.          steps than the time between frames.  In  other  words,  the  outer
  1623.          loop  should  advance  the  simulation  time  and frames should be
  1624.          generated  at  periodic  intervals  to  take  "snapshots"  of  the
  1625.          objects.  The following statements illustrate this approach:
  1626.  
  1627.              for (time=0; time<endtime; time+=timestep) {
  1628.                  //  Calculate updated positions of objects
  1629.                  x = x + xspeed * timestep;
  1630.                  y = y + yspeed * timestep;
  1631.                  << other statements to compute object positions >>
  1632.                  //  See if it is time to generate a frame
  1633.                  if (time >= frametime) {
  1634.                      //  Generate a frame
  1635.                      nextframe;
  1636.                      << statements to write to files >>
  1637.                      //  Calculate when next frame should be generated
  1638.                      frametime = frametime + sampletime;
  1639.                  }
  1640.              }
  1641.  
  1642.  
  1643.  
  1644.  
  1645.                                          28
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.                                      Chapter 5
  1653.  
  1654.                                  Example Animations
  1655.  
  1656.  
  1657.  
  1658.  
  1659.          The  RTAG  distribution comes with several example files which are
  1660.          explained below.  For each example there is  an  ".RTA"  animation
  1661.          command file and a ".POV" POV-Ray scene description file.
  1662.  
  1663.          TOUR  --  There is a simulated "city" (would you believe a village
  1664.          with high rise buildings?).  The camera begins from the  distance,
  1665.          sweeps  down  and along "Main Street", circles a dome structure at
  1666.          the end, and then climbs while  still  keeping  the  buildings  in
  1667.          view  as  it  moves  away.   The  SPLINE  function is used both to
  1668.          control the position of the camera and also the location that  the
  1669.          camera  is  looking  at.   This  120-frame animation takes about 6
  1670.          hours to render in  320x200  size  with  anti-aliasing  turned  on
  1671.          running on a 486/33 using POV-Ray.
  1672.  
  1673.          BOUNC  --  Bouncing  ball  simulation.   A ball rolls down a ramp,
  1674.          falls, bounces twice, and ends up in landing in a can.  This is  a
  1675.          good  example  of  a  simulation  where  time is advanced in small
  1676.          steps and frames are generated periodically as "snapshots" of  the
  1677.          scene.   The  position  of the ball is calculated using elementary
  1678.          physics: The speed of an accelerating object at the end of a  time
  1679.          interval  is  equal  to  its  speed  at  the  beginning  plus  the
  1680.          acceleration multiplied by the time  interval.   The  position  at
  1681.          the  end  of  an interval is equal to the position at the start of
  1682.          the interval plus the speed multiplied by the time  interval.   An
  1683.          animation  with  60  to  70  frames  seems  to work best with this
  1684.          example.
  1685.  
  1686.          ORBIT -- Orbital simulation.  Three  planets  move  in  elliptical
  1687.          orbits  around a sun.  One of the planets has a moon in a circular
  1688.          orbit.  The orbital speeds of the planets  follow  Kepler's  laws.
  1689.          If  you look closely you can see the shadow as one planet eclipses
  1690.          another.  The 200 frame sequence takes about 4 hours to render  on
  1691.          a 386/25 with coprocessor.
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.                                          29
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.                                      Chapter 6
  1712.  
  1713.                             Use and Distribution of RTAG
  1714.  
  1715.  
  1716.  
  1717.  
  1718.          You  are  welcome  to make copies of this program and pass them on
  1719.          to friends or post this program on bulletin boards  or  distribute
  1720.          it   via   disk   catalog   services   provided  the  entire  RTAG
  1721.          distribution is included in  its  original,  unmodified  form.   A
  1722.          distribution  fee  may  be  charged  for the cost of the diskette,
  1723.          shipping  and  handling.   However,  RTAG  may  not  be  sold,  or
  1724.          incorporated   in  another  product  that  is  sold,  without  the
  1725.          permission of Phillip H.   Sherrod.   Vendors  are  encouraged  to
  1726.          contact the author to get the most recent version of RTAG.
  1727.  
  1728.          As  a  shareware  product, you are granted a no-cost, trial period
  1729.          of 30 days during which you may evaluate RTAG.  If you  find  RTAG
  1730.          to  be  useful,  educational, and/or entertaining, and continue to
  1731.          use it beyond the  30  day  trial  period,  you  are  required  to
  1732.          compensate  the author by sending the registration form printed on
  1733.          page 34 (and in REGISTER.DOC) with  the  appropriate  registration
  1734.          fee to help cover the development and support of RTAG.
  1735.  
  1736.          In  return  for  registering,  you  will be authorized to continue
  1737.          using RTAG beyond the trial period and you will receive  the  most
  1738.          recent  version of the program, a laser-printed, bound manual, and
  1739.          three months of support via telephone, mail, or CompuServe.   Your
  1740.          registration  fee  will be refunded if you encounter a serious bug
  1741.          that cannot be corrected.
  1742.  
  1743.          You are welcome to contact the author:
  1744.  
  1745.                                  Phillip H. Sherrod
  1746.                                  4410 Gerald Place
  1747.                            Nashville, TN  37205-3806  USA
  1748.                               615-292-2881 (evenings)
  1749.                                CompuServe: 76166,2640
  1750.                         Internet: 76166.2640@compuserve.com
  1751.  
  1752.          6.1 Copyright Notice
  1753.  
  1754.          Both the RTAG program and documentation are copyright (c) 1993  by
  1755.          Phillip  H.   Sherrod.   You  are  not  authorized  to  modify the
  1756.          program.  "RTAG" is a trademark.
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.                                          30
  1764.  
  1765.          Chapter 6. Use and Distribution of RTAG                         31
  1766.  
  1767.  
  1768.          6.2 Disclaimer
  1769.  
  1770.          RTAG is provided "as is" without  warranty  of  any  kind,  either
  1771.          expressed  or  implied.   This  program  may  contain  "bugs"  and
  1772.          inaccuracies, and its results should not be assumed to be  correct
  1773.          unless  they  are  verified  by  independent  means.   The  author
  1774.          assumes no responsibility for the use of  RTAG  and  will  not  be
  1775.          responsible for any damage resulting from its use.
  1776.  
  1777.          This  program  is  produced  by  a  member  of  the Association of
  1778.          Shareware Professionals (ASP).  ASP wants to make  sure  that  the
  1779.          shareware  principle  works for you.  If you are unable to resolve
  1780.          a shareware-related problem with an ASP member by  contacting  the
  1781.          member  directly,  ASP may be able to help.  The ASP Ombudsman can
  1782.          help you resolve a dispute or problem  with  an  ASP  member,  but
  1783.          does  not provide technical support for members' products.  Please
  1784.          write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI  49442
  1785.          or  send a CompuServe message via CompuServe Mail to ASP Ombudsman
  1786.          7007,3536.
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.                                      Chapter 7
  1794.  
  1795.                                    Other Software
  1796.  
  1797.  
  1798.  
  1799.  
  1800.          If you like RTAG, you should check out  the  Mathplot  and  Nonlin
  1801.          programs by the same author.
  1802.  
  1803.          7.1 Mathplot
  1804.  
  1805.          Mathplot  allows you to specify complicated mathematical functions
  1806.          using ordinary algebraic expressions and  immediately  plot  them.
  1807.          Four  types  of  functions  may  be specified: cartesian (Y=f(X));
  1808.          parametric cartesian (Y=f(T) and X=f(T)); polar
  1809.          (Radius=f(Angle));   and   parametric   polar   (Radius=f(T)   and
  1810.          Angle=f(T)).   Up to four functions may be plotted simultaneously.
  1811.          Scaling is automatic.   Options  are  available  to  control  axis
  1812.          display  and labeling as well as grid lines.  Hard copy output may
  1813.          be generated as well as screen  display.   Mathplot  is  an  ideal
  1814.          tool  for  engineers,  scientists,  math and science teachers, and
  1815.          anyone  else  who  needs   to   quickly   visualize   mathematical
  1816.          functions.    Mathplot  requires  a  CGA,  EGA,  or  VGA  monitor.
  1817.          Hardcopy plots can be displayed on HP LaserJet printers.
  1818.  
  1819.          7.2 Nonlin
  1820.  
  1821.          Nonlin  performs  linear  and  nonlinear  statistical   regression
  1822.          analysis.   Nonlin  determines  the  values  of  parameters for an
  1823.          equation, whose form you specify, that cause the equation to  best
  1824.          fit   a   set   of   data   values.   Nonlin  can  handle  linear,
  1825.          multivariate, polynomial, and general  nonlinear  equations.   You
  1826.          specify  the form of the equation using normal algebraic notation.
  1827.          The data values and  fitted  equation  can  be  displayed  on  the
  1828.          screen  or  an  HP  LaserJet printer.  Nonlin is the best and most
  1829.          powerful shareware regression program available.
  1830.  
  1831.          7.3 TSX-32 Operating System
  1832.  
  1833.          If you have a  need  for  a  multi-user,  multi-tasking  operating
  1834.          system,  you  should look into TSX-32.  TSX-32 is a full-featured,
  1835.          high performance, multi-user operating system for the 386 and  486
  1836.          that  provides  both  32-bit  and  16-bit  program  support.  With
  1837.          facilities such as  multitasking  and  multisessions,  networking,
  1838.          virtual  memory, X-Windows, background batch queues, data caching,
  1839.          file  access  control,  real-time,  and  dial-in  support,  TSX-32
  1840.          provides a solid environment for a wide range of applications.
  1841.  
  1842.  
  1843.  
  1844.  
  1845.                                          32
  1846.  
  1847.          Chapter 7. Other Software                                       33
  1848.  
  1849.  
  1850.          A  two  user,  shareware version of TSX-32 called TSX-Lite is also
  1851.          available.
  1852.  
  1853.          TSX-32 is not a limited, 16-bit, multi-DOS add-on.  Rather, it  is
  1854.          a  complete  32-bit  operating  system which makes full use of the
  1855.          hardware's potential, including protected mode execution,  virtual
  1856.          memory,  and demand paging.  TSX-32 sites range from small systems
  1857.          with 2-3 terminals  to  large  installations  with  more  than  64
  1858.          terminals on a single 386.
  1859.  
  1860.          In  addition  to  supporting  most  popular  16-bit  DOS programs,
  1861.          TSX-32 also provides a 32-bit "flat" address space with both  Phar
  1862.          Lap and DPMI compatible modes of execution.
  1863.  
  1864.          RTAG,  POV-Ray,  and DTA run well under TSX.  In fact, you can run
  1865.          them  as  background  batch  jobs  while  performing  other   work
  1866.          interactively.
  1867.  
  1868.          Since  the  DOS  file  structure  is  standard for TSX-32, you can
  1869.          directly read and write DOS disks.  And, you can run DOS  part  of
  1870.          the time and TSX-32 the rest of the time on the same computer.
  1871.  
  1872.          TSX-32  allows  each  user to control up to 10 sessions.  Programs
  1873.          can also "fork" subtasks  for  multi-threaded  applications.   The
  1874.          patented  Adaptive Scheduling Algorithm provides consistently good
  1875.          response time under varying conditions.
  1876.  
  1877.          The  TSX-32  network  option  provides  industry  standard  TCP/IP
  1878.          networking  through  Ethernet  and  serial  lines.   Programs  can
  1879.          access files  on  remote  machines  as  easily  as  on  their  own
  1880.          machine.   The  SET  HOST  command allows a user on one machine to
  1881.          log onto another computer in the network.  FTP,  Telnet,  and  NFS
  1882.          are available for interoperability with other systems.
  1883.  
  1884.          TSX-32  is,  quite  simply,  the  best and most powerful operating
  1885.          system available for the 386 and 486.  For additional  information
  1886.          contact:
  1887.  
  1888.                              S&H Computer Systems, Inc.
  1889.                                1027 17th Avenue South
  1890.                               Nashville, TN 37212 USA
  1891.                                 615-327-3670 (voice)
  1892.                                  615-321-5929 (fax)
  1893.                                 CompuServe: 71333,27
  1894.                          Internet: 71333.27@compuserve.com
  1895.  
  1896.          =====================================================================
  1897.                                 Software Order Form
  1898.          =====================================================================
  1899.  
  1900.          Name ______________________________________________________
  1901.  
  1902.          Address ___________________________________________________
  1903.  
  1904.          City _______________________  State _______ Zip ___________
  1905.  
  1906.          Telephone _________________________________________________
  1907.  
  1908.          CompuServe account (optional) _____________________________
  1909.  
  1910.          RTAG version ______________________________________________
  1911.  
  1912.          Bulletin board where you found RTAG _______________________
  1913.  
  1914.          Comments __________________________________________________
  1915.  
  1916.          Check the boxes which indicate your order type:
  1917.  
  1918.              ___ I wish to register RTAG ($20).
  1919.  
  1920.              ___ I wish to order Mathplot ($20).
  1921.  
  1922.              ___ I wish to order Nonlin ($25)
  1923.  
  1924.          Add  $5  to the total amount of the order if the software is being
  1925.          shipped out of the United States.
  1926.  
  1927.          In return for  registering,  you  will  receive  the  most  recent
  1928.          version  of  the  program,  a  laser-printed,  bound  copy  of the
  1929.          manual, and three  months  of  telephone  or  CompuServe  support.
  1930.          Your  registration  fee will be refunded if you find a serious bug
  1931.          that cannot be corrected.
  1932.  
  1933.          Distribution disk choice (check one):
  1934.  
  1935.                3.50" HD (1.4 MB)  ______
  1936.                5.25" HD (1.2 MB)  ______
  1937.                5.25" DD (360 KB)  ______
  1938.  
  1939.          Send this form with the amount indicated to the author:
  1940.  
  1941.                                  Phillip H. Sherrod
  1942.                                  4410 Gerald Place
  1943.                            Nashville, TN  37205-3806 USA
  1944.  
  1945.                               615-292-2881 (evenings)
  1946.                                CompuServe: 76166,2640
  1947.                         Internet: 76166.2640@compuserve.com
  1948.  
  1949.          Index                                                           35
  1950.  
  1951.  
  1952.          ABS function, 10                   firstframe variable, 16, 26
  1953.          ACOS function, 10                  FLI files, 5
  1954.          AND operator, 9                    FLOOR function, 10
  1955.          Arc cosine function, 10            FOR statement, 19
  1956.          Arc sine function, 10              GAMMA function, 10
  1957.          Arc tangent function, 10           GIF generator, 4
  1958.          Arithmetic operators, 8            GRAPHDEV forum, 5
  1959.          Arrays, 16                         Graphics Alternative, 5
  1960.          ASIN function, 10                  Hyperbolic cosine, 10
  1961.          ASP, 31                            Hyperbolic sine, 12
  1962.          Assignment operators, 9            Hyperbolic tangent, 13
  1963.          Assignment statement, 18           IF statement, 18
  1964.          ATAN function, 10                  Include file, 3, 17
  1965.          Auxiliary data files, 24              /O option, 6
  1966.          Auxiliary file, 4                  INT function, 11
  1967.          Batch file, 3, 17                  Interpolation
  1968.             /B option, 6                       linear, 11, 13
  1969.             self-continuing, 23                spline, 12, 13
  1970.          BFILE statement, 17                Last frame
  1971.          BOB program, 4                        /L option, 6
  1972.          BOUNC example, 29                  lastframe variable, 16
  1973.          Brace characters, 15               Library functions, 10
  1974.          BREAK statement, 19, 20            LINEAR function, 11, 13
  1975.          Built-in constant, 10              Listing file, 4, 17
  1976.          Built-in functions, 10                /P option, 7
  1977.          Bulletin boards, 5                 LOG function, 11
  1978.          BWRITE function, 17, 21, 26        LOG10 function, 11
  1979.          CEIL function, 10                  Logical operators, 9
  1980.          CLOSE function, 10, 24             Mathplot, 32
  1981.          Comments in program, 15            MAX function, 11
  1982.          Comparison operators, 9            MIN function, 11
  1983.          CompuServe, 5                      MOD function, 11
  1984.          CONTINUE statement, 19, 20         Modulo operator, 8
  1985.          Copyright notice, 30               MOREDATA function, 11, 25
  1986.          COS function, 10                   NEXTFRAME statement, 18, 22
  1987.          COSH function, 10                  Nonlin, 32
  1988.          COT function, 10                   NOT operator, 9
  1989.          CREATE function, 10, 24            NPD function, 11
  1990.          CSC function, 10                   Numeric constants, 9
  1991.          CSHOW program, 4                   OFILE statement, 17
  1992.          Cubic spline, 12                   OPEN function, 11, 24
  1993.          curframe variable, 16, 26          Operator precedence, 9
  1994.          DEG function, 10                   OR operator, 9
  1995.          Disclaimer, 31                     ORBIT example, 29
  1996.          DO statement, 19                   Order form, 34
  1997.          Driver files, 1                    OWRITE function, 18, 21, 26
  1998.          DTA program, 5, 33                 PAREA function, 12
  1999.          ECHO command, 3                    PI constant, 10
  2000.          EPILOG statement, 23, 27           Piclab program, 4
  2001.          Examples, 29                       PLAY program, 5
  2002.          EXP function, 10                   Polyray program, 4
  2003.          Exponentation operator, 8          POV-Ray, 2, 4, 33
  2004.          FAC function, 10                   Precedence of operators, 9
  2005.          First frame                        PRINTF function, 12, 21
  2006.             /F option, 6                    Probability distribution, 11
  2007.  
  2008.          Index                                                           36
  2009.  
  2010.  
  2011.          PULSE function, 12
  2012.          RAD function, 12
  2013.          RANDOM function, 12, 17
  2014.          READ function, 12, 25
  2015.          Registration form, 34
  2016.          ROUND function, 12
  2017.          SEC function, 12
  2018.          SEL function, 12
  2019.          Shareware, 30
  2020.          SIN function, 12
  2021.          SINH function, 12
  2022.          SPLINE function, 12, 13
  2023.          SQRT function, 13
  2024.          srand variable, 16
  2025.          STEP function, 13
  2026.          stepinc variable, 16, 26, 27
  2027.          Steps between frames
  2028.             /S option, 7
  2029.          STOP statement, 21
  2030.          SUBCHAR statement, 22
  2031.          Subscripts, 16
  2032.          Support for RTAG, 30
  2033.          Syntax, 15
  2034.          TAN function, 13
  2035.          TANH function, 13
  2036.          Targa files, 4
  2037.          Time control, 28
  2038.          TOUR example, 29
  2039.          Trace program, 7
  2040.          TSX-32, 32
  2041.          Use of RTAG, 30
  2042.          VAR statement, 15
  2043.          Variables
  2044.             arrays, 16
  2045.             declaration of, 15
  2046.             initialization of, 15
  2047.             maximum length, 15
  2048.          Warranty, 31
  2049.          WHILE statement, 19
  2050.          WRITE function, 13, 25
  2051.