PxSceneDesc

Defined in include/PxSceneDesc.h

class PxSceneDesc : public PxSceneQueryDesc

Descriptor class for scenes.

See PxScene.

This struct must be initialized with the same PxTolerancesScale values used to initialize PxPhysics.

See also

PxScene PxPhysics.createScene PxTolerancesScale

Public Functions

inline PxSceneDesc(const PxTolerancesScale &scale)

constructor sets to default.

See also

PxCreatePhysics() PxTolerancesScale bounceThresholdVelocity frictionOffsetThreshold

Parameters

scale – [in] scale values for the tolerances in the scene, these must be the same values passed into PxCreatePhysics(). The affected tolerances are bounceThresholdVelocity and frictionOffsetThreshold.

inline void setToDefault(const PxTolerancesScale &scale)

(re)sets the structure to the default.

See also

PxCreatePhysics() PxTolerancesScale bounceThresholdVelocity frictionOffsetThreshold

Parameters

scale – [in] scale values for the tolerances in the scene, these must be the same values passed into PxCreatePhysics(). The affected tolerances are bounceThresholdVelocity and frictionOffsetThreshold.

inline bool isValid() const

Returns true if the descriptor is valid.

Returns

true if the current settings are valid.

inline void setToDefault()

(re)sets the structure to the default.

Public Members

PxVec3 gravity

Gravity vector.

Range: force vectorDefault: Zero

When setting gravity, you should probably also set bounce threshold.

See also

PxScene.setGravity() PxScene.getGravity()

PxSimulationEventCallback *simulationEventCallback

Possible notification callback.

Default: NULL

See also

PxSimulationEventCallback PxScene.setSimulationEventCallback() PxScene.getSimulationEventCallback()

PxContactModifyCallback *contactModifyCallback

Possible asynchronous callback for contact modification.

Default: NULL

See also

PxContactModifyCallback PxScene.setContactModifyCallback() PxScene.getContactModifyCallback()

PxCCDContactModifyCallback *ccdContactModifyCallback

Possible asynchronous callback for contact modification.

Default: NULL

See also

PxContactModifyCallback PxScene.setContactModifyCallback() PxScene.getContactModifyCallback()

const void *filterShaderData

Shared global filter data which will get passed into the filter shader.

Default: NULL

See also

PxSimulationFilterShader PxScene.setFilterShaderData() PxScene.getFilterShaderData()

Note

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

PxU32 filterShaderDataSize

Size (in bytes) of the shared global filter data filterShaderData.

Default: 0

See also

PxSimulationFilterShader filterShaderData PxScene.getFilterShaderDataSize()

PxSimulationFilterShader filterShader

The custom filter shader to use for collision filtering.

See also

PxSimulationFilterShader PxScene.getFilterShader()

Note

This parameter is compulsory. If you don’t want to define your own filter shader you can use the default shader PxDefaultSimulationFilterShader which can be found in the PhysX extensions library.

PxSimulationFilterCallback *filterCallback

A custom collision filter callback which can be used to implement more complex filtering operations which need access to the simulation state, for example.

Default: NULL

See also

PxSimulationFilterCallback PxScene.getFilterCallback()

PxPairFilteringMode::Enum kineKineFilteringMode

Filtering mode for kinematic-kinematic pairs in the broadphase.

Default: PxPairFilteringMode::eDEFAULT

See also

PxPairFilteringMode PxScene.getKinematicKinematicFilteringMode()

PxPairFilteringMode::Enum staticKineFilteringMode

Filtering mode for static-kinematic pairs in the broadphase.

Default: PxPairFilteringMode::eDEFAULT

See also

PxPairFilteringMode PxScene.getStaticKinematicFilteringMode()

PxBroadPhaseType::Enum broadPhaseType

Selects the broad-phase algorithm to use.

Default: PxBroadPhaseType::ePABP

See also

PxBroadPhaseType PxScene.getBroadPhaseType()

PxBroadPhaseCallback *broadPhaseCallback

Broad-phase callback.

Default: NULL

See also

PxBroadPhaseCallback PxScene.getBroadPhaseCallback() PxScene.setBroadPhaseCallback()

PxSceneLimits limits

Expected scene limits.

See also

PxSceneLimits PxScene.getLimits()

PxFrictionType::Enum frictionType

Selects the friction algorithm to use for simulation.

Default: PxFrictionType::ePATCH

See also

PxFrictionType PxScene.setFrictionType(), PxScene.getFrictionType()

Note

frictionType cannot be modified after the first call to any of PxScene::simulate, PxScene::solve and PxScene::collide

PxSolverType::Enum solverType

Selects the solver algorithm to use.

Default: PxSolverType::ePGS

See also

PxSolverType PxScene.getSolverType()

PxReal bounceThresholdVelocity

A contact with a relative velocity below this will not bounce.

A typical value for simulation. stability is about 0.2 * gravity.

Range: (0, PX_MAX_F32)Default: 0.2 * PxTolerancesScale::speed

See also

PxMaterial PxScene.setBounceThresholdVelocity() PxScene.getBounceThresholdVelocity()

PxReal frictionOffsetThreshold

A threshold of contact separation distance used to decide if a contact point will experience friction forces.

Range: [0, PX_MAX_F32)Default: 0.04 * PxTolerancesScale::length

See also

PxScene.setFrictionOffsetThreshold() PxScene.getFrictionOffsetThreshold()

Note

If the separation distance of a contact point is greater than the threshold then the contact point will not experience friction forces.

Note

If the aggregated contact offset of a pair of shapes is large it might be desirable to neglect friction for contact points whose separation distance is sufficiently large that the shape surfaces are clearly separated.

Note

This parameter can be used to tune the separation distance of contact points at which friction starts to have an effect.

PxReal frictionCorrelationDistance

Friction correlation distance used to decide whether contacts are close enough to be merged into a single friction anchor point or not.

Range: [0, PX_MAX_F32)Default: 0.025f * PxTolerancesScale::length

See also

PxScene.setFrictionCorrelationDistance() PxScene.getFrictionCorrelationDistance()

Note

If the correlation distance is larger than the distance between contact points generated between a pair of shapes, some of the contacts may not experience frictional forces.

Note

This parameter can be used to tune the correlation distance used in the solver. Contact points can be merged into a single friction anchor if the distance between the contacts is smaller than correlation distance.

PxSceneFlags flags

Flags used to select scene options.

Default: PxSceneFlag::eENABLE_PCM

See also

PxSceneFlag PxSceneFlags PxScene.getFlags() PxScene.setFlag()

PxCpuDispatcher *cpuDispatcher

The CPU task dispatcher for the scene.

See also

PxCpuDispatcher, PxScene::getCpuDispatcher

PxCudaContextManager *cudaContextManager

The CUDA context manager for the scene.

Platform specific: Applies to PC GPU only.

See also

PxCudaContextManager, PxScene::getCudaContextManager

void *userData

Will be copied to PxScene::userData.

Default: NULL

PxU32 solverBatchSize

Defines the number of actors required to spawn a separate rigid body solver island task chain.

This parameter defines the minimum number of actors required to spawn a separate rigid body solver task chain. Setting a low value will potentially cause more task chains to be generated. This may result in the overhead of spawning tasks can become a limiting performance factor. Setting a high value will potentially cause fewer islands to be generated. This may reduce thread scaling (fewer task chains spawned) and may detrimentally affect performance if some bodies in the scene have large solver iteration counts because all constraints in a given island are solved by the maximum number of solver iterations requested by any body in the island.

Note that a rigid body solver task chain is spawned as soon as either a sufficient number of rigid bodies or articulations are batched together.

Default: 128

See also

PxScene.setSolverBatchSize() PxScene.getSolverBatchSize()

PxU32 solverArticulationBatchSize

Defines the number of articulations required to spawn a separate rigid body solver island task chain.

This parameter defines the minimum number of articulations required to spawn a separate rigid body solver task chain. Setting a low value will potentially cause more task chains to be generated. This may result in the overhead of spawning tasks can become a limiting performance factor. Setting a high value will potentially cause fewer islands to be generated. This may reduce thread scaling (fewer task chains spawned) and may detrimentally affect performance if some bodies in the scene have large solver iteration counts because all constraints in a given island are solved by the maximum number of solver iterations requested by any body in the island.

Note that a rigid body solver task chain is spawned as soon as either a sufficient number of rigid bodies or articulations are batched together.

Default: 16

See also

PxScene.setSolverArticulationBatchSize() PxScene.getSolverArticulationBatchSize()

PxU32 nbContactDataBlocks

Setting to define the number of 16K blocks that will be initially reserved to store contact, friction, and contact cache data.

This is the number of 16K memory blocks that will be automatically allocated from the user allocator when the scene is instantiated. Further 16k memory blocks may be allocated during the simulation up to maxNbContactDataBlocks.

Default: 0

Range: [0, PX_MAX_U32]

See also

PxPhysics::createScene PxScene::setNbContactDataBlocks

Note

This value cannot be larger than maxNbContactDataBlocks because that defines the maximum number of 16k blocks that can be allocated by the SDK.

PxU32 maxNbContactDataBlocks

Setting to define the maximum number of 16K blocks that can be allocated to store contact, friction, and contact cache data.

As the complexity of a scene increases, the SDK may require to allocate new 16k blocks in addition to the blocks it has already allocated. This variable controls the maximum number of blocks that the SDK can allocate.

In the case that the scene is sufficiently complex that all the permitted 16K blocks are used, contacts will be dropped and a warning passed to the error stream.

If a warning is reported to the error stream to indicate the number of 16K blocks is insufficient for the scene complexity then the choices are either (i) re-tune the number of 16K data blocks until a number is found that is sufficient for the scene complexity, (ii) to simplify the scene or (iii) to opt to not increase the memory requirements of physx and accept some dropped contacts.

Default: 65536

Range: [0, PX_MAX_U32]

See also

nbContactDataBlocks PxScene.setNbContactDataBlocks()

PxReal maxBiasCoefficient

The maximum bias coefficient used in the constraint solver.

When geometric errors are found in the constraint solver, either as a result of shapes penetrating or joints becoming separated or violating limits, a bias is introduced in the solver position iterations to correct these errors. This bias is proportional to 1/dt, meaning that the bias becomes increasingly strong as the time-step passed to PxScene::simulate(…) becomes smaller. This coefficient allows the application to restrict how large the bias coefficient is, to reduce how violent error corrections are. This can improve simulation quality in cases where either variable time-steps or extremely small time-steps are used.

Default: PX_MAX_F32

Range [0, PX_MAX_F32]

See also

PxScene.setMaxBiasCoefficient() PxScene.getMaxBiasCoefficient()

PxU32 contactReportStreamBufferSize

Size of the contact report stream (in bytes).

The contact report stream buffer is used during the simulation to store all the contact reports. If the size is not sufficient, the buffer will grow by a factor of two. It is possible to disable the buffer growth by setting the flag PxSceneFlag::eDISABLE_CONTACT_REPORT_BUFFER_RESIZE. In that case the buffer will not grow but contact reports not stored in the buffer will not get sent in the contact report callbacks.

Default: 8192

Range: (0, PX_MAX_U32]

See also

PxScene.getContactReportStreamBufferSize()

PxU32 ccdMaxPasses

Maximum number of CCD passes.

The CCD performs multiple passes, where each pass every object advances to its time of first impact. This value defines how many passes the CCD system should perform.

Default: 1 Range: [1, PX_MAX_U32]

See also

PxScene.setCCDMaxPasses() PxScene.getCCDMaxPasses()

Note

The CCD system is a multi-pass best-effort conservative advancement approach. After the defined number of passes has been completed, any remaining time is dropped.

Note

This defines the maximum number of passes the CCD can perform. It may perform fewer if additional passes are not necessary.

PxReal ccdThreshold

CCD threshold.

CCD performs sweeps against shapes if and only if the relative motion of the shapes is fast-enough that a collision would be missed by the discrete contact generation. However, in some circumstances, e.g. when the environment is constructed from large convex shapes, this approach may produce undesired simulation artefacts. This parameter defines the minimum relative motion that would be required to force CCD between shapes. The smaller of this value and the sum of the thresholds calculated for the shapes involved will be used.

Default: PX_MAX_F32 Range: [Eps, PX_MAX_F32]

See also

PxScene.setCCDThreshold() PxScene.getCCDThreshold()

Note

It is not advisable to set this to a very small value as this may lead to CCD “jamming” and detrimentally effect performance. This value should be at least larger than the translation caused by a single frame’s gravitational effect

PxReal ccdMaxSeparation

A threshold for speculative CCD.

Used to control whether bias, restitution or a combination of the two are used to resolve the contacts.

Range: [0, PX_MAX_F32)Default: 0.04 * PxTolerancesScale::length

See also

PxScene.setCCDMaxSeparation() PxScene.getCCDMaxSeparation()

Note

This only has any effect on contacting pairs where one of the bodies has PxRigidBodyFlag::eENABLE_SPECULATIVE_CCD raised.

PxReal wakeCounterResetValue

The wake counter reset value.

Calling wakeUp() on objects which support sleeping will set their wake counter value to the specified reset value.

Range: (0, PX_MAX_F32)Default: 0.4 (which corresponds to 20 frames for a time step of 0.02)

See also

PxRigidDynamic::wakeUp() PxArticulationReducedCoordinate::wakeUp() PxScene.getWakeCounterResetValue()

PxBounds3 sanityBounds

The bounds used to sanity check user-set positions of actors and articulation links.

These bounds are used to check the position values of rigid actors inserted into the scene, and positions set for rigid actors already within the scene.

Range: any valid PxBounds3 Default: (-PX_MAX_BOUNDS_EXTENTS, PX_MAX_BOUNDS_EXTENTS) on each axis

PxGpuDynamicsMemoryConfig gpuDynamicsConfig

The pre-allocations performed in the GPU dynamics pipeline.

PxU32 gpuMaxNumPartitions

Limitation for the partitions in the GPU dynamics pipeline.

This variable must be power of 2. A value greater than 32 is currently not supported. Range: (1, 32)

PxU32 gpuMaxNumStaticPartitions

Limitation for the number of static rigid body partitions in the GPU dynamics pipeline.

Range: (1, 255)Default: 16

PxU32 gpuComputeVersion

Defines which compute version the GPU dynamics should target.

DO NOT MODIFY

PxU32 contactPairSlabSize

Defines the size of a contact pool slab.

Contact pairs and associated data are allocated using a pool allocator. Increasing the slab size can trade off some performance spikes when a large number of new contacts are found for an increase in overall memory usage.

Range:(1, PX_MAX_U32)Default: 256

PxSceneQuerySystem *sceneQuerySystem

The scene query sub-system for the scene.

If left to NULL, PxScene will use its usual internal sub-system. If non-NULL, all SQ-related calls will be re-routed to the user-provided implementation. An external SQ implementation is available in the Extensions library (see PxCreateExternalSceneQuerySystem). This can also be fully re-implemented by users if needed.

See also

PxSceneQuerySystem

PxPruningStructureType::Enum staticStructure

Defines the structure used to store static objects (PxRigidStatic actors).

There are usually a lot more static actors than dynamic actors in a scene, so they are stored in a separate structure. The idea is that when dynamic actors move each frame, the static structure remains untouched and does not need updating.

Default: PxPruningStructureType::eDYNAMIC_AABB_TREE

See also

PxPruningStructureType PxSceneSQSystem.getStaticStructure()

Note

Only PxPruningStructureType::eSTATIC_AABB_TREE and PxPruningStructureType::eDYNAMIC_AABB_TREE are allowed here.

PxPruningStructureType::Enum dynamicStructure

Defines the structure used to store dynamic objects (non-PxRigidStatic actors).

Default: PxPruningStructureType::eDYNAMIC_AABB_TREE

See also

PxPruningStructureType PxSceneSQSystem.getDynamicStructure()

PxU32 dynamicTreeRebuildRateHint

Hint for how much work should be done per simulation frame to rebuild the pruning structures.

This parameter gives a hint on the distribution of the workload for rebuilding the dynamic AABB tree pruning structure PxPruningStructureType::eDYNAMIC_AABB_TREE. It specifies the desired number of simulation frames the rebuild process should take. Higher values will decrease the workload per frame but the pruning structure will get more and more outdated the longer the rebuild takes (which can make scene queries less efficient).

Range: [4, PX_MAX_U32)Default: 100

See also

PxSceneQuerySystemBase.setDynamicTreeRebuildRateHint() PxSceneQuerySystemBase.getDynamicTreeRebuildRateHint()

Note

Only used for PxPruningStructureType::eDYNAMIC_AABB_TREE pruning structures.

Note

Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case this parameter is used for both.

Note

This parameter gives only a hint. The rebuild process might still take more or less time depending on the number of objects involved.

PxDynamicTreeSecondaryPruner::Enum dynamicTreeSecondaryPruner

Secondary pruner for dynamic tree.

This is used for PxPruningStructureType::eDYNAMIC_AABB_TREE structures, to control how objects added to the system at runtime are managed.

Default: PxDynamicTreeSecondaryPruner::eINCREMENTAL

See also

PxDynamicTreeSecondaryPruner

Note

Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case this parameter is used for both.

PxBVHBuildStrategy::Enum staticBVHBuildStrategy

Build strategy for PxSceneQueryDesc::staticStructure.

This parameter is used to refine / control the build strategy of PxSceneQueryDesc::staticStructure. This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

Default: PxBVHBuildStrategy::eFAST

See also

PxBVHBuildStrategy PxSceneQueryDesc::staticStructure

PxBVHBuildStrategy::Enum dynamicBVHBuildStrategy

Build strategy for PxSceneQueryDesc::dynamicStructure.

This parameter is used to refine / control the build strategy of PxSceneQueryDesc::dynamicStructure. This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

Default: PxBVHBuildStrategy::eFAST

See also

PxBVHBuildStrategy PxSceneQueryDesc::dynamicStructure

PxU32 staticNbObjectsPerNode

Number of objects per node for PxSceneQueryDesc::staticStructure.

This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::staticStructure. This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and update, but it can lead to slower queries.

Default: 4

See also

PxSceneQueryDesc::staticStructure

PxU32 dynamicNbObjectsPerNode

Number of objects per node for PxSceneQueryDesc::dynamicStructure.

This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::dynamicStructure. This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.

This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and update, but it can lead to slower queries.

Default: 4

See also

PxSceneQueryDesc::dynamicStructure

PxSceneQueryUpdateMode::Enum sceneQueryUpdateMode

Defines the scene query update mode.

Default: PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED

See also

PxSceneQuerySystemBase.setUpdateMode() PxSceneQuerySystemBase.getUpdateMode()