\pagebreak

\section{Developer information}\label{developers}\index{Developer Information}

The Mandelbulber team welcomes everyone who likes to help us with the development of the software.
Whether you are a C++ fan and want to implement new features or you like to tweak the fractal formulas.
The code base is well structured and can be compiled with most common compilers and operation systems.
No magic involved, you just need to learn the tools and utilities to modify and run your own version of Mandelbulber.

The following chapters will help you get ready for development.

\subsection{Setup}\label{developers-setup}

Mandelbulber is using git as version control system and github as the hoster.
If you do not know git yet, you may find the following ressource helpful: 

https://git-scm.com/book/en/v1/Getting-Started

Anyway the following setup steps will assume you git cloned the repository:

https://github.com/buddhi1980/mandelbulber2

locally to a project folder. This folder will be referenced as \textbf{MANDELBULBER2\_DIR}.

\subsubsection{Setup Debian/Ubuntu}\label{developers-setup-debian-and-ubuntu}

To setup the system for development in debian and ubuntu you can use the files: 

[MANDELBULBER2\_DIR]/mandelbulber2/tools/prepare\_for\_dev\_ubuntu.sh

[MANDELBULBER2\_DIR]/mandelbulber2/tools/prepare\_for\_dev\_debian\_testing.sh

Please make sure you read them before execution!

\subsubsection{Setup Windows}\label{developers-setup-windows}

TODO

\subsection{Building}\label{developers-building}
\subsubsection{Building with MSVC}\label{developers-building-msvc}

Download and install latest MS Visual Studio version (tested with Visual Studio Community 2017).
Make sure you enable nuget support as an installed software.

Then open the project file 

[MANDELBULBER2\_DIR]/mandelbulber2/msvc/mandelbulber2.sln

and compile. Good luck!

\subsubsection{Building with qtcreator}\label{developers-building-qtcreator}

Compilation in QtCreator

\begin{itemize}
	\item open [MANDELBULBER2\_DIR]/mandelbulber2/qmake folder in File Manager
	\item open mandelbulber.pro in Qt Creator
	\item when it's open, click Configure Project
	\item unfold Compiler Messages window (on the bottom of window)
	\item click hammer icon (build - left/bottom corner)
	   the program will be compiled. If you did all steps correctly, you shouldn't receive any error
	\item try to run the program using the green arrow
\end{itemize}

\subsection{Writing own formulas in Mandelbulber}\label{developers-writing-own-formulas}
\subsubsection{Writing formula code}\label{developers-writing-formula-code}

Adding new formulas:

- fractal\_list.hpp:45 - \emph{enum enumFractalFormula} - here is the list of formulas. Add new formula at the end with unique number.

- fractal\_list.cpp:41 - \emph{void DefineFractalList(QList<sFractalDescription> *fractalList)} - here is detailed list of formulas

example:
\begin{lstlisting}
fractalList->append(sFractalDescription("Kaleidoscopic IFS", "kaleidoscopic_ifs",
		kaleidoscopicIfs, KaleidoscopicIfsIteration, analyticDEType, linearDEFunction,
		cpixelDisabledByDefault, 100, analyticFunctionIFS, coloringFunctionIFS));
\end{lstlisting}

\begin{itemize}
	\item 1st field: Displayed name of the fractal
	\item 2nd field: internal name of the fractal. The same name is used for UI files
	\item 3rd field: the same name as in enumFractalFormula
	\item 4th field: The function name as defined in fractal\_formulas.cpp
	\item 5th parameter: Preferred distance estimation method. The deltaDE method needs more computation time but doesn't need analytical DE coding knowledge.
	\item 6th field: Preferred distance estimation function
	\item 7th field: TODO
	\item 8th field: Default bailout value
	\item 9th field: Final calculation type
	\item 10th field: Coloring function
\end{itemize}

- fractal\_formulas.cpp - here are definitions of functions which calculate single fractal iteration. There is no adding of C constant and bailout condition here.

example:
\lstinputlisting[caption={Formula > Mandelbulb formula}]{code/formula_mandelbulb_with_function.cpp}

The arguments are the same for each formula:
\begin{itemize}
	\item \textbf{CVector4 \&z}: input / output variable containing iteration vector
	\item \textbf{const sFractal * fractal}: read only container with all fractal parameters
	\item \textbf{sExtendedAux \& aux}: input / output auxiliary structure containing values 
		needed for instance to calculate estimated distance
\end{itemize}

All parameters and data structures are defined in fractal.h

- fractal\_formulas.hpp - here are tehe header declaration of the functions

- initparameters.cpp:499

\begin{lstlisting}
void InitFractalParams(cParameterContainer *par)
\end{lstlisting}

 - here are definition of names of parameters which are used in UI and settings files. If you add new formula then try to utilize existing names. If there is nothing which fits to your needs, then add a new one

- fractal.cpp, fractal.hpp - here are data structures for fractal parameters. There is also copying of values from internal parameter representation to data structures which you use in fractal functions

\subsubsection{Designing user interface}\label{developers-designing-user-interface}

To create UI files you can use Qt Designer application. The best would be if you make them based on existing files. All ui files are located in formula/ui folder. Names start with fractal\_ and the rest of name is the same as internal fractal name. Even if a formula doesn't use any parameters, you need to create an UI file with no adjustable input fields, see fractal\_quaternion.ui for example (some kind of dummy).

In the UI files the names of the edit fields define their type and their parameter reference. The program connects automatically edit fields with adequate parameters and with sliders / knobs. But to make it working first part of the name must describe type of edit widget. Use following prefixes:
\begin{itemize}
	\item spinbox\_ - scalar value
	\item slider\_ - slider for scalar value
	\item checkBox\_ - boolean value
	\item spinboxd3\_ - edit field for knob for angle. This is for 3 dimensions, 
		where angles are stored in CVector3 data type. Last letter of name must indicate axis name (\_x, \_y, \_z)
	\item dial3 - knob for spinboxd3
	\item spinboxInt - spinbox for integer value
	\item sliderInt - slider for spinboxInt
	\item logedit - edit field for high variation value (only positive)
	\item logslider - slider for logedit which changes value in logarithmic scale
	\item vect3 - 3d vector (related to CVector3 data type). Name must ends with axis name
\end{itemize}

The rest of the names of the edit field must be the same as defined in initparameters.cpp

\subsubsection{Autogeneration of opencl formula code}\label{developers-autogen-opencl-formulas}

TODO
