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

#include <PxSceneQuerySystem.h>

Inheritance diagram for physx::PxSceneQuerySystem:

Collaboration diagram for physx::PxSceneQuerySystem:

Public Member 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.

virtual void	preallocate (PxU32 prunerIndex, PxU32 nbShapes)=0
	Preallocates internal arrays to minimize the amount of reallocations.

virtual void	flushMemory ()=0
	Frees internal memory that may not be in-use anymore.

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.

virtual void	removeSQShape (const PxRigidActor &actor, const PxShape &shape)=0
	Removes a shape from the SQ system.

virtual void	updateSQShape (const PxRigidActor &actor, const PxShape &shape, const PxTransform &transform)=0
	Updates a shape in the SQ system.

virtual PxSQCompoundHandle	addSQCompound (const PxRigidActor &actor, const PxShape *shapes, const PxBVH &bvh, const PxTransform transforms)=0
	Adds a compound to the SQ system.

virtual void	removeSQCompound (PxSQCompoundHandle compoundHandle)=0
	Removes a compound from the SQ system.

virtual void	updateSQCompound (PxSQCompoundHandle compoundHandle, const PxTransform &compoundTransform)=0
	Updates a compound in the SQ system.

virtual void	shiftOrigin (const PxVec3 &shift)=0
	Shift the data structures' origin by the specified vector.

virtual void	visualize (PxU32 prunerIndex, PxRenderOutput &out) const =0
	Visualizes the system's internal data-structures, for debugging purposes.

virtual void	merge (const PxPruningStructure &pruningStructure)=0
	Merges a pruning structure with the SQ system's internal pruners.

virtual PxSQPrunerHandle	getHandle (const PxRigidActor &actor, const PxShape &shape, PxU32 &prunerIndex) const =0
	Shape to SQ-pruner-handle mapping function.

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.

virtual void	finalizeUpdates ()=0
	Finalizes updates made to the SQ system.

virtual PxSQBuildStepHandle	prepareSceneQueryBuildStep (PxU32 prunerIndex)=0
	Prepares asynchronous build step.

virtual void	sceneQueryBuildStep (PxSQBuildStepHandle handle)=0
	Executes asynchronous build step.

Public Member Functions inherited from physx::PxSceneQuerySystemBase
virtual void	setDynamicTreeRebuildRateHint (PxU32 dynamicTreeRebuildRateHint)=0
	Sets the rebuild rate of the dynamic tree pruning structures.

virtual PxU32	getDynamicTreeRebuildRateHint () const =0
	Retrieves the rebuild rate of the dynamic tree pruning structures.

virtual void	forceRebuildDynamicTree (PxU32 prunerIndex)=0
	Forces dynamic trees to be immediately rebuilt.

virtual void	setUpdateMode (PxSceneQueryUpdateMode::Enum updateMode)=0
	Sets scene query update mode.

virtual PxSceneQueryUpdateMode::Enum	getUpdateMode () const =0
	Gets 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.

virtual void	flushUpdates ()=0
	Flushes any changes to the scene query representation.

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.

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.

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.

Detailed Description

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

Member Function Documentation

◆ acquireReference()

virtual void physx::PxSceneQuerySystem::acquireReference ( )

pure virtual

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()

◆ addSQCompound()

virtual PxSQCompoundHandle physx::PxSceneQuerySystem::addSQCompound	(	const PxRigidActor &	actor,
		const PxShape **	shapes,
		const PxBVH &	bvh,
		const PxTransform *	transforms
	)

pure virtual

Adds a compound to the SQ system.

Parameters

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

Returns: SQ compound handle

See also: PxBVH PxCooking::createBVH

◆ addSQShape()

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

pure virtual

Adds a shape to the SQ system.

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

Parameters

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

See also: merge() PxPruningStructure

◆ finalizeUpdates()

virtual void physx::PxSceneQuerySystem::finalizeUpdates ( )

pure virtual

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.

See also: PxSceneQueryUpdateMode updateSQShape() sync()

◆ flushMemory()

virtual void physx::PxSceneQuerySystem::flushMemory ( )

pure virtual

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.

◆ getHandle()

virtual PxSQPrunerHandle physx::PxSceneQuerySystem::getHandle	(	const PxRigidActor &	actor,
		const PxShape &	shape,
		PxU32 &	prunerIndex
	)		const

pure virtual

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

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

Returns: Associated SQ pruner handle.

◆ merge()

virtual void physx::PxSceneQuerySystem::merge ( const PxPruningStructure & pruningStructure )

pure virtual

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

Parameters

[in] pruningStructure The pruning structure to merge

See also: PxPruningStructure

◆ preallocate()

virtual void physx::PxSceneQuerySystem::preallocate	(	PxU32	prunerIndex,
		PxU32	nbShapes
	)

pure virtual

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

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

◆ prepareSceneQueryBuildStep()

virtual PxSQBuildStepHandle physx::PxSceneQuerySystem::prepareSceneQueryBuildStep ( PxU32 prunerIndex )

pure virtual

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.

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.

Parameters

[in] prunerIndex Index of pruner being built. (PX_SCENE_PRUNER_STATIC or PX_SCENE_PRUNER_DYNAMIC when called by PxScene).

Returns: Null if there is no work to do, otherwise a pruner-specific handle.

See also: PxSceneSQSystem::sceneQueriesUpdate sceneQueryBuildStep

◆ removeSQCompound()

virtual void physx::PxSceneQuerySystem::removeSQCompound ( PxSQCompoundHandle compoundHandle )

pure virtual

Removes a compound from the SQ system.

Parameters

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

◆ removeSQShape()

virtual void physx::PxSceneQuerySystem::removeSQShape	(	const PxRigidActor &	actor,
		const PxShape &	shape
	)

pure virtual

Removes a shape from the SQ system.

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

Parameters

[in]	actor	The shape's actor owner
[in]	shape	The shape itself

◆ sceneQueryBuildStep()

virtual void physx::PxSceneQuerySystem::sceneQueryBuildStep ( PxSQBuildStepHandle handle )

pure virtual

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

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

See also: PxSceneSQSystem::sceneQueriesUpdate prepareSceneQueryBuildStep

◆ shiftOrigin()

virtual void physx::PxSceneQuerySystem::shiftOrigin ( const PxVec3 & shift )

pure virtual

Shift the data structures' origin by the specified vector.

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

Parameters

[in] shift Translation vector to shift the origin by.

◆ sync()

virtual void physx::PxSceneQuerySystem::sync	(	PxU32	prunerIndex,
		const PxSQPrunerHandle *	handles,
		const PxU32 *	indices,
		const PxBounds3 *	bounds,
		const PxTransform32 *	transforms,
		PxU32	count,
		const PxBitMap &	ignoredIndices
	)

pure virtual

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.

Parameters

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

See also: PxBounds3 PxTransform32 PxBitMap

◆ updateSQCompound()

virtual void physx::PxSceneQuerySystem::updateSQCompound	(	PxSQCompoundHandle	compoundHandle,
		const PxTransform &	compoundTransform
	)

pure virtual

Updates a compound in the SQ system.

The compound structures are immediately updated when the call occurs.

Parameters

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

◆ updateSQShape()

virtual void physx::PxSceneQuerySystem::updateSQShape	(	const PxRigidActor &	actor,
		const PxShape &	shape,
		const PxTransform &	transform
	)

pure virtual

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

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

◆ visualize()

virtual void physx::PxSceneQuerySystem::visualize	(	PxU32	prunerIndex,
		PxRenderOutput &	out
	)		const

pure virtual

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

Parameters

[in]	prunerIndex	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

See also: PxRenderOutput

The documentation for this class was generated from the following file:

RavEngine/deps/physx/physx/include/PxSceneQuerySystem.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ acquireReference()

◆ addSQCompound()

◆ addSQShape()

◆ finalizeUpdates()

◆ flushMemory()

◆ getHandle()

◆ merge()

◆ preallocate()

◆ prepareSceneQueryBuildStep()

◆ removeSQCompound()

◆ removeSQShape()

◆ sceneQueryBuildStep()

◆ shiftOrigin()

◆ sync()

◆ updateSQCompound()

◆ updateSQShape()

◆ visualize()