The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/f/fractalus/!Fractulus/Docs/Guide

Text File | 1995-05-04 | 17.2 KB | 408 lines

Fractulus, ©1994-1995 by Andreas Dehmel

Fractulus is rated Freeware: you may copy it freely but not
change any part of it (except for the Core directory).
Fractulus was written for RISC OS 3.

Although I have debugged it thoroughly I will not accept any
responsibilities for any damages caused to your computer or
data by using this program.
I would appreciate if you reported any errors you come across
so I can remove them (hopefully).



---------------------------------------------------------------
Changes since version 0.00:

- The usual number of bugs fixed
- Can now also compute 16/32bpp sprites and display them even on
  pre-RiscPC machines!
- Additional two words (extension) to pass to core
- Facilities to watch & modify batch file
- Make fractal movies
- Some new cores - including fixed point ones
---------------------------------------------------------------




                     FRACTULUS DOCS (v0.10)

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



Fractulus is a multitasking application for computing fractals.
By loading different cores you can compute different types of
fractals (standard Mandelbrot sets, Julia sets...). I should
mention, though, that most cores use FPA instructions and will
thus be *very* slow on machines not fitted with an FPA. Non FPA
cores included are "fix32" and "crazy32". People interested in
writing their own cores please refer to the CORES document.
On an FPA machine, though, it flies...


How to use:
-----------

Start up the program as usual by double clicking its icon in the
filer window. Fractulus will install its icon on the icon bar and
we're ready for action.
Clicking select or adjust on the icon bar icon will open a
Control Panel; you can have 8 of those active simultaneously.
Each Control Panel represents a fractal process - in english:
you can compute up to 8 fractals simultaneously.
Don't let the number of writable fields shock you - most of you
will never have to enter anything more than resolutions and
Iterations in here. Here's what everything means:

Continue, Pause, Abort, Display and Start are obvious.
Ratio: this determines if you want to preserve the ratio or
       allow distorted fractals. When ticked, min(im) is set
       so that (max(re)-min(re))/(max(im)-min(im) = resx/resy.
Resolution X/Y: What resolution the resulting fractal should
       have. These are mode 28 Pixels rather than OS units.
IterMax: Maximum iterations to do before breaking the loop and
       marking the current position convergent (black). High
       Iterations bring out more detail but slow computation
       down. Usually the deeper you get into a fractal set the
       higher you'll have to set IterMax.
IterPoll: Maximum iterations to do before returning control to
       the WIMP (actually no break occurs within the iterations
       loop, so the maximum number of iterations done will be
       between IterPoll and IterPoll + IterMax). The higher this
       number the less responsive the desktop but the faster
       computation. The default value (32768) works fine on an
       A5000 with FPA and the standard mandelbrot core. Users of
       A5000s or RiscPCs without FPAs should set this to no more than
       about 2000 (yes, the FPA speeds up things by a factor of
       30-40!).
Re/Im: The interval to compute. You should write the lower number
       in the left, the higher in the right writable field.
       Fractulus sorts the numbers but for order's sake do it.
       The default numbers entered here will give you a look on
       the standard mandelbrot set (provided the mandelbrot core
       is active).
Ext:   (since v0.10) Additional words to pass to core. Is greyed
       out if core doesn't use it.
Current Line: While computation goes on this shows you where
       Fractulus is at the moment.
bpp:   (since v0.10) Should be obvious. Icons of bpp the core
       doesn't support are greyed out.


For starters you should just adjust the resolution to your wishes
and start computation by clicking on "start" or pressing return
in the last writable icon. This will produce an asterisk in the
Control Panel's title bar and ungrey the Pause, Abort and Display
icons. Unless there've been any errors, that is. If you entered any
illegal numbers or specified a resolution that demands more memory
than your machine has to offer you'll be told so and should take
action. If all went well all writable icons except for IterPoll
will be greyed out - no more use for them.

Clicking on Display will show you the current fractal. You can
leave this window open, it will be updated (see Defaults), but that
will slow down computation a bit (not much!).

After computation's finished you can save the fractal. You do this
by pressing Menu over either the corresponding Control Panel or the
Sprite Window. You can also use the keyboard shortcuts to do so,
but these will only work when the Sprite window has the input
focus (click in it to have it gain it). Saving works as usual.
The fractal is saved as a standard sprite (28 for 8bpp, S16,90,90
for 16bpp and S32,90,90 for 32bpp) with important info (coordinates
and the like) stored as extension area. You can save to the Filer or
any other application. Fractulus can also handle RAM transfers. If
you've dragged it to a filer window the current fractal will be marked
as saved (the asterisk will be removed from Control Panel and Sprite
Window) and the Filename will be shown in the Sprite Window's title
bar. The other items in the sprite menu (except for "to batch" and
"export") refer to frames.

Export: (since v0.10)
-------
This is a new feature to be used for making movies. If you have two
fractals, one of which you wish to have as the starting picture, the
other as the ending picture and "interpolate" between them, thus making
a movie, here's how to do it:
Open the control panels of both pictures; no actual data has to have
been computed for either of those, it suffices for the control panels
to contain all data required. Select Export from the ending fractal's
Sprite Menu. Enter in the writable icon the number of the starting
fractal's control panel. If your choice is accepted (i.e. the panel
exists and is not equal to the one you're exporting) the "To Movie"
window will appear. From then on everything is exactly as "To Movie"
from the Frames menu (see below).
Resolution, bpp and extension words will be used from the starting
fractal's control panel.
Why don't I just export the data to a frame in the starting fractal's
sprite window? Easy: if you want to use this method (rather than
the alternative Frames.ToMovie) the ending fractal will usually be
very small compared to the starting one. Frames only offer precision
of 1 OS unit, i.e. 1/2 pixel in Fractulus' sprites. This is much too
bad for satisfying results. Besides the frame might lie outside of
the starting fractal's bounding box - which is no problem for Fractulus
but might still be a bit awkward for the user.


Frames:
-------

You can zoom into a fractal by dragging a frame that specifies the
new window's interval. Hold down either Select or Adjust and move
the mouse to draw a frame. If the menu item "New Ratio" is ticked,
the frame will always preserve the ratio specified there, if not
frame shapes will be arbitrary. The ratio entered here will also be
entered as the new Panel's resolution, so you should enter e.g.
640:480 rather than 4:3. If the pointer leaves the window it will
scroll in the appropriate direction; you don't have to have
everything visible that you want to include in your frame.
After finishing the drag the frame becomes selected: it is crossed
out (unselected frames are just rectangles). You can still manipulate
it, though. You can drag one of its corners to change its size or
you can click inside it to move the whole thing. In case of over-
lapping frames the one with its middle closest to your pointer will
be chosen.
Overlapping frames? Yeah, you can have up to 4 frames in each sprite
window simultaneously. Clicking Select in the sprite window will
deselect all frames (and select the one you've clicked in, if any),
adjust will do nothing (or toggle the frame's state you've clicked
in, if any).
Once you've drawn a frame the Frame menu becomes available. This
consists of the items:

Slct All: Select all frames.
Delete:   Delete all selected frames.
To Panel: create (a) new Control Panel(s) with the frame's (the frames')
          coordinates. This will draw the corresponding Control Panel's
          number into each frame (whether you can actually see this depends
          on the current fractal and good luck) and open the Control
          Panel, ready to process the next fractal.
AdjustRatio: This will change the shape of all selected frames to match
          the ratios specified there. Frames created without "New Ratio"
          ticked will now also have ratio on. As above, the minimal
          imaginative value becomes variable.
To Movie: (since v0.10) Only available if exactly one frame is selected.
          This will interpolate between the current fractal and the frame
          selected. Interpolation is non-linear and ensures that
          a) magnification is constant
          b) translation of the frame is always set in relation to its
             current size.

          You have to enter some values here:

          Iterations: Number of iterations to use for final fractal. In
                      between iterations are interpolated linearily.
          Steps:      Number of pictures to do. Since numbering is done with
                      3 digit hexnumbers you shouldn't enter values >= 4096.

          What this will do is add some entries to the batchfile (for batch-
          files see below). Save the batchfile and drag it to the Fractulus
          icon later to compute the movie.
          The upper section of the "To Movie" window consists of a typical
          save box and is used exactly like the one for "To Batch" (see
          below). The first 7 characters of the leaf name will be used for
          the movie's base name, the remaining 3 are a hexadecimal numbering.
          The resolution of the movie will be taken
          - from the frame, if it has ratio on
          - from the parent fractal otherwise.

Now you can zoom into fractals, save them and so on. Basically all you're
gonna need for the time being. But there's more.



Icon Bar Options:
-----------------

Apart from the usual Info and Quit we have:

Defaults:
---------
Here you can enter the values that should appear in each Control Panel
on opening it. Apart from that you can specify the value "Update", which
means the number of times a running fractal has to return control to the
WIMP before the line number and the sprite window are updated. The smaller
the number, the more accurate the display is at all times but the more the
computer will be slowed down. The current 10 is a good compromise, as far
as I'm concerned.
The Defaults window also shows the currently active Core. You can't
change it here, though.
Clicking on OK means read the values, store them as defaults and close
the window, save does the same + saves the values in Fractulus' main
directory. Closing the window any other way preserves the old values.

Choose Core:
------------
Provided you don't have any Control Panels open you can choose one of
the Cores provided here. On startup Fractulus will scan its Core
directory and offer all of the files resident there in the Core Menu.
Cores are basically different algorithms: mandelbrot, e.g, does the
standard z = z^2 + c iteration.
If you want to write your own core please look up details in the CORES
document.

Cores included in this release are:
julia, mandel3, mandel4, mandel5, mandel6, mandelbrot, dragon,
fix32, crazy32

The mandel<i> cores use the formula z^i + c.

fix32 does the same as mandelbrot only as 32 bit fixed point implemen-
tation. Thus precision is pretty lousy.

crazy32 gives some pretty nice overflow errors of the 32 bit fixed
point method.

The Julia core included here makes use of the extension words (unlike
the one from the old release - for obvious reasons). If you want to
zoom into old julia fractals with the new core you should enter the
following as extension words:
-0.562198486328125 and 0.6425286865234375
Note: The extension words are the complex number c in Julia's iteration
      z = z^2 + c.

dragon does the iteration z = c*z*(1-z) with c = complex number obtained
from extension words. Depending on what extension words you use you can
get *very* different results. A nice one to start with would be 1.64,0.96.



Batch:
------
See later.


Fractals you have created and saved can be reloaded into Fractulus by
dragging them to its icon bar icon. If the sprite was created by
Fractulus (i.e. has a valid extension area), was created with the
same core type as the one currently loaded and fits into memory it
will be loaded, otherwise Fractulus will complain. In case of a
difference in cores Fractulus will try to look up the core used to
compute this Fractal and give you its name. If it can't find it
(i.e. no core matching the ID is included in the Core Menu) it will
quote a "?".


Batch Files:
------------

Instead of computing fractals interactively you can choose to redirect
all the data of a fractal from a Control Panel to a Batch File. If
you choose the menu item "to batch" in the Sprite Menu you'll get
a save dialogue box just like the one "save" provides. This is because
all data except the name the fractal should be stored as can be
read from the Control Panel. You have to drag it to a Filer window,
all other destination windows will not be accepted (i.e. the save box
won't be closed). All Panels append their batch data to the same file.
Once you've batched at least one panel the "batch" item in the main
menu will be ungreyed. This offers four more options, Save, Clear, Show
and Delete.

Save should be obvious.
Clear will remove it from memory.
Show shows the current batch file.
Delete deletes the selected lines from the batch file - only available
  if the menu was opened by clicking Menu over the Batch (Text-)Window.

The Batch File is a text file and can be edited. Some editing can even
be done from Fractulus: you can select lines you wish to remove from
the file and delete them by clicking on "Delete" in the Batch Menu.
Selecting can be done by click or drag. The first two lines are pro-
tected; you can't select these.
If you want to edit by hand (you should know what you're doing, though)
The format is:

[optional data]ResX,ResY,IterMax,min(re),max(re),min(im),max(im),ratio(0/1),
corename,filename<lf>

[optinal data] is possible since v0.10. It can be
-bpp 8|16|32, to specify number of bpp. None defaults to 8bpp.
-ext float,float, for the extension numbers.
For an example refer to the file NewBatch.

It can also contain empty lines (linefeed only) and commentary lines
(which start with a "#"). Check out the demonstration batch file for
clearness. After having defined Pics$Dir (the directory you want to
store the resulting sprites in) you can also start it (by dragging it
to the Fractulus icon bar icon - it shows quite a few nice scenes).
NewBatch is a batch file with optional data and can thus only be
used with v0.10.

Fractulus can't enter batch mode when any Control Panels are open.
This is once more because the batch file can change the currently
active core. After Fractulus has entered Batch Mode, a Batch Panel
is opened - unlike in interactive mode this one is opened on the
bottom of the window stack, i.e. behind all others. That is so you
can do some work, e.g. use a texteditor such as myself at the moment
and not be disturbed any time a fractal is finished and out of nowhere
a new panel pops up. You can still choose "Display" to watch the current
fractal, you can still enter the IterPoll variable, show and save the
batch file but that's it. Neither can you open any more Panels.
Fractulus will leave Batch mode

a) on completing the Batch File
b) by having the Batch Panel closed via Abort or the close icon.

Any errors occurring during processing the Batch File will lead
to this Batch being skipped and the next one started up. This is
because a Batch File is a nice way to keep your computer occupied
while you're busy sleeping - which means you're not available to
answer any dialogue boxes. If you want to know if any errors
occured, simply check which files were saved.


Warning boxes:

Whenever you try to close a panel that's been started up but not
saved yet (i.e. it has an asterisk in its title bar) Fractulus will
open an error dialogue box to inform you of possible data loss.
If you get this warning with nothing but safe panels open, it refers
to an unsafed batch file.

Data will only be marked as saved when its destination is a filer
window.


This concludes this guide to Fractulus. I hope it was helpful.


If you like this program and feel the moral obligation to send me
large amounts of money here's where to send it to:


Andreas Dehmel
Am Schorn 18
82327 Tutzing
Germany


During University terms (Nov - Feb, Mar - Jul) you can also reach me
via e-mail:

[e-mail]

Outside of University terms I won't be checking my mailbox too often
(once or twice a month) so you'll have to be patient.


Now enjoy the program...



Andreas Dehmel





"Base not your joy upon the deeds of others, for what is given
 can be taken away. No hope = No fear."

                                            Peter Steele