Pre-transforms and batches up meshes for efficient use as instanced geometry in a scene. More...

#include <OgreInstancedGeometry.h>

Inheritance diagram for Ogre::InstancedGeometry:

Classes
class	BatchInstance
	The details of a topological BatchInstance which is the highest level of partitioning for this class. More...

class	GeometryBucket
	A GeometryBucket is a the lowest level bucket where geometry with the same vertex & index format is stored. More...

class	InstancedObject

class	LODBucket
	A LODBucket is a collection of smaller buckets with the same LOD. More...

class	MaterialBucket
	A MaterialBucket is a collection of smaller buckets with the same Material (and implicitly the same LOD). More...

class	OptimisedSubMeshGeometry
	Struct holding geometry optimised per SubMesh / LOD level, ready for copying to instances. More...

struct	QueuedGeometry
	Structure recording a queued geometry for low level builds. More...

struct	QueuedSubMesh
	Structure recording a queued submesh for the build. More...

struct	SubMeshLodGeometryLink
	Saved link between SubMesh at a LOD and vertex/index data May point to original or optimised geometry. More...

Public Types
typedef MapIterator< BatchInstanceMap >	BatchInstanceIterator
	Iterator for iterating over contained BatchInstances. More...

typedef map< uint32, BatchInstance * >::type	BatchInstanceMap
	Indexed BatchInstance map based on packed x/y/z BatchInstance index, 10 bits for each axis. More...

typedef list< OptimisedSubMeshGeometry * >::type	OptimisedSubMeshGeometryList

typedef vector< QueuedGeometry * >::type	QueuedGeometryList

typedef vector< QueuedSubMesh * >::type	QueuedSubMeshList

typedef vector< String >::type	QueuedSubMeshOriginList

typedef vector< RenderOperation * >::type	RenderOperationVector
	Simple vectors where are stored all the render operations of the Batch. More...

typedef map< SubMesh , SubMeshLodGeometryLinkList >::type	SubMeshGeometryLookup

typedef vector< SubMeshLodGeometryLink >::type	SubMeshLodGeometryLinkList

Public Member Functions
	InstancedGeometry (SceneManager *owner, const String &name)
	Constructor; do not use directly (. More...

virtual	~InstancedGeometry ()
	Destructor. More...

void	addBatchInstance (void)
	Add a new batch instance. More...

virtual void	addEntity (Entity *ent, const Vector3 &position, const Quaternion &orientation=Quaternion::IDENTITY, const Vector3 &scale=Vector3::UNIT_SCALE)
	Adds an Entity to the static geometry. More...

virtual void	addSceneNode (const SceneNode *node)
	Adds all the Entity objects attached to a SceneNode and all it's children to the static geometry. More...

virtual void	build (void)
	Build the geometry. More...

virtual void	destroy (void)
	Destroys all the built geometry state (reverse of build). More...

virtual void	dump (const String &filename) const
	Dump the contents of this InstancedGeometry to a file for diagnostic purposes. More...

AnimationStateSet *	getBaseAnimationState (void)

SkeletonPtr	getBaseSkeleton (void)

SkeletonInstance *	getBaseSkeletonInstance (void)

virtual const Vector3 &	getBatchInstanceDimensions (void) const
	Gets the size of a single batch of geometry. More...

BatchInstanceIterator	getBatchInstanceIterator (void)
	Get an iterator over the BatchInstances in this geometry. More...

virtual bool	getCastShadows (void)
	Will the geometry from this object cast shadows? More...

const String &	getName (void) const
	Get the name of this object. More...

unsigned int	getObjectCount (void)

virtual const Vector3 &	getOrigin (void) const
	Gets the origin of this geometry. More...

virtual bool	getProvideWorldInverses (void) const

virtual Real	getRenderingDistance (void) const
	Gets the distance at which batches are no longer rendered. More...

RenderOperationVector &	getRenderOperationVector ()
	get the mRenderOps vector. More...

virtual uint8	getRenderQueueGroup (void) const
	Gets the queue group for this entity, see setRenderQueueGroup for full details. More...

virtual Real	getSquaredRenderingDistance (void) const
	Gets the squared distance at which batches are no longer rendered. More...

virtual bool	isVisible (void) const
	Are the batches visible? More...

virtual void	reset (void)
	Clears any of the entities / nodes added to this geometry and destroys anything which has already been built. More...

virtual void	setBatchInstanceDimensions (const Vector3 &size)
	Sets the size of a single BatchInstance of geometry. More...

virtual void	setCastShadows (bool castShadows)
	Sets whether this geometry should cast shadows. More...

virtual void	setOrigin (const Vector3 &origin)
	Sets the origin of the geometry. More...

virtual void	setProvideWorldInverses (bool flag)

virtual void	setRenderingDistance (Real dist)
	Sets the distance at which batches are no longer rendered. More...

virtual void	setRenderQueueGroup (uint8 queueID)
	Sets the render queue group this object will be rendered through. More...

virtual void	setVisible (bool visible)
	Hides or shows all the batches. More...

void	visitRenderables (Renderable::Visitor *visitor, bool debugRenderables=false)
	Method to allow a caller to abstractly iterate over the Renderable instances that this MovableObject will add to the render queue when asked, if any. More...

Detailed Description

Pre-transforms and batches up meshes for efficient use as instanced geometry in a scene.

Remarks: Shader instancing allows to save both memory and draw calls. While StaticGeometry stores 500 times the same object in a batch to display 500 objects, this shader instancing implementation stores only 80 times the object, and then re-uses the vertex data with different shader parameter. Although you save memory, you make more draw call. However, you still make less draw calls than if you were rendering each object independently. Plus, you can move the batched objects independently of one another which you cannot do with StaticGeometry.

Therefore it is important when you are rendering a lot of geometry to batch things up into as few rendering calls as possible. This class allows you to build a batched object from a series of entities in order to benefit from this behaviour. Batching has implications of it's own though:

Batched geometry cannot be subdivided; that means that the whole group will be displayed, or none of it will. This obivously has culling issues.
A single material must apply for each batch. In fact this class allows you to use multiple materials, but you should be aware that internally this means that there is one batch per material. Therefore you won't gain as much benefit from the batching if you use many different materials; try to keep the number down.

: The bounding box information is computed with object position only. It doesn't take account of the object orientation.

: The LOD settings of both the Mesh and the Materials used in constructing this instanced geometry will be respected. This means that if you use meshes/materials which have LOD, batches in the distance will have a lower polygon count or material detail to those in the foreground. Since each mesh might have different LOD distances, during build the furthest distance at each LOD level from all meshes in that BatchInstance is used. This means all the LOD levels change at the same time, but at the furthest distance of any of them (so quality is not degraded). Be aware that using Mesh LOD in this class will further increase the memory required. Only generated LOD is supported for meshes.

: There are 2 ways you can add geometry to this class; you can add Entity objects directly with predetermined positions, scales and orientations, or you can add an entire SceneNode and it's subtree, including all the objects attached to it. Once you've added everything you need to, you have to call build() the fix the geometry in place.

: You should not construct instances of this class directly; instead, call SceneManager::createInstancedGeometry, which gives the SceneManager the option of providing you with a specialised version of this class if it wishes, and also handles the memory management for you like other classes.

Note: Warning: this class only works with indexed triangle lists at the moment, do not pass it triangle strips, fans or lines / points, or unindexed geometry.

Deprecated:: use InstanceManager::ShaderBased instead of this

Member Typedef Documentation

◆ OptimisedSubMeshGeometryList

typedef list<OptimisedSubMeshGeometry*>::type Ogre::InstancedGeometry::OptimisedSubMeshGeometryList

◆ SubMeshLodGeometryLinkList

typedef vector<SubMeshLodGeometryLink>::type Ogre::InstancedGeometry::SubMeshLodGeometryLinkList

◆ SubMeshGeometryLookup

typedef map<SubMesh*, SubMeshLodGeometryLinkList*>::type Ogre::InstancedGeometry::SubMeshGeometryLookup

◆ QueuedSubMeshList

typedef vector<QueuedSubMesh*>::type Ogre::InstancedGeometry::QueuedSubMeshList

◆ QueuedSubMeshOriginList

typedef vector<String>::type Ogre::InstancedGeometry::QueuedSubMeshOriginList

◆ QueuedGeometryList

typedef vector<QueuedGeometry*>::type Ogre::InstancedGeometry::QueuedGeometryList

◆ BatchInstanceMap

typedef map<uint32, BatchInstance*>::type Ogre::InstancedGeometry::BatchInstanceMap

Indexed BatchInstance map based on packed x/y/z BatchInstance index, 10 bits for each axis.

◆ RenderOperationVector

typedef vector<RenderOperation*>::type Ogre::InstancedGeometry::RenderOperationVector

Simple vectors where are stored all the render operations of the Batch.

This vector is used when we want to delete the batch, in order to delete only one time each render operation.

◆ BatchInstanceIterator

typedef MapIterator<BatchInstanceMap> Ogre::InstancedGeometry::BatchInstanceIterator

Iterator for iterating over contained BatchInstances.

Constructor & Destructor Documentation

◆ InstancedGeometry()

Ogre::InstancedGeometry::InstancedGeometry	(	SceneManager *	owner,
		const String &	name
	)

Constructor; do not use directly (.

See also: SceneManager::createInstancedGeometry)

◆ ~InstancedGeometry()

virtual Ogre::InstancedGeometry::~InstancedGeometry ( )

virtual

Destructor.

Member Function Documentation

◆ getName()

const String& Ogre::InstancedGeometry::getName ( void ) const

inline

Get the name of this object.

References Ogre::Quaternion::IDENTITY, and Ogre::Vector3::UNIT_SCALE.

◆ addEntity()

virtual void Ogre::InstancedGeometry::addEntity	(	Entity *	ent,
		const Vector3 &	position,
		const Quaternion &	orientation = `Quaternion::IDENTITY`,
		const Vector3 &	scale = `Vector3::UNIT_SCALE`
	)

virtual

Adds an Entity to the static geometry.

Remarks: This method takes an existing Entity and adds its details to the list of elements to include when building. Note that the Entity itself is not copied or referenced in this method; an Entity is passed simply so that you can change the materials of attached SubEntity objects if you want. You can add the same Entity instance multiple times with different material settings completely safely, and destroy the Entity before destroying this InstancedGeometry if you like. The Entity passed in is simply used as a definition.

Note: Must be called before 'build'.; All added entities must use the same LOD strategy.

Parameters

ent	The Entity to use as a definition (the Mesh and Materials referenced will be recorded for the build call).
position	The world position at which to add this Entity
orientation	The world orientation at which to add this Entity
scale	The scale at which to add this entity

◆ addSceneNode()

virtual void Ogre::InstancedGeometry::addSceneNode ( const SceneNode * node )

virtual

Adds all the Entity objects attached to a SceneNode and all it's children to the static geometry.

Remarks: This method performs just like addEntity, except it adds all the entities attached to an entire sub-tree to the geometry. The position / orientation / scale parameters are taken from the node structure instead of being specified manually.

Note: The SceneNode you pass in will not be automatically detached from it's parent, so if you have this node already attached to the scene graph, you will need to remove it if you wish to avoid the overhead of rendering both the original objects and their new static versions! We don't do this for you incase you are preparing this in advance and so don't want the originals detached yet.; Must be called before 'build'.; All added entities must use the same LOD strategy.

Parameters

node	Pointer to the node to use to provide a set of Entity templates

◆ build()

virtual void Ogre::InstancedGeometry::build ( void )

virtual

Build the geometry.

Remarks: Based on all the entities which have been added, and the batching options which have been set, this method constructs the batched geometry structures required. The batches are added to the scene and will be rendered unless you specifically hide them.

Note: Once you have called this method, you can no longer add any more entities.

◆ addBatchInstance()

void Ogre::InstancedGeometry::addBatchInstance ( void )

Add a new batch instance.

Remarks: This method add a new instance of the whole batch, by creating a new BatchInstance, containing new LOD buckets, material buckets and geometry buckets. The new geometry buckets will use the same buffers as the base bucket.

Note: no note

◆ destroy()

virtual void Ogre::InstancedGeometry::destroy ( void )

virtual

Destroys all the built geometry state (reverse of build).

Remarks: You can call build() again after this and it will pick up all the same entities / nodes you queued last time.

◆ reset()

virtual void Ogre::InstancedGeometry::reset ( void )

virtual

Clears any of the entities / nodes added to this geometry and destroys anything which has already been built.

◆ setRenderingDistance()

virtual void Ogre::InstancedGeometry::setRenderingDistance ( Real dist )

inlinevirtual

Sets the distance at which batches are no longer rendered.

Remarks: This lets you turn off batches at a given distance. This can be useful for things like detail meshes (grass, foliage etc) and could be combined with a shader which fades the geometry out beforehand to lessen the effect.

Parameters

dist	Distance beyond which the batches will not be rendered (the default is 0, which means batches are always rendered).

◆ getRenderingDistance()

virtual Real Ogre::InstancedGeometry::getRenderingDistance ( void ) const

inlinevirtual

Gets the distance at which batches are no longer rendered.

◆ getSquaredRenderingDistance()

virtual Real Ogre::InstancedGeometry::getSquaredRenderingDistance ( void ) const

inlinevirtual

Gets the squared distance at which batches are no longer rendered.

◆ setVisible()

virtual void Ogre::InstancedGeometry::setVisible ( bool visible )

virtual

Hides or shows all the batches.

◆ isVisible()

virtual bool Ogre::InstancedGeometry::isVisible ( void ) const

inlinevirtual

Are the batches visible?

◆ setCastShadows()

virtual void Ogre::InstancedGeometry::setCastShadows ( bool castShadows )

virtual

Sets whether this geometry should cast shadows.

Remarks: No matter what the settings on the original entities, the InstancedGeometry class defaults to not casting shadows. This is because, being static, unless you have moving lights you'd be better to use precalculated shadows of some sort. However, if you need them, you can enable them using this method. If the SceneManager is set up to use stencil shadows, edge lists will be copied from the underlying meshes on build. It is essential that all meshes support stencil shadows in this case.

Note: If you intend to use stencil shadows, you must set this to true before calling 'build' as well as making sure you set the scene's shadow type (that should always be the first thing you do anyway). You can turn shadows off temporarily but they can never be turned on if they were not at the time of the build.

◆ getCastShadows()

virtual bool Ogre::InstancedGeometry::getCastShadows ( void )

inlinevirtual

Will the geometry from this object cast shadows?

◆ setBatchInstanceDimensions()

virtual void Ogre::InstancedGeometry::setBatchInstanceDimensions ( const Vector3 & size )

inlinevirtual

Sets the size of a single BatchInstance of geometry.

Remarks: This method allows you to configure the physical world size of each BatchInstance, so you can balance culling against batch size. Entities will be fitted within the batch they most closely fit, and the eventual bounds of each batch may well be slightly larger than this if they overlap a little. The default is Vector3(1000, 1000, 1000).

Note: Must be called before 'build'.

Parameters

size	Vector3 expressing the 3D size of each BatchInstance.

◆ getBatchInstanceDimensions()

virtual const Vector3& Ogre::InstancedGeometry::getBatchInstanceDimensions ( void ) const

inlinevirtual

Gets the size of a single batch of geometry.

◆ setOrigin()

virtual void Ogre::InstancedGeometry::setOrigin ( const Vector3 & origin )

inlinevirtual

Sets the origin of the geometry.

Remarks: This method allows you to configure the world centre of the geometry, thus the place which all BatchInstances surround. You probably don't need to mess with this unless you have a seriously large world, since the default set up can handle an area 1024 * mBatchInstanceDimensions, and the sparseness of population is no issue when it comes to rendering. The default is Vector3(0,0,0).

Note: Must be called before 'build'.

Parameters

origin Vector3 expressing the 3D origin of the geometry.

◆ getOrigin()

virtual const Vector3& Ogre::InstancedGeometry::getOrigin ( void ) const

inlinevirtual

Gets the origin of this geometry.

◆ setRenderQueueGroup()

virtual void Ogre::InstancedGeometry::setRenderQueueGroup ( uint8 queueID )

virtual

Sets the render queue group this object will be rendered through.

Remarks: Render queues are grouped to allow you to more tightly control the ordering of rendered objects. If you do not call this method, all objects default to the default queue (RenderQueue::getDefaultQueueGroup), which is fine for most objects. You may want to alter this if you want to perform more complex rendering.

: See RenderQueue for more details.

Parameters

queueID Enumerated value of the queue group to use.

◆ getRenderQueueGroup()

virtual uint8 Ogre::InstancedGeometry::getRenderQueueGroup ( void ) const

virtual

Gets the queue group for this entity, see setRenderQueueGroup for full details.

◆ getBatchInstanceIterator()

BatchInstanceIterator Ogre::InstancedGeometry::getBatchInstanceIterator ( void )

Get an iterator over the BatchInstances in this geometry.

◆ getRenderOperationVector()

RenderOperationVector& Ogre::InstancedGeometry::getRenderOperationVector ( )

inline

get the mRenderOps vector.

◆ visitRenderables()

void Ogre::InstancedGeometry::visitRenderables	(	Renderable::Visitor *	visitor,
		bool	debugRenderables = `false`
	)

Method to allow a caller to abstractly iterate over the Renderable instances that this MovableObject will add to the render queue when asked, if any.

Parameters

visitor	Pointer to a class implementing the Renderable::Visitor interface which will be called back for each Renderable which will be queued. Bear in mind that the state of the Renderable instances may not be finalised depending on when you call this.
debugRenderables	If false, only regular renderables will be visited (those for normal display). If true, debug renderables will be included too.

◆ dump()

virtual void Ogre::InstancedGeometry::dump ( const String & filename ) const

virtual

Dump the contents of this InstancedGeometry to a file for diagnostic purposes.

◆ getBaseSkeletonInstance()

SkeletonInstance* Ogre::InstancedGeometry::getBaseSkeletonInstance ( void )

inline

Remarks: Return the skeletonInstance that will be used

◆ getBaseSkeleton()

SkeletonPtr Ogre::InstancedGeometry::getBaseSkeleton ( void )

inline

Remarks: Return the skeleton that is shared by all instanced objects.

◆ getBaseAnimationState()

AnimationStateSet* Ogre::InstancedGeometry::getBaseAnimationState ( void )

inline

Remarks: Return the animation state that will be cloned each time an InstancedObject is made

◆ getObjectCount()

unsigned int Ogre::InstancedGeometry::getObjectCount ( void )

inline

Remarks: return the total number of object that are in all the batches

◆ setProvideWorldInverses()

virtual void Ogre::InstancedGeometry::setProvideWorldInverses ( bool flag )

virtual

Remarks: Allows World Transform Inverse matrices to be passed as shader constants along with the world transform matrix list. Reduces the number of usable geometries in an instance to 40 instead of 80. The inverse matrices are interleaved with the world matrices at n+1.

◆ getProvideWorldInverses()

virtual bool Ogre::InstancedGeometry::getProvideWorldInverses ( void ) const

inlinevirtual

Remarks: Returns the toggle state indicating whether the World Transform INVERSE matrices would be passed to the shaders.

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

OgreInstancedGeometry.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ OptimisedSubMeshGeometryList

◆ SubMeshLodGeometryLinkList

◆ SubMeshGeometryLookup

◆ QueuedSubMeshList

◆ QueuedSubMeshOriginList

◆ QueuedGeometryList

◆ BatchInstanceMap

◆ RenderOperationVector

◆ BatchInstanceIterator

Constructor & Destructor Documentation

◆ InstancedGeometry()

◆ ~InstancedGeometry()

Member Function Documentation

◆ getName()

◆ addEntity()

◆ addSceneNode()

◆ build()

◆ addBatchInstance()

◆ destroy()

◆ reset()

◆ setRenderingDistance()

◆ getRenderingDistance()

◆ getSquaredRenderingDistance()

◆ setVisible()

◆ isVisible()

◆ setCastShadows()

◆ getCastShadows()

◆ setBatchInstanceDimensions()

◆ getBatchInstanceDimensions()

◆ setOrigin()

◆ getOrigin()

◆ setRenderQueueGroup()

◆ getRenderQueueGroup()

◆ getBatchInstanceIterator()

◆ getRenderOperationVector()

◆ visitRenderables()

◆ dump()

◆ getBaseSkeletonInstance()

◆ getBaseSkeleton()

◆ getBaseAnimationState()

◆ getObjectCount()

◆ setProvideWorldInverses()

◆ getProvideWorldInverses()