

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
Object common:Generic common:Formula
class
Formula base class.
This is a generic formula class. Its purpose is to take an arbitrary initial point and produce a sequence of points of indeterminate length. This roughly corresponds to UF's native fractal formula type. The advantage to writing a fractal formula as a class is that it can then be used in many other places. Formula classes also support the notion of "bailed out", as a way of indicating when the sequence of values is finished.
If you are migrating an existing fractal formula to a Formuladerived 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 bailout: test into the IsBailedOut() function (but be sure it returns the logically opposite value; see the explanation on IsBailedOut()).
If you have complicated bailout testing, you may instead put that code into your Iterate() function and save the result in the m_BailedOut variable and omit implementing IsBailedOut(). If you do this, remember to set m_BailedOut to false in your Init() function, as the base class implementation sets it to true to end iterating right away.
Note that if you are creating a formula whose outside points
escape towards infinity, you should derive from DivergentFormula
as it will automatically include a bailout parameter and make
that accessible to other objects. Similarly, if your formula
is convergent, you should derive from ConvergentFormula. If
your formula has both kinds of outside points, derive from
ConvergentDivergentFormula. Otherwise, you will have to write
your bailout test yourself.
class Formula(Generic) { ; Formula base class. ; <p> ; This is a generic formula class. Its purpose is to take ; an arbitrary initial point and produce a sequence of ; points of indeterminate length. This roughly corresponds ; to UF's native fractal formula type. The advantage to ; writing a fractal formula as a class is that it can then ; be used in many other places. Formula classes also ; support the notion of "bailed out", as a way of indicating ; when the sequence of values is finished. ; <p> ; If you are migrating an existing fractal formula to a ; Formuladerived 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 bailout: test into ; the IsBailedOut() function (but be sure it returns the logically ; opposite value; see the explanation on IsBailedOut()). ; <p> ; If you have complicated bailout testing, you may instead put ; that code into your Iterate() function and save the result in ; the m_BailedOut variable and omit implementing IsBailedOut(). ; If you do this, remember to set m_BailedOut to false in your ; Init() function, as the base class implementation sets it to ; true to end iterating right away. ; <p> ; Note that if you are creating a formula whose outside points ; escape towards infinity, you should derive from DivergentFormula ; as it will automatically include a bailout parameter and make ; that accessible to other objects. Similarly, if your formula ; is convergent, you should derive from ConvergentFormula. If ; your formula has both kinds of outside points, derive from ; ConvergentDivergentFormula. Otherwise, you will have to write ; your bailout test yourself. public: ; Constructor ; ; @param pparent a reference to the object creating the new object; typically, 'this' func Formula(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 seed value for the sequence; for a normal fractal formula, this will be #pixel ; @return first value in the sequence; this corresponds to #z in a fractal formula complex func Init(complex pz) ; Base class implementation flags the sequence to end ; immediately. As long as you provide your own implementation ; of IsBailedOut(), this is irrelevant. We also clear the ; iteration counter. m_Iterations = 0 m_BailedOut = true return pz endfunc ; Produce 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. ; ; @param pz previous value in the sequence; corresponds to #z in a fractal formula. Note that you should always use this value for computing the next iteration, rather than a saved value, as the calling code may modify the returned value before passing it back to the next Iterate() call. ; @return the next value in the sequence complex func Iterate(complex pz) ; Base class implentation automatically updates the ; iteration counter and returns an unmodified pz ; (that is, the default sequence is the same value ; repeated infinitely). m_Iterations = m_Iterations + 1 return pz endfunc ; Test whether the formula has bailed out (i.e. the sequence is complete) ; <p> ; This is typically called once per iteration to test whether ; the sequence has completed. If producing this result is ; difficult to do separately from the Iterate() processing, ; you should produce the result in Iterate() and set the ; m_BailedOut flag appropriately, and leave IsBailedOut() ; unimplemented in your class to inherit this behavior. ; <p> ; Note that this test is the OPPOSITE sense of the bailout: ; section in UF's fractal formulas. A bailout: section ; returns TRUE to continue iterating. IsBailedOut() must ; return FALSE to continue iterating. ; ; @param pz last sequence value to test; this should be the value returned from the previous Iterate() call. Note that it is acceptable to ignore pz and use m_BailedOut, but any code calling IsBailedOut() should pass in the correct pz for Formula classes which do not use m_BailedOut. ; @return true if the sequence has bailed out (i.e. should be terminated) bool func IsBailedOut(complex pz) return m_BailedOut endfunc ; Determine the primary exponent. ; <p> ; Many fractals can be characterized by an exponent value that ; is useful to other formulas, so we provide that here. If ; your formula does not need or use this value, override the ; p_power parameter and make it hidden. ; ; @return the primary exponent parameter complex func GetPrimaryExponent() return @p_power endfunc ; Determine the upper bailout boundary. ; <p> ; By default, we return a simple fixed value. Divergent ; formulas will override this function and return the ; real parameter. ; ; @return the upper bailout parameter float func GetUpperBailout() return 256 endfunc ; Determine the lower bailout boundary. ; <p> ; By default, we return a simple fixed value. Convergent ; formulas will override this function and return the ; real parameter. ; ; @return the lower bailout parameter float func GetLowerBailout() return 0 endfunc protected: int m_Iterations ; count the number of iterations bool m_BailedOut ; flag indicating whether sequence has bailed out or not default: int param v_formula caption = "Version (Formula)" 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_formula < 100 endparam complex param p_power caption = "Exponent" default = (2,0) hint = "Defines the primary exponent for the fractal." endparam }
Constructor Summary  

Formula()


Formula(Generic pparent)
Constructor 
Method Summary  

float 
GetLowerBailout()
Determine the lower bailout boundary. 
complex 
GetPrimaryExponent()
Determine the primary exponent. 
float 
GetUpperBailout()
Determine the upper bailout boundary. 
complex 
Init(complex pz)
Set up for a sequence of values 
boolean 
IsBailedOut(complex pz)
Test whether the formula has bailed out (i.e. 
complex 
Iterate(complex pz)
Produce the next value in the sequence 
Methods inherited from class common:Generic 

GetParent 
Methods inherited from class Object 


Constructor Detail 

public Formula(Generic pparent)
pparent
 a reference to the object creating the new object; typically, 'this'public Formula()
Method Detail 

public complex Init(complex pz)
This function will be called at the beginning of each sequence of values (e.g. at the beginning of each fractal orbit).
pz
 seed value for the sequence; for a normal fractal formula, this will be #pixel
public complex Iterate(complex pz)
As long as the sequence has not bailed out, this function will be continually called to produce sequence values.
pz
 previous value in the sequence; corresponds to #z in a fractal formula. Note that you should always use this value for computing the next iteration, rather than a saved value, as the calling code may modify the returned value before passing it back to the next Iterate() call.
public boolean IsBailedOut(complex pz)
This is typically called once per iteration to test whether the sequence has completed. If producing this result is difficult to do separately from the Iterate() processing, you should produce the result in Iterate() and set the m_BailedOut flag appropriately, and leave IsBailedOut() unimplemented in your class to inherit this behavior.
Note that this test is the OPPOSITE sense of the bailout: section in UF's fractal formulas. A bailout: section returns TRUE to continue iterating. IsBailedOut() must return FALSE to continue iterating.
pz
 last sequence value to test; this should be the value returned from the previous Iterate() call. Note that it is acceptable to ignore pz and use m_BailedOut, but any code calling IsBailedOut() should pass in the correct pz for Formula classes which do not use m_BailedOut.
public complex GetPrimaryExponent()
Many fractals can be characterized by an exponent value that is useful to other formulas, so we provide that here. If your formula does not need or use this value, override the p_power parameter and make it hidden.
public float GetUpperBailout()
By default, we return a simple fixed value. Divergent formulas will override this function and return the real parameter.
public float GetLowerBailout()
By default, we return a simple fixed value. Convergent formulas will override this function and return the real parameter.


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 