zsystem-t2/ZSystem.txt

ZSYSTEMS
--------



Fractal universe generation system



Terms
-

The SEED of an object is a random seed which is used to create
pseudo-random numbers.

A PARAM is a named piece of data.

The PARAMLIST of an object is a set of named pieces of data.

The INDEX of an object is it's position in it's parent's list
of objects.

The ADDRESS of an object is a string of INDEXes.  This uniquely
defines it and it's PARAMLIST - object can be generated from
this information.

An OBJECT is stored as a pointer to it's object function.

An OBJECTLIST is a list of OBJECTs each with their own
PARAMLIST.

The CACHE is a set of OBJECTLISTs stored against their
ADDRESSes.  The cache is a fixed size and a least recently
used scheme will probably be used to expire entries when space
is needed.

An object function creates a set of subobjects from it's SEED
and PARAMs.  This set is cached using the ADDRESS as a key and
the object function is only called again if that entry has been
removed from the cache.

The ZSYSTEM object which is passed around to all functions
contains global state information for the system like the CACHE
and the universal OBJECT. (Each ZYSTEM has it's own cache -
it's not global to the program)



The cache
-

Cache operation:
  Given an ADDRESS returns an OBJECTLIST if one is stored for that ADDRESS
  Can add an OBJECTLIST for a given ADDRESS



Object functions
-

An object function creates an OBEJCTLIST from a PARAMLIST and a SEED.
This is then cached against the ADDRESS of that object.  If the
OBJECTLIST is already cached then the object function does not need to
be called.  If a function does not produce an object list then

At the lowest level objects give way to primitives.  How does this work?



ZSystem code
-

There is a lot of global state (which is passed around as a ZSYSTEM
object)

You create a ZSystem with a specific entrypoint which is a universe
object function.  And then you can render this universe from any
viewpoint.



ZSystem data
-

A ZSystem object has associated with it some dynamic data:

Cache - stores subobjects and parameters so they don't need to be
        recalculated.
Params - Parameters for the current object function
Seed - Current random seed



ZSystem state
-

An object function 



ZREGION



void MySubObject(ZSYSTEM zs)
{

}



void MyObject(ZSYSTEM zs)
{
  ZREGION *r = ZsGetParam("region");

  ZSystem_Param(zs, "colour", 0xFF6699);
  ZSystem_Param(zs, "shape",  5);

  ZsObject(zs, MySubObject);

  ZSystem_Begin(zs, ZSubObject);
    ZSystem_Param(zs, "region", r2);
  ZSystem_End(zs);

  // ...
}