Import XaoS r489 (trunk after version 3.5)

1 files changed, 82 insertions, 0 deletions

diff --git a/help/rest/addformula.txt b/help/rest/addformula.txt
new file mode 100644
index 0000000..6a19e28
--- /dev/null
+++ b/help/rest/addformula.txt
@@ -0,0 +1,82 @@
+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.