OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::NodeMemoryManager Class Referencefinal

Wrap-around class that contains multiple ArrayMemoryManager, one per hierarchy depth. More...

#include <OgreNodeMemoryManager.h>

+ Inheritance diagram for Ogre::NodeMemoryManager:

Public Member Functions

 NodeMemoryManager ()
 
virtual ~NodeMemoryManager ()
 
SceneNode_getDummyNode () const
 
void _setTwin (SceneMemoryMgrTypes memoryManagerType, NodeMemoryManager *twinMemoryManager)
 
void applyRebase (uint16 level, const MemoryPoolVec &newBasePtrs, const ArrayMemoryManager::PtrdiffVec &diffsList) override
 Called when the manager already grew it's memory pool to honour more node requests. More...
 
void buildDiffList (uint16 level, const MemoryPoolVec &basePtrs, ArrayMemoryManager::PtrdiffVec &outDiffsList) override
 Called when the manager needs to grow it's memory pool to honour more node requests. More...
 
void defragment ()
 Triggers on demand a defragmentation of the pools, so that all slots become contiguous in memory. More...
 
size_t getFirstNode (Transform &outTransform, size_t depth)
 Retrieves a Transform pointing to the first Node in the given depth. More...
 
SceneMemoryMgrTypes getMemoryManagerType () const
 
size_t getNumDepths () const
 Retrieves the number of depth levels that have been created. More...
 
NodeMemoryManagergetTwin () const
 Note the return value can be null. More...
 
void migrateTo (Transform &inOutTransform, size_t depth, NodeMemoryManager *dstNodeMemoryManager)
 Releases memory belonging to us, not before copying it into another manager. More...
 
void migrateTo (Transform &inOutTransform, size_t oldDepth, size_t newDepth, NodeMemoryManager *dstNodeMemoryManager)
 Releases memory belonging to us, not before copying it into another manager. More...
 
void migrateToAndAttach (Transform &inOutTransform, size_t depth, NodeMemoryManager *dstNodeMemoryManager)
 It's the same as calling: this->nodeAttached( transform, depth ); this->migrateTo( transform, depth, dstNodeMemoryManager ); Without unnecessary transfers. More...
 
void migrateToAndDetach (Transform &inOutTransform, size_t depth, NodeMemoryManager *dstNodeMemoryManager)
 It's almost the same as calling: this->nodeDettached( transform, depth ); this->migrateTo( transform, 0, dstNodeMemoryManager ); Without unnecessary transfers and setting the correct dstNodeMemoryManager->mDummyNode. More...
 
void neverDefragment ()
 Prevent defragmentation from ever happening. More...
 
void nodeAttached (Transform &outTransform, size_t depth)
 Requests memory for the given transform to be attached, transferring existing values inside to the new memory block. More...
 
void nodeCreated (Transform &outTransform, size_t depth)
 Requests memory for the given transform for the first, initializing values. More...
 
void nodeDestroyed (Transform &outTransform, size_t depth)
 Releases current memory. More...
 
void nodeDettached (Transform &outTransform, size_t depth)
 Releases current memory and requests memory from the root level. More...
 
void nodeMoved (Transform &inOutTransform, size_t oldDepth, size_t newDepth)
 Requests memory for the given Node to be moved to a different depth level, transferring existing values inside to the new memory slot. More...
 
void performCleanup (uint16 level, const MemoryPoolVec &basePtrs, size_t const *elementsMemSizes, size_t startInstance, size_t diffInstances) override
 Called when too many nodes were destroyed in a non-LIFO fashion. More...
 
void shrinkToFit ()
 Defragments memory, then reallocates a smaller pool that tightly fits the current number of objects. More...
 

Detailed Description

Wrap-around class that contains multiple ArrayMemoryManager, one per hierarchy depth.

Remarks
This is the main memory manager that actually manages Nodes, and have to be called when a new SceneNode was created, when a SceneNode gets detached from it's parent, when it's attached again, etc.
Note that some SceneManager implementations (i.e. Octree like) may want to have more than one NodeMemoryManager, for example one per octant.

Constructor & Destructor Documentation

◆ NodeMemoryManager()

Ogre::NodeMemoryManager::NodeMemoryManager ( )

◆ ~NodeMemoryManager()

virtual Ogre::NodeMemoryManager::~NodeMemoryManager ( )
virtual

Member Function Documentation

◆ _getDummyNode()

SceneNode* Ogre::NodeMemoryManager::_getDummyNode ( ) const
inline

◆ _setTwin()

void Ogre::NodeMemoryManager::_setTwin ( SceneMemoryMgrTypes  memoryManagerType,
NodeMemoryManager twinMemoryManager 
)
See also
mMemoryManagerType

◆ applyRebase()

void Ogre::NodeMemoryManager::applyRebase ( uint16  level,
const MemoryPoolVec newBasePtrs,
const ArrayMemoryManager::PtrdiffVec diffsList 
)
overridevirtual

Called when the manager already grew it's memory pool to honour more node requests.

Remarks
Will use the new base ptr and the list we built in
See also
buildDiffList() to know what mChunkPtr & mIndex needs to be set for each ArrayVector3/etc we have.
Parameters
levelThe hierarchy depth level
newBasePtrsThe new base ptr.
diffsListThe list built in buildDiffList

Implements Ogre::ArrayMemoryManager::RebaseListener.

◆ buildDiffList()

void Ogre::NodeMemoryManager::buildDiffList ( uint16  level,
const MemoryPoolVec basePtrs,
ArrayMemoryManager::PtrdiffVec outDiffsList 
)
overridevirtual

Called when the manager needs to grow it's memory pool to honour more node requests.

See the class description on why we need to do this (to avoid C++ undefined behavior)

Remarks
Needs to builds a list that will contain the difference in bytes between each ArrayVector3/ArrayMatrix4/etc and the base pointers in_the_order in which the derived class holds those pointers (i.e. in the order the SceneNodes are arranged in memory)
Parameters
levelThe hierarchy depth level
basePtrsThe base pointers from each pool so we can calculate the differences
outDiffsListThe list we'll generate. "outDiffsList" already has enough reserved space

Implements Ogre::ArrayMemoryManager::RebaseListener.

◆ defragment()

void Ogre::NodeMemoryManager::defragment ( )

Triggers on demand a defragmentation of the pools, so that all slots become contiguous in memory.

ArrayMemoryManager::destroySlot already does this when the number of fragmented slots reaches mCleanupThreshold

◆ getFirstNode()

size_t Ogre::NodeMemoryManager::getFirstNode ( Transform outTransform,
size_t  depth 
)

Retrieves a Transform pointing to the first Node in the given depth.

Parameters
outTransform[out] Transform with filled pointers to the first Node in this depth
depthCurrent hierarchy level depth it belongs to.
Returns
Number of Nodes in this depth level

◆ getMemoryManagerType()

SceneMemoryMgrTypes Ogre::NodeMemoryManager::getMemoryManagerType ( ) const
inline

◆ getNumDepths()

size_t Ogre::NodeMemoryManager::getNumDepths ( ) const

Retrieves the number of depth levels that have been created.

Remarks
The return value is equal or below mMemoryManagers.size(), you should cache the result instead of calling this function too often.

◆ getTwin()

NodeMemoryManager* Ogre::NodeMemoryManager::getTwin ( ) const
inline

Note the return value can be null.

◆ migrateTo() [1/2]

void Ogre::NodeMemoryManager::migrateTo ( Transform inOutTransform,
size_t  depth,
NodeMemoryManager dstNodeMemoryManager 
)

Releases memory belonging to us, not before copying it into another manager.

Remarks
This function is useful when implementing multiple Memory Managers in Scene Managers or when switching nodes from Static to/from Dynamic.
Parameters
inOutTransformValid Transform that belongs to us. Output will belong to the other memory mgr.
depthCurrent hierarchy level depth it belongs to.
dstNodeMemoryManagerNodeMemoryManager that will now own the transform.

◆ migrateTo() [2/2]

void Ogre::NodeMemoryManager::migrateTo ( Transform inOutTransform,
size_t  oldDepth,
size_t  newDepth,
NodeMemoryManager dstNodeMemoryManager 
)

Releases memory belonging to us, not before copying it into another manager.

Remarks
This function is useful when implementing multiple Memory Managers in Scene Managers or when switching nodes from Static to/from Dynamic.
Parameters
inOutTransformValid Transform that belongs to us. Output will belong to the other memory mgr.
oldDepthCurrent hierarchy level depth it belongs to in this manager.
newDepthNew hierarchy level depth it will belong belongs in dstNodeMemoryManager. If this value is zero, then oldDepth must be zero as well. Otherwise use migrateToAndDetach instead.
dstNodeMemoryManagerNodeMemoryManager that will now own the transform.

◆ migrateToAndAttach()

void Ogre::NodeMemoryManager::migrateToAndAttach ( Transform inOutTransform,
size_t  depth,
NodeMemoryManager dstNodeMemoryManager 
)

It's the same as calling: this->nodeAttached( transform, depth ); this->migrateTo( transform, depth, dstNodeMemoryManager ); Without unnecessary transfers.

◆ migrateToAndDetach()

void Ogre::NodeMemoryManager::migrateToAndDetach ( Transform inOutTransform,
size_t  depth,
NodeMemoryManager dstNodeMemoryManager 
)

It's almost the same as calling: this->nodeDettached( transform, depth ); this->migrateTo( transform, 0, dstNodeMemoryManager ); Without unnecessary transfers and setting the correct dstNodeMemoryManager->mDummyNode.

instead of this->mDummyNode.

◆ neverDefragment()

void Ogre::NodeMemoryManager::neverDefragment ( )

Prevent defragmentation from ever happening.

◆ nodeAttached()

void Ogre::NodeMemoryManager::nodeAttached ( Transform outTransform,
size_t  depth 
)

Requests memory for the given transform to be attached, transferring existing values inside to the new memory block.

Remarks
Do NOT call this function twice in a row without having called nodeDettached in the middle
Parameters
outTransformTransform with filled pointers
depthHierarchy level depth the node belongs to. If 0, nothing happens.

◆ nodeCreated()

void Ogre::NodeMemoryManager::nodeCreated ( Transform outTransform,
size_t  depth 
)

Requests memory for the given transform for the first, initializing values.

Parameters
outTransformTransform with filled pointers
depthHierarchy level depth. 0 if not connected.

◆ nodeDestroyed()

void Ogre::NodeMemoryManager::nodeDestroyed ( Transform outTransform,
size_t  depth 
)

Releases current memory.

Parameters
outTransformTransform with nullified pointers
depthCurrent hierarchy level depth it belongs to.

◆ nodeDettached()

void Ogre::NodeMemoryManager::nodeDettached ( Transform outTransform,
size_t  depth 
)

Releases current memory and requests memory from the root level.

Remarks
Do NOT call this function twice in a row without having called nodeAttached in the middle
outTransform.mParents[outTransform.mIndex] is reset to a dummy parent node
Parameters
outTransformTransform with filled pointers
depthCurrent hierarchy level depth it belongs to. If 0, nothing happens.

◆ nodeMoved()

void Ogre::NodeMemoryManager::nodeMoved ( Transform inOutTransform,
size_t  oldDepth,
size_t  newDepth 
)

Requests memory for the given Node to be moved to a different depth level, transferring existing values inside to the new memory slot.

Parameters
inOutTransformTransform with filled pointers
oldDepthCurrent hierarchy level depth it belongs to.
newDepthHierarchy level depth it wants to belongs to.

◆ performCleanup()

void Ogre::NodeMemoryManager::performCleanup ( uint16  level,
const MemoryPoolVec basePtrs,
size_t const *  elementsMemSizes,
size_t  startInstance,
size_t  diffInstances 
)
overridevirtual

Called when too many nodes were destroyed in a non-LIFO fashion.

Without cleaning up, the scene manager will waste CPU & bandwidth on processing vectors & matrices that are not in use. The more fragmented/unordered those removals were, the worst it is. Try to create everything static first, then dynamic content.

Remarks
The manager behaves similarly to a Garbage Collector, as it is triggered after certain amount of nodes have been freed (unless they respected LIFO order)

In a way, it's very similar to vector::remove(), as removing an element from the middle means we need to shift everything past that point one place (or more).

Parameters
levelThe hierarchy depth level
basePtrsThe base ptrs.
startInstanceThe instance to which past that we need to shift
diffInstancesHow many places we need to shift backwards.

Implements Ogre::ArrayMemoryManager::RebaseListener.

◆ shrinkToFit()

void Ogre::NodeMemoryManager::shrinkToFit ( )

Defragments memory, then reallocates a smaller pool that tightly fits the current number of objects.

Useful when you know you won't be creating more slots and you need to reclaim memory.


The documentation for this class was generated from the following file: