Program Instructions

Home • Gallery • Tutorials • Download • Purchase • Site Map
 

Fractal Program Instructions

Skip this page if you are not a programmer.

The set of statements that make up a Fractal Science Kit fractal program are called Program Instructions or Instructions for short. Instructions are written in a language that is similar to the C programming language. See Programming Language for details.

Instructions are divided into sections. Each section begins with a section label which names the section. Each section performs a specific task related to the overall production of the fractal. The framework executes the code within a section at well-defined points within the fractal generation processing. This design is very powerful as it allows the framework to handle the common tasks necessary to generate a fractal while providing the developer a way to hook into the framework at critical points to perform tasks unique to the fractal at hand.

The different Program Types each support a different set of sections. How a section is used, and in some cases the syntax of the statements found within a section, depends on both the section label and the Program Type. See Program Types for details.

Standard Sections

There are 4 standard sections common to all Program Types:

comment:

macros:

global:

<other sections here>

properties:

As illustrated above, the comment, macros, and global sections, are placed before all other sections, and the properties section is always last. In addition, each program includes 1 or more additional sections specific to the Program Type. These sections are placed between the global section and the properties section. For each Program Type, one of these additional sections is designated the primary section.

Section labels are placed alone on a line with no leading spaces and contain the section name followed by a colon (:). The instructions after a section label up until the next section label, define that section.

As explained earlier, the set of sections allowed within the instructions depends on the Program Type. Sections may be omitted, but if present, they must be given in the correct order as defined by the Program Type. If the only section contained in the instructions is the primary section, the section label can be omitted, but it is considered good practice to include it nonetheless.

Comment Section

The comment section is a place to provide usage instructions, hints, notes, documentation of the code, etc. The compiler ignores the comment section altogether.

Example:

comment:
 
  Spiral Orbit Trap.
 
  Archimedean Polar Equation: r = Scale*t^(1/Power)
  where
    r      - polar radius
    t      - polar angle
    Scale  - distance of point p from the origin when t equals 0
    Power  - inverse power applied to t
 
  Power  Spiral
  ----   ------
  -2     Lituus (use large Scale; e.g., 10)
  -1     Hyperbolic spiral (use large Scale; e.g., 10)
   1     Archimedes' spiral (use small Scale; e.g., 0.1)
   2     Parabolic spiral (also know as Fermat's spiral)
 
  For details see:
    http://mathworld.wolfram.com/ArchimedeanSpiral.html
 
  Logarithmic Polar Equation: r = Scale*e^(t*Cot(Angle))
  where
    r      - polar radius
    t      - polar angle
    Scale  - distance of point p from the origin when t equals 0
    Angle  - angle of tangent at point p relative to line from origin to p
 
  For details see:
    http://mathworld.wolfram.com/LogarithmicSpiral.html

If you include a sequence of characters recognized as a hyperlink, it is displayed as an active link, and clicking on the link will attempt to connect to the Internet and view the associated page. See Hyperlinks for details.

Macros Section

The macros section is where you can include any object definitions, inline functions, inline methods, #include statements, or #define statements that are specific to a given set of instructions. Any other statements found by the compiler will generate a compiler error. Unlike the macros found in the built-in macros or My Macros, the macros placed in the macros section have access to the options, enums, function proxies, etc., defined in the program's properties section. The macros defined in the macros section can be used in the other sections of the program with the exception of the properties section. While the macros section is seldom used, in some situations it can be invaluable.

Example:

macros:
 
  Mobius Shift(angle) {
    Mobius m = Mobius.Identity()
    Mobius.Translate(m, -Center)
    Mobius.Rotate(m, angle)
   
    if (ApplyInversion) {
      Mobius.ApplyInversion(m)
    }
    return m
  }

In the above example, the Shift function is defined. Shift can be invoked in any additional functions or methods defined below Shift in the macros section, or in any of the other sections for these instructions with the exception of the properties section. Shift defines a single argument called angle. The constants Center and ApplyInversion are defined in the associated properties section (shown below). These constants are set to specific values based on the Program Properties settings. Shift uses its argument and the given constants to define/return a Mobius object.

Global Section

The global section is where you place program initialization statements. This section is executed exactly once, each time the program runs. This is where you should initialize data structures, declare arrays, perform one time calculations, etc. Since this section is executed only once, compared to other sections that are executed many times during the program's execution, you should try to move as much processing into the global section as possible.

The global section is also where all constants (i.e., variables declared const) must be declared and initialized. You can assign a value to a variable declared const anywhere inside the global section, just like any other variable. However, in the program's other sections, constants cannot be changed, and expressions using constants are highly optimized resulting in much faster execution times. Clearly, any variable that is initialized in the global section, and used, but not changed, in other sections, should be declared as const.

Example:

global:
 
  const Complex rotAng = DegreeToRadian(Angle)
  const Complex zRotate = Cis(-rotAng)
  const Complex ang
 
  switch (Triangle) {
    case TriangleTypes.T_60_60_60: ang = Math.PI / 3
    case TriangleTypes.T_30_60_90: ang = Math.PI / 6
    case TriangleTypes.T_45_45_90: ang = Math.PI / 4
  }

Properties Section

The properties section is where you define the set of options, through which, you control the program's execution. To define these options, this section supports an entirely different set of language constructs than those used by the other sections. In addition to options, this section can define option arrays, option maps, enums, function proxies, constants, and data tables. See Program Properties for details.

Most of the statements in this section result in one or more constants that you will use in the other sections of your program to control program flow. The user interacts with the properties on the properties pages which sets the values of the constants used by the other sections of your program. Expressions using these constants are highly optimized resulting in much faster execution times.

Example:

  option Count {
    type = IntegerEnum(2,16)
    caption = "Count"
    details = "Number of rotations"
    default = 4
  }
  option Center {
    type = Complex
    caption = "Center"
    details = "Center of rotations"
    default = 0
  }
  option ApplyInversion {
    type = Boolean
    caption = "Apply Inversion"
    details = "Check to apply complex inversion"
    default = False
  }

This example defines a set of options, some of which were used in the Shift function described in the discussion of the macros section above. Here is the resulting properties page:

Program Compilation

Program compilation is the process of compiling the Fractal Science Kit fractal program instructions in order to run the fractal program. Generally, you do not need to concern yourself with program compilation, you simply execute the Display Fractal command on the Tools menu of the Fractal Window, and each of your fractal programs are compiled/run to generate the fractal image. It's when things go wrong that program compilation becomes more important, and knowing a little about what is happening behind the scenes can sometimes help you to find and fix the instructions causing the problem.

When you open the Fractal Science Kit or execute the Display Fractal command on the Tools menu of the Fractal Window, some/all of the programs (based on Processing Optimization) associated with the current fractal are compiled/run to generate the fractal image. Errors resulting from program compilation are called compilation errors and terminate the Display Fractal request.

All compilation errors are reported in the Error/Debug Window. The compiler will usually include the section name and program name where the error occurred, and give a short description of the problem. Armed with this information, you need to open the Properties Window, navigate to the program named in the error message, read over the instructions in the named section, and find and fix the error.

Errors can occur in a function or method you have defined in My Macros too (see Macros). Should this occur, the compiler will tell you what went wrong and you will need to open the Macro Editor and fix the errors before you can generate any fractals.

When you load a fractal file, the properties section for each of the programs defined in the file is compiled. Any errors in the properties section of any program will be reported at this time. Once this section has been successfully compiled, it is only recompiled if the instructions in the program's properties section are modified.

The process of compiling a program is as follows:

  1. Compile the properties section and define constants.
  2. Compile the macros section.
  3. Compile and execute the global section.
  4. Compile all sections specific to the Program Type.

First, we compile the properties section and define constants for all the Program Properties found there. The properties are set to their default values during the compile but the user can interactively change the property values by interacting with controls on the properties pages. Once this section has been compiled, it is only recompiled if the instructions in the properties section are modified. When you modify the properties section and click on the properties page entry in the page hierarchy to view the page, the properties section is recompiled prior to displaying the page. Any compilation errors are reported at this time.

Next, we compile the macros section, and add any macros defined there to the set of macros available to the remaining sections of the program. The constants defined in the properties section are available when you define these macros. However, since we compile the macros section after the properties section, the macros defined here are not available in the properties section.

Next, we compile and execute the global section. Any variables declared const are added to the set of constants available to all the remaining sections. The constants defined in the properties section and the macros defined in the macros section are available in the global section.

Finally, all the remaining sections specific to the Program Type are compiled. The constants defined in the properties section, the macros defined in the macros section, and the constants defined in the global section are available to these sections.

 

Copyright © 2004-2019 Ross Hilbert
All rights reserved