Document with FracTrace.
------------------------

FracTrace is a Public Domain program. It may be copied and shared freely, as
long as the files that go with the program are not modified. The program may
not be sold or made commercial profit of in any way, with the exception of
Archive's 'CareWare'!
The images created with FracTrace may be used in whatever way though!


What is FracTrace?

FracTrace is yet another program to display fractal sets (Mandelbrot and 
Julia of z=z^2+c, currently). It does this by means of simple raytracing;
raycasting would be a better term though! The fractal set is rendered as a
continuous height field (a 'surface', in normal English) which is lit by a 
light-source with parallel beams.
For each point on the height field the program calculates the intensity, 
depending on the angle of the incident light-ray with the surface normal in
that point. An option in the program allows for additional shadow 
calculations as well!
The program is fully RISC OS compatible and will perform most of its 
processes in the background.


The logic of FracTrace:

The different parameters needed to specify the surface's characteristics
are set using a script language: "FTS" (which stands for FracTrace Script).
The commands of this script can be used to exactly define what the program
should output.
The program also allows the user to calculate a potential map (a 2D-array
which holds the potential for each point on the surface), which can be
used, saved and reloaded, when rendering the 3D-image of the surface.
Using this map will speed up the program by a certain factor. It is more
memory-consuming though!
When the rendering process is finished, the image can be saved as a 
standard mode 12 sprite.


How to use FracTrace?

FracTrace (version 2.00 and above) runs completely from the RISC OS desktop.
Double-clicking on its icon in a filer-window starts the program... After a
succesful load, the program installs itself on the iconbar.

Clicking with Select (left-button) on the icon causes the 'report window' to
be opened: via this window, the program informs the user on what it's doing!

Clicking with Adjust (right-button) on the icon causes the 'view window' to
be opened: this window shows the image that is rendered.

Clicking with Menu (middle-button) on the icon brings up the icon menu, which
allows the user to see the program info ('About this program'...) and to quit
the program when you wish to do so!

Clicking Menu over one of the windows ('report','view' and 'panel') provided
by FracTrace brings up the 'Main FracTrace Menu': this menu gives you the 
actual control over the program, its items are described below...

Title      : Choosing this item allows you to enter a title-name for the 
             current image and its control parameters. Don't use more than
             8 characters!

Misc       : The miscellaneous submenu. From this submenu you can toggle the 
             'auto-parse' option (see below), toggle 'multitask' mode,
             open the RISC OS directory filer of your saving directory, abort
             the current process, or resume it.
             Setting the 'auto-parse' option will cause FTS files to be
             parsed immediately when they're dragged into the program.
             When 'multitask' mode is deselected, processes such as 
             calculating a potential map and raytracing take over the whole
             machine, ie. they don't multitask but they're faster!
             The 'open filer' option opens the filer of the directory in
             which FracTrace stores its output files. Normally, when you 
             want to save a file (Map, Image, or Script), you can drag the
             icon in a filer, which is the 'Acorn proposed' way of saving 
             files. However, when the program is rendering multiple images,
             then called 'frames' (for animation sequences), each 'frame'
             must be saved when rendering is finished, without the 
             intervention of the user. This is done in a directory that is 
             specified beforehand.
             The options 'abort' and 'resume' are for aborting and resuming a
             process respectively.   

Save       : From this submenu you can save your files:
             Map ... Saves the current map.
             Image ... Saves last rendered image.
             Script ... Saves a script file containing FTS commands for the
                      current parameter-settings.
             Saving is done in the conventional way, ie. by dragging the icon
             in a filer window.   
             Savepath ... Set the saving-directory for frames (see above).
                          This is also done by dragging the icon in a filer.

Process    : From this submenu you start one of the processes, being:
             Parse: Starts parsing (ie. interpreting) the last loaded FTS
                    file.
             Raytrace: Starts rendering the surface using the parameters set
                       in the last parsed FTS file.
             Calculate: Starts calculating the potential map for a surface
                        using the parameters of the last parsed FTS file.
             Any of these processes can be aborted at any time by either:
              - clicking on 'abort' in the 'report' window or icon menu. 
              - clicking any mouse button when in non-'multitask' mode.
             Note that only one of these processes can be active at a time.

Show       : With this submenu you can open the windows of FracTrace.
             The 'view' window shows the image of the current surface. When
             the program is rendering a surface, the contents of this window
             are only updated between each row of points being rendered.
             Clicking with select in this window causes an immediate update.
             The 'panel' window shows the parameters and their current
             values. The values may be changed at any time by clicking on 
             the value's icon and entering a new value from the keyboard.
             When you wish to update the parameters with the new values,
             click on the 'OK' icon in the right-hand bottom corner of this
             window, otherwise click on the 'Cancel' icon to preserve the
             parameters' values. Note that clicking on the window's back-
             ground has the same effect as clicking on 'OK'!
             The 'report' window is used by the program to inform the user of
             what it's doing. This window is constantly updated, except when
             no process is active, or when a process is running with
             'multitask' mode switched off.

Map        : From this submenu you can claim space for a map, with the 
             'claim map' option, you can free the space for this map, with
             the 'free map' option, and you can select to use the map when
             rendering a surface with the 'use map' option.
             The 'claim map' option tries to allocate enough space from the
             free pool to hold the data of a potential map. The size of this
             amount of space depends on the resolution of the surface you
             want to render (which is also the resolution of the map).
             When there isn't enough space left, the program will report an
             error and will show the amount of free space (in Kb) required.
             The user can then try to free some memory elsewhere using the
             Task Manager!
             The 'free map' option just frees the space allocated by 'claim
             map', returning the memory to the WIMP's free pool.
             The 'use map' option must be toggled on if you want the program
             to use the map when it is rendering an image.
             Note that when no map is claimed, all the submenu-options 
             concerning the map are 'shaded', ie. they can't be selected,
             because at that point, they simply are of no use! These are:
             'save map', 'calculate', 'free map' and 'use map'. You will also
             get an error when you want to load a map file and you haven't
             claimed map space.


It is possible to abort a process, quit FracTrace, and resume the same 
process at a later date. This is done by writing down the line-number at 
which you abort the process, and entering this line-number in the 'resume'
option-icon in the Control Panel with your next FracTrace session. When you
set this option and subsequently start the raytracing process, it will resume
at the line-number you entered in the icon!

If you are rendering multiple frames and want a new potential map to be 
recalculated for each different frame, you can do so by setting the
'recalculate' option in the Control Panel!

These explanations may seem 'cryptic' (and so they are!), but the best way
of getting to know FracTrace is by experimenting with the demo-files,
and trying to make some variations.


How to use FTS?
---------------
An FTS file is just a text (ASCII) file as can be made with !Edit.
When you drag an FTS file over one of the FracTrace windows it will be
loaded (provided it isn't longer than 4000 bytes), and -with the default
configuration settings- will be parsed automatically. When the 'auto-parse'
option is switched off, parsing can explicitly be started by selecting 
'parse' from the process submenu.
An explanation of each of the commands provided by FTS is given in the
file 'FTS-Def'.


Comments of the author:
-----------------------
This version of FracTrace certainly isn't the last to be released. As I (or
you) encounter bugs or 'ill behaviour' in the program, I will try to fix 
them in future versions and provide you with the updated releases!
If you find any bugs, have any comments or ideas you'd like to see 
implemented, write to the address below...

Address :          Carl Declerck
                   Vrijgeweidestraat 24
                   B-2800 Mechelen
                   Belgium
Phone   :          015-41.96.49

I can also be reached at Archive BBS as: Carl Declerck (#1071).
If you mail any comments, please allow about one week for a reply!


                                                              Carl Declerck.
