PxSceneSQSystem

Inheritance Relationships

Base Type

public PxSceneQuerySystemBase (PxSceneQuerySystemBase)

Derived Type

public PxScene (PxScene)

class PxSceneSQSystem : public PxSceneQuerySystemBase 

Traditional SQ system for PxScene.

Methods defined here are only available through the traditional PxScene API. Thus PxSceneSQSystem effectively captures the scene-query related part of the PxScene API.

See also

PxScene PxSceneQuerySystemBase

Subclassed by PxScene

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.

Scene Query

inline void setSceneQueryUpdateMode(PxSceneQueryUpdateMode::Enum updateMode)

Sets scene query update mode.

See also

PxSceneQueryUpdateMode::Enum

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

inline PxSceneQueryUpdateMode::Enum getSceneQueryUpdateMode() const

Gets scene query update mode.

See also

PxSceneQueryUpdateMode::Enum

Returns: Current scene query update mode.

inline PxU32 getSceneQueryStaticTimestamp() const

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

Returns: scene query static timestamp

inline void flushQueryUpdates()

Flushes any changes to the scene query representation.

See also

flushUpdates

inline void forceDynamicTreeRebuild(bool rebuildStaticStructure, bool rebuildDynamicStructure)

Forces dynamic trees to be immediately rebuilt.

Parameters

rebuildStaticStructure – [in] True to rebuild the dynamic tree containing static objects
rebuildDynamicStructure – [in] True to rebuild the dynamic tree containing dynamic objects

virtual PxPruningStructureType::Enum getStaticStructure() const = 0

Return the value of PxSceneQueryDesc::staticStructure that was set when creating the scene with PxPhysics::createScene.

virtual PxPruningStructureType::Enum getDynamicStructure() const = 0

Return the value of PxSceneQueryDesc::dynamicStructure that was set when creating the scene with PxPhysics::createScene.

virtual void sceneQueriesUpdate(PxBaseTask *completionTask = NULL, bool controlSimulation = true) = 0

Executes scene queries update tasks.

This function will refit dirty shapes within the pruner and will execute a task to build a new AABB tree, which is build on a different thread. The new AABB tree is built based on the dynamic tree rebuild hint rate. Once the new tree is ready it will be commited in next fetchQueries call, which must be called after.

This function is equivalent to the following PxSceneQuerySystem calls: Synchronous calls:

PxSceneQuerySystemBase::flushUpdates()
handle0 = PxSceneQuerySystem::prepareSceneQueryBuildStep(PX_SCENE_PRUNER_STATIC)
handle1 = PxSceneQuerySystem::prepareSceneQueryBuildStep(PX_SCENE_PRUNER_DYNAMIC) Asynchronous calls:
PxSceneQuerySystem::sceneQueryBuildStep(handle0);
PxSceneQuerySystem::sceneQueryBuildStep(handle1);

This function is part of the PxSceneSQSystem interface because it uses the PxScene task system under the hood. But it calls PxSceneQuerySystem functions, which are independent from this system and could be called in a similar fashion by a separate, possibly user-defined task manager.

Note

If PxSceneQueryUpdateMode::eBUILD_DISABLED_COMMIT_DISABLED is used, it is required to update the scene queries using this function.

Parameters

completionTask – [in] if non-NULL, this task will have its refcount incremented in sceneQueryUpdate(), then decremented when the scene is ready to have fetchQueries called. So the task will not run until the application also calls removeReference().
controlSimulation – [in] if true, the scene controls its PxTaskManager simulation state. Leave true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.

virtual bool checkQueries(bool block = false) = 0

This checks to see if the scene queries update has completed.

This does not cause the data available for reading to be updated with the results of the scene queries update, it is simply a status check. The bool will allow it to either return immediately or block waiting for the condition to be met so that it can return true

See also

sceneQueriesUpdate() fetchResults()

Parameters: block – [in] When set to true will block until the condition is met.
Returns: True if the results are available.

virtual bool fetchQueries(bool block = false) = 0

This method must be called after sceneQueriesUpdate.

It will wait for the scene queries update to finish. If the user makes an illegal scene queries update call, the SDK will issue an error message.

If a new AABB tree build finished, then during fetchQueries the current tree within the pruning structure is swapped with the new tree.

Parameters: block – [in] When set to true will block until the condition is met, which is tree built task must finish running.

Protected Functions

inline PxSceneSQSystem()

inline virtual ~PxSceneSQSystem()