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_SIMULATION_EVENT_CALLBACK
32#define PX_SIMULATION_EVENT_CALLBACK
33/** \addtogroup physics
34@{
35*/
36
37#include "foundation/PxVec3.h"
38#include "foundation/PxTransform.h"
39#include "foundation/PxMemory.h"
40#include "PxPhysXConfig.h"
41#include "PxFiltering.h"
42#include "PxContact.h"
43
44#if !PX_DOXYGEN
45namespace physx
46{
47#endif
48
49class PxShape;
50class PxActor;
51class PxRigidActor;
52class PxRigidBody;
53class PxConstraint;
54
55
56/**
57\brief Extra data item types for contact pairs.
58
59@see PxContactPairExtraDataItem.type
60*/
61struct PxContactPairExtraDataType
62{
63 enum Enum
64 {
65 ePRE_SOLVER_VELOCITY, //!< see #PxContactPairVelocity
66 ePOST_SOLVER_VELOCITY, //!< see #PxContactPairVelocity
67 eCONTACT_EVENT_POSE, //!< see #PxContactPairPose
68 eCONTACT_PAIR_INDEX //!< see #PxContactPairIndex
69 };
70};
71
72
73/**
74\brief Base class for items in the extra data stream of contact pairs
75
76@see PxContactPairHeader.extraDataStream
77*/
78struct PxContactPairExtraDataItem
79{
80public:
81 PX_FORCE_INLINE PxContactPairExtraDataItem() {}
82
83 /**
84 \brief The type of the extra data stream item
85 */
86 PxU8 type;
87};
88
89
90/**
91\brief Velocities of the contact pair rigid bodies
92
93This struct is shared by multiple types of extra data items. The #type field allows to distinguish between them:
94\li PxContactPairExtraDataType::ePRE_SOLVER_VELOCITY: see #PxPairFlag::ePRE_SOLVER_VELOCITY
95\li PxContactPairExtraDataType::ePOST_SOLVER_VELOCITY: see #PxPairFlag::ePOST_SOLVER_VELOCITY
96
97\note For static rigid bodies, the velocities will be set to zero.
98
99@see PxContactPairHeader.extraDataStream
100*/
101struct PxContactPairVelocity : public PxContactPairExtraDataItem
102{
103public:
104 PX_FORCE_INLINE PxContactPairVelocity() {}
105
106 /**
107 \brief The linear velocity of the rigid bodies
108 */
109 PxVec3 linearVelocity[2];
110
111 /**
112 \brief The angular velocity of the rigid bodies
113 */
114 PxVec3 angularVelocity[2];
115};
116
117
118/**
119\brief World space actor poses of the contact pair rigid bodies
120
121@see PxContactPairHeader.extraDataStream PxPairFlag::eCONTACT_EVENT_POSE
122*/
123struct PxContactPairPose : public PxContactPairExtraDataItem
124{
125public:
126 PX_FORCE_INLINE PxContactPairPose() {}
127
128 /**
129 \brief The world space pose of the rigid bodies
130 */
131 PxTransform globalPose[2];
132};
133
134
135/**
136\brief Marker for the beginning of a new item set in the extra data stream.
137
138If CCD with multiple passes is enabled, then a fast moving object might bounce on and off the same
139object multiple times. Also, different shapes of the same actor might gain and lose contact with an other
140object over multiple passes. This marker allows to seperate the extra data items for each collision case, as well as
141distinguish the shape pair reports of different CCD passes.
142
143Example:
144Let us assume that an actor a0 with shapes s0_0 and s0_1 hits another actor a1 with shape s1.
145First s0_0 will hit s1, then a0 will slightly rotate and s0_1 will hit s1 while s0_0 will lose contact with s1.
146Furthermore, let us say that contact event pose information is requested as extra data.
147The extra data stream will look like this:
148
149PxContactPairIndexA | PxContactPairPoseA | PxContactPairIndexB | PxContactPairPoseB
150
151The corresponding array of PxContactPair events (see #PxSimulationEventCallback.onContact()) will look like this:
152
153PxContactPair(touch_found: s0_0, s1) | PxContactPair(touch_lost: s0_0, s1) | PxContactPair(touch_found: s0_1, s1)
154
155The #index of PxContactPairIndexA will point to the first entry in the PxContactPair array, for PxContactPairIndexB,
156#index will point to the third entry.
157
158@see PxContactPairHeader.extraDataStream
159*/
160struct PxContactPairIndex : public PxContactPairExtraDataItem
161{
162public:
163 PX_FORCE_INLINE PxContactPairIndex() {}
164
165 /**
166 \brief The next item set in the extra data stream refers to the contact pairs starting at #index in the reported PxContactPair array.
167 */
168 PxU16 index;
169};
170
171
172/**
173\brief A class to iterate over a contact pair extra data stream.
174
175@see PxContactPairHeader.extraDataStream
176*/
177struct PxContactPairExtraDataIterator
178{
179 /**
180 \brief Constructor
181 \param[in] stream Pointer to the start of the stream.
182 \param[in] size Size of the stream in bytes.
183 */
184 PX_FORCE_INLINE PxContactPairExtraDataIterator(const PxU8* stream, PxU32 size)
185 : currPtr(stream), endPtr(stream + size), contactPairIndex(0)
186 {
187 clearDataPtrs();
188 }
189
190 /**
191 \brief Advances the iterator to next set of extra data items.
192
193 The contact pair extra data stream contains sets of items as requested by the corresponding #PxPairFlag flags
194 #PxPairFlag::ePRE_SOLVER_VELOCITY, #PxPairFlag::ePOST_SOLVER_VELOCITY, #PxPairFlag::eCONTACT_EVENT_POSE. A set can contain one
195 item of each plus the PxContactPairIndex item. This method parses the stream and points the iterator
196 member variables to the corresponding items of the current set, if they are available. If CCD is not enabled,
197 you should only get one set of items. If CCD with multiple passes is enabled, you might get more than one item
198 set.
199
200 \note Even though contact pair extra data is requested per shape pair, you will not get an item set per shape pair
201 but one per actor pair. If, for example, an actor has two shapes and both collide with another actor, then
202 there will only be one item set (since it applies to both shape pairs).
203
204 \return True if there was another set of extra data items in the stream, else false.
205
206 @see PxContactPairVelocity PxContactPairPose PxContactPairIndex
207 */
208 PX_INLINE bool nextItemSet()
209 {
210 clearDataPtrs();
211
212 bool foundEntry = false;
213 bool endOfItemSet = false;
214 while ((currPtr < endPtr) && (!endOfItemSet))
215 {
216 const PxContactPairExtraDataItem* edItem = reinterpret_cast<const PxContactPairExtraDataItem*>(currPtr);
217 PxU8 type = edItem->type;
218
219 switch(type)
220 {
221 case PxContactPairExtraDataType::ePRE_SOLVER_VELOCITY:
222 {
223 PX_ASSERT(!preSolverVelocity);
224 preSolverVelocity = static_cast<const PxContactPairVelocity*>(edItem);
225 currPtr += sizeof(PxContactPairVelocity);
226 foundEntry = true;
227 }
228 break;
229
230 case PxContactPairExtraDataType::ePOST_SOLVER_VELOCITY:
231 {
232 postSolverVelocity = static_cast<const PxContactPairVelocity*>(edItem);
233 currPtr += sizeof(PxContactPairVelocity);
234 foundEntry = true;
235 }
236 break;
237
238 case PxContactPairExtraDataType::eCONTACT_EVENT_POSE:
239 {
240 eventPose = static_cast<const PxContactPairPose*>(edItem);
241 currPtr += sizeof(PxContactPairPose);
242 foundEntry = true;
243 }
244 break;
245
246 case PxContactPairExtraDataType::eCONTACT_PAIR_INDEX:
247 {
248 if (!foundEntry)
249 {
250 contactPairIndex = static_cast<const PxContactPairIndex*>(edItem)->index;
251 currPtr += sizeof(PxContactPairIndex);
252 foundEntry = true;
253 }
254 else
255 endOfItemSet = true;
256 }
257 break;
258
259 default:
260 return foundEntry;
261 }
262 }
263
264 return foundEntry;
265 }
266
267private:
268 /**
269 \brief Internal helper
270 */
271 PX_FORCE_INLINE void clearDataPtrs()
272 {
273 preSolverVelocity = NULL;
274 postSolverVelocity = NULL;
275 eventPose = NULL;
276 }
277
278public:
279 /**
280 \brief Current pointer in the stream.
281 */
282 const PxU8* currPtr;
283
284 /**
285 \brief Pointer to the end of the stream.
286 */
287 const PxU8* endPtr;
288
289 /**
290 \brief Pointer to the current pre solver velocity item in the stream. NULL if there is none.
291
292 @see PxContactPairVelocity
293 */
294 const PxContactPairVelocity* preSolverVelocity;
295
296 /**
297 \brief Pointer to the current post solver velocity item in the stream. NULL if there is none.
298
299 @see PxContactPairVelocity
300 */
301 const PxContactPairVelocity* postSolverVelocity;
302
303 /**
304 \brief Pointer to the current contact event pose item in the stream. NULL if there is none.
305
306 @see PxContactPairPose
307 */
308 const PxContactPairPose* eventPose;
309
310 /**
311 \brief The contact pair index of the current item set in the stream.
312
313 @see PxContactPairIndex
314 */
315 PxU32 contactPairIndex;
316};
317
318
319/**
320\brief Collection of flags providing information on contact report pairs.
321
322@see PxContactPairHeader
323*/
324struct PxContactPairHeaderFlag
325{
326 enum Enum
327 {
328 eREMOVED_ACTOR_0 = (1<<0), //!< The actor with index 0 has been removed from the scene.
329 eREMOVED_ACTOR_1 = (1<<1) //!< The actor with index 1 has been removed from the scene.
330 };
331};
332
333/**
334\brief Bitfield that contains a set of raised flags defined in PxContactPairHeaderFlag.
335
336@see PxContactPairHeaderFlag
337*/
338typedef PxFlags<PxContactPairHeaderFlag::Enum, PxU16> PxContactPairHeaderFlags;
339PX_FLAGS_OPERATORS(PxContactPairHeaderFlag::Enum, PxU16)
340
341
342/**
343\brief An Instance of this class is passed to PxSimulationEventCallback.onContact().
344
345@see PxSimulationEventCallback.onContact()
346*/
347struct PxContactPairHeader
348{
349 public:
350 PX_INLINE PxContactPairHeader() {}
351
352 /**
353 \brief The two actors of the notification shape pairs.
354
355 \note The actor pointers might reference deleted actors. This will be the case if PxPairFlag::eNOTIFY_TOUCH_LOST
356 or PxPairFlag::eNOTIFY_THRESHOLD_FORCE_LOST events were requested for the pair and one of the involved actors
357 gets deleted or removed from the scene. Check the #flags member to see whether that is the case.
358 Do not dereference a pointer to a deleted actor. The pointer to a deleted actor is only provided
359 such that user data structures which might depend on the pointer value can be updated.
360
361 @see PxActor
362 */
363 PxRigidActor* actors[2];
364
365 /**
366 \brief Stream containing extra data as requested in the PxPairFlag flags of the simulation filter.
367
368 This pointer is only valid if any kind of extra data information has been requested for the contact report pair (see #PxPairFlag::ePOST_SOLVER_VELOCITY etc.),
369 else it will be NULL.
370
371 @see PxPairFlag
372 */
373 const PxU8* extraDataStream;
374
375 /**
376 \brief Size of the extra data stream [bytes]
377 */
378 PxU16 extraDataStreamSize;
379
380 /**
381 \brief Additional information on the contact report pair.
382
383 @see PxContactPairHeaderFlag
384 */
385 PxContactPairHeaderFlags flags;
386
387 /**
388 \brief pointer to the contact pairs
389 */
390 const struct PxContactPair* pairs;
391
392 /**
393 \brief number of contact pairs
394 */
395 PxU32 nbPairs;
396};
397
398
399/**
400\brief Collection of flags providing information on contact report pairs.
401
402@see PxContactPair
403*/
404struct PxContactPairFlag
405{
406 enum Enum
407 {
408 /**
409 \brief The shape with index 0 has been removed from the actor/scene.
410 */
411 eREMOVED_SHAPE_0 = (1<<0),
412
413 /**
414 \brief The shape with index 1 has been removed from the actor/scene.
415 */
416 eREMOVED_SHAPE_1 = (1<<1),
417
418 /**
419 \brief First actor pair contact.
420
421 The provided shape pair marks the first contact between the two actors, no other shape pair has been touching prior to the current simulation frame.
422
423 \note: This info is only available if #PxPairFlag::eNOTIFY_TOUCH_FOUND has been declared for the pair.
424 */
425 eACTOR_PAIR_HAS_FIRST_TOUCH = (1<<2),
426
427 /**
428 \brief All contact between the actor pair was lost.
429
430 All contact between the two actors has been lost, no shape pairs remain touching after the current simulation frame.
431 */
432 eACTOR_PAIR_LOST_TOUCH = (1<<3),
433
434 /**
435 \brief Internal flag, used by #PxContactPair.extractContacts()
436
437 The applied contact impulses are provided for every contact point.
438 This is the case if #PxPairFlag::eSOLVE_CONTACT has been set for the pair.
439 */
440 eINTERNAL_HAS_IMPULSES = (1<<4),
441
442 /**
443 \brief Internal flag, used by #PxContactPair.extractContacts()
444
445 The provided contact point information is flipped with regards to the shapes of the contact pair. This mainly concerns the order of the internal triangle indices.
446 */
447 eINTERNAL_CONTACTS_ARE_FLIPPED = (1<<5)
448 };
449};
450
451/**
452\brief Bitfield that contains a set of raised flags defined in PxContactPairFlag.
453
454@see PxContactPairFlag
455*/
456typedef PxFlags<PxContactPairFlag::Enum, PxU16> PxContactPairFlags;
457PX_FLAGS_OPERATORS(PxContactPairFlag::Enum, PxU16)
458
459
460/**
461\brief A contact point as used by contact notification
462*/
463struct PxContactPairPoint
464{
465 /**
466 \brief The position of the contact point between the shapes, in world space.
467 */
468 PxVec3 position;
469
470 /**
471 \brief The separation of the shapes at the contact point. A negative separation denotes a penetration.
472 */
473 PxReal separation;
474
475 /**
476 \brief The normal of the contacting surfaces at the contact point. The normal direction points from the second shape to the first shape.
477 */
478 PxVec3 normal;
479
480 /**
481 \brief The surface index of shape 0 at the contact point. This is used to identify the surface material.
482 */
483 PxU32 internalFaceIndex0;
484
485 /**
486 \brief The impulse applied at the contact point, in world space. Divide by the simulation time step to get a force value.
487 */
488 PxVec3 impulse;
489
490 /**
491 \brief The surface index of shape 1 at the contact point. This is used to identify the surface material.
492 */
493 PxU32 internalFaceIndex1;
494};
495
496
497/**
498\brief Contact report pair information.
499
500Instances of this class are passed to PxSimulationEventCallback.onContact(). If contact reports have been requested for a pair of shapes (see #PxPairFlag),
501then the corresponding contact information will be provided through this structure.
502
503@see PxSimulationEventCallback.onContact()
504*/
505struct PxContactPair
506{
507 public:
508 PX_INLINE PxContactPair() {}
509
510 /**
511 \brief The two shapes that make up the pair.
512
513 \note The shape pointers might reference deleted shapes. This will be the case if #PxPairFlag::eNOTIFY_TOUCH_LOST
514 or #PxPairFlag::eNOTIFY_THRESHOLD_FORCE_LOST events were requested for the pair and one of the involved shapes
515 gets deleted. Check the #flags member to see whether that is the case. Do not dereference a pointer to a
516 deleted shape. The pointer to a deleted shape is only provided such that user data structures which might
517 depend on the pointer value can be updated.
518
519 @see PxShape
520 */
521 PxShape* shapes[2];
522
523 /**
524 \brief Pointer to first patch header in contact stream containing contact patch data
525
526 This pointer is only valid if contact point information has been requested for the contact report pair (see #PxPairFlag::eNOTIFY_CONTACT_POINTS).
527 Use #extractContacts() as a reference for the data layout of the stream.
528 */
529 const PxU8* contactPatches;
530
531 /**
532 \brief Pointer to first contact point in contact stream containing contact data
533
534 This pointer is only valid if contact point information has been requested for the contact report pair (see #PxPairFlag::eNOTIFY_CONTACT_POINTS).
535 Use #extractContacts() as a reference for the data layout of the stream.
536 */
537 const PxU8* contactPoints;
538
539 /**
540 \brief Buffer containing applied impulse data.
541
542 This pointer is only valid if contact point information has been requested for the contact report pair (see #PxPairFlag::eNOTIFY_CONTACT_POINTS).
543 Use #extractContacts() as a reference for the data layout of the stream.
544 */
545 const PxReal* contactImpulses;
546
547 /**
548 \brief Size of the contact stream [bytes] including force buffer
549 */
550 PxU32 requiredBufferSize;
551
552 /**
553 \brief Number of contact points stored in the contact stream
554 */
555 PxU8 contactCount;
556
557 /**
558 \brief Number of contact patches stored in the contact stream
559 */
560
561 PxU8 patchCount;
562
563 /**
564 \brief Size of the contact stream [bytes] not including force buffer
565 */
566
567 PxU16 contactStreamSize;
568
569 /**
570 \brief Additional information on the contact report pair.
571
572 @see PxContactPairFlag
573 */
574 PxContactPairFlags flags;
575
576 /**
577 \brief Flags raised due to the contact.
578
579 The events field is a combination of:
580
581 <ul>
582 <li>PxPairFlag::eNOTIFY_TOUCH_FOUND,</li>
583 <li>PxPairFlag::eNOTIFY_TOUCH_PERSISTS,</li>
584 <li>PxPairFlag::eNOTIFY_TOUCH_LOST,</li>
585 <li>PxPairFlag::eNOTIFY_TOUCH_CCD,</li>
586 <li>PxPairFlag::eNOTIFY_THRESHOLD_FORCE_FOUND,</li>
587 <li>PxPairFlag::eNOTIFY_THRESHOLD_FORCE_PERSISTS,</li>
588 <li>PxPairFlag::eNOTIFY_THRESHOLD_FORCE_LOST</li>
589 </ul>
590
591 See the documentation of #PxPairFlag for an explanation of each.
592
593 \note eNOTIFY_TOUCH_CCD can get raised even if the pair did not request this event. However, in such a case it will only get
594 raised in combination with one of the other flags to point out that the other event occured during a CCD pass.
595
596 @see PxPairFlag
597 */
598 PxPairFlags events;
599
600 PxU32 internalData[2]; // For internal use only
601
602 /**
603 \brief Extracts the contact points from the stream and stores them in a convenient format.
604
605 \param[out] userBuffer Array of PxContactPairPoint structures to extract the contact points to. The number of contacts for a pair is defined by #contactCount
606 \param[in] bufferSize Number of PxContactPairPoint structures the provided buffer can store.
607 \return Number of contact points written to the buffer.
608
609 @see PxContactPairPoint
610 */
611 PX_INLINE PxU32 extractContacts(PxContactPairPoint* userBuffer, PxU32 bufferSize) const;
612
613 /**
614 \brief Helper method to clone the contact pair and copy the contact data stream into a user buffer.
615
616 The contact data stream is only accessible during the contact report callback. This helper function provides copy functionality
617 to buffer the contact stream information such that it can get accessed at a later stage.
618
619 \param[out] newPair The contact pair info will get copied to this instance. The contact data stream pointer of the copy will be redirected to the provided user buffer. Use NULL to skip the contact pair copy operation.
620 \param[out] bufferMemory Memory block to store the contact data stream to. At most #requiredBufferSize bytes will get written to the buffer.
621 */
622 PX_INLINE void bufferContacts(PxContactPair* newPair, PxU8* bufferMemory) const;
623
624 PX_INLINE const PxU32* getInternalFaceIndices() const;
625};
626
627
628PX_INLINE PxU32 PxContactPair::extractContacts(PxContactPairPoint* userBuffer, PxU32 bufferSize) const
629{
630 PxU32 nbContacts = 0;
631
632 if(contactCount && bufferSize)
633 {
634 PxContactStreamIterator iter(contactPatches, contactPoints, getInternalFaceIndices(), patchCount, contactCount);
635
636 const PxReal* impulses = contactImpulses;
637
638 const PxU32 flippedContacts = (flags & PxContactPairFlag::eINTERNAL_CONTACTS_ARE_FLIPPED);
639 const PxU32 hasImpulses = (flags & PxContactPairFlag::eINTERNAL_HAS_IMPULSES);
640
641 while(iter.hasNextPatch())
642 {
643 iter.nextPatch();
644 while(iter.hasNextContact())
645 {
646 iter.nextContact();
647 PxContactPairPoint& dst = userBuffer[nbContacts];
648 dst.position = iter.getContactPoint();
649 dst.separation = iter.getSeparation();
650 dst.normal = iter.getContactNormal();
651 if(!flippedContacts)
652 {
653 dst.internalFaceIndex0 = iter.getFaceIndex0();
654 dst.internalFaceIndex1 = iter.getFaceIndex1();
655 }
656 else
657 {
658 dst.internalFaceIndex0 = iter.getFaceIndex1();
659 dst.internalFaceIndex1 = iter.getFaceIndex0();
660 }
661
662 if(hasImpulses)
663 {
664 const PxReal impulse = impulses[nbContacts];
665 dst.impulse = dst.normal * impulse;
666 }
667 else
668 dst.impulse = PxVec3(0.0f);
669 ++nbContacts;
670 if(nbContacts == bufferSize)
671 return nbContacts;
672 }
673 }
674 }
675
676 return nbContacts;
677}
678
679
680PX_INLINE void PxContactPair::bufferContacts(PxContactPair* newPair, PxU8* bufferMemory) const
681{
682 PxU8* patches = bufferMemory;
683 PxU8* contacts = NULL;
684 if(patches)
685 {
686 contacts = bufferMemory + patchCount * sizeof(PxContactPatch);
687 PxMemCopy(dest: patches, src: contactPatches, count: sizeof(PxContactPatch)*patchCount);
688 PxMemCopy(dest: contacts, src: contactPoints, count: contactStreamSize - (sizeof(PxContactPatch)*patchCount));
689 }
690
691 if(contactImpulses)
692 {
693 PxMemCopy(dest: bufferMemory + ((contactStreamSize + 15) & (~15)), src: contactImpulses, count: sizeof(PxReal) * contactCount);
694 }
695
696 if (newPair)
697 {
698 *newPair = *this;
699 newPair->contactPatches = patches;
700 newPair->contactPoints = contacts;
701 }
702}
703
704
705PX_INLINE const PxU32* PxContactPair::getInternalFaceIndices() const
706{
707 return reinterpret_cast<const PxU32*>(contactImpulses + contactCount);
708}
709
710/**
711\brief Collection of flags providing information on trigger report pairs.
712
713@see PxTriggerPair
714*/
715struct PxTriggerPairFlag
716{
717 enum Enum
718 {
719 eREMOVED_SHAPE_TRIGGER = (1<<0), //!< The trigger shape has been removed from the actor/scene.
720 eREMOVED_SHAPE_OTHER = (1<<1), //!< The shape causing the trigger event has been removed from the actor/scene.
721 eNEXT_FREE = (1<<2) //!< For internal use only.
722 };
723};
724
725/**
726\brief Bitfield that contains a set of raised flags defined in PxTriggerPairFlag.
727
728@see PxTriggerPairFlag
729*/
730typedef PxFlags<PxTriggerPairFlag::Enum, PxU8> PxTriggerPairFlags;
731PX_FLAGS_OPERATORS(PxTriggerPairFlag::Enum, PxU8)
732
733
734/**
735\brief Descriptor for a trigger pair.
736
737An array of these structs gets passed to the PxSimulationEventCallback::onTrigger() report.
738
739\note The shape pointers might reference deleted shapes. This will be the case if #PxPairFlag::eNOTIFY_TOUCH_LOST
740 events were requested for the pair and one of the involved shapes gets deleted. Check the #flags member to see
741 whether that is the case. Do not dereference a pointer to a deleted shape. The pointer to a deleted shape is
742 only provided such that user data structures which might depend on the pointer value can be updated.
743
744@see PxSimulationEventCallback.onTrigger()
745*/
746struct PxTriggerPair
747{
748 PX_INLINE PxTriggerPair() {}
749
750 PxShape* triggerShape; //!< The shape that has been marked as a trigger.
751 PxRigidActor* triggerActor; //!< The actor to which triggerShape is attached
752 PxShape* otherShape; //!< The shape causing the trigger event. \deprecated (see #PxSimulationEventCallback::onTrigger()) If collision between trigger shapes is enabled, then this member might point to a trigger shape as well.
753 PxRigidActor* otherActor; //!< The actor to which otherShape is attached
754 PxPairFlag::Enum status; //!< Type of trigger event (eNOTIFY_TOUCH_FOUND or eNOTIFY_TOUCH_LOST). eNOTIFY_TOUCH_PERSISTS events are not supported.
755 PxTriggerPairFlags flags; //!< Additional information on the pair (see #PxTriggerPairFlag)
756};
757
758
759/**
760\brief Descriptor for a broken constraint.
761
762An array of these structs gets passed to the PxSimulationEventCallback::onConstraintBreak() report.
763
764@see PxConstraint PxSimulationEventCallback.onConstraintBreak()
765*/
766struct PxConstraintInfo
767{
768 PX_INLINE PxConstraintInfo() {}
769 PX_INLINE PxConstraintInfo(PxConstraint* c, void* extRef, PxU32 t) : constraint(c), externalReference(extRef), type(t) {}
770
771 PxConstraint* constraint; //!< The broken constraint.
772 void* externalReference; //!< The external object which owns the constraint (see #PxConstraintConnector::getExternalReference())
773 PxU32 type; //!< Unique type ID of the external object. Allows to cast the provided external reference to the appropriate type
774};
775
776
777/**
778\brief An interface class that the user can implement in order to receive simulation events.
779
780With the exception of onAdvance(), the events get sent during the call to either #PxScene::fetchResults() or
781#PxScene::flushSimulation() with sendPendingReports=true. onAdvance() gets called while the simulation
782is running (that is between PxScene::simulate(), onAdvance() and PxScene::fetchResults()).
783
784\note SDK state should not be modified from within the callbacks. In particular objects should not
785be created or destroyed. If state modification is needed then the changes should be stored to a buffer
786and performed after the simulation step.
787
788<b>Threading:</b> With the exception of onAdvance(), it is not necessary to make these callbacks thread safe as
789they will only be called in the context of the user thread.
790
791@see PxScene.setSimulationEventCallback() PxScene.getSimulationEventCallback()
792*/
793class PxSimulationEventCallback
794 {
795 public:
796 /**
797 \brief This is called when a breakable constraint breaks.
798
799 \note The user should not release the constraint shader inside this call!
800
801 \note No event will get reported if the constraint breaks but gets deleted while the time step is still being simulated.
802
803 \param[in] constraints - The constraints which have been broken.
804 \param[in] count - The number of constraints
805
806 @see PxConstraint PxConstraintDesc.linearBreakForce PxConstraintDesc.angularBreakForce
807 */
808 virtual void onConstraintBreak(PxConstraintInfo* constraints, PxU32 count) = 0;
809
810 /**
811 \brief This is called with the actors which have just been woken up.
812
813 \note Only supported by rigid bodies yet.
814 \note Only called on actors for which the PxActorFlag eSEND_SLEEP_NOTIFIES has been set.
815 \note Only the latest sleep state transition happening between fetchResults() of the previous frame and fetchResults() of the current frame
816 will get reported. For example, let us assume actor A is awake, then A->putToSleep() gets called, then later A->wakeUp() gets called.
817 At the next simulate/fetchResults() step only an onWake() event will get triggered because that was the last transition.
818 \note If an actor gets newly added to a scene with properties such that it is awake and the sleep state does not get changed by
819 the user or simulation, then an onWake() event will get sent at the next simulate/fetchResults() step.
820
821 \param[in] actors - The actors which just woke up.
822 \param[in] count - The number of actors
823
824 @see PxScene.setSimulationEventCallback() PxSceneDesc.simulationEventCallback PxActorFlag PxActor.setActorFlag()
825 */
826 virtual void onWake(PxActor** actors, PxU32 count) = 0;
827
828 /**
829 \brief This is called with the actors which have just been put to sleep.
830
831 \note Only supported by rigid bodies yet.
832 \note Only called on actors for which the PxActorFlag eSEND_SLEEP_NOTIFIES has been set.
833 \note Only the latest sleep state transition happening between fetchResults() of the previous frame and fetchResults() of the current frame
834 will get reported. For example, let us assume actor A is asleep, then A->wakeUp() gets called, then later A->putToSleep() gets called.
835 At the next simulate/fetchResults() step only an onSleep() event will get triggered because that was the last transition (assuming the simulation
836 does not wake the actor up).
837 \note If an actor gets newly added to a scene with properties such that it is asleep and the sleep state does not get changed by
838 the user or simulation, then an onSleep() event will get sent at the next simulate/fetchResults() step.
839
840 \param[in] actors - The actors which have just been put to sleep.
841 \param[in] count - The number of actors
842
843 @see PxScene.setSimulationEventCallback() PxSceneDesc.simulationEventCallback PxActorFlag PxActor.setActorFlag()
844 */
845 virtual void onSleep(PxActor** actors, PxU32 count) = 0;
846
847 /**
848 \brief This is called when certain contact events occur.
849
850 The method will be called for a pair of actors if one of the colliding shape pairs requested contact notification.
851 You request which events are reported using the filter shader/callback mechanism (see #PxSimulationFilterShader,
852 #PxSimulationFilterCallback, #PxPairFlag).
853
854 Do not keep references to the passed objects, as they will be
855 invalid after this function returns.
856
857 \param[in] pairHeader Information on the two actors whose shapes triggered a contact report.
858 \param[in] pairs The contact pairs of two actors for which contact reports have been requested. See #PxContactPair.
859 \param[in] nbPairs The number of provided contact pairs.
860
861 @see PxScene.setSimulationEventCallback() PxSceneDesc.simulationEventCallback PxContactPair PxPairFlag PxSimulationFilterShader PxSimulationFilterCallback
862 */
863 virtual void onContact(const PxContactPairHeader& pairHeader, const PxContactPair* pairs, PxU32 nbPairs) = 0;
864
865 /**
866 \brief This is called with the current trigger pair events.
867
868 Shapes which have been marked as triggers using PxShapeFlag::eTRIGGER_SHAPE will send events
869 according to the pair flag specification in the filter shader (see #PxPairFlag, #PxSimulationFilterShader).
870
871 \note Trigger shapes will no longer send notification events for interactions with other trigger shapes.
872
873 \param[in] pairs - The trigger pair events.
874 \param[in] count - The number of trigger pair events.
875
876 @see PxScene.setSimulationEventCallback() PxSceneDesc.simulationEventCallback PxPairFlag PxSimulationFilterShader PxShapeFlag PxShape.setFlag()
877 */
878 virtual void onTrigger(PxTriggerPair* pairs, PxU32 count) = 0;
879
880 /**
881 \brief Provides early access to the new pose of moving rigid bodies.
882
883 When this call occurs, rigid bodies having the #PxRigidBodyFlag::eENABLE_POSE_INTEGRATION_PREVIEW
884 flag set, were moved by the simulation and their new poses can be accessed through the provided buffers.
885
886 \note The provided buffers are valid and can be read until the next call to #PxScene::simulate() or #PxScene::collide().
887
888 \note Buffered user changes to the rigid body pose will not yet be reflected in the provided data. More important,
889 the provided data might contain bodies that have been deleted while the simulation was running. It is the user's
890 responsibility to detect and avoid dereferencing such bodies.
891
892 \note This callback gets triggered while the simulation is running. If the provided rigid body references are used to
893 read properties of the object, then the callback has to guarantee no other thread is writing to the same body at the same
894 time.
895
896 \note The code in this callback should be lightweight as it can block the simulation, that is, the
897 #PxScene::fetchResults() call.
898
899 \param[in] bodyBuffer The rigid bodies that moved and requested early pose reporting.
900 \param[in] poseBuffer The integrated rigid body poses of the bodies listed in bodyBuffer.
901 \param[in] count The number of entries in the provided buffers.
902
903 @see PxScene.setSimulationEventCallback() PxSceneDesc.simulationEventCallback PxRigidBodyFlag::eENABLE_POSE_INTEGRATION_PREVIEW
904 */
905 virtual void onAdvance(const PxRigidBody*const* bodyBuffer, const PxTransform* poseBuffer, const PxU32 count) = 0;
906
907 virtual ~PxSimulationEventCallback() {}
908 };
909
910#if !PX_DOXYGEN
911} // namespace physx
912#endif
913
914/** @} */
915#endif
916

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