*********************************************************************
FRACTAL INFINITY v1.0 - An Exploration Program for the Mandelbrot Set
COPYRIGHT (C) 1999 GRAEME FENWICK
*********************************************************************

------------------------------------------------------------------------------
CONTENTS ---------------------------------------------------------------------

	LEGAL NOTICE/ DISTRIBUTION TERMS
	QUICK START
	INSTRUCTIONS
		REQUIREMENTS
		RUNNING FRACTAL INFINITY
		NAVIGATING THE MANDELBROT SET
		COMMAND LINE ARGUMENTS
	OTHER STUFF

------------------------------------------------------------------------------
LEGAL NOTICE/ DISTRIBUTION TERMS ---------------------------------------------

Fractal Infinity is Freeware. You may redistribute it as you wish, subject to
the following conditions :-
	- Beyond reasonable copying and media costs, no charge may be made for
          this program. It may not be used as part of a commercial package,
          nor may it be used without permission for any commercial purpose.
	- The program must be accompanied by this document.
	- Neither the program or this document may be modified.
	- The author accepts no liability whatsover for any damage caused by
          use of this program. The user accepts that this program is free of
          charge, and that they use it entirely at their own risk.
	- By using and/or distributing this program, you agree to these
          conditions.

------------------------------------------------------------------------------
QUICK START ------------------------------------------------------------------

Type
   FRACINF
at the MS-DOS command line (either within DOS proper, or from a
Windows DOS-Box). You may see some messages as the program selects a 
compatible display.
After the screen has cleared, the entire Mandelbrot set will be generated
on-screen (this may take some time if you're running the program on a
386/486). Once complete, you can select a point using the arrow keys, and
alter the magnification setting with +/-. Pressing <RETURN> or <ENTER> will
generate a new picture with that point at the center, using those
magnification settings. (To zoom out, select a magnification less than 1.
If you don't want to zoom at all, <SPACE> sets magnification to 1.0).

-------------------------------------------------------------------------------
INSTRUCTIONS ------------------------------------------------------------------

REQUIREMENTS ------------------------------------------------------------------

To run Fractal Infinity, you'll need the following setup :-
	- IBM PC or compatible, with a 386 (or higher) processor.
	- Either MS-DOS with a DPMI server installed, or Microsoft Windows.
	- SVGA (minimum) graphics card and monitor.

RUNNING FRACTAL INFINITY ------------------------------------------------------

(If you want to run Fractal Infinity under Windows, you should open a
"DOS-Box" or enter MS-DOS mode at this point). 

Make sure you're in the correct directory (or remember to enter the full
pathname), and type :-
	FRACINF
to run the program with the default settings. (At this stage you might see
some messages telling you that the program is trying to find a setting
compatible with your graphics card). Once this has been done, the serious
business of generating the Mandelbrot set begins!

Unfortunately, this process is very processor intensive, and may take some
time on older 386/486s. Pentium based machines should be somewhat quicker.
The image gradually appearing on your screen at this point may look familiar-
it's the Mandelbrot set in it's entirety!

NAVIGATING THE MANDELBROT SET -------------------------------------------------

There are two lines at the bottom of the screen. These contain information
about the current display -
	X	the x coordinate at the center of the current image.
	Y	the y coordinate.
	RANGE	the number of units from the left of the screen to the right.
                The closer you zoom in, the smaller this will be.
	MAG	how much closer the next image will be. The default setting of
                2.0 means that RANGE will halve every time you generate a new
                image. 1.0 means no zoom, and any value less than 1 means
                you're zooming back out again.

(X, Y and RANGE are represented using a form of scientific notation, where
1.5e1 = 15 , -6.7e-02 = -0.067, and so on. If this is all Double Dutch to
you- don't worry. As long as you've can understand the magnification setting,
you should have no trouble making your way round the set).

Once the current display has been generated, you can use the following keys to
adjust the settings for the next display.

        Arrow keys        move the center of the next image to the point
                          selected.
        +, -              increase and decrease magnification.
        Space             Sets magnification to 1.0, i.e. no zoom.
        /                 Save image in BMP format in the current directory,
                          with a filename in the form fr------.bmp. The blanks
                          represent numbers, starting with fr000000.bmp, then
                          fr000001.bmp, and so on.
        Enter             Generate the next image. Because of the way the
                          Mandelbrot set is calculated, areas with a lot of
                          black in them will take longer to calculate than
                          those without.
        Q                 Quit.
 
(You may find very occasionally when saving the screen that the computer will
refuse, saying there isn't enough room- the program recognises slightly less
drive space than actually exists. This *may* be related to the introduction
of the FAT32 file system- see the program notes for more details- but the
problem should only occur very rarely, and only if your hard drive is almost
totally full. I'm still looking into it.)

COMMAND LINE ARGUMENTS --------------------------------------------------------

When you first run the program from the DOS prompt, it's possible to alter a
number of the default settings by following the program name with one or more
switches (the order isn't important)-

FRACTAL [/X[:]xcoord] [/Y[:]ycoord] [/R[:]range] [/H[:]hres]
        [/V[:]vres] [/C[:]depth] [/E] [/?]

With one exception, these are all optional.

        /X:xcoord       specifies the fractal x coordinate at the center of
                        the image.
        /Y:ycoord       same as above, but for the y coordinate.
        /R:range        width of image on display
        /E              Save and Exit mode. Will generate a single image with
                        the specified parameters, save it to disk, and exit.
                        Might be useful if you want to run the program from a
                        batch file.
        /?              A brief summary of the command line options.

The following three switches alter the resolution and depth of the display
used. Before using any of these, you *must* be aware of the following :-
ATTEMPTING TO DISPLAY INCOMPATIBLE RESOLUTIONS ON YOUR MONITOR MAY PERMANENTLY
DAMAGE IT. (You should also read the disclaimer within this document).
Apologies if I've frightened anyone off there, but these aren't settings you
should mess around with casually. Find out which resolutions your monitor
supports first, or stick with the default 640 x 480 screen if you're in any
doubt. 

        /H:hres	        Sets the horizontal resolution. If hres is 640, 800 or
                        1024, then the display set up will be 640 x 480,
                        800 x 600 or 1024 x 768 respectively. For all other
                        values, you must specify the vertical resolution as
                        well.
        /V:vres	        Vertical resolution.
        /C:depth        Color depth. This can be 32, 24, 16, 15 or 8 bits,
                        and determines the number of colors on the screen.
                        Most cards will be unable to display all resolution/
                        depth combinations- generally, the higher the
                        resolution, the less colors you can display. If the
                        program is unable to setup your choice of resolution
                        and depth, it will try again using less colors. You
                        will probably find that 16 or 15 bits are more than
                        enough, but 8 bits (256 colors) will give an
                        acceptable display.

-------------------------------------------------------------------------------
WHAT IS THE MANDELBROT SET? A BRIEF DESCRIPTION -------------------------------

(If this section isn't of interest, or doesn't make sense, you can miss it
out).

This paragraph is only intended to be a brief summary of the important points
for those interested in knowing how the program generates these complex and
beautiful images. (I don't claim to be anything like an expert on the subject-
if any of this is incorrect, please let me know).
The Mandelbrot set is just one of many mathematically generated images known
as fractals, which all have this in common- no matter how much you magnify an
area of detail, you can always zoom in and see more- in other words, they are
infinitely detailed. (Of course, there are also large areas where nothing
happens. The most interesting stuff mostly occurs at the edge of the set (the
set itself is black in this program, with different colors being used to
represent the parts near it).
 

To understand how the image is generated, you first have to understand the
concept of complex numbers. These are a combination of real (ordinary numbers
that we've all seen) and imaginary numbers. 
Imaginary numbers are based on the square root of -1. Since the square of
*any* real number (even negative numbers) will *always* be positive, the
square root of a negative number like -1 has no meaning, or existence (try it
out on an ordinary calculator!). Or does it?
In fact, these strange numbers have many uses, even in "real world" fields
such as engineering. They normally take the form of a number, followed by the
letter i (6.7i, for example), to distinguish them from real numbers. A complex
number combines both real and imaginary components in the form 1 + 2i, where 1
and 2 could represent anything. If you're still with me at this stage, you're
probably wondering where the Mandelbrot set comes into this...

We can look at the screen as displaying part of a graph (in the opening screen
of Fractal Infinity, the point 0, 0 is at the center). The coords of each point
form the basis of a complex number c, where c = x + yi. The equation we need
to get at the fractal takes the following form
	z := z^2 + c
(where := means "becomes equal to", and ^ represents raising to a power, and z
has the *initial* value 0 + 0i). This equation is repeated *many* times (which
is why the Mandelbrot set takes so long to generate), generating new values
for z based on it's previous value, and the value of c.
If the magnitude of z exceeds 2 at any point, we know that the point is not a
member of the Mandelbrot set. If it *never* exceeds 2, then it is part of the
set. The magnitude is defined as the square root of (real(z)^2 + imag(z)^2),
where real(z) and imag(z) are the real and imaginary components of z
respectively. So, if z = 3 + 4i, the magnitude of z is sqrt(3^2 + 4^2), which
works out to be 5. However, in order to save valuable processor time, we don't
need to bother calculating the square root, since
	(real(z)^2 + imag(z)^2) < 4 ???
is the same as
	sqrt(real(z)^2 + imag(z)^2) < 2 ???

The colors on screen are determined by how many iterations of the equation it
takes for the magnitude of z to exceed 2 (or rather, the square of the
magnitude to exceed 4). Different numbers of iterations are assigned the
programmer's color of choice (careful selection here can bring out more
detail, and produce more attractive looking pictures). If the magnitude never
exceeds 2 within a predetermined number of iterations (1000 in this case), we
can say that the point is *probably* a member of the set, and color it black
(or whatever).
All we need do now is to repeat the process for every point we wish to 
display. That's it- however, you can probably see why the process is so slow
now, particularly on the black areas of the image.

Due to the self imposed limit of 1000 iterations in this program, you'll
probably notice some edges have a distinctly moth eaten appearance if you zoom
in close. Increasing the limit would improve this- unfortunately, it would
also make the program run much more slowly.
The other limitation of the program is that you *can't* zoom in forever. At
extreme close up, you may notice the image becomes very chunky and "pixelly".
This is down to the range of values the floating point math can handle- the
spacing between the points has become too small for the computer to represent
accurately. Improving this would also involve a trade off in speed and, in
this case, programming time as well.

-------------------------------------------------------------------------------
OTHER STUFF -------------------------------------------------------------------

Fractal Infinity was mainly written to give myself some practise in using the
C programming language. For this reason, you might not find it as slick as some
other Mandelbrot generation programs- but it isn't as complex either.
This first version certainly isn't perfect- there are a few areas of
improvement I might decide to work on in future (if there's enough interest).
You might want to email me with your own suggestions as well- any constructive
feedback is welcome!
From a programming point of view, the code was written with portability in
mind. I've tried to keep the machine specific stuff isolated from the rest of
the program in order to make life simpler if I ever decide to do this.
As for the name- well, Fractal Explorer would have been my first choice, but
after a quick search of the net, it turned out to have been used already.
Fractal Universe also turned up too often for comfort, and so Fractal
Infinity it was... well, it could have been worse!

Finally, thanks should go to a number of people- DJ Delorie for DJGPP (the
MSDOS port of the Gnu C Compiler), Shawn Hargreaves for the Allegro
multimedia libraries, and the Free Software Foundation who developed the
original GCC compiler. Thanks also to everyone on Usenet who answered my C
questions, and contributed to the numerous resources I consulted while
learning the language.

If you'd like to give me some feedback on the program, or just want to contact
me for any reason, my internet email address is:-
        gfenwick@primex.co.uk

Have fun!

- Graeme Fenwick, 11 January 1999

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

