VRS::SceneGraphAnalyzer Class Reference

SceneGraphAnalyzer provides an overview of the singular objects in a given unknown SceneGraph, e.g. More...

#include <vrs/sg/scenegraphanalyzer.h>

Inheritance diagram for VRS::SceneGraphAnalyzer:

List of all members.

Public Types

enum ClipMode { CLIPMODE_INSIDE, CLIPMODE_PARTIALLY_INSIDE, CLIPMODE_PARTIALLY_OUTSIDE, CLIPMODE_OUTSIDE }

enum ClipMask { CLIPMASK_IGNORE_X = 1, CLIPMASK_IGNORE_Y = 2, CLIPMASK_IGNORE_Z = 4 }

enum ShapeType { SH_PolygonSet, SH_MappedVertexAttributeShapeGL }

Converts all PolygonSets to MappedVertexAttributeShapeGL or vice versa. More...

Static Public Member Functions

static SO< Iterator< const
ClassInfo * > > findClasses (SO< SceneThing > scene, bool traverseSceneThingsOnly=false)

findClasses() creates an iterator of all classes of the objects in the scene graph.

static Result findObjects (const ID &className, SO< SceneThing > scene, bool traverseSceneThingsOnly=false)

Given a class name and a SceneGraph this methods collects all RenderObjs of the given class.

static SO< Iterator< SO
< RenderObj > > > findLeafs (SO< SceneThing > scene)

Returns an iterator containing all leafs of the scene graph,.

static SO< SceneThing > createOptimizedScene (SO< SceneThing > scene, bool checkPreconditions=true, bool useStaticLighting=false)

Creates an optimized scene graph by removing redundancies.

template<class T>

static void replaceSceneObjects (SO< SceneThing > scene, const VRS::ID &className, SO< CallbackR2< Iterator< SO< SharedObj > > *, SharedObj *, T > > replaceCB, T userData)

replaceSceneObjects() traverses the scene graph.

static void replaceSceneObjects (SO< SceneThing > scene, const VRS::ID &className, SO< CallbackR1< Iterator< SO< SharedObj > > *, SharedObj * > > replaceCB=0)

static void clipScene (SO< SceneThing > target, const Bounds &bounds, ClipMode mode, ClipMask mask=ClipMask(0), bool enablePolygonSetClipping=false)

Removes all subgraphs and polygonset inside, intersecting, or not intersecting (dependent on 'mode') subgraphs and shapes.

static SO< Iterator< SO
< PolygonSet > > > collapseScene (SO< SceneThing > scene, bool changeScene=false)

Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.

static void extractTexturedShapes (std::vector< SceneGraphAnalyzer::TexturedShapes > &outTexturedShapes, SO< SceneThing > scene)

static void KillLowerLODs (SO< SceneThing > target)

Extracting all shapes from a Scene containing LOD nodes leads to merging of different LODs.

static SO< SceneThing > flattenScene (SO< SceneThing > scene)

Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.

static std::pair< SO
< SceneThing >, SO< SceneThing > > extractNormalMappedPolygonSets (SO< SceneThing > scene)

This method splits a scene into two parts: a) input scene without the parts described in b) b) all Polygonsets that occure after a NormalmapGL attribute in the scene graph Note:

Works only for simple scene containing polygonsets and attributes (no special nodes)
Not considered:

Other objects than polygonsets.

static std::pair< SO
< SceneThing >, SO< SceneThing > > splitScene (VRS::SO< VRS::SceneThing > scene, double alphaThreshold=0.9)

This method splits a scene into two parts: a) Completely opaque objects (first result) (all alpha values above "alphaThreshold") b) Semitransparent or complete objects (second result) Note:

Works only for simple scene containing polygonsets and attributes (no special nodes)
Considers texture alpha values and material properties (more exactly: the alpha value of the diffuse color for ShapeMaterialGL)
Not considered:

Alpha values in color iterators
Attributes of class Material
Different TexEnvGL variants: An object is considered to be opaque if and only if the material alpha value and all texture values are approximately 1.0.

static void convertToPrimitiveQuadTree (SO< SceneThing > &scene, unsigned int desiredLeafVertexCount=1000)

This method converts all PolygonSets and MappedVertexAttributeShapes into PrimitiveQuadTrees Only shapes with more than minVertexCount are affected.

static void forceShapeType (SO< SceneThing > scene, enum ShapeType)

static void forceTriangleMeshes (SO< SceneThing > scene, bool indexed)

Converts all PolygonSets in a scene to triangle meshes.

static void applyBatchSegmentation (SO< SceneThing > scene, unsigned int maxBatchSize=0xFFFF)

Vertex buffers of size 0xFFFF or less allow for using unsigned short indices, which are more efficient to store and render.

static void applyVertexCacheOptimization (SO< SceneThing > scene)

Sorts the triangles of each indexed triangle mesh according to vertex-cache coherency to optimize rendering performance.

static void optimizeMeshes (SO< SceneThing > scene, unsigned int maxBatchSize=0xFFFF)

Combines the methods above in a mesh optimization procedure.

static int countTriangles (SO< SceneThing > scene)

Traverse the scene with a visitor and counts the number of triangles for all occurrences of PolygonSet and MappedVertexAttributeShape and sums up their triangle count.

static void InvertOrientation (SO< SceneNode > target)

Traverses target with a visitor that calls invertOrientation() for all found PolygonSets and MappedVertexAttributeShapes.

static bool ValidatePolygonSets (SO< SceneNode > target, bool fixErrors=false)

Checks all PolygonSets in a Scene using PolygonSetTool::isValid().

Classes

struct Result

struct TexturedShapes

For simple scenes (no special nodes) containing Textures and PolygonSets, this method extracts all PolygonSets and corresponding textures. More...

Detailed Description

SceneGraphAnalyzer provides an overview of the singular objects in a given unknown SceneGraph, e.g.

provided by a loaded 3ds file. NOTE: If the scene graph contains some special SceneNodes which influence their contained objects (e.g. SceneAdjuster), their effect is not represented in the iterator of context objects. For this, the methods have a bool parameter traverseSceneThingsOnly. If it is set to true, all SceneNodes that are not instances of SceneThing (and therefore have unknown effect on its contained objects) are handled as atomic objects, i.e. they are not traversed.

Member Enumeration Documentation

enum VRS::SceneGraphAnalyzer::ClipMode

Enumerator:

CLIPMODE_INSIDE
CLIPMODE_PARTIALLY_INSIDE
CLIPMODE_PARTIALLY_OUTSIDE
CLIPMODE_OUTSIDE

enum VRS::SceneGraphAnalyzer::ClipMask

Enumerator:

CLIPMASK_IGNORE_X
CLIPMASK_IGNORE_Y
CLIPMASK_IGNORE_Z

enum VRS::SceneGraphAnalyzer::ShapeType

Converts all PolygonSets to MappedVertexAttributeShapeGL or vice versa.

Note the restrictions of the conversion, stated in mappedvertexattributeshapegl.h.

Enumerator:

SH_PolygonSet
SH_MappedVertexAttributeShapeGL

Member Function Documentation

static SO<Iterator<const ClassInfo*> > VRS::SceneGraphAnalyzer::findClasses	(	SO< SceneThing >	scene,
		bool	traverseSceneThingsOnly = `false`
	)			`[static]`

findClasses() creates an iterator of all classes of the objects in the scene graph.

More exactly the result contains one ClassInfo pointer for each class present in the scene.

static Result VRS::SceneGraphAnalyzer::findObjects	(	const ID &	className,
		SO< SceneThing >	scene,
		bool	traverseSceneThingsOnly = `false`
	)			`[static]`

Given a class name and a SceneGraph this methods collects all RenderObjs of the given class.

Usually it will be used for Shapes or more specificly for PolygonSets.

The 'objects' member of the Result contains pointers to all objects in the scene that are instances of the given class or a derivation. Multiply referenced objects will appear several times in the iterator.
For each object in the scene graph, a path from starting at the root defines the context of the object. (attributes, transforms etc. that are active when the object is rendered.) See class comment for the traverseSceneThingsOnly parameter.

static SO<Iterator<SO<RenderObj> > > VRS::SceneGraphAnalyzer::findLeafs ( SO< SceneThing > scene ) [static]

Returns an iterator containing all leafs of the scene graph,.

i.e. all RenderObjs being the last object contained in a SceneNode.

static SO<SceneThing> VRS::SceneGraphAnalyzer::createOptimizedScene	(	SO< SceneThing >	scene,
		bool	checkPreconditions = `true`,
		bool	useStaticLighting = `false`
	)			`[static]`

Creates an optimized scene graph by removing redundancies.

E.g. if there is a SceneThing with two subscenes both containing a pointer to the same texture and respectively a shape, it will be replaced by one subscene containing the texture reference and both shapes. If checkPreconditions is false, the preconditions described below are not checked. Therefore there is no warranty for the returned scene to contain the full information of the source scene. If checkPreconditions is true, NULL is returned for an unsuitable input scene graph.

Note:

The optimization is ONLY intended for description of shapes and render objects describing their appearance (e.g. imported 3ds-objects.) Therefore the optimized scene is a complete representation of the input scene ONLY if two conditions are met:
- All leaf objects (i.e. all objects without a successor in the traversal) are Shapes.
- All ScenenNodes are instances of class SceneThing. No other classes and no derivations of SceneThing are allowed, because the optimizer cannot know the effect of specific nodes on its contained objects. Therefore, special SceneNodes (and their content) are ignored.
In the current implementation, the optimizations works only for simple and obvious redundancies like the above example. It combines two shapes if and only if the objects on their path are the same and in the same order. The equality of the objects is also currently quite restricted. Objects are only detected as equal if
- They are the same (pointer equality)
- They have equal settings and are instances of one of the classes ColorAttribute, Material, FaceStyle, TexEnvGL.
In the current implementation the static lighting will not consider possible transformations that are applied to light sources in the scene graph.

If 'useStaticLighting' is true, the complete lighting is precalculated and stored in the color iterators of PolygonSets. (see lightingcalculator.h) Using static lighting can increase the rendering performance. It is, however, only useful if neither objects nor light sources are ever changed afterwards. In addition, static lighting does not provide specular reflections. The static lighting is only possible for PolygonSets. The scene must not contain any LightModelGLs already.

template<class T>

static void VRS::SceneGraphAnalyzer::replaceSceneObjects	(	SO< SceneThing >	scene,
		const VRS::ID &	className,
		SO< CallbackR2< Iterator< SO< SharedObj > > , SharedObj , T > >	replaceCB,
		T	userData
	)			`[inline, static]`

replaceSceneObjects() traverses the scene graph.

Each instance of 'className' (or a derivation) is removed and passed to the replaceCallback. All objects returned by the callback are inserted into the scene graph at the position where the previous object had been removed. If 'callback' is NULL, the objects are removed only. The pointer 'userData' is passed to the callback in each call. Note: The method works only for Objects that are contained in SceneThings (or derivations of SceneThing). For other nodes, it cannot be known how to replace objects.

static void VRS::SceneGraphAnalyzer::replaceSceneObjects	(	SO< SceneThing >	scene,
		const VRS::ID &	className,
		SO< CallbackR1< Iterator< SO< SharedObj > > , SharedObj > >	replaceCB = `0`
	)			`[static]`

static void VRS::SceneGraphAnalyzer::clipScene	(	SO< SceneThing >	target,
		const Bounds &	bounds,
		ClipMode	mode,
		ClipMask	mask = `ClipMask(0)`,
		bool	enablePolygonSetClipping = `false`
	)			`[static]`

Removes all subgraphs and polygonset inside, intersecting, or not intersecting (dependent on 'mode') subgraphs and shapes.

Note: clipScene does only subdivide SceneThings. Other kinds of scene nodes are handled like shapes, i.e. they are either removed or retained, but never split. Using 'mask' you can specify that only certain axes are considered, e.g., one can split in (x,y) by setting mask to CLIPMASK_IGNORE_Z. If enablePolygonSetClipping is true, polygonsets in the scene graph are clipped on a per triangle basis. When setting it to true, note:

It is only allowed for CLIPMODE_INSIDE
All polygonsets are converted to non-indexed triangle meshes. (points and lines will be lost!)

Note: In the current implementation, transformations are not yet considered!

static SO<Iterator<SO<PolygonSet> > > VRS::SceneGraphAnalyzer::collapseScene	(	SO< SceneThing >	scene,
		bool	changeScene = `false`
	)			`[static]`

Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.

The return value contains all appropriately transformed PolygonSets of the scene. If 'changeScene' is true, all transforms within the scene are removed and the vertices of the original PolygonSets within the scene are directly changed. In this case, the return iterator contains pointer to the transformed original PolygonSets. Otherwise, (for 'changeScene' = false) the returned iterator contains transformed copies of the scene PolygonSets. Note the following restrictions:

This method works only for SceneGraphs containing exclusively PolygonSets as shapes
This method assumes simple scene graphs without special nodes. (only SceneThings)

static void VRS::SceneGraphAnalyzer::extractTexturedShapes	(	std::vector< SceneGraphAnalyzer::TexturedShapes > &	outTexturedShapes,
		SO< SceneThing >	scene
	)			`[static]`

static void VRS::SceneGraphAnalyzer::KillLowerLODs ( SO< SceneThing > target ) [static]

Extracting all shapes from a Scene containing LOD nodes leads to merging of different LODs.

To avoid this, this method reduces all LOD nodes to their maximum LOD.

static SO<SceneThing> VRS::SceneGraphAnalyzer::flattenScene ( SO< SceneThing > scene ) [static]

Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.

The return scene graph is a copy of the original one. No objects are modified. The returned scene contains one sub-scene per PolygonSet and each sub-scene contains all attributes influencing the corresponding PolygonSet-object. Note the following restrictions:

This method works only for SceneGraphs containing exclusively PolygonSets as shapes
This method assumes simple scene graphs without special nodes. (only SceneThings)

static std::pair<SO<SceneThing>, SO<SceneThing> > VRS::SceneGraphAnalyzer::extractNormalMappedPolygonSets ( SO< SceneThing > scene ) [static]

This method splits a scene into two parts: a) input scene without the parts described in b) b) all Polygonsets that occure after a NormalmapGL attribute in the scene graph Note:

Works only for simple scene containing polygonsets and attributes (no special nodes)
Not considered:
- Other objects than polygonsets.

static std::pair<SO<SceneThing>, SO<SceneThing> > VRS::SceneGraphAnalyzer::splitScene	(	VRS::SO< VRS::SceneThing >	scene,
		double	alphaThreshold = `0.9`
	)			`[static]`

This method splits a scene into two parts: a) Completely opaque objects (first result) (all alpha values above "alphaThreshold") b) Semitransparent or complete objects (second result) Note:

Works only for simple scene containing polygonsets and attributes (no special nodes)
Considers texture alpha values and material properties (more exactly: the alpha value of the diffuse color for ShapeMaterialGL)
Not considered:
- Alpha values in color iterators
- Attributes of class Material
- Different TexEnvGL variants: An object is considered to be opaque if and only if the material alpha value and all texture values are approximately 1.0.

static void VRS::SceneGraphAnalyzer::convertToPrimitiveQuadTree	(	SO< SceneThing > &	scene,
		unsigned int	desiredLeafVertexCount = `1000`
	)			`[static]`

This method converts all PolygonSets and MappedVertexAttributeShapes into PrimitiveQuadTrees Only shapes with more than minVertexCount are affected.

No other optimizations are performed (use respective methods before this one)

static void VRS::SceneGraphAnalyzer::forceShapeType	(	SO< SceneThing >	scene,
		enum	ShapeType
	)			`[static]`

static void VRS::SceneGraphAnalyzer::forceTriangleMeshes	(	SO< SceneThing >	scene,
		bool	indexed
	)			`[static]`

Converts all PolygonSets in a scene to triangle meshes.

The following shapes will be ignored (=> left unchanged):

PolygonSets with more than one primitive type
PolygonSets with points or lines

static void VRS::SceneGraphAnalyzer::applyBatchSegmentation	(	SO< SceneThing >	scene,
		unsigned int	maxBatchSize = `0xFFFF`
	)			`[static]`

Vertex buffers of size 0xFFFF or less allow for using unsigned short indices, which are more efficient to store and render.

Therefore, this method splits large triangle meshes into a set of smaller ones, whereby each mesh has 0xFFFF or less vertices. This method has only effect for indexed triangle meshes.

static void VRS::SceneGraphAnalyzer::applyVertexCacheOptimization ( SO< SceneThing > scene ) [static]

Sorts the triangles of each indexed triangle mesh according to vertex-cache coherency to optimize rendering performance.

static void VRS::SceneGraphAnalyzer::optimizeMeshes	(	SO< SceneThing >	scene,
		unsigned int	maxBatchSize = `0xFFFF`
	)			`[static]`

Combines the methods above in a mesh optimization procedure.

As a result, all shapes (PolygonSets as well as MappedVertexAttributeShapes) are converted to vertex-cache-optimized batches of the given size. These batches are finally stored as MappedVertexAttributeShapes. Note: This optimization procedure does not yet address the problem of too many small shapes.

static int VRS::SceneGraphAnalyzer::countTriangles ( SO< SceneThing > scene ) [static]

Traverse the scene with a visitor and counts the number of triangles for all occurrences of PolygonSet and MappedVertexAttributeShape and sums up their triangle count.

Note: Only simple triangle meshes are supported. Other primitve types or shapes with range iterators are skipped.

static void VRS::SceneGraphAnalyzer::InvertOrientation ( SO< SceneNode > target ) [static]

Traverses target with a visitor that calls invertOrientation() for all found PolygonSets and MappedVertexAttributeShapes.

static bool VRS::SceneGraphAnalyzer::ValidatePolygonSets	(	SO< SceneNode >	target,
		bool	fixErrors = `false`
	)			`[static]`

Checks all PolygonSets in a Scene using PolygonSetTool::isValid().

If everything is okay, it returns true. If fixErrors is set, PolygonSetTool::ValidatePolygonSet is applied to all invalid shapes, so that the shape validity is ensured. Note:

This method does only work for PolygonSets.
Invalid meshes cannot actually be "repaired" due to missing information. The result will probably look not as expected. However, this method avoids the otherwise occuring crash.
NULL-Pointer shapes cannot be detected or fixed. They must be already avoided by shape readers.

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

scenegraphanalyzer.h


Public Types
enum	ClipMode { CLIPMODE_INSIDE, CLIPMODE_PARTIALLY_INSIDE, CLIPMODE_PARTIALLY_OUTSIDE, CLIPMODE_OUTSIDE }
enum	ClipMask { CLIPMASK_IGNORE_X = 1, CLIPMASK_IGNORE_Y = 2, CLIPMASK_IGNORE_Z = 4 }
enum	ShapeType { SH_PolygonSet, SH_MappedVertexAttributeShapeGL }
	Converts all PolygonSets to MappedVertexAttributeShapeGL or vice versa. More...
Static Public Member Functions
static SO< Iterator< const ClassInfo * > >	findClasses (SO< SceneThing > scene, bool traverseSceneThingsOnly=false)
	findClasses() creates an iterator of all classes of the objects in the scene graph.
static Result	findObjects (const ID &className, SO< SceneThing > scene, bool traverseSceneThingsOnly=false)
	Given a class name and a SceneGraph this methods collects all RenderObjs of the given class.
static SO< Iterator< SO < RenderObj > > >	findLeafs (SO< SceneThing > scene)
	Returns an iterator containing all leafs of the scene graph,.
static SO< SceneThing >	createOptimizedScene (SO< SceneThing > scene, bool checkPreconditions=true, bool useStaticLighting=false)
	Creates an optimized scene graph by removing redundancies.
template<class T>
static void	replaceSceneObjects (SO< SceneThing > scene, const VRS::ID &className, SO< CallbackR2< Iterator< SO< SharedObj > > , SharedObj , T > > replaceCB, T userData)
	replaceSceneObjects() traverses the scene graph.
static void	replaceSceneObjects (SO< SceneThing > scene, const VRS::ID &className, SO< CallbackR1< Iterator< SO< SharedObj > > , SharedObj > > replaceCB=0)
static void	clipScene (SO< SceneThing > target, const Bounds &bounds, ClipMode mode, ClipMask mask=ClipMask(0), bool enablePolygonSetClipping=false)
	Removes all subgraphs and polygonset inside, intersecting, or not intersecting (dependent on 'mode') subgraphs and shapes.
static SO< Iterator< SO < PolygonSet > > >	collapseScene (SO< SceneThing > scene, bool changeScene=false)
	Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.
static void	extractTexturedShapes (std::vector< SceneGraphAnalyzer::TexturedShapes > &outTexturedShapes, SO< SceneThing > scene)
static void	KillLowerLODs (SO< SceneThing > target)
	Extracting all shapes from a Scene containing LOD nodes leads to merging of different LODs.
static SO< SceneThing >	flattenScene (SO< SceneThing > scene)
	Collects all PolygonSets of a scene and transforms them according to the corresponding transforms in the scene graph.
static std::pair< SO < SceneThing >, SO< SceneThing > >	extractNormalMappedPolygonSets (SO< SceneThing > scene)
	This method splits a scene into two parts: a) input scene without the parts described in b) b) all Polygonsets that occure after a NormalmapGL attribute in the scene graph Note: Works only for simple scene containing polygonsets and attributes (no special nodes) Not considered: Other objects than polygonsets.
static std::pair< SO < SceneThing >, SO< SceneThing > >	splitScene (VRS::SO< VRS::SceneThing > scene, double alphaThreshold=0.9)
	This method splits a scene into two parts: a) Completely opaque objects (first result) (all alpha values above "alphaThreshold") b) Semitransparent or complete objects (second result) Note: Works only for simple scene containing polygonsets and attributes (no special nodes) Considers texture alpha values and material properties (more exactly: the alpha value of the diffuse color for ShapeMaterialGL) Not considered: Alpha values in color iterators Attributes of class Material Different TexEnvGL variants: An object is considered to be opaque if and only if the material alpha value and all texture values are approximately 1.0.
static void	convertToPrimitiveQuadTree (SO< SceneThing > &scene, unsigned int desiredLeafVertexCount=1000)
	This method converts all PolygonSets and MappedVertexAttributeShapes into PrimitiveQuadTrees Only shapes with more than minVertexCount are affected.
static void	forceShapeType (SO< SceneThing > scene, enum ShapeType)
static void	forceTriangleMeshes (SO< SceneThing > scene, bool indexed)
	Converts all PolygonSets in a scene to triangle meshes.
static void	applyBatchSegmentation (SO< SceneThing > scene, unsigned int maxBatchSize=0xFFFF)
	Vertex buffers of size 0xFFFF or less allow for using unsigned short indices, which are more efficient to store and render.
static void	applyVertexCacheOptimization (SO< SceneThing > scene)
	Sorts the triangles of each indexed triangle mesh according to vertex-cache coherency to optimize rendering performance.
static void	optimizeMeshes (SO< SceneThing > scene, unsigned int maxBatchSize=0xFFFF)
	Combines the methods above in a mesh optimization procedure.
static int	countTriangles (SO< SceneThing > scene)
	Traverse the scene with a visitor and counts the number of triangles for all occurrences of PolygonSet and MappedVertexAttributeShape and sums up their triangle count.
static void	InvertOrientation (SO< SceneNode > target)
	Traverses target with a visitor that calls invertOrientation() for all found PolygonSets and MappedVertexAttributeShapes.
static bool	ValidatePolygonSets (SO< SceneNode > target, bool fixErrors=false)
	Checks all PolygonSets in a Scene using PolygonSetTool::isValid().
Classes
struct	Result
struct	TexturedShapes
	For simple scenes (no special nodes) containing Textures and PolygonSets, this method extracts all PolygonSets and corresponding textures. More...