Introduction to Objects
Users Version

Damien M. Jones

"This way to the revolution..."

From a user's perspective, Ultra Fractal 5 offers a few new features that make life easier. It seems very evolutionary, a continued refinement of an already excellent product. A thumbnail browser, layer groups, linked layers, image importing. Very good things, but they don't seem earth-shattering--perhaps a minor earthquake, but certainly not anything that will make California fall into the ocean.

This appearance is quite deceptive. Under the hood, UF5 packs a MAJOR foundational change in the way fractal formulas are written, a change that will--once mastered by users--break down constraining walls that many fractal artists didn't even know were there.

I'm talking about objects and classes, which at first seem like they are only of interest to those who write the formulas everyone uses. While it's true that formula writers in particular have the most to gain from this new feature, UF5 actually makes objects accessible to users. As a user, you need to know why objects are a good idea and what kinds of things objects will let you do.

Over the past year the UF beta testers have been banging on the new object compiler to help make sure it is solid. We've also been writing a lot of formula code to take advantage of the new compiler; when you update your UF5 formulas you'll find a slew of new toys. This brief introduction is to help you begin exploring. If you want to start programming for the new compiler, read the related "Programmers Version".

I want to stress here that all your old formulas will continue to work, just the same way that they did before. UF5 does not break them. But if you only continue to use your old formulas, you will be missing out on some amazing new tools.


With UF4, we have three types of formula: transformations, fractal formulas, and colorings. Each of these goes in a particular "slot" in the Layer Properties tool window. For each layer, you can have any number of transformations, one fractal formula, one inside coloring, and one outside coloring.

A "class" is just a type of formula. With UF4 we had only the three basic formula types. Each formula was a single, big piece. With UF5, formula writers can create their own formula types, but more than that, they can take what used to be a single, big, unbreakable piece, and split it into many smaller pieces that work together. This allows new pieces to be written easily to fit into the new slot types (and even written by people other than the original author).

An "object" is just a particular selection of a class along with its parameters. For example, when you copy just the inside coloring of a fractal, you are copying the type of coloring used and the parameters for that particular image's use of that coloring. Most of the time, the difference between a class and an object is not important.

With UF4, the program helps you select the right formula for each type of slot by only showing you formulas that match the type. With UF5, nothing has changed except that now you have a lot more types available. You still have access to all your old formulas, but now you also have access to new formula classes. These are stored in new .ulb (Ultra Fractal Library) files.


When we (as beta testers) began writing classes for UF5, we started by carefully looking at how our formulas were written. Classes allow us to take one big formula and break it into small pieces; to do that effectively, we had to decide where the right places to break it apart were.

As an example, consider the OrbitTraps formula in dmj3.ucl. This allows the user to choose trap shape(s), trap mode, trap coloring, texturing, distortions, lots of things. All of these knobs all collected together can be overwhelming. So many of these have been pulled out and put into their own classes. We now have a TrapShape class; all of the old trap shapes have been rewritten as classes. Instead of choosing the trap shape from a drop-down list, you now choose a TrapShape class using the formula browser. Why is this better? Because now you can use trap shapes written by ANY formula author, whether it's me (Damien Jones) or Ron Barnett or Ken Childress or Toby Marshall or Mark Townsend, as long as it's written to be a TrapShape object.

This means that even if you're experienced with Ultra Fractal, and very familiar with certain formulas, you may find new class-based formulas very different. I urge you to experiment anyway, because the flexibility classes offer is worth the effort in learning to use them. Class-based formulas are often set up differently from the old-method formulas.

As an example, consider the TrapShape. A formula which needs to use a trap shape creates a TrapShape slot; the user (that's you) chooses a TrapShape class to go in the slot. But my old OrbitTraps formula lets you choose up to three trap shapes; how do you do that when you only have one TrapShape slot?

The answer is a "Merge" class. "Merge" classes are designed to let you fit multiples of a class type into a single slot. So you use a TrapShapeMerge class, and now you can fit up to ten TrapShape classes. Think of a "Merge" class as being like the electrical outlet adapters that let you plug three things into a single electrical socket. There are "Merge" classes for many different types of slots. And if you find that the ten new slots the Merge class gives you aren't enough, you can put a Merge class into one of the new slots, and get ten more.


Many of the old formulas have been converted to new, class-based versions. This doesn't just mean they now USE classes; in most cases, it means they ARE objects. With UF5, there are actual classes for Transform, Formula, and Coloring. This means that some classes may actually use complete transformation formulas (in the form of Transform classes) inside their calculation.

Here's another example from (obviously) OrbitTraps. The old version of this coloring allowed you to position trap shapes, rotate and stretch them, tile them, and distort them with fBm texture. These groups of effects (position/rotate/stretch, tiling, distorting) are now Transform classes, and you can use them with each TrapShape. Or you can use ANY OTHER Transform. Do you want to make your TrapShape have a mosaic tile look? Use the Mosaic Transform class. Do you want to apply a wave to your trap shape? Use the LinearWave Transform class. Do you want to do both of these, and still use trap tiling and positioning? Use the TransformMerge class to squeeze all those Transforms into a single Transform slot.

There are more possibilities, too. You can use any Formula and Coloring classes together as a ColorTrap class, for use with DirectTraps (the direct-coloring version of GradientTraps, which is the new OrbitTraps). You can use a Slope class, which turns any Formula into a slope variant for use with a Lighting coloring.

We've barely scratched the surface of what's possible. We can now mix and match our code pieces together as we like. And the best part is, as a user, you STILL don't have to know about the math under the hood. All you need to do is choose classes to go into slots--and UF5 makes it easy, because it only shows you the classes that will fit.


All this ability to fit pieces together is a result of UF5's new class- based compiler, that little thing that seemed unimportant unless you were a programmer. And helping to make sure programmers are using the same kinds of slots (so a Formula from one author will work in a Formula slot used by another author) is what the common library, the common.ulb file, is for.

The contents of this file are the result of collaboration between the UF beta testers and Frederik Slijkerman. Because it is part of the formula database, it's possible for us to update it separately from the Ultra Fractal software itself. However, we will do so very carefully, as any errors on our part would potentially ruin every image based on the common classes.

We have done our best to include all the necessary components. There will most likely be more to add. Just in case you thought you didn't have enough toys already...