1//
2// Redistribution and use in source and binary forms, with or without
3// modification, are permitted provided that the following conditions
4// are met:
5// * Redistributions of source code must retain the above copyright
6// notice, this list of conditions and the following disclaimer.
7// * Redistributions in binary form must reproduce the above copyright
8// notice, this list of conditions and the following disclaimer in the
9// documentation and/or other materials provided with the distribution.
10// * Neither the name of NVIDIA CORPORATION nor the names of its
11// contributors may be used to endorse or promote products derived
12// from this software without specific prior written permission.
13//
14// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
15// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
18// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25//
26// Copyright (c) 2008-2021 NVIDIA Corporation. All rights reserved.
27// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
28// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
29
30
31#ifndef PX_PHYSICS_NX_SCENEDESC
32#define PX_PHYSICS_NX_SCENEDESC
33/** \addtogroup physics
34@{
35*/
36
37#include "PxPhysXConfig.h"
38#include "foundation/PxFlags.h"
39#include "foundation/PxBounds3.h"
40#include "PxFiltering.h"
41#include "PxBroadPhase.h"
42#include "common/PxTolerancesScale.h"
43#include "task/PxTask.h"
44
45#if !PX_DOXYGEN
46namespace physx
47{
48#endif
49
50 class PxCudaContextManager;
51
52/**
53\brief Pruning structure used to accelerate scene queries.
54
55eNONE uses a simple data structure that consumes less memory than the alternatives,
56but generally has slower query performance.
57
58eDYNAMIC_AABB_TREE usually provides the fastest queries. However there is a
59constant per-frame management cost associated with this structure. How much work should
60be done per frame can be tuned via the #PxSceneDesc::dynamicTreeRebuildRateHint
61parameter.
62
63eSTATIC_AABB_TREE is typically used for static objects. It is the same as the
64dynamic AABB tree, without the per-frame overhead. This can be a good choice for static
65objects, if no static objects are added, moved or removed after the scene has been
66created. If there is no such guarantee (e.g. when streaming parts of the world in and out),
67then the dynamic version is a better choice even for static objects.
68
69*/
70struct PxPruningStructureType
71{
72 enum Enum
73 {
74 eNONE, //!< Using a simple data structure
75 eDYNAMIC_AABB_TREE, //!< Using a dynamic AABB tree
76 eSTATIC_AABB_TREE, //!< Using a static AABB tree
77
78 eLAST
79 };
80};
81
82/**
83\brief Scene query update mode
84
85When PxScene::fetchResults is called it does scene query related work, with this enum it is possible to
86set what work is done during the fetchResults.
87
88FetchResults will sync changed bounds during simulation and update the scene query bounds in pruners, this work is mandatory.
89
90eCOMMIT_ENABLED_BUILD_ENABLED does allow to execute the new AABB tree build step during fetchResults, additionally the pruner commit is
91called where any changes are applied. During commit PhysX refits the dynamic scene query tree and if a new tree was built and
92the build finished the tree is swapped with current AABB tree.
93
94eCOMMIT_DISABLED_BUILD_ENABLED does allow to execute the new AABB tree build step during fetchResults. Pruner commit is not called,
95this means that refit will then occur during the first scene query following fetchResults, or may be forced by the method PxScene::flushSceneQueryUpdates().
96
97eCOMMIT_DISABLED_BUILD_DISABLED no further scene query work is executed. The scene queries update needs to be called manually, see PxScene::sceneQueriesUpdate.
98It is recommended to call PxScene::sceneQueriesUpdate right after fetchResults as the pruning structures are not updated.
99
100*/
101struct PxSceneQueryUpdateMode
102{
103 enum Enum
104 {
105 eBUILD_ENABLED_COMMIT_ENABLED, //!< Both scene query build and commit are executed.
106 eBUILD_ENABLED_COMMIT_DISABLED, //!< Scene query build only is executed.
107 eBUILD_DISABLED_COMMIT_DISABLED //!< No work is done, no update of scene queries
108 };
109};
110
111
112/**
113\brief Enum for selecting the friction algorithm used for simulation.
114
115#PxFrictionType::ePATCH selects the patch friction model which typically leads to the most stable results at low solver iteration counts and is also quite inexpensive, as it uses only
116up to four scalar solver constraints per pair of touching objects. The patch friction model is the same basic strong friction algorithm as PhysX 3.2 and before.
117
118#PxFrictionType::eONE_DIRECTIONAL is a simplification of the Coulomb friction model, in which the friction for a given point of contact is applied in the alternating tangent directions of
119the contact's normal. This simplification allows us to reduce the number of iterations required for convergence but is not as accurate as the two directional model.
120
121#PxFrictionType::eTWO_DIRECTIONAL is identical to the one directional model, but it applies friction in both tangent directions simultaneously. This hurts convergence a bit so it
122requires more solver iterations, but is more accurate. Like the one directional model, it is applied at every contact point, which makes it potentially more expensive
123than patch friction for scenarios with many contact points.
124
125#PxFrictionType::eFRICTION_COUNT is the total numer of friction models supported by the SDK.
126*/
127struct PxFrictionType
128{
129 enum Enum
130 {
131 ePATCH, //!< Select default patch-friction model.
132 eONE_DIRECTIONAL, //!< Select one directional per-contact friction model.
133 eTWO_DIRECTIONAL, //!< Select two directional per-contact friction model.
134 eFRICTION_COUNT //!< The total number of friction models supported by the SDK.
135 };
136};
137
138
139/**
140\brief Enum for selecting the type of solver used for the simulation.
141
142#PxSolverType::ePGS selects the default iterative sequential impulse solver. This is the same kind of solver used in PhysX 3.4 and earlier releases.
143
144#PxSolverType::eTGS selects a non linear iterative solver. This kind of solver can lead to improved convergence and handle large mass ratios, long chains and jointed systems better. It is slightly more expensive than the default solver and can introduce more energy to correct joint and contact errors.
145*/
146struct PxSolverType
147{
148 enum Enum
149 {
150 ePGS, //!< Default Projected Gauss-Seidel iterative solver
151 eTGS //!< Temporal Gauss-Seidel solver
152 };
153};
154
155
156/**
157\brief flags for configuring properties of the scene
158
159@see PxScene
160*/
161
162struct PxSceneFlag
163{
164 enum Enum
165 {
166 /**
167 \brief Enable Active Actors Notification.
168
169 This flag enables the Active Actor Notification feature for a scene. This
170 feature defaults to disabled. When disabled, the function
171 PxScene::getActiveActors() will always return a NULL list.
172
173 \note There may be a performance penalty for enabling the Active Actor Notification, hence this flag should
174 only be enabled if the application intends to use the feature.
175
176 <b>Default:</b> False
177 */
178 eENABLE_ACTIVE_ACTORS = (1<<0),
179
180 /**
181 \brief Enables a second broad phase check after integration that makes it possible to prevent objects from tunneling through eachother.
182
183 PxPairFlag::eDETECT_CCD_CONTACT requires this flag to be specified.
184
185 \note For this feature to be effective for bodies that can move at a significant velocity, the user should raise the flag PxRigidBodyFlag::eENABLE_CCD for them.
186 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
187
188 <b>Default:</b> False
189
190 @see PxRigidBodyFlag::eENABLE_CCD, PxPairFlag::eDETECT_CCD_CONTACT, eDISABLE_CCD_RESWEEP
191 */
192 eENABLE_CCD = (1<<1),
193
194 /**
195 \brief Enables a simplified swept integration strategy, which sacrifices some accuracy for improved performance.
196
197 This simplified swept integration approach makes certain assumptions about the motion of objects that are not made when using a full swept integration.
198 These assumptions usually hold but there are cases where they could result in incorrect behavior between a set of fast-moving rigid bodies. A key issue is that
199 fast-moving dynamic objects may tunnel through each-other after a rebound. This will not happen if this mode is disabled. However, this approach will be potentially
200 faster than a full swept integration because it will perform significantly fewer sweeps in non-trivial scenes involving many fast-moving objects. This approach
201 should successfully resist objects passing through the static environment.
202
203 PxPairFlag::eDETECT_CCD_CONTACT requires this flag to be specified.
204
205 \note This scene flag requires eENABLE_CCD to be enabled as well. If it is not, this scene flag will do nothing.
206 \note For this feature to be effective for bodies that can move at a significant velocity, the user should raise the flag PxRigidBodyFlag::eENABLE_CCD for them.
207 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
208
209 <b>Default:</b> False
210
211 @see PxRigidBodyFlag::eENABLE_CCD, PxPairFlag::eDETECT_CCD_CONTACT, eENABLE_CCD
212 */
213 eDISABLE_CCD_RESWEEP = (1<<2),
214
215 /**
216 \brief Enable adaptive forces to accelerate convergence of the solver.
217
218 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
219
220 <b>Default:</b> false
221 */
222 eADAPTIVE_FORCE = (1<<3),
223
224 /**
225 \brief Enable GJK-based distance collision detection system.
226
227 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
228
229 <b>Default:</b> true
230 */
231 eENABLE_PCM = (1 << 6),
232
233 /**
234 \brief Disable contact report buffer resize. Once the contact buffer is full, the rest of the contact reports will
235 not be buffered and sent.
236
237 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
238
239 <b>Default:</b> false
240 */
241 eDISABLE_CONTACT_REPORT_BUFFER_RESIZE = (1 << 7),
242
243 /**
244 \brief Disable contact cache.
245
246 Contact caches are used internally to provide faster contact generation. You can disable all contact caches
247 if memory usage for this feature becomes too high.
248
249 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
250
251 <b>Default:</b> false
252 */
253 eDISABLE_CONTACT_CACHE = (1 << 8),
254
255 /**
256 \brief Require scene-level locking
257
258 When set to true this requires that threads accessing the PxScene use the
259 multi-threaded lock methods.
260
261 \note This flag is not mutable, and must be set in PxSceneDesc at scene creation.
262
263 @see PxScene::lockRead
264 @see PxScene::unlockRead
265 @see PxScene::lockWrite
266 @see PxScene::unlockWrite
267
268 <b>Default:</b> false
269 */
270 eREQUIRE_RW_LOCK = (1 << 9),
271
272 /**
273 \brief Enables additional stabilization pass in solver
274
275 When set to true, this enables additional stabilization processing to improve that stability of complex interactions between large numbers of bodies.
276
277 Note that this flag is not mutable and must be set in PxSceneDesc at scene creation. Also, this is an experimental feature which does result in some loss of momentum.
278 */
279 eENABLE_STABILIZATION = (1 << 10),
280
281 /**
282 \brief Enables average points in contact manifolds
283
284 When set to true, this enables additional contacts to be generated per manifold to represent the average point in a manifold. This can stabilize stacking when only a small
285 number of solver iterations is used.
286
287 Note that this flag is not mutable and must be set in PxSceneDesc at scene creation.
288 */
289 eENABLE_AVERAGE_POINT = (1 << 11),
290
291 /**
292 \brief Do not report kinematics in list of active actors.
293
294 Since the target pose for kinematics is set by the user, an application can track the activity state directly and use
295 this flag to avoid that kinematics get added to the list of active actors.
296
297 \note This flag has only an effect in combination with eENABLE_ACTIVE_ACTORS.
298
299 @see eENABLE_ACTIVE_ACTORS
300
301 <b>Default:</b> false
302 */
303 eEXCLUDE_KINEMATICS_FROM_ACTIVE_ACTORS = (1 << 12),
304
305 /*\brief Enables the GPU dynamics pipeline
306
307 When set to true, a CUDA ARCH 3.0 or above-enabled NVIDIA GPU is present and the CUDA context manager has been configured, this will run the GPU dynamics pipelin instead of the CPU dynamics pipeline.
308
309 Note that this flag is not mutable and must be set in PxSceneDesc at scene creation.
310 */
311 eENABLE_GPU_DYNAMICS = (1 << 13),
312
313 /**
314 \brief Provides improved determinism at the expense of performance.
315
316 By default, PhysX provides limited determinism guarantees. Specifically, PhysX guarantees that the exact scene (same actors created in the same order) and simulated using the same
317 time-stepping scheme should provide the exact same behaviour.
318
319 However, if additional actors are added to the simulation, this can affect the behaviour of the existing actors in the simulation, even if the set of new actors do not interact with
320 the existing actors.
321
322 This flag provides an additional level of determinism that guarantees that the simulation will not change if additional actors are added to the simulation, provided those actors do not interfere
323 with the existing actors in the scene. Determinism is only guaranteed if the actors are inserted in a consistent order each run in a newly-created scene and simulated using a consistent time-stepping
324 scheme.
325
326 Note that this flag is not mutable and must be set at scene creation.
327
328 Note that enabling this flag can have a negative impact on performance.
329
330 Note that this feature is not currently supported on GPU.
331
332 <b>Default</b> false
333 */
334 eENABLE_ENHANCED_DETERMINISM = (1<<14),
335
336 /**
337 \brief Controls processing friction in all solver iterations
338
339 By default, PhysX processes friction only in the final 3 position iterations, and all velocity
340 iterations. This flag enables friction processing in all position and velocity iterations.
341
342 The default behaviour provides a good trade-off between performance and stability and is aimed
343 primarily at game development.
344
345 When simulating more complex frictional behaviour, such as grasping of complex geometries with
346 a robotic manipulator, better results can be achieved by enabling friction in all solver iterations.
347
348 \note This flag only has effect with the default solver. The TGS solver always performs friction per-iteration.
349 */
350 eENABLE_FRICTION_EVERY_ITERATION = (1 << 15),
351
352 eMUTABLE_FLAGS = eENABLE_ACTIVE_ACTORS|eEXCLUDE_KINEMATICS_FROM_ACTIVE_ACTORS
353 };
354};
355
356
357/**
358\brief collection of set bits defined in PxSceneFlag.
359
360@see PxSceneFlag
361*/
362typedef PxFlags<PxSceneFlag::Enum,PxU32> PxSceneFlags;
363PX_FLAGS_OPERATORS(PxSceneFlag::Enum,PxU32)
364
365
366class PxSimulationEventCallback;
367class PxContactModifyCallback;
368class PxCCDContactModifyCallback;
369class PxSimulationFilterCallback;
370
371/**
372\brief Class used to retrieve limits(e.g. maximum number of bodies) for a scene. The limits
373are used as a hint to the size of the scene, not as a hard limit (i.e. it will be possible
374to create more objects than specified in the scene limits).
375
3760 indicates no limit. Using limits allows the SDK to preallocate various arrays, leading to
377less re-allocations and faster code at runtime.
378*/
379class PxSceneLimits
380{
381public:
382 PxU32 maxNbActors; //!< Expected maximum number of actors
383 PxU32 maxNbBodies; //!< Expected maximum number of dynamic rigid bodies
384 PxU32 maxNbStaticShapes; //!< Expected maximum number of static shapes
385 PxU32 maxNbDynamicShapes; //!< Expected maximum number of dynamic shapes
386 PxU32 maxNbAggregates; //!< Expected maximum number of aggregates
387 PxU32 maxNbConstraints; //!< Expected maximum number of constraint shaders
388 PxU32 maxNbRegions; //!< Expected maximum number of broad-phase regions
389 PxU32 maxNbBroadPhaseOverlaps; //!< Expected maximum number of broad-phase overlaps
390
391 /**
392 \brief constructor sets to default
393 */
394 PX_INLINE PxSceneLimits();
395
396 /**
397 \brief (re)sets the structure to the default
398 */
399 PX_INLINE void setToDefault();
400
401 /**
402 \brief Returns true if the descriptor is valid.
403 \return true if the current settings are valid.
404 */
405 PX_INLINE bool isValid() const;
406};
407
408PX_INLINE PxSceneLimits::PxSceneLimits() : //constructor sets to default
409 maxNbActors (0),
410 maxNbBodies (0),
411 maxNbStaticShapes (0),
412 maxNbDynamicShapes (0),
413 maxNbAggregates (0),
414 maxNbConstraints (0),
415 maxNbRegions (0),
416 maxNbBroadPhaseOverlaps (0)
417{
418}
419
420PX_INLINE void PxSceneLimits::setToDefault()
421{
422 *this = PxSceneLimits();
423}
424
425PX_INLINE bool PxSceneLimits::isValid() const
426{
427 if(maxNbRegions>256) // max number of regions is currently limited
428 return false;
429
430 return true;
431}
432
433//#if PX_SUPPORT_GPU_PHYSX
434/**
435\brief Sizes of pre-allocated buffers use for GPU dynamics
436*/
437
438struct PxgDynamicsMemoryConfig
439{
440 PxU32 constraintBufferCapacity; //!< Capacity of constraint buffer allocated in GPU global memory
441 PxU32 contactBufferCapacity; //!< Capacity of contact buffer allocated in GPU global memory
442 PxU32 tempBufferCapacity; //!< Capacity of temp buffer allocated in pinned host memory.
443 PxU32 contactStreamSize; //!< Size of contact stream buffer allocated in pinned host memory. This is double-buffered so total allocation size = 2* contactStreamCapacity * sizeof(PxContact).
444 PxU32 patchStreamSize; //!< Size of the contact patch stream buffer allocated in pinned host memory. This is double-buffered so total allocation size = 2 * patchStreamCapacity * sizeof(PxContactPatch).
445 PxU32 forceStreamCapacity; //!< Capacity of force buffer allocated in pinned host memory.
446 PxU32 heapCapacity; //!< Initial capacity of the GPU and pinned host memory heaps. Additional memory will be allocated if more memory is required.
447 PxU32 foundLostPairsCapacity; //!< Capacity of found and lost buffers allocated in GPU global memory. This is used for the found/lost pair reports in the BP.
448
449 PxgDynamicsMemoryConfig() :
450 constraintBufferCapacity(32 * 1024 * 1024),
451 contactBufferCapacity(24 * 1024 * 1024),
452 tempBufferCapacity(16 * 1024 * 1024),
453 contactStreamSize(1024 * 512),
454 patchStreamSize(1024 * 80),
455 forceStreamCapacity(1 * 1024 * 1024),
456 heapCapacity(64 * 1024 * 1024),
457 foundLostPairsCapacity(256 * 1024)
458 {
459 }
460};
461
462//#endif
463
464/**
465\brief Descriptor class for scenes. See #PxScene.
466
467This struct must be initialized with the same PxTolerancesScale values used to initialize PxPhysics.
468
469@see PxScene PxPhysics.createScene PxTolerancesScale
470*/
471class PxSceneDesc
472{
473public:
474
475 /**
476 \brief Gravity vector.
477
478 <b>Range:</b> force vector<br>
479 <b>Default:</b> Zero
480
481 @see PxScene.setGravity() PxScene.getGravity()
482
483 When setting gravity, you should probably also set bounce threshold.
484 */
485 PxVec3 gravity;
486
487 /**
488 \brief Possible notification callback.
489
490 <b>Default:</b> NULL
491
492 @see PxSimulationEventCallback PxScene.setSimulationEventCallback() PxScene.getSimulationEventCallback()
493 */
494 PxSimulationEventCallback* simulationEventCallback;
495
496 /**
497 \brief Possible asynchronous callback for contact modification.
498
499 <b>Default:</b> NULL
500
501 @see PxContactModifyCallback PxScene.setContactModifyCallback() PxScene.getContactModifyCallback()
502 */
503 PxContactModifyCallback* contactModifyCallback;
504
505 /**
506 \brief Possible asynchronous callback for contact modification.
507
508 <b>Default:</b> NULL
509
510 @see PxContactModifyCallback PxScene.setContactModifyCallback() PxScene.getContactModifyCallback()
511 */
512 PxCCDContactModifyCallback* ccdContactModifyCallback;
513
514 /**
515 \brief Shared global filter data which will get passed into the filter shader.
516
517 \note The provided data will get copied to internal buffers and this copy will be used for filtering calls.
518
519 <b>Default:</b> NULL
520
521 @see PxSimulationFilterShader PxScene::setFilterShaderData()
522 */
523 const void* filterShaderData;
524
525 /**
526 \brief Size (in bytes) of the shared global filter data #filterShaderData.
527
528 <b>Default:</b> 0
529
530 @see PxSimulationFilterShader filterShaderData
531 */
532 PxU32 filterShaderDataSize;
533
534 /**
535 \brief The custom filter shader to use for collision filtering.
536
537 \note This parameter is compulsory. If you don't want to define your own filter shader you can
538 use the default shader #PxDefaultSimulationFilterShader which can be found in the PhysX extensions
539 library.
540
541 @see PxSimulationFilterShader
542 */
543 PxSimulationFilterShader filterShader;
544
545 /**
546 \brief A custom collision filter callback which can be used to implement more complex filtering operations which need
547 access to the simulation state, for example.
548
549 <b>Default:</b> NULL
550
551 @see PxSimulationFilterCallback
552 */
553 PxSimulationFilterCallback* filterCallback;
554
555 /**
556 \brief Filtering mode for kinematic-kinematic pairs in the broadphase.
557
558 <b>Default:</b> PxPairFilteringMode::eDEFAULT
559
560 @see PxPairFilteringMode
561 */
562 PxPairFilteringMode::Enum kineKineFilteringMode;
563
564 /**
565 \brief Filtering mode for static-kinematic pairs in the broadphase.
566
567 <b>Default:</b> PxPairFilteringMode::eDEFAULT
568
569 @see PxPairFilteringMode
570 */
571 PxPairFilteringMode::Enum staticKineFilteringMode;
572
573 /**
574 \brief Selects the broad-phase algorithm to use.
575
576 <b>Default:</b> PxBroadPhaseType::eABP
577
578 @see PxBroadPhaseType
579 */
580 PxBroadPhaseType::Enum broadPhaseType;
581
582 /**
583 \brief Broad-phase callback
584
585 <b>Default:</b> NULL
586
587 @see PxBroadPhaseCallback
588 */
589 PxBroadPhaseCallback* broadPhaseCallback;
590
591 /**
592 \brief Expected scene limits.
593
594 @see PxSceneLimits
595 */
596 PxSceneLimits limits;
597
598 /**
599 \brief Selects the friction algorithm to use for simulation.
600
601 \note frictionType cannot be modified after the first call to any of PxScene::simulate, PxScene::solve and PxScene::collide
602
603 @see PxFrictionType
604 <b>Default:</b> PxFrictionType::ePATCH
605
606 @see PxScene::setFrictionType, PxScene::getFrictionType
607 */
608 PxFrictionType::Enum frictionType;
609
610 /**
611 \brief Selects the solver algorithm to use.
612
613 <b>Default:</b> PxSolverType::ePGS
614
615 @see PxSolverType
616 */
617 PxSolverType::Enum solverType;
618
619 /**
620 \brief A contact with a relative velocity below this will not bounce. A typical value for simulation.
621 stability is about 0.2 * gravity.
622
623 <b>Range:</b> [0, PX_MAX_F32)<br>
624 <b>Default:</b> 0.2 * PxTolerancesScale::speed
625
626 @see PxMaterial PxScene.setBounceThresholdVelocity() PxScene.getBounceThresholdVelocity()
627 */
628 PxReal bounceThresholdVelocity;
629
630 /**
631 \brief A threshold of contact separation distance used to decide if a contact point will experience friction forces.
632
633 \note If the separation distance of a contact point is greater than the threshold then the contact point will not experience friction forces.
634
635 \note If the aggregated contact offset of a pair of shapes is large it might be desirable to neglect friction
636 for contact points whose separation distance is sufficiently large that the shape surfaces are clearly separated.
637
638 \note This parameter can be used to tune the separation distance of contact points at which friction starts to have an effect.
639
640 <b>Range:</b> [0, PX_MAX_F32)<br>
641 <b>Default:</b> 0.04 * PxTolerancesScale::length
642 */
643 PxReal frictionOffsetThreshold;
644
645 /**
646 \brief A threshold for speculative CCD. Used to control whether bias, restitution or a combination of the two are used to resolve the contacts.
647
648 \note This only has any effect on contacting pairs where one of the bodies has PxRigidBodyFlag::eENABLE_SPECULATIVE_CCD raised.
649
650 <b>Range:</b> [0, PX_MAX_F32)<br>
651 <b>Default:</b> 0.04 * PxTolerancesScale::length
652 */
653
654 PxReal ccdMaxSeparation;
655
656 /**
657 \brief A slop value used to zero contact offsets from the body's COM on an axis if the offset along that axis is smaller than this threshold. Can be used to compensate
658 for small numerical errors in contact generation.
659
660 <b>Range:</b> [0, PX_MAX_F32)<br>
661 <b>Default:</b> 0.0
662 */
663
664 PxReal solverOffsetSlop;
665
666 /**
667 \brief Flags used to select scene options.
668
669 @see PxSceneFlag PxSceneFlags
670 */
671 PxSceneFlags flags;
672
673 /**
674 \brief The CPU task dispatcher for the scene.
675
676 See PxCpuDispatcher, PxScene::getCpuDispatcher
677 */
678 PxCpuDispatcher* cpuDispatcher;
679
680 /**
681 \brief The CUDA context manager for the scene.
682
683 <b>Platform specific:</b> Applies to PC GPU only.
684
685 See PxCudaContextManager, PxScene::getCudaContextManager
686 */
687 PxCudaContextManager* cudaContextManager;
688
689 /**
690 \brief Defines the structure used to store static objects.
691
692 \note Only PxPruningStructureType::eSTATIC_AABB_TREE and PxPruningStructureType::eDYNAMIC_AABB_TREE are allowed here.
693 */
694 PxPruningStructureType::Enum staticStructure;
695
696 /**
697 \brief Defines the structure used to store dynamic objects.
698 */
699 PxPruningStructureType::Enum dynamicStructure;
700
701 /**
702 \brief Hint for how much work should be done per simulation frame to rebuild the pruning structure.
703
704 This parameter gives a hint on the distribution of the workload for rebuilding the dynamic AABB tree
705 pruning structure #PxPruningStructureType::eDYNAMIC_AABB_TREE. It specifies the desired number of simulation frames
706 the rebuild process should take. Higher values will decrease the workload per frame but the pruning
707 structure will get more and more outdated the longer the rebuild takes (which can make
708 scene queries less efficient).
709
710 \note Only used for #PxPruningStructureType::eDYNAMIC_AABB_TREE pruning structure.
711
712 \note This parameter gives only a hint. The rebuild process might still take more or less time depending on the
713 number of objects involved.
714
715 <b>Range:</b> [4, PX_MAX_U32)<br>
716 <b>Default:</b> 100
717 */
718 PxU32 dynamicTreeRebuildRateHint;
719
720 /**
721 \brief Defines the scene query update mode.
722 <b>Default:</b> PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED
723 */
724 PxSceneQueryUpdateMode::Enum sceneQueryUpdateMode;
725
726 /**
727 \brief Will be copied to PxScene::userData.
728
729 <b>Default:</b> NULL
730 */
731 void* userData;
732
733 /**
734 \brief Defines the number of actors required to spawn a separate rigid body solver island task chain.
735
736 This parameter defines the minimum number of actors required to spawn a separate rigid body solver task chain. Setting a low value
737 will potentially cause more task chains to be generated. This may result in the overhead of spawning tasks can become a limiting performance factor.
738 Setting a high value will potentially cause fewer islands to be generated. This may reduce thread scaling (fewer task chains spawned) and may
739 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
740 maximum number of solver iterations requested by any body in the island.
741
742 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.
743
744 <b>Default:</b> 128
745
746 @see PxScene.setSolverBatchSize() PxScene.getSolverBatchSize()
747 */
748 PxU32 solverBatchSize;
749
750 /**
751 \brief Defines the number of articulations required to spawn a separate rigid body solver island task chain.
752
753 This parameter defines the minimum number of articulations required to spawn a separate rigid body solver task chain. Setting a low value
754 will potentially cause more task chains to be generated. This may result in the overhead of spawning tasks can become a limiting performance factor.
755 Setting a high value will potentially cause fewer islands to be generated. This may reduce thread scaling (fewer task chains spawned) and may
756 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
757 maximum number of solver iterations requested by any body in the island.
758
759 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.
760
761 <b>Default:</b> 128
762
763 @see PxScene.setSolverArticulationBatchSize() PxScene.getSolverArticulationBatchSize()
764 */
765 PxU32 solverArticulationBatchSize;
766
767 /**
768 \brief Setting to define the number of 16K blocks that will be initially reserved to store contact, friction, and contact cache data.
769 This is the number of 16K memory blocks that will be automatically allocated from the user allocator when the scene is instantiated. Further 16k
770 memory blocks may be allocated during the simulation up to maxNbContactDataBlocks.
771
772 \note This value cannot be larger than maxNbContactDataBlocks because that defines the maximum number of 16k blocks that can be allocated by the SDK.
773
774 <b>Default:</b> 0
775
776 <b>Range:</b> [0, PX_MAX_U32]<br>
777
778 @see PxPhysics::createScene PxScene::setNbContactDataBlocks
779 */
780 PxU32 nbContactDataBlocks;
781
782 /**
783 \brief Setting to define the maximum number of 16K blocks that can be allocated to store contact, friction, and contact cache data.
784 As the complexity of a scene increases, the SDK may require to allocate new 16k blocks in addition to the blocks it has already
785 allocated. This variable controls the maximum number of blocks that the SDK can allocate.
786
787 In the case that the scene is sufficiently complex that all the permitted 16K blocks are used, contacts will be dropped and
788 a warning passed to the error stream.
789
790 If a warning is reported to the error stream to indicate the number of 16K blocks is insufficient for the scene complexity
791 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,
792 (ii) to simplify the scene or (iii) to opt to not increase the memory requirements of physx and accept some dropped contacts.
793
794 <b>Default:</b> 65536
795
796 <b>Range:</b> [0, PX_MAX_U32]<br>
797
798 @see nbContactDataBlocks PxScene::setNbContactDataBlocks
799 */
800 PxU32 maxNbContactDataBlocks;
801
802 /**
803 \brief The maximum bias coefficient used in the constraint solver
804
805 When geometric errors are found in the constraint solver, either as a result of shapes penetrating
806 or joints becoming separated or violating limits, a bias is introduced in the solver position iterations
807 to correct these errors. This bias is proportional to 1/dt, meaning that the bias becomes increasingly
808 strong as the time-step passed to PxScene::simulate(...) becomes smaller. This coefficient allows the
809 application to restrict how large the bias coefficient is, to reduce how violent error corrections are.
810 This can improve simulation quality in cases where either variable time-steps or extremely small time-steps
811 are used.
812
813 <b>Default:</b> PX_MAX_F32
814
815 <b> Range</b> [0, PX_MAX_F32] <br>
816
817 */
818 PxReal maxBiasCoefficient;
819
820 /**
821 \brief Size of the contact report stream (in bytes).
822
823 The contact report stream buffer is used during the simulation to store all the contact reports.
824 If the size is not sufficient, the buffer will grow by a factor of two.
825 It is possible to disable the buffer growth by setting the flag PxSceneFlag::eDISABLE_CONTACT_REPORT_BUFFER_RESIZE.
826 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.
827
828 <b>Default:</b> 8192
829
830 <b>Range:</b> (0, PX_MAX_U32]<br>
831
832 */
833 PxU32 contactReportStreamBufferSize;
834
835 /**
836 \brief Maximum number of CCD passes
837
838 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.
839
840 \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.
841 \note This defines the maximum number of passes the CCD can perform. It may perform fewer if additional passes are not necessary.
842
843 <b>Default:</b> 1
844 <b>Range:</b> [1, PX_MAX_U32]<br>
845 */
846 PxU32 ccdMaxPasses;
847
848 /**
849 \brief CCD threshold
850
851 CCD performs sweeps against shapes if and only if the relative motion of the shapes is fast-enough that a collision would be missed
852 by the discrete contact generation. However, in some circumstances, e.g. when the environment is constructed from large convex shapes, this
853 approach may produce undesired simulation artefacts. This parameter defines the minimum relative motion that would be required to force CCD between shapes.
854 The smaller of this value and the sum of the thresholds calculated for the shapes involved will be used.
855
856 \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
857
858 <b>Default:</b> PX_MAX_F32
859 <b>Range:</b> [Eps, PX_MAX_F32]<br>
860 */
861
862 PxReal ccdThreshold;
863
864 /**
865 \brief The wake counter reset value
866
867 Calling wakeUp() on objects which support sleeping will set their wake counter value to the specified reset value.
868
869 <b>Range:</b> (0, PX_MAX_F32)<br>
870 <b>Default:</b> 0.4 (which corresponds to 20 frames for a time step of 0.02)
871
872 @see PxRigidDynamic::wakeUp() PxArticulationBase::wakeUp()
873 */
874 PxReal wakeCounterResetValue;
875
876 /**
877 \brief The bounds used to sanity check user-set positions of actors and articulation links
878
879 These bounds are used to check the position values of rigid actors inserted into the scene, and positions set for rigid actors
880 already within the scene.
881
882 <b>Range:</b> any valid PxBounds3 <br>
883 <b>Default:</b> (-PX_MAX_BOUNDS_EXTENTS, PX_MAX_BOUNDS_EXTENTS) on each axis
884 */
885 PxBounds3 sanityBounds;
886
887 /**
888 \brief The pre-allocations performed in the GPU dynamics pipeline.
889 */
890 PxgDynamicsMemoryConfig gpuDynamicsConfig;
891
892 /**
893 \brief Limitation for the partitions in the GPU dynamics pipeline.
894 This variable must be power of 2.
895 A value greater than 32 is currently not supported.
896 <b>Range:</b> (1, 32)<br>
897 */
898 PxU32 gpuMaxNumPartitions;
899
900 /**
901 \brief Defines which compute version the GPU dynamics should target. DO NOT MODIFY
902 */
903 PxU32 gpuComputeVersion;
904
905private:
906 /**
907 \cond
908 */
909 // For internal use only
910 PxTolerancesScale tolerancesScale;
911 /**
912 \endcond
913 */
914
915
916public:
917 /**
918 \brief constructor sets to default.
919
920 \param[in] scale scale values for the tolerances in the scene, these must be the same values passed into
921 PxCreatePhysics(). The affected tolerances are bounceThresholdVelocity and frictionOffsetThreshold.
922
923 @see PxCreatePhysics() PxTolerancesScale bounceThresholdVelocity frictionOffsetThreshold
924 */
925 PX_INLINE PxSceneDesc(const PxTolerancesScale& scale);
926
927 /**
928 \brief (re)sets the structure to the default.
929
930 \param[in] scale scale values for the tolerances in the scene, these must be the same values passed into
931 PxCreatePhysics(). The affected tolerances are bounceThresholdVelocity and frictionOffsetThreshold.
932
933 @see PxCreatePhysics() PxTolerancesScale bounceThresholdVelocity frictionOffsetThreshold
934 */
935 PX_INLINE void setToDefault(const PxTolerancesScale& scale);
936
937 /**
938 \brief Returns true if the descriptor is valid.
939 \return true if the current settings are valid.
940 */
941 PX_INLINE bool isValid() const;
942
943 /**
944 \cond
945 */
946 // For internal use only
947 PX_INLINE const PxTolerancesScale& getTolerancesScale() const { return tolerancesScale; }
948 /**
949 \endcond
950 */
951};
952
953PX_INLINE PxSceneDesc::PxSceneDesc(const PxTolerancesScale& scale):
954 gravity (PxVec3(0.0f)),
955 simulationEventCallback (NULL),
956 contactModifyCallback (NULL),
957 ccdContactModifyCallback (NULL),
958
959 filterShaderData (NULL),
960 filterShaderDataSize (0),
961 filterShader (NULL),
962 filterCallback (NULL),
963
964 kineKineFilteringMode (PxPairFilteringMode::eDEFAULT),
965 staticKineFilteringMode (PxPairFilteringMode::eDEFAULT),
966
967 broadPhaseType (PxBroadPhaseType::eABP),
968 broadPhaseCallback (NULL),
969
970 frictionType (PxFrictionType::ePATCH),
971 solverType (PxSolverType::ePGS),
972 bounceThresholdVelocity (0.2f * scale.speed),
973 frictionOffsetThreshold (0.04f * scale.length),
974 ccdMaxSeparation (0.04f * scale.length),
975 solverOffsetSlop (0.0f),
976
977 flags (PxSceneFlag::eENABLE_PCM),
978
979 cpuDispatcher (NULL),
980 cudaContextManager (NULL),
981
982 staticStructure (PxPruningStructureType::eDYNAMIC_AABB_TREE),
983 dynamicStructure (PxPruningStructureType::eDYNAMIC_AABB_TREE),
984 dynamicTreeRebuildRateHint (100),
985 sceneQueryUpdateMode (PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED),
986
987 userData (NULL),
988
989 solverBatchSize (128),
990 solverArticulationBatchSize (16),
991
992 nbContactDataBlocks (0),
993 maxNbContactDataBlocks (1<<16),
994 maxBiasCoefficient (PX_MAX_F32),
995 contactReportStreamBufferSize (8192),
996 ccdMaxPasses (1),
997 ccdThreshold (PX_MAX_F32),
998 wakeCounterResetValue (20.0f*0.02f),
999 sanityBounds (PxBounds3(PxVec3(-PX_MAX_BOUNDS_EXTENTS), PxVec3(PX_MAX_BOUNDS_EXTENTS))),
1000 gpuMaxNumPartitions (8),
1001 gpuComputeVersion (0),
1002 tolerancesScale (scale)
1003{
1004}
1005
1006PX_INLINE void PxSceneDesc::setToDefault(const PxTolerancesScale& scale)
1007{
1008 *this = PxSceneDesc(scale);
1009}
1010
1011PX_INLINE bool PxSceneDesc::isValid() const
1012{
1013 if(!filterShader)
1014 return false;
1015
1016 if( ((filterShaderDataSize == 0) && (filterShaderData != NULL)) ||
1017 ((filterShaderDataSize > 0) && (filterShaderData == NULL)) )
1018 return false;
1019
1020 if(!limits.isValid())
1021 return false;
1022
1023 if(staticStructure!=PxPruningStructureType::eSTATIC_AABB_TREE && staticStructure!=PxPruningStructureType::eDYNAMIC_AABB_TREE)
1024 return false;
1025
1026 if(dynamicTreeRebuildRateHint < 4)
1027 return false;
1028
1029 if(bounceThresholdVelocity < 0.0f)
1030 return false;
1031 if(frictionOffsetThreshold < 0.0f)
1032 return false;
1033 if(ccdMaxSeparation < 0.0f)
1034 return false;
1035 if (solverOffsetSlop < 0.f)
1036 return false;
1037
1038 if(ccdThreshold <= 0.f)
1039 return false;
1040
1041 if(!cpuDispatcher)
1042 return false;
1043
1044 if(!contactReportStreamBufferSize)
1045 return false;
1046
1047 if(maxNbContactDataBlocks < nbContactDataBlocks)
1048 return false;
1049
1050 if(wakeCounterResetValue <= 0.0f)
1051 return false;
1052
1053 //Adaptive force and stabilization are incompatible. You can only have one or the other
1054 if((flags & (PxSceneFlag::eADAPTIVE_FORCE | PxSceneFlag::eENABLE_STABILIZATION)) == (PxSceneFlag::eADAPTIVE_FORCE | PxSceneFlag::eENABLE_STABILIZATION))
1055 return false;
1056
1057 if(!sanityBounds.isValid())
1058 return false;
1059
1060#if PX_SUPPORT_GPU_PHYSX
1061 //gpuMaxNumPartitions must be power of 2
1062 if((gpuMaxNumPartitions&(gpuMaxNumPartitions - 1)) != 0)
1063 return false;
1064 if (gpuMaxNumPartitions > 32)
1065 return false;
1066#endif
1067
1068 return true;
1069}
1070
1071
1072#if !PX_DOXYGEN
1073} // namespace physx
1074#endif
1075
1076/** @} */
1077#endif
1078

source code of qtquick3dphysics/src/3rdparty/PhysX/include/PxSceneDesc.h