FRACTAL INFINITY v1.0 - Source Code Notes/ Distribution.
COPYRIGHT (C) 1999 GRAEME FENWICK

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

This file, and all the files comprising the Fractal Infinity v1.0 source code
are freely distributable, subject to the following conditions :-
	- Beyond reasonable copying and media costs, no charge may be made for
the notes or source code. They may not be used as part of a commercial package,
nor may they be used without permission for any commercial purpose.
	- This file, and the source files comprising the program code must be
distributed together. However, they may be distributed separately from the
main (compiled) distribution.
	- This document may not be modified. You may modify the source code for
your own use, but you may not distribute this modified version without written
permission from me. Copyright in the source code remains with the author.
	- The author accepts no liability whatsover for any damage caused by
use of this program and/or related files. The user accepts that these are free
of charge, and that they use them entirely at their own risk.
	- By using and/or distributing this program, you agree to these
conditions.

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

Fractal Infinity was written in C using the DJGPP compiler, in conjunction
with the Allegro multimedia libraries. The main reason behind writing it was
to give myself some practice with the language, which may explain it's
simplicity in some areas.
Since it was designed with portability in mind,  all non-ANSI code is stored in
the fr_hware.c/.h files, making it easy to keep track of what will need
modifying, and what shouldn't.

In general, there are two types of coords used in the program- those based on
the physical screen position, and those based on the position relative to the
center of the fractal.

Where there is no other value to be returned directly, nonzero
usually indicates a function was successful, and zero means failure. 

fr_main.c : The main program file
---------------------------------

main()
	- default settings are made at initialization, possibly to be over-
written by the command line parser. xr and yr specify resolution, and svx is
the save-exit mode flag.

fr_par.c : The command line parser
----------------------------------

arg_parse() -
	- generic function takes a single command-line-argument, and tries to
separate it out into as many different types of data (initial
character, followed by one or more of long double, int and string) as possible.
	- value returned is a bit-mask, with the appropriate bit being set if
a valid value for a particular type is found. Masks corresponding to these 
bits can be found in the header.
	- sspace is the amount of space passed in for the string. If
the string to be scanned is any longer, it is ignored.

cli_parse() -
	- Uses arg_parse to find out what each switch-argument does, and will
fail if it comes across any nonvalid switches.

correct_usage() -
	- Displays usage info. Will print either an error or program 
description at top of page, depending on value passed in.

fr_gen.c - The fractal generator
--------------------------------

image_generate() -
	- Parent fractal image generator.

iterations() -
	- Return number of iterations for a given set of coords, up to the
limit IT_MAX.
	- Attempts to optimize this function further were unsuccesful- any 
minor tweaks here had the opposite effect of slowing the function down.
	- Despite its simplicity, this function consumes the vast majority of
processor time when the program isn't idle (around 78%).

iteration_color() -
	- Calculates a suitable color for a given number of iterations. This
function may be modified or replaced for a different color range.
	- Normally maxit (limit on number of iterations calculated) and maxcol
will be the same. However, reducing maxcol will squeeze the color range down,
resulting in any values above this becoming "bleached" (all the same color). 
This is hard to explain, but imagine you have a line with the number of
iterations going from 0 to maxit, and a corresponding color range bar below.
Reducing maxcol results in the color bar being squashed toward the left hand 
side, and increasing it has the opposite effect.
	- Regardless of the value of maxcol, any values >= maxit are deemed to
be part of the set, and painted black.

fr_user.c - User adjustments
----------------------------

save_next() -
	- Searches for a valid filename (in the form fr000001.bmp, and so on),
that isn't already used, then saves the current screen under it. There's also
some elementary disk error checking here, but unfortunately, not for the disk
full bug described in the instructions.
	
adjustment() -
	- Uses detect_key() to find out what user has pressed, and lets them
make the appropriate adjustments.
	- The key pressed is returned as an integer value (with a corresponding
#define in the header) if it is Return or Quit (Q). This allows the calling
environment to determine if the user wants to generate the next picture, or to
quit. (Note that a quick-and-dirty way of quitting is to type alt-ctrl-END. 
This is part of Allegro's behavior, and not an explicit feature of my progam).

xhair_adjust() -
	- Allows the user to adjust xc and yc (center of current fractal image)
by moving a crosshair around the screen with the cursor keys.
	- key must be UP, DOWN, LEFT, or RIGHT as returned by detect_key().
	- To select a point outwith the current display, the user must zoom
out first.

auto_setup() -
	- Like a sort of intelligent wrapper to hardware_setup(), this function
checks that everything has gone fine. If not, it will try again at a lower 
color depth, and let the user know by way of a message on screen.
	- xr and yr are the x and y resolutions- depth is fairly obvious.
	- It's debatable whether this function should be in this file at all,
but it seemed like the most appropriate place at the time.

fr_hware.c : Hardware specific (ie non-ANSI) functions
------------------------------------------------------

	- fake_true will contain a pseudo-truecolor palette if the screen is
only 256 colors.
	- sxdim, sydim and sdeep all have external linkage to the rest of the
program (i.e. they are "global"), and correspond to the screen dimensions and
depth. They are used extensively by other functions in other files, which
aren't dependent on any single resolution.

hardware_setup() -
	- Takes x res, y res and depth as arguments.
	- This function sets up a lot of basic Allegro stuff including the
screen, the keyboard handler, and a fake truecolor palette if we're working on
an 8 bit screen. If the screen setup doesn't work, the function will return a
fail value to the calling environment.
	
plot_point() -
	- Takes the screen coords, maxval and maxit (see iteration_color() in 
fr_gen.c, as these variables correpsond to maxcol and maxit respectively), and
the number of iterations. It uses these to calculate a suitable color for
plotting, and puts the point onto the screen at sx, sy.

save_display() -
	- Saves display in file fname.
	- Because of the way Allegro works, it's neccessary to create a
bitmap containing only the visible portion of the screen. Otherwise, when the
screen is saved to disk, a whole load of extraneous border will be saved along
with it. The bitmap is destroyed when we're finished with it.

detect_key() -
	- Normally used to detect user's keypresses (values returned are 
reliant on the #defines in the header file), if flush is set when the function
is called, it has the effect of clearing the keyboard buffer instead.

sleep_wrap() -
	- Included only because sleep() isn't an ANSI function, and I wanted to
keep all files (except this one) totally standard.

message_dialog() -
	- A message only, resolution independent dialog box display. The box is
automatically scaled to the correct width.
	- Two lines of text are passed in. These are displayed alongside the
message "PRESS ANY KEY TO CONTINUE". Whichever is widest determines the width
of the box.
	- If the box would be too wide for the screen, the function returns a 
fail value.

__crt0_glob_function() -
	- By default, DJGPP performs Unix-style globbing of command line args.
We don't want that here, so including this do-nothing globbing function causes
the usual one to be replaced.

verify_imagespace() -
	- This should check that there is enough space on the current disk to
save the screen. If the number returned is less than zero, there isn't.
However, the libc.a function statfs() which this function relies on doesn't
seem to recognise *all* the space on my hard drive- the figure returned is
usually very slightly smaller. This is probably down to the compiler predating
the launch of the FAT32 file system (?)- it seems to work perfectly with other
drives. As yet, I haven't been able to fix this minor bug.

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












