*********   FRACTINT (Version 9.3)  **********

    An experiment in "Stone Soup" development.  Got anything for the pot?

*****************************************************************************
*  AARRGGHH!  The video table got so darned big that we ran clean out of    *
* Alt-Keys on old (non-enhanced) keyboards!  If you have one of those old   *
* keyboards, and want to use a video mode at the end of the table (from the *
* F11 entry on), read the "Config File" section of the documentation and    *
* then run "fractint batch=config", edit the FRACTINT.CFG file that is left *
* behind to remove the video modes you don't care about, and leave the      *
* resulting file somewhere on your DOS PATH.  FRACTINT will use that file   *
* rather than its full internal video table from that point on.             *
*  (We will try to come up with a more elegant solution for Version 10.x)   *
*****************************************************************************

      +++++ Quick Documentation Format -- Features new to 9.3 +++++

      - (9.3 is just version 9.1 with a bug-fix that works around an
        apparant 8088-incompatibility in the NEC V20 processor <IMUL
        doesn't set the sign flag, which is an (undocumented) 80xxx "feature">
        ... and a second bug-fix for the new Trident, Chips & Technologies,
        and ATI VGA Wonder video modes.

      - New 'P(rint) command and 'printer=' options from Matt Saucier
      - New 8514/A video modes (from Kyle Powell)
      - New SSTOOLS.INI sensitivity and '@thisfile' option on the cmd-line
      - New "Continuous Potential" algorithm for Mandelbrot/Julia sets
      - New "Light source" 3D option for all fractal types
      - New "Distance Estimator" Mandelbrot/Julia method (implemented
        as this version's "test" fractal type) from Phil Wilson
      - New Lambdacosine and LambdaExponent fractal types
      - Color-Cycling mode works with 640x350x16 EGA (as well as VGA) adapters
      - Plasma Clouds can now be generated in 16-color and 4-color video modes
      - Improved TARGA support (from Joe McLain, again)
      - CGA modes now use direct-video read/writes
      - New Tandy 1000 320x200x16 and 640x200x4 modes (thanks to Tom Price)
      - New TRIDENT chip-set Super-VGA video modes (thanks to Lew Ramsey)
      - New Direct-Access Video modes for TRIDENT, Chips & Technologies,
        and ATI VGA WONDER adapters (thanks to John Bridges)
      - New 'Zoom-out' (Control-Enter) option for zooming out instead of in
      - New 'D(os)' command lets you shell-to-DOS from inside FRACTINT.
      - New 2/4/16-color Disk/RAM video mode capability and 2-color
        video modes supporting full-page printer graphics
      - New "inside=-1" option (treated dynamically as "inside == maxiter")
      - slightly improved "Help" and sound routines (even 'sound=off')
      - Turbo-C and TASM Compatibility (really!  Would we lie to you?)

      +++++ Quick Documentation Format -- Features new to 8.1 +++++

      - New 3D Restore-From Disk ('3') and 3D Overlay ('o') commands (Fractal
        Landscapes and Planets!).  (Read the "3D IMAGES" section for details)
      - New "3d=" command-line option for batch-mode 3D images
      - New fast Newton algorithm including inversion option (from Lee Crocker)
      - New 16-bit Mandelbrot/Julia logic for 386-class speed with non-386
        PCs on large (initial screen, first zoom) images (from Mark Peterson)
      - Restore-From-Disk now loads non-FRACTINT GIF files (as Plasma Clouds)
      - New TARGA video modes and color-map file options (from Joe McLain)
      - Thirty New Color-Cycling palette options (SF1 - AF10)
      - New "Disk-Video" (and RAM-Video and Expanded-RAM video) modes
        (no particular graphics adapter required for these modes)
      - Lambda Sets now use integer math (with 80386 speedups)
      - New "warn=yes" command-line option to eliminate over-writing old
        files during save-to-disk operations.

                        +++ 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 (from 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.x +++

      - 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 16-bit
or 32-bit integer arithmetic rather than the "traditional" floating point
("large" images use 16-bit logic; "zoomed-in" images switch over to 32-bit
logic when necessary).   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 some of 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 (functions marked with an "*" are
also available at the initial credits screen):

  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)
  Control-Enter  'Zoom-out' - zoom out so that your current image is
                 positioned inside the current Zoom Box location and Redraw
* 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!
  + or -         (For EGA/VGA adapters only) Begin rotating the palette and
                 switch to the Color-cycling command mode, described below.
                 Note: on EGA adapters, only the 640x350x16 mode cycles.
                 If you have an EGA/VGA adapter, use this for NEAT images!
  c or C         (for EGA and VGA adapters only) Switch to the Color-Cycling
                 command mode described below (in "paused" mode).  
  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 restoring it later 
                 with the 'r' command causes it to be treated as a "plasma
                 cloud" image.  A full explanation of your save and restore
                 options is in the 'FRACTINT and .GIF files' section).
* r or R         Restore an image previously saved with an 's' command
                 (Images saved using version 7.0 or later of FRACTINT can
                 be fully-restored.  Images saved with earlier versions of
                 FRACTINT and non-FRACTINT GIF images are restored as
                 "plasma cloud" images, which may still be color-cycled) 
* 3  or o or O   Restore a (fractal or GIF) image as a 3-D image.  You will
                 be prompted for all KINDS of options - see the section
                 of this document titled "3D IMAGES" for details.
  p or P         Print the current fractal image on your (Laserjet or Epson-
                 compatible) printer.  See the 'printer=' command in the
                 "Command-Line Arguments" section for details on describing
                 your printer setup to FRACTINT.
  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.
                 Note:  if you've used a lot of options, the "frabatch.bat"
                 entry you create may well exceed MS-DOS's 128-character limit
                 on command-line arguments.  If that happens, you can create
                 an indirect file out of the entry ("fractint @myfile").  In
                 fact, if "frabatch.bat" contains only a single entry, you can
                 even use that as an indirect file ("fractint @frabatch.bat").
* 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
* d or D         Shell to DOS (you return to FRACTINT by typing 'exit' at
                 a DOS prompt)
* Esc or Delete  Stop the Program and Return to MSDOS

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

                Color-Cycling commands (EGA and VGA adapters only)

If you have a VGA adapter, or have an EGA adapter and are in 640x350x16 mode,
hitting the 'c', 'C', '+' or '-' keys at the main command level will enter
'color-cycling' (animation) mode (if your adapter is not EGA or VGA
compatible - that is, if it does not have a modifiable color palette - 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.

Note that the palette colors available on an EGA adapter (16 colors at a
time out of a palette of 64) are a LOT more restrictive that those on a
VGA adapter (16 or 256 colors at a time out of a palette of 262,144), so
color-cycling in general looks a LOT better on VGA screens.  Also, because
of the EGA palette restrictions, the commands marked with an '*' are not
available with EGA adapters.

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).
* SF1 thru AF10  (Shifted-F1 thru Alt-F10) Force a pause and set the palette
               to one of thirty pre-set color patterns.  Shifted-Fn keys select
               two-color "straight" patterns (black -> white).  Control-Fn keys
               select two-color cyclical patterns (red -> yellow -> red). 
               Alt-Fn keys select three-color cyclical patterns (blue -> green
               -> white -> blue).
* 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.
  d,D,a or A   Forces a pause and loads an external color map from either
               DEFAULT.MAP or ALTERN.MAP.  These color-maps must be ASCII files
               set up as a series of RGB triplet values (one triplet per line).
               Note that the color values are in TARGA/GIF format (values go
               from 0 to 255), and get divided by 4 before being stuffed into
               the VGA's Video-DAC, so '6' and '7' end up being the same color.
               There are sample DEFAULT.MAP (the VGA start-up values) and
               ALTERN.MAP (the famous "Peterson-Vigneau Pseudo-Grey Scale")
               files for you to examine and modify.
  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 several seconds for a Mandelbrot
Set image in "Low-Rez" EGA or MCGA mode on a 386-based PC or 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.

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 files 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.

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  and the SSTOOLS.INI command file ***

FRACTINT accepts optional arguments that allow you to better control
such things a video modes, iteration limits, and startup display areas.
With Version 8.3 and later, these arguments can also be included in a
SSTOOLS.INI startup file or command-files invoked on the command line
using LINK-style syntax ('fractint @myfile').  When FRACTINT fires up, it
first looks along the DOS PATH for any file called SSTOOLS.INI and reads
start-up variables from that file.  Then, it looks at its own command-line
for arguments that will over-ride those on the .INI file.  The syntax of
the FRACTINT command-line is:

                FRACTINT [argument] [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=]filename  Causes FRACTINT to read the named file, which must either
                   have been saved via an earlier (vers 7.0 or later) FRACTINT
                   session or be a generic GIF file, and use that as its
                   starting point, bypassing the initial information screens
                   (the filetype is optional and defaults to '.fra').  Generic
                   GIF files are restored with fractal type "plasma cloud".
                   The 'filename=' piece of the argument is optional only
                   on the command-line - it is mandatory inside command-files
                   such as SSTOOLS.INI.
@filename          Causes FRACTINT to read 'filename' for command-line
                   arguments.  When it finishes reading 'filename', FRACTINT
                   will resume reading the rest of the command-line arguments
                   (IE, 'fractint maxiter=250 @myfile passes=1' is legal).
                   This option is only valid on the command-line - FRACTINT
                   is not clever enough to deal with multiple-indirection.
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)
                   Note: setting 'inside' to -1 makes inside=maxiter.
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)
warn=xxx           sets the savename warning flag (to 'yes' or 'no', default
                   is 'no').  If 'yes', saved files will NOT over-write
                   existing files (instead the filename will be modified by
                   replacing the last characters with incrementing digits
                   until an unused filename is attained (IE. 'FRACT047').
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).
potential=maxcolor[/slope[/modulus[/potfile]]]  Establishes the "continuous 
                   potential" mode of the MANDEL and MANDELFP fractal types.  
                   The four arguments define the maximum color value, the
                   slope of the potential curve, and the modulus "bailout"
                   value, and the savefile name.  Example:  
                   'potential=240/2000/40/potfile'.  Read the section on the 
                   "continuous potential" algorithm for details.
                   Note that the current implementation of the MANDEL fractal
                   type ignores the modulus bailout value and uses its own
                   hardwired value of 4.0 instead. 
3d=[nn[/nn[/nn]]]...   Replaces the default answers to the '3(D)' command
                   prompts.  If 'filename' is given (above), also forces
                   the restore to be performed in 3D mode.  Very handy when
                   used with the 'batch=yes' option for batch-mode 3D images.
                   Read the "3D IMAGES" section for a full description of
                   the prompts related to 3D.
printer=type[/resolution[/port#]]  Defines your printer setup for FRACTINT.
                   Currently legal printer types (and only the first two
                   characters count) are HP-Laserjet, Epson-Compatible, and
                   IBM-Compatible (which == the Epson at the moment) - the
                   default printer type is the Epson/IBM.  'Resolution' is
                   in DPI, and currently available values are 60, 120, and
                   240 for the Epson/IBM and 75, 150, and 300 for the LaserJet
                   (the default value is the lowest resolution).  Currently 
                   legal port values are 1, 2, and 3 (for LPT1-3) and 11,
                   12, 13, and 14 (for COM1-4).
                   NOTE:  The SSTOOLS.INI file is a REAL handy place to
                   put this option, so that you don't have to remember
                   to type it in every time you load the silly program!
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).
map=filename       Reads in a replacement color map from "filename".  This
                   map replaces the default video color map on your VGA card
                   or the color map on your TARGA card (depending on your
                   video mode).  The file must be in the same format as the
                   DEFAULT.MAP and ALTERN.MAP sample files described in the
                   Color-Cycling section.  The difference between this option
                   and the color-cycling option is that this one is permanent.
                   NOTE WELL:  If colors 0 and 1 decode to the same color,
                   your HELP screens will use the same color for both text 
                   and background - which can be kind of difficult to read.
  ;                indicates the rest of the command-line (or the rest of
                   the individual line inside command-files) is a comment.
                   ('fractint inside=0 ; set the lake to traditional black')
sound=off          Now we all know that nobody ever generates fractals at
                   work, so this is just here so as not to wake the kids...

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.

If you are familiar with Microsoft's TOOLS.INI file, note that you use
the SSTOOLS.INI file in a similar manner.  In particular, you designate a
section of SSTOOLS.INI as belonging to a particular program by
beginning the section with a label in brackets.  FRACTINT looks for the
label [fractint], and ignores any lines it finds in the file belonging
to any other label.  If an SSTOOLS.INI file looks like:

         [fractint]   
         sound=off                    ; (for office use)
         printer=hp                   ; my printer is a LaserJet
         [startrek]
         aye, captain, but I dinna think the engines can take it!
         [fractint]
         inside=0                     ; using "traditional" black

FRACTINT will pick up the second, third, and last line of that file.

(Why use a convention like that when FRACTINT is the only program around
that bothers to look for an SSTOOLS.INI file?  Well, it's because there
are people working on sister programs to FRACTINT that ARE going to read
that file!)

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

       ************** 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 286 or 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).

Also, Mark was the individual responsible for pointing out that 16-bit integer
math was good enough for "large" Mandelbrot/Julia Set fractals (where the
distance between individual pixels is such that any round-off errors using
16-bit math stay well within the range of the area covered by a single pixel).
FRACTINT now uses 16-bit math where applicable, which makes a BIG difference
on 286-class (and below) PCs.

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"


The first parameter to the Newton fractal type is the "order" of the
equation - the value of "n" calculates the Newton formula for the equation
'x**n - 1'.  This determines how many "spokes" are present in the image.
The overall Newton image is radially symmetrical about the origin.

The other parameters are used to invert the Newton plot through a
circle, and they represent the radius, x value of center, and y value
of the center of that circle.  "Inversion" is a process in which each
point inside a circle is mapped onto a point outside, and each point
outside is mapped to the corresponding point inside.  Thus, the plane
is turned "inside-out" with respect to the circle.

For example, if a point on the inside of a circle is 1/3 the way
along a line drawn from the center to the edge, its inverse point is
the point outside the circle along the same line at a distance of 3
times the radius.  If you move the inner point inward to 1/4 the
distance from center to edge, its inverse moves out to 4 times the
radius of the circle.

Because the newton plot has spokes radiating out toward infinity,
inverting each point through a circle centered on the origin makes
these spokes all radiate in toward the center, and the portion that
was inside the circle "explodes" out onto the whole plane.

The best way to visualize this is to create two Newton plots of the
same order, one inverted.  For example:

    type=newton params=5
    type=newton params=5/1

The second plot will be inverted through a circle of radius 1.0
centered on the origin.

If 3rd and 4th parameters are specified, they are used as the center
of the inversion circle.  Inverting through a circle not centered on
the origin produces bizarre effects that are hard to describe. 
Remember that when you place the inversion circle, everything that
was outside the circle will now be inside, and vice versa.

Thanks to Lee Crocker for developing a new, faster, assembler-based algorithm 
for Newton fractals and adding the inversion option.


                *** 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".  Then try 'params=0.2/1' for a lot more detail to zoom in on.  The
Lambda Set algorithm has been re-written using integer math (with 80386
speedups), so an FPU is no longer handy (or even used).

               *** 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.
With Version 8.4, FRACTINT can now generate Plasma Clouds on any adapter
capable of generating four or more colors (previously, Plasma Clouds
required VGA adapters and 256-color video modes).  Still, the more colors
the better with Plasma Clouds.

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.

Finally, Plasma Clouds make GREAT fractal landscapes when viewed in 3D!

         **** "Lambda*Sine" Sets (type=lambdasine) *****
         **** "Lambda*Cosine" Sets (type=lambdacos) ****
         *** "Lambda*Exponent" Sets (type=lambdaexp) ***
 
Thess types calculate the Julia set of the formulas lambda*sine(z), 
lambda*cosine(z), or lambda*exp(z), where lambda and z are both complex.
The LambdaSine 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. For LambdaSines, make the
real part = 1, and try values for the imaginary part ranging from .1 to .4.
In these ranges the Julia set "explodes".  An FPU is a NECESSITY - each
LambdaSine/Cosine iteration calculates a hyperbolic sine, hyperbolic cosine,
a sine, and a cosine (the LambdaExponent iteration "omly" requires an
exponent, sine, and cosine operation)!  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.  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.

The "test" fractal type in this version of FRACTINT is an implementation
of the "Distance Estimator" method for the Mandelbrot and Julia sets
sent to us by Phil Wilson.  It is described in "The Science of Fractal
Images", p. 198.  The algorithm takes two parameters.  If they are both zero,
which is what they will be if you don't specify anything, the algorithm
will use the Mandelbrot set.  If either parameter IS given, the algorithm
will generate a Julia Set image (and the parameters mean the same thing
as they do fir the Julia set fractal).  This algorithm generates two-color
(monochrome) images.

If you have a favorite fractal type that you believe would fit nicely into
FRACTINT, just rewrite the C function in testpt.c (or use the prototype
function in 'testsamp.c', which is a simple Mandelbrot Set implementation)
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.

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

                                3D IMAGES

FRACTINT can now restore images in 3D.  Note the important point that
FRACTINT does not CREATE 3D fractals - it only RESTORES fractal images (or
other single-image .GIF images) in 3D.  To view your favorite image in 3D,
you must first generate it, save it, and then use the new '3' command (or
the '3D=' command-line option) to restore it as a 3D image.  The advantage
to this method (aside from the fact that it's the way we could figure out
how to do it) is that you can view your favorite image many times, varying
the rotation values, aspect ration, and any number of items until you get
the perfect image - and then save the results as a GIF file for the world
to share.

In addition, you can use the 'O' (for 'overlay') command to overlay 3D
images on TOP of existing (fractal or GIF) images (the only difference
between the '3' command and the 'O' command is that the '3' command creates
a 3D image on a blank screen, while the 'O' command overlays the 3D image
over whatever screen you already have).  The 'O' command can be used to
create as many overlays as you like - think of multiple fractal moons
overlooking a fractal landscape.

When you type the '3' command, you get bombarded with a number of options.
Just remember that all of these options have defaults, the defaults have
been chosen so as to give you a pleasant starting point, and that your
answers to the prompts become the defaults for the next 3D image.  Unless
you are a pro at this take the defaults the first time, and then change one
item at a time until you get what you want.

(First picture your original image - the 2D one - as being a 3D image, with
the color of each pixel determining its "height" and pointing toward you.
All the twisting and pulling starts from this "image".)

After prompting you for a filename and video mode, the 3D command asks you
if you want a sphere projection. Answering "y" wraps your fractal around
the surface of a sphere.  Answering "n" gives a "regular" 3D view of your
fractal. Some of the prompts are different in the two modes, so let's
suppose you answered "n" and want "regular", also called the

                   RECTANGULAR COORDINATE TRANSFORMATION

FRACTINT then prompts you for three rotation values - X, Y, and Z axes.
Think of the result as first tilting your 3D image up by pulling the bottom
of your monitor towards you, then tilting it by pulling the left side of
the monitor towards you, and then finally spinning it counter-clockwise,
all by the number of degrees in the prompts.  Note that these are NOT
independent rotations - the image is spun first along the X-axis, then
along the Y-axis, and finally along the Z-axis, and those are YOUR axes,
not those of your (by now hopelessly skewed) monitor.

You are then prompted for three scaling factors in percent - scaling along
the X, Y, and surface "roughness".  Initially, leave the X and Y axes alone
and play with the roughness.  High values of roughness make large mountains
and deep valleys -low values make flat plains. Negative roughness is legal
- if you want Mandelbrot lake to be BELOW the ground, instead of eerily
floating ABOVE, use a roughness of about -30%. (Mathematical note -
roughness is really just a z scale factor).

Next you are prompted for a "water level" (say, did we mention that Plasma
Clouds make quite realistic fractal landscapes when viewed in 3D?).  This
is really a "minimum color" value that performs the function 'if (color <
waterlevel) color = waterlevel' and has the effect of filling in fractal
"valleys" and converting them to fractal lakes.

Next, you are prompted for a "fill" option.  These options exist because
transformed points of an image that DID cover all the pixels MAY NOT any
longer cover all the pixels.  This will become dramatically clear if you pick
the first fill option, which maps dots to the corresponding dot after applying
the 3D transformations. Generally you see many of the dots have been missed.
Therefore you can choose various algorithms that attempt to "fill in" the
missing dots.
                          Fill Options

     0 - (default) - no fill at all - just draw the dots.
     1 - wire frame - joins points with lines
     2 - surface fill - fills in all points on the surface
     3 - surface fill - (interpolation turned off)
     4 - solid fill - draws lines from the "ground" up to the point
     5 - surface fill with light model - calculated before 3D transforms
     6 - surface fill with light model - calculated after 3D transforms

Warning - it takes considerably longer to generate solid images - try lines
first if you don't like dot-mode, and then try surface fills (the general
favorite of the authors).

After all THAT you are prompted for a "perspective 3D" value - the "distance"
from your eye to the image.  A zero value here (the default) means no
perspective calculations (which uses is a considerably faster algorithm).
Otherwise, picture a box with the original x-y plane of your flat fractal on
the bottom, and your 3D fractal inside. A perspective value of 100% places
your eye RIGHT ON THE EDGE OF THE BOX - results in pretty severe perspective
distortion - like taking a close-up with a wide-angle lens. Try about 150%
for reasonable results. LARGE values (500%) give small perspective
modifications (you are far away), and smaller ones create extreme
modifications. Values smaller than 100% put you inside the image itself.
Try larger values first, and work your way in.

Finally you are prompted for two values that let you move the image up or
down, in case the image is improperly centered.

If you selected fill type 5 or 6, you are not done! These two modes color
each pixel according to the ANGLE the surface makes with an imaginary light
source. You are asked to enter the three coordinates of of the vector
pointing toward the light. Finally, you are asked for a "smoothing" factor.
Unless you used continuous potential when generating the fractal (see
below), the illumination fills 5 and 6 will be "sparkly", just like a sandy
beach in bright sun. Applying a smoothing factor of 2 or 3 will allow you
to see the large-scale shapes better. But if your fractal has sharply-
defined boundaries (e.g. "Mandelbrot Lake"), the smoothing effect may cause
the colors to run. If they do, remember, its a FEATURE not a BUG!

The colors will look strange with fill types 5 and 6 until you start color-
cycling and try one of the more continuous palettes (F8 thru F10), or even
better, load the GRAY palette with the "A" ("Alternate") command.

Illumination fill type 5 and 6 differ in this respect: type 5 calculates
the illumination BEFORE doing any transformations. Type 6 applies the
transformations FIRST, then calculates the color. Type 6 is better, but
type 5 is faster. In sphere mode, only type 6 gives you a light and dark
side of the "planet".

Types 2, 5, and 6 interpolate colors when filling, making a very smooth
fill if the palette is continuous. This may NOT be desirable if the palette
is NOT continuous. Type 3 is the same as type 2 with interpolation turned
off. You might want to use fill type 3 if, for example, you wanted to project
a GIF photograph onto a sphere. With type 2, you might see the filled in
points, since chances are the palette is not continuous; type 3 fills those
same points in with the colors of adjacent pixels. However, for most fractal
images, fill type 2 is better than 3. 

                           SPHERICAL PROJECTIONS

Now suppose you answered the first question "y" - you WANT a sphere
projection. Picture a globe lying on its side - north pole to the right. We
are going to map the x and y of the original map to latitude and longitude
on the globe (really a hemisphere). Each ROW of the original fractal
becomes a LONGITUDE LINE on the globe. By changing the defaults, you can
map the fractal to a PIECE of the globe, or wrap the picture clear AROUND
the globe. The defaults exactly cover the globe. You are asked for starting
longitude (180 degrees is the top) and ending longitude (zero is the
bottom). Similarly the latitude goes from -90 to 90 (equator is in the
center - a vertical line since the globe is on its side).

The next prompt is for a RADIUS factor - this affects the size of globe.

All the rest of the prompts have the same meaning as in the regular case.
However "roughness" in this case is roughness of the GLOBE SURFACE.

AN "UGLY" WARNING - some of these parameters result in points hidden from
view by the obstruction of front globe surfaces. Because the process begins
at the "edge" of the sphere, this phenomenon happens most often just as
the process generates its first few dozen lines.  If the computer seems to
have died, WAIT a respectable time to see if points start to appear.

You can also specify these values (and there WERE a lot of them, weren't
there?) with the "3d=" command-line argument.  The argument lets you list
your answers in the same order as they are asked.  You can stop listing
your own arguments and take the rest as defaults at any time, and you can
skip over those defaults you don't care about.  IE, "3d=/////50" just over-
rides the sixth argument (the Z-scaling value).  The "Sphere Projection"
question uses a 0/1 parameter, with 0 (the default) meaning "no".  The
command

          fractint myfile savename=my3d 3d= batch=yes

by itself causes FRACTINT to load up MYFILE.FRA as a 3D image (taking all
of the defaults), save the results in MY3D.FRA, and return to MS-DOS.

Note that any image loaded up in 3D is treated as if it was a Plasma
Cloud.  We have NO idea how to zoom and pan around a 3D image that has
been twisted, stretched, perspective-ized, and had lakes added to it.
And by the time you read this, we've probably added options to wrap it
around a Mobius Strip and pour it through a Klein Bottle.

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

                           CONTINUOUS POTENTIAL

Conventional fractals are calculated by the level set method. The image has
solid bands of color corresponding to regions where the fractal calculation
gives the same value. When viewed in 3D, these images are like terraced
landscapes - most of the surface is either horizontal or vertical. This
does not lend itself to the illumination fill options. However, there is an
alternative approach that calculates a "continuous potential". For our
purposes, the word "continuous" is more important than the word
"potential". The continuous potential method results in CONTINUOUS changes
in colors. A VGA is mandatory to REALLY see this effect. It is hard to show
continuously varying colors with 16 or 4 colors!  The intent of continuous
potential is to display the resulting image in 3D with one of the
illumination model fills. The results have to be seen to be believed.

Continuous potential is approximated by calculating

         potential =  log(modulus)/2**iterations

where "modulus" is orbit value (magnitude of the complex number) when the
modulus bailout was exceeded, at the "iterations" iteration. Clear as mud,
right? Fortunately, you don't REALLY have to understand all the details.
However, there ARE a few points to understand. First, generally the
criteria for halting a fractal calculation, the "modulus bailout value", is
generally set to 4 in FRACTINT.  Continuous potential is inaccurate at such
a low value.  The BAD news is that the superfast types Mandel and Julia
have a value of 4 hard wired, a requirement of the integer math that makes
those types so fast. You can STILL make interesting images in those modes,
though, so don't avoid them. You will see ridges in the hillsides - some
folks LIKE the effect. The GOOD news is that the slower Mandelfp and
Juliafp types have no such limitation.

The parameters for potential are as follows:
    potential=maxcolor[/slope[/modulus[/potfile]]]

"Maxcolor" is the color corresponding to zero potential, which plots as the
TOP of the mountain.  Generally this should be set to one less than the
number of colors - e.g. 255 for VGA. Remember that the last few colors of
the IBM VGA palette are BLACK, so you won't see what you are really getting
unless you change to a different palette.

"Slope" affects how rapidly the colors change - affects the SLOPE of the
mountains when viewed in 3D. If this is too low, the palette will not
cover all the potential values and large areas will be black. If it is too
high, the range of colors in the picture will be much less than those
available. There is no easy way to predict in advance what these values
should be.

"Modulus" is the bailout value used to determine when an orbit has 
"escaped". Larger values give more accurate and smoother potential.
A value of 500 gives excellent results. Note that this value is ignored
for Mandel and Julia fractal types, which have this value hard-wired at
4. If you wish to use a higher value, you must use Mandelfp and Juliafp
types.

"Potfile" is a filename to store the potential image with 16 bits per
pixel. If you save the image in the normal way, and then use the "3"
command to view in 3D, the illumination modes 5 and 6 will work fine, but
the colors will look a bit granular. This is because even with 256 colors,
the continuous potential is being truncated to integers. If the "potfile"
parameter is given, much smoother pictures can be obtained. But beware -
unlike GIF files, these files are not compressed, and they take up 2 bytes
per pixel, so the files can get quit large.

The following commands can be used to recreate the image that Mark Peterson
first prototyped for us, and named "MtMand":

                type=Mandelfp
                corners=-0.19920/-0.11/1.0/1.06707
                inside=255
                maxiter=255
                potential=255/2000/1000/potfile.tiw
                passes=1

This assumes a 256 color video mode.

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

 *** 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 98 adapter/mode combinations,
and is automatically tied to eighty-four 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 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 8514/A MODES:  The IBM 8514/A modes use IBM's software
interface, and require the pre-loading of IBM's HDIDLOAD TSR utility.
There are two sets of 8514/A modes: full sets (640x480, 1024x768) which
cover the entire 8514/A screen and do NOT have a "border color" (so that
you cannot tell when you are "paused" in a color-cycling mode), and partial
sets (632x474, 1016x762) which have small border areas which do turn 
white when you are paused in color-cycling mode.  Also, the video modes
are declared to be 256-color modes, but if you do not have your 8514/A
adapter loaded with its full complement of memory you will actually be
in 16-color mode.  Finally, because IBM's interface does not handle drawing
single pixels very well (we have to "draw" a 1x1 pixel "box"), generating
the zoom-box is excruciatingly slow.  Still, it works!

SPECIAL NOTE ON SUPER-EGA AND SUPER-VGA MODES:  After the 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.

SPECIAL NOTE ON TARGA MODES:  TARGA support for FRACTINT is provided courtesy
of Joe McLain.  The first item we have to bring up about TARGA boards is that
there are a LOT of possible TARGA configurations, and a LOT of opportunities
for a TARGA board and a VGA/EGA board to interfere with each other, and we
may not have all of them smoothed away yet.  Also, the TARGA boards have an
entirely different color-map scheme than the VGA cards, and at the moment
they cannot be run through the color-cycling menu.  Joe has managed to set
up a new "map=" command-line option, however, that works with both TARGA and
VGA boards and enables you to redefine the default color maps with either
board - see the command-line section for details.
 
SPECIAL NOTE ON THE "DISK-VIDEO" AND "RAM-VIDEO" MODES:  After the "Super-VGA"
modes, the video adapter table contains several "Disk/RAM-Video" modes.
These "Video modes" do not involve a video adapter at all - they use either
your spare RAM (if you have enough), your spare Expanded Memory (if you have
that feature, and have enough of it), or your disk drive ("FRACTINT.DSK") to
store the fractal image temporarily.  These non-video modes are useful for
creating images beyond the capacity of your "real" video adapter (right up
to the current internal FRACTINT limit of 2048x2048 x 256 colors), and for
background processing under multi-tasking DOS managers such as DESKVIEW.
Note that Zoom and Pan is disabled during these modes (you can't see where
your Zoom Box is anyway) and, to eliminate thrashing, features such as
orbit display, dual-pass mode, solid-guessing, symmetry checks and (sorry)
plasma clouds that require simultaneous access to several lines of the
"display" are disabled for disk-video and Expanded-Memory-video modes.
On a "typical" PC with 640K of memory running just FRACTINT under DOS,
"Disk-Video" modes up to 640x480x256 currently fit into RAM, and any higher
resolution modes end up going to Expanded Memory or disk.   While in
"Disk-Video" mode, your screen will display text information that lets
you know whether you are using your RAM or your disk drive and what
portion of the "screen" is being read from or written to.

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).
Note: with version 9.x, these "tweaked" IBM VGA modes have been moved to the
very end of the video table to make the keystroke commands for the Super-VGA
video modes a bit easier to remember ("Alt-Comma?  Alt-Equals?").


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

         The Video Modes Configuration file  (FRACTINT.CFG)

If you have a favorite adapter/video mode that you would like added to
FRACTINT, if you want to effectively remove table entries that do not
apply to you, if you just get tired of the fact that your favorite video
mode involves using the "Alt-Left-Swizzlestick" key, or if you are using a
non-enhanced keyboard so that you don't HAVE an "Alt-Left-Swizzlestick"
key, 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) TARGA video modes
             10) Reserved for Future use (HERCULES)
             11) Non-Video [disk or RAM] "video"
             12) 8514/A video modes
             13) CGA 320x200x4-color and 640x200x2-color modes
             14) Reserved for Tandy 1000 video modes
             15) SuperVGA 256-Color mode using the Trident Chipset
             16) SuperVGA 256-Color mode using the Chips & Tech Chipset
             17) SuperVGA 256-Color mode using the ATI VGA Wonder Chipset

  The number of pixels across the screen (X - 160 to 2048)
  The number of pixels down   the screen (Y - 160 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.

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

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

This program uses 16-bit and/or 32-bit integer math to generate Mandelbrot and
Julia Set fractals quickly ("traditional" fractal packages take hours to draw
on a PC without an FPU).  The advantage of integer math is speed:  quite
simply, this is by far the fastest Mandelbrot/Julia Set fractal package that
I have ever seen on any PC - and when running on a 386-class machine in 32-bit
mode, or with a "large" Mandelbrot image in 16-bit mode, the speed is simply
awesome.  The disadvantage of integer math 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 fifth
consecutive "maximum zoom", each of which zooms in on about 0.25% 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 fully restore true '.GIF'
files back into FRACTINT with the 'R' command, however, because the extra
information FRACTINT needs just isn't there.  When the 'R' command encounters
true GIF files (whether FRACTINT created them or not), it does the best it
can and restores them as fractal type "plasma clouds".  

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 .ARCed
file, and because a number of people now download it with no intention of
ever modifying it, it is now distributed as two 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 ***

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

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

             *** Distribution and Contribution Policies ***

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

FRACTINT is distributed as a public domain package, and the bulk of the
code in FRACTINT is public domain software (portions of the code are from
copyrighted sources, and in such cases are clearly marked as such).
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.


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

                    *** Credits and Contact Points ***

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

FRACTINT is the result of a combined effort of MANY developers and literally
thousands of man-hours of time, all for a tiny bit of fame and glory.  Well,
maybe there's a few "bragging rights" included as well.  At any rate, it
has become simply impossible to include the names of all of the contributors
on that pathetic little "credits screen" (a multi-screen "Credits screen"
will have its own set of problems - who makes it to the first page?), and one
of the not-so-welcome tasks of the final co-ordinator is deciding just who
makes it to that screen.

In particular, code and concepts for various sections of FRACTINT have been
"lifted" (quite legally, but still "lifted") from the following unheralded
sources:

PC Tech Journal    -  The CPU and FPU detectors.  Sorry to see that fine
                      magazine bite the dust.

PC Magazine        -  The speaker routines.  "borrowed" from an article in the
                      (as I remember) April, 1977 issue.

Byte Magazine      -  (and the BIX BBS).  The "tweaked" VGA modes, taken from
                      an article (and associated programs) by Richard Wilton
                      in the October, 1988 issue.

MS-Kermit          -  Keyboard routines, including the Expanded Keyboard stuff

Dave Warker        -  The concept of using Integer math for fractal
                      calculations.  No, he didn't invent it, but he DID
                      come up with the idea independently.

Compuserve (and    -  A special thanks here for putting up with all the
the PICS forum        rabble-rousing in PICS Section 16 and elsewhere.
SYSOPs)

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

The following list of authors agreed to the distribution of their mailing
addresses.  Note that Usenet/Internet/Bitnet/Whatevernet users can access
Compuserve users directly if they know the Compuserve userid (IE, Bert
can be reached as 73477.433@compuserve.com).  Just remember that Compuserve
charges by the minute so it costs us a little bit (maybe 10 or 20 cents) to
read a message - don't kill us with kindness.  And don't send all your mail
to Bert - spread it around a little!


            Bert Tyler                    [73477,433] on Compuserve
            Tyler Software                 btyler on BIX
            124 Wooded Lane
            Villanova, Pa  19085
            (215) 525-6355

            Timothy Wegner                 [71320,675] on Compuserve
            1955 Portsmouth
            Houston, Texas  77098
            (713) 522-7933

            Lee Daniel Crocker             [73407,2030] on Compuserve
            1380 Jewett Avenue             lcrocker on BIX
            Pittsburg, CA  94565           ames!pacbell!sactoh0!siva!lee
                                               on Usenet

            Michael L. Kaufman             (accessible via EXEC-PC bbs)
            2247 Ridge Ave #2k
            Evanston, Il, 60201
            (312) 864-7916

            Joe McLain                     [75066,1257] on Compuserve
            McLain Imaging
            2417 Venier
            Costa Mesa, Ca  92627
            (714) 642-5219

            Mark C. Peterson               [70441,3353] on Compuserve
            128 Hamden Ave., F
            Waterbury, CT 06704
            (203) 754-1162