com.jme.bounding
Class CollisionTreeManager

java.lang.Object
  extended by com.jme.bounding.CollisionTreeManager

public class CollisionTreeManager
extends java.lang.Object

CollisionTreeManager is an automated system for handling the creation and deletion of CollisionTrees. The manager maintains a cache map of currently generated collision trees. The collision system itself requests a collision tree from the manager via the getCollisionTree method. The cache is checked for the tree, and if it is available, sent to the caller. If the tree is not in the cache, and generateTrees is true, a new CollisionTree is generated on the fly and sent to the caller. When a new tree is created, the cache size is compared to the maxElements value. If the cache is larger than maxElements, the cache is sent to the CollisionTreeController for cleaning. There are a number of settings that can be used to control how trees are generated. First, generateTrees denotes whether the manager should be creating trees at all. This is set to true by default. doSort defines if the CollisionTree triangle array should be sorted as it is built. This is false by default. Sorting is beneficial for model data that is not well ordered spatially. This occurrence is rare, and sorting slows creation time. It is, therefore, only to be used when model data requires it. maxTrisPerLeaf defines the number of triangles a leaf node in the collision tree should maintain. The larger number of triangles maintained in a leaf node, the smaller the tree, but the larger the number of triangle checks during a collision. By default, this value is set to 16. maxElements defines the maximum number of trees that will be maintained before clean-up is required. A collision tree is defined for each mesh that is being collided with. The user should determine the optimal number of trees to maintain (a memory/performance tradeoff), based on the number of meshes, their population density and their triangle size. By default, this value is set to 25. The type of trees that will be generated is defined by the treeType value, where valid options are define in CollisionTree as AABB_TREE, OBB_TREE and SPHERE_TREE. You can set the functionality of how trees are removed from the cache by providing the manager with a CollisionTreeController implementation. By default, the manager will use the UsageTreeController for removing trees, but any other CollisionTreeController is acceptable. You can create protected tree manually. These are collision trees that you request the manager to create and not allow them to be removed by the CollisionTreeController.

Author:
Mark Powell
See Also:
CollisionTree, CollisionTreeController

Field Summary
static int DEFAULT_MAX_ELEMENTS
          defines the default maximum number of trees to maintain.
static int DEFAULT_MAX_TRIS_PER_LEAF
          defines the default maximum number of triangles in a tree leaf.
 
Method Summary
 void generateCollisionTree(CollisionTree.Type type, Spatial object, boolean protect)
          creates a new collision tree for the provided spatial.
 CollisionTree generateCollisionTree(CollisionTree.Type type, TriMesh mesh, boolean protect)
          generates a new tree for the associated mesh.
 CollisionTree generateCollisionTree(CollisionTree tree, TriMesh mesh, boolean protect)
          generates a new tree for the associated mesh.
 CollisionTree getCollisionTree(TriMesh mesh)
          getCollisionTree obtains a collision tree that is assigned to a supplied TriMesh.
static CollisionTreeManager getInstance()
          retrieves the singleton instance of the CollisionTreeManager.
 int getMaxTrisPerLeaf()
          returns the maximum number of triangles a leaf of the collision tree will contain.
 CollisionTree.Type getTreeType()
           
 boolean isDoSort()
          returns true if the manager is set to sort new generated trees.
 boolean isGenerateTrees()
          returns true if the manager will automatically generate new trees as needed, false otherwise.
 void removeCollisionTree(Spatial object)
          removes all collision trees associated with a Spatial object.
 void removeCollisionTree(TriMesh mesh)
          removes a collision tree from the manager based on the mesh supplied.
 void setCollisionTreeController(CollisionTreeController treeRemover)
          sets the CollisionTreeController used for cleaning the cache when the maximum number of elements is reached.
 void setDoSort(boolean doSort)
          set if this manager should have newly generated trees sort triangles.
 void setGenerateTrees(boolean generateTrees)
          set if this manager should generate new trees as needed.
 void setMaxTrisPerLeaf(int maxTrisPerLeaf)
          set the maximum number of triangles a leaf of the collision tree will contain.
 void setTreeType(CollisionTree.Type treeType)
           
 void updateCollisionTree(Spatial object)
          updates the existing tree(s) for a supplied spatial.
 void updateCollisionTree(TriMesh mesh)
          updates the existing tree for a supplied mesh.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX_ELEMENTS

public static final int DEFAULT_MAX_ELEMENTS
defines the default maximum number of trees to maintain.

See Also:
Constant Field Values

DEFAULT_MAX_TRIS_PER_LEAF

public static final int DEFAULT_MAX_TRIS_PER_LEAF
defines the default maximum number of triangles in a tree leaf.

See Also:
Constant Field Values
Method Detail

getInstance

public static CollisionTreeManager getInstance()
retrieves the singleton instance of the CollisionTreeManager.

Returns:
the singleton instance of the manager.

setCollisionTreeController

public void setCollisionTreeController(CollisionTreeController treeRemover)
sets the CollisionTreeController used for cleaning the cache when the maximum number of elements is reached.

Parameters:
treeRemover - the controller used to clean the cache.

getCollisionTree

public CollisionTree getCollisionTree(TriMesh mesh)
getCollisionTree obtains a collision tree that is assigned to a supplied TriMesh. The cache is checked for a pre-existing tree, if none is available and generateTrees is true, a new tree is created and returned.

Parameters:
mesh - the mesh to use as the key for the tree to obtain.
Returns:
the tree associated with a triangle mesh

generateCollisionTree

public void generateCollisionTree(CollisionTree.Type type,
                                  Spatial object,
                                  boolean protect)
creates a new collision tree for the provided spatial. If the spatial is a node, it recursively calls generateCollisionTree for each child. If it is a TriMesh, a call to generateCollisionTree is made for each mesh. If this tree(s) is to be protected, i.e. not deleted by the CollisionTreeController, set protect to true.

Parameters:
type - the type of collision tree to generate.
object - the Spatial to generate tree(s) for.
protect - true to keep these trees from being removed, false otherwise.

generateCollisionTree

public CollisionTree generateCollisionTree(CollisionTree.Type type,
                                           TriMesh mesh,
                                           boolean protect)
generates a new tree for the associated mesh. The type is provided and a new tree is constructed of this type. The tree is placed in the cache. If the cache's size then becomes too large, the cache is sent to the CollisionTreeController for clean-up. If this tree is to be protected, i.e. protected from the CollisionTreeController, set protect to true.

Parameters:
type - the type of collision tree to generate.
mesh - the mesh to generate the tree for.
protect - true if this tree is to be protected, false otherwise.
Returns:
the new collision tree.

generateCollisionTree

public CollisionTree generateCollisionTree(CollisionTree tree,
                                           TriMesh mesh,
                                           boolean protect)
generates a new tree for the associated mesh. It is provided with a pre-existing, non-null tree. The tree is placed in the cache. If the cache's size then becomes too large, the cache is sent to the CollisionTreeController for clean-up. If this tree is to be protected, i.e. protected from the CollisionTreeController, set protect to true.

Parameters:
tree - the tree to use for generation
mesh - the mesh to generate the tree for.
protect - true if this tree is to be protected, false otherwise.
Returns:
the new collision tree.

removeCollisionTree

public void removeCollisionTree(TriMesh mesh)
removes a collision tree from the manager based on the mesh supplied.

Parameters:
mesh - the mesh to remove the corresponding collision tree.

removeCollisionTree

public void removeCollisionTree(Spatial object)
removes all collision trees associated with a Spatial object.

Parameters:
object - the spatial to remove all collision trees from.

updateCollisionTree

public void updateCollisionTree(TriMesh mesh)
updates the existing tree for a supplied mesh. If this tree does not exist, the tree is not updated. If the tree is not in the cache, no further operations are handled.

Parameters:
mesh - the mesh key for the tree to update.

updateCollisionTree

public void updateCollisionTree(Spatial object)
updates the existing tree(s) for a supplied spatial. If this tree does not exist, the tree is not updated. If the tree is not in the cache, no further operations are handled.

Parameters:
object - the object on which to update the tree.

isDoSort

public boolean isDoSort()
returns true if the manager is set to sort new generated trees. False otherwise.

Returns:
true to sort tree, false otherwise.

setDoSort

public void setDoSort(boolean doSort)
set if this manager should have newly generated trees sort triangles.

Parameters:
doSort - true to sort trees, false otherwise.

isGenerateTrees

public boolean isGenerateTrees()
returns true if the manager will automatically generate new trees as needed, false otherwise.

Returns:
true if this manager is generating trees, false otherwise.

setGenerateTrees

public void setGenerateTrees(boolean generateTrees)
set if this manager should generate new trees as needed.

Parameters:
generateTrees - true to generate trees, false otherwise.

getTreeType

public CollisionTree.Type getTreeType()
Returns:
the type of tree the manager will create.
See Also:
CollisionTree.Type

setTreeType

public void setTreeType(CollisionTree.Type treeType)
Parameters:
treeType - the type of tree to create.
See Also:
CollisionTree.Type

getMaxTrisPerLeaf

public int getMaxTrisPerLeaf()
returns the maximum number of triangles a leaf of the collision tree will contain.

Returns:
the maximum number of triangles a leaf will contain.

setMaxTrisPerLeaf

public void setMaxTrisPerLeaf(int maxTrisPerLeaf)
set the maximum number of triangles a leaf of the collision tree will contain.

Parameters:
maxTrisPerLeaf - the maximum number of triangles a leaf will contain.