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_SCENE
32#define PX_PHYSICS_NX_SCENE
33/** \addtogroup physics
34@{
35*/
36
37#include "PxVisualizationParameter.h"
38#include "PxSceneDesc.h"
39#include "PxSimulationStatistics.h"
40#include "PxQueryReport.h"
41#include "PxQueryFiltering.h"
42#include "PxClient.h"
43#include "task/PxTask.h"
44
45#include "pvd/PxPvdSceneClient.h"
46
47#if !PX_DOXYGEN
48namespace physx
49{
50#endif
51
52class PxRigidStatic;
53class PxRigidDynamic;
54class PxConstraint;
55class PxMaterial;
56class PxSimulationEventCallback;
57class PxPhysics;
58class PxBatchQueryDesc;
59class PxBatchQuery;
60class PxAggregate;
61class PxRenderBuffer;
62
63class PxSphereGeometry;
64class PxBoxGeometry;
65class PxCapsuleGeometry;
66
67class PxPruningStructure;
68class PxBVHStructure;
69struct PxContactPairHeader;
70
71typedef PxU8 PxDominanceGroup;
72
73class PxPvdSceneClient;
74
75/**
76\brief Expresses the dominance relationship of a contact.
77For the time being only three settings are permitted:
78
79(1, 1), (0, 1), and (1, 0).
80
81@see getDominanceGroup() PxDominanceGroup PxScene::setDominanceGroupPair()
82*/
83struct PxDominanceGroupPair
84{
85 PxDominanceGroupPair(PxU8 a, PxU8 b)
86 : dominance0(a), dominance1(b) {}
87 PxU8 dominance0;
88 PxU8 dominance1;
89};
90
91
92/**
93\brief Identifies each type of actor for retrieving actors from a scene.
94
95\note #PxArticulationLink objects are not supported. Use the #PxArticulation object to retrieve all its links.
96
97@see PxScene::getActors(), PxScene::getNbActors()
98*/
99struct PxActorTypeFlag
100{
101 enum Enum
102 {
103 /**
104 \brief A static rigid body
105 @see PxRigidStatic
106 */
107 eRIGID_STATIC = (1 << 0),
108
109 /**
110 \brief A dynamic rigid body
111 @see PxRigidDynamic
112 */
113 eRIGID_DYNAMIC = (1 << 1)
114 };
115};
116
117/**
118\brief Collection of set bits defined in PxActorTypeFlag.
119
120@see PxActorTypeFlag
121*/
122typedef PxFlags<PxActorTypeFlag::Enum,PxU16> PxActorTypeFlags;
123PX_FLAGS_OPERATORS(PxActorTypeFlag::Enum,PxU16)
124
125/**
126\brief single hit cache for scene queries.
127
128If a cache object is supplied to a scene query, the cached actor/shape pair is checked for intersection first.
129\note Filters are not executed for the cached shape.
130\note If intersection is found, the hit is treated as blocking.
131\note Typically actor and shape from the last PxHitCallback.block query result is used as a cached actor/shape pair.
132\note Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
133\note Cache is only used if no touch buffer was provided, for single nearest blocking hit queries and queries using eANY_HIT flag.
134\note if non-zero touch buffer was provided, cache will be ignored
135
136\note It is the user's responsibility to ensure that the shape and actor are valid, so care must be taken
137when deleting shapes to invalidate cached references.
138
139The faceIndex field is an additional hint for a mesh or height field which is not currently used.
140
141@see PxScene.raycast
142*/
143struct PxQueryCache
144{
145 /**
146 \brief constructor sets to default
147 */
148 PX_INLINE PxQueryCache() : shape(NULL), actor(NULL), faceIndex(0xffffffff) {}
149
150 /**
151 \brief constructor to set properties
152 */
153 PX_INLINE PxQueryCache(PxShape* s, PxU32 findex) : shape(s), actor(NULL), faceIndex(findex) {}
154
155 PxShape* shape; //!< Shape to test for intersection first
156 PxRigidActor* actor; //!< Actor to which the shape belongs
157 PxU32 faceIndex; //!< Triangle index to test first - NOT CURRENTLY SUPPORTED
158};
159
160/**
161 \brief A scene is a collection of bodies and constraints which can interact.
162
163 The scene simulates the behavior of these objects over time. Several scenes may exist
164 at the same time, but each body or constraint is specific to a scene
165 -- they may not be shared.
166
167 @see PxSceneDesc PxPhysics.createScene() release()
168*/
169class PxScene
170{
171 protected:
172
173 /************************************************************************************************/
174
175 /** @name Basics
176 */
177 //@{
178
179 PxScene(): userData(0) {}
180 virtual ~PxScene() {}
181
182 public:
183
184 /**
185 \brief Deletes the scene.
186
187 Removes any actors and constraint shaders from this scene
188 (if the user hasn't already done so).
189
190 Be sure to not keep a reference to this object after calling release.
191 Avoid release calls while the scene is simulating (in between simulate() and fetchResults() calls).
192
193 @see PxPhysics.createScene()
194 */
195 virtual void release() = 0;
196
197 /**
198 \brief Sets a scene flag. You can only set one flag at a time.
199
200 \note Not all flags are mutable and changing some will result in an error. Please check #PxSceneFlag to see which flags can be changed.
201
202 @see PxSceneFlag
203 */
204 virtual void setFlag(PxSceneFlag::Enum flag, bool value) = 0;
205
206 /**
207 \brief Get the scene flags.
208
209 \return The scene flags. See #PxSceneFlag
210
211 @see PxSceneFlag
212 */
213 virtual PxSceneFlags getFlags() const = 0;
214
215
216 /**
217 \brief Set new scene limits.
218
219 \note Increase the maximum capacity of various data structures in the scene. The new capacities will be
220 at least as large as required to deal with the objects currently in the scene. Further, these values
221 are for preallocation and do not represent hard limits.
222
223 \param[in] limits Scene limits.
224 @see PxSceneLimits
225 */
226 virtual void setLimits(const PxSceneLimits& limits) = 0;
227
228 /**
229 \brief Get current scene limits.
230 \return Current scene limits.
231 @see PxSceneLimits
232 */
233 virtual PxSceneLimits getLimits() const = 0;
234
235
236 /**
237 \brief Call this method to retrieve the Physics SDK.
238
239 \return The physics SDK this scene is associated with.
240
241 @see PxPhysics
242 */
243 virtual PxPhysics& getPhysics() = 0;
244
245 /**
246 \brief Retrieves the scene's internal timestamp, increased each time a simulation step is completed.
247
248 \return scene timestamp
249 */
250 virtual PxU32 getTimestamp() const = 0;
251
252
253 //@}
254 /************************************************************************************************/
255
256 /** @name Add/Remove Contained Objects
257 */
258 //@{
259 /**
260 \brief Adds an articulation to this scene.
261
262 \note If the articulation is already assigned to a scene (see #PxArticulation::getScene), the call is ignored and an error is issued.
263
264 \param[in] articulation Articulation to add to scene. See #PxArticulation
265
266 @see PxArticulation
267 */
268 virtual void addArticulation(PxArticulationBase& articulation) = 0;
269
270 /**
271 \brief Removes an articulation from this scene.
272
273 \note If the articulation is not part of this scene (see #PxArticulation::getScene), the call is ignored and an error is issued.
274
275 \note If the articulation is in an aggregate it will be removed from the aggregate.
276
277 \param[in] articulation Articulation to remove from scene. See #PxArticulation
278 \param[in] wakeOnLostTouch Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulation and PxRigidActor types.
279
280 @see PxArticulation, PxAggregate
281 */
282 virtual void removeArticulation(PxArticulationBase& articulation, bool wakeOnLostTouch = true) = 0;
283
284
285 //@}
286 /************************************************************************************************/
287
288
289 /**
290 \brief Adds an actor to this scene.
291
292 \note If the actor is already assigned to a scene (see #PxActor::getScene), the call is ignored and an error is issued.
293 \note If the actor has an invalid constraint, in checked builds the call is ignored and an error is issued.
294
295 \note You can not add individual articulation links (see #PxArticulationLink) to the scene. Use #addArticulation() instead.
296
297 \note If the actor is a PxRigidActor then each assigned PxConstraint object will get added to the scene automatically if
298 it connects to another actor that is part of the scene already.
299
300 \note When BVHStructure is provided the actor shapes are grouped together.
301 The scene query pruning structure inside PhysX SDK will store/update one
302 bound per actor. The scene queries against such an actor will query actor
303 bounds and then make a local space query against the provided BVH structure, which is in
304 actor's local space.
305
306 \param[in] actor Actor to add to scene.
307 \param[in] bvhStructure BVHStructure for actor shapes.
308
309 @see PxActor, PxConstraint::isValid(), PxBVHStructure
310 */
311 virtual void addActor(PxActor& actor, const PxBVHStructure* bvhStructure = NULL) = 0;
312
313 /**
314 \brief Adds actors to this scene.
315
316 \note If one of the actors is already assigned to a scene (see #PxActor::getScene), the call is ignored and an error is issued.
317
318 \note You can not add individual articulation links (see #PxArticulationLink) to the scene. Use #addArticulation() instead.
319
320 \note If an actor in the array contains an invalid constraint, in checked builds the call is ignored and an error is issued.
321 \note If an actor in the array is a PxRigidActor then each assigned PxConstraint object will get added to the scene automatically if
322 it connects to another actor that is part of the scene already.
323
324 \note this method is optimized for high performance, and does not support buffering. It may not be called during simulation.
325
326 \param[in] actors Array of actors to add to scene.
327 \param[in] nbActors Number of actors in the array.
328
329 @see PxActor, PxConstraint::isValid()
330 */
331 virtual void addActors(PxActor*const* actors, PxU32 nbActors) = 0;
332
333 /**
334 \brief Adds a pruning structure together with its actors to this scene.
335
336 \note If an actor in the pruning structure contains an invalid constraint, in checked builds the call is ignored and an error is issued.
337 \note For all actors in the pruning structure each assigned PxConstraint object will get added to the scene automatically if
338 it connects to another actor that is part of the scene already.
339
340 \note This method is optimized for high performance, and does not support buffering. It may not be called during simulation.
341
342 \note Merging a PxPruningStructure into an active scene query optimization AABB tree might unbalance the tree. A typical use case for
343 PxPruningStructure is a large world scenario where blocks of closely positioned actors get streamed in. The merge process finds the
344 best node in the active scene query optimization AABB tree and inserts the PxPruningStructure. Therefore using PxPruningStructure
345 for actors scattered throughout the world will result in an unbalanced tree.
346
347 \param[in] pruningStructure Pruning structure for a set of actors.
348
349 @see PxPhysics::createPruningStructure, PxPruningStructure
350 */
351 virtual void addActors(const PxPruningStructure& pruningStructure) = 0;
352
353 /**
354 \brief Removes an actor from this scene.
355
356 \note If the actor is not part of this scene (see #PxActor::getScene), the call is ignored and an error is issued.
357
358 \note You can not remove individual articulation links (see #PxArticulationLink) from the scene. Use #removeArticulation() instead.
359
360 \note If the actor is a PxRigidActor then all assigned PxConstraint objects will get removed from the scene automatically.
361
362 \note If the actor is in an aggregate it will be removed from the aggregate.
363
364 \param[in] actor Actor to remove from scene.
365 \param[in] wakeOnLostTouch Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulation and PxRigidActor types.
366
367 @see PxActor, PxAggregate
368 */
369 virtual void removeActor(PxActor& actor, bool wakeOnLostTouch = true) = 0;
370
371 /**
372 \brief Removes actors from this scene.
373
374 \note If some actor is not part of this scene (see #PxActor::getScene), the actor remove is ignored and an error is issued.
375
376 \note You can not remove individual articulation links (see #PxArticulationLink) from the scene. Use #removeArticulation() instead.
377
378 \note If the actor is a PxRigidActor then all assigned PxConstraint objects will get removed from the scene automatically.
379
380 \param[in] actors Array of actors to add to scene.
381 \param[in] nbActors Number of actors in the array.
382 \param[in] wakeOnLostTouch Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulation and PxRigidActor types.
383
384 @see PxActor
385 */
386 virtual void removeActors(PxActor*const* actors, PxU32 nbActors, bool wakeOnLostTouch = true) = 0;
387
388 /**
389 \brief Adds an aggregate to this scene.
390
391 \note If the aggregate is already assigned to a scene (see #PxAggregate::getScene), the call is ignored and an error is issued.
392 \note If the aggregate contains an actor with an invalid constraint, in checked builds the call is ignored and an error is issued.
393
394 \note If the aggregate already contains actors, those actors are added to the scene as well.
395
396 \param[in] aggregate Aggregate to add to scene.
397
398 @see PxAggregate, PxConstraint::isValid()
399 */
400 virtual void addAggregate(PxAggregate& aggregate) = 0;
401
402 /**
403 \brief Removes an aggregate from this scene.
404
405 \note If the aggregate is not part of this scene (see #PxAggregate::getScene), the call is ignored and an error is issued.
406
407 \note If the aggregate contains actors, those actors are removed from the scene as well.
408
409 \param[in] aggregate Aggregate to remove from scene.
410 \param[in] wakeOnLostTouch Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulation and PxRigidActor types.
411
412 @see PxAggregate
413 */
414 virtual void removeAggregate(PxAggregate& aggregate, bool wakeOnLostTouch = true) = 0;
415
416 /**
417 \brief Adds objects in the collection to this scene.
418
419 This function adds the following types of objects to this scene: PxActor, PxAggregate, PxArticulation.
420 This method is typically used after deserializing the collection in order to populate the scene with deserialized objects.
421
422 \note If the collection contains an actor with an invalid constraint, in checked builds the call is ignored and an error is issued.
423
424 \param[in] collection Objects to add to this scene. See #PxCollection
425
426 @see PxCollection, PxConstraint::isValid()
427 */
428 virtual void addCollection(const PxCollection& collection) = 0;
429 //@}
430 /************************************************************************************************/
431
432 /** @name Contained Object Retrieval
433 */
434 //@{
435
436 /**
437 \brief Retrieve the number of actors of certain types in the scene.
438
439 \param[in] types Combination of actor types.
440 \return the number of actors.
441
442 @see getActors()
443 */
444 virtual PxU32 getNbActors(PxActorTypeFlags types) const = 0;
445
446 /**
447 \brief Retrieve an array of all the actors of certain types in the scene.
448
449 \param[in] types Combination of actor types to retrieve.
450 \param[out] userBuffer The buffer to receive actor pointers.
451 \param[in] bufferSize Size of provided user buffer.
452 \param[in] startIndex Index of first actor pointer to be retrieved
453 \return Number of actors written to the buffer.
454
455 @see getNbActors()
456 */
457 virtual PxU32 getActors(PxActorTypeFlags types, PxActor** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
458
459 /**
460 \brief Queries the PxScene for a list of the PxActors whose transforms have been
461 updated during the previous simulation step
462
463 \note PxSceneFlag::eENABLE_ACTIVE_ACTORS must be set.
464
465 \note Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored and NULL will be returned.
466
467 \param[out] nbActorsOut The number of actors returned.
468
469 \return A pointer to the list of active PxActors generated during the last call to fetchResults().
470
471 @see PxActor
472 */
473 virtual PxActor** getActiveActors(PxU32& nbActorsOut) = 0;
474
475 /**
476 \brief Returns the number of articulations in the scene.
477
478 \return the number of articulations in this scene.
479
480 @see getArticulations()
481 */
482 virtual PxU32 getNbArticulations() const = 0;
483
484 /**
485 \brief Retrieve all the articulations in the scene.
486
487 \param[out] userBuffer The buffer to receive articulations pointers.
488 \param[in] bufferSize Size of provided user buffer.
489 \param[in] startIndex Index of first articulations pointer to be retrieved
490 \return Number of articulations written to the buffer.
491
492 @see getNbArticulations()
493 */
494 virtual PxU32 getArticulations(PxArticulationBase** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
495
496 /**
497 \brief Returns the number of constraint shaders in the scene.
498
499 \return the number of constraint shaders in this scene.
500
501 @see getConstraints()
502 */
503 virtual PxU32 getNbConstraints() const = 0;
504
505 /**
506 \brief Retrieve all the constraint shaders in the scene.
507
508 \param[out] userBuffer The buffer to receive constraint shader pointers.
509 \param[in] bufferSize Size of provided user buffer.
510 \param[in] startIndex Index of first constraint pointer to be retrieved
511 \return Number of constraint shaders written to the buffer.
512
513 @see getNbConstraints()
514 */
515 virtual PxU32 getConstraints(PxConstraint** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
516
517
518 /**
519 \brief Returns the number of aggregates in the scene.
520
521 \return the number of aggregates in this scene.
522
523 @see getAggregates()
524 */
525 virtual PxU32 getNbAggregates() const = 0;
526
527 /**
528 \brief Retrieve all the aggregates in the scene.
529
530 \param[out] userBuffer The buffer to receive aggregates pointers.
531 \param[in] bufferSize Size of provided user buffer.
532 \param[in] startIndex Index of first aggregate pointer to be retrieved
533 \return Number of aggregates written to the buffer.
534
535 @see getNbAggregates()
536 */
537 virtual PxU32 getAggregates(PxAggregate** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
538
539 //@}
540 /************************************************************************************************/
541
542 /** @name Dominance
543 */
544 //@{
545
546 /**
547 \brief Specifies the dominance behavior of contacts between two actors with two certain dominance groups.
548
549 It is possible to assign each actor to a dominance groups using #PxActor::setDominanceGroup().
550
551 With dominance groups one can have all contacts created between actors act in one direction only. This is useful, for example, if you
552 want an object to push debris out of its way and be unaffected,while still responding physically to forces and collisions
553 with non-debris objects.
554
555 Whenever a contact between two actors (a0, a1) needs to be solved, the groups (g0, g1) of both
556 actors are retrieved. Then the PxDominanceGroupPair setting for this group pair is retrieved with getDominanceGroupPair(g0, g1).
557
558 In the contact, PxDominanceGroupPair::dominance0 becomes the dominance setting for a0, and
559 PxDominanceGroupPair::dominance1 becomes the dominance setting for a1. A dominanceN setting of 1.0f, the default,
560 will permit aN to be pushed or pulled by a(1-N) through the contact. A dominanceN setting of 0.0f, will however
561 prevent aN to be pushed by a(1-N) via the contact. Thus, a PxDominanceGroupPair of (1.0f, 0.0f) makes
562 the interaction one-way.
563
564
565 The matrix sampled by getDominanceGroupPair(g1, g2) is initialised by default such that:
566
567 if g1 == g2, then (1.0f, 1.0f) is returned
568 if g1 < g2, then (0.0f, 1.0f) is returned
569 if g1 > g2, then (1.0f, 0.0f) is returned
570
571 In other words, we permit actors in higher groups to be pushed around by actors in lower groups by default.
572
573 These settings should cover most applications, and in fact not overriding these settings may likely result in higher performance.
574
575 It is not possible to make the matrix asymetric, or to change the diagonal. In other words:
576
577 * it is not possible to change (g1, g2) if (g1==g2)
578 * if you set
579
580 (g1, g2) to X, then (g2, g1) will implicitly and automatically be set to ~X, where:
581
582 ~(1.0f, 1.0f) is (1.0f, 1.0f)
583 ~(0.0f, 1.0f) is (1.0f, 0.0f)
584 ~(1.0f, 0.0f) is (0.0f, 1.0f)
585
586 These two restrictions are to make sure that contacts between two actors will always evaluate to the same dominance
587 setting, regardless of the order of the actors.
588
589 Dominance settings are currently specified as floats 0.0f or 1.0f because in the future we may permit arbitrary
590 fractional settings to express 'partly-one-way' interactions.
591
592 <b>Sleeping:</b> Does <b>NOT</b> wake actors up automatically.
593
594 @see getDominanceGroupPair() PxDominanceGroup PxDominanceGroupPair PxActor::setDominanceGroup() PxActor::getDominanceGroup()
595 */
596 virtual void setDominanceGroupPair(
597 PxDominanceGroup group1, PxDominanceGroup group2, const PxDominanceGroupPair& dominance) = 0;
598
599 /**
600 \brief Samples the dominance matrix.
601
602 @see setDominanceGroupPair() PxDominanceGroup PxDominanceGroupPair PxActor::setDominanceGroup() PxActor::getDominanceGroup()
603 */
604 virtual PxDominanceGroupPair getDominanceGroupPair(PxDominanceGroup group1, PxDominanceGroup group2) const = 0;
605
606 //@}
607 /************************************************************************************************/
608
609 /** @name Dispatcher
610 */
611 //@{
612
613 /**
614 \brief Return the cpu dispatcher that was set in PxSceneDesc::cpuDispatcher when creating the scene with PxPhysics::createScene
615
616 @see PxSceneDesc::cpuDispatcher, PxPhysics::createScene
617 */
618 virtual PxCpuDispatcher* getCpuDispatcher() const = 0;
619
620 /**
621 \brief Return the CUDA context manager that was set in PxSceneDesc::cudaContextManager when creating the scene with PxPhysics::createScene
622
623 <b>Platform specific:</b> Applies to PC GPU only.
624
625 @see PxSceneDesc::cudaContextManager, PxPhysics::createScene
626 */
627 virtual PxCudaContextManager* getCudaContextManager() const = 0;
628
629 //@}
630 /************************************************************************************************/
631 /** @name Multiclient
632 */
633 //@{
634 /**
635 \brief Reserves a new client ID.
636
637 PX_DEFAULT_CLIENT is always available as the default clientID.
638 Additional clients are returned by this function. Clients cannot be released once created.
639 An error is reported when more than a supported number of clients (currently 128) are created.
640
641 @see PxClientID
642 */
643 virtual PxClientID createClient() = 0;
644
645 //@}
646
647 /************************************************************************************************/
648
649 /** @name Callbacks
650 */
651 //@{
652
653 /**
654 \brief Sets a user notify object which receives special simulation events when they occur.
655
656 \note Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.
657
658 \param[in] callback User notification callback. See #PxSimulationEventCallback.
659
660 @see PxSimulationEventCallback getSimulationEventCallback
661 */
662 virtual void setSimulationEventCallback(PxSimulationEventCallback* callback) = 0;
663
664 /**
665 \brief Retrieves the simulationEventCallback pointer set with setSimulationEventCallback().
666
667 \return The current user notify pointer. See #PxSimulationEventCallback.
668
669 @see PxSimulationEventCallback setSimulationEventCallback()
670 */
671 virtual PxSimulationEventCallback* getSimulationEventCallback() const = 0;
672
673 /**
674 \brief Sets a user callback object, which receives callbacks on all contacts generated for specified actors.
675
676 \note Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.
677
678 \param[in] callback Asynchronous user contact modification callback. See #PxContactModifyCallback.
679 */
680 virtual void setContactModifyCallback(PxContactModifyCallback* callback) = 0;
681
682 /**
683 \brief Sets a user callback object, which receives callbacks on all CCD contacts generated for specified actors.
684
685 \note Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.
686
687 \param[in] callback Asynchronous user contact modification callback. See #PxCCDContactModifyCallback.
688 */
689 virtual void setCCDContactModifyCallback(PxCCDContactModifyCallback* callback) = 0;
690
691 /**
692 \brief Retrieves the PxContactModifyCallback pointer set with setContactModifyCallback().
693
694 \return The current user contact modify callback pointer. See #PxContactModifyCallback.
695
696 @see PxContactModifyCallback setContactModifyCallback()
697 */
698 virtual PxContactModifyCallback* getContactModifyCallback() const = 0;
699
700 /**
701 \brief Retrieves the PxCCDContactModifyCallback pointer set with setContactModifyCallback().
702
703 \return The current user contact modify callback pointer. See #PxContactModifyCallback.
704
705 @see PxContactModifyCallback setContactModifyCallback()
706 */
707 virtual PxCCDContactModifyCallback* getCCDContactModifyCallback() const = 0;
708
709 /**
710 \brief Sets a broad-phase user callback object.
711
712 \note Do not set the callback while the simulation is running. Calls to this method while the simulation is running will be ignored.
713
714 \param[in] callback Asynchronous broad-phase callback. See #PxBroadPhaseCallback.
715 */
716 virtual void setBroadPhaseCallback(PxBroadPhaseCallback* callback) = 0;
717
718 /**
719 \brief Retrieves the PxBroadPhaseCallback pointer set with setBroadPhaseCallback().
720
721 \return The current broad-phase callback pointer. See #PxBroadPhaseCallback.
722
723 @see PxBroadPhaseCallback setBroadPhaseCallback()
724 */
725 virtual PxBroadPhaseCallback* getBroadPhaseCallback() const = 0;
726
727 //@}
728 /************************************************************************************************/
729
730 /** @name Collision Filtering
731 */
732 //@{
733
734 /**
735 \brief Sets the shared global filter data which will get passed into the filter shader.
736
737 \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.
738 If the filter output for existing pairs does change nonetheless then such a change will not take effect until the pair gets refiltered.
739 resetFiltering() can be used to explicitly refilter the pairs of specific objects.
740
741 \note The provided data will get copied to internal buffers and this copy will be used for filtering calls.
742
743 \note Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.
744
745 \param[in] data The shared global filter shader data.
746 \param[in] dataSize Size of the shared global filter shader data (in bytes).
747
748 @see getFilterShaderData() PxSceneDesc.filterShaderData PxSimulationFilterShader
749 */
750 virtual void setFilterShaderData(const void* data, PxU32 dataSize) = 0;
751
752 /**
753 \brief Gets the shared global filter data in use for this scene.
754
755 \note The reference points to a copy of the original filter data specified in #PxSceneDesc.filterShaderData or provided by #setFilterShaderData().
756
757 \return Shared filter data for filter shader.
758
759 @see getFilterShaderDataSize() setFilterShaderData() PxSceneDesc.filterShaderData PxSimulationFilterShader
760 */
761 virtual const void* getFilterShaderData() const = 0;
762
763 /**
764 \brief Gets the size of the shared global filter data (#PxSceneDesc.filterShaderData)
765
766 \return Size of shared filter data [bytes].
767
768 @see getFilterShaderData() PxSceneDesc.filterShaderDataSize PxSimulationFilterShader
769 */
770 virtual PxU32 getFilterShaderDataSize() const = 0;
771
772 /**
773 \brief Gets the custom collision filter shader in use for this scene.
774
775 \return Filter shader class that defines the collision pair filtering.
776
777 @see PxSceneDesc.filterShader PxSimulationFilterShader
778 */
779 virtual PxSimulationFilterShader getFilterShader() const = 0;
780
781 /**
782 \brief Gets the custom collision filter callback in use for this scene.
783
784 \return Filter callback class that defines the collision pair filtering.
785
786 @see PxSceneDesc.filterCallback PxSimulationFilterCallback
787 */
788 virtual PxSimulationFilterCallback* getFilterCallback() const = 0;
789
790 /**
791 \brief Marks the object to reset interactions and re-run collision filters in the next simulation step.
792
793 This call forces the object to remove all existing collision interactions, to search anew for existing contact
794 pairs and to run the collision filters again for found collision pairs.
795
796 \note The operation is supported for PxRigidActor objects only.
797
798 \note All persistent state of existing interactions will be lost and can not be retrieved even if the same collison pair
799 is found again in the next step. This will mean, for example, that you will not get notified about persistent contact
800 for such an interaction (see #PxPairFlag::eNOTIFY_TOUCH_PERSISTS), the contact pair will be interpreted as newly found instead.
801
802 \note Lost touch contact reports will be sent for every collision pair which includes this shape, if they have
803 been requested through #PxPairFlag::eNOTIFY_TOUCH_LOST or #PxPairFlag::eNOTIFY_THRESHOLD_FORCE_LOST.
804
805 \note This is an expensive operation, don't use it if you don't have to.
806
807 \note Can be used to retrieve collision pairs that were killed by the collision filters (see #PxFilterFlag::eKILL)
808
809 \note It is invalid to use this method if the actor has not been added to a scene already.
810
811 \note It is invalid to use this method if PxActorFlag::eDISABLE_SIMULATION is set.
812
813 <b>Sleeping:</b> Does wake up the actor.
814
815 \param[in] actor The actor for which to re-evaluate interactions.
816
817 @see PxSimulationFilterShader PxSimulationFilterCallback
818 */
819 virtual void resetFiltering(PxActor& actor) = 0;
820
821 /**
822 \brief Marks the object to reset interactions and re-run collision filters for specified shapes in the next simulation step.
823
824 This is a specialization of the resetFiltering(PxActor& actor) method and allows to reset interactions for specific shapes of
825 a PxRigidActor.
826
827 <b>Sleeping:</b> Does wake up the actor.
828
829 \param[in] actor The actor for which to re-evaluate interactions.
830 \param[in] shapes The shapes for which to re-evaluate interactions.
831 \param[in] shapeCount Number of shapes in the list.
832
833 @see PxSimulationFilterShader PxSimulationFilterCallback
834 */
835 virtual void resetFiltering(PxRigidActor& actor, PxShape*const* shapes, PxU32 shapeCount) = 0;
836
837 /**
838 \brief Gets the pair filtering mode for kinematic-kinematic pairs.
839
840 \return Filtering mode for kinematic-kinematic pairs.
841
842 @see PxPairFilteringMode PxSceneDesc
843 */
844 virtual PxPairFilteringMode::Enum getKinematicKinematicFilteringMode() const = 0;
845
846 /**
847 \brief Gets the pair filtering mode for static-kinematic pairs.
848
849 \return Filtering mode for static-kinematic pairs.
850
851 @see PxPairFilteringMode PxSceneDesc
852 */
853 virtual PxPairFilteringMode::Enum getStaticKinematicFilteringMode() const = 0;
854
855 //@}
856 /************************************************************************************************/
857
858 /** @name Simulation
859 */
860 //@{
861 /**
862 \brief Advances the simulation by an elapsedTime time.
863
864 \note Large elapsedTime values can lead to instabilities. In such cases elapsedTime
865 should be subdivided into smaller time intervals and simulate() should be called
866 multiple times for each interval.
867
868 Calls to simulate() should pair with calls to fetchResults():
869 Each fetchResults() invocation corresponds to exactly one simulate()
870 invocation; calling simulate() twice without an intervening fetchResults()
871 or fetchResults() twice without an intervening simulate() causes an error
872 condition.
873
874 scene->simulate();
875 ...do some processing until physics is computed...
876 scene->fetchResults();
877 ...now results of run may be retrieved.
878
879
880 \param[in] elapsedTime Amount of time to advance simulation by. The parameter has to be larger than 0, else the resulting behavior will be undefined. <b>Range:</b> (0, PX_MAX_F32)
881 \param[in] completionTask if non-NULL, this task will have its refcount incremented in simulate(), then
882 decremented when the scene is ready to have fetchResults called. So the task will not run until the
883 application also calls removeReference().
884 \param[in] scratchMemBlock a memory region for physx to use for temporary data during simulation. This block may be reused by the application
885 after fetchResults returns. Must be aligned on a 16-byte boundary
886 \param[in] scratchMemBlockSize the size of the scratch memory block. Must be a multiple of 16K.
887 \param[in] controlSimulation if true, the scene controls its PxTaskManager simulation state. Leave
888 true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.
889
890 @see fetchResults() checkResults()
891 */
892 virtual void simulate(PxReal elapsedTime, physx::PxBaseTask* completionTask = NULL,
893 void* scratchMemBlock = 0, PxU32 scratchMemBlockSize = 0, bool controlSimulation = true) = 0;
894
895
896 /**
897 \brief Performs dynamics phase of the simulation pipeline.
898
899 \note Calls to advance() should follow calls to fetchCollision(). An error message will be issued if this sequence is not followed.
900
901 \param[in] completionTask if non-NULL, this task will have its refcount incremented in advance(), then
902 decremented when the scene is ready to have fetchResults called. So the task will not run until the
903 application also calls removeReference().
904
905 */
906 virtual void advance(physx::PxBaseTask* completionTask = 0) = 0;
907
908 /**
909 \brief Performs collision detection for the scene over elapsedTime
910
911 \note Calls to collide() should be the first method called to simulate a frame.
912
913
914 \param[in] elapsedTime Amount of time to advance simulation by. The parameter has to be larger than 0, else the resulting behavior will be undefined. <b>Range:</b> (0, PX_MAX_F32)
915 \param[in] completionTask if non-NULL, this task will have its refcount incremented in collide(), then
916 decremented when the scene is ready to have fetchResults called. So the task will not run until the
917 application also calls removeReference().
918 \param[in] scratchMemBlock a memory region for physx to use for temporary data during simulation. This block may be reused by the application
919 after fetchResults returns. Must be aligned on a 16-byte boundary
920 \param[in] scratchMemBlockSize the size of the scratch memory block. Must be a multiple of 16K.
921 \param[in] controlSimulation if true, the scene controls its PxTaskManager simulation state. Leave
922 true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.
923
924 */
925 virtual void collide(PxReal elapsedTime, physx::PxBaseTask* completionTask = 0, void* scratchMemBlock = 0,
926 PxU32 scratchMemBlockSize = 0, bool controlSimulation = true) = 0;
927
928 /**
929 \brief This checks to see if the simulation run has completed.
930
931 This does not cause the data available for reading to be updated with the results of the simulation, it is simply a status check.
932 The bool will allow it to either return immediately or block waiting for the condition to be met so that it can return true
933
934 \param[in] block When set to true will block until the condition is met.
935 \return True if the results are available.
936
937 @see simulate() fetchResults()
938 */
939 virtual bool checkResults(bool block = false) = 0;
940
941 /**
942 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
943 message.
944
945 \param[in] block When set to true will block until the condition is met, which is collision must finish running.
946 */
947
948 virtual bool fetchCollision(bool block = false) = 0;
949
950 /**
951 This is the big brother to checkResults() it basically does the following:
952
953 \code
954 if ( checkResults(block) )
955 {
956 fire appropriate callbacks
957 swap buffers
958 return true
959 }
960 else
961 return false
962
963 \endcode
964
965 \param[in] block When set to true will block until results are available.
966 \param[out] errorState Used to retrieve hardware error codes. A non zero value indicates an error.
967 \return True if the results have been fetched.
968
969 @see simulate() checkResults()
970 */
971 virtual bool fetchResults(bool block = false, PxU32* errorState = 0) = 0;
972
973
974 /**
975 This call performs the first section of fetchResults (callbacks fired before swapBuffers), and returns a pointer to a
976 to the contact streams output by the simulation. It can be used to process contact pairs in parallel, which is often a limiting factor
977 for fetchResults() performance.
978
979 After calling this function and processing the contact streams, call fetchResultsFinish(). Note that writes to the simulation are not
980 permitted between the start of fetchResultsStart() and the end of fetchResultsFinish().
981
982 \param[in] block When set to true will block until results are available.
983 \param[out] contactPairs an array of pointers to contact pair headers
984 \param[out] nbContactPairs the number of contact pairs
985 \return True if the results have been fetched.
986
987 @see simulate() checkResults() fetchResults() fetchResultsFinish()
988 */
989 virtual bool fetchResultsStart(const PxContactPairHeader*& contactPairs, PxU32& nbContactPairs, bool block = false) = 0;
990
991
992 /**
993 This call processes all event callbacks in parallel. It takes a continuation task, which will be executed once all callbacks have been processed.
994
995 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
996 fetchResultsStart(...) and fetchResultsFinish(...)
997
998 \param[in] continuation The task that will be executed once all callbacks have been processed.
999 */
1000 virtual void processCallbacks(physx::PxBaseTask* continuation) = 0;
1001
1002
1003 /**
1004 This call performs the second section of fetchResults: the buffer swap and subsequent callbacks.
1005
1006 It must be called after fetchResultsStart() returns and contact reports have been processed.
1007
1008 Note that once fetchResultsFinish() has been called, the contact streams returned in fetchResultsStart() will be invalid.
1009
1010 \param[out] errorState Used to retrieve hardware error codes. A non zero value indicates an error.
1011
1012 @see simulate() checkResults() fetchResults() fetchResultsStart()
1013 */
1014 virtual void fetchResultsFinish(PxU32* errorState = 0) = 0;
1015
1016
1017 /**
1018 \brief Clear internal buffers and free memory.
1019
1020 This method can be used to clear buffers and free internal memory without having to destroy the scene. Can be useful if
1021 the physics data gets streamed in and a checkpoint with a clean state should be created.
1022
1023 \note It is not allowed to call this method while the simulation is running. The call will fail.
1024
1025 \param[in] 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).
1026 */
1027 virtual void flushSimulation(bool sendPendingReports = false) = 0;
1028
1029 /**
1030 \brief Sets a constant gravity for the entire scene.
1031
1032 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
1033
1034 \param[in] vec A new gravity vector(e.g. PxVec3(0.0f,-9.8f,0.0f) ) <b>Range:</b> force vector
1035
1036 @see PxSceneDesc.gravity getGravity()
1037 */
1038 virtual void setGravity(const PxVec3& vec) = 0;
1039
1040 /**
1041 \brief Retrieves the current gravity setting.
1042
1043 \return The current gravity for the scene.
1044
1045 @see setGravity() PxSceneDesc.gravity
1046 */
1047 virtual PxVec3 getGravity() const = 0;
1048
1049 /**
1050 \brief Set the bounce threshold velocity. Collision speeds below this threshold will not cause a bounce.
1051
1052 @see PxSceneDesc::bounceThresholdVelocity, getBounceThresholdVelocity
1053 */
1054 virtual void setBounceThresholdVelocity(const PxReal t) = 0;
1055
1056 /**
1057 \brief Return the bounce threshold velocity.
1058
1059 @see PxSceneDesc.bounceThresholdVelocity, setBounceThresholdVelocity
1060 */
1061 virtual PxReal getBounceThresholdVelocity() const = 0;
1062
1063
1064 /**
1065 \brief Sets the maximum number of CCD passes
1066
1067 \param[in] ccdMaxPasses Maximum number of CCD passes
1068
1069 @see PxSceneDesc.ccdMaxPasses getCCDMaxPasses()
1070
1071 */
1072 virtual void setCCDMaxPasses(PxU32 ccdMaxPasses) = 0;
1073
1074 /**
1075 \brief Gets the maximum number of CCD passes.
1076
1077 \return The maximum number of CCD passes.
1078
1079 @see PxSceneDesc::ccdMaxPasses setCCDMaxPasses()
1080
1081 */
1082 virtual PxU32 getCCDMaxPasses() const = 0;
1083
1084 /**
1085 \brief Return the value of frictionOffsetThreshold that was set in PxSceneDesc when creating the scene with PxPhysics::createScene
1086
1087 @see PxSceneDesc::frictionOffsetThreshold, PxPhysics::createScene
1088 */
1089 virtual PxReal getFrictionOffsetThreshold() const = 0;
1090
1091 /**
1092 \brief Set the friction model.
1093
1094 \deprecated The friction type cannot be changed after the first simulate call so this function is deprecated. Set the friction type at scene creation time in PxSceneDesc.
1095
1096 @see PxFrictionType, PxSceneDesc::frictionType
1097 */
1098 PX_DEPRECATED virtual void setFrictionType(PxFrictionType::Enum frictionType) = 0;
1099
1100 /**
1101 \brief Return the friction model.
1102 @see PxFrictionType, PxSceneDesc::frictionType
1103 */
1104 virtual PxFrictionType::Enum getFrictionType() const = 0;
1105
1106 //@}
1107 /************************************************************************************************/
1108
1109 /** @name Visualization and Statistics
1110 */
1111 //@{
1112 /**
1113 \brief Function that lets you set debug visualization parameters.
1114
1115 Returns false if the value passed is out of range for usage specified by the enum.
1116
1117 \param[in] param Parameter to set. See #PxVisualizationParameter
1118 \param[in] 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.
1119 \return False if the parameter is out of range.
1120
1121 @see getVisualizationParameter PxVisualizationParameter getRenderBuffer()
1122 */
1123 virtual bool setVisualizationParameter(PxVisualizationParameter::Enum param, PxReal value) = 0;
1124
1125 /**
1126 \brief Function that lets you query debug visualization parameters.
1127
1128 \param[in] paramEnum The Parameter to retrieve.
1129 \return The value of the parameter.
1130
1131 @see setVisualizationParameter PxVisualizationParameter
1132 */
1133 virtual PxReal getVisualizationParameter(PxVisualizationParameter::Enum paramEnum) const = 0;
1134
1135
1136 /**
1137 \brief 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.
1138
1139 \param[in] box the box to which the geometry will be culled. Empty box to disable the feature.
1140 @see setVisualizationParameter getVisualizationCullingBox getRenderBuffer()
1141 */
1142 virtual void setVisualizationCullingBox(const PxBounds3& box) = 0;
1143
1144 /**
1145 \brief Retrieves the visualization culling box.
1146
1147 \return the box to which the geometry will be culled.
1148 @see setVisualizationParameter setVisualizationCullingBox
1149 */
1150 virtual PxBounds3 getVisualizationCullingBox() const = 0;
1151
1152 /**
1153 \brief Retrieves the render buffer.
1154
1155 This will contain the results of any active visualization for this scene.
1156
1157 \note Do not use this method while the simulation is running. Calls to this method while result in undefined behaviour.
1158
1159 \return The render buffer.
1160
1161 @see PxRenderBuffer
1162 */
1163 virtual const PxRenderBuffer& getRenderBuffer() = 0;
1164
1165 /**
1166 \brief Call this method to retrieve statistics for the current simulation step.
1167
1168 \note Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.
1169
1170 \param[out] stats Used to retrieve statistics for the current simulation step.
1171
1172 @see PxSimulationStatistics
1173 */
1174 virtual void getSimulationStatistics(PxSimulationStatistics& stats) const = 0;
1175
1176
1177 //@}
1178 /************************************************************************************************/
1179
1180 /** @name Scene Query
1181 */
1182 //@{
1183
1184 /**
1185 \brief Return the value of PxSceneDesc::staticStructure that was set when creating the scene with PxPhysics::createScene
1186
1187 @see PxSceneDesc::staticStructure, PxPhysics::createScene
1188 */
1189 virtual PxPruningStructureType::Enum getStaticStructure() const = 0;
1190
1191 /**
1192 \brief Return the value of PxSceneDesc::dynamicStructure that was set when creating the scene with PxPhysics::createScene
1193
1194 @see PxSceneDesc::dynamicStructure, PxPhysics::createScene
1195 */
1196 virtual PxPruningStructureType::Enum getDynamicStructure() const = 0;
1197
1198 /**
1199 \brief Flushes any changes to the scene query representation.
1200
1201 This method updates the state of the scene query representation to match changes in the scene state.
1202
1203 By default, these changes are buffered until the next query is submitted. Calling this function will not change
1204 the results from scene queries, but can be used to ensure that a query will not perform update work in the course of
1205 its execution.
1206
1207 A thread performing updates will hold a write lock on the query structure, and thus stall other querying threads. In multithread
1208 scenarios it can be useful to explicitly schedule the period where this lock may be held for a significant period, so that
1209 subsequent queries issued from multiple threads will not block.
1210
1211 */
1212 virtual void flushQueryUpdates() = 0;
1213
1214 /**
1215 \brief Creates a BatchQuery object.
1216
1217 Scene queries like raycasts, overlap tests and sweeps are batched in this object and are then executed at once. See #PxBatchQuery.
1218
1219 \deprecated The batched query feature has been deprecated in PhysX version 3.4
1220
1221 \param[in] desc The descriptor of scene query. Scene Queries need to register a callback. See #PxBatchQueryDesc.
1222
1223 @see PxBatchQuery PxBatchQueryDesc
1224 */
1225 PX_DEPRECATED virtual PxBatchQuery* createBatchQuery(const PxBatchQueryDesc& desc) = 0;
1226
1227 /**
1228 \brief Sets the rebuild rate of the dynamic tree pruning structures.
1229
1230 \param[in] dynamicTreeRebuildRateHint Rebuild rate of the dynamic tree pruning structures.
1231
1232 @see PxSceneDesc.dynamicTreeRebuildRateHint getDynamicTreeRebuildRateHint() forceDynamicTreeRebuild()
1233 */
1234 virtual void setDynamicTreeRebuildRateHint(PxU32 dynamicTreeRebuildRateHint) = 0;
1235
1236 /**
1237 \brief Retrieves the rebuild rate of the dynamic tree pruning structures.
1238
1239 \return The rebuild rate of the dynamic tree pruning structures.
1240
1241 @see PxSceneDesc.dynamicTreeRebuildRateHint setDynamicTreeRebuildRateHint() forceDynamicTreeRebuild()
1242 */
1243 virtual PxU32 getDynamicTreeRebuildRateHint() const = 0;
1244
1245 /**
1246 \brief Forces dynamic trees to be immediately rebuilt.
1247
1248 \param[in] rebuildStaticStructure True to rebuild the dynamic tree containing static objects
1249 \param[in] rebuildDynamicStructure True to rebuild the dynamic tree containing dynamic objects
1250
1251 @see PxSceneDesc.dynamicTreeRebuildRateHint setDynamicTreeRebuildRateHint() getDynamicTreeRebuildRateHint()
1252 */
1253 virtual void forceDynamicTreeRebuild(bool rebuildStaticStructure, bool rebuildDynamicStructure) = 0;
1254
1255 /**
1256 \brief Sets scene query update mode
1257
1258 \param[in] updateMode Scene query update mode.
1259
1260 @see PxSceneQueryUpdateMode::Enum
1261 */
1262 virtual void setSceneQueryUpdateMode(PxSceneQueryUpdateMode::Enum updateMode) = 0;
1263
1264 /**
1265 \brief Gets scene query update mode
1266
1267 \return Current scene query update mode.
1268
1269 @see PxSceneQueryUpdateMode::Enum
1270 */
1271 virtual PxSceneQueryUpdateMode::Enum getSceneQueryUpdateMode() const = 0;
1272
1273 /**
1274 \brief Executes scene queries update tasks.
1275 This function will refit dirty shapes within the pruner and will execute a task to build a new AABB tree, which is
1276 build on a different thread. The new AABB tree is built based on the dynamic tree rebuild hint rate. Once
1277 the new tree is ready it will be commited in next fetchQueries call, which must be called after.
1278
1279 \note If PxSceneQueryUpdateMode::eBUILD_DISABLED_COMMIT_DISABLED is used, it is required to update the scene queries
1280 using this function.
1281
1282 \param[in] completionTask if non-NULL, this task will have its refcount incremented in sceneQueryUpdate(), then
1283 decremented when the scene is ready to have fetchQueries called. So the task will not run until the
1284 application also calls removeReference().
1285 \param[in] controlSimulation if true, the scene controls its PxTaskManager simulation state. Leave
1286 true unless the application is calling the PxTaskManager start/stopSimulation() methods itself.
1287
1288 @see PxSceneQueryUpdateMode::eBUILD_DISABLED_COMMIT_DISABLED
1289 */
1290 virtual void sceneQueriesUpdate(physx::PxBaseTask* completionTask = NULL, bool controlSimulation = true) = 0;
1291
1292 /**
1293 \brief This checks to see if the scene queries update has completed.
1294
1295 This does not cause the data available for reading to be updated with the results of the scene queries update, it is simply a status check.
1296 The bool will allow it to either return immediately or block waiting for the condition to be met so that it can return true
1297
1298 \param[in] block When set to true will block until the condition is met.
1299 \return True if the results are available.
1300
1301 @see sceneQueriesUpdate() fetchResults()
1302 */
1303 virtual bool checkQueries(bool block = false) = 0;
1304
1305 /**
1306 This method must be called after sceneQueriesUpdate. It will wait for the scene queries update to finish. If the user makes an illegal scene queries update call,
1307 the SDK will issue an error message.
1308
1309 If a new AABB tree build finished, then during fetchQueries the current tree within the pruning structure is swapped with the new tree.
1310
1311 \param[in] block When set to true will block until the condition is met, which is tree built task must finish running.
1312 */
1313
1314 virtual bool fetchQueries(bool block = false) = 0;
1315
1316 /**
1317 \brief Performs a raycast against objects in the scene, returns results in a PxRaycastBuffer object
1318 or via a custom user callback implementation inheriting from PxRaycastCallback.
1319
1320 \note Touching hits are not ordered.
1321 \note Shooting a ray from within an object leads to different results depending on the shape type. Please check the details in user guide article SceneQuery. User can ignore such objects by employing one of the provided filter mechanisms.
1322
1323 \param[in] origin Origin of the ray.
1324 \param[in] unitDir Normalized direction of the ray.
1325 \param[in] distance Length of the ray. Has to be in the [0, inf) range.
1326 \param[out] hitCall Raycast hit buffer or callback object used to report raycast hits.
1327 \param[in] hitFlags Specifies which properties per hit should be computed and returned via the hit callback.
1328 \param[in] filterData Filtering data passed to the filter shader. See #PxQueryFilterData #PxBatchQueryPreFilterShader, #PxBatchQueryPostFilterShader
1329 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
1330 \param[in] cache Cached hit shape (optional). Ray is tested against cached shape first. If no hit is found the ray gets queried against the scene.
1331 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
1332 Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
1333
1334 \return True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.
1335
1336 @see PxRaycastCallback PxRaycastBuffer PxQueryFilterData PxQueryFilterCallback PxQueryCache PxRaycastHit PxQueryFlag PxQueryFlag::eANY_HIT
1337 */
1338 virtual bool raycast(
1339 const PxVec3& origin, const PxVec3& unitDir, const PxReal distance,
1340 PxRaycastCallback& hitCall, PxHitFlags hitFlags = PxHitFlags(PxHitFlag::eDEFAULT),
1341 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL,
1342 const PxQueryCache* cache = NULL) const = 0;
1343
1344 /**
1345 \brief Performs a sweep test against objects in the scene, returns results in a PxSweepBuffer object
1346 or via a custom user callback implementation inheriting from PxSweepCallback.
1347
1348 \note Touching hits are not ordered.
1349 \note If a shape from the scene is already overlapping with the query shape in its starting position,
1350 the hit is returned unless eASSUME_NO_INITIAL_OVERLAP was specified.
1351
1352 \param[in] geometry Geometry of object to sweep (supported types are: box, sphere, capsule, convex).
1353 \param[in] pose Pose of the sweep object.
1354 \param[in] unitDir Normalized direction of the sweep.
1355 \param[in] distance Sweep distance. Needs to be in [0, inf) range and >0 if eASSUME_NO_INITIAL_OVERLAP was specified. Will be clamped to PX_MAX_SWEEP_DISTANCE.
1356 \param[out] hitCall Sweep hit buffer or callback object used to report sweep hits.
1357 \param[in] hitFlags Specifies which properties per hit should be computed and returned via the hit callback.
1358 \param[in] filterData Filtering data and simple logic.
1359 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
1360 \param[in] cache Cached hit shape (optional). Sweep is performed against cached shape first. If no hit is found the sweep gets queried against the scene.
1361 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
1362 Note: Using past touching hits as cache will produce incorrect behavior since the cached hit will always be treated as blocking.
1363 \param[in] inflation This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal.
1364 Note: ePRECISE_SWEEP doesn't support inflation. Therefore the sweep will be performed with zero inflation.
1365
1366 \return True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.
1367
1368
1369 @see PxSweepCallback PxSweepBuffer PxQueryFilterData PxQueryFilterCallback PxSweepHit PxQueryCache
1370 */
1371 virtual bool sweep(const PxGeometry& geometry, const PxTransform& pose, const PxVec3& unitDir, const PxReal distance,
1372 PxSweepCallback& hitCall, PxHitFlags hitFlags = PxHitFlags(PxHitFlag::eDEFAULT),
1373 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL,
1374 const PxQueryCache* cache = NULL, const PxReal inflation = 0.f) const = 0;
1375
1376
1377 /**
1378 \brief Performs an overlap test of a given geometry against objects in the scene, returns results in a PxOverlapBuffer object
1379 or via a custom user callback implementation inheriting from PxOverlapCallback.
1380
1381 \note Filtering: returning eBLOCK from user filter for overlap queries will cause a warning (see #PxQueryHitType).
1382
1383 \param[in] geometry Geometry of object to check for overlap (supported types are: box, sphere, capsule, convex).
1384 \param[in] pose Pose of the object.
1385 \param[out] hitCall Overlap hit buffer or callback object used to report overlap hits.
1386 \param[in] filterData Filtering data and simple logic. See #PxQueryFilterData #PxQueryFilterCallback
1387 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to overlap.
1388
1389 \return True if any touching or blocking hits were found or any hit was found in case PxQueryFlag::eANY_HIT was specified.
1390
1391 \note eBLOCK should not be returned from user filters for overlap(). Doing so will result in undefined behavior, and a warning will be issued.
1392 \note If the PxQueryFlag::eNO_BLOCK flag is set, the eBLOCK will instead be automatically converted to an eTOUCH and the warning suppressed.
1393
1394 @see PxOverlapCallback PxOverlapBuffer PxHitFlags PxQueryFilterData PxQueryFilterCallback
1395 */
1396 virtual bool overlap(const PxGeometry& geometry, const PxTransform& pose, PxOverlapCallback& hitCall,
1397 const PxQueryFilterData& filterData = PxQueryFilterData(), PxQueryFilterCallback* filterCall = NULL
1398 ) const = 0;
1399
1400
1401 /**
1402 \brief Retrieves the scene's internal scene query timestamp, increased each time a change to the
1403 static scene query structure is performed.
1404
1405 \return scene query static timestamp
1406 */
1407 virtual PxU32 getSceneQueryStaticTimestamp() const = 0;
1408 //@}
1409
1410 /************************************************************************************************/
1411 /** @name Broad-phase
1412 */
1413 //@{
1414
1415 /**
1416 \brief Returns broad-phase type.
1417
1418 \return Broad-phase type
1419 */
1420 virtual PxBroadPhaseType::Enum getBroadPhaseType() const = 0;
1421
1422 /**
1423 \brief Gets broad-phase caps.
1424
1425 \param[out] caps Broad-phase caps
1426 \return True if success
1427 */
1428 virtual bool getBroadPhaseCaps(PxBroadPhaseCaps& caps) const = 0;
1429
1430 /**
1431 \brief Returns number of regions currently registered in the broad-phase.
1432
1433 \return Number of regions
1434 */
1435 virtual PxU32 getNbBroadPhaseRegions() const = 0;
1436
1437 /**
1438 \brief Gets broad-phase regions.
1439
1440 \param[out] userBuffer Returned broad-phase regions
1441 \param[in] bufferSize Size of userBuffer
1442 \param[in] startIndex Index of first desired region, in [0 ; getNbRegions()[
1443 \return Number of written out regions
1444 */
1445 virtual PxU32 getBroadPhaseRegions(PxBroadPhaseRegionInfo* userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
1446
1447 /**
1448 \brief Adds a new broad-phase region.
1449
1450 Note that by default, objects already existing in the SDK that might touch this region will not be automatically
1451 added to the region. In other words the newly created region will be empty, and will only be populated with new
1452 objects when they are added to the simulation, or with already existing objects when they are updated.
1453
1454 It is nonetheless possible to override this default behavior and let the SDK populate the new region automatically
1455 with already existing objects overlapping the incoming region. This has a cost though, and it should only be used
1456 when the game can not guarantee that all objects within the new region will be added to the simulation after the
1457 region itself.
1458
1459 \param[in] region User-provided region data
1460 \param[in] populateRegion Automatically populate new region with already existing objects overlapping it
1461 \return Handle for newly created region, or 0xffffffff in case of failure.
1462 */
1463 virtual PxU32 addBroadPhaseRegion(const PxBroadPhaseRegion& region, bool populateRegion=false) = 0;
1464
1465 /**
1466 \brief Removes a new broad-phase region.
1467
1468 If the region still contains objects, and if those objects do not overlap any region any more, they are not
1469 automatically removed from the simulation. Instead, the PxBroadPhaseCallback::onObjectOutOfBounds notification
1470 is used for each object. Users are responsible for removing the objects from the simulation if this is the
1471 desired behavior.
1472
1473 If the handle is invalid, or if a valid handle is removed twice, an error message is sent to the error stream.
1474
1475 \param[in] handle Region's handle, as returned by PxScene::addBroadPhaseRegion.
1476 \return True if success
1477 */
1478 virtual bool removeBroadPhaseRegion(PxU32 handle) = 0;
1479
1480 //@}
1481
1482 /************************************************************************************************/
1483
1484 /** @name Threads and Memory
1485 */
1486 //@{
1487
1488 /**
1489 \brief Get the task manager associated with this scene
1490
1491 \return the task manager associated with the scene
1492 */
1493 virtual PxTaskManager* getTaskManager() const = 0;
1494
1495
1496 /**
1497 \brief Lock the scene for reading from the calling thread.
1498
1499 When the PxSceneFlag::eREQUIRE_RW_LOCK flag is enabled lockRead() must be
1500 called before any read calls are made on the scene.
1501
1502 Multiple threads may read at the same time, no threads may read while a thread is writing.
1503 If a call to lockRead() is made while another thread is holding a write lock
1504 then the calling thread will be blocked until the writing thread calls unlockWrite().
1505
1506 \note Lock upgrading is *not* supported, that means it is an error to
1507 call lockRead() followed by lockWrite().
1508
1509 \note Recursive locking is supported but each lockRead() call must be paired with an unlockRead().
1510
1511 \param file String representing the calling file, for debug purposes
1512 \param line The source file line number, for debug purposes
1513 */
1514 virtual void lockRead(const char* file=NULL, PxU32 line=0) = 0;
1515
1516 /**
1517 \brief Unlock the scene from reading.
1518
1519 \note Each unlockRead() must be paired with a lockRead() from the same thread.
1520 */
1521 virtual void unlockRead() = 0;
1522
1523 /**
1524 \brief Lock the scene for writing from this thread.
1525
1526 When the PxSceneFlag::eREQUIRE_RW_LOCK flag is enabled lockWrite() must be
1527 called before any write calls are made on the scene.
1528
1529 Only one thread may write at a time and no threads may read while a thread is writing.
1530 If a call to lockWrite() is made and there are other threads reading then the
1531 calling thread will be blocked until the readers complete.
1532
1533 Writers have priority. If a thread is blocked waiting to write then subsequent calls to
1534 lockRead() from other threads will be blocked until the writer completes.
1535
1536 \note If multiple threads are waiting to write then the thread that is first
1537 granted access depends on OS scheduling.
1538
1539 \note Recursive locking is supported but each lockWrite() call must be paired
1540 with an unlockWrite().
1541
1542 \note If a thread has already locked the scene for writing then it may call
1543 lockRead().
1544
1545 \param file String representing the calling file, for debug purposes
1546 \param line The source file line number, for debug purposes
1547 */
1548 virtual void lockWrite(const char* file=NULL, PxU32 line=0) = 0;
1549
1550 /**
1551 \brief Unlock the scene from writing.
1552
1553 \note Each unlockWrite() must be paired with a lockWrite() from the same thread.
1554 */
1555 virtual void unlockWrite() = 0;
1556
1557
1558 /**
1559 \brief set the cache blocks that can be used during simulate().
1560
1561 Each frame the simulation requires memory to store contact, friction, and contact cache data. This memory is used in blocks of 16K.
1562 Each frame the blocks used by the previous frame are freed, and may be retrieved by the application using PxScene::flushSimulation()
1563
1564 This call will force allocation of cache blocks if the numBlocks parameter is greater than the currently allocated number
1565 of blocks, and less than the max16KContactDataBlocks parameter specified at scene creation time.
1566
1567 \param[in] numBlocks The number of blocks to allocate.
1568
1569 @see PxSceneDesc.nbContactDataBlocks PxSceneDesc.maxNbContactDataBlocks flushSimulation() getNbContactDataBlocksUsed getMaxNbContactDataBlocksUsed
1570 */
1571 virtual void setNbContactDataBlocks(PxU32 numBlocks) = 0;
1572
1573
1574 /**
1575 \brief get the number of cache blocks currently used by the scene
1576
1577 This function may not be called while the scene is simulating
1578
1579 \return the number of cache blocks currently used by the scene
1580
1581 @see PxSceneDesc.nbContactDataBlocks PxSceneDesc.maxNbContactDataBlocks flushSimulation() setNbContactDataBlocks() getMaxNbContactDataBlocksUsed()
1582 */
1583 virtual PxU32 getNbContactDataBlocksUsed() const = 0;
1584
1585 /**
1586 \brief get the maximum number of cache blocks used by the scene
1587
1588 This function may not be called while the scene is simulating
1589
1590 \return the maximum number of cache blocks everused by the scene
1591
1592 @see PxSceneDesc.nbContactDataBlocks PxSceneDesc.maxNbContactDataBlocks flushSimulation() setNbContactDataBlocks() getNbContactDataBlocksUsed()
1593 */
1594 virtual PxU32 getMaxNbContactDataBlocksUsed() const = 0;
1595
1596
1597 /**
1598 \brief Return the value of PxSceneDesc::contactReportStreamBufferSize that was set when creating the scene with PxPhysics::createScene
1599
1600 @see PxSceneDesc::contactReportStreamBufferSize, PxPhysics::createScene
1601 */
1602 virtual PxU32 getContactReportStreamBufferSize() const = 0;
1603
1604
1605 /**
1606 \brief Sets the number of actors required to spawn a separate rigid body solver thread.
1607
1608 \param[in] solverBatchSize Number of actors required to spawn a separate rigid body solver thread.
1609
1610 @see PxSceneDesc.solverBatchSize getSolverBatchSize()
1611 */
1612 virtual void setSolverBatchSize(PxU32 solverBatchSize) = 0;
1613
1614 /**
1615 \brief Retrieves the number of actors required to spawn a separate rigid body solver thread.
1616
1617 \return Current number of actors required to spawn a separate rigid body solver thread.
1618
1619 @see PxSceneDesc.solverBatchSize setSolverBatchSize()
1620 */
1621 virtual PxU32 getSolverBatchSize() const = 0;
1622
1623 /**
1624 \brief Sets the number of articulations required to spawn a separate rigid body solver thread.
1625
1626 \param[in] solverBatchSize Number of articulations required to spawn a separate rigid body solver thread.
1627
1628 @see PxSceneDesc.solverBatchSize getSolverArticulationBatchSize()
1629 */
1630 virtual void setSolverArticulationBatchSize(PxU32 solverBatchSize) = 0;
1631
1632 /**
1633 \brief Retrieves the number of articulations required to spawn a separate rigid body solver thread.
1634
1635 \return Current number of articulations required to spawn a separate rigid body solver thread.
1636
1637 @see PxSceneDesc.solverBatchSize setSolverArticulationBatchSize()
1638 */
1639 virtual PxU32 getSolverArticulationBatchSize() const = 0;
1640
1641
1642 //@}
1643
1644 /**
1645 \brief Returns the wake counter reset value.
1646
1647 \return Wake counter reset value
1648
1649 @see PxSceneDesc.wakeCounterResetValue
1650 */
1651 virtual PxReal getWakeCounterResetValue() const = 0;
1652
1653 /**
1654 \brief Shift the scene origin by the specified vector.
1655
1656 The poses of all objects in the scene and the corresponding data structures will get adjusted to reflect the new origin location
1657 (the shift vector will get subtracted from all object positions).
1658
1659 \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.
1660
1661 \note Do not use this method while the simulation is running. Calls to this method while the simulation is running will be ignored.
1662
1663 \note Make sure to propagate the origin shift to other dependent modules (for example, the character controller module etc.).
1664
1665 \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.
1666
1667 \param[in] shift Translation vector to shift the origin by.
1668 */
1669 virtual void shiftOrigin(const PxVec3& shift) = 0;
1670
1671 /**
1672 \brief Returns the Pvd client associated with the scene.
1673 \return the client, NULL if no PVD supported.
1674 */
1675 virtual PxPvdSceneClient* getScenePvdClient() = 0;
1676
1677 void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
1678};
1679
1680#if !PX_DOXYGEN
1681} // namespace physx
1682#endif
1683
1684/** @} */
1685#endif
1686

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