Vortex Studio SDK Classes Documentation
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Vx::VxTriangleMeshBVTree Class Reference

Triangle mesh geometry for collision. More...

#include <Vx/VxTriangleMeshBVTree.h>

+ Inheritance diagram for Vx::VxTriangleMeshBVTree:

Public Types

enum  Options { OptionDefault = 0, OptionDeformAllowed = 2 }
 Deformation options for the triangle mesh. More...
 
- Public Types inherited from Vx::VxGeometry
enum  eSmallestEnclosingLockedAxes {
  kNoAxis = -1, kXAxis, kYAxis, kZAxis,
  kAllAxes
}
 Enum for specifying locked axes. More...
 

Public Member Functions

 VxTriangleMeshBVTree (int triCount, Options option=OptionDefault)
 Default constructor. More...
 
 VxTriangleMeshBVTree (const char *fileName, double scale, bool merge, double mergeEps, bool flipNormals, Options option=OptionDefault, int OBBSubtreeHeight=-1, VxTriangleFilter *filter=0)
 Constructor which creates a triangle mesh from a Wavefront obj file. More...
 
virtual ~VxTriangleMeshBVTree ()
 Destructor.
 
int addMergedTriangle (VxReal3Ptr v0, VxReal3Ptr v1, VxReal3Ptr v2, double epsilon=0)
 Adds triangles in the same way as addTriangle() does but also merges the vertices within the epsilon of vertices that were previously added using this function. More...
 
int addMergedTriangleByVertexCopy (VxReal3 v0, VxReal3 v1, VxReal3 v2, double epsilon=0)
 Same as addTriangleByVertexCopy() but also merges the vertices within the epsilon of vertices that were previously added using this function. More...
 
int addTriangle (VxReal3Ptr v0, VxReal3Ptr v1, VxReal3Ptr v2)
 Adds a triangle specified by the three vertex pointers. More...
 
int addTriangleByVertexCopy (VxReal3 v0, VxReal3 v1, VxReal3 v2)
 Adds a triangle specified by the three vertices that are copied. More...
 
virtual bool build ()
 Builds internal data structures to optimize the mesh geometry for collision. More...
 
virtual VxTriangleMeshBVTreeclone () const
 Clones the geometry. More...
 
void computeVerticesNormal (double hardEdgeThreshold)
 Precomputes all the vertex normals (and allocates the memory). More...
 
void deform ()
 Apply deformations, if the triangle mesh has been modified after build() has been called. More...
 
void deformInBoundingBox (double BBMinX, double BBMinY, double BBMinZ, double BBMaxX, double BBMaxY, double BBMaxZ)
 Recomputes as necessary for deformation. More...
 
virtual const char * getClassName () const
 Returns the class name.
 
void getMeshMeshContactCullingThresholds (double *distance, double *cosAngle)
 Returns the distance culling parameters. More...
 
void getOBBDepth (int *minDepth, int *maxDepth) const
 Returns the minimum and maximum leaf depth.
 
void getOrientedBoundingBox (VxReal44 relTM, double *dx, double *dy, double *dz) const
 Returns a tight, oriented bounding box around the mesh.
 
double getTriangleAreaThreshold () const
 Returns the minimum acceptable triangle area. More...
 
int getTriangleCount () const
 Returns the number of triangles in the mesh.
 
void getTriangleNormal (int index, VxVector3 *n) const
 Returns the normal for the triangle specified by index. More...
 
void getTriangleNormal (int index, VxReal3Ptr n) const
 Returns the normal for the triangle specified by index. More...
 
void getTriangleVertexPtrs (int index, VxReal3Ptr *v1, VxReal3Ptr *v2, VxReal3Ptr *v3) const
 Gets pointers to the vertices of the triangle specified by index.
 
void getVertexArray (VxReal3Ptr *v, int *vertexCount)
 Returns a pointer to the array of vertices specified in setVertexArray().
 
virtual bool isBuilt () const
 Returns true if build() has been called on this mesh.
 
void saveToFile (const char *fileName, bool merge, double mergeEps=0.0)
 Saves this mesh to a Wavefront obj file. More...
 
void setMeshMeshContactCullingThresholds (double distance, double cosAngle)
 Sets the distance culling parameters used to reduce the number of contacts for mesh-to-mesh collision. More...
 
void setOBBSubtreeHeight (int depth)
 Defines the transition between AABB and OBB in the collision tree. More...
 
void setTriangleAreaThreshold (double eps)
 Sets the minimum acceptable triangle area. More...
 
void setVertexArray (VxReal3Ptr v, int vertexCount)
 Sets a pointer to a user-defined array of vertices, for later retrieval by getVertexArray(). More...
 
void takeVertexOwnership ()
 Directs the triangle mesh to take ownership of an externally provided vertex and triangle list. More...
 
- Public Member Functions inherited from Vx::VxGeometry
VXCORE_SYMBOL VxGeometry ()
 Default constructor.
 
virtual VXCORE_SYMBOL ~VxGeometry ()
 Destructor.
 
VXCORE_SYMBOL void addOwner (Vx::VxCollisionGeometry *owner)
 Adds the collision geometry as owner .
 
virtual VXCORE_SYMBOL void computeSmallestEnclosing (const VxArray< VxVector3 > &points, VxTransform *inOutTM, VxGeometry::eSmallestEnclosingLockedAxes lockedAxes=VxGeometry::kNoAxis, bool isPositionLocked=false)
 Resizes the geometry and computes the new global position and orientation (inOutTm), such that the given set of points is covered while minimizing the volume. More...
 
virtual VXCORE_SYMBOL void computeSmallestEnclosing (const VxVector3 *inPoints, size_t numPoints, VxTransform *inOutTM, VxGeometry::eSmallestEnclosingLockedAxes lockedAxes=VxGeometry::kNoAxis, bool isPositionLocked=false)
 Resizes the geometry and computes the new global position and orientation (inOutTm), such that the given set of points is covered while minimizing the volume. More...
 
VXCORE_SYMBOL const
MaterialPointerArray
createMaterialMap (int size, VxMaterial *iDefaultMaterial)
 Creates a new material map of the specified size and with the specified default material. More...
 
VXCORE_SYMBOL void getBoundingBox (const VxReal44 tm, VxReal3 minCorner, VxReal3 maxCorner) const
 Gets the axis aligned bounding box for the geometry in a specified coordinate system. More...
 
VXCORE_SYMBOL void getBoundingSphere (VxReal3 center, double *radius) const
 Gets the bounding sphere of the geometry in local space. More...
 
VXCORE_SYMBOL double getBoundingSphereRadius () const
 Returns the bounding sphere radius in local coordinates.
 
VXCORE_SYMBOL const VxVector3getCOM ()
 Gets the center of mass from this geometry's mass properties . More...
 
VXCORE_SYMBOL void getExtremePoint (const VxReal44 tm, const VxReal3 inDir, VxReal3 outPoint) const
 Returns the extreme point in the specified direction on the geometry. More...
 
const MaterialPointerArraygetMaterialMap () const
 Returns the material map Only use getMaterialMap() to inspect the materials used in the VxGeometry. More...
 
VXCORE_SYMBOL const VxArray
< VxCollisionGeometry * > & 
getOwners () const
 Returns a list of the VxCollisionGeometry objects that own this geometry. More...
 
VXCORE_SYMBOL double getVolume ()
 Gets the volume from this geometry's mass properties . More...
 
VXCORE_SYMBOL bool hasOwner (Vx::VxCollisionGeometry *owner) const
 Returns true if the specified collision geometry owns this geometry.
 
VXCORE_SYMBOL bool isHole () const
 Returns true if the geometry type is one of the following: More...
 
VXCORE_SYMBOL void removeOwner (Vx::VxCollisionGeometry *owner)
 Removes the collision geometry as owner .
 
virtual VXCORE_SYMBOL void setDimensions (const Vx::VxVector3 &)
 Sets the size dimensions for the geometry. More...
 
VXCORE_SYMBOL bool setMaterial (int index, VxMaterial *material)
 Assigns a material to the geometry feature with the given index. More...
 
VXCORE_SYMBOL void updateOwners ()
 Updates the owners of this geometry (see addOwner() and VxCollisionGeometry::setAutomaticGeometryOwner). More...
 
- Public Member Functions inherited from Vx::VxBaseUserData
VXCORE_SYMBOL VxBaseUserData ()
 Default constructor.
 
virtual VXCORE_SYMBOL ~VxBaseUserData ()
 Destructor.
 
void * getUserDataPtr () const
 Get pointer to generic user data.
 
void setUserDataPtr (void *dataPtr)
 Set pointer to generic user data. More...
 
VXCORE_SYMBOL const
VxUserDataContainer
userData () const
 Accessor for user data (const version)
 
VXCORE_SYMBOL VxUserDataContaineruserData ()
 Accessor for user data.
 
- Public Member Functions inherited from Vx::VxBase
unsigned int getCreationIndex () const
 Access the creation index of the instance.
 
const char * getName () const
 Retrieves the name. More...
 
void setCombinedName (const char *base, const char *name, size_t i=0)
 Utility to set the name to a concatenate string = base_name_i.
 
virtual void setName (const char *name)
 Sets the name.
 
- Public Member Functions inherited from Vx::VxRefCount
VxRefCountoperator= (const VxRefCount &rhs)=delete
 Assignment operator must not be used.
 
void ref () const
 Increment the reference count by one, indicating that this object has another pointer which is referencing it.
 
int referenceCount () const
 Return the number pointers currently referencing this object.
 
void unref () const
 Decrement the reference count by one, indicating that a pointer to this object is no longer referencing it. More...
 
void unref_nodelete () const
 Decrement the reference count by one, indicating that a pointer to this object is referencing it. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from Vx::VxGeometry
static VXCORE_SYMBOL int getDefaultRequestID (const VxGeometry *g)
 Returns the default request id for the given geometry. More...
 

Detailed Description

Triangle mesh geometry for collision.

Defines a mesh of triangles with shared vertices.

Triangle meshes allow the most flexibility in representing the collision geometry for an object but are also less efficient than primitives or convex meshes.

The geometrical surface of an arbitrarily complex model can be specified as a collection of such triangles. Vertices are allocated and managed by the user. If two triangles share a vertex, it is preferable that the corresponding vertex pointers are also the same in each triangle.

Triangle vertices must be ordered counter-clockwise when seen from the outside of the object (right-hand rule) in order to produce correct normals.

Meshes can also be loaded from and saved to Wavefront obj files.

Member Enumeration Documentation

Deformation options for the triangle mesh.

Enumerator
OptionDefault 

No deformations are allowed on this mesh (default).

OptionDeformAllowed 

Deformation (vertex position change) is allowed in this mesh.

Produces a slightly less efficiently colliding mesh.

Constructor & Destructor Documentation

Vx::VxTriangleMeshBVTree::VxTriangleMeshBVTree ( int  triCount,
Options  option = OptionDefault 
)

Default constructor.

Creates a new triangle mesh geometry.

Use addTriangle() to add triangles, and build() to build the mesh. After the mesh is built, triangles cannot be added, and vertex positions cannot be changed.

The user must allocate storage for the vertices, since only pointers are used internally. You can use setVertexArray(), if desired, to maintain a reference to a user-defined vertex array.

Vx::VxTriangleMeshBVTree::VxTriangleMeshBVTree ( const char *  fileName,
double  scale,
bool  merge,
double  mergeEps,
bool  flipNormals,
Options  option = OptionDefault,
int  OBBSubtreeHeight = -1,
VxTriangleFilter filter = 0 
)

Constructor which creates a triangle mesh from a Wavefront obj file.

Parameters
[in]fileNameLocation of the loaded Wavefront obj file.
[in]scaleSpecifies a uniform scale which is applied to the mesh loaded from file.
[in]mergeSpecifies whether vertex merging should be performed to the mesh after being loaded from file. Vertex merging fuses vertices to a single vertex if they are closer than mergeEps.
[in]mergeEpsEpsilon used in vertex merging (see merge). Defines the maximum distance between two vertices which causes the vertice to be merged.
[in]flipNormalsSpecifies if mesh normals should be flipped after loading.
[in]optionMesh deformation options (see VxTriangleMeshBVTree::Options).
[in]OBBSubtreeHeightDefines the height of the OBB subtree (see setOBBSubtreeHeight()).
[in]filterAn optional triangle filter, used to filter out triangles loaded from the file. If NULL, no triangles will be filtered.

Member Function Documentation

int Vx::VxTriangleMeshBVTree::addMergedTriangle ( VxReal3Ptr  v0,
VxReal3Ptr  v1,
VxReal3Ptr  v2,
double  epsilon = 0 
)

Adds triangles in the same way as addTriangle() does but also merges the vertices within the epsilon of vertices that were previously added using this function.

If the vertices are already shared between neighbor triangles use addTriangle() instead.

Note
Triangles are assumed to be given so that their vertices are listed counter-clockwise as seen from the outside of the model. Normals are computed using this assumption, and point outside.
int Vx::VxTriangleMeshBVTree::addMergedTriangleByVertexCopy ( VxReal3  v0,
VxReal3  v1,
VxReal3  v2,
double  epsilon = 0 
)

Same as addTriangleByVertexCopy() but also merges the vertices within the epsilon of vertices that were previously added using this function.

If the vertices are already shared between neighbor triangles use addTriangleByVertexCopy() instead.

Triangles are assumed to be given so that their vertices are listed counter-clockwise as seen from the outside of the model. Normals are computed using this assumption, and point outside.

int Vx::VxTriangleMeshBVTree::addTriangle ( VxReal3Ptr  v0,
VxReal3Ptr  v1,
VxReal3Ptr  v2 
)

Adds a triangle specified by the three vertex pointers.

The vertices themselves are not stored, so the pointers must still be valid for the duration of the simulation.

Triangles whose area is less the value returned by getTriangleAreaThreshold() are ignored (not added) and the method returns 0. Otherwise the triangle is added and the method returns 1.

Triangles are assumed to be given so that their vertices are listed counter-clockwise as seen from the outside of the model. Normals are computed using this assumption, and point outside.

int Vx::VxTriangleMeshBVTree::addTriangleByVertexCopy ( VxReal3  v0,
VxReal3  v1,
VxReal3  v2 
)

Adds a triangle specified by the three vertices that are copied.

Triangles whose area is less the value returned by getTriangleAreaThreshold() are ignored (not added) and the method returns 0. Otherwise the triangle is added and the method returns 1.

Triangles are assumed to be given so that their vertices are listed counter-clockwise as seen from the outside of the model. Normals are computed using this assumption, and point outside.

virtual bool Vx::VxTriangleMeshBVTree::build ( )
virtual

Builds internal data structures to optimize the mesh geometry for collision.

After the mesh is built, triangles cannot be added, and vertex positions cannot be changed.

Reimplemented from Vx::VxGeometry.

virtual VxTriangleMeshBVTree* Vx::VxTriangleMeshBVTree::clone ( ) const
virtual

Clones the geometry.

Reimplemented in each sub-class.

Implements Vx::VxGeometry.

void Vx::VxTriangleMeshBVTree::computeVerticesNormal ( double  hardEdgeThreshold)

Precomputes all the vertex normals (and allocates the memory).

Parameters
[in]hardEdgeThresholdDefines the min dot product between 2 adjacent triangles's hard edge consideration.
void Vx::VxTriangleMeshBVTree::deform ( )

Apply deformations, if the triangle mesh has been modified after build() has been called.

Deformations will only take effect if this function is called.

Note
Mesh must have been created with the OptionDeformAllowed option to support deformations.
Warning
The changes will only take effect if automatic owner list maintenance is activated or the triangle mesh's owner collision geometry has been manually set (see VxGeometry::addOwner ).
void Vx::VxTriangleMeshBVTree::deformInBoundingBox ( double  BBMinX,
double  BBMinY,
double  BBMinZ,
double  BBMaxX,
double  BBMaxY,
double  BBMaxZ 
)

Recomputes as necessary for deformation.

Mesh must have been created with the OptionDeformAllowed option. Only vertices/triangles included in the given bounding box are updated. The Bounding Box is defined in the local frame of the mesh geometry (the same coordinate system as the vertices ).

Several calls to this function (one per independent group of deformations) can optimize the update of the collision model.

Warning
The Bounding Box given must contains the regions in space occupied by the modified vertices before their displacement.
void Vx::VxTriangleMeshBVTree::getMeshMeshContactCullingThresholds ( double *  distance,
double *  cosAngle 
)

Returns the distance culling parameters.

See Also
VincTriangleMeshSetContactCullingThresholds
double Vx::VxTriangleMeshBVTree::getTriangleAreaThreshold ( ) const

Returns the minimum acceptable triangle area.

Smaller triangles are ignored by addTriangle().

void Vx::VxTriangleMeshBVTree::getTriangleNormal ( int  index,
VxVector3 n 
) const

Returns the normal for the triangle specified by index.

The mesh must have already been built.

void Vx::VxTriangleMeshBVTree::getTriangleNormal ( int  index,
VxReal3Ptr  n 
) const

Returns the normal for the triangle specified by index.

The mesh must have already been built.

void Vx::VxTriangleMeshBVTree::saveToFile ( const char *  fileName,
bool  merge,
double  mergeEps = 0.0 
)

Saves this mesh to a Wavefront obj file.

Parameters
[in]fileNameTarget location of the Wavefront obj file.
[in]mergeSpecifies whether vertex merging should be performed to the mesh which is written to file. Vertex merging fuses vertices to a single vertex if they are closer than mergeEps.
[in]mergeEpsEpsilon used in vertex merging (see merge). Defines the maximum distance between two vertices which causes the vertice to be merged
void Vx::VxTriangleMeshBVTree::setMeshMeshContactCullingThresholds ( double  distance,
double  cosAngle 
)

Sets the distance culling parameters used to reduce the number of contacts for mesh-to-mesh collision.

Two contacts within distance are merged together. A merge also happens if the contact count is larger than contactMaxCount as defined in the request table. The cosAngle controls merging of the contact normal and penetration.

Warning
Larger values for distance will increase speed but might cause instability.
Smaller values for cosAngle will increase speed but might cause instability.
void Vx::VxTriangleMeshBVTree::setOBBSubtreeHeight ( int  depth)

Defines the transition between AABB and OBB in the collision tree.

This is the number of the deepest (close to triangles) levels represented by OBB (coarser levels will use AABB). By default if the triangle mesh is deformable, only one level of OBB is used (every other level uses AABB as it is faster to update).

When the mesh is cannot be deformed, every level uses OBB by default (more tight).

Warning
This must be set before the call to build()
void Vx::VxTriangleMeshBVTree::setTriangleAreaThreshold ( double  eps)

Sets the minimum acceptable triangle area.

Smaller triangles are ignored by addTriangle().

void Vx::VxTriangleMeshBVTree::setVertexArray ( VxReal3Ptr  v,
int  vertexCount 
)

Sets a pointer to a user-defined array of vertices, for later retrieval by getVertexArray().

This function is provided for convenience. The user must allocate storage for the vertices, since only pointers are used internally.

void Vx::VxTriangleMeshBVTree::takeVertexOwnership ( )

Directs the triangle mesh to take ownership of an externally provided vertex and triangle list.

This means that the lists will be deleted by the mesh (see setVertexArray()).