Ogre::ProgressiveMesh Class Reference
[LOD]

This class reduces the complexity of the geometry it is given. More...

#include <OgreProgressiveMesh.h>

Inheritance diagram for Ogre::ProgressiveMesh:

Classes
class	PMFaceVertex
	A vertex as used by a face. More...
class	PMTriangle
	A triangle in the progressive mesh, holds extra info like face normal. More...
class	PMVertex
	A vertex in the progressive mesh, holds info like collapse cost etc. More...
struct	PMWorkingData
	Data used to calculate the collapse costs. More...
Public Types
enum	VertexReductionQuota { VRQ_CONSTANT, VRQ_PROPORTIONAL, VRQ_ERROR_COST }
	The way to derive the quota of vertices which are reduced at each LOD. More...
typedef vector< Real >::type	LodValueList
Public Member Functions
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void ptr, void )
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
Static Public Member Functions
static bool	generateLodLevels (Mesh *pMesh, const LodValueList &lodValues, VertexReductionQuota reductionMethod, Real reductionValue)
	Automatically generates lower level of detail versions of this mesh for use when a simpler version of the model is acceptable for rendering.
static MeshPtr	generateSimplifiedMesh (const String &name, const String &groupName, Mesh inMesh, bool dropOriginalGeometry, const LodValueList &lodValues, VertexReductionQuota reductionMethod, Real reductionValue, size_t removedVertexDuplicatesCount)
	Automatically generates lower level of detail versions of this mesh for use when a simpler version of the model is acceptable for rendering.
Protected Types
typedef vector < ProgressiveMesh * >::type	ProgressiveMeshList
typedef vector< PMTriangle >::type	TriangleList
typedef vector< PMFaceVertex > ::type	FaceVertexList
typedef vector< PMVertex >::type	CommonVertexList
typedef std::pair< Real, unsigned int >	CostIndexPair
typedef vector< CostIndexPair > ::type	WorstCostList
typedef vector< PMWorkingData > ::type	WorkingDataList
typedef std::pair< unsigned, PMVertex * >	IndexVertexPair
	We can defragment mesh, removing unused vertices and re-indexing other, storing old-to-new mapping in index map.
Protected Member Functions
	ProgressiveMesh (SubMesh *pSubMesh)
	Constructor, takes SubMesh pointer.
virtual	~ProgressiveMesh ()
virtual void	addExtraVertexPositionBuffer (const VertexData *vertexData)
	Adds an extra vertex position buffer.
void	addWorkingData (const VertexData vertexData, const IndexData indexData)
	Internal method for building PMWorkingData from geometry data.
void	mergeWorkingDataBorders ()
void	initialiseEdgeCollapseCosts (void)
	Internal method for initialising the edge collapse costs.
Real	computeEdgeCollapseCost (PMVertex src, PMVertex dest) const
	Internal calculation method for deriving a collapse cost from u to v.
bool	collapseInvertsNormals (PMVertex src, PMVertex dest) const
	Internal calculation method, return true if edge collapse flip some neighbor face normal.
Real	computeEdgeCostAtVertexForBuffer (PMVertex *v)
	Internal method evaluates all collapse costs from this vertex and picks the lowest for a single buffer.
Real	computeEdgeCostAtVertex (size_t vertIndex)
	Internal method evaluates all collapse costs from this vertex for every buffer and returns the worst.
void	computeAllCosts (void)
	Internal method to compute edge collapse costs for all buffers /.
void	recomputeInvalidCosts ()
void	sortIndexesByCost ()
CostIndexPair *	getNextCollapser ()
void	bakeNewLOD (IndexData *pData)
	Internal method builds an new LOD based on the current state.
void	collapse (PMVertex *collapser)
	Internal method, collapses vertex onto it's saved collapse target.
void	dumpContents (const String &log)
	Internal debugging method.
Static Protected Member Functions
static void	initializeProgressiveMeshList (ProgressiveMeshList &pmList, Mesh *pMesh)
	Allocates internal resources.
static void	freeProgressiveMeshList (ProgressiveMeshList *pmList)
	Deletes allocated internal resources.
static bool	build (ProgressiveMeshList &pmInList, const LodStrategy *lodStrategy, const LodValueList &lodValues, VertexReductionQuota quota, Real reductionValue=0.5f)
	Builds the progressive mesh with the specified number of levels.
static size_t	getInvalidCostCount (ProgressiveMesh::ProgressiveMeshList &pmList)
	Internal methods for lazy costs recomputing.
static bool	recomputeInvalidCosts (ProgressiveMeshList &pmInList)
static int	cmpByCost (const void p1, const void p2)
static void	getNextCollapser (ProgressiveMeshList &pmList, ProgressiveMesh &pm, CostIndexPair &bestCollapser)
	Internal methods for getting the index of next best vertex to collapse among all submeshes.
static void	bakeLodUsage (Mesh pMesh, LodStrategy lodStrategy, const LodValueList &lodValues, bool skipFirstLodLevel=false)
	Internal method builds an LODs usage, possibly skipping first LOD, that can be used as original geometry.
static void	bakeSimplifiedMesh (Mesh destMesh, Mesh srcMesh, ProgressiveMeshList &pmList, bool dropFirstLodLevel=false)
	Optionally discards first LOD level (i.e. original geometry), removes unused vertices, remaps indexes.
static void	createSimplifiedVertexData (vector< IndexVertexPair >::type &usedVertices, VertexData inVData, VertexData &outVData, AxisAlignedBox &aabox)
	Defragments vertices, removing unused. Useful if original geometry is redundant or dropped at all.
static void	createIndexMap (vector< IndexVertexPair >::type &usedVertices, unsigned allVertexCount, vector< unsigned >::type &indexMap)
	During vertices defragmentation vertices are re-indexed, so old-to-new mapping is stored in index map by this function.
Protected Attributes
SubMesh *	mSubMesh
	Can be NULL for non-indexed subMeshes, such PM would be skipped.
VertexData *	mVertexData
IndexData *	mIndexData
vector< IndexData * >::type	mLodFaceList
size_t	mRemovedVertexDuplicatesCount
size_t	mCurrNumIndexes
float	mInvSquaredBoundBoxDiagonal
int	mVertexComponentFlags
WorkingDataList	mWorkingData
	Multiple copies, 1 per vertex buffer.
WorstCostList	mWorstCosts
	The worst collapse cost from all vertex buffers for each vertex.
BitArray	mInvalidCostMask
size_t	mInvalidCostCount
size_t	mWorstCostsSize
size_t	mNextWorstCostHint
PMVertex::FaceList	mEdgeAdjacentSides
	Temporary variable used in computeEdgeCollapseCost, declared here to avoid multiple memory allocations.

Detailed Description

This class reduces the complexity of the geometry it is given.

This class is dedicated to reducing the number of triangles in a given mesh taking into account seams in both geometry and texture co-ordinates and meshes which have multiple frames.

: The primary use for this is generating LOD versions of Mesh objects, but it can be used by any geometry provider. The only limitation at the moment is that the provider uses a common vertex buffer for all LODs and one index buffer per LOD. Therefore at the moment this class can only handle indexed geometry.

: NB the interface of this class will certainly change when compiled vertex buffers are supported.

Definition at line 107 of file OgreProgressiveMesh.h.

Member Typedef Documentation

typedef vector<PMVertex>::type Ogre::ProgressiveMesh::CommonVertexList [protected]

Definition at line 308 of file OgreProgressiveMesh.h.

typedef std::pair<Real, unsigned int> Ogre::ProgressiveMesh::CostIndexPair [protected]

Definition at line 309 of file OgreProgressiveMesh.h.

typedef vector<PMFaceVertex>::type Ogre::ProgressiveMesh::FaceVertexList [protected]

Definition at line 307 of file OgreProgressiveMesh.h.

typedef std::pair<unsigned, PMVertex*> Ogre::ProgressiveMesh::IndexVertexPair [protected]

We can defragment mesh, removing unused vertices and re-indexing other, storing old-to-new mapping in index map.

Definition at line 376 of file OgreProgressiveMesh.h.

typedef vector<Real>::type Ogre::ProgressiveMesh::LodValueList

Definition at line 110 of file OgreProgressiveMesh.h.

typedef vector<ProgressiveMesh*>::type Ogre::ProgressiveMesh::ProgressiveMeshList [protected]

Definition at line 168 of file OgreProgressiveMesh.h.

typedef vector<PMTriangle>::type Ogre::ProgressiveMesh::TriangleList [protected]

Definition at line 306 of file OgreProgressiveMesh.h.

typedef vector<PMWorkingData>::type Ogre::ProgressiveMesh::WorkingDataList [protected]

Definition at line 320 of file OgreProgressiveMesh.h.

typedef vector<CostIndexPair>::type Ogre::ProgressiveMesh::WorstCostList [protected]

Definition at line 310 of file OgreProgressiveMesh.h.

Member Enumeration Documentation

enum Ogre::ProgressiveMesh::VertexReductionQuota

The way to derive the quota of vertices which are reduced at each LOD.

Enumerator:

VRQ_CONSTANT

A set number of vertices are removed at each reduction.

VRQ_PROPORTIONAL

A proportion of the remaining number of vertices are removed at each reduction.

VRQ_ERROR_COST

All vertices with reduction error cost less than reductionValue * sqr(lodDistance[lodLevel] / lodDistance[0]) are removed at each reduction.

Error cost is calculated as introduced error area divided by squared mesh diagonal

Definition at line 113 of file OgreProgressiveMesh.h.

Constructor & Destructor Documentation

Ogre::ProgressiveMesh::ProgressiveMesh ( SubMesh * pSubMesh ) [protected]

Constructor, takes SubMesh pointer.

Remarks:: DO NOT pass write-only, unshadowed buffers to this method! They will not work. Pass only shadowed buffers, or better yet perform mesh reduction as an offline process using DefaultHardwareBufferManager to manage vertex buffers in system memory.

virtual Ogre::ProgressiveMesh::~ProgressiveMesh ( ) [protected, virtual]

Member Function Documentation

virtual void Ogre::ProgressiveMesh::addExtraVertexPositionBuffer ( const VertexData * vertexData ) [protected, virtual]

Adds an extra vertex position buffer.

Remarks:: As well as the main vertex buffer, the client of this class may add extra versions of the vertex buffer which will also be taken into account when the cost of simplifying the mesh is taken into account. This is because the cost of simplifying an animated mesh cannot be calculated from just the reference position, multiple positions needs to be assessed in order to find the best simplification option.

: DO NOT pass write-only, unshadowed buffers to this method! They will not work. Pass only shadowed buffers, or better yet perform mesh reduction as an offline process using DefaultHardwareBufferManager to manage vertex buffers in system memory.

Parameters:

buffer

Pointer to x/y/z buffer with vertex positions. The number of vertices must be the same as in the original GeometryData passed to the constructor.

void Ogre::ProgressiveMesh::addWorkingData	(	const VertexData *	vertexData,
		const IndexData *	indexData
	)			`[protected]`

Internal method for building PMWorkingData from geometry data.

static void Ogre::ProgressiveMesh::bakeLodUsage	(	Mesh *	pMesh,
		LodStrategy *	lodStrategy,
		const LodValueList &	lodValues,
		bool	skipFirstLodLevel = `false`
	)			`[static, protected]`

Internal method builds an LODs usage, possibly skipping first LOD, that can be used as original geometry.

void Ogre::ProgressiveMesh::bakeNewLOD ( IndexData * pData ) [protected]

Internal method builds an new LOD based on the current state.

static void Ogre::ProgressiveMesh::bakeSimplifiedMesh	(	Mesh *	destMesh,
		Mesh *	srcMesh,
		ProgressiveMeshList &	pmList,
		bool	dropFirstLodLevel = `false`
	)			`[static, protected]`

Optionally discards first LOD level (i.e. original geometry), removes unused vertices, remaps indexes.

static bool Ogre::ProgressiveMesh::build	(	ProgressiveMeshList &	pmInList,
		const LodStrategy *	lodStrategy,
		const LodValueList &	lodValues,
		VertexReductionQuota	quota,
		Real	reductionValue = `0.5f`
	)			`[static, protected]`

Builds the progressive mesh with the specified number of levels.

Parameters:

	numLevels	The number of levels to include in the output excluding the full detail version.
	outList	Pointer to a list of LOD geometry data which will be completed by the application. Each entry is a reduced form of the mesh, in decreasing order of detail.
	quota	The way to derive the number of vertices removed at each LOD
	reductionValue	Either the proportion of vertices to remove at each level, or a fixed number of vertices to remove at each level, depending on the value of quota

static int Ogre::ProgressiveMesh::cmpByCost	(	const void *	p1,
		const void *	p2
	)			`[static, protected]`

void Ogre::ProgressiveMesh::collapse ( PMVertex * collapser ) [protected]

Internal method, collapses vertex onto it's saved collapse target.

Remarks:: This updates the working triangle list to drop a triangle and recalculates the edge collapse costs around the collapse target. This also updates all the working vertex lists for the relevant buffer.

bool Ogre::ProgressiveMesh::collapseInvertsNormals	(	PMVertex *	src,
		PMVertex *	dest
	)			const `[protected]`

Internal calculation method, return true if edge collapse flip some neighbor face normal.

void Ogre::ProgressiveMesh::computeAllCosts ( void ) [protected]

Internal method to compute edge collapse costs for all buffers /.

Real Ogre::ProgressiveMesh::computeEdgeCollapseCost	(	PMVertex *	src,
		PMVertex *	dest
	)			const `[protected]`

Internal calculation method for deriving a collapse cost from u to v.

Real Ogre::ProgressiveMesh::computeEdgeCostAtVertex ( size_t vertIndex ) [protected]

Internal method evaluates all collapse costs from this vertex for every buffer and returns the worst.

Real Ogre::ProgressiveMesh::computeEdgeCostAtVertexForBuffer ( PMVertex * v ) [protected]

Internal method evaluates all collapse costs from this vertex and picks the lowest for a single buffer.

static void Ogre::ProgressiveMesh::createIndexMap	(	vector< IndexVertexPair >::type &	usedVertices,
		unsigned	allVertexCount,
		vector< unsigned >::type &	indexMap
	)			`[static, protected]`

During vertices defragmentation vertices are re-indexed, so old-to-new mapping is stored in index map by this function.

static void Ogre::ProgressiveMesh::createSimplifiedVertexData	(	vector< IndexVertexPair >::type &	usedVertices,
		VertexData *	inVData,
		VertexData *&	outVData,
		AxisAlignedBox &	aabox
	)			`[static, protected]`

Defragments vertices, removing unused. Useful if original geometry is redundant or dropped at all.

void Ogre::ProgressiveMesh::dumpContents ( const String & log ) [protected]

Internal debugging method.

static void Ogre::ProgressiveMesh::freeProgressiveMeshList ( ProgressiveMeshList * pmList ) [static, protected]

Deletes allocated internal resources.

static bool Ogre::ProgressiveMesh::generateLodLevels	(	Mesh *	pMesh,
		const LodValueList &	lodValues,
		VertexReductionQuota	reductionMethod,
		Real	reductionValue
	)			`[static]`

Automatically generates lower level of detail versions of this mesh for use when a simpler version of the model is acceptable for rendering.

Remarks:: There are 2 ways that you can create level-of-detail (LOD) versions of a mesh; the first is to call this method, which does fairly extensive calculations to work out how to simplify the mesh whilst having the minimum affect on the model. The alternative is to actually create simpler versions of the mesh yourself in a modelling tool, and having exported them, tell the 'master' mesh to use these alternative meshes for lower detail versions; this is done by calling the createManualLodLevel method.

: As well as creating the lower detail versions of the mesh, this method will also associate them with depth values. As soon as an object is at least as far away from the camera as the depth value associated with it's LOD, it will drop to that level of detail.

: I recommend calling this method before mesh export, not at runtime.

Parameters:

	lodValues	A list of lod values indicating the values at which new lods should be generated. These are 'user values', before being potentially transformed by the strategy, so for the distance strategy this is an unsquared distance for example.
	reductionMethod	The way to determine the number of vertices collapsed per LOD
	reductionValue	Meaning depends on reductionMethod, typically either the proportion of remaining vertices to collapse or a fixed number of vertices.

static MeshPtr Ogre::ProgressiveMesh::generateSimplifiedMesh	(	const String &	name,
		const String &	groupName,
		Mesh *	inMesh,
		bool	dropOriginalGeometry,
		const LodValueList &	lodValues,
		VertexReductionQuota	reductionMethod,
		Real	reductionValue,
		size_t *	removedVertexDuplicatesCount
	)			`[static]`

Automatically generates lower level of detail versions of this mesh for use when a simpler version of the model is acceptable for rendering.

Remarks:: Useful for importing of external mesh with unknown size and structure into something manageable.

: Simplifies vertex structure to { pos, norm, tex0 } stored in single stream. Removes unused vertices, performing reindexing.

: Can optionally discard first LOD level (i.e. original geometry), unused vertices would be removed.

static size_t Ogre::ProgressiveMesh::getInvalidCostCount ( ProgressiveMesh::ProgressiveMeshList & pmList ) [static, protected]

Internal methods for lazy costs recomputing.

CostIndexPair* Ogre::ProgressiveMesh::getNextCollapser ( ) [protected]

static void Ogre::ProgressiveMesh::getNextCollapser	(	ProgressiveMeshList &	pmList,
		ProgressiveMesh *&	pm,
		CostIndexPair *&	bestCollapser
	)			`[static, protected]`