----------------------------------------------------------------------------------------------------
            (C) 2005-2014 by Dennis Busch, Dennis-Busch@gmx.net, http://www.dennisbusch.de
----------------------------------------------------------------------------------------------------
(This documentation is -> preliminary <- and subject to change.)

0.)
Content:
--------
-1.) Changelist
 0.) Content
 1.) Title,Version,License
 2.) Quick Start Guide
 3.) Source Code
 4.) short compiling instructions
 5.) Greetings to
 6.) Thanks to
 7.) TO DO
 8.) Closing Comment


1.)
Dennis Busch's Dynamic Color Gradient Generator
-----------------------------------------------
Version: beta2
License: see LICENSE.txt

----------------------------------------------------------------------
#include <std_disclaimer.h>
"I do not accept responsibility for any effects, adverse or otherwise, 
 that this code may have on you, your computer, your sanity, your dog, 
 and anything else that you can think of. Use it at your own risk."  
----------------------------------------------------------------------

2.)
QUICK START GUIDE:
------------------
"What does this "Dynamic Color Gradient Generator" do?"
  It generates color gradients based on objects, i want to call "color attractors".

"How does it work? (basically)"
  For every pixel on the target bitmap, it checks the distance of that pixel
  to every color attractor.
  Based on that distance(d), 
  (and on parameters: intensity(i),exponent(exp) and range(rng))
  a precisely calculated amount of every color attractors' color is mixed in to
  the resulting color for the current pixel.

  (details)
  More precisely, if the pixel is in range of an attractor, the fraction(fr) of its'
  color, that gets mixed in is calculated by:
  fr = (1.0 - (d/rng)^exp ) * i
  (You see from the formula: if 'd' is 0.0 'fr' equals 'i' and if 'd' is 'rng', 'fr' equals 0.
  Depending on the mode (attract+,absorb-) the sign of 'fr' is changed.

"How do i make it do anything?"
  Load up the supplied examples in the programme itself.
  Play around with the various parameters. Have some fun. 
  (USER manual is "work in progress" at the time of writing this)
  (Also note the known BUGS in beta version: load "knownBUG1.dcgg" and "knownBUG2.dcgg")


3.)
SOURCE CODE:
------------
  Full C/C++ sourcecode is supplied with the archive this file came in, see subdirectory: "./src/"
  For now you have to be happy with the comments inside the code, a good place to start looking
  are the introducing comments in "dycogrgen.cpp" and "gradient_gen.hpp".


4.)
short compiling instructions:
-----------------------------
  Just compile all .cpp files and link with Allegro(4.20rc2 or higher REQUIRED!).
  For platform specific additional libraries to link in, check the Allegro documentation.


5.)
GREETINGS:
----------
  Greetings fly out to my family, my friends and last but not least
  to all members of the Allegro Community. (http://www.allegro.cc)


6.)
VERY SPECIAL THANKS GO TO THE FOLLOWING ALLEGRO.CC MEMBERS:
-----------------------------------------------------------
Miran Amon(miran)
  for voluntarily writing a nice GUI to an early C version of the generator and
  implementing new features to it almost immediately after i requested them.

Florian Lherbette(da_flo)
  for not growing tired of extensive math discussions, regarding the polynomial/ellipse p
  attractor type and for suggesting to keep the core generator functionality system independent.

Martin Cerny
  for trying to find a faster way of computing the precise distance to the polynomial.

Additional thanks go to following allegro.cc members for participating in more discussion 
about the generator, for their interest in it, and/or for commenting some of its' output:
  Neil Walker, Richard Phipps, James Lohr, Edward Sheets, Jakub Wasilewski, HoHo,
  Kent Larsson, Michael Faerber, Gideon Weems, Evan Wilson, Pedro Avelar Gontijo,
  dthompson, GullRaDriel, William Heatley, 23yrold3yrold, Ceagon Xylas and Jonny Cook
(hope i did not forget anyone, if so, drop me a line)


7.)
  TODO(after BETA2 release):
  -------------------------
    * fix bugs (known GUI bugs: point e / ellipse middleclick dimension setting 
		(is set wrong when attractor is rotated))
		known Generator bugs : see "gradient_gen.hpp")
    * implement missing features( render over image(generator already
                                                    has it, but it is not yet
                                                    accessible from GUI),
                                  save language on exit)
    * write USER, TRANSLATOR, DEVELOPER documentation
    * seperate GUI code into smaller (better maintainable) files
    * optional loading of font from a datafile "languagename.dat", so
      that translators can create fonts that include the needed UNICODE
      ranges for languages not supported by the Allegro standard font
      (write FONT creating documentation (max font height will be 22 pixels)
    (only the top-priority "todo"s are listed here)


8.)
CLOSING COMMENT:
----------------
I'm sorry for this very short "manual", i'll write some more extensive documentation
for version 1.0.

I hope you enjoy playing around with this tool,
  Dennis Busch
----------------------------------------------------------------------------------------------------
            (C) 2005-2014 by Dennis Busch, Dennis-Busch@gmx.net, http://www.dennisbusch.de
----------------------------------------------------------------------------------------------------
(EOF)