Adding Built-in Formulas
========================

.. highlight:: c

This provides developers an overview of how XaoS handles built-in formulas
and how to add one.

Built-in formulas are defined in :file:`/src/engine/formulas.c`. 

Defining the Formula
--------------------

Each formula is defined by a block of ``#defines``, followed by ``#include "docalc.c"``, 
like this::

	#ifdef __i386__
	#define UNCOMPRESS
	#endif
	#define USEHACKS
	#define PRETEST 0
	#define FORMULA \
		rp = zre * (rp - 3 * ip); \
		zim = zim * (3 * zre * zre - ip) + pim; \
		zre = rp + pre; \
		rp = zre * zre; \
		ip = zim * zim;
	#define BTEST less_than_4(rp+ip)
	#define SMOOTH
	#define SCALC smand3_calc
	#define SPERI smand3_peri
	#define CALC mand3_calc
	#define PERI mand3_peri
	#define JULIA mand3_julia
	#define RANGE 2
	#define RPIP
	#include "docalc.c"

Every time you include :file:`docalc.c`, it means something different depending
on how you have defined the macros. 

Adding the Formula Description
------------------------------

After you have defined the macros, there are two other things are to do:

You must put the description of your formula at the end of
the structure named "formulas". You can make it to be similar to the
other formula descriptions.

	1. FORMULAMAGIC
	2. CALC function
	3. PERI function
	4. SCALC function
	5. SPERI function
	6. JULIA function
	7. {"Name of Mandelbrot", "Name of Julia"}
	8. "short name"
	9. point of view: {x_translate, y_translate, ?, scale}
	10. hassymmetry
	11. isMandelbrot (or Julia, at startup)
	12. pre -- real part of Julia seed
	13. pim -- imag part of Julia seed
	14. {{}{}... structures about the symmetries of the outcoloring modes}
	15. {{}{}... structures about the symmetries of the incoloring modes}

		The symmetry structures take the form:
		{vertical_symmetry, horizontical_symmetry, size_of_other_symmetries, other_symmetries}

		Horizontical and vertical symmetries can be INT_MAX or 0, 
		INT_MAX means no symmetry, 0 means symmetry
		The next two is like: {... 2, sym6} {... 2, sym8} or {... 6, sym16}

	16. some FLAGS, (I still don't know what they mean.)


Adding Function Calls to the Formula
------------------------------------

When this is done, you must put your new functions in the four switch commands at the end of the file.

After compiling XaoS, you should find your fractal at the "More Formulae" menu.
