Custom Variations

Fractal Architect 5 Help Index
Fractal Architect icon

Custom Variations

Applies to:FA 5

See: Variation Set Tutorial

See: Custom Variations Syntax

Custom Variations Concepts

Variations provide control over the geometric shapes created by the renderer. For instance, if you choose to just use julia variations in your fractals, you will see the characteristic julia shapes. If then say you add a linear variation to your fractals, those fractals will exhibit the typical shapes of both the linear and julia variations.

Creating Brand New Variation Types

New variation types can add new exciting shapes to your fractals. Writing variations is actually programming in the OpenCL C language and can require both programming skills as well as knowledge of computer graphics and analytical geometry. So for most Fractal Architect users, writing new variation types is a very difficult task. But the hope is that some advanced users will create their own variation types, export their Custom variation library, and share that library with the fractal community on websites like deviantart.com.

Tweaking Existing Variation Types

Another thing you can do is to take an existing variation type, duplicate it and modify the copy, and name the changed variation with a new name showing that is a derivative of another classical variation type. This can be surprisingly easy to do, even for non-programmers. The app has the ability to do these steps for you.

The app suggests new variation names for these tweaked duplicates. For example, if you
want to tweak the julia variation type, you pick the Factory Library, the select the variation type to clone, then click the Duplicate button. It will copy the cloned variation to your Custom library, and name it as julia_x1. The copied source code is modified automatically to reflect the new name. The new name shows that it is an experimental fork of the Julia variation type.

Now you want to use the text editor and change the source code for the experimental Julia variation. Test compile it to check for syntax problems. When the changes compile successfully, you then create a new variation set using your experimental Julia. Make some fractals with it.

The app does not allow you use the original factory variation name again. The name must be different. This restriction is VERY important. Just think how confusing it would be you were allowed to change the factory variation types. Then all of your older fractals that used that variation would look wrong! That would be a total mess.

Writing Variations for OpenCL vs Apophysis vs JWildfire

Fractal Architect’s renderer is implemented in OpenCL and can execute on either a Mac’s CPU or its GPU(s) if it has them.

The actual renderer OpenCL is comprised of two main pieces: a core set of kernels invoked by the app and a separately configurable variation library. Experience has shown that programming for the GPU imposes a number of limitations versus programming apps in general. The most important is that the size and complexity of the variation type library can make it impossible for current OpenCL driver/runtime compiler implementations to actually use kernels that have a huge variation type library in them.

This fact drove us to create the Variation Set architecture to work around this fundamental limitation. Variation set size limitations force you, the user, to work with just a subset of at most 100 variation types at a time (out of potentially thousands of variation types).

So with Fractal Architect custom variations, the variation source code is written in the OpenCL C language. Documentation for this fork of the C programming language can be found in the OpenCL 1.2 Specification.

Apophysis C Based Variations

Apophysis custom variations are written in C language and most conform to their custom variation framework’s protocols. Apophysis custom variations are built into DLL’s using Microsoft Visual Studio.

Jwildfire Java Based Variations

Java’s expression and statement syntax is similar to C, so porting variation source code from Java to OpenCL C is not hard, just tedious. Most Java development is done with an IDE like Eclipse. Andreas Maschke’s JWildfire has the most comprehensive variation library available now. The Apophysis community for custom variations can be found on deviantart,com. Andreas has ported many Apophysis variation types into Java.

Tools Required for OpenCL C

The app contains all of the tools you need to create new variation types, test compile them, and actually use them in new fractals you create. The created variation types can be exported as an XML library, which you can share with other users of the app. The app contains a basic text editor sufficient for coding your new variations. You can also choose to use your own programming text editor instead. We use TextMate, but any programming editor can be used.

The custom library you create is an XML file containing C language snippets for each new variation type you create. So you need an editor that handles both XML and C well.

The app’s Custom Variations panel hides the XML format allowing you to focus on just the C source code.

You don’t need to use Xcode at all. Xcode does not provide the best tools for working with XML and it is awkward to edit C code that is not part of an Xcode project.

Apple currently provides no debugging capability on any OpenCL platform. You cannot even add simple print statements. If you manage to crash the renderer in your custom variation code, the crash dump cannot be symbolicated, leaving you guessing as to the code defect that caused the crash. This is a tough development environment.

Thankfully, most of the C code for variations is implementing math equations in C. Normally math equations don’t crash OpenCL kernels. They might create the wrong output.

Still it is possible to crash the app or even lock-up your GPU forcing you to forcefully reboot your Mac. But after porting 200 popular variation types to OpenCL, we found the port effort is just tedious and not crash prone. (The app has some builtin tools to help you port/convert Apophysis C and JWildfire Java to OpenCL C.)

In practice, we have had trouble porting Perlin/Simplex noise based variation types (like the popular Crackle). Those variation types use complex data structures, which if incorrectly used in the code, can cause crashes/lock-ups. Typically those variation’s source code is much more complex than for a typical variation. Apple has improved their OpenCL drivers, so Mac OS recovers better from faulty GPU code. Its unfortunate that Apple provides no debugging capability, as incorrect memory access is so hard to troubleshoot when you have no tools to work with.

We have clearly been able to use it to create the Fractal Architect app. We are what you call: “experts” in OpenCL development. We gained this ability by simple persistence and a lot of head scratching when trying to figure out solutions. We have not figured out how to fix broken OpenCL driver implementations which have Mac OS X on certain platforms. (Only Apple can fix OpenCL driver/compiler issues.)

Factory Library vs. My Library

Fractal Architect provides a builtin factory library with about 350 variation types in it.
There are probably about 100 to 200 more existing variation types not included in the library and with the new Custom Variations capability now part of Fractal Architect 5 there is the potential for thousands of new variation types.

That library is stored inside the application’s runtime sandbox container as library.xml.

Because future application updates might overwrite any changes you make to this file, Fractal Architect provides an initially empty library, myLibrary.xml. The factory library is treated as a read-only library, whereas My Library is fully editable (and not subject to updates).

You can study the variations inside the factory library to learn how they work.

Custom Variations Panel

This panel allows you to create new custom variations and/or create new experimental clones of another variation type. Open it from the Random Generation Settings popup or the Make New Variation Set popup.

Library Sub-Panel

Factory variations (those that are provided by the app) always reside in the Factory Library. Custom variations will always reside in your My Library.

Selecting a Library

In the upper left hand corner of the panel is the Library Selector. Choose one of the libraries, whose variations you want to work with.

Viewing a Library’s Variations List

Click the View Library button. This table will pop up:

Variation: the variation’s name.
Status: will be one of: Useable, In-Development, or Broken.; Only useable variations can be used in variation sets or fractals. Broken variations indicate the variation does not work correctly. In-Development status indicates a custom variation that has not been test compiled successfully.
Usage: The number of variation sets that include this variation.
Author: the varition’s original author (if known).
3D: is this a 3D only variation?
DC: Does this variation support direct coloring?

Removing Unwanted Custom Variations

Select the custom variations you want to delete from the Library Viewer popover. Then click the - button to remove them.

Note: If a custom variation is being by any variation set, it cannot be deleted. You will need to discard the referring variation sets first. Use the Used By button to investigate which variation sets use a selected custom variation.

Library Management Utilities

See the upper right hand portion of the panel for these utilities.

Choose Location For My Library: My Library is initially inside the app’s sandbox container. This utility allows it to be moved anywhere you like (moving it outside the container is recommended).
Show Library in Finder: Opens the folder holding the library in the Mac Finder. This allows you to use your own programmable text editor to view it.
View Library Source: Opens the library’s XML source into a read-only text viewer window.
Import External Library: Select a library and import its variations. Duplicate variations found inside the import library are ignored.

Adding a New Custom Variation

Select the My Library library, then click on the + button.

This will create a new variation named “myCustomVariation”. Please change the name to something you like.

Duplicating an Existing Variation

Select the My Library library, then click on the Duplicate button.

Let’s say you have the julian variation selected in the Factory library. Click the Duplicate button.

This will create a new variation named “julian_x1” in your My Library. The “_x1” is appended to the original variation name to signify that this is the first experimental variation.

Note the app does not allow you to create a new custom variation with the same name as a builtin factory variation. All custom variations must have new unique names.

Deleting a Custom Variation

Select the My Library library, then click on the - button.

If that custom variation is being used by variation set, deleting the custom variation is not allowed. (So remove any test variation sets first, then you can remove the variation set.)

Note: You cannot delete a factory variation.

Finding Which Variation Sets Use the Variation

Click the Used By button to get the names of the variation sets that are using this variation.

Variation Properties

Variations have a number of properties that can be set:

Renderer: Set to one of: 2D Only, 3D Only, or Both 2D and 3D. This specifies whether the variation can be used in 2D and/or 3D variation sets.
Supports Direct Coloring: specifies that the variation supports direct coloring or not.

Author and License Info

Author: who is the author?
License: a choice of some popular licenses.
Copyright Year: specifies the year of the author’s copyright.

Variation Parameters Table

This table holds information about the variation’s parameters. These parameters values can be set by you, when you actually use that variation type in a new fractal.

I recommend looking at the mobius variation in the factory library for an example of their use.

Also, a good simple example is the very popular classic variation, julian in the factory library

Name: Parameter’s name; Note: in fractal files, the parameter’s value is saved like: mobius_re_a, where the parameter name is concatenated after the variation name. If the parameter has an alias name, that file might use the alias name instead of the fully qualified name.
Type: Either Float or Integer
Default: the default value for that paramerter.
Min Random: minimum of random value range for that parameter
Max Random: maximum of random value range for that parameter
Non-Zero: if set to true, the random generator will not use zero for this parameter
Alias: Most variations parameters do not have alias names, but these are alternate
parameter names that you might find if you open a fractal created in Apophysis.

Adding a New Variation Parameter

Click the + button next to the variation parameters table.

Removing a Variation Parameter

Click the - button next to the variation parameters table.

More Utilities

Test Compile: Does a test compile of the current variation. If the compile is successful, the variation’s status is set to Useable. Both compile success or failure is reported.
Batch Compile: Test compiles all variations in the library whose status is In-Development.
View Test Kernal: Opens a text viewer showing the actual Test Compile’s test kernel.

Builtin Variation Source Editor

Open it by clicking on the Variation Editor button.

Source Editing Utilities

Find: Text editor Find and Replace.
Convert Apo Plugin: Converts Apophysis plugin C source code to OpenCL C compatible source. This converts the standard builtin global variatble names, math function names, and double precision numeric costants to float single precision. Its a dumb converter, so you may have to do more modifications by hand afterwards.
Test Compile: Creates test kernel and trys to compile it. Success or compile errors are reported. Error messages are logged to the app’s Render Status Log.

The vast majority of variations in use today do not use Sub-Functions or Function Prototypes. Fractal Architect does support custom variations using those features. It is discussed later in this document.

Using Your Own Text Editor

You can choose to use your own text editor. Here is how with TextMate:

First, open the builtin editor for a variation. Select all the variations source text by using the ⌘A key combination. Next copy the selected text to the clipboard with the ⌘C key combination.

Switch over to TextMate. Create a new empty document with File > New. Paste the source text with Edit > Paste or ⌘V. Choose C as the source format.

Edit the source in TextMate. When you are done, you need to copy the source text from TextMate and paste it over the source text if Fractal Architect’s source editor.

Close the Fractal Architect source editor (or use the Context menu Save command %S) to save the source text.

Sub-Functions / Function Prototypes

I recommend looking at Georg Kiehne’s falloff2 variation in the Factory library for an example of their use. Typically, only very complex variations make use of sub-functions.

You can click on the Sub-Functions Editor button to edit the sub-functions. You can click on the Prototypes Editor to edit their prototypes.

Auto-Versioning Concept

A variation name represents the variation’s source code that when used in a fractal will always create the same output. The app, if it encounters the same variation name again, and that variation’s source code is materially different from the original source version, a new auto-versioned name will be assigned to the changed variation.

Variation Names Correspond to Actual Source Code

Variation names represent blocks of source code that implement the variation’s shape behavior.

Custom Variation’s Source Code Can Be Changed

Custom variations can be edited and changed (effectively this implies multiple versions of the same variation). If a custom variation has been used in several fractals, each having a different version of the custom variation, the variation name to variation source code contract is broken. If you however modify the name for each version, then the contract is maintained.

No Central Repository for Custom Variations

If two users on 2 different Macs create the same experimental named variation, it is unlikely that their variations will create the same shapes (unless they made the same identical source code changes). There is no mechanism for a user to even know about the other user’s experiments.

Auto-versioning is where a suffix is added to the name so that the changed name will be unique (against other variation names in the Factory + My libraries).

Automatic Import of Custom Variations From Flame Files

If you open a flame file that uses a custom variation and that custom variation is not part of My Library it will be automatically imported into My Library.

Automatic Variation Renaming

If you have a custom variation and you try to rename it to an existing factory or custom variation’s name, your new name will be auto-versioned to maintain uniqueness.

For example, take a brand new custom variation named “myCustomVariation” and rename it to julian. Its name will be changed to: julian_v1 by the app. It will create a new unique variation name not already in use by adding a version.

Auto-Versioning Scenarios

With custom variations, the user can change the actual C source code for a custom variation.

Say on May 1, they create a new custom variation and render some fractals with it and save the fractals to a file.

On June 1, they change the custom variation source code, create some fractals with the changed custom variation and save those fractals to a file.

On August 1, they open the older file. So which version of the custom variation source code is uses on August 1 by the app??

The app will detect that the custom variation’s version found in the app’s My Library has different source code from the version stored in the older file. It will auto-version the older version of the custom variation (so it has a new unique name), create a new dynamic variation set for the older flame file, and render that file with the older version of the custom variation. The fractal will render exactly the same as it did on May 1!!

The auto-versioned custom variation is also saved to the user’s MyLibrary
so they can use if for other fractals in the future.

If they then open the file saved on June 1, with the newer custom variation source code, the app will render that fractal with the newer source code version. It does not need to auto-version the newer version (as the name and source code in the file matches that
in the user’s MyLibrary).

If the user receives a file from another user with a custom variation in it that has the same name as a custom variation that they created (each user’s source code in this case for the exact same named custom variation is different).

When the app sees that the other user’s custom variation source code is different, it will auto-version the other user’s custom variation, create a new dynamic variation set, and render the other users’s fractals exactly as the other user saw them rendered !

There might be a little confusion with the new auto-versioned variation names, but more importantly, the app renders the fractal exactly the same as the other user saw on their Mac !

More Auto-versioning Scenarios

The problem is that it now detects that you modified the variation definition, but had used an earlier version in a fractal before. So it wants to rename the new variation definition to avoid two different versions with the same name.

The app has no way to figure out that you want one version over another one, so the best solution is to change the name to represent a different version.

Just think if it was possible for you to change the “julian” variation definition without renaming the changed version. That would have generate endless complaints saying that the renderer does not render Apophysis fractals correctly .. when you yourself changed how “julian” renders (and forgot you changed it).

There is no central Internet repository for user defined variations, so its possible that 2 different users could have different “julian” versions that have the same name, but are in fact different variation definitions. Then on opening a file with the 2nd user’s “julian_v1” by user 1; that will cause auto versioning to kick off and change the user 1’s julian variation name to “julian_v2”. The best way to resolve this would be for each user to add their own initials to the changed variation. For example, if your own name is John Doe, you could rename your “julian_v1” to “julian_jd”.

It is an ugly problem with no simple fix other than auto-versioning.