GradientColoring

This is a generic coloring class. Its purpose is to take a sequence of points and reduce it to a gradient index. This gradient index can then be assigned to #index or used with the gradient() function or in any other fashion.

If you are migrating an existing coloring formula to a Coloring-derived class, the process is fairly straightforward. Any variables you set in your global: section that are used elsewhere in your formula should be declared in your protected: section. Move the code from your global: section into the constructor. Move the code from your init: section into the Init() function. Move the code from your loop: section into the Iterate() function. Move the code from your final: section into the Result() function.

 class GradientColoring(Coloring) {
   ; Gradient-based Coloring base class.
   ; <p>
   ; This is a generic coloring class. Its purpose is to take
   ; a sequence of points and reduce it to a gradient index.
   ; This gradient index can then be assigned to #index or
   ; used with the gradient() function or in any other fashion.
   ; <p>
   ; If you are migrating an existing coloring formula to a
   ; Coloring-derived class, the process is fairly straightforward.
   ; Any variables you set in your global: section that are used
   ; elsewhere in your formula should be declared in your protected:
   ; section. Move the code from your global: section into the
   ; constructor. Move the code from your init: section into the
   ; Init() function. Move the code from your loop: section into the
   ; Iterate() function. Move the code from your final: section
   ; into the Result() function.
   
 public:
   ; Constructor
   ;
   ; @param pparent a reference to the object creating the new object; typically, 'this'
   func GradientColoring(Generic pparent)
     Coloring.Coloring(pparent)
   endfunc
   
   ; Set up for a sequence of values
   ; <p>
   ; This function will be called at the beginning of each
   ; sequence of values (e.g. at the beginning of each fractal
   ; orbit).
   ;
   ; @param pz first value for the sequence; for a normal coloring formula, this will be #z
   ; @param ppixel seed value for the sequence; for a normal coloring formula, this will be #pixel
   func Init(complex pz, complex ppixel)
     Coloring.Init(pz, ppixel)
   endfunc
   
   ; Process the next value in the sequence
   ; <p>
   ; As long as the sequence has not bailed out, this function
   ; will be continually called to produce sequence values. Note
   ; that such processing generally will not know in advance
   ; precisely how long the sequence is, and should be prepared
   ; to deal with sequences of arbitrary length.
   ; <p>
   ; Your coloring may determine at some point that a solid color
   ; should be used rather than an index value.
   ;
   ; @param pz next value in the sequence; corresponds to #z in a coloring formula
   func Iterate(complex pz)
     ; Base class implementation only updates the iteration counter.
     ; Some colorings may not need to do per-iteration updates, but
     ; if their coloring depends on the final sequence value, they
     ; will need to save pz in a member variable so it can be used
     ; in the Result() function.
     m_Iterations = m_Iterations + 1
   endfunc
   
   ; Produce a resulting color index after a sequence is finished
   ; <p>
   ; This corresponds to the final: section in a coloring formula.
   ; Once it is called, no further calls to Iterate() should be
   ; made without calling Init() first.
   ;
   ; @return the color (corresponding to #color in a coloring formula)
   color func Result(complex pz)
     ; Base class implementation looks the color up in the gradient.
     ; Gradient-based coloring does not need to override this
     ; function unless different behavior when used as a direct
     ; coloring is required.
     return gradient(ResultIndex(pz))
   endfunc
 
   ; Produce a resulting color index after a sequence is finished
   ; <p>
   ; This corresponds to the final: section in a coloring formula.
   ; Once it is called, no further calls to Iterate() should be
   ; made without calling Init() first.
   ;
   ; @return the gradient index (corresponding to #index in a coloring formula)
   float func ResultIndex(complex pz)
     ; Base class implementation just returns the iteration counter.
     ; Every coloring class should override this function.
     return m_Iterations
   endfunc
 
   ; Test whether the sequence produced a solid-color value rather than an index. 
   ; <p>
   ; This test is usually fairly complex and should be done as part of
   ; Iterate() or Result(), with the result saved in m_Solid. This function
   ; can then be left as the base class implementation, which just returns
   ; the value of that flag.
   ;
   ; @return whether the sequence produced a solid-color value
   bool func IsSolid()
     return m_Solid
   endfunc
   
   ; Test whether the formula produces gradient colors or direct colors.
   ; <p>
   ; Note: this MUST NOT change over the lifetime of the object; other
   ; objects will call this and alter their behavior because of it, and
   ; it must give the same result regardless of the sequence. The only
   ; factors that should influence the return value of this function are
   ; parameters that the user has selected.
   ;
   ; @return whether the class provides gradient colors (true) or direct colors (false)
   bool func IsGradient()
     ; Base class implementation always declares itself as returning gradient colors.
     return true
   endfunc
   
 protected:
 
 default:
   int param v_gradientcoloring
     caption = "Version (GradientColoring)"
     default = 100
     hint = "This version parameter is used to detect when a change has been made to the formula that is incompatible with the previous version. When that happens, this field will reflect the old version number to alert you to the fact that an alternate rendering is being used."
     visible = @v_gradientcoloring < 100
   endparam
 }

Method Summary
`void`	`Init(complex pz, complex ppixel)` Set up for a sequence of values
`boolean`	`IsGradient()` Test whether the formula produces gradient colors or direct colors.
`boolean`	`IsSolid()` Test whether the sequence produced a solid-color value rather than an index.
`void`	`Iterate(complex pz)` Process the next value in the sequence
`color`	`Result(complex pz)` Produce a resulting color index after a sequence is finished
`float`	`ResultIndex(complex pz)` Produce a resulting color index after a sequence is finished

Constructor Summary
`GradientColoring()`
`GradientColoring(Generic pparent)` Constructor

common Class GradientColoring

GradientColoring

GradientColoring

Init

Iterate

Result

ResultIndex

IsSolid

IsGradient

common
Class GradientColoring