A Simple Scene Graph API for OpenGL.

## `class ssgEntity` - A Node in the Tree.

All nodes in the SSG scene graph are ssgEntities.

    clas ssgEntity : public ssgBase
    {
    public:

      ssgEntity (void) ;
      virtual ~ssgEntity (void) ;

      int  getTraversalMask     () ;
      void setTraversalMask     ( int t ) ;
      void setTraversalMaskBits ( int t ) ;
      void clrTraversalMaskBits ( int t ) ;

      virtual void recalcBSphere (void) ;
      int  isDirtyBSphere (void) ;
      void dirtyBSphere  () ;
      sgSphere *getBSphere () ;

      virtual int getNumKids (void) ;
      int getNumParents () ;
      ssgBranch *getParent ( int p ) ;
      ssgBranch *getNextParent () ;

      virtual void cull  ( sgFrustum *f, sgMat4 m, int test_needed ) ;
      virtual void isect ( sgSphere  *s, sgMat4 m, int test_needed ) ;
      virtual void hot   ( sgVec3     s, sgMat4 m, int test_needed ) ;
    } ;

### The tree structure.

Every entity has a list of parent entities and (conceptually), a list of child entities ("kids"). In practice, ssgRoot nodes never have parents and ssgLeaf nodes never have kids.

The structure of the scene graph permits the same node to be inserted into the graph in multiple locations. This is useful for saving space when the same object is needed many times in the scene. Hence, any given node may have more than one parent node.

You can traverse the list of parent nodes using `ssgEntity::getNumParents()` to find out the number of parents this node has and `ssgEntity::getParent(n)` to locate the n'th parent.

Alternatively, after calling getParent, you can call getNextParent to get the N+1'th parent node - it returns NULL when no more parents are available.

As a convenience for general tree-walking routines, there is a `ssgEntity::getNumKids()` call - which will always return zero on leaf nodes. You cannot actually get kid nodes unless the node is some kind of ssgBranch.

### Traversals

Much of the work done on an SSG scene graph entails 'traversing' the tree structure. This is done most commonly to display the scene using OpenGL - but is also done when doing intersection testing and other operations.

It's quite useful to be able to limit the traversal so that certain nodes do not get tested. This can save time - or prevent undesirable side-effects.

Each entity has a 'traveral mask' - which is a simple integer with one bit per kind of traversal. At present, there are three kinds of traversal:

    SSGTRAV_CULL   -- Culling to the field of view.
    SSGTRAV_ISECT  -- General intersection testing.
    SSGTRAV_HOT    -- Height-over-terrain testing.

You can directly set or get the traversal mask with `ssgEntity::setTraversalMask(m)` `ssgEntity::getTraversalMask()`. You can set an individual traversal bit using `ssgEntity::setTraversalMaskBits(m)` or clear one using `ssgEntity::clrTraversalMaskBits(m)`.

### Bounding Sphere

Quite a few graphics algorithms can be accellerated using a bounding sphere. The standard ssgEntity uses bounding spheres to do field-of-view and intersection testing.

Clearly one does not want to recompute the bounding sphere every frame - just some objects do change their size over time. Hence, the bounding sphere is lazily evaluated.

Whenever you do something to change the size or shape of an entity, you should call `ssgEntity::dirtyBSphere()`. This will mark this entity's sphere as invalid ("dirty") and also, walk backwards up the scene graph tree making all the nodes above this one dirty too. The next time SSG needs to know the bounding sphere size, it'll recompute it.

If you'd prefer for the bounding sphere recalculation to be done immediately, then you can call `ssgEntity::recalcBSphere()` and it will be done immediately. Branch nodes like ssgTransforms will automatically dirty their bounding spheres when necessary. Leaf nodes generally do not.

When anyone needs to know the bounding sphere size for a node, they'll call `ssgEntity::getBSphere()` - which will recaclulate the Bsphere if it needs to.

### Culling and Drawing

The actual tree-traversal, culling and rendering is handled by a virtual function `ssgEntity::cull()` - calling this on the root node in the scene graph causes the entire scene to be rendered in an efficient manner.

<= previous = | Return to SSG Index | = next =>