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