Formula Compiler - Description Function

ChaosPro Home

Introduction

What's New

Palettes

Using Formulas

Layering in ChaosPro

Rendering

Fractal Parameter Windows

Windows

3D Transformations

Animations

Formula Compiler

Writing Formulas

Language Reference

Introduction

Basic Syntax

Datatypes

Constants

Variables

Expressions

Operators

Functions

Control Structures

Compiler Directives

Functions

Interface to ChaosPro

Escapetime Formulas

Quaternion Formulas

Attractor Formulas

Libraries

How it works together

Description function

this.angle

this.center

this.helpfile

this.helptopic

this.magn

this.maxiter

this.method

this.periodicity

this.title

<param>.caption

<param>.default

<param>.enabled

<param>.enum

<param>.hint

<param>.max

<param>.min

<param>.randomizable

<param>.randomizationType

<param>.randomizeMin

<param>.randomizeMax

<param>.visible

<func>.caption

<func>.default

<func>.hint

Special Features, Notes...

Compatibility

Fractal Type Reference

Tutorials

Appendix


Release 4.0

Description Function

This function lets you define general properties of your formula and properties for all parameters of your formula.

General Formula Properties

Formulas can have several properties which make a formula more usable: Some properties define default values for the formula, whereas others specify a descriptive name and the location of a help file for the formula.

Not all properties are supported by all types of formulas. The following table lists all properties and informs you about what type of formula supports a specific property:

	Escapetime			Quaternion			Attractor
	Transformation	Iteration	Coloring	Transformation	Iteration	Coloring	Iteration	Coloring
this.title
this.helpfile
this.helptopic
this.maxiter
this.periodicity
this.method
this.angle
this.magn
this.center

Parameter Properties

Transformations, iteration formulas and coloring formulas may define any number of parameters. But perhaps you may have wondered how ChaosPro actually displays these parameters.

As you can see in that image ChaosPro knows the parameters after having compiled the formula and then displays them using proper GUI elements.

In order to assist ChaosPro in displaying the parameters you can specify additional properties for each parameter. So for example you can adjust the order in which the parameters appear, you can group parameters using separators, and much more.

The biggest benefit from providing additional properties for each parameter is of course not for ChaosPro but the the user of your formula: If you have defined a parameter "cx1Offs_center", then it would be quite confusing for the end user. But you can specify a label and a hint text for this parameter, so users won't ever see the parameter, instead, they would adjust a real number which has a descriptive label.

All this GUI related stuff must be put into a special function called "description".

The order of parameters and functions in the GUI is not defined by the order in which they have been defined. Instead, the order comes from the order of the properties in the description function: So a parameter, whose properties are defined after another parameter, will always be put below that parameter.

To give you a feeling about a typical small description function, have a look at the following piece of code.

   void description(void)
   {
      this.title = "Alpha Texture Mapping";
      this.helpfile = "mpf\alphatexmap.htm";
      
      expertmode.caption = "Show Options";
      expertmode.default =  0;
      expertmode.enum = "Beginner\nExpert";
      expertmode.hint = "Please choose your skill level. If you choose 'Beginner', then only the most common options are visible. If you choose 'Expert' you will see all options.";
      
      mapshape.caption = "Shape of texture";
      mapshape.default =  0;
      mapshape.enum = "circle\nbox\ntriangle\nelliptic";
      mapshape.hint = "Please choose the texture mapping mode, i.e. how your texture will be mapped onto the fractal.";
      mapshape.visible =  expertmode== "Expert"; // only visible in "expert-mode"
      
      separator.label1.caption  = "General Parameters"; // A separator
      separator.label1.visible =  expertmode== "Expert";
      
      randomnoise.caption = "Use random noise";
      randomnoise.default =  0;
      randomnoise.enum = "No\nSlight\nHeavy";
      randomnoise.hint = "Lets you choose the amount of noise to add to the texturing.";
      randomnoise.visible =  expertmode== "Expert";
   }

As mentioned before, transformations, iteration formulas and coloring formulas support parameters and user functions. Thus a description function is supported in all three formula types.

Parameters and their Properties and GUI Elements

ChaosPro supports several datatypes and almost each datatype can be declared as a parameter. Let's have a look at what type of GUI element ChaosPro creates for each datatype and what properties are supported:

Datatype real/double/float

In order to display a real parameter ChaosPro will display a single edit field to that parameter. The edit field pays attention to its minimum and maximum parameter, so if you specify that the valid range for the parameter is from -5 to 5 then the user will not be able to type in a value outside that range.
The following table lists all parameter properties and whether they are supported by this datatype or not.

min max caption hint default enum visible enabled

Datatype complex

A complex parameter consists of two real numbers, thus it has two entry fields: The first one will display the real part of the complex parameter, the second one the imaginary part.
The small button containing a hand appears only for complex parameters: By clicking onto this hand (it will appear sunken) you will enter a special selection mode: If you then move the mouse pointer over any fractal image ChaosPro examines the complex number belonging to the current pixel under the mouse pointer and sets the parameter to that value. If you click onto the fractal using the left mouse button the current value gets set and the fractal will be updated. Clicking with the right mouse button terminates that mode, leaving the parameter unchanged (all changes are undone). You can also terminate this mode by clicking onto the hand again such that it appears raised.

And even more: If you hold down the left mouse button while you are in this selection mode all changes are applied immediately and the fractal gets redrawn on every change. This makes it possible to explore Julia sets: Calculate a Mandelbrot set, calculate the corresponding Julia set for that formula. Then choose the parameter 'c' of the Julia set, enter the selection mode and place the mouse pointer on the Mandelbrot set. Press the left mouse button and - while having it pressed - move the mouse over the Mandelbrot set: The Julia set will change as you move the mouse over the Mandelbrot set. This selection mode is available with any complex parameter.

min max caption hint default enum visible enabled

Datatype quaternion

A quaternion consists of four parts, i.e. of four numbers: They are called "real"-part, "imaginary"-part, "j"-part and "k"-part. ChaosPro will display four edit fields.
If you specify a minimum and maximum (quaternion) value, then these values act component wise, i.e. the real part of the minimum and maximum quaternion value limits the real part of the parameter, the imaginary part of the minimum and maximum quaternion value limits the imaginary part of the parameter. And the same applies for the "j"- and "k"-part.
The following table lists all parameter properties and whether they are supported by this datatype or not.

min max caption hint default enum visible enabled

Datatype int

An integer parameter accepts only non-fractional numbers. There are mainly two cases where integer parameters are used:

The standard way as an integer number: The number of loops to perform, the number of traps, or whatever, where the end user just has to input the desired integer number.
Or as a multi-select value, mostly found in a series of if - else if - else if statements, where depending on the integer number the corresponding branch in the if - else if statement will be taken. In this case you mostly do not want that the user inputs a number. Instead, you would like to allow the user to select a "branch" in your if statement. You can support this by using an enumeration property which is valid only for integer numbers.

Ok, now how will ChaosPro visually display an integer parameter? If you do not specify an enum property then ChaosPro will use the standard edit field as seen below:

Here you can enter your integer number. It will be limited to the minimum and maximum value (if specified).

min	max	caption	hint	default	enum	visible	enabled

Now let's have a look at what happens if you specify the enum property:

Using this property you can assign string values to integer values starting with integer number 0. So ChaosPro will use a drop down box and fills this drop down box with all string values found in the enum property: The user now can choose a descriptive entry in the drop down box, and this entry will be translated to the corresponding integer value: The first entry means "0", the second one "1" etc.

In the formula code you can compare the parameter with either an integer number or with the string. For more details see the description of the enum property.

min	max	caption	hint	default	enum	visible	enabled

Datatype bool

Parameters having datatype bool will be displayed as checkboxes. Please note that the default value for boolean parameters must be a boolean value, too, i.e. either true or false. The properties min and max are not supported, but this should not be a big surprise...

min	max	caption	hint	default	enum	visible	enabled

Datatype color

Parameters having datatype color will be displayed as small color fields. By clicking onto the colored field the color selection window will open where the end user can choose the appropriate color.
The properties min and max are not supported, but this should not be a big surprise. Plase note that the default value for color parameters must be a color, too.

min	max	caption	hint	default	enum	visible	enabled

Datatype array

A very interesting parameter datatype is the array. Normally arrays are used to conveniently store data so that loops can access any desired array value by using indexes. But how should a parameter array work? Well, such a parameter lets you choose an image. The array then gets initialized with the image data. So as you can imagine, initializing an array using a two dimensional image can work if and only if the array has also two dimensions. Well, the compiler will complain if you try to declare a parameter array having a dimension other than 2.

You can use static or dynamic arrays:
- If you declare a static array (i.e. a two dimensional array with fixed dimensions, say real a[20,20];, then there are two cases: Either the image is smaller than the array or it is larger than the array.
  If the image is larger than the array, then only a part (the upper left part) of the image will be used to initialize the array.
  If the image is smaller than the array, then the uninitialized parts (lower right part) of the array will be set to 0.
- In case you defined a dynamic array, say array a[2] of complex, then the array will be sized to exactly match the image dimensions. Use ubound(a,0) and ubound(a,1) to find out the actual array dimensions and thus the image width and height.
But with what values will the array get initialized? First of all, each pixel of an image contains three color components: red, green and blue. Each component can have a value from 0 to 1. If the datatype of the array is:
- bool and int, then the image will be internally converted to a black and white image, the array will be initialized using that image, i.e. black=false=0 and white=true=1.
- real, then the image will be converted to a grey scaled image, the array will be initialized using that image, i.e. the intensity of each pixel.
- complex, then only the red and green parts of the image will be taken: The red part of each pixel becomes the real part of an array element, the green part of a pixel becomes the imaginary part of an array element.
- quaternion, then the real, imaginary and j part of each array element is initialized with the red, green and blue component of the pixels. The k part is set to 1 (alpha=1).
- color, then red, green and blue are initialized with the values from the image, the alpha value is set to 1.
Initializing an array using an image is quite slow, but it will occur only once, when the end user selects the image. Because the image is loaded and remains in memory as long as it gets referenced it need not be loaded again when the user changes any other parameter. So generally it's quite fast after the initial load.

Note:
The default value for an array parameter is a path to an image, i.e. a string!

min max caption hint default enum visible enabled

Separator

In order to visually group certain parameters you can place a separator (horizontal line) between parameters. A separator must have a unique identifier. It need not and cannot be declared, simply put the separator instructions into the description section.
The identifier must be followed by the property.

The general syntax is:
separator.<ident>.<property> = <value>;

The supported properties are only caption for the preceeding text and visible to show/hide the separator.

Example:
- separator.label3.caption = "Texturing";
- separator.label3.visible = trapcount>= 1;
min max caption hint default enum visible enabled

Function Selector

Sometimes it is desirable that the user chooses one of the standard arithmetic functions. Whenever your formula uses an unknown function which accepts a complex number ChaosPro will make that function adjustable. The end user then can choose what function to use.

Example:
```
z2=map_func(z);
```
The function map_func is unknown to ChaosPro. Normally the program now would display an error "Undefined function". But this function accepts a single complex value: So ChaosPro won't display an error. Instead, it will display a drop down box where the end user can select a function from the standard arithmetic functions.
You do not need to declare such an adjustable function nor do you need to place a parameter keyword anywhere. But you can specify additional properties for this function, so the user can see what is means.

Please note that you cannot adjust the list of arithmetic functions. It will always display all standard arithmetic functions built into ChaosPro.

min max caption hint default enum visible enabled

Merge Function Selector

Similar to above there is another kind of function which is user adjustable: Whenever your formula uses an unknown function which accepts two variables of datatype color ChaosPro will display a drop down combo box so that the end user can choose a proper function to use. In contrast to the previous section the combo box gets filled with all color merging functions and not with the arithmetic functions.

Example:
```
pixelcolor=merge_func(gradient(real(z)),pixelcolor);
```
The function merge_func is unknown to ChaosPro and apparently accepts two colors. So ChaosPro will display a drop down box where the end user can select one of the merge functions which have been built into ChaosPro.
Just as before, you do not need to declare such an adjustable function nor do you need to place a parameter keyword anywhere. But you can specify additional properties for this function, so the user can see what is means.

Please note that you cannot adjust the list of merge functions. It will always display all merge functions which have been built into ChaosPro.

min max caption hint default enum visible enabled