Package com.ardor3d.bounding

Enum Class CollisionTreeManager

java.lang.Object
java.lang.Enum<CollisionTreeManager>
com.ardor3d.bounding.CollisionTreeManager
All Implemented Interfaces:
Serializable, Comparable<CollisionTreeManager>, Constable
public enum CollisionTreeManager extends Enum<CollisionTreeManager>
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 primitive 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. maxPrimitivesPerLeaf defines the number of primitives a leaf node in the collision tree should maintain. The larger number of primitives maintained in a leaf node, the smaller the tree, but the larger the number of 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 primitive 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.

See Also:

  • Enum Constant Details

  • Field Details

    • DEFAULT_MAX_ELEMENTS

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

    • DEFAULT_MAX_PRIMITIVES_PER_LEAF

      public static final int DEFAULT_MAX_PRIMITIVES_PER_LEAF
      defines the default maximum number of primitives in a tree leaf.
      See Also:

  • Method Details

    • values

      public static CollisionTreeManager[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static CollisionTreeManager valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • 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(Mesh mesh)
      getCollisionTree obtains a collision tree that is assigned to a supplied Mesh. 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 given 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 Mesh, 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, Mesh 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

      protected void generateCollisionTree(CollisionTree tree, Mesh 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.

    • removeCollisionTree

      public void removeCollisionTree(Mesh 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(Mesh 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 primitives.
      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:

    • setTreeType

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

    • getMaxPrimitivesPerLeaf

      public int getMaxPrimitivesPerLeaf()
      returns the maximum number of primitives a leaf of the collision tree may contain.
      Returns:
      the maximum number of primitives a leaf may contain.

    • setMaxPrimitivesPerLeaf

      public void setMaxPrimitivesPerLeaf(int maxPrimitivesPerLeaf)
      set the maximum number of primitives a leaf of the collision tree may contain.
      Parameters:
      maxPrimitivesPerLeaf - the maximum number of primitives a leaf may contain.

    • getMaxElements

      public int getMaxElements()
      returns the maximum number of CollisionTree elements this manager will hold on to before starting to clear some.
      Returns:
      the maximum number of CollisionTree elements.

    • setMaxElements

      public void setMaxElements(int maxElements)
      set the maximum number of CollisionTree elements this manager will hold on to before starting to clear some.
      Parameters:
      maxElements - the maximum number of CollisionTree elements.

    • setProtected

      public void setProtected(Mesh meshToProtect)
      Add the given mesh to our "protected" list. This will signal to our cleanup operation that when deciding which trees to trim in an effort to keep our cache size to a certain desired size, do not trim the tree associated with this mesh.
      Parameters:
      meshToProtect - the mesh whose CollisionTree we want to protect.

    • removeProtected

      public void removeProtected(Mesh mesh)
      Removes the supplied mesh from the "protected" list.
      Parameters:
      mesh - the mesh to remove from the "protected" list

    • getProtectedMeshes

      public List<Mesh> getProtectedMeshes()
      Returns:
      an immutable copy of the list of protected meshes.