PxSceneQuerySystem

Inheritance Relationships

Base Type

public PxSceneQuerySystemBase (PxSceneQuerySystemBase)

Derived Type

public PxCustomSceneQuerySystem (PxCustomSceneQuerySystem)

class PxSceneQuerySystem : public PxSceneQuerySystemBase 

Scene-queries external sub-system for PxScene-based objects.

The default PxScene has hardcoded support for 2 regular pruners + 1 compound pruner, but these interfaces should work with multiple pruners.

Regular shapes are traditional PhysX shapes that belong to an actor. That actor can be a compound, i.e. it has more than one shape. All of these go to the regular pruners. This is important because it might be misleading: by default all shapes go to one of the two regular pruners, even shapes that belong to compound actors.

For compound actors, adding all the actor’s shapes individually to the SQ system can be costly, since all the corresponding bounds will always move together and remain close together - that can put a lot of stress on the code that updates the SQ spatial structures. In these cases it can be more efficient to add the compound’s bounds (i.e. the actor’s bounds) to the system, as the first level of a bounds hierarchy. The scene queries would then be performed against the actor’s bounds first, and only visit the shapes’ bounds second. This is only useful for actors that have more than one shape, i.e. compound actors. Such actors added to the SQ system are thus called “SQ compounds”. These objects are managed by the “compound pruner”, which is only used when an explicit SQ compound is added to the SQ system via the addSQCompound call. So in the end one has to distinguish between:

a “compound shape”, which is added to regular pruners as its own individual entity.
an “SQ compound shape”, which is added to the compound pruner as a subpart of an SQ compound actor.

A compound shape has an invalid compound ID, since it does not belong to an SQ compound. An SQ compound shape has a valid compound ID, that identifies its SQ compound owner.

See also

PxScene PxSceneQuerySystemBase

Subclassed by PxCustomSceneQuerySystem

Scene Query

virtual void setDynamicTreeRebuildRateHint(PxU32 dynamicTreeRebuildRateHint) = 0

Sets the rebuild rate of the dynamic tree pruning structures.

Parameters: dynamicTreeRebuildRateHint – [in] Rebuild rate of the dynamic tree pruning structures.

virtual PxU32 getDynamicTreeRebuildRateHint() const = 0

Retrieves the rebuild rate of the dynamic tree pruning structures.

Returns: The rebuild rate of the dynamic tree pruning structures.

virtual void forceRebuildDynamicTree(PxU32 prunerIndex) = 0

Forces dynamic trees to be immediately rebuilt.

Note

PxScene will call this function with the PX_SCENE_PRUNER_STATIC or PX_SCENE_PRUNER_DYNAMIC value.

Parameters: prunerIndex – [in] Index of pruner containing the dynamic tree to rebuild

virtual void setUpdateMode(PxSceneQueryUpdateMode::Enum updateMode) = 0

Sets scene query update mode.

See also

PxSceneQueryUpdateMode::Enum

Parameters: updateMode – [in] Scene query update mode.

virtual PxSceneQueryUpdateMode::Enum getUpdateMode() const = 0

Gets scene query update mode.

See also

PxSceneQueryUpdateMode::Enum

Returns: Current scene query update mode.

virtual PxU32 getStaticTimestamp() const = 0

Retrieves the system’s internal scene query timestamp, increased each time a change to the static scene query structure is performed.

Returns: scene query static timestamp

virtual void flushUpdates() = 0

Flushes any changes to the scene query representation.

This method updates the state of the scene query representation to match changes in the scene state.

By default, these changes are buffered until the next query is submitted. Calling this function will not change the results from scene queries, but can be used to ensure that a query will not perform update work in the course of its execution.

A thread performing updates will hold a write lock on the query structure, and thus stall other querying threads. In multithread scenarios it can be useful to explicitly schedule the period where this lock may be held for a significant period, so that subsequent queries issued from multiple threads will not block.

virtual bool raycast(const PxVec3 &origin, const PxVec3 &unitDir, const PxReal distance, PxRaycastCallback &hitCall, PxHitFlags hitFlags = PxHitFlag::eDEFAULT, const PxQueryFilterData &filterData = PxQueryFilterData(), PxQueryFilterCallback *filterCall = NULL, const PxQueryCache *cache = NULL, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Performs a raycast against objects in the scene, returns results in a PxRaycastBuffer object or via a custom user callback implementation inheriting from PxRaycastCallback.

Note

Touching hits are not ordered.

Note

Shooting a ray from within an object leads to different results depending on the shape type. Please check the details in user guide article SceneQuery. User can ignore such objects by employing one of the provided filter mechanisms.

Parameters

origin – [in] Origin of the ray.
unitDir – [in] Normalized direction of the ray.
distance – [in] Length of the ray. Has to be in the [0, inf) range.
hitCall – [out] Raycast hit buffer or callback object used to report raycast hits.
hitFlags – [in] Specifies which properties per hit should be computed and returned via the hit callback.
filterData – [in] Filtering data passed to the filter shader.
filterCall – [in] Custom filtering logic (optional). Only used if the corresponding PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
cache – [in] Cached hit shape (optional). Ray is tested against cached shape first. If no hit is found the ray gets queried against the scene. Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit. Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
queryFlags – [in] Optional flags controlling the query.

Returns

True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.

virtual bool sweep(const PxGeometry &geometry, const PxTransform &pose, const PxVec3 &unitDir, const PxReal distance, PxSweepCallback &hitCall, PxHitFlags hitFlags = PxHitFlag::eDEFAULT, const PxQueryFilterData &filterData = PxQueryFilterData(), PxQueryFilterCallback *filterCall = NULL, const PxQueryCache *cache = NULL, const PxReal inflation = 0.0f, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Performs a sweep test against objects in the scene, returns results in a PxSweepBuffer object or via a custom user callback implementation inheriting from PxSweepCallback.

Note

Touching hits are not ordered.

Note

If a shape from the scene is already overlapping with the query shape in its starting position, the hit is returned unless eASSUME_NO_INITIAL_OVERLAP was specified.

Parameters

geometry – [in] Geometry of object to sweep (supported types are: box, sphere, capsule, convex).
pose – [in] Pose of the sweep object.
unitDir – [in] Normalized direction of the sweep.
distance – [in] Sweep distance. Needs to be in [0, inf) range and >0 if eASSUME_NO_INITIAL_OVERLAP was specified. Will be clamped to PX_MAX_SWEEP_DISTANCE.
hitCall – [out] Sweep hit buffer or callback object used to report sweep hits.
hitFlags – [in] Specifies which properties per hit should be computed and returned via the hit callback.
filterData – [in] Filtering data and simple logic.
filterCall – [in] Custom filtering logic (optional). Only used if the corresponding PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
cache – [in] Cached hit shape (optional). Sweep is performed against cached shape first. If no hit is found the sweep gets queried against the scene. Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit. Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
inflation – [in] This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal. Note: ePRECISE_SWEEP doesn’t support inflation. Therefore the sweep will be performed with zero inflation.
queryFlags – [in] Optional flags controlling the query.

Returns

True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.

virtual bool overlap(const PxGeometry &geometry, const PxTransform &pose, PxOverlapCallback &hitCall, const PxQueryFilterData &filterData = PxQueryFilterData(), PxQueryFilterCallback *filterCall = NULL, const PxQueryCache *cache = NULL, PxGeometryQueryFlags queryFlags = PxGeometryQueryFlag::eDEFAULT) const = 0

Performs an overlap test of a given geometry against objects in the scene, returns results in a PxOverlapBuffer object or via a custom user callback implementation inheriting from PxOverlapCallback.

Note

Filtering: returning eBLOCK from user filter for overlap queries will cause a warning (see PxQueryHitType).

Note

eBLOCK should not be returned from user filters for overlap(). Doing so will result in undefined behavior, and a warning will be issued.

Note

If the PxQueryFlag::eNO_BLOCK flag is set, the eBLOCK will instead be automatically converted to an eTOUCH and the warning suppressed.

Parameters

geometry – [in] Geometry of object to check for overlap (supported types are: box, sphere, capsule, convex).
pose – [in] Pose of the object.
hitCall – [out] Overlap hit buffer or callback object used to report overlap hits.
filterData – [in] Filtering data and simple logic. See PxQueryFilterData PxQueryFilterCallback
filterCall – [in] Custom filtering logic (optional). Only used if the corresponding PxQueryFlag flags are set. If NULL, all hits are assumed to overlap.
cache – [in] Cached hit shape (optional). Overlap is performed against cached shape first. If no hit is found the overlap gets queried against the scene.
queryFlags – [in] Optional flags controlling the query. Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit. Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.

Returns

True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.

Public Functions

virtual void release() = 0: Decrements the reference count of the object and releases it if the new reference count is zero.

virtual void acquireReference() = 0

Acquires a counted reference to this object.

This method increases the reference count of the object by 1. Decrement the reference count by calling release()

virtual void preallocate(PxU32 prunerIndex, PxU32 nbShapes) = 0

Preallocates internal arrays to minimize the amount of reallocations.

The system does not prevent more allocations than given numbers. It is legal to not call this function at all, or to add more shapes to the system than the preallocated amounts.

Parameters

prunerIndex – [in] Index of pruner to preallocate (PX_SCENE_PRUNER_STATIC, PX_SCENE_PRUNER_DYNAMIC or PX_SCENE_COMPOUND_PRUNER when called from PxScene).
nbShapes – [in] Expected number of (regular) shapes

virtual void flushMemory() = 0

Frees internal memory that may not be in-use anymore.

This is an entry point for reclaiming transient memory allocated at some point by the SQ system, but which wasn’t been immediately freed for performance reason. Calling this function might free some memory, but it might also produce a new set of allocations in the next frame.

virtual void addSQShape(const PxRigidActor &actor, const PxShape &shape, const PxBounds3 &bounds, const PxTransform &transform, const PxSQCompoundHandle *compoundHandle = NULL, bool hasPruningStructure = false) = 0

Adds a shape to the SQ system.

The same function is used to add either a regular shape, or a SQ compound shape.

See also

merge() PxPruningStructure

Parameters

actor – [in] The shape’s actor owner
shape – [in] The shape itself
bounds – [in] Shape bounds, in world-space for regular shapes, in local-space for SQ compound shapes.
transform – [in] Shape transform, in world-space for regular shapes, in local-space for SQ compound shapes.
compoundHandle – [in] Handle of SQ compound owner, or NULL for regular shapes.
hasPruningStructure – [in] True if the shape is part of a pruning structure. The structure will be merged later, adding the objects will not invalidate the pruner.

virtual void removeSQShape(const PxRigidActor &actor, const PxShape &shape) = 0

Removes a shape from the SQ system.

The same function is used to remove either a regular shape, or a SQ compound shape.

Parameters

actor – [in] The shape’s actor owner
shape – [in] The shape itself

virtual void updateSQShape(const PxRigidActor &actor, const PxShape &shape, const PxTransform &transform) = 0

Updates a shape in the SQ system.

The same function is used to update either a regular shape, or a SQ compound shape.

The transforms are eager-evaluated, but the bounds are lazy-evaluated. This means that the updated transform has to be passed to the update function, while the bounds are automatically recomputed by the system whenever needed.

Parameters

actor – [in] The shape’s actor owner
shape – [in] The shape itself
transform – [in] New shape transform, in world-space for regular shapes, in local-space for SQ compound shapes.

virtual PxSQCompoundHandle addSQCompound(const PxRigidActor &actor, const PxShape **shapes, const PxBVH &bvh, const PxTransform *transforms) = 0

Adds a compound to the SQ system.

See also

PxBVH PxCooking::createBVH

Parameters

actor – [in] The compound actor
shapes – [in] The compound actor’s shapes
bvh – [in] BVH structure containing the compound’s shapes in local space
transforms – [in] Shape transforms, in local-space

Returns

SQ compound handle

virtual void removeSQCompound(PxSQCompoundHandle compoundHandle) = 0

Removes a compound from the SQ system.

Parameters: compoundHandle – [in] SQ compound handle (returned by addSQCompound)

virtual void updateSQCompound(PxSQCompoundHandle compoundHandle, const PxTransform &compoundTransform) = 0

Updates a compound in the SQ system.

The compound structures are immediately updated when the call occurs.

Parameters

compoundHandle – [in] SQ compound handle (returned by addSQCompound)
compoundTransform – [in] New actor/compound transform, in world-space

virtual void shiftOrigin(const PxVec3 &shift) = 0

Shift the data structures’ origin by the specified vector.

Please refer to the notes of the similar function in PxScene.

Parameters: shift – [in] Translation vector to shift the origin by.

virtual void visualize(PxU32 prunerIndex, PxRenderOutput &out) const = 0

Visualizes the system’s internal data-structures, for debugging purposes.

See also

PxRenderOutput

Parameters

prunerIndex – [in] Index of pruner to visualize (PX_SCENE_PRUNER_STATIC, PX_SCENE_PRUNER_DYNAMIC or PX_SCENE_COMPOUND_PRUNER when called from PxScene).
out – [out] Filled with render output data

virtual void merge(const PxPruningStructure &pruningStructure) = 0

Merges a pruning structure with the SQ system’s internal pruners.

See also

PxPruningStructure

Parameters: pruningStructure – [in] The pruning structure to merge

virtual PxSQPrunerHandle getHandle(const PxRigidActor &actor, const PxShape &shape, PxU32 &prunerIndex) const = 0

Shape to SQ-pruner-handle mapping function.

This function finds and returns the SQ pruner handle associated with a given (actor/shape) couple that was previously added to the system. This is needed for the sync function.

Parameters

actor – [in] The shape’s actor owner
shape – [in] The shape itself
prunerIndex – [out] Index of pruner the shape belongs to

Returns

Associated SQ pruner handle.

virtual void sync(PxU32 prunerIndex, const PxSQPrunerHandle *handles, const PxU32 *indices, const PxBounds3 *bounds, const PxTransform32 *transforms, PxU32 count, const PxBitMap &ignoredIndices) = 0

Synchronizes the scene-query system with another system that references the same objects.

This function is used when the scene-query objects also exist in another system that can also update them. For example the scene-query objects (used for raycast, overlap or sweep queries) might be driven by equivalent objects in an external rigid-body simulation engine. In this case the rigid-body simulation engine computes the new poses and transforms, and passes them to the scene-query system using this function. It is more efficient than calling updateSQShape on each object individually, since updateSQShape would end up recomputing the bounds already available in the rigid-body engine.

See also

PxBounds3 PxTransform32 PxBitMap

Parameters

prunerIndex – [in] Index of pruner being synched (PX_SCENE_PRUNER_DYNAMIC for regular PhysX usage)
handles – [in] Handles of updated objects
indices – [in] Bounds & transforms indices of updated objects, i.e. object handles[i] has bounds[indices[i]] and transforms[indices[i]]
bounds – [in] Array of bounds for all objects (not only updated bounds)
transforms – [in] Array of transforms for all objects (not only updated transforms)
count – [in] Number of updated objects
ignoredIndices – [in] Optional bitmap of ignored indices, i.e. update is skipped if ignoredIndices[indices[i]] is set.

virtual void finalizeUpdates() = 0

Finalizes updates made to the SQ system.

This function should be called after updates have been made to the SQ system, to fully reflect the changes inside the internal pruners. In particular it should be called:

after calls to updateSQShape
after calls to sync

This function:

recomputes bounds of manually updated shapes (i.e. either regular or SQ compound shapes modified by updateSQShape)
updates dynamic pruners (refit operations)
incrementally rebuilds AABB-trees

The amount of work performed in this function depends on PxSceneQueryUpdateMode.

virtual PxSQBuildStepHandle prepareSceneQueryBuildStep(PxU32 prunerIndex) = 0

Prepares asynchronous build step.

This is directly called (synchronously) by PxSceneSQSystem::sceneQueriesUpdate(). See the comments there.

This function is called to let the system execute any necessary synchronous operation before the asynchronous sceneQueryBuildStep() function is called.

If there is any work to do for the specific pruner, the function returns a pruner-specific handle that will be passed to the corresponding, asynchronous sceneQueryBuildStep function.

Parameters: prunerIndex – [in] Index of pruner being built. (PX_SCENE_PRUNER_STATIC or PX_SCENE_PRUNER_DYNAMIC when called by PxScene).
Returns: A pruner-specific handle that will be sent to sceneQueryBuildStep if there is any work to do, i.e. to execute the corresponding sceneQueryBuildStep() call.
Returns: Null if there is no work to do, otherwise a pruner-specific handle.

virtual void sceneQueryBuildStep(PxSQBuildStepHandle handle) = 0

Executes asynchronous build step.

This is directly called (asynchronously) by PxSceneSQSystem::sceneQueriesUpdate(). See the comments there.

This function incrementally builds the internal trees/pruners. It is called asynchronously, i.e. this can be called from different threads for building multiple trees at the same time.

Parameters: handle – [in] Pruner-specific handle previously returned by the prepareSceneQueryBuildStep function.

Protected Functions

inline PxSceneQuerySystem()

inline virtual ~PxSceneQuerySystem()