Module de.fabmax.physxjni
Package physx.physics

Class PxScene

java.lang.Object
physx.NativeObject
physx.physics.PxSceneQuerySystemBase
physx.physics.PxSceneSQSystem
physx.physics.PxScene
public class PxScene extends 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.

See Also:

  • Field Details

    • SIZEOF

      public static final int SIZEOF

    • ALIGNOF

      public static final int ALIGNOF
      See Also:

  • Constructor Details

    • PxScene

      protected PxScene()

    • PxScene

      protected PxScene(long address)

  • Method Details

    • wrapPointer

      public static PxScene wrapPointer(long address)

    • arrayGet

      public static PxScene arrayGet(long baseAddress, int index)

    • getUserData

      public NativeObject getUserData()
      user can assign this to whatever, usually to create a 1:1 relationship with a user object.

    • setUserData

      public void setUserData(NativeObject value)
      user can assign this to whatever, usually to create a 1:1 relationship with a user object.

    • addActor

      public boolean addActor(PxActor actor)
      Adds an actor to this scene.

      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 - Actor to add to scene.
      Returns:
      True if success
      See Also:

    • addActor

      public boolean addActor(PxActor actor, PxBVH bvh)
      Adds an actor to this scene.

      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 - Actor to add to scene.
      bvh - BVH for actor shapes.
      Returns:
      True if success
      See Also:

    • removeActor

      public void removeActor(PxActor actor)
      Removes an actor from this scene.

      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 - Actor to remove from scene.
      See Also:

    • removeActor

      public void removeActor(PxActor actor, boolean wakeOnLostTouch)
      Removes an actor from this scene.

      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 - Actor to remove from scene.
      wakeOnLostTouch - Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.
      See Also:

    • addAggregate

      public boolean addAggregate(PxAggregate aggregate)
      Adds an aggregate to this scene.

      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 - Aggregate to add to scene.
      Returns:
      True if success

    • removeAggregate

      public void removeAggregate(PxAggregate aggregate)
      Removes an aggregate from this scene.

      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 - Aggregate to remove from scene.
      See Also:

    • removeAggregate

      public void removeAggregate(PxAggregate aggregate, boolean wakeOnLostTouch)
      Removes an aggregate from this scene.

      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 - Aggregate to remove from scene.
      wakeOnLostTouch - Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.
      See Also:

    • addCollection

      public boolean addCollection(PxCollection collection)
      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.

      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 - Objects to add to this scene. See #PxCollection
      Returns:
      True if success

    • getWakeCounterResetValue

      public float getWakeCounterResetValue()
      Returns the wake counter reset value.
      Returns:
      Wake counter reset value

    • shiftOrigin

      public void shiftOrigin(PxVec3 shift)
      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 - Translation vector to shift the origin by.

    • addArticulation

      public boolean addArticulation(PxArticulationReducedCoordinate articulation)
      Adds an articulation to this scene.

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

      Parameters:
      articulation - The articulation to add to the scene.
      Returns:
      True if success
      See Also:

    • removeArticulation

      public void removeArticulation(PxArticulationReducedCoordinate articulation)
      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 - The articulation to remove from the scene. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.
      See Also:

    • removeArticulation

      public void removeArticulation(PxArticulationReducedCoordinate articulation, boolean wakeOnLostTouch)
      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 - The articulation to remove from the scene.
      wakeOnLostTouch - Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulationReducedCoordinate and PxRigidActor types.
      See Also:

    • getNbActors

      public int getNbActors(PxActorTypeFlags types)
      Retrieve the number of actors of certain types in the scene. For supported types, see PxActorTypeFlags.
      Parameters:
      types - Combination of actor types.
      Returns:
      the number of actors.

    • getNbSoftBodies

      public int getNbSoftBodies()
      Retrieve the number of soft bodies in the scene.
      Returns:
      the number of soft bodies.

    • getNbParticleSystems

      @Deprecated public int getNbParticleSystems(PxParticleSolverTypeEnum type)
      Deprecated.
      Use getNbPBDParticleSystems() instead. Retrieve the number of particle systems of the requested type in the scene.
      Parameters:
      type - The particle system type. See PxParticleSolverType. Only one type can be requested per function call.
      Returns:
      the number particle systems.

      See getPBDParticleSystems(), PxParticleSolverType

    • getNbArticulations

      public int getNbArticulations()
      Returns the number of articulations in the scene.
      Returns:
      the number of articulations in this scene.

    • getNbConstraints

      public int getNbConstraints()
      Returns the number of constraint shaders in the scene.
      Returns:
      the number of constraint shaders in this scene.

    • getNbAggregates

      public int getNbAggregates()
      Returns the number of aggregates in the scene.
      Returns:
      the number of aggregates in this scene.

    • setDominanceGroupPair

      public void setDominanceGroupPair(byte group1, byte group2, PxDominanceGroupPair dominance)
      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.

      See Also:

    • getDominanceGroupPair

      public PxDominanceGroupPair getDominanceGroupPair(byte group1, byte group2)
      Samples the dominance matrix.
      See Also:

    • getCpuDispatcher

      public PxCpuDispatcher getCpuDispatcher()
      Return the cpu dispatcher that was set in PxSceneDesc::cpuDispatcher when creating the scene with PxPhysics::createScene

    • getCudaContextManager

      public PxCudaContextManager getCudaContextManager()
      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.

    • createClient

      public byte createClient()
      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.

    • setSimulationEventCallback

      public void setSimulationEventCallback(PxSimulationEventCallback callback)
      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 - User notification callback. See #PxSimulationEventCallback.
      See Also:

    • getSimulationEventCallback

      public PxSimulationEventCallback getSimulationEventCallback()
      Retrieves the simulationEventCallback pointer set with setSimulationEventCallback().
      Returns:
      The current user notify pointer. See #PxSimulationEventCallback.
      See Also:

    • setFilterShaderData

      public void setFilterShaderData(NativeObject data, int dataSize)
      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 - The shared global filter shader data.
      dataSize - Size of the shared global filter shader data (in bytes).
      See Also:

    • getFilterShaderData

      public NativeObject getFilterShaderData()
      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.
      See Also:

    • getFilterShaderDataSize

      public int getFilterShaderDataSize()
      Gets the size of the shared global filter data (#PxSceneDesc.filterShaderData)
      Returns:
      Size of shared filter data [bytes].
      See Also:

    • getFilterShader

      public PxSimulationFilterShader getFilterShader()
      Gets the custom collision filter shader in use for this scene.
      Returns:
      Filter shader class that defines the collision pair filtering.
      See Also:

    • resetFiltering

      public boolean resetFiltering(PxActor actor)
      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.

      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.

      Sleeping: Does wake up the actor.

      Parameters:
      actor - The actor for which to re-evaluate interactions.
      Returns:
      True if success
      See Also:

    • getKinematicKinematicFilteringMode

      public PxPairFilteringModeEnum getKinematicKinematicFilteringMode()
      Gets the pair filtering mode for kinematic-kinematic pairs.
      Returns:
      Filtering mode for kinematic-kinematic pairs.
      See Also:

    • getStaticKinematicFilteringMode

      public PxPairFilteringModeEnum getStaticKinematicFilteringMode()
      Gets the pair filtering mode for static-kinematic pairs.
      Returns:
      Filtering mode for static-kinematic pairs.
      See Also:

    • simulate

      public boolean simulate(float elapsedTime)
      Advances the simulation by an elapsedTime time.

      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.

      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.

      Parameters:
      elapsedTime - 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) decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference(). after fetchResults returns. Must be aligned on a 16-byte boundary
      Returns:
      True if success
      See Also:

    • simulate

      public boolean simulate(float elapsedTime, PxBaseTask completionTask)
      Advances the simulation by an elapsedTime time.

      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.

      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.

      Parameters:
      elapsedTime - 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 - 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(). after fetchResults returns. Must be aligned on a 16-byte boundary
      Returns:
      True if success
      See Also:

    • simulate

      public boolean simulate(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock)
      Advances the simulation by an elapsedTime time.

      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.

      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.

      Parameters:
      elapsedTime - 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 - 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 - 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
      Returns:
      True if success
      See Also:

    • simulate

      public boolean simulate(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock, int scratchMemBlockSize)
      Advances the simulation by an elapsedTime time.

      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.

      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.

      Parameters:
      elapsedTime - 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 - 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 - 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 - the size of the scratch memory block. Must be a multiple of 16K.
      Returns:
      True if success
      See Also:

    • simulate

      public boolean simulate(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock, int scratchMemBlockSize, boolean controlSimulation)
      Advances the simulation by an elapsedTime time.

      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.

      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.

      Parameters:
      elapsedTime - 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 - 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 - 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 - the size of the scratch memory block. Must be a multiple of 16K.
      controlSimulation - 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
      See Also:

    • advance

      public boolean advance()
      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.

      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

    • advance

      public boolean advance(PxBaseTask completionTask)
      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 - 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

    • collide

      public boolean collide(float elapsedTime)
      Performs collision detection for the scene over elapsedTime

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

      Parameters:
      elapsedTime - 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) decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference(). after fetchResults returns. Must be aligned on a 16-byte boundary
      Returns:
      True if success

    • collide

      public boolean collide(float elapsedTime, PxBaseTask completionTask)
      Performs collision detection for the scene over elapsedTime

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

      Parameters:
      elapsedTime - 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 - 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(). after fetchResults returns. Must be aligned on a 16-byte boundary
      Returns:
      True if success

    • collide

      public boolean collide(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock)
      Performs collision detection for the scene over elapsedTime

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

      Parameters:
      elapsedTime - 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 - 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 - 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
      Returns:
      True if success

    • collide

      public boolean collide(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock, int scratchMemBlockSize)
      Performs collision detection for the scene over elapsedTime

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

      Parameters:
      elapsedTime - 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 - 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 - 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 - the size of the scratch memory block. Must be a multiple of 16K.
      Returns:
      True if success

    • collide

      public boolean collide(float elapsedTime, PxBaseTask completionTask, NativeObject scratchMemBlock, int scratchMemBlockSize, boolean controlSimulation)
      Performs collision detection for the scene over elapsedTime

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

      Parameters:
      elapsedTime - 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 - 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 - 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 - the size of the scratch memory block. Must be a multiple of 16K.
      controlSimulation - 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

    • checkResults

      public boolean checkResults()
      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

      Returns:
      True if the results are available.
      See Also:

    • checkResults

      public boolean checkResults(boolean block)
      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

      Parameters:
      block - When set to true will block until the condition is met.
      Returns:
      True if the results are available.
      See Also:

    • fetchCollision

      public boolean fetchCollision()
      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.

    • fetchCollision

      public boolean fetchCollision(boolean block)
      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 - When set to true will block until the condition is met, which is collision must finish running.

    • fetchResults

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

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

      \endcode

      Returns:
      True if the results have been fetched.
      See Also:

    • fetchResults

      public boolean fetchResults(boolean block)
      This is the big brother to checkResults() it basically does the following:

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

      \endcode

      Parameters:
      block - When set to true will block until results are available.
      Returns:
      True if the results have been fetched.
      See Also:

    • processCallbacks

      public void processCallbacks(PxBaseTask continuation)
      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 - The task that will be executed once all callbacks have been processed.

    • fetchResultsParticleSystem

      public void fetchResultsParticleSystem()
      This call performs the synchronization of particle system data copies.

    • flushSimulation

      public void flushSimulation()
      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.

    • flushSimulation

      public void flushSimulation(boolean sendPendingReports)
      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 - 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).

    • setGravity

      public void setGravity(PxVec3 vec)
      Sets a constant gravity for the entire scene.

      Note: Do not use this method while the simulation is running.

      Sleeping: Does NOT wake the actor up automatically.

      Parameters:
      vec - A new gravity vector(e.g. PxVec3(0.0f,-9.8f,0.0f) ) Range: force vector
      See Also:

    • getGravity

      public PxVec3 getGravity()
      Retrieves the current gravity setting.
      Returns:
      The current gravity for the scene.
      See Also:

    • setBounceThresholdVelocity

      public void setBounceThresholdVelocity(float t)
      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.

      See Also:

    • getBounceThresholdVelocity

      public float getBounceThresholdVelocity()
      Return the bounce threshold velocity.
      See Also:

    • setCCDMaxPasses

      public void setCCDMaxPasses(int ccdMaxPasses)
      Sets the maximum number of CCD passes

      Note: Do not use this method while the simulation is running.

      Parameters:
      ccdMaxPasses - Maximum number of CCD passes
      See Also:

    • getCCDMaxPasses

      public int getCCDMaxPasses()
      Gets the maximum number of CCD passes.
      Returns:
      The maximum number of CCD passes.
      See Also:

    • setCCDMaxSeparation

      public void setCCDMaxSeparation(float t)
      Set the maximum CCD separation.

      Note: Do not use this method while the simulation is running.

      See Also:

    • getCCDMaxSeparation

      public float getCCDMaxSeparation()
      Gets the maximum CCD separation.
      Returns:
      The maximum CCD separation.
      See Also:

    • setCCDThreshold

      public void setCCDThreshold(float t)
      Set the CCD threshold.

      Note: Do not use this method while the simulation is running.

      See Also:

    • getCCDThreshold

      public float getCCDThreshold()
      Gets the CCD threshold.
      Returns:
      The CCD threshold.
      See Also:

    • setMaxBiasCoefficient

      public void setMaxBiasCoefficient(float t)
      Set the max bias coefficient.

      Note: Do not use this method while the simulation is running.

      See Also:

    • getMaxBiasCoefficient

      public float getMaxBiasCoefficient()
      Gets the max bias coefficient.
      Returns:
      The max bias coefficient.
      See Also:

    • setFrictionOffsetThreshold

      public void setFrictionOffsetThreshold(float t)
      Set the friction offset threshold.

      Note: Do not use this method while the simulation is running.

      See Also:

    • getFrictionOffsetThreshold

      public float getFrictionOffsetThreshold()
      Gets the friction offset threshold.
      See Also:

    • setFrictionCorrelationDistance

      public void setFrictionCorrelationDistance(float t)
      Set the friction correlation distance.

      Note: Do not use this method while the simulation is running.

      See Also:

    • getFrictionCorrelationDistance

      public float getFrictionCorrelationDistance()
      Gets the friction correlation distance.
      See Also:

    • getFrictionType

      public PxFrictionTypeEnum getFrictionType()
      Return the friction model.

    • getSolverType

      public PxSolverTypeEnum getSolverType()
      Return the solver model.

    • getRenderBuffer

      public PxRenderBuffer getRenderBuffer()
      Retrieves the render buffer.

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

      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.
      See Also:

    • setVisualizationParameter

      public boolean setVisualizationParameter(PxVisualizationParameterEnum param, float value)
      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 - Parameter to set. See #PxVisualizationParameter
      value - 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.
      See Also:

    • getVisualizationParameter

      public float getVisualizationParameter(PxVisualizationParameterEnum paramEnum)
      Function that lets you query debug visualization parameters.
      Parameters:
      paramEnum - The Parameter to retrieve.
      Returns:
      The value of the parameter.
      See Also:

    • setVisualizationCullingBox

      public void setVisualizationCullingBox(PxBounds3 box)
      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 - the box to which the geometry will be culled. Empty box to disable the feature.
      See Also:

    • getVisualizationCullingBox

      public PxBounds3 getVisualizationCullingBox()
      Retrieves the visualization culling box.
      Returns:
      the box to which the geometry will be culled.
      See Also:

    • getSimulationStatistics

      public void getSimulationStatistics(PxSimulationStatistics stats)
      Call this method to retrieve statistics for the current simulation step.

      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 - Used to retrieve statistics for the current simulation step.
      See Also:

    • getBroadPhaseType

      public PxBroadPhaseTypeEnum getBroadPhaseType()
      Returns broad-phase type.
      Returns:
      Broad-phase type

    • getBroadPhaseCaps

      public boolean getBroadPhaseCaps(PxBroadPhaseCaps caps)
      Gets broad-phase caps.
      Parameters:
      caps - Broad-phase caps
      Returns:
      True if success

    • getNbBroadPhaseRegions

      public int getNbBroadPhaseRegions()
      Returns number of regions currently registered in the broad-phase.
      Returns:
      Number of regions

    • getBroadPhaseRegions

      public int getBroadPhaseRegions(PxBroadPhaseRegionInfo userBuffer, int bufferSize)
      Gets broad-phase regions.
      Parameters:
      userBuffer - Returned broad-phase regions
      bufferSize - Size of userBuffer
      Returns:
      Number of written out regions

    • getBroadPhaseRegions

      public int getBroadPhaseRegions(PxBroadPhaseRegionInfo userBuffer, int bufferSize, int startIndex)
      Gets broad-phase regions.
      Parameters:
      userBuffer - Returned broad-phase regions
      bufferSize - Size of userBuffer
      startIndex - Index of first desired region, in [0 ; getNbRegions()[
      Returns:
      Number of written out regions

    • addBroadPhaseRegion

      public int addBroadPhaseRegion(PxBroadPhaseRegion region)
      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.

      Parameters:
      region - User-provided region data
      Returns:
      Handle for newly created region, or 0xffffffff in case of failure.
      See Also:

    • addBroadPhaseRegion

      public int addBroadPhaseRegion(PxBroadPhaseRegion region, boolean populateRegion)
      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.

      Parameters:
      region - User-provided region data
      populateRegion - Automatically populate new region with already existing objects overlapping it
      Returns:
      Handle for newly created region, or 0xffffffff in case of failure.
      See Also:

    • removeBroadPhaseRegion

      public boolean removeBroadPhaseRegion(int handle)
      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 - Region's handle, as returned by PxScene::addBroadPhaseRegion.
      Returns:
      True if success

    • lockRead

      public void lockRead()
      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().

    • lockRead

      public void lockRead(String file)
      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().

      \param file String representing the calling file, for debug purposes

    • lockRead

      public void lockRead(String file, int line)
      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().

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

    • unlockRead

      public void unlockRead()
      Unlock the scene from reading.

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

    • lockWrite

      public void lockWrite()
      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().

    • lockWrite

      public void lockWrite(String file)
      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().

      \param file String representing the calling file, for debug purposes

    • lockWrite

      public void lockWrite(String file, int line)
      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().

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

    • unlockWrite

      public void unlockWrite()
      Unlock the scene from writing.

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

    • setNbContactDataBlocks

      public void setNbContactDataBlocks(int numBlocks)
      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 - The number of blocks to allocate.
      See Also:

    • getNbContactDataBlocksUsed

      public int getNbContactDataBlocksUsed()
      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
      See Also:

    • getMaxNbContactDataBlocksUsed

      public int getMaxNbContactDataBlocksUsed()
      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
      See Also:

    • getContactReportStreamBufferSize

      public int getContactReportStreamBufferSize()
      Return the value of PxSceneDesc::contactReportStreamBufferSize that was set when creating the scene with PxPhysics::createScene

    • setSolverBatchSize

      public void setSolverBatchSize(int solverBatchSize)
      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 - Number of actors required to spawn a separate rigid body solver thread.
      See Also:

    • getSolverBatchSize

      public int getSolverBatchSize()
      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.
      See Also:

    • setSolverArticulationBatchSize

      public void setSolverArticulationBatchSize(int solverBatchSize)
      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 - Number of articulations required to spawn a separate rigid body solver thread.
      See Also:

    • getSolverArticulationBatchSize

      public int getSolverArticulationBatchSize()
      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.
      See Also:

    • release

      public void release()
      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:

    • setFlag

      public void setFlag(PxSceneFlagEnum flag, boolean value)
      Sets a scene flag. You can only set one flag at a time.

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

    • getFlags

      public PxSceneFlags getFlags()
      Get the scene flags.
      Returns:
      The scene flags. See #PxSceneFlag

    • setLimits

      public void setLimits(PxSceneLimits limits)
      Set new scene limits.

      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 - Scene limits.
      See Also:

    • getLimits

      public PxSceneLimits getLimits()
      Get current scene limits.
      Returns:
      Current scene limits.
      See Also:

    • getPhysics

      public PxPhysics getPhysics()
      Call this method to retrieve the Physics SDK.
      Returns:
      The physics SDK this scene is associated with.
      See Also:

    • getTimestamp

      public int getTimestamp()
      Retrieves the scene's internal timestamp, increased each time a simulation step is completed.
      Returns:
      scene timestamp