PxBVH

Defined in include/geometry/PxBVH.h

Structs

class PxBVH : public PxBase

Class representing a bounding volume hierarchy.

PxBVH can be provided to PxScene::addActor. In this case the scene query pruning structure inside PhysX SDK will store/update one bound per actor. The scene queries against such an actor will query actor bounds and then make a local space query against the provided BVH, which is in actor’s local space.

PxBVH can also be used as a standalone data-structure for arbitrary purposes, unrelated to PxScene / PxActor.

See also

PxScene::addActor

Public Functions

virtual bool raycast(const PxVec3 &origin, const PxVec3 &unitDir, float maxDist, RaycastCallback &cb, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Raycast test against a BVH.

Parameters

  • origin – [in] The origin of the ray.

  • unitDir – [in] Normalized direction of the ray.

  • maxDist – [in] Maximum ray length, has to be in the [0, inf) range

  • cb – [in] Raycast callback, called once per hit

  • queryFlags – [in] Optional flags controlling the query.

Returns

false if query has been aborted

virtual bool sweep(const PxGeometry &geom, const PxTransform &pose, const PxVec3 &unitDir, float maxDist, RaycastCallback &cb, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Sweep test against a BVH.

Parameters

  • geom – [in] The query volume

  • pose – [in] The pose of the query volume

  • unitDir – [in] Normalized direction of the sweep.

  • maxDist – [in] Maximum sweep length, has to be in the [0, inf) range

  • cb – [in] Raycast callback, called once per hit

  • queryFlags – [in] Optional flags controlling the query.

Returns

false if query has been aborted

virtual bool overlap(const PxGeometry &geom, const PxTransform &pose, OverlapCallback &cb, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Overlap test against a BVH.

Parameters

  • geom – [in] The query volume

  • pose – [in] The pose of the query volume

  • cb – [in] Overlap callback, called once per hit

  • queryFlags – [in] Optional flags controlling the query.

Returns

false if query has been aborted

virtual bool cull(PxU32 nbPlanes, const PxPlane *planes, OverlapCallback &cb, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Frustum culling test against a BVH.

This is similar in spirit to an overlap query using a convex object around the frustum. However this specialized query has better performance, and can support more than the 6 planes of a frustum, which can be useful in portal-based engines.

On the other hand this test only returns a conservative number of bounds, i.e. some of the returned bounds may actually be outside the frustum volume, close to it but not touching it. This is usually an ok performance trade-off when the function is used for view-frustum culling.

Parameters

  • nbPlanes – [in] Number of planes. Only 32 planes max are supported.

  • planes – [in] Array of planes, should be in the same space as the BVH.

  • cb – [in] Overlap callback, called once per visible object

  • queryFlags – [in] Optional flags controlling the query.

Returns

false if query has been aborted

virtual PxU32 getNbBounds() const = 0

Returns the number of bounds in the BVH.

You can use getBounds() to retrieve the bounds.

See also

getBounds() getBoundsForModification()

Note

These are the user-defined bounds passed to the BVH builder, not the internal bounds around each BVH node.

Returns

Number of bounds in the BVH.

virtual const PxBounds3 *getBounds() const = 0

Retrieve the read-only bounds in the BVH.

See also

PxBounds3 getNbBounds() getBoundsForModification()

Note

These are the user-defined bounds passed to the BVH builder, not the internal bounds around each BVH node.

inline PxBounds3 *getBoundsForModification()

Retrieve the bounds in the BVH.

These bounds can be modified. Call refit() after modifications are done.

See also

PxBounds3 getNbBounds() getBounds() refit() updateBounds() partialRefit()

Note

These are the user-defined bounds passed to the BVH builder, not the internal bounds around each BVH node.

virtual void refit() = 0

Refit the BVH.

This function “refits” the tree, i.e. takes the new (leaf) bounding boxes into account and recomputes all the BVH bounds accordingly. This is an O(n) operation with n = number of bounds in the BVH.

This works best with minor bounds modifications, i.e. when the bounds remain close to their initial values. With large modifications the tree quality degrades more and more, and subsequent query performance suffers. It might be a better strategy to create a brand new BVH if bounds change drastically.

This function refits the whole tree after an arbitrary number of bounds have potentially been modified by users (via getBoundsForModification()). If you only have a small number of bounds to update, it might be more efficient to use setBounds() and partialRefit() instead.

See also

getNbBounds() getBoundsForModification() updateBounds() partialRefit()

virtual bool updateBounds(PxU32 boundsIndex, const PxBounds3 &newBounds) = 0

Update single bounds.

This is an alternative to getBoundsForModification() / refit(). If you only have a small set of bounds to update, it can be inefficient to call the refit() function, because it refits the whole BVH.

Instead, one can update individual bounds with this updateBounds() function. It sets the new bounds and marks the corresponding BVH nodes for partial refit. Once all the individual bounds have been updated, call partialRefit() to only refit the subset of marked nodes.

See also

getNbBounds() getBoundsForModification() refit() partialRefit()

Parameters

  • boundsIndex – [in] Index of updated bounds. Valid range is between 0 and getNbBounds().

  • newBounds – [in] Updated bounds.

Returns

true if success

virtual void partialRefit() = 0

Refits subset of marked nodes.

This is an alternative to the refit() function, to be called after updateBounds() calls. See updateBounds() for details.

See also

getNbBounds() getBoundsForModification() refit() updateBounds()

virtual bool traverse(TraversalCallback &cb) const = 0

Generic BVH traversal function.

This can be used to implement custom BVH traversal functions if provided ones are not enough. In particular this can be used to visualize the tree’s bounds.

Parameters

cb – [in] Traversal callback, called for each visited node

Returns

false if query has been aborted

inline virtual const char *getConcreteTypeName() const

Returns string name of dynamic type.

Returns

Class name of most derived type of this object.

virtual void release() = 0

Releases the PxBase instance, please check documentation of release in derived class.

template<class T>
inline T *is()
template<class T>
inline const T *is() const
inline PxType getConcreteType() const

Returns concrete type of object.

See also

PxConcreteType

Returns

PxConcreteType::Enum of serialized object

inline void setBaseFlag(PxBaseFlag::Enum flag, bool value)

Set PxBaseFlag

Parameters

  • flag – [in] The flag to be set

  • value – [in] The flags new value

inline void setBaseFlags(PxBaseFlags inFlags)

Set PxBaseFlags

See also

PxBaseFlags

Parameters

inFlags – [in] The flags to be set

inline PxBaseFlags getBaseFlags() const

Returns PxBaseFlags.

See also

PxBaseFlags

Returns

PxBaseFlags

inline virtual bool isReleasable() const

Whether the object is subordinate.

A class is subordinate, if it can only be instantiated in the context of another class.

See also

PxSerialization::isSerializable

Returns

Whether the class is subordinate

Protected Functions

inline PxBVH(PxType concreteType, PxBaseFlags baseFlags)
inline PxBVH(PxBaseFlags baseFlags)
inline virtual ~PxBVH()
inline virtual bool isKindOf(const char *name) const

Returns whether a given type name matches with the type of this instance.

template<class T>
inline bool typeMatch() const

Protected Attributes

PxType mConcreteType
PxBaseFlags mBaseFlags
PxU32 mBuiltInRefCount
struct OverlapCallback

Public Functions

inline OverlapCallback()
inline virtual ~OverlapCallback()
virtual bool reportHit(PxU32 boundsIndex) = 0
struct RaycastCallback

Public Functions

inline RaycastCallback()
inline virtual ~RaycastCallback()
virtual bool reportHit(PxU32 boundsIndex, PxReal &distance) = 0
struct TraversalCallback

Public Functions

inline TraversalCallback()
inline virtual ~TraversalCallback()
virtual bool visitNode(const PxBounds3 &bounds) = 0
virtual bool reportLeaf(PxU32 nbPrims, const PxU32 *prims) = 0