Wiki

Clone wiki

gengine / SceneManager_API

Scene objects and scene management

Structure

Current approach to the scene management (the one which is currently used) is the common for the retained rendering.

Scene is defined as the hierarchical tree of the scene elements which defines their parent to child relation in terms of the spatial frame. Each child inherit visibility and reference spatial frame of the parent.

Scene tree plays several roles:

  • Spatial hierarchy
  • Scene object periodic updates (animations or anything like that)
  • Scene culling wrt. camera frustum

SceneGraph

Scene graph manages the forest of the scene trees, their lifetimes and updates. It doesn't know anything about hierarchy and the scene itself or spatial coordinates. The basic element of the scene is Element class which can be culled and drawn.

// Construct a new scene and optionally attach update task object.
SceneGraph(ModifierUpdateTask* task)

// Tests whether scene graph contains any elements
BOOL IsEmpty() const

// Add another scene/graph to this scene graph
// All the root nodes will be updated
void AddScene( Element* scene );

// Remove the scene supplied from the scene graph
// Returns false if scene does not exists
BOOL UnlinkScene( Element* scene );

// Delete the element supplied by the first adding it to
// the death row ( as a stay execution ). This will be
// deleted at the end of update cycle then death row is purged.
// This is done to avoid deleting objects that might
// be referenced to later in the update cycle.
void DelayedDelete( Element* elem );

// Purge and delete all elements on death row
void PurgeDeathRow();

// Update all scene graph using the time
// increment supplied
void Update( FLOAT dt );

// Get/set the global ambient color
const Color& GetAmbient();
void SetAmbient( const Color& clr );

// Get the current modifier task
ModifierUpdateTask* GetModifierTask();

// Set the current modifier task. If a task already exists,
// destroy it. 
// NOTE: This does not copy over any existing task - intended for
// initial creation only.
void SetModifierTask( ModifierUpdateTask* task );

Element

Element is the basic parts managed by the SceneGraph. Naturally they don't have any spatial information (Element might be as well a global enironmental part of the scene. Like a background.) But the only part the Element is responsible for is the rendering process. As such it exposes two parts of its interface - culling and rendering.

The culling interface is exposed in form of the culled flag which means that the graphics represented by the element is not visible. The workhorse here is the Cull method which takes a viewport and transformation matrix and makes a decision about he visibility.

The rendering is performed by the Render method which takes a reference to the display driver, viewport and transformation matrix as well.

// Get or Set the culled flag
inline BOOL GetCulled() const;
virtual inline void SetCulled( BOOL cull );

// Check if this particle is visible from the supplied
// viewport. The fundamental idea behind this culling is that
// the object will always be in local space when Cull()
// is called. This means that it is a parent's
// responsibility to always pass in the matrix in local
// space for the child
virtual inline void Cull( ViewPort& view, const Matrix4& trans );

// Render the object after the first transforming
// it to world space with the passed in matrix
//
// ( The matrix is not const since it's ok for
// the object to wreck it if so desired, we
// dont need it afterwards anyway and it would
// be more slower to create a copy just to be able
// to add something like a scale )
virtual inline void Render( Display* display, ViewPort& view, Matrix4& trans );

Particle

Particle class does represents a hierarchical part of the scene graph, thus it inherits from the both Element and the Tree node. Particles can be added to the scene graph, rendered as well as organised into the tree-like hierarchy.

As such Particle class serves as the base class for any part of the scene which is spatially organised wrt frame of reference.

For the classes whose inherit the Paritcle it provides a number of convinience interfaces.

Identification

Particle can have assigned name, numerical id or user data.

Spatial

Particle has a defined position in form of vector and orientation in form of the quaternion. Also Particle provides methods to convert from local to global frame of reference or vice versa.

Hierarchy tree

As the tree node Particle is able to accomodate child particles and form a complete tree branch. Children inherit parent properties of the position, orientation and a visibility.

Culling

Particle defines object spatial boundary as the bounding sphere. It also provides an interface to calculate minimal bounding sphere of the child particles as the branch of spatial hierarchy.

// Creates a new cloned instance of this particle. Clone shares all the properties of the parent.
virtual inline Particle* CreateInstance() const;

// Gets identifier for this particle
virtual inline INT GetID() const;

// Gets user defined data
inline void* GetUserData() const;

// Sets the used defined data
inline void SetUsedData( void* data );

// Gets the name of this particle
inline const PString& GetName() const;

// Sets a new name for this particle
inline void SetName( const PString& name );

//////////////////////////////////////////
// Structure manipulation

// Gets a parent for this particle
inline Particle* GetParent();
inline const Particle* GetParent() const;

// Sets the parent for this particle
inline void SetParent( Particle* parent );

//////////////////////////////////////////
// Position and Orientation

// Gets the local position of this particle
inline const Vector3& GetPosition() const;

// Sets the local position for this particle and updates bounding sphere
// and global position flags
virtual inline void SetPosition( const Vector3& newPos );

// Gets the local XY position of this particle
//inline const Vector2& GetPositionXY() const;

// Sets the local XY position for this particle
//virtual inline void SetPositionXY( const Vector2& newPos );

// Gets the local orientation of this particle
inline const Quaternion& GetOrientation() const;

// Set the local orientation of this particle
virtual inline void SetOrientation( const Quaternion& orientation );

// Sets the local position and orientation at once
virtual inline void SetReferenceFrame( const Vector3& pos, const Quaternion& orient );

////////////////////////////////////////////
// Visibility and opacity

// Get the visibility flag
inline BOOL GetVisibile() const;

// Sets the visibility flag
inline void SetVisible( BOOL visible );

// Gets the opacity of this particle (this property is used to determine opaque objects from transparent)
inline FLOAT GetOpacity() const;

// Sets the opacity for this particle
virtual void SetOpacity( FLOAT opacity );

/////////////////////////////////////////
// Flags
        
// Gets the state of the dirtyGlobalCenter flag. Meaning it has to be recalculated.
inline BOOL GetDirtyGlobalCenter() const;

// Gets the state of the dirtySphere flag
inline BOOL GetDirtySphere() const;

/////////////////////////////////////////
// Bounding sphere

// Gets the reference to the bounding sphere ( local coords )
inline const Sphere& GetBoundingSphere( BOOL recalc = TRUE ) const;

// Gets the bounding sphere with the center in global coords
inline Sphere GetGlobalBoundingSphere( BOOL recalc = TRUE ) const;
inline void GetGlobalBoundingSphere( Sphere& globalBound, BOOL recalc = TRUE ) const;

// Gets the center of the bounding sphere in global coords
inline const Vector3& GetGlobalBoundingCenter( BOOL recalc = TRUE ) const;

///////////////////////////////////////
// Internal flags setup

// Sets this particle dirtySphere flag to true
virtual inline void ResetBoundingSphere() const;

// Sets this particle dirtyGlobalCenter flag to true
virtual inline void ResetGlobalBoundingCenter() const;

// Sets the dirtySphere flag for parents of this particle tree
virtual void ResetParentSpheres() const;

// Sets the dirtyGlobalCenter flag for all childs of this particle
virtual void ResetChildGlobalBoundingCenters() const;

// Recalculate this particle bounding sphere
virtual void RecalculateBoundingSphere() const;

// Recalculartes the global position for the center of the bounding sphere
virtual void RecalculateGlobalBoundingCenter() const;

///////////////////////////////////////
// Childs operatoin

// Adds a particle to the end of this particle child list
virtual inline void Add( Particle* particle );

// Adds particle to the one in the sub-tree ( including this one )
// matching given name
virtual BOOL Add( const PString& hostName, Particle* particle );

// Adds a particle to the head of this particle child list
virtual inline void Push( Particle* particle );


// Inserts a particle before the given child particle
virtual inline Iterator InsertBefore( Iterator& target, Particle* particle );

// Inserts a particle after the given child particle
virtual inline Iterator InsertAfter( Iterator& target, Particle* particle );

// Removes a particle from the tail of the child list
virtual inline Particle* Remove();

// Removes a specified child particle
virtual inline BOOL Remove( Particle* particle );

// Searches a sub-tree for the particle with given name and removes it
virtual Particle* Remove( const PString& name );

// Removes a particle from the child list at the given iterator
virtual inline Iterator Remove( Iterator& target );

// Removes a particle from the head of the child list
virtual inline Particle* Pop();

// Removes all child particles
virtual void RemoveAll();

// Recursively removes all child particles without destroying them
virtual void RemoveAllChildren();

// Removes and destroys all child particles
virtual void DeleteAll();

////////////////////////////////////////////////////
// Search and enumeration

// Search all the child particles for one of the specified name
Particle* FindByName( const PString& name );
const Particle* FindByName( const PString& name ) const;

// Adds all child particles into the specified list
BOOL EnumerateParticles( ParticlePtrList& particleList );
BOOL EnumerateParticles( ConstParticlePtrList& particleList ) const;

/////////////////////////////////////////////////
// Visibility check

// Determines if this particle is visible from given viewport and updates culled state
// Check if this particle and it's bounding volume is
// within the view frustum, if so - clears the 'culled' flag
// Allowed only to clear culled flag, because of coherency
inline BOOL CheckVisible( const ViewPort& viewPort );

// Determines if this particle is visible from given viewport 
virtual BOOL IsWithinView( const ViewPort& viewPort ) const;

// Test if the child particles are visible from the supplied viewport
virtual void Cull( ViewPort& viewport, const Matrix4& transform );

/////////////////////////////////////////////////
// Transformation

// Gets the current model-view transform
Matrix4 GetModelView( const Matrix4& trans ) const;
void GetModelView( Matrix4& result, const Matrix4& trans ) const;

// Moves the particle by the given delta vector
void Translate( const Vector3& delta );

// Rotates particle about it origin
void Rotate( const Matrix3& rot );
void Rotate( const Quaternion& rot );

// Rotates particle about its local center
void SelfRotate( const Matrix3& rot );
void SelfRotate( const Quaternion& rot );

//////////////////////////////////////////////
// Translate spatial primitive into/from particle's frame of reference

void LocalToGlobal( Plane& plane ) const;
void LocalToGlobal( Vector3& position ) const;
void LocalToGlobal( Quaternion& quat ) const;
void LocalToGlobal( Vector3& position, Quaternion& orient ) const;

void GlobalToLocal( Plane& plane ) const;
void GlobalToLocal( Vector3& position ) const;
void GlobalToLocal( Quaternion& quat ) const;
void GlobalToLocal( Vector3& position, Quaternion& orient ) const;

// Translates the given primitive from one local coordinate system into another
// particle parameter defines a new frame of the refenence to translate into
void LocalToLocal( Particle* particle, Plane& plane ) const;
void LocalToLocal( Particle* particle, Vector3& position ) const;
void LocalToLocal( Particle* particle, Quaternion& quat ) const;
void LocalToLocal( Particle* particle, Vector3& position, Quaternion& orient ) const;

//////////////////////////////////////////
// Collision test


// Determines if this particle bounding sphere is within the given plane list
// Note: planes are organized in the same way as the in case of Frustum
virtual BOOL IsWithin( const PlaneList& planeList ) const;

//////////////////////////////////////////////////
// Internals

// Get a raw reference to the position of this particle
inline Vector3& GetRawPosition();

// Get a raw reference to the local orientation of this particle
inline Quaternion& GetRawOrientation();

// Get a raw bounding sphere      
inline Sphere& GetRawBoundingSphere();

// Get global bounding sphere center
inline Vector3& GetRawGlobalBoundingCenter();

// Sets the local position of this particle without altering flags
virtual inline void SetRawPosition( const Vector3& pos );

// Sets the local orientation of this particle
virtual inline void SetRawOrientation( const Quaternion& orient );

// Sets the state of dirtyGlobalCenter flag
inline void SetRawDirtyGlobalCenter( BOOL state ) const;

// Sets the state of dirtySphere flag
inline void SetRawDirtySphere( BOOL state ) const;

// Sets the bounding sphere
inline void SetRawBoundingSphere( const Sphere& bounding ) const;

// Sets the radius of bounding sphere for this particle
inline void SetRawBoundingRadius( FLOAT bounding ) const;

// Sets the center position of the bounding sphere
inline void SetRawBoundingCenter( const Vector3& center ) const;

// Sets the center position of the global bounding sphere
inline void SetRawGlobalBoundingCenter( const Vector3& globalCenter ) const;


///////////////////////////
// Render a particle (inherited from the Element class)
virtual void Render( Display* display, ViewPort& view, Matrix4& trans );

ModifierUpdateTask

This class is the base for all periodic updates controlled by the SceneGraph. It hosts a list of the Modifier objects which gets called in certain predefined order every frame.

Updated