/*
    brot2: Yet Another Mandelbrot Plotter
    Copyright (C) 2010-2016 Ross Younger

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

A GTK-based interactive fractal explorer.

Features
--------

* mouse-driven navigation (click to zoom in/out and recentre);
* specific zooming by dragging out a rectangle;
* multiple extensible palettes;
* linear antialiasing (optional);
* save image as PNG;
* draws the original Mandelbrot set and a number of related fractals;
  can be relatively easily extended to add more.

Interacting with the plot
-------------------------

The default controls are:

* Left-click to recentre around the spot clicked on.
* Drag with the right button to mark out a rectangle to zoom in to.
  (It may be adjusted to fit the window.)
* Middle-click to zoom out around the spot clicked on.
* Button 8 (the 4th button on my Kensington Expert Mouse) to zoom in,
  centred on the spot clicked on.
* Scroll wheel up and down zoom in and out, centring around the pointer's
  current location.
* Keyboard '+' and '-' zoom in and out around the current centre of the plot.

You can change these via the Controls window (hide/show via the Options menu).

There is a simple single-step undo mechanism. This is designed to let you
recover from the "oh dear I accidentally clicked somewhere silly,
where was I?" scenario.

The current fractal position is shown in the heads-up display overlaid
onto the window. You can change its size, colour, transparency and
positioning via the Preferences dialog.

If you want to specify your plot numerically, you can do this via the
Parameters dialog.

The plot and window sizes are always the same; if you resize the window,
the plot is redrawn to fit.

You can save the current plot as a PNG file, with the option to save at
a different size. (Changing size may take a while as the image has to
be re-plotted.) The HUD is not drawn onto a saved image.

For better image quality, activate the antialiasing mode (Ctrl-A). This
takes longer to draw as it has to plot four times as many points and
average across them. (This is a pretty naive linear antialiasing; better
ways remain to be found and implemented.)

brot2 has the notion of a plot being "good enough" to stop computing. This is
expressed as a fraction (percentage) of the pixels which should have escaped
(or be provably within the set), and a proportion of pixels continuing to
escape in each pass. This is a tricky compromise between drawing enough detail
and not taking forever, and it doesn't always get it right; you can tune it
via the Preferences dialog. You can always stop a plot with Ctrl-. or ask it
to make another pass ("More iterations") with Ctrl-M.

There are multiple colour palettes. At the moment these are hard-coded.
Changing colour scheme is a quick and cheap operation; you can even cycle
through them with Ctrl-1 and Ctrl-2.


Getting and Building
--------------------

The project is mostly hosted on LaunchPad:
	https://launchpad.net/brot2
There is a release archive PPA:
	https://launchpad.net/~crazyscot/+archive/brot2
and a daily build PPA:
	https://launchpad.net/~crazyscot/+archive/brot2-daily

The live source code can be obtained from github:
	git://github.com/crazyscot/brot2.git

In order to build, you will need to have various gtk and gtkmm developer
libraries installed. They are listed in the debian/control file, so will
be taken care of if you use the standard package building tools.


Reporting bugs
--------------

Undoubtedly there are some. Please report them, along with suggestions,
via LaunchPad: https://bugs.launchpad.net/brot2


Hacking
-------

To build for debug, configure with a line along the lines of:
	./configure --disable-silent-rules CXXFLAGS='-g -O0' CFLAGS='-g -O0'

To build for performance, configure with:
	./configure CXXFLAGS='-O3' CFLAGS='-O3'

If you don't specify CXXFLAGS and CFLAGS, your system default optimisation
level (usually -O2) will obtain.

For best speed, a little source-level optimisation helps; while we
compile with -O3 you can still help the compiler out with careful tuning.
See Mandelbrots.cpp for examples.


Fractals and palettes are defined in libbrot2.

To add a new fractal engine, extend class Fractal::FractalImpl or
one of its subclasses. Be sure to add a line to register the class in
Fractal::FractalCommon::load_base() or a function called from it.

The plotter handles fractional escape counts, where the fractal engine
provides that information and a smooth palette is selected.


To add a new palette, extend one of DiscretePalette or SmoothPalette
(or even BasePalette if you want to do something more exotic). Again,
be sure to register it in one of the register_base() functions.
You will find a few RGB and HSV utility classes defined in palette.h.
At the moment all the implementations are in palette.cpp.


What's in a name? 
-----------------

This is my second Mandelbrotter.

The first was cryptically named 'brot'; both the origins of its name, and
the code, are lost in the mists of time circa 2001. It was a bit pants,
even by the standards of the time; it took its parameters on the command
line and output as a TIFF, ASCII art or to a terminal which understood
ANSI graphics codes. (I claim this as a dubiously legitimate reason for
setting xterm to 'unreadable' :-) )

When Benoit Mandelbrot passed away in 2010, I was inspired to revisit
his work (as, it turns out, were some of my friends).
This application is a bit better featured, but to me it's logically the
heir to its now-departed ancestor, hence the name.