This document provides class hierarchy information and documentation for Ultra Fractal 5 for those class files publicly available.

See:
Description

ULB Files

ck
common	Common Classes for Ultra Fractal 5
dmj5	dmj5.ulb 1.0 Base Classes for Ultra Fractal 5 by Damien M.
jlb
kcc5	kcc5.ulb 1.0 Classes for Ultra Fractal 5 by Ken Childress 24 June 2008
mmf	Classes by David Makin for Ultrafractal 5 and later. This version 10th December 2008. Minor improvements to exponential smoothing in Field Estimator. Added the Switch Magnet 2 formula. 6th December 2008. Added the Switch Magnet 1 formula. Added the "fix" to the Magnet 1 Distance Estimator. 29th November 2008 Fixed the default version in Field Estimator.
mt	Classes for Ultra Fractal 5 by Mark Townsend
reb	by Ron Barnett July 3, 2008 Ron's Website
rkb	rkb.ulb - Classes written by Robert K.
Standard	Standard.ulb implements the transformations, formulas and coloring algorithms from Standard.uxf/ufm/ucl as objects for the common.ulb framework.
tma

This document provides class hierarchy information and documentation for Ultra Fractal 5 for those class files publicly available.

Ultra Fractal Class Library Documentation 28 October 2008

Ultra Fractal Class Library Documentation

28 October 2008

This overview page also describes some important information for understanding this documentation and for documenting your class files for inclusion in this documentation.

• Important Links - Important Ultra Fractal links.
• Object Tutorials - User and programmer object tutorials.
• Ultra Fractal 5 Tutorials & Challenges - Ultra Fractal 5 specific tutorials and challenges applying the information in the tutorials.
• Ultra Fractal Class Libraries - A brief description of class library files.
• Class File Usage - A brief description of class file usage.
• Documentation Notes - A description of this documentation and how it is generated.
• Class File Mapping - A description of how Ultra Fractal class files (.ULB) map to this documentation.
• Class Naming Conventions - A description of class file naming conventions.
• Class File Documentation Conventions - A description of recommended conventions to use in documenting class files for inclusion in this document.

Important Links

Important Links

Ultra Fractal Home

Ultra Fractal Formula Database

Documentation Notes

Class File Mapping

Class Naming Conventions

Class File Documentation Conventions

Downloadable Class File Documentation

Class Examples and Tutorials

Object Tutorials

Object Tutorials

Damien Jones has written two very important tutorials on the new object framework of Ultra Fractal 5. The first is geared towards normal users, or those users who are not really interested in the details of formula writing.

Introduction to Objects - Users Version

The second one is intended for those interested in writing formulas using the object features of Ultra Fractal 5. It is a brief, detailed introduction to objects and the object features contained in Ultra Fractal 5.

Introduction to Objects - Programmers Version

Ultra Fractal 5 Tutorials & Challenges

Tutorials

Ron Barnett has written a collection of tutorials to aid users in learning the new plugin features of UF5. Plugins are classes written using the new object oriented features of the UF5 formula language. From the user point of view, they can be viewed as plugins because many different classes can be used in any given slot in a particular formula.

• The Basics of UltraFractal 5 and Its Use of Classes
• Changing and Exploring Plug-ins
• Transforms as Plug-ins
• Application of Texture
• Advanced Topics in Applying Textures
• Using Slope/Lighting formulas
• Using Trap Transfer Bias for Texturing
• MMF Smooth Orbit Traps
• All About Images - Part 1
• Switching and Switch Formula Classes

Ron has also designed a series of challenges to help users apply the techniques described in the tutorials.

• Challenge #1 - Plug and Play
• Challenge #2 - All Wrapped Up
• Challenge #3 - Transformed
• Challenge #4 - All About Textures
• Challenge #5 - Advanced Texture
• Challenge #6 - Slope/Lighting
• Challenge #7 - Texturing Tools
• Challenge #8 - MMF Smooth Orbit Traps Challenge
• Challenge #9 - Importing Images

Additional tutorials and examples can be found here.

Ultra Fractal Class Libraries

Ultra Fractal Class Libraries

Ultra Fractal 5 provides extensions to its formula language that allow the formula writer to define classes and functions. This provides the ability to place commonly used code in class library files (.ulb extension) so that others may reuse the code instead of copying or rewriting it.

Ultra Fractal 5 is delivered with a set of base classes that are designed to be used as building blocks for other formulas. These are located in the common.ulb class file. The formulas in the Standard.ufm and Standard.ucl files have been rewritten using classes. These can be found in Standard.ulb.

Several formula authors have written classes and re-written formulas to use classes. These can be found in the files,

• dmj5.ufm
• dmj5.ucl
• dmj5.ulb
• kcc5.ulb
• mmf5.ufm
• mmf5.ucl
• mmf.ulb
• mt5.ucl
• mt.ulb
• reb5.ufm
• reb5.ucl
• reb.ulb
• tma.ulb

Additional class files will be added to this documentation as more class files are created and uploaded to the formula database. Additional formula files specific to Ultra Fractal 5 will be added to the formula database as authors write new formulas to take advantage of the new class features.

Class File Usage

Class File Usage

The introduction of classes to the Ultra Fractal formula language is one of the most significant enhancements to its capabilities. This capability literally opens up a whole new universe of possiblities for formula writers. Now, instead of copying a formula, making additions and enhancements, and publishing a new formula, authors can use classes written by others as building blocks to create new formulas. By creating a new class that is based on a previous class, authors can add new capabilities without having to copy an existing formula. The Standard.ulb file contains class versions of the formulas contained in the Standard.ufm and Standard.ucl files. The common.ulb file contains classes that are intended to be used as base classes for extension by class files created by anyone. These classes are intended to provide a standard framework by which others can extend the classes and maximize compatibility. Class file creators are not required to follow this framework, but doing so will maximum compatibility with other formulas and classes.

Documentation Notes

Documentation Notes

This documentation is produced using the javadoc documentation tool for Java class files. A customized version of the javadoc tool is used to make the output less Java-like and more UF-like. A customized tool written by Ken Childress is used to parse the .ulb class files and produce Java class files that the javadoc tool then parses to create this documentation. Formula authors wishing to have their publicly available class files included in this documentation should first follow the documentation conventions listed below, then contact Ken Childress to include the class files in the documentation. Please notify Ken when you upload changes to your class file to the formula database that need to be reflected in this documentation.

Since the documentation is generated with a tool designed to document Java code, there will be a few cases where the UF syntax doesn't exactly show in the documentation. A primary example is parameters that are passed by reference. In the UF code, these parameters are prefaced by the '&' character. There is no corresponding Java syntax, thus the function documentation when this is used will not be properly reflected. One should inspect the UF code listing in the class documentation for the correct parameter passing mode.

There may also be a few minor "Javaisms". These would be syntax or conventions that are appropriate for Java, but perhaps not for the UF formula language. As many of these as possible have been removed, or changed to be more UF-like.

Class File Mapping

Class File Mapping

The publicly downloadable class library files (*.ulb) are contained in the Ultra Fractal Formula Database. The naming follows the same convention as the formula files, with the author's initials forming the base name of the file. In this documentation, the ULB File names correspond to the .ulb files containing the classes. Some examples,

ULB File	Class File	Author
common	common.ulb	Common base classes
dmj5	dmj5.ulb	Classes written by Damien M. Jones
jlb	jlb.ulb	Classes written by Jim Blue
kcc5	kcc5.ulb	Classes written by Ken Childress
mmf	mmf.ulb	Classes written by Dave Makin
mt	mt.ulb	Classes written by Mark Townsend
reb	reb.ulb	Classes written by Ron Barnett
tma	tma.ulb	Classes written by Toby Marshall

Class Naming Conventions

Class Naming Conventions

In order to more easily tell in which file a particular class is located, it is very strongly encouraged that you prefix your classes with your formula file identifier in upper case. This eliminates naming conflicts and allows the user to more easily tell which .ULB file in which to find the class. By convention, class names begin with a capital letter.

The primary exception to this rule are the classes contained in common.ulb. By convention, there is no prefix on these class names as they are intended to be extended by user created classes.

TrapShape = Trap Shape class located in common.ulb

DMJ_Clipping = Clipping class located in dmj5.ulb

KCC_TangentBallsTrap = Tangent Balls Trap class located in kcc5.ulb

Class File Documentation Conventions

Class File Documentation Conventions

To make the automatic generation of the UF class documentation files run smoothly, the following documentation conventions are suggested. They are not mandatory, but if they are not followed, the documentation will not be as useful as when they are followed.

• To make long comments more readible, HTML tags may be placed in the text. Tags such as <b>bold</b>, <u>underline</u>, <br> to force line breaks, <p> to deliniate paragraphs can be used.
  
  
• The automatic documentation tools allow for the creation of a class file specific description. This description will occur on the main page of a particular class file. This corresponds to a UF "comment { ... }" block at the beginning of the class file. This block should be first in the class file and look something like the following:

  comment {
    kcc5.ulb 1.0 <br>
    Classes for Ultra Fractal 5 <br>
    by Ken Childress <br>
    24 June 2008 <br>
    <p>
    This is my collection of classes.  This collection
    consists of class versions of the Carlson Orbit Traps
    types, Plane Curve Trap types, and the coloring maps
    included in those formulas.  The older versions of the
    formulas work perfectly fine in UF5.  These classes
    were written to allow the trap types to work in the new
    UF 5 class hierarchy.  This provides much more flexibility
    than could be obtained by the previous versions.
    <p>
    The classes contained here are class implementations
    of the following coloring formulas from kcc3.ucl.
    <ul>
    <li><strong>Carlson Orbit Traps<</strong> - These are
    the 3D coloring shapes originally created by Paul
    Carson.
    <li><strong>Plane Curve Traps</strong> - These are the
    traps shapes contained in the Plane Curve Traps UCL found
    in kcc3.ucl.
    <li><strong>Color Map Classes</strong> - These are the
    color maps implemented as classes to provide the same
    3D colorings as Paul Carlson's original formulas.
    </ul>
  }
  

  The first sentence of the comment should be a brief description of the class file. This short description will appear in the summary of class files that appears on the main index page of the documentation.

  HTML tags may be used to format this description block as desired when the documentation is generated.
  

• Comments describing the function of the class must be the comments immediately following the class declaration and before the first public, private, or protected section.
  

  class DMJ_PolyCurveSelector(common.ulb:Generic) {
          ; PolyCurve Selector abstract base class.
          ; <p>
          ; When writing a formula which uses PolyCurve objects, it is
          ; usually necessary to allow the user to select the actual
          ; curve shape (unless it is going to be synthetically created).
          ; In that case, you can include a DMJ_PolyCurveSelector object
          ; and allow the user to choose any of the available curve
          ; selection mechanisms. You may also want to allow them to use
          ; DMJ_PolyCurveTransform objects, but that is up to you.
          
  public:
  

• The first sentence of the class comment should be a brief summary of the function of the class. This summary will appear in the table of classes that is generated for each class file.
  
  
• While it is optional for UF, the "public:" section keyword should not be omitted. This helps ensure the documenter program correctly identifies the class comment.
  
  
• In order to make sure that function comments are processed correctly, it is suggested that if you comment variable declarations, that you place them after the functions for a particular "public:", "private:", or "protected:" section. Uncommented variables placed elsewhere in the section won't have any effect on the generated documentation.
  
  
• Function comments are the comments that immediately precede the function code.

          ; set parameters for a segment
          ; note: do not manually specify a close point; use the
          ; auto-close flag instead. Otherwise, your shape may not
          ; render correctly (it will "leak").
          ; @param ppoint slot number (use -1 for next slot)
          ; @param ptype segment type: 
          ;    0 = none (close), 
          ;    1 = linear, 
          ;    2 = quadratic (use pcontrol1), 
          ;    3 = cubic (use pcontrol1 and 2)
          ; @param pauto auto-compute controls: 
          ;    1 = close, 
          ;    2 = smooth, 
          ;    4 = curvature smooth
          ; @param panchor anchor point
          ; @param pcontrol1 control point 1
          ; @param pcontrol2 control point 2
          func SetSegment(int ppoint, int ptype, int pauto, complex panchor, complex pcontrol1, complex pcontrol2)
                  if (ppoint == -1)
                          ppoint = m_AnchorNext
                          m_AnchorNext = m_AnchorNext + 1
                  endif
                  if (ppoint > m_AnchorHighest)
                          m_AnchorHighest = ppoint
                  endif
  
                  print("segment ", ppoint, ": type ", ptype, " auto ", pauto, " ", panchor, " ", pcontrol1, " ", pcontrol2)
  
                  m_Anchors[ppoint] = panchor
                  m_Control1[ppoint] = pcontrol1
                  m_Control2[ppoint] = pcontrol2
                  m_Types[ppoint] = ptype
                  m_Auto[ppoint] = pauto
          endfunc
  

• The first sentence of the function comment should be a brief summary of the function. This summary will appear in the table of functions that is generated for each class.
  
  
• To document parameters, use the @param tag. The format of this tag is
  
  @param parameter_name parameter_description
  

  parameter_name should simply be the name of the parameter without any additional characters or punctuation. For example, just write "@param ppoint [description]" rather than "@param ppoint," or "@param ppoint:", or "@param ppoint=", etc.
  

• If the function returns a value, use the @return tag after any @param tags.
  
  @return description_of_the_return_value
  
  
• The UF formula language is not case sensitive, but the program that produces this documentation is. Therefore, it will aid in automatic generation of this documentation if formula authors would follow the following conventions.
  
  • For classes used from other files, use the same case for the class name as in the imported file. For example, use "common.ulb:TrapShapeBlock" rather than "common.ulb:trapshapeblock".
  • Use the same case for importing class files, as the file exists in the file system, e.g. import "common.ulb", rather than import "Common.ulb".
  • If including the standard class file, write the include statement as include "Standard.ulb".
  • For class declarations, use "class" rather than "Class" or "CLASS".
  • Begin class declarations at the beginning of a line without any leading whitespace
  
  
• The UF source code for each class is included in the Description section of each class. Therefore, it is recommended that the author make judicious use of comments to explain the logic of the code. This will greatly aid others in understanding the class in the event they wish to reuse or extend the class.