PxScene

Inheritance Relationships

Base Type

public PxSceneSQSystem (PxSceneSQSystem)

class PxScene : public PxSceneSQSystem 

A scene is a collection of bodies and constraints which can interact.

The scene simulates the behavior of these objects over time. Several scenes may exist at the same time, but each body or constraint is specific to a scene — they may not be shared.

Basics

inline PxScene()

inline virtual ~PxScene()

virtual void release() = 0

Deletes the scene.

Removes any actors and constraint shaders from this scene (if the user hasn’t already done so).

Be sure to not keep a reference to this object after calling release. Avoid release calls while the scene is simulating (in between simulate() and fetchResults() calls).

See also

PxPhysics.createScene()

virtual void setFlag(PxSceneFlag::Enum flag, bool value) = 0

Sets a scene flag.

You can only set one flag at a time.

See also

PxSceneFlag

Note

Not all flags are mutable and changing some will result in an error. Please check PxSceneFlag to see which flags can be changed.

virtual PxSceneFlags getFlags() const = 0

Get the scene flags.

See also

PxSceneFlag

Returns: The scene flags. See PxSceneFlag

virtual void setLimits(const PxSceneLimits &limits) = 0

Set new scene limits.

See also

PxSceneLimits

Note

Increase the maximum capacity of various data structures in the scene. The new capacities will be at least as large as required to deal with the objects currently in the scene. Further, these values are for preallocation and do not represent hard limits.

Parameters: limits – [in] Scene limits.

virtual PxSceneLimits getLimits() const = 0

Get current scene limits.

See also

PxSceneLimits

Returns: Current scene limits.

virtual PxPhysics &getPhysics() = 0

Call this method to retrieve the Physics SDK.

See also

PxPhysics

Returns: The physics SDK this scene is associated with.

virtual PxU32 getTimestamp() const = 0

Retrieves the scene’s internal timestamp, increased each time a simulation step is completed.

Returns: scene timestamp

virtual void setName(const char *name) = 0

Sets a name string for the Scene that can be retrieved with getName().

This is for debugging and is not used by the SDK. The string is not copied by the SDK, only the pointer is stored.

Default: NULL

See also

getName()

Parameters: name – [in] String to set the objects name to.

virtual const char *getName() const = 0

Retrieves the name string set with setName().

See also

setName()

Returns: Name string associated with the Scene.

Add/Remove Articulations

virtual bool addArticulation(PxArticulationReducedCoordinate &articulation) = 0

Adds an articulation to this scene.

See also

PxArticulationReducedCoordinate

Note

If the articulation is already assigned to a scene (see PxArticulationReducedCoordinate::getScene), the call is ignored and an error is issued.

Parameters: articulation – [in] The articulation to add to the scene.
Returns: True if success

virtual void removeArticulation(PxArticulationReducedCoordinate &articulation, bool wakeOnLostTouch = true) = 0

Removes an articulation from this scene.

Note

If the articulation is not part of this scene (see PxArticulationReducedCoordinate::getScene), the call is ignored and an error is issued.

Note

If the articulation is in an aggregate it will be removed from the aggregate.

Parameters

articulation – [in] The articulation to remove from the scene.
wakeOnLostTouch – [in] Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.

Add/Remove Actors

virtual bool addActor(PxActor &actor, const PxBVH *bvh = NULL) = 0

Adds an actor to this scene.

See also

PxActor, PxConstraint::isValid(), PxBVH

Note

If the actor is already assigned to a scene (see PxActor::getScene), the call is ignored and an error is issued.

Note

If the actor has an invalid constraint, in checked builds the call is ignored and an error is issued.

Note

You can not add individual articulation links (see PxArticulationLink) to the scene. Use addArticulation() instead.

Note

If the actor is a PxRigidActor then each assigned PxConstraint object will get added to the scene automatically if it connects to another actor that is part of the scene already.

Note

When a BVH is provided the actor shapes are grouped together. 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.

Parameters

actor – [in] Actor to add to scene.
bvh – [in] BVH for actor shapes.

Returns

True if success

virtual bool addActors(PxActor *const *actors, PxU32 nbActors) = 0

Adds actors to this scene.

Only supports actors of type PxRigidStatic and PxRigidDynamic.

See also

PxActor, PxConstraint::isValid()

Note

This method only supports actors of type PxRigidStatic and PxRigidDynamic. For other actors, use addActor() instead. For articulation links, use addArticulation().

Note

If one of the actors is already assigned to a scene (see PxActor::getScene), the call is ignored and an error is issued.

Note

If an actor in the array contains an invalid constraint, in checked builds the call is ignored and an error is issued.

Note

If an actor in the array is a PxRigidActor then each assigned PxConstraint object will get added to the scene automatically if it connects to another actor that is part of the scene already.

Note

this method is optimized for high performance.

Parameters

actors – [in] Array of actors to add to scene.
nbActors – [in] Number of actors in the array.

Returns

True if success

virtual bool addActors(const PxPruningStructure &pruningStructure) = 0

Adds a pruning structure together with its actors to this scene.

Only supports actors of type PxRigidStatic and PxRigidDynamic.

Note

This method only supports actors of type PxRigidStatic and PxRigidDynamic. For other actors, use addActor() instead. For articulation links, use addArticulation().

Note

If an actor in the pruning structure contains an invalid constraint, in checked builds the call is ignored and an error is issued.

Note

For all actors in the pruning structure each assigned PxConstraint object will get added to the scene automatically if it connects to another actor that is part of the scene already.

Note

This method is optimized for high performance.

Note

Merging a PxPruningStructure into an active scene query optimization AABB tree might unbalance the tree. A typical use case for PxPruningStructure is a large world scenario where blocks of closely positioned actors get streamed in. The merge process finds the best node in the active scene query optimization AABB tree and inserts the PxPruningStructure. Therefore using PxPruningStructure for actors scattered throughout the world will result in an unbalanced tree.

Parameters: pruningStructure – [in] Pruning structure for a set of actors.
Returns: True if success

virtual void removeActor(PxActor &actor, bool wakeOnLostTouch = true) = 0

Removes an actor from this scene.

See also

PxActor, PxAggregate

Note

If the actor is not part of this scene (see PxActor::getScene), the call is ignored and an error is issued.

Note

You can not remove individual articulation links (see PxArticulationLink) from the scene. Use removeArticulation() instead.

Note

If the actor is a PxRigidActor then all assigned PxConstraint objects will get removed from the scene automatically.

Note

If the actor is in an aggregate it will be removed from the aggregate.

Parameters

actor – [in] Actor to remove from scene.
wakeOnLostTouch – [in] Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.

virtual void removeActors(PxActor *const *actors, PxU32 nbActors, bool wakeOnLostTouch = true) = 0

Removes actors from this scene.

Only supports actors of type PxRigidStatic and PxRigidDynamic.

See also

PxActor

Note

This method only supports actors of type PxRigidStatic and PxRigidDynamic. For other actors, use removeActor() instead. For articulation links, use removeArticulation().

Note

If some actor is not part of this scene (see PxActor::getScene), the actor remove is ignored and an error is issued.

Note

You can not remove individual articulation links (see PxArticulationLink) from the scene. Use removeArticulation() instead.

Note

If the actor is a PxRigidActor then all assigned PxConstraint objects will get removed from the scene automatically.

Parameters

actors – [in] Array of actors to add to scene.
nbActors – [in] Number of actors in the array.
wakeOnLostTouch – [in] Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCooridnate and PxRigidActor types.

virtual bool addAggregate(PxAggregate &aggregate) = 0

Adds an aggregate to this scene.

See also

PxAggregate, PxConstraint::isValid()

Note

If the aggregate is already assigned to a scene (see PxAggregate::getScene), the call is ignored and an error is issued.

Note

If the aggregate contains an actor with an invalid constraint, in checked builds the call is ignored and an error is issued.

Note

If the aggregate already contains actors, those actors are added to the scene as well.

Parameters: aggregate – [in] Aggregate to add to scene.
Returns: True if success

virtual void removeAggregate(PxAggregate &aggregate, bool wakeOnLostTouch = true) = 0

Removes an aggregate from this scene.

See also

PxAggregate

Note

If the aggregate is not part of this scene (see PxAggregate::getScene), the call is ignored and an error is issued.

Note

If the aggregate contains actors, those actors are removed from the scene as well.

Parameters

aggregate – [in] Aggregate to remove from scene.
wakeOnLostTouch – [in] Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.

virtual bool addCollection(const PxCollection &collection) = 0

Adds objects in the collection to this scene.

This function adds the following types of objects to this scene: PxRigidActor (except PxArticulationLink), PxAggregate, PxArticulationReducedCoordinate. This method is typically used after deserializing the collection in order to populate the scene with deserialized objects.

See also

PxCollection, PxConstraint::isValid()

Note

If the collection contains an actor with an invalid constraint, in checked builds the call is ignored and an error is issued.

Parameters: collection – [in] Objects to add to this scene. See PxCollection
Returns: True if success

Contained Object Retrieval

virtual PxU32 getNbActors(PxActorTypeFlags types) const = 0

Retrieve the number of actors of certain types in the scene.

For supported types, see PxActorTypeFlags.

See also

getActors()

Parameters: types – [in] Combination of actor types.
Returns: the number of actors.

virtual PxU32 getActors(PxActorTypeFlags types, PxActor **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve an array of all the actors of certain types in the scene.

For supported types, see PxActorTypeFlags.

See also

getNbActors()

Parameters

types – [in] Combination of actor types to retrieve.
userBuffer – [out] The buffer to receive actor pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first actor pointer to be retrieved

Returns

Number of actors written to the buffer.

virtual PxActor **getActiveActors(PxU32 &nbActorsOut) = 0

Queries the PxScene for a list of the PxActors whose transforms have been updated during the previous simulation step.

Only includes actors of type PxRigidDynamic and PxArticulationLink.

See also

PxActor

Note

PxSceneFlag::eENABLE_ACTIVE_ACTORS must be set.

Note

Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored and NULL will be returned.

Parameters: nbActorsOut – [out] The number of actors returned.
Returns: A pointer to the list of active PxActors generated during the last call to fetchResults().

virtual PxU32 getNbSoftBodies() const = 0

Retrieve the number of soft bodies in the scene.

See also

getActors()

Returns: the number of soft bodies.

virtual PxU32 getSoftBodies(PxSoftBody **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve an array of all the soft bodies in the scene.

See also

getNbActors()

Parameters

userBuffer – [out] The buffer to receive actor pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first actor pointer to be retrieved

Returns

Number of actors written to the buffer.

virtual PxU32 getNbParticleSystems(PxParticleSolverType::Enum type) const = 0

Retrieve the number of particle systems of the requested type in the scene.

See getParticleSystems(), PxParticleSolverType

Parameters: type – [in] The particle system type. See PxParticleSolverType. Only one type can be requested per function call.
Returns: the number particle systems.

virtual PxU32 getParticleSystems(PxParticleSolverType::Enum type, PxParticleSystem **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve an array of all the particle systems of the requested type in the scene.

See getNbParticleSystems(), PxParticleSolverType

Parameters

type – [in] The particle system type. See PxParticleSolverType. Only one type can be requested per function call.
userBuffer – [out] The buffer to receive particle system pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first particle system pointer to be retrieved

Returns

Number of particle systems written to the buffer.

virtual PxU32 getNbFEMCloths() const = 0

Retrieve the number of FEM cloths in the scene.

See getFEMCloths()

Warning

Feature under development, only for internal usage.

Returns: the number of FEM cloths.

virtual PxU32 getFEMCloths(PxFEMCloth **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve an array of all the FEM cloths in the scene.

Warning

Feature under development, only for internal usage.

Parameters

userBuffer – [out] The buffer to write the FEM cloth pointers to
bufferSize – [in] Size of the provided user buffer
startIndex – [in] Index of first FEM cloth pointer to be retrieved

Returns

Number of FEM cloths written to the buffer

virtual PxU32 getNbHairSystems() const = 0

Retrieve the number of hair systems in the scene.

See also

getActors()

Warning

Feature under development, only for internal usage.

Returns: the number of hair systems

virtual PxU32 getHairSystems(PxHairSystem **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve an array of all the hair systems in the scene.

Warning

Feature under development, only for internal usage.

Parameters

userBuffer – [out] The buffer to write the actor pointers to
bufferSize – [in] Size of the provided user buffer
startIndex – [in] Index of first actor pointer to be retrieved

Returns

Number of actors written to the buffer

virtual PxU32 getNbArticulations() const = 0

Returns the number of articulations in the scene.

See also

getArticulations()

Returns: the number of articulations in this scene.

virtual PxU32 getArticulations(PxArticulationReducedCoordinate **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the articulations in the scene.

See also

getNbArticulations()

Parameters

userBuffer – [out] The buffer to receive articulations pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first articulations pointer to be retrieved

Returns

Number of articulations written to the buffer.

virtual PxU32 getNbConstraints() const = 0

Returns the number of constraint shaders in the scene.

See also

getConstraints()

Returns: the number of constraint shaders in this scene.

virtual PxU32 getConstraints(PxConstraint **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the constraint shaders in the scene.

See also

getNbConstraints()

Parameters

userBuffer – [out] The buffer to receive constraint shader pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first constraint pointer to be retrieved

Returns

Number of constraint shaders written to the buffer.

virtual PxU32 getNbAggregates() const = 0

Returns the number of aggregates in the scene.

See also

getAggregates()

Returns: the number of aggregates in this scene.

virtual PxU32 getAggregates(PxAggregate **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all the aggregates in the scene.

See also

getNbAggregates()

Parameters

userBuffer – [out] The buffer to receive aggregates pointers.
bufferSize – [in] Size of provided user buffer.
startIndex – [in] Index of first aggregate pointer to be retrieved

Returns

Number of aggregates written to the buffer.

Dominance

virtual void setDominanceGroupPair(PxDominanceGroup group1, PxDominanceGroup group2, const PxDominanceGroupPair &dominance) = 0

Specifies the dominance behavior of contacts between two actors with two certain dominance groups.

It is possible to assign each actor to a dominance groups using PxActor::setDominanceGroup().

With dominance groups one can have all contacts created between actors act in one direction only. This is useful, for example, if you want an object to push debris out of its way and be unaffected,while still responding physically to forces and collisions with non-debris objects.

Whenever a contact between two actors (a0, a1) needs to be solved, the groups (g0, g1) of both actors are retrieved. Then the PxDominanceGroupPair setting for this group pair is retrieved with getDominanceGroupPair(g0, g1).

In the contact, PxDominanceGroupPair::dominance0 becomes the dominance setting for a0, and PxDominanceGroupPair::dominance1 becomes the dominance setting for a1. A dominanceN setting of 1.0f, the default, will permit aN to be pushed or pulled by a(1-N) through the contact. A dominanceN setting of 0.0f, will however prevent aN to be pushed by a(1-N) via the contact. Thus, a PxDominanceGroupPair of (1.0f, 0.0f) makes the interaction one-way.

The matrix sampled by getDominanceGroupPair(g1, g2) is initialised by default such that:

if g1 == g2, then (1.0f, 1.0f) is returned if g1 < g2, then (0.0f, 1.0f) is returned if g1 > g2, then (1.0f, 0.0f) is returned

In other words, we permit actors in higher groups to be pushed around by actors in lower groups by default.

These settings should cover most applications, and in fact not overriding these settings may likely result in higher performance.

It is not possible to make the matrix asymetric, or to change the diagonal. In other words:

it is not possible to change (g1, g2) if (g1==g2) if you set

(g1, g2) to X, then (g2, g1) will implicitly and automatically be set to ~X, where:

~(1.0f, 1.0f) is (1.0f, 1.0f) ~(0.0f, 1.0f) is (1.0f, 0.0f) ~(1.0f, 0.0f) is (0.0f, 1.0f)

These two restrictions are to make sure that contacts between two actors will always evaluate to the same dominance setting, regardless of the order of the actors.

Dominance settings are currently specified as floats 0.0f or 1.0f because in the future we may permit arbitrary fractional settings to express ‘partly-one-way’ interactions.

Sleeping: Does NOT wake actors up automatically.

virtual PxDominanceGroupPair getDominanceGroupPair(PxDominanceGroup group1, PxDominanceGroup group2) const = 0

Samples the dominance matrix.

Dispatcher

virtual PxCpuDispatcher *getCpuDispatcher() const = 0

Return the cpu dispatcher that was set in PxSceneDesc::cpuDispatcher when creating the scene with PxPhysics::createScene.

virtual PxCudaContextManager *getCudaContextManager() const = 0

Return the CUDA context manager that was set in PxSceneDesc::cudaContextManager when creating the scene with PxPhysics::createScene.

Platform specific: Applies to PC GPU only.

Multiclient

virtual PxClientID createClient() = 0

Reserves a new client ID.

PX_DEFAULT_CLIENT is always available as the default clientID. Additional clients are returned by this function. Clients cannot be released once created. An error is reported when more than a supported number of clients (currently 128) are created.

See also

PxClientID

Callbacks

virtual void setSimulationEventCallback(PxSimulationEventCallback *callback) = 0

Sets a user notify object which receives special simulation events when they occur.

Note

Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters: callback – [in] User notification callback. See PxSimulationEventCallback.

virtual PxSimulationEventCallback *getSimulationEventCallback() const = 0

Retrieves the simulationEventCallback pointer set with setSimulationEventCallback().

Returns: The current user notify pointer. See PxSimulationEventCallback.

virtual void setContactModifyCallback(PxContactModifyCallback *callback) = 0

Sets a user callback object, which receives callbacks on all contacts generated for specified actors.

Note

Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters: callback – [in] Asynchronous user contact modification callback. See PxContactModifyCallback.

virtual void setCCDContactModifyCallback(PxCCDContactModifyCallback *callback) = 0

Sets a user callback object, which receives callbacks on all CCD contacts generated for specified actors.

Note

Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters: callback – [in] Asynchronous user contact modification callback. See PxCCDContactModifyCallback.

virtual PxContactModifyCallback *getContactModifyCallback() const = 0

Retrieves the PxContactModifyCallback pointer set with setContactModifyCallback().

Returns: The current user contact modify callback pointer. See PxContactModifyCallback.

virtual PxCCDContactModifyCallback *getCCDContactModifyCallback() const = 0

Retrieves the PxCCDContactModifyCallback pointer set with setContactModifyCallback().

Returns: The current user contact modify callback pointer. See PxContactModifyCallback.

virtual void setBroadPhaseCallback(PxBroadPhaseCallback *callback) = 0

Sets a broad-phase user callback object.

Note

Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters: callback – [in] Asynchronous broad-phase callback. See PxBroadPhaseCallback.

virtual PxBroadPhaseCallback *getBroadPhaseCallback() const = 0

Retrieves the PxBroadPhaseCallback pointer set with setBroadPhaseCallback().

Returns: The current broad-phase callback pointer. See PxBroadPhaseCallback.

Collision Filtering

virtual void setFilterShaderData(const void *data, PxU32 dataSize) = 0

Sets the shared global filter data which will get passed into the filter shader.

Note

It is the user’s responsibility to ensure that changing the shared global filter data does not change the filter output value for existing pairs. If the filter output for existing pairs does change nonetheless then such a change will not take effect until the pair gets refiltered. resetFiltering() can be used to explicitly refilter the pairs of specific objects.

Note

The provided data will get copied to internal buffers and this copy will be used for filtering calls.

Note

Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters

data – [in] The shared global filter shader data.
dataSize – [in] Size of the shared global filter shader data (in bytes).

virtual const void *getFilterShaderData() const = 0

Gets the shared global filter data in use for this scene.

Note

The reference points to a copy of the original filter data specified in PxSceneDesc.filterShaderData or provided by setFilterShaderData().

Returns: Shared filter data for filter shader.

virtual PxU32 getFilterShaderDataSize() const = 0

Gets the size of the shared global filter data (PxSceneDesc.filterShaderData)

Returns: Size of shared filter data [bytes].

virtual PxSimulationFilterShader getFilterShader() const = 0

Gets the custom collision filter shader in use for this scene.

Returns: Filter shader class that defines the collision pair filtering.

virtual PxSimulationFilterCallback *getFilterCallback() const = 0

Gets the custom collision filter callback in use for this scene.

Returns: Filter callback class that defines the collision pair filtering.

virtual bool resetFiltering(PxActor &actor) = 0

Marks the object to reset interactions and re-run collision filters in the next simulation step.

This call forces the object to remove all existing collision interactions, to search anew for existing contact pairs and to run the collision filters again for found collision pairs.

Sleeping: Does wake up the actor.

Note

The operation is supported for PxRigidActor objects only.

Note

All persistent state of existing interactions will be lost and can not be retrieved even if the same collison pair is found again in the next step. This will mean, for example, that you will not get notified about persistent contact for such an interaction (see PxPairFlag::eNOTIFY_TOUCH_PERSISTS), the contact pair will be interpreted as newly found instead.

Note

Lost touch contact reports will be sent for every collision pair which includes this shape, if they have been requested through PxPairFlag::eNOTIFY_TOUCH_LOST or PxPairFlag::eNOTIFY_THRESHOLD_FORCE_LOST.

Note

This is an expensive operation, don’t use it if you don’t have to.

Note

Can be used to retrieve collision pairs that were killed by the collision filters (see PxFilterFlag::eKILL)

Note

It is invalid to use this method if the actor has not been added to a scene already.

Note

It is invalid to use this method if PxActorFlag::eDISABLE_SIMULATION is set.

Note

Do not use this method while the simulation is running.

Parameters: actor – [in] The actor for which to re-evaluate interactions.
Returns: True if success

virtual bool resetFiltering(PxRigidActor &actor, PxShape *const *shapes, PxU32 shapeCount) = 0

Marks the object to reset interactions and re-run collision filters for specified shapes in the next simulation step.

This is a specialization of the resetFiltering(PxActor& actor) method and allows to reset interactions for specific shapes of a PxRigidActor.

Sleeping: Does wake up the actor.

Note

Do not use this method while the simulation is running.

Parameters

actor – [in] The actor for which to re-evaluate interactions.
shapes – [in] The shapes for which to re-evaluate interactions.
shapeCount – [in] Number of shapes in the list.

virtual PxPairFilteringMode::Enum getKinematicKinematicFilteringMode() const = 0

Gets the pair filtering mode for kinematic-kinematic pairs.

See also

PxPairFilteringMode PxSceneDesc

Returns: Filtering mode for kinematic-kinematic pairs.

virtual PxPairFilteringMode::Enum getStaticKinematicFilteringMode() const = 0

Gets the pair filtering mode for static-kinematic pairs.

See also

PxPairFilteringMode PxSceneDesc

Returns: Filtering mode for static-kinematic pairs.

Simulation

virtual bool simulate(PxReal elapsedTime, physx::PxBaseTask *completionTask = NULL, void *scratchMemBlock = 0, PxU32 scratchMemBlockSize = 0, bool controlSimulation = true) = 0

Advances the simulation by an elapsedTime time.

Calls to simulate() should pair with calls to fetchResults(): Each fetchResults() invocation corresponds to exactly one simulate() invocation; calling simulate() twice without an intervening fetchResults() or fetchResults() twice without an intervening simulate() causes an error condition.

scene->simulate(); …do some processing until physics is computed… scene->fetchResults(); …now results of run may be retrieved.

See also

fetchResults() checkResults()

Note

Large elapsedTime values can lead to instabilities. In such cases elapsedTime should be subdivided into smaller time intervals and simulate() should be called multiple times for each interval.

Parameters

elapsedTime – [in] Amount of time to advance simulation by. The parameter has to be larger than 0, else the resulting behavior will be undefined. Range: (0, PX_MAX_F32)
completionTask – [in] if non-NULL, this task will have its refcount incremented in simulate(), then decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference().
scratchMemBlock – [in] a memory region for physx to use for temporary data during simulation. This block may be reused by the application after fetchResults returns. Must be aligned on a 16-byte boundary
scratchMemBlockSize – [in] the size of the scratch memory block. Must be a multiple of 16K.
controlSimulation – [in] if true, the scene controls its PxTaskManager simulation state. Leave true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.

Returns

True if success

virtual bool advance(physx::PxBaseTask *completionTask = 0) = 0

Performs dynamics phase of the simulation pipeline.

Note

Calls to advance() should follow calls to fetchCollision(). An error message will be issued if this sequence is not followed.

Parameters: completionTask – [in] if non-NULL, this task will have its refcount incremented in advance(), then decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference().
Returns: True if success

virtual bool collide(PxReal elapsedTime, physx::PxBaseTask *completionTask = 0, void *scratchMemBlock = 0, PxU32 scratchMemBlockSize = 0, bool controlSimulation = true) = 0

Performs collision detection for the scene over elapsedTime.

Note

Calls to collide() should be the first method called to simulate a frame.

Parameters

elapsedTime – [in] Amount of time to advance simulation by. The parameter has to be larger than 0, else the resulting behavior will be undefined. Range: (0, PX_MAX_F32)
completionTask – [in] if non-NULL, this task will have its refcount incremented in collide(), then decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference().
scratchMemBlock – [in] a memory region for physx to use for temporary data during simulation. This block may be reused by the application after fetchResults returns. Must be aligned on a 16-byte boundary
scratchMemBlockSize – [in] the size of the scratch memory block. Must be a multiple of 16K.
controlSimulation – [in] if true, the scene controls its PxTaskManager simulation state. Leave true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.

Returns

True if success

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

This checks to see if the simulation run has completed.

This does not cause the data available for reading to be updated with the results of the simulation, 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

simulate() fetchResults()

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

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

This method must be called after collide() and before advance().

It will wait for the collision phase to finish. If the user makes an illegal simulation call, the SDK will issue an error message.

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

virtual bool fetchResults(bool block = false, PxU32 *errorState = 0) = 0

This is the big brother to checkResults() it basically does the following:

if ( checkResults(block) )
{
    fire appropriate callbacks
    swap buffers
    return true
}
else
    return false

See also

simulate() checkResults()

Parameters

block – [in] When set to true will block until results are available.
errorState – [out] Used to retrieve hardware error codes. A non zero value indicates an error.

Returns

True if the results have been fetched.

virtual bool fetchResultsStart(const PxContactPairHeader *&contactPairs, PxU32 &nbContactPairs, bool block = false) = 0

This call performs the first section of fetchResults, and returns a pointer to the contact streams output by the simulation.

It can be used to process contact pairs in parallel, which is often a limiting factor for fetchResults() performance.

After calling this function and processing the contact streams, call fetchResultsFinish(). Note that writes to the simulation are not permitted between the start of fetchResultsStart() and the end of fetchResultsFinish().

Parameters

block – [in] When set to true will block until results are available.
contactPairs – [out] an array of pointers to contact pair headers
nbContactPairs – [out] the number of contact pairs

Returns

True if the results have been fetched.

virtual void processCallbacks(physx::PxBaseTask *continuation) = 0

This call processes all event callbacks in parallel.

It takes a continuation task, which will be executed once all callbacks have been processed.

This is a utility function to make it easier to process callbacks in parallel using the PhysX task system. It can only be used in conjunction with fetchResultsStart(…) and fetchResultsFinish(…)

Parameters: continuation – [in] The task that will be executed once all callbacks have been processed.

virtual void fetchResultsFinish(PxU32 *errorState = 0) = 0

This call performs the second section of fetchResults.

It must be called after fetchResultsStart() returns and contact reports have been processed.

Note that once fetchResultsFinish() has been called, the contact streams returned in fetchResultsStart() will be invalid.

Parameters: errorState – [out] Used to retrieve hardware error codes. A non zero value indicates an error.

virtual void fetchResultsParticleSystem() = 0: This call performs the synchronization of particle system data copies.

virtual void flushSimulation(bool sendPendingReports = false) = 0

Clear internal buffers and free memory.

This method can be used to clear buffers and free internal memory without having to destroy the scene. Can be useful if the physics data gets streamed in and a checkpoint with a clean state should be created.

Note

It is not allowed to call this method while the simulation is running. The call will fail.

Parameters: sendPendingReports – [in] When set to true pending reports will be sent out before the buffers get cleaned up (for instance lost touch contact/trigger reports due to deleted objects).

virtual void setGravity(const PxVec3 &vec) = 0

Sets a constant gravity for the entire scene.

Sleeping: Does NOT wake the actor up automatically.

See also

PxSceneDesc.gravity getGravity()

Note

Do not use this method while the simulation is running.

Parameters: vec – [in] A new gravity vector(e.g. PxVec3(0.0f,-9.8f,0.0f) ) Range: force vector

virtual PxVec3 getGravity() const = 0

Retrieves the current gravity setting.

See also

setGravity() PxSceneDesc.gravity

Returns: The current gravity for the scene.

virtual void setBounceThresholdVelocity(const PxReal t) = 0

Set the bounce threshold velocity.

Collision speeds below this threshold will not cause a bounce.

Note

Do not use this method while the simulation is running.

virtual PxReal getBounceThresholdVelocity() const = 0

Return the bounce threshold velocity.

virtual void setCCDMaxPasses(PxU32 ccdMaxPasses) = 0

Sets the maximum number of CCD passes.

Note

Do not use this method while the simulation is running.

Parameters: ccdMaxPasses – [in] Maximum number of CCD passes

virtual PxU32 getCCDMaxPasses() const = 0

Gets the maximum number of CCD passes.

Returns: The maximum number of CCD passes.

virtual void setCCDMaxSeparation(const PxReal t) = 0

Set the maximum CCD separation.

Note

Do not use this method while the simulation is running.

virtual PxReal getCCDMaxSeparation() const = 0

Gets the maximum CCD separation.

Returns: The maximum CCD separation.

virtual void setCCDThreshold(const PxReal t) = 0

Set the CCD threshold.

Note

Do not use this method while the simulation is running.

virtual PxReal getCCDThreshold() const = 0

Gets the CCD threshold.

Returns: The CCD threshold.

virtual void setMaxBiasCoefficient(const PxReal t) = 0

Set the max bias coefficient.

Note

Do not use this method while the simulation is running.

virtual PxReal getMaxBiasCoefficient() const = 0

Gets the max bias coefficient.

Returns: The max bias coefficient.

virtual void setFrictionOffsetThreshold(const PxReal t) = 0

Set the friction offset threshold.

Note

Do not use this method while the simulation is running.

virtual PxReal getFrictionOffsetThreshold() const = 0

Gets the friction offset threshold.

virtual void setFrictionCorrelationDistance(const PxReal t) = 0

Set the friction correlation distance.

Note

Do not use this method while the simulation is running.

virtual PxReal getFrictionCorrelationDistance() const = 0

Gets the friction correlation distance.

virtual PxFrictionType::Enum getFrictionType() const = 0

Return the friction model.

virtual PxSolverType::Enum getSolverType() const = 0

Return the solver model.

See also

PxSolverType, PxSceneDesc::solverType

Visualization and Statistics

virtual bool setVisualizationParameter(PxVisualizationParameter::Enum param, PxReal value) = 0

Function that lets you set debug visualization parameters.

Returns false if the value passed is out of range for usage specified by the enum.

Note

Do not use this method while the simulation is running.

Parameters

param – [in] Parameter to set. See PxVisualizationParameter
value – [in] The value to set, see PxVisualizationParameter for allowable values. Setting to zero disables visualization for the specified property, setting to a positive value usually enables visualization and defines the scale factor.

Returns

False if the parameter is out of range.

virtual PxReal getVisualizationParameter(PxVisualizationParameter::Enum paramEnum) const = 0

Function that lets you query debug visualization parameters.

Parameters: paramEnum – [in] The Parameter to retrieve.
Returns: The value of the parameter.

virtual void setVisualizationCullingBox(const PxBounds3 &box) = 0

Defines a box in world space to which visualization geometry will be (conservatively) culled.

Use a non-empty culling box to enable the feature, and an empty culling box to disable it.

Note

Do not use this method while the simulation is running.

Parameters: box – [in] the box to which the geometry will be culled. Empty box to disable the feature.

virtual PxBounds3 getVisualizationCullingBox() const = 0

Retrieves the visualization culling box.

Returns: the box to which the geometry will be culled.

virtual const PxRenderBuffer &getRenderBuffer() = 0

Retrieves the render buffer.

This will contain the results of any active visualization for this scene.

See also

PxRenderBuffer

Note

Do not use this method while the simulation is running. Calls to this method while the simulation is running will result in undefined behaviour.

Returns: The render buffer.

virtual void getSimulationStatistics(PxSimulationStatistics &stats) const = 0

Call this method to retrieve statistics for the current simulation step.

See also

PxSimulationStatistics

Note

Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.

Parameters: stats – [out] Used to retrieve statistics for the current simulation step.

Broad-phase

virtual PxBroadPhaseType::Enum getBroadPhaseType() const = 0

Returns broad-phase type.

Returns: Broad-phase type

virtual bool getBroadPhaseCaps(PxBroadPhaseCaps &caps) const = 0

Gets broad-phase caps.

Parameters: caps – [out] Broad-phase caps
Returns: True if success

virtual PxU32 getNbBroadPhaseRegions() const = 0

Returns number of regions currently registered in the broad-phase.

Returns: Number of regions

virtual PxU32 getBroadPhaseRegions(PxBroadPhaseRegionInfo *userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Gets broad-phase regions.

Parameters

userBuffer – [out] Returned broad-phase regions
bufferSize – [in] Size of userBuffer
startIndex – [in] Index of first desired region, in [0 ; getNbRegions()[

Returns

Number of written out regions

virtual PxU32 addBroadPhaseRegion(const PxBroadPhaseRegion &region, bool populateRegion = false) = 0

Adds a new broad-phase region.

The bounds for the new region must be non-empty, otherwise an error occurs and the call is ignored.

Note that by default, objects already existing in the SDK that might touch this region will not be automatically added to the region. In other words the newly created region will be empty, and will only be populated with new objects when they are added to the simulation, or with already existing objects when they are updated.

It is nonetheless possible to override this default behavior and let the SDK populate the new region automatically with already existing objects overlapping the incoming region. This has a cost though, and it should only be used when the game can not guarantee that all objects within the new region will be added to the simulation after the region itself.

Objects automatically move from one region to another during their lifetime. The system keeps tracks of what regions a given object is in. It is legal for an object to be in an arbitrary number of regions. However if an object leaves all regions, or is created outside of all regions, several things happen:

collisions get disabled for this object
if a PxBroadPhaseCallback object is provided, an “out-of-bounds” event is generated via that callback
if a PxBroadPhaseCallback object is not provided, a warning/error message is sent to the error stream

If an object goes out-of-bounds and user deletes it during the same frame, neither the out-of-bounds event nor the error message is generated.

See also

PxBroadPhaseRegion PxBroadPhaseCallback

Parameters

region – [in] User-provided region data
populateRegion – [in] Automatically populate new region with already existing objects overlapping it

Returns

Handle for newly created region, or 0xffffffff in case of failure.

virtual bool removeBroadPhaseRegion(PxU32 handle) = 0

Removes a new broad-phase region.

If the region still contains objects, and if those objects do not overlap any region any more, they are not automatically removed from the simulation. Instead, the PxBroadPhaseCallback::onObjectOutOfBounds notification is used for each object. Users are responsible for removing the objects from the simulation if this is the desired behavior.

If the handle is invalid, or if a valid handle is removed twice, an error message is sent to the error stream.

Parameters: handle – [in] Region’s handle, as returned by PxScene::addBroadPhaseRegion.
Returns: True if success

Threads and Memory

void *userData: user can assign this to whatever, usually to create a 1:1 relationship with a user object.

virtual PxTaskManager *getTaskManager() const = 0

Get the task manager associated with this scene.

Returns: the task manager associated with the scene

virtual void lockRead(const char *file = NULL, PxU32 line = 0) = 0

Lock the scene for reading from the calling thread.

When the PxSceneFlag::eREQUIRE_RW_LOCK flag is enabled lockRead() must be called before any read calls are made on the scene.

Multiple threads may read at the same time, no threads may read while a thread is writing. If a call to lockRead() is made while another thread is holding a write lock then the calling thread will be blocked until the writing thread calls unlockWrite().

Note

Lock upgrading is not supported, that means it is an error to call lockRead() followed by lockWrite().

Note

Recursive locking is supported but each lockRead() call must be paired with an unlockRead().

Parameters

file – String representing the calling file, for debug purposes
line – The source file line number, for debug purposes

virtual void unlockRead() = 0: Unlock the scene from reading.

Note

Each unlockRead() must be paired with a lockRead() from the same thread.

virtual void lockWrite(const char *file = NULL, PxU32 line = 0) = 0

Lock the scene for writing from this thread.

When the PxSceneFlag::eREQUIRE_RW_LOCK flag is enabled lockWrite() must be called before any write calls are made on the scene.

Only one thread may write at a time and no threads may read while a thread is writing. If a call to lockWrite() is made and there are other threads reading then the calling thread will be blocked until the readers complete.

Writers have priority. If a thread is blocked waiting to write then subsequent calls to lockRead() from other threads will be blocked until the writer completes.

Note

If multiple threads are waiting to write then the thread that is first granted access depends on OS scheduling.

Note

Recursive locking is supported but each lockWrite() call must be paired with an unlockWrite().

Note

If a thread has already locked the scene for writing then it may call lockRead().

Parameters

file – String representing the calling file, for debug purposes
line – The source file line number, for debug purposes

virtual void unlockWrite() = 0: Unlock the scene from writing.

Note

Each unlockWrite() must be paired with a lockWrite() from the same thread.

virtual void setNbContactDataBlocks(PxU32 numBlocks) = 0

set the cache blocks that can be used during simulate().

Each frame the simulation requires memory to store contact, friction, and contact cache data. This memory is used in blocks of 16K. Each frame the blocks used by the previous frame are freed, and may be retrieved by the application using PxScene::flushSimulation()

This call will force allocation of cache blocks if the numBlocks parameter is greater than the currently allocated number of blocks, and less than the max16KContactDataBlocks parameter specified at scene creation time.

Note

Do not use this method while the simulation is running.

Parameters: numBlocks – [in] The number of blocks to allocate.

virtual PxU32 getNbContactDataBlocksUsed() const = 0

get the number of cache blocks currently used by the scene

This function may not be called while the scene is simulating

Returns: the number of cache blocks currently used by the scene

virtual PxU32 getMaxNbContactDataBlocksUsed() const = 0

get the maximum number of cache blocks used by the scene

This function may not be called while the scene is simulating

Returns: the maximum number of cache blocks everused by the scene

virtual PxU32 getContactReportStreamBufferSize() const = 0

Return the value of PxSceneDesc::contactReportStreamBufferSize that was set when creating the scene with PxPhysics::createScene.

virtual void setSolverBatchSize(PxU32 solverBatchSize) = 0

Sets the number of actors required to spawn a separate rigid body solver thread.

Note

Do not use this method while the simulation is running.

Parameters: solverBatchSize – [in] Number of actors required to spawn a separate rigid body solver thread.

virtual PxU32 getSolverBatchSize() const = 0

Retrieves the number of actors required to spawn a separate rigid body solver thread.

Returns: Current number of actors required to spawn a separate rigid body solver thread.

virtual void setSolverArticulationBatchSize(PxU32 solverBatchSize) = 0

Sets the number of articulations required to spawn a separate rigid body solver thread.

Note

Do not use this method while the simulation is running.

Parameters: solverBatchSize – [in] Number of articulations required to spawn a separate rigid body solver thread.

virtual PxU32 getSolverArticulationBatchSize() const = 0

Retrieves the number of articulations required to spawn a separate rigid body solver thread.

Returns: Current number of articulations required to spawn a separate rigid body solver thread.

virtual PxReal getWakeCounterResetValue() const = 0

Returns the wake counter reset value.

See also

PxSceneDesc.wakeCounterResetValue

Returns: Wake counter reset value

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

Shift the scene origin by the specified vector.

The poses of all objects in the scene and the corresponding data structures will get adjusted to reflect the new origin location (the shift vector will get subtracted from all object positions).

Note

It is the user’s responsibility to keep track of the summed total origin shift and adjust all input/output to/from PhysX accordingly.

Note

Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.

Note

Make sure to propagate the origin shift to other dependent modules (for example, the character controller module etc.).

Note

This is an expensive operation and we recommend to use it only in the case where distance related precision issues may arise in areas far from the origin.

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

virtual PxPvdSceneClient *getScenePvdClient() = 0

Returns the Pvd client associated with the scene.

Returns: the client, NULL if no PVD supported.

virtual void copyArticulationData(void *data, void *index, PxArticulationGpuDataType::Enum dataType, const PxU32 nbCopyArticulations, void *copyEvent = NULL) = 0

Copy GPU articulation data from the internal GPU buffer to a user-provided device buffer.

Parameters

data – [in] User-provided gpu data buffer which should be sized appropriately for the particular data that is requested. Further details provided in the user guide.
index – [in] User-provided gpu index buffer. This buffer stores the articulation indices which the user wants to copy.
dataType – [in] Enum specifying the type of data the user wants to read back from the articulations.
nbCopyArticulations – [in] Number of articulations that data should be copied from.
copyEvent – [in] User-provided event for the articulation stream to signal when the data copy to the user buffer has completed.

virtual void applyArticulationData(void *data, void *index, PxArticulationGpuDataType::Enum dataType, const PxU32 nbUpdatedArticulations, void *waitEvent = NULL, void *signalEvent = NULL) = 0

Apply GPU articulation data from a user-provided device buffer to the internal GPU buffer.

Parameters

data – [in] User-provided gpu data buffer which should be sized appropriately for the particular data that is requested. Further details provided in the user guide.
index – [in] User-provided gpu index buffer. This buffer stores the articulation indices which the user wants to write to.
dataType – [in] Enum specifying the type of data the user wants to write to the articulations.
nbUpdatedArticulations – [in] Number of articulations that data should be written to.
waitEvent – [in] User-provided event for the articulation stream to wait for data.
signalEvent – [in] User-provided event for the articulation stream to signal when the data read from the user buffer has completed.

virtual void copySoftBodyData(void **data, void *dataSizes, void *softBodyIndices, PxSoftBodyGpuDataFlag::Enum flag, const PxU32 nbCopySoftBodies, const PxU32 maxSize, void *copyEvent = NULL) = 0

Copy GPU softbody data from the internal GPU buffer to a user-provided device buffer.

Parameters

data – [in] User-provided gpu buffer containing a pointer to another gpu buffer for every softbody to process
dataSizes – [in] The size of every buffer in bytes
softBodyIndices – [in] User provided gpu index buffer. This buffer stores the softbody index which the user want to copy.
maxSize – [in] The largest size stored in dataSizes. Used internally to decide how many threads to launch for the copy process.
flag – [in] Flag defining which data the user wants to read back from the softbody system
nbCopySoftBodies – [in] The number of softbodies to be copied.
copyEvent – [in] User-provided event for the user to sync data

virtual void applySoftBodyData(void **data, void *dataSizes, void *softBodyIndices, PxSoftBodyGpuDataFlag::Enum flag, const PxU32 nbUpdatedSoftBodies, const PxU32 maxSize, void *applyEvent = NULL) = 0

Apply user-provided data to the internal softbody system.

Parameters

data – [in] User-provided gpu buffer containing a pointer to another gpu buffer for every softbody to process
dataSizes – [in] The size of every buffer in bytes
softBodyIndices – [in] User provided gpu index buffer. This buffer stores the updated softbody index.
flag – [in] Flag defining which data the user wants to write to the softbody system
maxSize – [in] The largest size stored in dataSizes. Used internally to decide how many threads to launch for the copy process.
nbUpdatedSoftBodies – [in] The number of updated softbodies
applyEvent – [in] User-provided event for the softbody stream to wait for data

virtual void copyContactData(void *data, const PxU32 maxContactPairs, void *numContactPairs, void *copyEvent = NULL) = 0

Copy rigid body contact data from the internal GPU buffer to a user-provided device buffer.

Note

This function only reports contact data for actor pairs where both actors are either rigid bodies or articulations.

Note

The contact data contains pointers to internal state and is only valid until the next call to simulate().

Parameters

data – [in] User-provided gpu data buffer, which should be the size of PxGpuContactPair * numContactPairs
maxContactPairs – [in] The maximum number of pairs that the buffer can contain
numContactPairs – [in] The actual number of contact pairs that were written
copyEvent – [in] User-provided event for the user to sync data

virtual void copyBodyData(PxGpuBodyData *data, PxGpuActorPair *index, const PxU32 nbCopyActors, void *copyEvent = NULL) = 0

Copy GPU rigid body data from the internal GPU buffer to a user-provided device buffer.

Parameters

data – [in] User-provided gpu data buffer which should nbCopyActors * sizeof(PxGpuBodyData). The only data it can copy is PxGpuBodyData.
index – [in] User provided node PxGpuActorPair buffer. This buffer stores pairs of indices: the PxNodeIndex corresponding to the rigid body and an index corresponding to the location in the user buffer that this value should be placed.
nbCopyActors – [in] The number of rigid body to be copied.
copyEvent – [in] User-provided event for the user to sync data.

virtual void applyActorData(void *data, PxGpuActorPair *index, PxActorCacheFlag::Enum flag, const PxU32 nbUpdatedActors, void *waitEvent = NULL, void *signalEvent = NULL) = 0

Apply user-provided data to rigid body.

Parameters

data – [in] User-provided gpu data buffer which should be sized appropriately for the particular data that is requested. Further details provided in the user guide.
index – [in] User provided PxGpuActorPair buffer. This buffer stores pairs of indices: the PxNodeIndex corresponding to the rigid body and an index corresponding to the location in the user buffer that this value should be placed.
flag – [in] Flag defining which data the user wants to write to the rigid body
nbUpdatedActors – [in] The number of updated rigid body
waitEvent – [in] User-provided event for the rigid body stream to wait for data
signalEvent – [in] User-provided event for the rigid body stream to signal when the read from the user buffer has completed

virtual void evaluateSDFDistances(const PxU32 *sdfShapeIds, const PxU32 nbShapes, const PxVec4 *localSamplePointsConcatenated, const PxU32 *samplePointCountPerShape, const PxU32 maxPointCount, PxVec4 *localGradientAndSDFConcatenated, void *event = NULL) = 0

Evaluate sample point distances on sdf shapes.

Parameters

sdfShapeIds – [in] The shapes ids in a gpu buffer (must be triangle mesh shapes with SDFs) which specify the shapes from which the sdf information is taken
nbShapes – [in] The number of shapes
localSamplePointsConcatenated – [in] User-provided gpu buffer containing the sample point locations for every shape in the shapes local space. The buffer stride is maxPointCount.
samplePointCountPerShape – [in] Gpu buffer containing the number of sample points for every shape
maxPointCount – [in] The maximum value in the array samplePointCountPerShape
localGradientAndSDFConcatenated – [out] The gpu buffer where the evaluated distances and gradients in SDF local space get stored. It has the same structure as localSamplePointsConcatenated.
event – [in] User-provided event for the user to sync

virtual void computeDenseJacobians(const PxIndexDataPair *indices, PxU32 nbIndices, void *computeEvent) = 0

Compute dense Jacobian matrices for specified articulations on the GPU.

The size of Jacobians can vary by articulation, since it depends on the number of links, degrees-of-freedom, and whether the base is fixed.

The size is determined using these formulas: nCols = (fixedBase ? 0 : 6) + dofCount nRows = (fixedBase ? 0 : 6) + (linkCount - 1) * 6;

The user must ensure that adequate space is provided for each Jacobian matrix.

Parameters

indices – [in] User-provided gpu buffer of (index, data) pairs. The entries map a GPU articulation index to a GPU block of memory where the returned Jacobian will be stored.
nbIndices – [in] The number of (index, data) pairs provided.
computeEvent – [in] User-provided event for the user to sync data.

virtual void computeGeneralizedMassMatrices(const PxIndexDataPair *indices, PxU32 nbIndices, void *computeEvent) = 0

Compute the joint-space inertia matrices that maps joint accelerations to joint forces: forces = M * accelerations on the GPU.

The size of matrices can vary by articulation, since it depends on the number of links and degrees-of-freedom.

The size is determined using this formula: sizeof(float) * dofCount * dofCount

The user must ensure that adequate space is provided for each mass matrix.

Parameters

indices – [in] User-provided gpu buffer of (index, data) pairs. The entries map a GPU articulation index to a GPU block of memory where the returned matrix will be stored.
nbIndices – [in] The number of (index, data) pairs provided.
computeEvent – [in] User-provided event for the user to sync data.

virtual void computeGeneralizedGravityForces(const PxIndexDataPair *indices, PxU32 nbIndices, void *computeEvent) = 0

Computes the joint DOF forces required to counteract gravitational forces for the given articulation pose.

The size of the result can vary by articulation, since it depends on the number of links and degrees-of-freedom.

The size is determined using this formula: sizeof(float) * dofCount

The user must ensure that adequate space is provided for each articulation.

Parameters

indices – [in] User-provided gpu buffer of (index, data) pairs. The entries map a GPU articulation index to a GPU block of memory where the returned matrix will be stored.
nbIndices – [in] The number of (index, data) pairs provided.
computeEvent – [in] User-provided event for the user to sync data.

virtual void computeCoriolisAndCentrifugalForces(const PxIndexDataPair *indices, PxU32 nbIndices, void *computeEvent) = 0

Computes the joint DOF forces required to counteract coriolis and centrifugal forces for the given articulation pose.

The size of the result can vary by articulation, since it depends on the number of links and degrees-of-freedom.

The size is determined using this formula: sizeof(float) * dofCount

The user must ensure that adequate space is provided for each articulation.

Parameters

indices – [in] User-provided gpu buffer of (index, data) pairs. The entries map a GPU articulation index to a GPU block of memory where the returned matrix will be stored.
nbIndices – [in] The number of (index, data) pairs provided.
computeEvent – [in] User-provided event for the user to sync data.

virtual PxgDynamicsMemoryConfig getGpuDynamicsConfig() const = 0

virtual void applyParticleBufferData(const PxU32 *indices, const PxGpuParticleBufferIndexPair *bufferIndexPair, const PxParticleBufferFlags *flags, PxU32 nbUpdatedBuffers, void *waitEvent = NULL, void *signalEvent = NULL) = 0

Apply user-provided data to particle buffers.

This function should be used if the particle buffer flags are already on the device. Otherwise, use PxParticleBuffer::raiseFlags() from the CPU.

This assumes the data has been changed directly in the PxParticleBuffer.

Parameters

indices – [in] User-provided index buffer that indexes into the BufferIndexPair and flags list.
bufferIndexPair – [in] User-provided index pair buffer specifying the unique id and GPU particle system for each PxParticleBuffer. See PxGpuParticleBufferIndexPair.
flags – [in] Flags to mark what data needs to be updated. See PxParticleBufferFlags.
nbUpdatedBuffers – [in] The number of particle buffers to update.
waitEvent – [in] User-provided event for the particle stream to wait for data.
signalEvent – [in] User-provided event for the particle stream to signal when the data read from the user buffer has completed.

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.