     &Contents:CONTENTS&
     &Help:HELP&
     
                             ANIM8 3D Animator
                               Version 1.4
                                     
                               User's Guide
                           (c) 1996 Mark Willis
                                     
                             Wire Frame Studio
                             113 Bascomb Drive
                           Woodstock, GA  30189
                                     
                           maw01@mindspring.com
     
     The  Wire Frame Studio web site is  an art gallery and school for
     beginning to advanced computer artists.  Drop by and register for 
     our FREE Computer Art Print GiveAway!
     
                         &:WWW&Set your Web Browser to:
               http://www.mindspring.com/~maw01/wfstdio.html
     
     

     &:CONTENTS&CONTENTS
     
       &REVISIONS:REVISIONS&
       &WHAT IS ANIM8?:WHATIS&
       &ANIM8 FEATURES:FEATURES&
       &PREREQUISITES:PREQ&
       &SYSTEM REQUIREMENTS:SYSREQ&
         &HARDWARE:HARDWARE&
         &SOFTWARE:SOFTWARE&
       &REGISTERING ANIM8:REG&
       &UNREGISTERED VERSION:UNREG&
       &LEGAL STUFF:LEGAL&

       &INSTALLING ANIM8:INSTL&
         &UNLOAD ANIM8 ZIP FILE:INSTL1&
         &SETUP INITIAL CONFIGURATION:INSTL2&
         &SET UP YOUR PATH VARIABLE:INSTL3&
         &CUSTOMIZE THE RAYTRACER BATCH FILE:INSTL4&
         &RUN YOUR FIRST TEST:INSTL5&
         &SETUP YOUR IMAGE FILE VIEWER:INSTL6&
         &SETUP USER DEFINED PROGRAMS:INSTL7&
 
       &UNDERSTANDING ANIM8 - OBJECTS, KEYS, AND MACROS:OKM&
       
       &ANIM8 CONTROLS:CTRLS&
         &GUI Basic Terminology:CTRLS1&
         &Buttons:CTRLS2&
         &Pop Up Lists:CTRLS3&
         &Sliders:CTRLS4&
         &Scroll Bars:CTRLS5&
         &Dialogs:CTRLS6&
         &Edit Fields:CTRLS7&
 
       &THE ANIM8 SCREEN:SCRN&
         &PREVIEW WINDOW:PRVWND&
         &ANIM8 COORDINATES AND ROTATIONS:COORDS&
         &MESSAGE AND FREE MEMORY BAR:MEMBAR&
         &PROJECT PANEL:PRJPNL&
           &File Menu:FILEMENU&
           &Object Menu:OBJMENU&
           &Path Menu:PATHMENU&
         &VIEW PANEL:VIEW&
           &Grid:VP1&
           &Path:VP2&
           &Obj:VP3&
           &Link:VP4&
           &Prsp:VP5&
           &Angl:VP6&
           &Zoom:VP7&
           &Dist:VP8&
           &Pan:VP9&
           &Cam:VP10&
         &PATH EDITOR PANEL:PPNL&
           &Drag:PE1&
           &Size:PE2&
           &Spin:PE3&
           &X, Y, and Z:PE4&
           &+P and -P:PE5&
         &KEY PANEL:KPNL&
           &Using Animation Keys:KP1&
           &Animation Preview Controls:KP2&
           &Keyframe Animation:KP3&
           &Moving Keys:KP4&
           &Shifting Keys:KP5&
           &Changing the Total Frames:KP6&
           &Deleting Keys:KP7&
           &Assigning a Path to an Object:KP8&
         &RENDER PANEL:RPNL&
           &Render Button Option:RP1&
           &View current frame:RP1&
           &Edit source:RP1&
           &Preview 1, Preview 2, Final:RP1&
           &Build:RP1&
           &Play:RP1&

       &CONFIGURING ANIM8:A8CFG&
         &ANIM8 Components:CFG1&
         &Running a Raytracer from ANIM8:CFG2&
         &Running Other Programs from ANIM8:CFG3&
         &Setting Up an External Program:CFG4&
         &Passing Arguments to an External Program:CFG5&
         &Reserved Macro Definitions Table:CFG6&
         &Using Environment Variables as Macros:CFG7&
         &Source File Macros:CFG8&
         &Frame Macro:CFG9&
         
       &CONFIGURE MENU:CFGNMENU&
         &Verify Option:CM1&
         &Configuring Images:CM2&
         &Configuring Animation:CM3&
         &Configuring Build:CM4&
         &Configuring Player:CM5&
         &Configuring Image Viewer:CM6&
         &Configuring Raytracer:CM7&
         &PVTD and the Images Configuration:CM8&
         &Other Configuration Issues:CM9&
         &Keywords and Syntax Files:CM10&

       &DEMO FILES:DMOS&
       &FREQUENTLY ASKED QUESTIONS:FAQS&
       &HYPERTEXT HELP:HELP&


     &:REVISIONS&REVISIONS

     Changes for 1.3 (6/02/96):
         Added hypertext help system and enhanced documentation.

     Changes for 1.2 (1/26/96):
         Fixed bug in rotate keys to correctly convert from ANIM8's
         radian measurements to degrees before exporting. This fixes
         many rotate and look at problems.

     Changes for 1.1:
         Parser no longer forces input text to lower case.  This fixes
         the problem with  POVRAY's case-sensitivity on texture names.

         Allow mixed case input on raytracer setting dialog.


     
     &:WHATIS&WHAT IS ANIM8?  
     
     ANIM8  is  a  powerful  animation  environment that allows any PC
     animation hobbyist to build a sophisticated animation system from 
     a variety of inexpensive components.  With ANIM8, you can do your 
     rendering with POV, VIVID, or other ASCII text  based  raytracers
     and  set  up  your choice of image viewer, text editor, animation
     builder and player.  
     
     ANIM8's  Graphical  User  Interface  lets  you  create  and  edit
     keyframe data   quickly   and   easily.    Design  complex  three
     dimensional  spline  curve  paths  on  screen  and  even  preview
     animated motion  in real time!  Then edit, render, build and play
     directly from ANIM8's control panel.  



     &:FEATURES&ANIM8 FEATURES 
     
        Ortho views: Front, Right, and Top with pan and zoom
        Perspective view with pan, zoom, and angle control
        Camera view from camera object
        Camera objects can move, roll, zoom, and track other objects
        Link objects with configurable link types
        Hide/Show objects, paths, grids and links
        Create three dimensional spline paths with easy editing
        Assign any object to any path
        Optional path offset by object for following objects
        Set number of frames along path by object
        Path editing - drag, resize, rotate, flip x, y, or z
        Constrain path edits by axis
        Real time animation motion preview
        Modifiable preview play speed
        Step through frames, set highest frame number
        Assign keys to frame
        Keys can be any vector or scalar values used by raytracer
        Easeto and Easefrom control for natural looking motion
        Absolute and relative keys
        Edit, move, copy and delete keys
        Shift whole groups of keys in a single action
        Use macros to configure command line or source options
        Edit, build, and play directly from ANIM8
        Configure multiple rendering setting
        External command verification for debugging configuration
        Message bar provides on-line instructions
        Free memory display
     
     

     &:PREQ&PREREQUISITES 
     
     If you have  no  experience  with  rendering,  I  advise  you  to
     download  a raytracing package and spend a few weeks learning how
     to model, light, and render scenes  before  you  try  to  install
     ANIM8.  POVRAY is available at http://www.povray.org.
     
     Visit  &Wire  Frame  University:WWW&  for  courses  in  computer   art,
     raytracing and  animation.    You should understand the basics of
     the following topics before you start using ANIM8: 
     
         Modelling and Rendering 
         Image file formats 
         Image viewing programs 
         How computer animations work 
         Animation file formats (FLC/FLI/AVI) 
         DTA or other animation builders 
         Animation players 
     
     
     
     &:SYSREQ&SYSTEM REQUIREMENTS 

     &:HARDWARE&HARDWARE
     
     Any  system  you  would  seriously  consider running 3D rendering
     software on should be more than adequate to run ANIM8. ANIM8 is a 
     DOS based program.    Although  you  can  bring  up  ANIM8  under
     Windows,  you  may  have  trouble    swapping  from ANIM8 to your
     renderer, viewer, editor, etc.  Windows 95  provides  much better
     memory  management and  should handle  ANIM8 easily  within a DOS
     window  although  I have heard  some reports  of the mouse cursor
     appearing as a black block instead of the usual pointer icon.

     ANIM8 uses only conventional memory so it should have no problems 
     with your memory configuration.   If  you  can  run  a  rendering
     package  on  your machine, you can probably run it through ANIM8.
     ANIM8's conventional memory restriction  is  not  as  bad  as  it
     sounds.   It doesn't take much key data to create a sophisticated
     animation.  You will learn quickly that the major  bottleneck  in
     PC animation  is rendering speed.  You will probably never render
     so many objects that ANIM8's  lack  of  memory  space  becomes  a
     problem.  
     
     Mouse (and mouse driver under Windows 95).  
        
     Math coprocessor.  ANIM8  won't  crash without one but it is VERY
        slow.  


     &:SOFTWARE&SOFTWARE 
     
     Raytracer. ANIM8 comes  with  configuration  files  for  POV  and
        VIVID.  Any  raytracer  that accepts ASCII text files as input
        can probably be driven by ANIM8, see &Configuring ANIM8:A8CFG&.
        
     Image Viewer  -  The  simpler  the  better.  You want a DOS based
        viewer that accepts the image file name from the command  line
        and exits  quickly  and  cleanly.  VIEWTGA works well with POV
        and VIVID but I had trouble viewing PolyRay output with it.  
        
     Text Editor - The DOS EDIT program works well if you  don't  have
        another favorite.   Again,  simple is best.  The editor should
        accept a command line file name.
        
     Animation Builder - A builder creates the playable animation file 
        from a sequence of  rendered  images.    My  favorite  is  DTA
        (Dave's TARGA Animator).  
        
     Animation Player  -  PLAYFLC is a good choice.  It is small, fast
        and cheap and accepts command line file names.  

     
     
     &:REG&REGISTERING ANIM8 
     
     Registration gets rid of the nag screens that appear occasionally 
     within the program.  Sorry, but I  am  asking  a  small  fee  for
     registering  ANIM8.  This program is much more sophisticated than
     its predecessors and required a great deal of work to create.  
     
     The registration fee is only $10 (US). What a bargain!  
     
     How much of a bargain?  Here's a few current (late 95) prices for 
     typical PC animation systems: 
     
        Visual Reality 2.0   $400
        Imagine 4.0          $700
        3D Studio 4.0        over $3000
     
     Although ANIM8 alone does not provide the modelling and rendering 
     capabilities of the advanced systems, ANIM8  combined  with  POV,
     MORAY,  DTA  or  VFD,  and  your  favorite  player and viewer can
     provide YOU with a sophisticated and powerful computer  animation
     system for UNDER $100 DOLLARS!  
     
        ANIM8 Animator       $10
        POVRAY               free
        MORAY Modeler        35
        DTA                   35
        AAPLAYHI             free
        VIEWTGA               15
                            -----
        Total                $95
     
     Even  better, all these components are available as shareware, so
     you can assemble, test, and choose the components that suit  your
     needs BEFORE you have to spend any money.  
     
     
     
     Please  include  the following information with your registration
     fee: 
     
        Name    ___________________________________
     
        Address ___________________________________
     
        City    _______________________ State  ____
     
        Zip     ___________
     
        E-Mail  ____________________

     
        Where did you get your copy of ANIM8?
     
        __________________________________________________________
     
     
     Send check or money order, sorry no credit cards yet, to: 
     
        Wire Frame Studio
        ANIM8 Registration Offer
        113 Bascomb Drive
        Woodstock, GA  30189
     
     I will e-mail you a number that will  immediately  register  your
     copy and enable all of ANIM8's features.  


     
     &:UNREG&UNREGISTERED VERSION
     
     Yes,  the  unregistered  version  of  ANIM8  has  a  few disabled
     features but you can use the SAVE command, so this is more than a 
     demo version.  
     
     Restrictions in unregistered version: 
     
        Number of frames is 30 or less
        Edit source, Build, Play, and User Programs are disabled.
        The annoying nag screen will appear for 10 seconds at the 
        start of each session.
     


     &:LEGAL&LEGAL STUFF 
     
     By installing this Software package (ANIM8), you  are  consenting
     to be  bound  by  and are becoming a party to this agreement.  If
     you do not agree to all the terms of this agreement, delete ANIM8 
     and its associated files from your system.  
     
     
     WIRE FRAME STUDIO END USER LICENSE AGREEMENT 
     
     GRANT.  Wire  Frame  Studio   ("WFS")   hereby   grants   you   a
     non-exclusive  license  to  use its accompanying software product
     ("ANIM8").  
     
     You may: use ANIM8 on any computer you use on  a  regular  basis;
     and  copy ANIM8 for archival purposes, provided any copy contains
     all the original proprietary notices.  
     
     You may not: permit other individuals to use your registered copy 
     of ANIM8 except for demonstration  purposes;  modify,  translate,
     reverse  engineer,  decompile,  disassemble (except to the extent
     applicable  laws  specifically  prohibit  such  restriction),  or
     create  derivative  works  based on ANIM8; copy ANIM8 (except for
     back-up purposes); rent, lease, transfer  or  otherwise  transfer
     rights to ANIM8; or remove any proprietary notices or labels.  
     
     UPDATES.  This  license  does  not  grant  you  any  right to any
     enhancements or updates.  WFS may make bug  fixes,  updates,  and
     enhancements  available  electronically from time to time, but is
     under no obligation to do so.  (Hey, what do you expect for $10?) 
     
     TITLE. Title, ownership rights, and intellectual property  rights
     in  and  to  ANIM8 shall remain in WFS. ANIM8 is protected by the
     copyright laws of the United States and  international  copyright
     treaties.   Title,  ownership  rights,  and intellectual property
     rights in and to any project files  or  animations  created  with
     ANIM8  remain  the sole property of the applicable license holder
     owner and may be protected by applicable copyright or other law.  
     
     DISCLAIMER OF WARRANTY. ANIM8 is provided on an  "AS  IS"  basis,
     without  warranty  of  any kind, including without limitation the
     warranties of merchantability, fitness for a  particular  purpose
     and non-infringement.  This disclaimer of warranty constitutes an 
     essential part  of  the  agreement.    SOME  STATES  DO NOT ALLOW
     EXCLUSIONS OF AN IMPLIED WARRANTY, SO  THIS  DISCLAIMER  MAY  NOT
     APPLY  TO  YOU AND YOU MAY HAVE OTHER LEGAL RIGHTS THAT VARY FROM
     STATE TO STATE OR BY JURISDICTION.  
     
     LIMITATION OF LIABILITY. UNDER  NO  CIRCUMSTANCES  AND  UNDER  NO
     LEGAL  THEORY,  TORT,  CONTRACT,  OR  OTHERWISE, SHALL WFS OR ITS
     SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR ANY OTHER  PERSON  FOR
     ANY  INDIRECT,  SPECIAL,  INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF
     ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS  OF
     GOODWILL,  WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY
     AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES. IN NO EVENT WILL  WFS
     BE  LIABLE  FOR ANY DAMAGES IN EXCESS OF ANIM8'S ORIGINAL LICENSE
     FEE.  
     
     TERMINATION. This license will  terminate  automatically  if  you
     fail to   comply  with  the  limitations  described  above.    On
     termination, you must destroy all registered copies of  ANIM8  in
     your possession.  
     
     MISCELLANEOUS.  This  Agreement represents the complete agreement
     concerning this license between the parties  and  supersedes  all
     prior agreements  and  representations  between  them.  It may be
     amended only by a writing executed  by  both  parties.    If  any
     provision  of  this Agreement is held to be unenforceable for any
     reason, such provision shall  be  reformed  only  to  the  extent
     necessary to make it enforceable.  
     


     &:INSTL&INSTALLING ANIM8 
     
     You should have the following files  after unzipping the ANIM zip
     file.
     
        ANIM8.EXE        Graphical animation environment program
        ASWAPR.EXE       Job controller program
        PVT3.EXE         POVTICK 3.0 animation interpreter
        PVTD.EXE         Render driver program
        ANIM8DOC.TXT     Hypertext help text file
        A8HELP.EXE       Help text viewer
        READ_ME.TXT      Tells you to use the help viewer
        ANIM8POV.ZIP     POVRAY configuration and sample files
        ANIM8VIV.ZIP     VIVID configuration and sample files
        ANIM8.SYN        Default syntax file
     
     Installing  ANIM8  is  easy.   The  hard part is getting ANIM8 to
     execute other software properly.  Follow along step-by-step below 
     to get a basic system running.  
     
     I assume you already have AT LEAST a raytracer and viewer program 
     already installed and working somewhere on your machine.  
     
     If you are not using POV  or  VIVID,  you  should  read  all  the
     documentation  first  to understand how ANIM8 uses macro commands
     and batch files to create appropriate command  lines  and  source
     modifications to operate different raytracers.  Study the way POV 
     and VIVID are implemented, then decide how to interface with your 
     own programs.  
     
     
     &:INSTL1&1) UNLOAD ANIM8 ZIP FILE
     
     Since  you  are reading this, I assume you have unzipped the main
     file.  You should create a directory (such as C:\ANIM8) and  move
     all unzipped files to this directory.  

     
     &:INSTL2&2) SETUP INITIAL CONFIGURATION 
     
     If  you  plan to use the VIVID raytracer, unzip ANIM8VIV.ZIP into
     your ANIM8 directory.  
     
     If you plan to use the POVRAY raytracer, unzip ANIM8POV.ZIP  into
     your ANIM8 directory.  
     
     If  you  plan to use any other raytracer, unzip ANIM8POV.ZIP into
     your ANIM8 directory to provide a starting setup.  
     
     If you want to animate with multiple  rendering  systems,  create
     separate ANIM8 directories for each configuration.  
     
     
     &:INSTL3&3) SET UP YOUR PATH VARIABLE 
     
     You  should  have  the  home  directory of your raytracing system
     listed in your PATH variable.  Edit your AUTOEXEC.BAT  file  PATH
     line.   Consult  your DOS manual (or Windows 95) for instructions
     if you don't know what I am talking about.  
     
     You should also have all the programs for viewing, building,  and
     playing set up in one or more directories that are listed in your 
     PATH variable.  
     
     
     &:INSTL4&4) CUSTOMIZE THE RAYTRACER BATCH FILE 
     
     To use VIVID, no changes should be needed as long as your PATH is 
     set correctly.  
     
     To use POV, edit POVBAT.BAT and set the correct directory names.  
     
     For  another  raytracer,  modify POVBAT.BAT or create a new batch
     file to set up an appropriate command line call.  
     
     
     &:INSTL5&5) RUN YOUR FIRST TEST 
     
     If you are configuring ANIM8 for a raytracer other  than  POV  or
     VIVID,  copy  a  VERY  simple  source file to the ANIM8 directory
     before starting ANIM8. Make  sure  this  file  renders  correctly
     outside ANIM8.  
     
     Enter ANIM8  at  the  command  line in your ANIM8 directory.  The
     ANIM8 screen will appear.  If you get a message about  a  missing
     SYN  file,  you have not unzipped one of the configuration files.
     The syntax file (SYN) provides the key words  ANIM8  uses.    The
     "Configuring  ANIM8"  section  below  discusses  syntax files and
     keywords in detail.  
     
     Press the File button in the Project panel to pop up  a  list  of
     ANIM8 files in the current directory.  Select the SIMPLE.PVT file 
     for POV  raytracing,  or SIMPLEV.PVT for VIVID users.  If you are
     configuring ANIM8 for  another  raytracer,  copy  a  very  simple
     source  file  to the ANIM8 directory and open SIMPLE.PVT from the
     POV configuration files.  
     
     Press the Render button (directly below the File button a  little
     more than half way down the screen).  Choose the Preview 1 option 
     from the  pop  up list.  For raytracers other than VIVID and POV,
     enter the name of the source file you copied in earlier.    Press
     the Ok button and cross your fingers.  
     
     If  all  goes well, your raytracer will execute and render a test
     frame and you will be returned to the  ANIM8  screen.    In  case
     something  goes  wrong,  ANIM8  keeps  track  of the elapsed time
     whenever it swaps out to run another program.    If  the  program
     ends  in  less  than  three  seconds,  ANIM8  will  pause  before
     returning to the ANIM8 screen so you have a chance to  study  any
     error messages.  
     
     The most likely problems will be: 
     
     File not found problems.  Probably caused by a bad path name in a 
        batch  file or a missing directory that should be on your PATH
        variable.  Make any needed changes and try again.  
        
     Insufficient memory problems.  ANIM8 leaves memory  entirely  and
        chains to a much smaller animation interpreter named PVT3.EXE. 
        If  you  do  have  memory problems, you probably have too many
        TSR's, device drivers, or other programs running.   Shut  down
        as many other programs as you can before starting ANIM8.  
        
     Source syntax errors.  I tried to keep the demo files very simple 
        and generic but there is always the possibility your raytracer 
        version may   complain about my source syntax.  If so, fix the
        offending statements and try again.  
        
     
     &:INSTL6&6) SETUP YOUR IMAGE FILE VIEWER 
     
     If your raytracer output images are TARGA (.tga extension) go  on
     to the  next  paragraph.    Press the Configure button and choose
     Images from the pop up list.  Change the  TGA  extension  to  the
     appropriate extension and press Ok.  
     
     Press  the Config button and choose "Image viewer" from the list.
     The default viewer should already be set to VIEWTGA. Change  this
     to the viewer program of your choice.  If the program is not in a 
     directory on  your  PATH,  enter the entire pathname.  Be sure to
     leave the %i% after the program name.  This  is  an  ANIM8  macro
     that  expands  to  the  name  of  the current image file when the
     viewer command is  executed.    Press  Ok  to  continue.     Your
     configuration changes are saved automatically.  
     
     Press the  Render  button  and  choose "View current frame".  The
     frame you rendered earlier  should  appear.    Exit  your  viewer
     program.  You should return to the ANIM8 screen.  If you have any 
     problems, refer to the troubleshooting section above.  
     
     
     &:INSTL7&7) SETUP USER DEFINED PROGRAMS
     
     The three blank options at the bottom of the Render button pop-up
     are for user-defined commands.  Chose "User 1", 2, or 3 under the
     Config button  to enter a short menu description  and the command
     you wish to execute.  The description will  then appear under the
     Render button.

     If you need to  shell out to DOS often,  you can  set up a  "DOS"
     entry  under Render  and execute "command.com"  to create  a  new
     DOS shell.  Don't forget to exit back to ANIM8 instead of running
     another copy!
     
     
     Congratulations!    You   are   now  ready  to  begin  animating.
     &Registered copies of ANIM8:REG& also allow you  to  configure  a  text
     editor,  animation builder, and player to complete your animation
     studio.  This is discussed below under &Configuring ANIM8:A8CFG&.
     
     For now, let's learn about how an ANIM8 animation works...  



     &:OKM&UNDERSTANDING ANIM8 - OBJECTS, KEYS, AND MACROS 
     
     To understand how ANIM8 works, you must understand objects, keys, 
     and macros.  
     
     An object in ANIM8 represents some "thing" within the source file 
     that is given to the raytracer to render.  That thing can  be  an
     object, a group of objects, a part of an object, or an attribute, 
     special effect,  or  background.  An ANIM8 object can even be the
     viewpoint of the raytracer.  
     
     Keys tell what the object does.  For  example,  a  translate  key
     could  be  created  at  frame  1  to  place an object at location
     (0,0,1). Another translate key at frame 10 could  reposition  the
     object to  (0,0,10).    ANIM8  will  compute  the position of the
     object for each frame, in this case  (0,0,1),  (0,0,2),  (0,0,3),
     and so on up to (0,0,10) at frame 10.  
     
     How does  the  ANIM8 tell the renderer where the object is?  Here
     is a  small sample of POVRAY source code  illustrating  an  ANIM8
     macro: 
     
      object {
        box {<-5,-5,-5>,<5,5,5>}
        texture { pigment { color White } }
        translate < %my_cube translate% >  // <---- ANIM8 MACRO
      }
     
     The  translate  statement  contains the macro "%cube translate%".
     When ANIM8 finds this command in the source code, it will look up 
     the object named "my_cube" and compute the  translate  key  value
     for the  current  frame.    The  macro  will  be  replaced by the
     computed value and  the  results  written  to  a  temporary  file
     (tmp_rndr.pov) to pass to the raytracer.  
     
     For frame 5, the raytracer would see: 
     
      object {
        box {<-5,-5,-5>,<5,5,5>}
        texture { pigment { color White } }
        translate < 0.00000, 0.00000, 5.00000 >  // <---- ANIM8 MACRO
      }
     
     Objects  can  do much more than simply move from point A to point
     B.  Complicated three dimensional paths can  be  constructed  and
     assigned to  one  or more objects.  An object can be rotated with
     rotate keys.  The size can be change with scale keys.  
     
     Keys can change more than just  the  orientation  of  an  object.
     Keys can  be created for any scalar or vector value.  A scalar is
     a single floating point number.  A vector is  a  group  of  three
     floating point  numbers.   You can animate the color of an object
     with vector keys and the turbulence value of textures with scalar 
     keys.  You can animate, morph, and  change  practically  anything
     you can render!  
     
     The macro  illustrated  above  is  called an object macro.  ANIM8
     also provides several special macros to  modify  other  raytracer
     actions.   For raytracer that declare the image resolution within
     the source file, the macros %w% and %h% are used to set the width 
     and height of the image.   This  allows  ANIM8  to  render  quick
     previews  and higher resolution images without changes the source
     file.  
     
     ANIM8 has  no  idea  what  an  object  looks  like.    All   that
     information  is  stored  in the raytracer source in whatever form
     the raytracer supports.  Objects in ANIM8 are  displayed  in  the
     preview screen  as boxes.  You can set the preview bow dimensions
     for each object to get an idea of the relationships  between  the
     objects.   This  allows  you  to see how objects will move in the
     final  animation  but  cannot  show  you  colors,  surfaces,   or
     textures.  
     
     ANIM8  comes  with several demo files to illustrate simple linear
     motion, color animation,  path  animation,  object  linking,  and
     camera motion.    You  should  finish  reading  the  rest of this
     document, then study the demo files to see  you  to  create  your
     source macros.  
     
     
     
     &:CTRLS&ANIM8 CONTROLS 
     
     ANIM8  is  a DOS program with relatively simple graphic controls.
     Anyone  familiar  with  Windows  or  other  GUI  (Graphical  User
     Interface) systems should have no trouble with ANIM8.  
     
     You can  probably skip the next section.  If you have any trouble
     understanding how any of the controls work  within  the  program,
     come back and read this later.  

     
     &:CTRLS1&GUI Basic Terminology 
     
     Clicking  means  to  move  the  mouse  pointer  over a control or
     object, press a mouse  button  and  release  the  button  without
     moving the  mouse  pointer.  Clicking is used to activate buttons
     and select objects on the screen or items from a list.  
     
     Dragging means to move the move the mouse pointer  while  holding
     down one  of  the mouse buttons.  This action is used to move and
     rotate screen objects.  

     
     &:CTRLS2&Buttons 
     
     Move the mouse  cursor  over  any  button  and  press  any  mouse
     button.   The  button  will immediately change state (in or out).
     Release the mouse button to activate.   If  you  move  the  mouse
     cursor off the button before releasing, the button returns to its 
     original state and no action occurs.  
     
     Each  button  is  labeled  with  a letter or word to describe the
     action associated with the button.  If the button text  is  gray,
     the button  is  currently  disabled  and cannot be used.  Buttons
     with black text are enabled.  
     
     Some buttons are  toggle  switches,  such  as  the  Grid  button.
     Whenever  the  grid  is displayed in the preview window, the Grid
     button appears to be pressed in.  Clicking  on  the  Grid  button
     will  cause  the  button to "pop out" and the grid in the preview
     window to disappear.  
     
     Some buttons are grouped together, such  as  the  view  controls.
     Only one view will be active at a time.  Clicking any view button 
     causes  the  current  view  button  to "pop out" and the new view
     button to "pop in".  It is easy to tell what view you are  in  by
     seeing which view button is in.  
     
     
     &:CTRLS3&Pop Up Lists 
     
     Some buttons have options which "pop up" in a small list whenever 
     the button  is  clicked.  To select an option, click on a word in
     the list.  To cancel, move the mouse pointer completely  off  the
     list and  press any mouse button.  Buttons with pop up lists have
     a small mark in the lower right corner.  
     
     
     &:CTRLS4&Sliders 
     
     Buttons with a vertical line near the right edge are Sliders. The 
     first click brings up a pop up list with a light gray  number  as
     the last list item.  Moving the mouse up and down will change the 
     value of  the  number.    The  list  may also include one or more
     default values to pick from as well as a cancel option.  
     
     
     &:CTRLS5&Scroll Bars 
     
     ANIM8's scroll bars are not very fancy.  Only the dark  gray  end
     squares are useful, there is no "thumb" or page up/down control.  
     
     
     &:CTRLS6&Dialogs 
     
     Actions  that  require  more  complex  information will display a
     dialog box.  These windows can  contain  messages,  buttons,  and
     small areas of text that can be modified using the keyboard.  
     
     Every dialog  box  has  a  default  button.   Press Ctrl-ENTER to
     accept the default (hilighted)  button  action.    Press  ESC  to
     cancel the dialog.  
     
     
     &:CTRLS7&Edit Fields 
     
     Press  ENTER or TAB to advance the cursor to the next edit field.
     Use Ctrl-D to clear from the  cursor  to  the  end  of  the  edit
     field.   ANIM8 edit fields are always in insert mode, so whatever
     you enter will push all following characters to the right.    Use
     Del or  Backspace  to  remove  characters.    When  you reach the
     maximum  field  length,  any    other  characters   entered   are
     discarded.  

     
     
     &:SCRN&THE ANIM8 SCREEN 
     
     There  is  only one screen so all of ANIM8's many features can be
     accessed quickly and easily without having to  pay  attention  to
     what module or mode you are in.  
     
     The  screen  is  divided into several panels which group together
     related  controls and displays.  There are many buttons that  pop
     up lists  of choices.  For the sake of brevity, I will abbreviate
     commands such as "Press the  File  button  and  choose  the  Open
     option" to File/Open.  
     
     
     &:PRVWND&PREVIEW WINDOW 
     
     The  large  dark  area  between the panels is the Preview Window.
     Here you can see objects move, spin, change sizes, follow  paths,
     and track  other  objects.   You also edit path control points in
     this window.  Many views are available.  See The View Panel below 
     for more about views.  
     
     To the bottom left of the Preview Window is a  number  indicating
     the current animation frame number.  
     
     
     &:COORDS&ANIM8 COORDINATES AND ROTATIONS
     
     ANIM8  uses  a  "Z  is  Up,  Positive  X to the right" coordinate
     system.   Many  advanced  graphic  and  CAD  systems   use   such
     coordinates  but the default for many raytracers is "Y is Up". Be
     sure to set up your viewpoint with a statement like: 
     
        up (0 0 1) 

     to align your raytracers coordinate system with ANIM8's. See  any
     of the  demo  files  for  examples.   My apologies to anyone with
     elaborate models built with Y up coordinates.

     &:RADS&Rotations are measured in RADIANS in ANIM8.  A radian is 57.29578
     degrees.  The C math routines  that ANIM8 uses  expect radians so
     calculation time can be saved by not converting from degrees.
     
     
     &:MEMBAR&MESSAGE AND FREE MEMORY BAR 
     
     At the bottom of the screen are the Message Bar and  Free  Memory
     Bar.  The Message Bar displays &registration:REG& and version info, the
     current file name, and  instructions  depending  on  the  current
     active tools.  
     
     The Free Memory Bar shows how much memory is available.  ANIM8 is 
     a  16  bit  DOS  application  with no use of extended or expanded
     memory.  As strange as this  seems  among  today's  32  bit  mega
     applications,  it  turned  out  quite adequate for ANIM8's needs.
     Don't panic if you have 16 Meg of memory and ANIM8 says only 400K 
     is available, you will never see more than around 500K. Trust me, 
     400K can hold more objects  and  keys  than  you  would  care  to
     animate on a PC (in 1995 anyway!).  
     
     If  free  memory  drops below 80K, seriously consider saving your
     work and exiting.  Remove any TSRs or extraneous  device  drivers
     and restart.      Below   80K   you  may  see  strange  behavior,
     particularly  dialog  boxes  that  don't  clear  off  the  screen
     correctly  because  the  background  image  buffer  could  not be
     allocated.  
     
     
     &:PRJPNL&PROJECT PANEL 
     
     This panel contains the File, Object, and Path  buttons  and  the
     Object and Path list windows.  

     
     &:FILEMENU&File Menu
     
     File/New 
     
     This command  clears  all  information from memory.  A dialog box
     will appear to confirm this action.  
     
     File/Open 
     
     Pops up a list  of  the  project  files  (.PVT)  in  the  current
     directory.  There  is  a  limit  to  the number of files.  If you
     don't see the project you want to open, select  Other  and  enter
     the file name in the resulting dialog.  
     
     File/Save 
     
     Saves  all  objects, paths, and animation information to the file
     named in the resulting dialog.  
     
     File/About 
     
     Displays &registration:REG& information and accesses  the  registration
     dialog for unregistered copies of ANIM8.  
     
     File/Quit 
     
     Exit ANIM8. A dialog will appear to confirm this action.  You can 
     also press ESC to exit ANIM8.  
     
     
     &:OBJMENU&Object Menu
     
     Object/New
     
     Creates  a  new  object.    A  default  object  name is  provided
     Objects will be discussed in  more detail  shortly.  You can also
     create a new object by clicking your right mouse  button  on  the
     "(new  object)"  line  of the object list window.  No two objects
     can have the same name.  
     
     Object/Edit 
     
     Allows you to change the name, preview size, and visibility  flag
     for an  object.  You can also edit an object by right clicking on
     the object's name in the object list window.  
     
     Object/Copy
     
     Creates a copy of the object and all its  keys  to  a  new  object
     name.  A default new name is provided.  
     
     Object/Delete 
     
     A confirmation  dialog  will  appear.    This  deletes the object
     definition and all keys associated with the object.  
     
     Object/Links 
     
     Brings up the links dialog window.  This allows any object to  be
     linked to  another  object.    You can link the position rotation
     and/or scale on any axis to the  transformations  of  the  parent
     object.   You  can  also  track  the parent object with the child
     object's Y  axis  with  a  "lookat"  link.    Links   and   their
     applications will be discussed in detail below.  
     
     
     &:PTHMENU&Path Menu
     
     Path/New 
     
     Creates a new path.  The path is a short curve with three control 
     points.   Use  the  Path  Editor  controls to add more points and
     reshape the path.  
     
     Path/Edit 
     
     Allows you to change the name and visibility flag.  
     
     Path/Copy 
     
     Creates a copy of the path offset slightly from the original.  
     
     Path/Delete 
     
     A confirmation dialog will appear.  This deletes the path.  
     
     Path/Flip X 
     
     Mirrors the path across an YZ plane through  the  center  of  the
     path.  
     
     Path/Flip Y 
     
     Mirrors the path across an XZ plane.  
     
     Path/Flip Z 
     
     Mirrors the path across an XY plane.  
     
     
     &:VIEW&VIEW PANEL 
     
     This panel contains tools to set the current view type as well as 
     zooming   and  panning.    Path editing can be done in any of the
     orthogonal views.   Click  and  drag  in  any  open  area  of  an
     orthogonal view to pan the view left to right and up and down.  
     
        Frnt Sets Front orthogonal view 
        Rght Sets Right orthogonal view 
        Top Sets Top orthogonal view.  Default view.  
        In Orthogonal zoom in 
        Out Orthogonal zoom out 
     
     The next  four  buttons  are  display  toggles.  If the button is
     pushed in, the corresponding entity is visible,  other  they  are
     hidden.  
     
     &:VP1&Grid 
     
     Orthogonal views display a rectangular grid.  The Perspective and 
     camera views show a 100 unit square on the XY plane.  
     
     &:VP2&Path 
     
     Displays or  hides all paths.  Hiding paths greatly increases the
     refresh speed of the Preview  Window.  Individual  paths  can  be
     hidden  by  right  clicking on the path name in the path list and
     pressing the Hidden/Visible button in the path edit dialog.  
     
     &:VP3&Obj 
     
     Displays or hides all object boxes.  Individual  objects  can  be
     hidden  by  right  clicking on the object name in the object list
     and  pressing  the  Hidden/Visible  button  in  the  object  edit
     dialog.  
     
     &:VP4&Link 
     
     Show or  hide the link relationship among all the objects.  Links
     are shown as brown lines connecting the centers of the parent and 
     child objects.  
     
     
     The next five buttons control the Perspective view.  
     
     &:VP5&Prsp 
     
     Select Perspective view.  The default view position  is  slightly
     above and to the right of the origin.  
     
     &:VP6&Angl 
     
     Turns on  the  Angle  view  tool.   Click anywhere in the Preview
     Window and drag to  spin  the  view  around  the  origin  of  the
     coordinate system.  
     
     &:VP7&Zoom 
     
     Click and drag in the Preview Window to zoom in and out.  
     
     &:VP8&Dist 
     
     Click  and  drag  to  adjust  the focal length of the perspective
     viewer.  
     
     &:VP9&Pan 
     
     Click and drag to pan the view up and down.  This is the  default
     tool.  
     
     &:VP10&Cam 
     
     The last View button enables the Camera view.  
     
     In  Camera  view  a dashed frame appears around the outer edge of
     the Preview Window. This shows approximately  the  boundaries  of
     the rendered image if you use the camera as the viewpoint for the 
     raytracer.  See the CAMDEMO1 or CAMDEMOV demo files to see how to 
     use cameras  in  your  raytracer  source.    The frame is only an
     approximation of the final view because each raytracer implements 
     viewpoints in a different way.  
     
     The camera view sets the viewpoint to the location of the  object
     named  "camera".  If no such object exists, ANIM8 will ask if you
     would like to create a camera object.    The  view  direction  is
     along the  cameras  positive Y axis.  The camera can be zoomed by
     setting scale keys to rescale the cameras Y length.  
     
     
     &:PPNL&PATH EDITOR PANEL 
     
     This panel contains most of the tools you use to edit paths.  The 
     Path button in the Project panel is used  to  create  and  delete
     paths and  contains options to flip a path around any axis.  
     
     An orthogonal  view  must  be  enabled  to edit a path.  Start up
     ANIM8 and create a new path to try out each of the tools.  
     
     You activate a path by clicking on its  name  in  the  path  list
     window.  The active path appears in red surrounded by white lines 
     whose endpoints  are the control points for the spline curve.  No
     matter what edit tool is selected, you can click  directly  on  a
     control point  and  drag  to  reshape  the  path.  Use the In/Out
     buttons on the View panel to zoom in and out as needed.  
     
     &:PE1&Drag 
     
     This override the  normal  panning  of  an  orthogonal  view  and
     instead moves the active path when you click and drag in any open 
     area to move a path.  
     
     &:PE2&Size 
     
     Select  this  tool,  then  click and drag to scale the path along
     either axis.  
     
     &:PE3&Spin 
     
     Click and drag to rotate the path.  
     
     &:PE4&X, Y, and Z 
     
     These are toggles that enable and disable a tool's effect along a 
     particular axis.  For  example,  if  you  wish  to  move  a  path
     horizontally  only,  select  Frnt  view,  click on the Drag tool,
     press Z to disable the Z axis, then drag the path.  The path will 
     only move horizontally.  
     
     &:PE5&+P and -P 
     
     These are used to add and delete path control points.   Click  on
     any control point to hilight it.  (It becomes a solid white box.) 
     Press -P to delete the point or +P to add a new point between the 
     selected control point and the next control point on the path.  
     
     
     &:KPNL&KEY PANEL 
     
     In  this  panel  you create, edit, and delete keys, set the total
     number of frames for  the  animation,  and  operate  the  Preview
     Window animation.  
     
     Enter  ANIM8 and choose Object/New and accept the default values.
     A small square will appear in the Preview Window. Press  Prsp  to
     enter perspective view.  
     
     Any key  operations  affect only the active object.  You activate
     an object by clicking on the object's name  in  the  object  list
     window in the Project panel.  The active object's name is display 
     in  white  text  and  the object's image in the Preview Window is
     hilighted.  
     
     Keys assigned to the active object appear in the list  window  at
     the left of the Key panel.  The right part of the key panel shows 
     which frames  have keys of the type listed.  The upper area shows
     frame numbers from 1 to 999.  The is called the Frame  Line.  The
     open  area below the Frame Line is called the KeyFrame area since
     it relates keys to specific animation frames.  
     
     If you click along the Frame Line will see that the current frame 
     number in the Preview Window jumps to the selected frame.  
     
     
     &:KP1&Using Animation Keys 
     
     Assuming you have a new object selected, press on the Add  button
     at  the  bottom  of  the Key panel if it is not already selected.
     Click in the KeyFrame area directly below the  number  1  in  the
     Frame Line.  A  dialog  box  will  appear.  Click on the key type
     button to see a list of key words.  Select the translate key word 
     and then press the Ok button.  
     
     A small gray box will appear at the upper left  of  the  KeyFrame
     area  and  the word translate will appear in the key list window.
     This tells you that a  translation  key  exists  for  the  active
     object at frame 1.  
     
     Now press  the Copy button at the bottom of the Key panel.  Click
     directly on  the  first  key.    A  white  square  should  appear
     surrounding the  selected  key.   Move your mouse to the right to
     drag the square all the way to frame number 30 and  click  again.
     A new key box will appear.  
     
     Click  on  the  new  key  and make a copy at frame number 15. You
     should now have three translate keys.  
     
     Click on the Edit button at the bottom of the Key panel and  then
     click on  the  key at frame 15. A dialog box will appear.  Change
     the THIRD floating point number to 40.0 and press Ok.  
     
     
     &:KP2&Animation Preview Controls 
     
     To the left of the Key panel are several buttons used to  control
     the  Animation  Preview.  Click  the  First  button  to reset the
     preview to frame 1.  Click the Next button.  The cube  will  rise
     slightly  and  the frame number in the preview window will change
     to 2. Click Prev (previous) to return to frame 1.  
     
     Click on Play to see the object move  up  and  down.    The  Play
     button  will change to Stop. Click on Stop to halt the animation.
     Depending on your system speed, you may want to adjust  the  play
     speed.  Click on the Speed button and move your mouse up and down 
     to change the speed value.  
     
     You  can  run  the  animation  preview  while you are doing other
     things in ANIM8 but your system's response time may  be  poor  if
     you have a slow machine.  
     
     
     &:KP3&Keyframe Animation 
     
     By  now  you  should realize how KeyFrame animation allows you to
     create  complex  animation  sequences  with   relatively   little
     effort.   With  three  simple  keys  you  have  created a natural
     looking animated motion.  ANIM8 takes care of calculating all the 
     position values  between  the  key  frame.    This  is  known  as
     "tweening" in animation terminology.  
     
     Classical animation studios used apprentice artists as "tweeners" 
     to  do  the  laborious task of filling in motions between the key
     frames  images the more experienced master animators produced.  


     &:E2EFRM&Easeto and EaseFrom

     If ANIM8  always  computed  points  between  key frames as evenly
     distributed values,  the  resulting  movements would be stiff and
     mechanical.  You may want this kind of motion  if you are doing a
     robot animation  but most of the  time it is better to adjust the
     the  rate of change  around  a key  frame  to create more natural
     motion.
     
     If you toss a ball in the air,  it will slow down and stop before
     falling  then pick  up speed  as it falls.  Such  motions  can be
     created by adjusting the easeto and  easefrom controls in the Key
     Edit dialog.

     Here's an example.  Start ANIM8 and load the demo, SIMPLE.PVT. In
     this demo,  a single object  moves up and down  through 30 frames
     controlled by three translate keys.

     Click  on  the "Edit" button  at the bottom of the Key Panel then 
     click  on the translate key at frame 1.  At the bottom of the Key
     Edit Dialog is  a hatched  line with  unevenly spaced marks and a 
     small circle  at the  middle of the line.  The line is called the
     Frame Spacing Indicator.  The small circle represents the current
     key frame.
     
     The Key Edit dialog should show both ease values set to 50 (if you
     haven't changed  the demo.)  Click  on  the easeto slider and move
     your mouse up and down. Note the changes to the spacing indicator.
     At an easeto value of  0,  the frames  approaching the key  become
     exactly evenly spaced.  As the easeto value increases,  the frames
     become more densely packed near the key. This results in an object
     slowing down as it approaches the key.

     Changes  to  the easefrom slider  result in similar adjustments to
     frames after the current key.  Set the easeto  and easefrom values
     to 0. All frames should be evenly spaced across the indicator.

     Click on Ok to save the key changes. Click on the translate key at
     frame 30 and set both ease values to 0 and save.  Click on the key
     at frame 15 and set both ease values to 80. Now play the animation
     preview. The box will jump upward,  slow down, stop, and then fall
     back down  in a  very natural motion.  Setting  the ease values to
     100 causes the box to appear to hang briefly before falling.

     Although motion  is an easy way to illustrate easeto and easefrom,
     ease values are not just for translate keys.  You can also  adjust
     rotation and scale rates, color changes, light source intensities,
     in fact, any key can have ease values for extra special effects.
     
     
     &:KP4&Moving Keys 
     
     Click on the Move button and drag the key at  frame  15  over  to
     frame 25.    Play  the  preview and notice how the cube now rises
     more slowly and falls quickly.  Move the middle key to  different
     frames and observe the changes in the animation.  

     This  real-time  preview  feature  is  probably  ANIM8's greatest
     contribution to animation hobbyists.  No longer do  you  have  to
     what minutes  or  even hours to see the results of change.  ANIM8
     lets you experiment with new ideas NOW!  I sincerely  hope  ANIM8
     will  fire  up  your  imagination and let you produce truly first
     class animations even on a limited budget.  
     
     If you have multiple keys at a single frame  (such  as  translate
     and  rotate),  you can click in the Frame Line to select all keys
     and move them all at once.  
     
     
     &:KP5&Shifting Keys 
     
     Click on the Shift button and move the middle  key  again.    The
     Shift tool  lets  you  select  a key and all later keys.  This is
     extremely handy when you need to insert new keys to fine  tune  a
     motion.  
     
     Click  in  the  Frame Line to select all keys in all frames after
     the selected frame.  
     
     You may have noticed the white move indicator square occasionally 
     turns red.  You cannot move to these locations because you  would
     be overwriting  a  key  of  the  same  type.    ANIM8 checks this
     automatically for you.  
     
     
     &:KP6&Changing the Total Frames 
     
     At the bottom of the Key panel just to the left of the Add button 
     is a  button with a number on it.  This is the  total  number  of
     frames in  the  animation.  Notice that the highest number on the
     Frame Line is the same as this number.   Unregistered  copies  of
     ANIM8 allow a maximum of 30 frames.  
     
     Press this button.    A  dialog  box  will appear.  Enter the new
     number of frames.  If you want to chop off or append  new  frames
     without  affecting  existing  keys,  select No for "Scale keys to
     fit?".  If you want to grow or shrink the total number of  frames
     but maintain the relationship among the keys, select Yes.  
     
     If  the  change  you  request  will cause any keys to be deleted,
     ANIM8 will warn you and let you decide to cancel or continue.  
     
     
     &:KP7&Deleting Keys 
     
     The Delete tool lets you delete individual keys.  A dialog always 
     appears to confirm the deletion.  If you want to get rid  of  all
     an  object's  keys,  it  is  easier  to  delete  the object using
     Object\Delete and create a replacement.  

     
     &:KP8&Assigning a Path to an Object 
     
     A path is assigned to an object by creating a path key.  The path 
     assigned is the currently selected (red) path.   If  no  path  is
     selected,  ANIM8  will  tell  you to select one before creating a
     path key.  You  can  change  the  path  assignment  by  selecting
     another  path,  Edit  the key, and reselect the path keyword from
     the keyword list.  
     
     Two path parameters are required.  The first number is the  total
     number  of  frames  required  for the object to travel the entire
     path length.  The  second is a number between 0.0 and  1.0.  This
     "offset" value allows you to start an object at any point along a 
     path.   This  feature  is  particularly  useful  for  flyby style
     animations.  
     
     In a flyby, the point of view of the renderer moves  through  the
     three  dimensional  scene  usually  looking in various directions
     while it travels through the scene.  Flybys generate particularly 
     large animation files but the results can be quite dramatic.  
     
     To create a flyby in ANIM8: 
     
        Create a camera object and assign it to a path.
        Create a dummy object and assign it to the same path with a
         slight offset, such as 0.05.
        Link the camera to the dummy object with a lookat link. Select
         the camera, then use Object/Links and click on the button
         below lookat.
        Study the CAMDEMO* source to see how to set up the camera and
         target in your raytracer source.
        Render your flyby and enjoy!
     
     
     &:RPNL&RENDER PANEL 
     
     ANIM8 communicates with the other components  of  your  animation
     studio using  the  options  under  the Render button.  What ANIM8
     does when you select a render option is set up with the Configure 
     options.  
     
     Each animation project consists of predictable stages.  
     
        Model objects, possibly low and hi-res versions
        Set up test stage and lighting
        Assign first draft of keys to establish rough motion
        Run a test render of the starting frame at low resolution
        View the results
        Run a higher res version and view the results
        Make any adjustment to stage and lighting
        Run low res images of important key frames
        Make adjustments
        Render a low res animation and play results
        Adjust any keys to fine tune motions
        Continue low res renders and adjust until satisfactory
        Render final scene

     &:RP1&Render Button Option
     
     The options available on the Render button reflect the real world 
     tasks  animators  must  perform  to  craft  a  quality  animation
     sequence.  Support is provided for multiple resolution rendering, 
     access  to  the  raytracer source for editing, viewing individual
     frames, and building and playing animations.  
     
     &:RP2&View current frame
     
     Executes your choice of image viewer program passing the name  of
     the current frame's image file.  
     
     &:RP3&Edit source
     
     Executes  your  choice  of  text  editor  passing the name of the
     appropriate raytracer source file. This option is disabled in the
     unregistered version of ANIM8.
     
     &:RP4&Preview 1, Preview 2, Final
     
     These options bring up a dialog box that lets  you  choose  which
     frames  to  render  and  which source file to associated with the
     ANIM8 project.  The default is to render only the current  frame.
     Press All to render all frames or slide the Start, Stop, and Step 
     Frame values as needed.  
     
     &:RP5&Build
     
     Executes your choice  of animation builder.  Not available in the
     unregistered version.
     
     &:RP6&Play
     
     Executes your choice  of animation player.  Not available  in the
     unregistered version.
     
     
     
     &:A8CFG&CONFIGURING ANIM8 

     &:CFG1&ANIM8 Components
     
     If  you are running POV or VIVID and ANIM8 is working properly on
     your system, you may wish to skip ahead to the Demo section.  The 
     following describes in detail how ANIM8 is configured to  execute
     a variety of programs.  
     
     The ANIM8 system is composed of several programs: 
     
     ANIM8 
     
     The graphical user environment.  
     
     ASWAPR 
     
     ANIM8  Swapper.  This  small  program  runs  your  viewer, editor
     builder and player and then restarts ANIM8.  
     
     PVT3 
     
     The animation interpreter.  This program reads  a  PVT  animation
     file  and  the  raytracer source and writes out a source file the
     raytracer can render.  
     
     PVTD 
     
     A driver for the interpreter.  This program runs PVT3 to  produce
     the  source  file  readable  by  the  raytracer,  then  runs  the
     raytracer to create the image file.  
     
     Why all these different program?  The main reason is to  minimize
     memory  usage  by  ANIM8.  When an external program is run, ANIM8
     writes a file called $ANIM8.SWP that  contains  all  the  current
     view and  option  settings.    ANIM8 then executes ASWAPR or PVTD
     using a system call that completely removes  ANIM8  from  memory.
     ASWAPR  and  PVTD  restart  ANIM8  later with a switch that tells
     ANIM8 to restore its previous settings from the SWP file.  
     
     This makes it appear that you are running  another  program  from
     inside  ANIM8,  but  you  are  actually  quitting ANIM8 entirely,
     running a very tiny control program, and  restarting  ANIM8  from
     scratch.  
     
     From  the  point  of view of the external program, the only extra
     memory overhead is about 20 K taken up by  the  control  program.
     
     No  matter  how big or complex your animation gets, this overhead
     remains constant!  


     &:CFG2&Running a Raytracer from ANIM8 
     
                 ---------       _____________
         /-----> | ANIM8 | <--> ( $ANIM8.SWP (  Screen settings
        /        ---------       -------------
        |              V
        |      ______________
        |     ( $RENDER.PVT (  Temporary animation file
        |      --------------
        |              V
        |            ---------
         \-----------| PVTD  |  Animation Driver
                     ---------
       _____________     ^
      ( SOURCE.??? (     |  for each frame
       -------------     |
           |   __________|___________________
           V   V                            V
         --------    _____________   -------------    ______________
         | PTV3 |-> ( TMP_RNDR.? (-> | RAYTRACER |-> ( $$$0001.??? (
         --------    -------------   -------------    --------------
        Interpreter                          One image file per frame
     
     
     
     &:CFG3&Running Other Programs from ANIM8 
     
             ---------       _____________
     /-----> | ANIM8 | <--> ( $ANIM8.SWP (  Screen settings
    /        ---------       -------------
    |            V
    |         ----------
     \--------| ASWAPR |  Swapper program
              ----------
                 ^ 
         ________|____________________________
         V           V          V            V
     ----------  ----------  -----------  ----------
     | VIEWER |  | EDITOR |  | BUILDER |  | PLAYER |
     ----------  ----------  -----------  ----------
     
     
     &:CFG4&Setting Up an External Program 
     
     Let's start by looking at the simplest external  call,  the  Text
     Editor.  Start ANIM8 and press the Configure button in the Render 
     panel.  Choose the last option, "Text editor".  A long dialog box 
     will appear  with  the  default  EDIT  editor.   No arguments are
     needed.  ANIM8 assumes you always want the name  of  the  current
     source file appended to the editor command line.  

     For  example, if your current project is set up to use SIMPLE.POV
     as the source file, choosing "Edit text" from the  Render  button
     options will generate the command: 
     
     EDIT SIMPLE.POV 
     
     To  use  a different editor, change the name in the "Text editor"
     dialog.  
     
     
     &:CFG5&Passing Arguments to an External Program 
     
     Raytracers, animation builders,  and  players  may  require  more
     complex command  lines than a text editor.  ANIM8 provides a very
     flexible  technique   to   construct   elaborate   command   line
     interfaces.  
     
     The  idea  of ANIM8 macros was introduced briefly earlier in this
     document.  A macro is any string surrounded by percent signs (%), 
     for example %w%, %object key%, %envvar%.  
     
     The are several one letter  macros  ANIM8  reserves  for  special
     items  such as the image width and height, the project name, etc.
     The  table  below  describes  each  of  these  reserved   macros.
     Reserved macros may be used in several parts of ANIM8.  
     
     Most  macros can be used in the command lines for your raytracer,
     builder, and player.  
     
     Preview 1, Preview 2 and Final render arguments can be configured 
     to pass different switches to the raytracer to adjust the  render
     speed and  quality.    These argument settings are referred to as
     %r% in the Raytracer command line.  As you can see from the table 
     below, it does not make any sense (n/a) to use %r% in the  render
     arguments  themselves,  since  the  string  would be referring to
     itself.  

     
     &:CFG6&Reserved Macro Definitions Table
     
     =================================================================
      Macro   Description             Command  Args  Src  Image Anim
     =================================================================
     |  p  |  project name             |  x  |  x  |     |     |     |
     |  f  |  frame number (0001)      |  x  |  x  |  x  |  x  |     |
     |  w  |  image width in pixels    |  x  |  x  |  x  |     |     |
     |  h  |  image height in pixels   |  x  |  x  |  x  |     |     |
     |  r  |  raytracer arguments      |  x  | n/a |     |     |     |
     |  i  |  image file name          |  x  |     |     | n/a |     |
     |  a  |  animation file name      |  x  |     |     |     | n/a |
     |  d  |  autodetect fli/flc       |     |     |     |     |  x  |
     |  t  |  image file template      |  x  |     |     |     |     |
     |  m  |  frame number template    |  x  |     |     |     |     |
     |  n  |  tmp render file basename |  x  |     |     |     |     |
     |     |  object/key macros        |     |     |  x  |     |     |
     |     |  environment variables    |  x  |     |  x  |     |     |
     =================================================================
      n/a = not applicable
     
     Bear with me, this will make more sense after we discuss  setting
     up each Configure option.  
     
     
     &:CFG7&Using Environment Variables as Macros 
     
     Whenever ANIM8 encounters a macro it cannot identify, the program 
     checks your  environment  variables  for  a  match.   Environment
     variables are created with the DOS SET  command,  usually  within
     your AUTOEXEC.BAT file.  
     
     
     &:CFG8&Source File Macros 
     
     The  use  of  macros  such  as  %object key% within the raytracer
     source was introduced earlier.  Such  macros  provide  the  links
     between  ANIM8 and your raytracer, but they are not the only type
     of ANIM8 macro you can insert into the raytracer source.  
     
     Some raytracer require the image resolution  be  declared  within
     the source  file instead of on the command line.  This is easy to
     accomplish with the %w% and %h% macros.   Here  is  some  example
     VIVID source to illustrate this: 
     
        studio {
            from -50 -140 55
            at 20 0 50
            up 0 0 1      // <-- note: use "Z up" for ANIM8!
            angle 80
            res %w% %h%   // <-- ***** ANIM8 macros *****
            aspect 4/3
        }
     
     These  macros  allow  you to select your preconfigured resolution
     settings (Preview 1, Preview 2, or Final) from the  ANIM8  Render
     options without having to worry about changing your source code.  
     
     
     &:CFG9&Frame Macro
     
     The macro  %f%  represents the current frame number.  This is the
     most widely available ANIM8 macro.  It can  be  used  on  command
     lines,  in  the  image  name  definition, in source files, and in
     render argument lists.  
     
     If ANIM8 is doing all the animation work, why would you need  the
     frame number  in  your  source  file?    Many  advanced animation
     systems provide a technique called rotoscoping.  Rotoscoping lets 
     an image map applied to an object be animated, such as flying  by
     a TV screen in your animation while the TV image is changing.  
     
     Rotoscoping with ANIM8: 
     
        Render a series of frames to use as image maps.
        Move the frames to a separate directory such as \myimages
        In your final animation add an entry such as:
            image_map { "\myimages\$$$%f%.TGA" }
        Render you final animation
     


     &:CFGMENU&CONFIGURE MENU

     
     &:CM1&Verify Option 
     
     The  Configure button includes an option labeled "Verify is ...".
     The default is "Verify is On". This setting is  a  debugging  aid
     whenever you  are making changes to your configuration.  When on,
     ANIM8 stops before running any external command and displays  the
     command after all macros have been expanded.  Make sure Verify is 
     On.  
     
     
     &:CM2&Configuring Images 
     
     The  Images  option under Configure tells ANIM8 how each rendered
     image  will be named.  The default value of $$$%f%.TGA produces a 
     series of image such as  $$$0001.TGA,  $$$0002.TGA,  etc.    Most
     rendering  systems  support output in TARGA format (TGA). This is
     a 24  bit  TrueColor  image  format  supported  by  almost  every
     graphics program available today.  
     
     If  you  do require a different format, change the extension here
     and in the default Builder configuration.  
     
     For example, if you produce image frame in BMP  format  and  want
     them  all  prefixed  with PIC, change the Images configuration to
     "PIC%f%.BMP".  
     
     Always include the %f% macros in any Images configuration so each 
     image will be assigned the correct sequential frame number.  
     
     
     &:CM3&Configuring Animation 
     
     Animation tells ANIM8 the name of the final animation file.   The
     cryptic default value %p%.%d% contains ANIM8's macros for project 
     name and a special autodetect FLI/FLC macro.  
     
     AutoDesk's  FLI and FLC  are  very  popular  and  well  supported
     formats.  The FLI format only supports 320x200 resolution,  while
     FLC format  supports  multiple  resolutions.  Some builders, like
     DTA, default to FLI output  whenever  the  input  image  size  is
     320x200 and FLC for other sizes.  
     
     This  poses  a problem for ANIM8. If the animation file extension
     changes depending on resolution, how can ANIM8 know which or  the
     FLI or  FLC files to pass to the animation player?  The %d% macro
     solves this problem.  When ANIM8 finds this macro, it  looks  for
     both  FLC  and  FLI animations and determines which is the newest
     (latest timestamp).  
     
     Assume your project is name MYFIRST and  you  are  doing  FLI/FLC
     animations.   If you render and build a short low-res sequence as
     MYFIRST.FLC and ask  ANIM8  to  play  it,  ANIM8  will  look  for
     MYFIRST.FLI and MYFIRST.FLC. Finding only the FLC file ANIM8 will 
     expand  %p%.%d%  to  MYFIRST.FLC.  If you then render and build a
     320x200 final version to MYFIRST.FLI, ANIM8 can tell that the FLI 
     was created later than the FLC and correctly expands  %p%.%d%  to
     MYFIRST.FLI.  
     
     
     &:CM4&Configuring Build 
     
     The Build process assembles all the individual image files into a 
     compressed animation  format.  Several DOS animation builders are
     available; my favorite is DTA. You should  study  your  builder's
     documentation carefully.  Some builders provide gamma correction, 
     overlays, motion blur and many other useful features.  
     
     The default build configuration is: 
     
     DTA $$$*.TGA /o%p%.FLC 
     
     Change DTA to the name or pathname of your builder.  The $$$*.TGA 
     portion  of the command should correspond to the image file names
     set up using  Configure/Images. The output animation file is  set
     with /o%p%.FLC to include the ANIM8 project name.  
     
     
     &:CM5&Configuring Player 
     
     Default is: 
     
     PLAYFLC %a% 
     
     The %a% macro expands to the current animation file name.  Change 
     PLAYFLC to the name or pathname of your animation player.  
     
     
     &:CM6&Configuring Image Viewer 
     
     Default is: 
     
     VIEWTGA %i% 
     
     The %i% macro expands to the image file name of the current frame 
     number  display  at  the bottom left of the Preview Window. There
     are many PC image file viewers available today.   Change  VIEWTGA
     to the name or pathname of your favorite.  
     
     
     &:CM7&Configuring Raytracer 
     
     Configuring a  raytracer can be a challenging task.  Luckily, POV
     and VIVID users can use the preconfigured setups that  come  with
     ANIM8.  
     
     
     The  first  step  is to identify switches and options you need to
     communicate adequately with the raytracer.  
     
     Next, assign each option to the proper ANIM8 location.  
     
     Options that are always the same are best assembled into a  batch
     file which  ANIM8  can  call.   For example, ANIM8 uses the batch
     file POVBAT.BAT to invoke the POVRAY raytracer:  
     
        c:\povray2\povray -lc:\povray2\include -p -d +v +ft  +x  +b100
     %1 %2 %3 %4 %5 %6 %7 %8 %9 
     
     Here  options  such  as nopause (-p), no display (-d), output TGA
     format (+ft), etc.  are set up.  Notice the  use  of  %1  %2  %3,
     etc.   This  allows  up  to  9  arguments to the batch file to be
     passed through to POVRAY.  
     
     Options that vary between raytracer runs should be set  up  under
     the Configure/Raytracer. The default POVRAY configuration is: 
     
        POVBAT %r% -w%w% -h%h% -i%n%.pov -o%t% 
     
     The  Preview  1,  Preview  2,  and Final options allow you to set
     three different rendering setting.  You can  set  separate  image
     widths  and  heights  as well as entering arguments to adjust the
     raytracer's image quality.  
     
     POVRAY gets its image file resolution  information  from  command
     line switches.    The  %w% and %h% macros expand to the width and
     height of the current render  settings.    %r%  is  the  optional
     render setting arguments.  
     
     The  macro  %n%  expands  to the basename of the temporary source
     file that will be passed to the raytracer to render.   This  name
     is  always  TMP_RNDR, so POVRAY will always be given TMP_RNDR.POV
     to render.  
     
     
     &:CM8&PVTD and the Images Configuration 
     
     The %t% macro expands to the contents of the Images configuration 
     string.  The default is "$$$%f%.TGA". Don't you %i% here!    Here
     you  want  to  pass  the  template,  not  the current image name,
     because you are calling the PVTD driver instead  of  calling  the
     raytracer directly.    Since  PVTD  calls your raytracer for each
     frame, it needs to know how to construct an  image  filename  for
     each frame  number.   This is exactly the information provided by
     the %t% macro.  
     
     
     &:CM9&Other Configuration Issues 
     
     VIVID does not output TGA files directly.    Instead  a  separate
     program   must be run to convert the IMG output to TGA. Study the
     VIVID.BAT file to see how this type of problem can be handled.  
     
     
     &:CM10&Keywords and Syntax Files 
     
     The keywords used by ANIM8 can be changed to match  the  reserved
     words  for  your  raytracer by editing the ANIM8.SYN syntax file.
     This is an ASCII text file you can edit  with  any  text  editor.
     Lines starting  with  //  are  considered  comments.  Information
     about editing the SYN files is contained in  the  SYN  file  from
     either ANIM8POV.ZIP or ANIM8VIV.ZIP.  
     
     Pay  attention  to the requirement that the first three keys must
     be the equivalent of translate, rotate and scale, in that order.  


     
     &:DMOS&DEMO FILES 
     
     VIVID demo file name end in V link SIMPLEV.PVT.  
     
     SIMPLE.PVT and SIMPLEV.PVT 
     
     A cube moving up and down over  a  checkered  plane.    About  as
     simple as you can get, this demo illustrates simple linear motion 
     with one object and three translate keys.  
     
     COLRMORF.PVT and CLRMORFV.PVT 
     
     Here is  an  easy  special  effect.  This demo illustrates how to
     morph smoothly from one color to another.  Experiment  with  this
     by   adding  a  color  mapped  texture  and  varying  the  colors
     separately.  Try  animating the values for turbulence  and  other
     settings.  The possibilities are endless!  
     
     PATHDEMO.PVT and PATHDEMV.PVT 
     
     Need more  sophisticated  motion control.  Study this demo to see
     how to add spline paths to your animations.  
     
     LINKDEMO.PVT and LINKDEMV.PVT 
     
     A  small  sphere  orbits  a  moving   larger   sphere   in   this
     demonstration of  linked  motion.   The little sphere follows the
     small path but is linked to the translation  values  of  the  big
     object.   Try editing both paths and study the resulting motions.
     Choose Object/Links and experiment with different link  settings.
     Turn on Link display with the Link button in the View Panel.  
     
     CAMDEMO1.PVT and CAMDEMOV.PVT 
     
     A  simple illustration of camera motion with ANIM8. In this demo,
     a sphere orbits a cube.  The camera stays at a fixed location but 
     has a lookat link to the moving sphere so the sphere  remains  in
     the center of the view frame in Cam view.  
     

     
     &:FAQS&FREQUENTLY ASKED QUESTIONS

     Here  are a  few questions  and problems  ANIM8  users have asked
     about.

     =================================================================
     "My rotations don't behave correctly! My objects spin faster than
     I told it too..."

     You are probably expressing  your rotations in degrees instead of
     &radians:RADS&.  Divide  degrees  by 57.29578 to  calculate  the  proper 
     rotation amount.

     
     =================================================================
     "When I render my object, it doesn't move like the preview."

     Make sure you calculate your translations  AFTER rotating in your
     raytracer source code.  Why?  Here's a simple example:

          <0,0,0>   original point
          <0,0,0>   rotate 45 degrees... trivial here
        + <1,0,0>   translate
          <1,0,0>   result

     But if you translate BEFORE you rotate:
    
          <0,0,0>   start
        + <1,0,0>   translate
          <1,0,0>   now rotate this point 45 degrees
          <0.707,0.707,0>    It's NOT the same!

     So instead of this:

     object {  // object1
         box <0, 0, 0> <-10, -10, -10>
         translate < %object1 translate% >
         rotate < %object1 rotate% >
     }

     Do this:

     object {  // object1
         box <0, 0, 0> <-10, -10, -10>
         rotate < %object1 rotate% >
         translate < %object1 translate% >
     }


     =================================================================
     "I have access to  powerful  non-PC  computers  to do really fast
     renders of my raytracer source. Is there a way ANIM8 can output a
     series of animated source files?"

     ANIM8  can create  source files series  with  the utility program,
     AURENAME, available at the &Wire Frame Studio:WWW& web site.

     
     
     &:HELP&HYPERTEXT HELP

     ACTION               USE ANY OF THESE KEYS
     ================================================
     help                 F1  ?
     contents             c  C
     jump to topic        enter (on hilighted link)
     next link            TAB
     quit program         ESC  q  Q
     string search        s  S  /
     repeat search        .  n  N
     previous position    b  B
     forward position     f  F
     previous link        Shift-TAB  p  P
     first line           HOME  h  H
     last line            END  l  L     
     down one line        DOWN-ARROW  d  D
     up one line          UP-ARROW  u  U
     down one page        PGDWN
     up one page          PGUP
     right one space      RIGHT-ARROW
     left one space       LEFT-ARROW
     
     In string search  entry,  press ENTER to begin search  or ESC  to
     to cancel.


     
     HAVE FUN!
     
     Good luck and let me know what you think.  My e-mail address is: 
     
     maw01@mindspring.com 
     
     Mark Willis 

     
     All material is (c) 1995, 1996 by Mark Willis 
     

     END OF ANIM8 DOCUMENTATION

