RBBS in a Box Volume 1 #2/RBBS_vol1_no2.iso/add2/fractint.zip/FRACTINT.DOC

Text File | 1989-04-09 | 53KB | 922 lines

               *********   FRACTINT (Version 7.0)  **********

        Original Program (Versions 1.0 through 6.1) by Bert Tyler
        Driving force behind version 7.0: Timothy Wegner

      +++++ Quick Documentation Format -- Features new to 7,0 +++++

      - Restore-From-Disk (from prior Save-To-Disk using version 7.0 or later)
      - New Fractal types (Newton/Lambda/Mandelfp/Juliafp/Plasma/Lambdasine)
      - Many new Color-Cycling options (for VGA Adapters only)
      - New Periodicity Logic (courtesy of Mark Peterson)
      - Initial Fractal displays recognize (and use) symmetry
      - Solid-Guessing option (which is now the default)
      - Context-Sensitive Help (press 'h' or '?' at any time)
      - Customizable Video Mode Configuration file (FRACTINT.CFG)
      - "Batch Mode" option (run from a .BAT file, no keyboard activity rqd)
      - Improved Super-VGA Support (with direct video read/writes)
      - New (non-standard) 360 x 480 x 256 color mode on a STANDARD IBM VGA!

                        +++ Features new to 6.1 +++

      - 32-bit Integer math is now emulated for non-386 processors
      - Program name changed (from FRACT386) to reflect the above
      - (and, of course, there are just a few more video modes)

                        +++ Features new to 5.x +++

      - Save-to-disk support  (using the 's' key)
      - New!  Improved!  (and Incompatible!)  Optional Arguments Format
      - "Correct" Initial Image Aspect Ratio
      - Still more video modes

                        +++ Features new to 4.x +++

      - Mouse Support (by Mike Kaufman)  (See the Mouse Notes, below)
      - Dynamic Iteration Limits         ('<' and '>' keys)
      - Color-Cycling                    ('+' and '-' keys)
      - Dual-Pass Mode                   ('1' and '2' keys)
      - More Video Modes, including "tweaked" modes for IBM VGA
              and register-compatible adapters

                       +++ Features new to 3.x +++

      - Julia Sets

                       +++ Features new to 2.x +++

      - Zoom and Pan

                       +++ Features new to 1.x +++

      - The original, blindingly fast, 386-specific 32-bit integer algorithm


      +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


This program generates Mandelbrot and Julia set fractal images using 32-bit
integer arithmetic rather than the "traditional" floating point.   When run
on a 386-based PC, it will use the 32-bit math specific to that processor -
otherwise, it will emulate it using the generic 16-bit math available on
the entire INTEL family (at about 15% of the speed of the 386-specific
math).  The program also generates other types of fractal images (described
below), although it generates those other fractals using "traditional"
floating point math.

The program will work with CGA, EGA, MCGA, VGA, "tweaked" VGA, and
many popular super-rez adapters, and can switch display modes on-the-fly for
those adapters capable of multiple emulation. For instance, I can run this
program in any of the IBM CGA/EGA/MCGA/VGA modes on my PS/2 model 80.
The program does not perform any floating point arithmetic during its
Mandelbrot/Julia set image generation routines, and does not require an FPU.

To start the program, simply type its name (FRACTINT) without any parameters.
When the program fires up, it displays an initial credits screen with a
(partial) list of those whose contributions made FRACTINT possible.  The
program then waits for you to hit one of the available command keys to set
up the program or select an initial video mode and start up the first
image.   You can also (at this screen or at any time) press the HELP key
('h' or '?') to enter HELP mode, with screens describing the commands and
video modes currently available and the keys you can hit to activate them.
As soon as you select a video mode, the program begins drawing an initial
display (of the full Mandelbrot set, if you haven't selected another fractal
image).   From this point on, and AT ANY TIME, you can hit any of
the following keys to select a function:

 Key          Function
 ===========  ===============================================================

 h or ?         Enter HELP mode (the Escape key brings you back)
 PageUp         Display and Shrink the Zoom Box ("Zoom In")
 PageDown       Display and Expand the Zoom Box ("Zoom Out")
 Cursor Keys    Display and Move the Zoom Box Left, Right, Up, or Down ("Pan")
 Ctrl-Cursor-Keys   Pan like the normal Cursor-Keys, but (five times) faster
                (NOTE:  Fast-Panning works only with an Enhanced Keyboard BIOS)
 Enter or End   Redraw the area inside the Zoom Box as a full-screen image
                (If there is no Zoom Box, just re-draw the current screen)
 F1,F2,F3,F4... Select a new Video Mode and THEN perform a Screen Redraw
                Currently supported video modes include:
                F1 = 320x200 16-color EGA/VGA   F2 = 640x350 16-color EGA/VGA
                F3 = 320x200 256-color MCGA/VGA F4 = 640x480 16-color VGA
                F5 = 320x200 4-color CGA        F6 = 640x200 B&W CGA
                F7 = 640x350 B&W EGA/VGA        F8 = 640x480 B&W VGA
                F9 = 640x200 16-color EGA/VGA   F10= 360x480 256 color VGA (!)
                ..etc...etc...etc
                (For a complete list, scan through the Help screens)
 Home           Redraw the Previous Screen (the program tracks 50 screens)
                (this gives you the ability to "back out" screen-by-screen)
 Tab            Display the Current Fractal Type, Parameters, Screen or
                Zoom-Box coordinates, and other pertinent image information
                (this gives you the ability to track where you are and
                restart the program at your current position later on)
 Spacebar       Toggles between Mandelbrot images and their corresponding
                Julia set images (read the Julia set notes below before
                trying this option if you want to see anything interesting)
 < or >         Lower or Raise the maximum iteration count (hit the Tab key
                to display the current value).  The default value is 150, the
                range is 10 - 1000, and the default adjustment value is 50).
                ((Note:  the unshifted equivalents (comma, period) also work))
 2 or 1 or g    Select dual-pass, single-pass, or solid-guessing (the default)
                mode.  Dual-pass mode generates a "coarse" screen first using
                (2x2) pixel boxes, and then generates the rest of the dots
                with a second pass. (same net speed and final display, but
                with a quick-preview).  Solid-guessing performs the same
                first "coarse-screen" pass, and then performs the second pass
                only for blocks that aren't "surrounded" by a single color.
                Solid guessing can guess wrong - but it sure guesses (right
                or wrong) quickly!
 c or C         (for VGA adapters only) Switch to the Color-Cycling command
                mode described below.
 + or -         (For VGA adapters only) Begin rotating the Video DAC and
                switch to the Color-cycling command mode, described below.
                If you have a VGA adapter, use this for NEAT fractal images!
 s or S         Save the screen contents to disk (default = FRACT001.FRA)
                To display its progress, the program colors the left-most
                and right-most dots as it saves the screen, top to bottom.
                The saved files are restorable with either the 'r' key or a
                command-line option.  They are also displayable by most GIF
                decoders, but they are NOT GIF FILES (you can force a save
                in true GIF format by specifying a '.GIF' extension with the
                'savename=' command-line option, but then you can't restore
                it with the 'r' command afterwards.  A full explanation of
                your options is in the 'FRACTINT and .GIF files' section).
 r or R         Restore an image previously saved with an 's' command
                (This image must have been saved using version 7.0 or later)
 b or B         add a line to (and create, if necessary) "frabatch.bat"
                describing the current image.  The entries in "frabatch.bat"
                look just like FRACTINT command lines.  An easy way to set up
                batch files of fractal image commands for later (overnight?)
                runs at Super-resolution video modes or iteration limits.
 t or T         Select a fractal type (the program lists the available types,
                then lets you select one and prompts you for any parameters
                it may require)
 o or O         (the letter, not the number), if pressed while a fractal
                image is being generated, toggles the display of intermediate
                results on and off (the "o" stands for "show orbits")
 Insert         Restart the Program all over again at the Credits Screen
 Esc or Delete  Stop the Program and Return to MSDOS

=============================================================================

                Color-Cycling commands (VGA adapters only)

If you have a VGA adapter, hitting the 'c', 'C', '+' or '-' keys at the main
command level will enter 'color-cycling' (animation) mode (if your adapter is
not VGA compatible - that is, if it does not have a 256-color video DAC - the
program will simply beep in despair and leave you at the main command level).
It's pretty easy to tell when you are in Color-Cycling mode, because either
the overscan (border) area has switched from black to white, or the colors
are constantly cycling on the screen.  Also, pressing the HELP screen in
Color-Cycling mode gives you the Color-Cycling HELP screen.  The command
keys appropriate to color-cycling mode are:

 Key          Function
 ===========  ===============================================================

 h or ?       Enter HELP mode (the Escape key brings you back)
 + or -       Switch the rotating direction out or in (left or right?)
 Right/Left   (Cursor Keys) perform the same function as the +/- keys
 Up/Down      (Cursor Keys) speed up / slow down the color cycling process
              Note that speeding it up too much will cause (non-harmful)
              flickering at the top of the screen as you over-run the
              vertical retrace / blanking interval.
 F1 thru F10  Switches from simple rotation to color selection using randomly-
              generated color bands of short (F1) to long (F10) duration.
 1 thru 9     Causes the screen to be updated every 'n' color cycles (the
              default is 1).  Handy for slower computers.
 ENTER        Randomly selects a function key (F1 thru F10) and then updates
              ALL the screen colors prior to displaying them for instant,
              random colors.  Hit this over and over again (I do).
 Spacebar     Pauses and temporarily switches from the normal black background
              (overscan area) to a white one (so that you can tell the
              difference between a 'normal' command state and a paused Color-
              cycling one).  Restarts automatically with any command key
              (including another Spacebar).
 R or G or B  Forces a pause and raises the Red, Green, or Blue component of
              the fractal image by a small amount.
 r or g or b  Forces a pause and lowers the Red, Green, or Blue component of
              the fractal image by a small amount.
 Any Other    terminates the color-cycling process (you can always return
              to it with another c or +/- key) and returns to the main
              command mode.


==============================================================================
                          Mouse Support

If you have a mouse, FRACTINT now supports it, thanks to the contributions
of Michael Kaufman.  The mouse encoding is as follows:

=============================================================================

Left Button:   Brings up and sizes the Zoom Box.   While holding down the
               left button, push the mouse forward to shrink the Zoom Box,
               and pull it back to expand it.   Then let go of the button
               and move the mouse around to "pan" the Zoom Box (with no
               buttons held down, you are in "fast-pan" mode).

Right Button:  When the right button is held down, the "panning" operation
               switches from "fast-pan" to "slow-pan" mode, giving you
               better control over the location of the Zoom Box.

Both Buttons:  (or the middle button, if you have three of them) Redraws
               the area inside the Zoom Box over your full screen.

Zoom and Pan using the mouse typically consists of pushing in the left
button, sizing the zoom box, letting go of the button, fast-panning to
the general area, pushing in the right button and slow-panning to the
exact area you want, and then (still holding down the right button) tapping
the left button to perform the Zoom.

=============================================================================

                                  HINTS

Remember, you do NOT have to wait for the program to finish generating the
full screen display (a process that can take from 30 seconds for a Mandelbrot
Set image in "Low-Rez" EGA or MCGA mode on a 386-based PC to several hours
(days?) for a Lambda-Sine image in full VGA mode on a "vintage" 8088 with
no FPU) before hitting one of the above keys.   If you hit a keyboard
key while the program is generating a screen image, it will simply stop and
process the key (it will NOT finish the display, though). If, say, you see
an interesting spot you want to zoom in on, don't wait --  do it!   If the
program finishes a display before you hit any keys, it will simply beep and
wait for you to hit one.

For Mandelbrot fractals, the most interesting areas are the border areas
where the colors are changing rapidly.   Zoom in on them for the best
results.   The areas closer to the outside of the fractal "egg" tend to
involve fewer iterations and display more quickly than those closer to the
inside.  The solid blue interior is the slowest region of all to display --
in fact, it's where the program has hit its iteration maximum (the default
is 150) and given up.

>>BIG IMPORTANT HINT<<:  It's a LOT quicker to save an initial screen once to
a file (say, STARTUP.FRA), and then fire up subsequent FRACTINT sessions
with a command like 'fractint startup'.   This can be handled automatically
with the 'batch=yes' command-line option (the example below creates a startup
file for register-compatible VGA adapters using 360x480x256 color mode):
           fractint batch=yes video=f10 type=mandel savename=startup
One hasn't been added to the distribution .ARC file only because of the
space it would take (the files are getting big enough as it is!) and because
we don't know what your favorite (or possible) video modes are.

The time it takes to generate a fractal image is directly proportional to the
resolution of the selected video mode (more dots = more calculations).   You
can select a low-resolution mode (I use F3 for MCGA) on the startup screens,
and at some later point hit a function key instead of the ENTER key to switch
to a higher resolution mode (I use F10 for 360x480x256 mode) when things get
interesting.  That gets you into the interesting stuff in detailed resolution
quickly -- after awhile, you've seen that first Mandelbrot image too often
to get excited about it.  Actually, with its 256 colors (the program "only"
uses the first 150 by default), MCGA mode can give you some pretty spectacular
effects on its own.

On a slow machine, I have been known to fire up FRACTINT with a low iteration
limit ('fractint maxiter=50') to get the initial screens up quickly, and raise
the iteration limit later with the '>' key.   True confession time:   I've
even used 'fractint maxiter=10' on an old, 4.77 MHZ "classic" IBM PC (patience
was never one of my strong suits).

Solid-Guessing is now the default image-generation mode.  Solid-Guessing
works by generating a coarse first-pass image using 2x2 pixel boxes, and then
performs a second "clean-up" pass only for blocks that aren't "surrounded"
by a single color.   Solid guessing is fast, but it can guess wrong.  If
you are a perfectionist, or are using "batch mode" to save a particular
image for posterity, you probably want to disable solid-guessing by switching
to either single-pass or dual-pass mode using either the '1' or '2' commands
or the 'passes=' command-line option.

=============================================================================

             ******   Optional Command Line Arguments  ******

   FRACTINT accepts optional arguments that allow you to better control
such things a video modes, iteration limits, and startup display areas.
NOTE that the current argument list is (a lot better, much more expandable,
but) totally incompatible with the argument lists of FRACTINT versions prior
to version 5.1.   The full FRACTINT command line is:

                FRACTINT [filename] [argument] [argument] ...

where the individual arguments are separated by one or more spaces (an
individual argument can NOT include spaces), can be in any order or
(upper/lower) case, and can be any of the following:

Argument                    Description

filename           Causes FRACTINT to read the named file, which must have
                   been saved via an earlier (version 7.0 or later) FRACTINT
                   session, and use that as its starting point, bypassing the
                   initial information screens (the filetype is optional -
                   'myfile' and 'myfile.fra' refer to the same file).
passes=x           Selects (1) Single-Pass mode, (2) Dual-Pass mode, or
                   (g) solid-guessing mode (Examples: passes=1, passes=g).
inside=nnn         Set the color of the Fractal interior (Example: inside=0
                   sets the inside of the Mandelbrot set to traditional black)
maxiter=nnn        Set the starting iteration maximum (Example: maxiter=500).
                   The program accepts maxiter values from 10 to 1000.
iterincr=nnn       Set the iteration increment (the value maxiter is changed
                   by when you hit the '<' or '>' keys)
video=xxxxx        Set the initial video mode (and bypass the informational
                   screens).  Handy for "batch" runs. (Example: video=F4)
savename=xxxxxx    Set the filename to use when you press the 's' key.
                   The default filename is FRACT001.  Typing the '.FRA' is
                   optional (Example: savename=myfile)
type=fractaltype   Selects the type of fractal image to display.  The default
                   is type 'mandel' for the Mandelbrot set.  The current list
                   of available fractal types is described later.  (Example:
                   type=julia generates Julia sets).
params=param1/param2   Set optional (required, for some fractal types) values
                   used in generating fractals.  These two numbers typically
                   represent the real and imaginary portions of some startup
                   value.  These parameters are described in detail later on
                   (Julia Set example:  type=julia params=-0.48/0.626)
corners=xmin/xmax/ymin/ymax   Begin with these screen corner Coordinates
                   rather than the default values of -2.0/2.0/-1.5/1.5
                   (Example: corners=-0.739/-0.736/0.288/0.291).
cyclelimit=nnn     Limits the color-cycling speed used by the Color-cycling
                   options.  Technically, the number of DAC registers
                   updated during a single vertical refresh cycle.  Legal
                   values are 1 - 256, default is 55 (Example: cyclelimit=256)
batch=yes          Run in "batch mode" - acts as if you had hit the 's' key
                   to save the image after drawing the first fractal, and
                   that you hit the <ESC> key to exit afterwards.  The
                   'video=' option is required, and the 'savename=',
                   'corners=' and other options are REAL handy.
batch=config       Runs a special "batch mode" run that creates a default
                   FRACTINT.CFG file from the full internal video table
                   (FRACTINT.CFG is described below).

The 'type=', 'param=' and 'corner=' arguments let you recreate images
that you or others have generated in previous sessions of FRACTINT or other
fractal generation programs.   These values can be displayed at any time
during FRACTINT by hitting the TAB key.

A warning about the 'video=' option:   EVERY version of FRACTINT (including
this one) has been introduced with a bigger, better, and generally shuffled
around Video Table.   BE CAUTIOUS about using this argument and then
downloading future versions of FRACTINT, particularly if you are using
the "Super-VGA" modes near the end of the video table.

=============================================================================

       ************** Mandelbrot and Julia Set Fractals  **********
                                     and
          ***** Toggling between Mandelbrot and Julia Sets *****

Note on algebraic conventions: in the text that follows, "a*b" means "a
times b", and "a**b" means "a to the power b".

   FRACTINT can be toggled between Mandelbrot images and their corresponding
Julia sets.   What is a Julia set?   I don't really know either, but I can
describe how the program generates them.  Let's start with a diversionary
tactic and describe how the program generates the Mandelbrot set.   The
Mandelbrot set is generated by assuming that each pixel on the screen
represents a point on the complex-number "C plane", (X + i*Y), and calculating
the following function until the "size" of Z(n) is greater than 2 :

Start with a complex-number constant            C = xcoord + i * ycoord
use as the initial value of Z                   Z(0) = 0
and iterate using this function                 Z(n+1) = Z(n)**2 + C

   Julia sets (or, more specifically, the Julia set of the polynomial
Z**2+C, which is the Julia set that we are discussing at the moment -
FRACTINT now generates other Julia set fractals as well, which are described
later) use a slightly different tactic, picking out a specific point
on the "C plane" and assuming that each pixel on the screen represents
an initial point on the "Z plane".   Once everything has been started up,
however, the calculations are the same:

Start with a USER-SPECIFIED value of C          C = Creal + i * Cimaginary
use as the initial value of Z                   Z(0) = xcoord + i * ycoord
and iterate using this function                 Z(n+1) = Z(n)**2 + C


   In either case, the pixel's color is arbitrarily determined by the
number of iterations it took the program to get Z "large" enough to
bail out of the loop.


   Generating Julia sets are different from generating Mandelbrot sets in
several important ways:

   (1) There is only one Mandelbrot set but, given that there are an infinite
number of values available for the complex-number C, there are an infinite
number of Julia sets.

   (2) Although there are an infinite number of Julia sets, a lot of them
are pretty boring.   Only certain ranges of C result in interesting
Julia set displays - values too "small" generate a simple circular display,
and values that are too "big" generate something that looks like scattered
dust.

   (3) It turns out, however, that the coordinates of the most interesting
portions of the Mandelbrot image, where the colors are changing rapidly,
are the VERY SAME values that generate the most interesting Julia sets.
(There is a very sound mathematical reason for this.   I haven't the
vaguest idea what it is, though.)


   What FRACTINT does is begin with the full Mandelbrot set, give you the
capability to zoom and pan around generating interesting Mandelbrot images,
and then AT ANY POINT hit the spacebar toggle to "flip" to a full Julia set
with startup constant C set to the coordinates at the center of the Mandelbrot
image that you last generated.   From that point, you are zooming and
panning around in a Julia set "Z plane" (you can always hit the spacebar
toggle again to get your Mandelbrot set back).   You can think of it this way:
all those fantastic Mandelbrot images you have been generating are just
a way to select an initial value for Julia sets you can play with!

NOTE:  Beginning with version 7.0, "Warped" Mandelbrot sets ( sets with
a starting value of Z(0) other than 0) can be generated by FRACTINT by
firing it up with a 'params=' option.  The two optional parameters are
taken as the real and imaginary portion of Z(0).  When the Mandelbrot set
has been warped in this fashion, the relationship between it and Julia sets
described above no longer applies.

           *******  "Go-Fast" additions to the logic *******

The "Mandelbrot Lake" in the center of the Mandelbrot images is the
traditional bane of all fractal programs.  The center of the lake always
sucks up the most computer time because it always reaches the iteration
limit - and yet the most interesting images are invariably right at the edge
the lake.  Thanks to Mark Peterson for pointing out (well, he more like beat
us over the head until we paid attention to him) that the iterative values
in the middle of Mandelbrot Lake tend to decay to periodic loops (IE,
Z(n+m) == Z(n), a fact that is pointed out on pages 58-61 of "The Beauty of
Fractals"), and that an intelligent program (like the one he wrote) would
check for this periodicity once in a while, recognize that iterations caught
in an iterative loop are going to max out on iterations, and bail out early.
For speed purposes, the current version of the program turns this checking
algorithm on only if the last pixel generated was in the lake (the checking
itself takes a small amount of time, and the pixels on the very edge of the
lake tend to decay to periodic loops very slowly, so this compromise turned
out to be the fastest generic answer).  Try a full Mandelbrot image with
a 1000-iteration maximum with any other program, and then try it on this
one for a pretty dramatic proof of the value of periodicity checking (hint:
on a 16MHZ 386 in MCGA mode, FRACTINT takes ten seconds)!

You can get a visual display of the periodicity effects in the Mandelbrot
Lake if you press the 'o' (letter o, not zero) while a Mandelbrot image is
being generated.  The 'o' ("show orbits") key toggles on and off the display
of the intermediate iterations during the image generation process.  If
you use this toggle, it's best to disable solid-guessing first using the '1'
or '2' command (in its second pass, solid-guessing guesses away many of the
pixel calculations precisely where the 'show orbits' option is the most
interesting).

An additional trick commonly used in fractal displays is solid-guessing -
generating a grid of colors, and then assuming that the interior points are
a solid block of color if all the surrounding points are the same color.
This trick works very well, but can mis-guess pixels.  Solid-guessing is
now the default mode in FRACTINT, but is easily disabled with the
'passes=1' or 'passes=2' command-line option, or with the '1' or '2' commands.
Visually, solid-guessing looks just like Dual-Pass mode ('passes=2' or the
'2' command) - except that the second pass seems faster, somehow...

=============================================================================

  *******  Fractal Set types other than Mandelbrot and Julia Sets  ********

Beginning with version 7.0, FRACTINT supports fractal images other than the
"classic" Mandelbrot and Julia sets.  Note that these extra image types are
typically calculated using generic "C" code (in CALCFRAC.C) and use
"traditional" floating-point math rather than the 32-bit integer math which
was FRACTINT's original claim to fame.  As a result, although they take full
advantage of FRACTINT's other features, they are no faster than routines
found in other, similar packages.  A quick way to obtain the current list of
fractal types is by  using the 'T' command.  Current fractal types supported
by FRACTINT include:

      *** Newton Domains-of-Attraction (type=newtbasin) ***

The Newton formula is well known to struggling students of calculus as an
algorithm for calculating the roots of polynomials. The polynomial 'z**4 - 1'
has 4 roots in the complex plane: 1, -1, i, and -i, where i is the square
root of -1.  The Newton formula for that polynomial is the rational function
(4*(z**3) + 1)/(3*(z**4)).  If you pick a value of z NEAR one of the roots
and plug it in to Newton's formula, the result is CLOSER. Do this several
times, and you have an accurate root. That is, define a sequence z[0], z[1],
z[2] ... by z[0] = guess, z[k+1] = (4*(z[k]**3)+1)/(3*(z[k]**4)).
But what happens if the first guess is BETWEEN the roots?  Which root does
the formula converge to? Glad you asked! The answer is -- CHAOS!!!

To see the answer, try type=newtbasin. Pixels are colored according to the
"attracting" root. The graph you see, in high-powered esoteric fractal
language, is a graph of "the basins of attraction for the Newton formula
of the polynomial z**4-1"

For the above example, use "params=4". Other legal values are 3 through 10.
The params value of "n" calculates the Newton formula for the equation
'x**n - 1'.  An FPU is EXTREMELY handy.

                *** Newton Formula (type=newton) ***

The formula is identical to type=newtbasin, but the pixels are colored
according to the iteration when the value is close to a root, rather than
according to WHICH root. If you have a 256 color mode, use it. (Newtbasin
uses fewer colors). Also, if your "corners" choice is symmetrical, FRACTINT
exploits the symmetry.  There is symmetry also in "type=newtbasin", but
the current version of the software isn't smart enough to exploit it.

The useful "params=" values are the same as Newtbasin. Try 'params=4'.
Other values are 3 thru 10.  Multiples of 4 have twice the symmetry
and are faster.  As with 'type=newtbasin', an FPU is EXTREMELY handy.

               *** "Lambda" Sets (type=lambda) ***

This type calculates the Julia set of the formula lambda*z*(1-z).  That is,
the value z[0] is initialized with the value corresponding to each pixel
position, and the formula iterated.  The pixel is colored according to the
iteration when the sum of the squares of the real and imaginary parts
exceeds 4.  Look in this space later for a profound discussion of the
physical significance of this formula, if we ever dig it out of our books!

Two values should be given in the "params=" option.  These values will become
the real and imaginary parts of  lambda. Try 'params=0/1' to see the classical
"dragon".   An FPU is EXTREMELY handy.

               *** Plasma Clouds (type=plasma) ***

"Plasma Clouds" are generated by a recursive algorithm that randomly picks
colors of the corner of a rectangle, and then continues recursively
quartering previous rectangles.  Random colors are averaged with those of
the outer rectangles in such a way that in small neighborhoods do not show
much change, resulting in the effect of clouds. MUST be viewed with
FRACTINT's palette animation (hit "+" or "-" when done).  A side effect
of watching the screen being painted by the recursive algorithm is that
the watcher becoming hypnotized, if not immediately, then when the plasma
clouds begin writhing with palette animation. Haven't yet added subliminal
messages to exploit this --  next release! Algorithm is based on the pascal
program distributed by Bret Mulvey as "plasma.arc" (we have ported it to C
and integrated it with FRACTINT's graphics and animation facilities).

Plasma Clouds accept a single parameter, which determines how abruptly
the colors change.  Selecting "params=.5" results in bland clouds, while
"params=50" results in very grainy ones.  The default parameter value is 2.
Sorry, but you must have a VGA or Super-VGA adapter and you must select a
256-color mode.  Plasma clouds in 16 colors just don't make it.

FRACTINT's implementation of Plasma Clouds does not use floating-point math,
and so does not require (or use) an FPU.  Also, Zoom and Pan is effectively
ignored for Plasma Clouds, as each Plasma Cloud screen is generated randomly.

          *** "Lambda*Sine" Sets (type=lambdasine) ***

This type calculates the Julia set of the formula lambda*sine(z), where
lambda and z are both complex. The algorithm is given in "The Science of
Fractal Images", by Barnsley, Devaney, Mandelbrot, Peitgen, Saupe, and
Voss, published by Springer-Verlag in 1988, p. 158.

Two values should be given in the "params=" option.  These values will
become the real and imaginary parts of lambda. Make the real part = 1,
and try values for the imaginary part ranging from .1 to .4. In this range
the Julia set "explodes".  An FPU is a NECESSITY - each iteration calculates
a hyperbolic sine, hyperbolic cosine, a sine, and a cosine!  However, if you
DON'T have an FPU, and you are going on a LONG vacation ....  well, that's
what batch mode is for!

   *** "Traditional" Floating-Point Mandelbrot and Julia Functions ***
                  *** (type=mandelfp and type=juliafp) ***

These fractal types are identical to their 'type=mandel' and 'type=julia'
counterparts.  If you are using an 8088/8086 and have an FPU, these routines
may actually be faster than their integer counterparts (the integer MULtiply
instruction on the 8088 takes a LOOOOONG time).  Otherwise, these fractal
types are included more for historical purposes than anything else.  That
and the source code (in CALCFRAC.C) is a TAD easier to follow than the
assembler version (in CALCMAND.ASM).

If you do not have an FPU, steer clear of these routines unless you feel
the need to reminisce about the good old days when men were men and fractals
took forever to generate.

                 *** Roll your own (type=test) ***

This is a stub that we (and you!) use for trying out new fractal types.
Type 'test' fractals use FRACTINT's structure and features (like dual-pass
mode, zoom-and-pan, and support for a zillion video modes), but use whatever
code happens to be in routine 'testpt()' (located in the small source file
'testpt.c') to determine the color of a particular pixel.  If you have a
favorite fractal type that you believe would fit nicely into FRACTINT, just
rewrite the C function in testpt.c (which is currently a simple Mandelbrot
routine) with some algorithm that computes a color based on a point in the
complex plane. After you get it working, send your 'testpt()' code to one of
the authors and we might just add it to the next "official" release of
FRACTINT, with full credit to you. Our criteria is 1) an interesting picture,
and 2) formulas significantly different from types already supported.
(Bribery may also work - THIS author is completely honest, but I don't trust
those other guys.)  Be sure to include an explanation of the algorithm, and
the "params=" options supported, formatted in a way similar to this
documentation.

=============================================================================

                         BATCH FILE CHALLENGE!!

The authors hearby challenge FRACTINT USERS everywhere to submit FRACTINT
command lines that calculate their favorite fractals images. A sample command
line entry would be something like (and you can do better than THIS):

   fractint type=julia params=0.3/0.6
                        or
   fractint type=newton params=4 corners=-2/2/-2/2

We will add a batch file with each line credited to the proposer to future
releases of FRACTINT. Send to one of the authors via CompuServe or BIX.


=============================================================================

 *** Support for "Tweaked" VGA modes and Third-Party Hi-Rez Video Adapters ***

   FRACTINT uses a Video Adapter Table in the "C" program to reference
everything it needs to know about any particular adapter/mode combination.
This table can contain information for up to 76 adapter/mode combinations,
and is automatically tied to seventy-six Function Keys (F1-F10, their Control/
Shift/Alt variants, and many Alt-x keypad combos) when the program is running.
The table entries, and the function keys they are tied to, are displayed
as part of the Video-Mode Help Screen(s).   With version 7.0, this table is
also customizable using an external configuration file (FRACTINT.CFG),
described in a few more paragraphs.   This table makes adding support for
various third-party video cards and their high-rez modes much easier, at
least for the ones that pretend to be a standard adapter with more dots
and/or colors.

   The table as currently distributed begins with nine standard and several
non-standard ("tweaked") IBM video modes that have been exercised successfully
with a PS/2 model 80.   These entries, coupled with the descriptive comments
in the table definition and the knowledge you have about throwing your adapter
into its unique modes, should be all you need to see to be able to add your
own entries.

   SPECIAL NOTE ON THE NON-STANDARD 360 x 480 x 256 VGA MODE:   The IBM VGA
adapter is a highly programmable device, and can be set up to display many
video-mode combinations beyond those "officially" supported by the IBM BIOS.
This video mode is perfectly legal, but it temporarily reprograms the
(IBM or any truly Register-Compatible) VGA adapter in a non-standard
manner that the BIOS does not recognize.  Because of this, the program
cannot send any text to the screen while it is in this mode (the BIOS
would garbage it).  An internal flag inhibits all text output while the
screen is in this video mode.  Note, however that the HELP and TAB keys
still work, because they temporarily switch the screen to an alternate
video mode.

   SPECIAL NOTE ON "TWEAKED" VGA MODES:   The IBM VGA adapter is a highly
programmable device, and can be set up to display many video-mode combinations
beyond those "officially" supported by the IBM BIOS.   FRACTINT contains
code that sets up the IBM (or any truly register-compatible) VGA adapter
for several extended modes - such as 704x528, 736x552, 768x576, and 800x600.
The program accomplishes this by programming the VGA controller to use the
fastest dot-clock on the IBM adapter (28.322Mhz), throwing more pixels on
the screen, and reducing the refresh-rate to make up for it.   Note that
these modes push many monitors beyond their rated specs, both in terms of
higher pixel resolution and lower refresh-rate.   Signs that your monitor
is having problems with a particular "tweak" include: vertical or horizontal
overscan (displaying dots beyond the edges of your visible CRT area),
annoying "flicker" (caused by a too-slow refresh-rate), and "rolling" or
total garbage on the screen (your monitor simply can't keep up, or is
attempting to "force" the image into a pre-set mode that doesn't fit).
I have successfully tested the modes up to 768x576 on an IBM PS/2 model 80
connected to IBM 8513, IBM 8514, NEC Multisync II, and Zenith 1490 monitors
(all of which exhibit some overscan and flicker at the highest rates), and
have tested 800x600 mode on the NEC Multisync II (although I had to fiddle
with the vertical size knob some to get it to display correctly).

   After the standard and "tweaked" IBM-style video modes, the video adapter
table contains an ever-increasing number of entries for third-party
(generally "Super-EGA " and "Super-VGA") adapters.   Almost all of these
entries have been added because someone like you sent us spec sheets on his or
her adapter, or modified FRACTINT to support it and then informed us about it.


=============================================================================

         The Video Modes Configuration file  (FRACTINT.CFG)

   If you have a favorite adapter/video mode that you would like added to
FRACTINT (or if you want to effectively remove table entries that do not
apply to you), you can handle that task easily by creating and editing an
external configuration file (FRACTINT.CFG).  The easiest way to get started
is by having FRACTINT create a default configuration file for you.  You do
this by typing 'fractint batch=config'.  FRACTINT will create a configuration
file with an entry for every one of the internal video table entries, and
from that on will use FRACTINT.CFG instead of its internal table as long as
it can locate it somewhere along the DOS PATH.

Any line in the configuration file that begins with a tab or a space (or is
empty) is treated as a comment.  The rest of the lines must consist of ten
fields separated by commas.  The ten fields are defined as:

  The name of the adapter/video mode (25 chars max, no leading blanks)
  The adapter is set up for that mode via INT 10H, with AX = this
  ""     and  BX = this    |  Hey, all these registers wasn't my
  ""     and  CX = this    |  idea:  blame the adapter manufacturers.
  ""     and  DX = this    |  <<Also, note that AX/BX/CX/DX use HEX Notation>>
  An encoded value describing how to write to your video memory in that mode
         Currently available codes are (use the BIOS as a last resort)
              1) use the BIOS (INT 10H, AH=12/13, AL=color) ((SLOW))
              2) pretend it's a (perhaps super-res) EGA/VGA
              3) pretend it's an MCGA
              4) SuperVGA 256-Color mode using the Tseng Labs Chipset
              5) SuperVGA 256-Color mode using the Paradise Chipset
              6) SuperVGA 256-Color mode using the Video-7 Chipset
              7) Non-Standard IBM VGA 360 x 480 x 256-Color mode
              8) Reserved for future use (Super-VGA)
              9) Reserved for Future use (TARGA)
  The number of pixels across the screen (X - 200 to 2048)
  The number of pixels down   the screen (Y - 200 to 2048)
  The number of available colors (2, 4, 16, or 256)
  A Comment describing this mode (25 chars max, leading blanks are OK)

NOTE that the AX, BX, CX, and DX fields are generated (and read back) using
Hexadecimal notation (fifteen ==> 'f', sixteen ==> '10'), because that's the
way most of your video adapter documentation describes it.  The other fields
use standard decimal notation.

If you look closely at the default entries, you will notice that the IBM
VGA entries labeled "tweaked" and "non standard" have entries in the table
with AX = BX = CX = 0, and DX = some other number.  Those are special flags
that we used to tell the program to custom-program the VGA adapter, and are
NOT undocumented BIOS calls.  Maybe they should be, but they aren't.

If you have a fancy adapter and a new video mode that works on it, and it
is not on our current list, PLEASE GET THAT INFORMATION TO US!  We will add
the video mode to the list on our next release, and give you credit for it.
Which brings up another point:   If you can confirm that a particular video
adapter/mode works (or that it doesn't), and the program says it is UNTESTED,
please get that information to us also.   Thanks.

SPECIAL NOTE FOR VIDEO-7 ADAPTERS:  To implement the new 'help' and TAB
screens, FRACTINT takes advantage of a little-used option available on IBM
EGA and VGA adapters - switching video modes without clearing video memory
(accomplished by setting bit 7 of AL high when performing the mode switch).
To implement interactive HELP in anything beyond CGA mode, FRACTINT switches
to 640x200 CGA mode without clearing video memory, saves the first 16K of
video memory, clears the first 16K of video memory, displays the help screens,
and, when help-mode is finished, restores that 16K of video memory and
switches back to the "old" mode without clearing the memory again.  This
works great on all IBM adapters and other Super-VGA adapters - and on Video-7
adapters as long as they weren't in one of their proprietary "Super-VGA"
modes.  If your Video-7 adapter was in one of its Super-VGA modes (like
640x480x256), however, the adapter will not recognize the last mode switch,
leaving you (and your computer) in video limbo.  This is, in the authors'
minds at least, a bug in the Video-7 BIOS (Video-7 probably disagrees).
In either case, you can continue to use the Super-VGA modes of your Video-7
adapter - just don't hit the 'h' or TAB key when you do (think of yourself
as HELPless).

=============================================================================

                  ***** Limitations and Uglies *****

This program uses 32-bit integer math to generate Mandelbrot and Julia Set
fractals quickly (I do not have an FPU, and "normal" fractal packages take
hours to draw on my machine).  The advantage of this option is speed:  quite
simply, this is by far the fastest Mandelbrot/Julia Set fractal package that
I have ever seen on a 386-class machine (on 286-class PCs and below, the
program "only" runs at FPU-class speeds).   The disadvantage is accuracy.
To keep as much accuracy as possible, the program represents numbers like
1.00 as 32-bit integers of the form [1.00 * (2**29)] (approximately
500,000,000).   This yields over 8 significant digits of accuracy, and works
just great -- until the initial values of the fractal calculations on
consecutive pixels differ only in the ninth decimal place.  At that point,
the program does the best it can do -- it switches to its minimal drawing
mode, with consecutive pixels in both directions having initial values
differing by 1 (really 0.000000002) and disables zooming and panning.
This happens more often than you might think, only because it's so easy
(and fascinating) to zoom in on a tiny piece of the previous screen -- and
you can force this situation with your seventh consecutive "maximum zoom",
each of which zooms in on about 1% of the previous screen.  If it's any
consolation, remember that this situation occurs when you are
attempting to draw an area over your full screen that is less than
1/(10**13)th [~0.0000000000001] of the area of the full Mandelbrot set ***
-- and you can always hit the "Home" key to get the previous screen(s) back.

***  Or, you can think of it this way:   First, draw the full Mandelbrot set
     in full VGA mode.   Then zoom in on an area represented by a SINGLE
     PIXEL (which you can't do with the current program) and redraw it as
     a full-screen image.   Then zoom in on an area represented by a single
     pixel of THAT screen and redraw IT as a full-screen image.   Your
     screen is now displaying an area representing ((1/(640*480))**2)th
     [~0.00000000001] of the area of the area of the full Mandelbrot set -
     not yet in minimal drawing mode.   Try it a THIRD time, though, and
     you'll reach it - but not if you can contain yourself and zoom in on
     an area no smaller than 1/100th of the third screen.

***  Or think of it this way:  By the time you have hit minimal drawing mode,
     your CRT would have to have a surface area of over one million square
     miles to be able to display the entire Mandelbrot set.

Also, this being a public domain program and being true to that spirit, the
program makes no attempt to verify that your video adapter can run in the
mode you specify, or even that it's really there, before writing to it.
It also assumes that every EGA adapter has a full 256K of memory (and can
therefore display sixteen simultaneous colors in 640x350 resolution), but
does nothing in particular to verify that fact before throwing pixels at it.

=============================================================================

                    ***** FRACTINT and .GIF Files *****

FRACTINT has for some time contained a "save-to-disk" command which
saves screen images in GIF format.  With version 7.0, FRACTINT also has
a "restore-from-disk" capability.  Unfortunately, this creates a problem.
Compuserve's Graphics Interchange Format (GIF), in its official specification,
does not offer a readily-available place to store the small amount of extra
information that FRACTINT needs in order to implement its 'restore-from-disk'
feature.   FRACTINT gets around this restriction in a non-standard manner,
using the GIF format to store its screen image information and then saving
its 'application-specific' information AFTER the official GIF terminator
character.  This trick works with all of the popular GIF decoders that
we have tested (although some of them require renaming the file to xxxx.GIF
first).

Note, however, that these files saved by FRACTINT are NOT GIF files.
For one thing, information after the GIF terminator has the potential to
confuse the on-line GIF image viewers in wide use on the Compuserve network.
For another, it is the opinion of some of the GIF developers (although not
this one) that the addition of this extra information violates the GIF spec.
For this reason, we are using the default filetype of '.FRA' instead of the
traditional '.GIF', and are NOT portraying these files as .GIF files.
If you wish to save FRACTINT files as true .GIF files, simply specify '.GIF'
as  part of the savename option on the command line ('savename=somename.gif').
FRACTINT will detect the '.GIF' filetype in the savename option and
save its files in a totally compatible .GIF format, without the extra
information.  Note that you will NOT be able to read true '.GIF' files
back into FRACTINT with the 'R' command, however.

Converting an existing FRActal file into GIF format suitable for uploading
to Compuserve is easy.  Just type something like the following command
at the DOS prompt:

             FRACTINT MYFILE SAVENAME=MYFILE.GIF BATCH=YES

FRACTINT will load up the 'myfile.fra' file, save it in true GIF format
as 'myfile.GIF', and return to DOS.

Note that the GIF specifications are constantly under review by Compuserve,
and it is entirely possible that future enhancements to the GIF spec will
provide for a standard way to store application information inside a GIF
file.  It is the intent of the authors to switch to the use of any such GIF
extensions in an upward-compatible manner if and when they become available.

=============================================================================


   This program was compiled using Microsoft C (version 5.1) and Microsoft
Assembler (also version 5.1) using the "Medium" model.   Note that the
assembler code uses the "C" model option added to version 5.1, and must
be assembled with the /MX switch to link with the "C" code.  Because the
program simply got too large to distribute comfortably as a single .ARC
file, and because a number of people now download it with no intention of
ever modifying it, it is now distributed as two .ARC files - one containing
this FRACTINT.DOC file and the executable program, and another containing
complete source code (including a .MAK file and MAKEFRAC.BAT).

=============================================================================

         *** GIF Protocol Statement (required by Compuserve) ***

GIF and 'Graphics Interchange Format' are trademarks (tm) of Compuserve
Incorporated, an H&R Block Company.

=============================================================================

             *** Distribution and Contribution Policies ***

   This is public domain software.   There is no warranty or acceptance
of liability either expressed or implied with it.   Use it, modify it,
distribute it as you wish.   Your uploading it to other bulletin boards and
the like is specifically encouraged.

Contribution policy:    Don't want money.   Got money.   Want admiration.


            Bert Tyler                    btyler on BIX
            Tyler Software                [73477,433] on Compuserve
            124 Wooded Lane
            Villanova, Pa  19085
            [phone]


Super-VGA 256-color mode, Restore-From-GIF, Color-Cycling, FRACTINT.CFG,
and all KINDS of other code in collaboration with:

            Timothy Wegner                 [71320,675] on Compuserve
            1955 Portsmouth
            Houston, Texas  77098
            [phone]


Mouse support in collaboration with:

            Michael L. Kaufman             (accessible via EXEC-PC bbs)
            2247 Ridge Ave #2k
            Evanston, Il, 60201
            [phone]