Coloring

This is a generic coloring class. Its purpose is to take a sequence of points and reduce it to either a gradient index or an exact color (precisely which is left up to the derived class).

For the most part, you will not use this formula directly. If you are migrating an existing coloring formula to a Coloring-derived class, you would normally choose to derive from either GradientColoring or DirectColoring. These sub- classes of Coloring automatically indicate whether they return an index or a color. In fact, other classes which use Coloring objects will likely specify which type of coloring they can be used with, so if at all possible, a class should be derived from one of these sub-classes rather than directly from Coloring.

The one exception is for those very, very few colorings that can behave as either a gradient coloring or a direct coloring.

 class Coloring(Generic) {
   ; Coloring base class.
   ; <p>
   ; This is a generic coloring class. Its purpose is to take
   ; a sequence of points and reduce it to either a gradient
   ; index or an exact color (precisely which is left up to
   ; the derived class).
   ; <p>
   ; For the most part, you will not use this formula directly.
   ; If you are migrating an existing coloring formula to a
   ; Coloring-derived class, you would normally choose to derive
   ; from either GradientColoring or DirectColoring. These sub-
   ; classes of Coloring automatically indicate whether they
   ; return an index or a color. In fact, other classes which
   ; use Coloring objects will likely specify which type of
   ; coloring they can be used with, so if at all possible, a
   ; class should be derived from one of these sub-classes
   ; rather than directly from Coloring.
   ; <p>
   ; The one exception is for those very, very few colorings
   ; that can behave as either a gradient coloring or a direct
   ; coloring.
   
 public:
   ; Constructor
   ;
   ; @param pparent a reference to the object creating the new object; typically, 'this'
   func Coloring(Generic pparent)
     Generic.Generic(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)
     ; Base class implementation just resets the iteration counter
     ; and clears the solid-color flag.
     m_Iterations = 0
     m_Solid = false
     m_Pixel = 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 just returns black.
     ; Every coloring class should override this function.
     return rgb(0,0,0)
   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 direct colors.
     return false
   endfunc
 
   ; Get saved value of pixel.
   ; <p>
   ; Sometimes it's useful for another object to be able to retrieve the
   ; value of ppixel that's been passed in during Init(). This provides
   ; that access.
   ;
   ; @return the value of ppixel from the Init() for this sequence
   complex func GetPixel()
     return m_Pixel
   endfunc
   
 protected:
   int m_Iterations    ; count the number of iterations
   bool m_Solid      ; flag indicating whether sequence was solid or not
   complex m_Pixel      ; saved value of pixel from Init()
 
 default:
   int param v_coloring
     caption = "Version (Coloring)"
     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_coloring < 100
   endparam
 }

Method Summary
`complex`	`GetPixel()` Get saved value of pixel.
`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

Constructor Summary
`Coloring()`
`Coloring(Generic pparent)` Constructor

common Class Coloring

Coloring

Coloring

Init

Iterate

Result

IsSolid

IsGradient

GetPixel

common
Class Coloring