FracTrace Script (FTS) command descriptions
-------------------------------------------

An FTS file is a plain ASCII text file containing the commands and their
right parameters to describe a fractal surface and its rendering in 
FracTrace.

Lines may contain : - a single command
                    - multiple commands, separated by a semi-colon ';'
                    - comments, preceded by a back-slash '\'
                    - the combination of both commands and comments

Some good examples of FTS files can be found in the 'FTS-Files' directory.

A description of each individual command follows underneath:


Command              Description
-----------------------------------------------------------------------------
Title                Sets the title for the current surface(s). This title is
                     used for all file-handling. A string of maximum eight
                     characters is given as the sole parameter.
                     Example: Title Snowy

Frames               Sets the maximum number of 'frames'. The parameter is an
                     integer. 
                     Example: Frames 24

Scope                Sets the range of frames to be rendered. If you have set
                     the maximum number of frames to, say 24, it is possible
                     to set the range of frames to be rendered to any
                     interval within 1..24. The two parameters are the 
                     minimum and maximum frame number.
                     Example: Scope 3,18

Mandelbrot           Tells the program that the set to be used is the
                     Mandelbrot Set. This command takes no parameters.

Julia                Tells the program that the set to be used is a Julia
                     Set. This command takes no parameters.

Resolution           Sets the resolution of the surface to be calculated and/
                     or rendered. The units for this resolution may be 
                     regarded as pixels. The two parameters are the x and y 
                     resolution of the surface.
                     Example: Resolution 300,300

Range                Sets the range in the complex plane for the part of the
                     set that is to be calculated and/or rendered. The four
                     parameters are minimum x, maximum x (real axis), minimum
                     y, maximum y (imaginary axis). These values can best be
                     obtained from a normal Mandelbrot plotting program!
                     Example: Range -1.5,1.5,-1.5,1.5

Cval                 Sets the real and imaginary part of the point to 
                     calculate and/or render the Julia Set of. The two 
                     parameters are the real and imaginary part of the point.
                     Example: Cval 0.32,0.043

Smoothness           Sets the smoothness of the surface. The higher the
                     smoothness-value, the smoother the surface, and the more
                     calculations will be performed to obtain the potential 
                     of a point on the surface! The sole parameter is an
                     integer, which really should be at least about 100!
                     Example: Smoothness 120

Depth                Sets the depth of the iterations in the calculation of 
                     the potential of a point. The higher the value, the more
                     precise the set will be calculated, and again, the 
                     longer it takes to calculate a point-potential. The 
                     parameter is an integer in the range 1..127!!!
                     Example: Depth 100

Mountains            Tells the program to render the surface as a mountain.
                     This command takes no parameters.

Valleys              Tells the program to render the surface as a valley.
                     This command takes no parameters.

Light                Sets the direction of the light-vector. This vector
                     need not be normalised. Note that this vector is the
                     direction of the light-rays, ie. it points away from the
                     light source! The three parameters are the x, y, and z
                     components of the vector. (z always should be negative!)
                     Example: Light 0.5,1,-2        

Brightness           Sets the brightness of the light-source. The higher the
                     value, the brighter the light. The sole parameter is an
                     integer.
                     Example: Brightness 78

Steepness            Sets the steepness of the mountain/valley slopes. The
                     higher the value, the steeper the slopes. Note that the
                     magnitude of this value is disproportional with size of
                     the region indicated with the range command. The sole
                     parameter is an integer.
                     Example: Steepness 240

Dithering            Sets the color-dithering factor. Because the program
                     only uses 16 colors to render an image (due to the 4bit
                     nature of mode 12), abrupt color changes on the surface
                     may give a non-realistic feel to the image. Therefore,
                     a simple technique, called random dithering, is used to
                     produce intermediate 'pseudo-colors', which make the
                     color changes seem quite continuous. A value of 1 means
                     no color dithering. The sole parameter is an integer.
                     Example: Dithering 16

Shadows              Tells the program whether to calculate shadows or not.
                     The calculation of shadows slows down the rendering
                     quite drastically. The parameter is a string of the form
                     'On' or 'Off'.
                     Example: Shadows On

Interpolation        Tells the program whether to interpolate values in the
                     horizontal direction. Interpolating doubles the time 
                     needed for rendering an image, but it produces more
                     detail. An image created with interpolation off has
                     'mode 9' resolution, whereas images created with
                     interpolation on have a true 'mode 12' resolution.
                     The parameter is a string of the form 'On' or 'Off'.
                     Example: Interpolation Off

Offset               Sets the two 'screen offsets' for the image. A 
                     horizontal offset of 0 would place the image to the left
                     edge of the screen. A vertical offset of 0 would place
                     the image half way below the bottom edge of the screen.
                     Normally, the x (horizontal) offset should remain at 40,
                     and the y (vertical) offset should vary between 240 and
                     480, depending on the angle at which to view the 
                     image. The two parameters are the x and y offsets.
                     Example: Offset 40,380

Angle                Sets the viewing angles. The first value is the x angle,
                     a value of 0 makes you look at the image 'head-on'.
                     The second value is the y angle, which should be in the
                     range 15..90 to get a meaningful view on the image, 30
                     being a quite reasonable average. In the current 
                     versions of FracTrace, the x angle is best kept at 0!
                     The two parameters are the x and y viewing angles.
                     Example: Angle 0,25

Increment            Sets the x and y 'OS-Unit' increment steps when 
                     rendering the surface. These values are both best kept
                     at 4!
                     Example: Increment 4,4

Slope Front          Sets the front-slope range and steepness. For some 
                     images it will be necessary to use this feature to avoid
                     the artificial cut-off of the front-most edge of the
                     surface. When you do have an image that seems to be
                     'cut off' at the front edge, you should force the front
                     lines down with a certain steepness-factor!
                     The first value is the number of front lines you want to
                     pull down (one line corresponds with one resolution-
                     unit), the second value is the factor by which you want
                     to enlarge the steepness. These values should be 
                     obtained by trial and error. The two parameters are the
                     slope-range (in lines) and the steepness factor.
                     Example: Slope Front 30,5

Color                Sets the overall color of the surface. This color is
                     specified by an RGB-vector. The components of the RGB-
                     vector must be in the range 0..15! In current versions
                     of FracTrace the vector should be 15,15,15, as there are
                     still some problems with the ColourTrans module. Other
                     values may be used, but the only way to display these
                     created images correctly would be by '*ScreenLoad'ing
                     them (ie. not with !Paint or !FracTrace itself). The 
                     three parameters are the components of the RGB-vector.
                     Example: Color 15,15,15

Var                  Sets (declares) the names for user-variables. See the
                     paragraph 'Using frames' for further details on
                     user-variables. This command takes up to 100 parameters,
                     these being the names of the user-variables.
                     Example: Var min,max,radius

Show                 Shows the contents of the specified variable in the
                     'report' window. This command may be useful for 
                     debugging script programs. The single parameter is the
                     variable-name.
                     Example: Show radius
                                                           
Stop                 Immediately stops execution (ie. parsing) of an FTS
                     file. When you use subroutines, a 'stop' should be
                     put at the end of the main program, before the start
                     of the first subroutine!

                              -----------------

The best way to get to know these commands and their effects is by 
experimenting with the supplied FTS files. Try changing one parameter at a
time and noticing the change in the according image(s).


Using frames
------------

FracTrace provides a simple way to generate multiple images, called frames,
from one FTS file. This is done by allowing the user to replace any 
parameter by a variable or a constant expression. (The use of variables is
recommended over the use of constant expressions!)        
FracTrace allows the user to declare up to 100 user-variables. Declaration
of a user-variable is as simple as including it in the so called 'var-list'
at the beginning of a 'program'. This 'var-list' is just a list of names
you choose for your variables, preceded by the 'var' command, 
eg. : 'var count, loop, step, min, max', with the words after 'var'
referring to user-variable names.
These user-variables may be assigned any expression that is legal in
BASIC V!
There are also two other 'read-only' variables which the user may use in his
expressions: 'frames' and 'frame'. The variable frames is the number of
maximum frames set with the 'Frames' command. The other variable, frame, is
the current frame number which the program is processing, which of course,
is in the range 1..frames!
Most user-variables will be defined by an expression containing the frame
variable.
There are two ways of assigning an expression to a user-variable:

      1) by using the form 'variable=expression(frame)' 
         eg. : 'radius=60*SINRAD(frame)+100'
         no spaces are allowed in the expression to the right of '=' !!!

      2) by using the form 'variable=expression,expression,expression,...'
         eg. : 'height=12,23,34,45,56,67,78'    when frames would be 7

With the second form variable 'height' will be 12 for frame=1, 23 for
frame=2, 34 for frame=3,..., and 78 for frame=7. Of course, expressions
containing the variable frame (but no spaces!!!) may also be used in the
second from!

People who know Render Bender will be familiar with this method.
           

Conditional command execution
-----------------------------

FracTrace also allows conditional execution of commands with the 'if .. else
.. endif' construct!
The use of this construct is as follows:

      if expression
       commands
          .
          .
      else
       commands
          .
          .
      endif

Where 'expression' is again any legal BASIC V expression evaluating to TRUE
or FALSE, eg. 'frame+4 < frames' or 'xstep >= stepsize+0.2'.
Each opening 'if' must have a closing 'endif', an 'else' is optional.
The 'if .. else .. endif' constructs may be nested up to 32 levels deep!


Repeated command execution
--------------------------

a) The first loop-construct allowed in FracTrace is 'repeat .. until'.
   It is used as follows:

      repeat
       commands
          .
          .
      until expression

   With 'expression' evaluating to TRUE or FALSE as in BASIC V,
   eg. 'count > frames'.
   Each opening 'repeat' must have a closing 'until'.
   The 'repeat .. until' constructs may be nested up to 32 levels deep!

               
b) The second loop-construct allowed in FracTrace is 'for .. endfor'.
   It is used as follows:

      for variable=start to end by step
       commands
          .
          .
      endfor

   With 'start', 'end' and 'step' legal BASIC V expressions evaluating to a
   real number, eg. 'for cnt=-3 to max by 2' or 'for size=2 to 1 by -0.1',
   and 'variable' the name of a user-variable.
   Each opening 'for' must have a closing 'endfor'.
   The 'for .. endfor' constructs may be nested up to 32 levels deep!


Execution of subroutines
------------------------

A last feature of FracTrace is the ability to execute subroutines.
Each (part of a) subroutine is marked with a label, this label is a word
preceded by a dot '.', eg. '.routine1'.
Such subroutines are called in the following way:

      commands             \
         .                  \
         .                   \
      call labelname          > main program
         .                   /
         .                  /
      stop                 /

      .labelname            \
       commands              \
          .                   > subroutine 'labelname'
          .                  /
       return               /
                                
As you can see, execution of a subroutine is started with a 'call' command,
and ends with a 'return' command. Therefore, each 'call' MUST have a
'return'!!!
The subroutine-calls ie. 'call .. return' may be nested up to 32 levels
deep. (That includes recursion!)


Writing programs
----------------

You will certainly have noticed from the last three paragraphs that it is
possible to build small programs using the control constructs and variables
provided by FracTrace. These programs don't have to define a fractal surface
(they may do!), they can also be used to solve whatever - small - problem!
The FTS files 'Factorial', 'Fibonacci', 'Sum50' and 'MandelPot' are some
examples of such small programs.

                                                              Carl Declerck.
