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_PHYSICS_NX_FILTERING
15#define PX_PHYSICS_NX_FILTERING
16/** \addtogroup physics
17@{
18*/
19
20#include "PxPhysXConfig.h"
21#include "foundation/PxFlags.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28class PxActor;
29class PxShape;
30
31
32/**
33\brief Collection of flags describing the actions to take for a collision pair.
34
35@see PxPairFlags PxSimulationFilterShader.filter() PxSimulationFilterCallback
36*/
37struct PxPairFlag
38{
39 enum Enum
40 {
41 /**
42 \brief Process the contacts of this collision pair in the dynamics solver.
43
44 \note Only takes effect if the colliding actors are rigid bodies.
45 */
46 eSOLVE_CONTACT = (1<<0),
47
48 /**
49 \brief Call contact modification callback for this collision pair
50
51 \note Only takes effect if the colliding actors are rigid bodies.
52
53 @see PxContactModifyCallback
54 */
55 eMODIFY_CONTACTS = (1<<1),
56
57 /**
58 \brief Call contact report callback or trigger callback when this collision pair starts to be in contact.
59
60 If one of the two collision objects is a trigger shape (see #PxShapeFlag::eTRIGGER_SHAPE)
61 then the trigger callback will get called as soon as the other object enters the trigger volume.
62 If none of the two collision objects is a trigger shape then the contact report callback will get
63 called when the actors of this collision pair start to be in contact.
64
65 \note Only takes effect if the colliding actors are rigid bodies.
66
67 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
68
69 @see PxSimulationEventCallback.onContact() PxSimulationEventCallback.onTrigger()
70 */
71 eNOTIFY_TOUCH_FOUND = (1<<2),
72
73 /**
74 \brief Call contact report callback while this collision pair is in contact
75
76 If none of the two collision objects is a trigger shape then the contact report callback will get
77 called while the actors of this collision pair are in contact.
78
79 \note Triggers do not support this event. Persistent trigger contacts need to be tracked separately by observing eNOTIFY_TOUCH_FOUND/eNOTIFY_TOUCH_LOST events.
80
81 \note Only takes effect if the colliding actors are rigid bodies.
82
83 \note No report will get sent if the objects in contact are sleeping.
84
85 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
86
87 \note If this flag gets enabled while a pair is in touch already, there will be no eNOTIFY_TOUCH_PERSISTS events until the pair loses and regains touch.
88
89 @see PxSimulationEventCallback.onContact() PxSimulationEventCallback.onTrigger()
90 */
91 eNOTIFY_TOUCH_PERSISTS = (1<<3),
92
93 /**
94 \brief Call contact report callback or trigger callback when this collision pair stops to be in contact
95
96 If one of the two collision objects is a trigger shape (see #PxShapeFlag::eTRIGGER_SHAPE)
97 then the trigger callback will get called as soon as the other object leaves the trigger volume.
98 If none of the two collision objects is a trigger shape then the contact report callback will get
99 called when the actors of this collision pair stop to be in contact.
100
101 \note Only takes effect if the colliding actors are rigid bodies.
102
103 \note This event will also get triggered if one of the colliding objects gets deleted.
104
105 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
106
107 @see PxSimulationEventCallback.onContact() PxSimulationEventCallback.onTrigger()
108 */
109 eNOTIFY_TOUCH_LOST = (1<<4),
110
111 /**
112 \brief Call contact report callback when this collision pair is in contact during CCD passes.
113
114 If CCD with multiple passes is enabled, then a fast moving object might bounce on and off the same
115 object multiple times. Hence, the same pair might be in contact multiple times during a simulation step.
116 This flag will make sure that all the detected collision during CCD will get reported. For performance
117 reasons, the system can not always tell whether the contact pair lost touch in one of the previous CCD
118 passes and thus can also not always tell whether the contact is new or has persisted. eNOTIFY_TOUCH_CCD
119 just reports when the two collision objects were detected as being in contact during a CCD pass.
120
121 \note Only takes effect if the colliding actors are rigid bodies.
122
123 \note Trigger shapes are not supported.
124
125 \note Only takes effect if eDETECT_CCD_CONTACT is raised
126
127 @see PxSimulationEventCallback.onContact() PxSimulationEventCallback.onTrigger()
128 */
129 eNOTIFY_TOUCH_CCD = (1<<5),
130
131 /**
132 \brief Call contact report callback when the contact force between the actors of this collision pair exceeds one of the actor-defined force thresholds.
133
134 \note Only takes effect if the colliding actors are rigid bodies.
135
136 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
137
138 @see PxSimulationEventCallback.onContact()
139 */
140 eNOTIFY_THRESHOLD_FORCE_FOUND = (1<<6),
141
142 /**
143 \brief Call contact report callback when the contact force between the actors of this collision pair continues to exceed one of the actor-defined force thresholds.
144
145 \note Only takes effect if the colliding actors are rigid bodies.
146
147 \note If a pair gets re-filtered and this flag has previously been disabled, then the report will not get fired in the same frame even if the force threshold has been reached in the
148 previous one (unless #eNOTIFY_THRESHOLD_FORCE_FOUND has been set in the previous frame).
149
150 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
151
152 @see PxSimulationEventCallback.onContact()
153 */
154 eNOTIFY_THRESHOLD_FORCE_PERSISTS = (1<<7),
155
156 /**
157 \brief Call contact report callback when the contact force between the actors of this collision pair falls below one of the actor-defined force thresholds (includes the case where this collision pair stops being in contact).
158
159 \note Only takes effect if the colliding actors are rigid bodies.
160
161 \note If a pair gets re-filtered and this flag has previously been disabled, then the report will not get fired in the same frame even if the force threshold has been reached in the
162 previous one (unless #eNOTIFY_THRESHOLD_FORCE_FOUND or #eNOTIFY_THRESHOLD_FORCE_PERSISTS has been set in the previous frame).
163
164 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
165
166 @see PxSimulationEventCallback.onContact()
167 */
168 eNOTIFY_THRESHOLD_FORCE_LOST = (1<<8),
169
170 /**
171 \brief Provide contact points in contact reports for this collision pair.
172
173 \note Only takes effect if the colliding actors are rigid bodies and if used in combination with the flags eNOTIFY_TOUCH_... or eNOTIFY_THRESHOLD_FORCE_...
174
175 \note Only takes effect if eDETECT_DISCRETE_CONTACT or eDETECT_CCD_CONTACT is raised
176
177 @see PxSimulationEventCallback.onContact() PxContactPair PxContactPair.extractContacts()
178 */
179 eNOTIFY_CONTACT_POINTS = (1<<9),
180
181 /**
182 \brief This flag is used to indicate whether this pair generates discrete collision detection contacts.
183
184 \note Contacts are only responded to if eSOLVE_CONTACT is enabled.
185 */
186
187 eDETECT_DISCRETE_CONTACT = (1<<10),
188
189
190 /**
191 \brief This flag is used to indicate whether this pair generates CCD contacts.
192
193 \note The contacts will only be responded to if eSOLVE_CONTACT is enabled on this pair.
194 \note The scene must have PxSceneFlag::eENABLE_CCD enabled to use this feature.
195 \note Non-static bodies of the pair should have PxRigidBodyFlag::eENABLE_CCD specified for this feature to work correctly.
196 \note This flag is not supported with trigger shapes. However, CCD trigger events can be emulated using non-trigger shapes
197 and requesting eNOTIFY_TOUCH_FOUND and eNOTIFY_TOUCH_LOST and not raising eSOLVE_CONTACT on the pair.
198
199 @see PxRigidBodyFlag::eENABLE_CCD
200 @see PxSceneFlag::eENABLE_CCD
201 */
202
203 eDETECT_CCD_CONTACT = (1<<11),
204
205 /**
206 \brief Provide pre solver velocities in contact reports for this collision pair.
207
208 If the collision pair has contact reports enabled, the velocities of the rigid bodies before contacts have been solved
209 will be provided in the contact report callback unless the pair lost touch in which case no data will be provided.
210
211 \note Usually it is not necessary to request these velocities as they will be available by querying the velocity from the provided
212 PxRigidActor object directly. However, it might be the case that the velocity of a rigid body gets set while the simulation is running
213 in which case the PxRigidActor would return this new velocity in the contact report callback and not the velocity the simulation used.
214
215 @see PxSimulationEventCallback.onContact(), PxContactPairVelocity, PxContactPairHeader.extraDataStream
216 */
217 ePRE_SOLVER_VELOCITY = (1<<12),
218
219 /**
220 \brief Provide post solver velocities in contact reports for this collision pair.
221
222 If the collision pair has contact reports enabled, the velocities of the rigid bodies after contacts have been solved
223 will be provided in the contact report callback unless the pair lost touch in which case no data will be provided.
224
225 @see PxSimulationEventCallback.onContact(), PxContactPairVelocity, PxContactPairHeader.extraDataStream
226 */
227 ePOST_SOLVER_VELOCITY = (1<<13),
228
229 /**
230 \brief Provide rigid body poses in contact reports for this collision pair.
231
232 If the collision pair has contact reports enabled, the rigid body poses at the contact event will be provided
233 in the contact report callback unless the pair lost touch in which case no data will be provided.
234
235 \note Usually it is not necessary to request these poses as they will be available by querying the pose from the provided
236 PxRigidActor object directly. However, it might be the case that the pose of a rigid body gets set while the simulation is running
237 in which case the PxRigidActor would return this new pose in the contact report callback and not the pose the simulation used.
238 Another use case is related to CCD with multiple passes enabled, A fast moving object might bounce on and off the same
239 object multiple times. This flag can be used to request the rigid body poses at the time of impact for each such collision event.
240
241 @see PxSimulationEventCallback.onContact(), PxContactPairPose, PxContactPairHeader.extraDataStream
242 */
243 eCONTACT_EVENT_POSE = (1<<14),
244
245 eNEXT_FREE = (1<<15), //!< For internal use only.
246
247 /**
248 \deprecated
249 \brief Provides default flag for resolving contacts
250 */
251
252 PX_DEPRECATED eRESOLVE_CONTACTS = eSOLVE_CONTACT | eDETECT_DISCRETE_CONTACT,
253
254 /**
255 \deprecated
256 \brief Provided default flag to enable performing linear CCD sweeps and response for this collision pair.
257 */
258 PX_DEPRECATED eCCD_LINEAR = eSOLVE_CONTACT | eDETECT_CCD_CONTACT,
259
260 /**
261 \brief Provided default flag to do simple contact processing for this collision pair.
262 */
263 eCONTACT_DEFAULT = eSOLVE_CONTACT | eDETECT_DISCRETE_CONTACT,
264
265 /**
266 \brief Provided default flag to get commonly used trigger behavior for this collision pair.
267 */
268 eTRIGGER_DEFAULT = eNOTIFY_TOUCH_FOUND | eNOTIFY_TOUCH_LOST | eDETECT_DISCRETE_CONTACT
269 };
270};
271
272/**
273\brief Bitfield that contains a set of raised flags defined in PxPairFlag.
274
275@see PxPairFlag
276*/
277typedef PxFlags<PxPairFlag::Enum, PxU16> PxPairFlags;
278PX_FLAGS_OPERATORS(PxPairFlag::Enum, PxU16)
279
280
281
282/**
283\brief Collection of flags describing the filter actions to take for a collision pair.
284
285@see PxFilterFlags PxSimulationFilterShader PxSimulationFilterCallback
286*/
287struct PxFilterFlag
288{
289 enum Enum
290 {
291 /**
292 \brief Ignore the collision pair as long as the bounding volumes of the pair objects overlap.
293
294 Killed pairs will be ignored by the simulation and won't run through the filter again until one
295 of the following occurs:
296
297 \li The bounding volumes of the two objects overlap again (after being separated)
298 \li The user enforces a re-filtering (see #PxScene::resetFiltering())
299
300 @see PxScene::resetFiltering()
301 */
302 eKILL = (1<<0),
303
304 /**
305 \brief Ignore the collision pair as long as the bounding volumes of the pair objects overlap or until filtering relevant data changes for one of the collision objects.
306
307 Suppressed pairs will be ignored by the simulation and won't make another filter request until one
308 of the following occurs:
309
310 \li Same conditions as for killed pairs (see #eKILL)
311 \li The filter data or the filter object attributes change for one of the collision objects
312
313 \note For PxCloth objects, eSUPPRESS will be treated as eKILL.
314
315 @see PxFilterData PxFilterObjectAttributes
316 */
317 eSUPPRESS = (1<<1),
318
319 /**
320 \brief Invoke the filter callback (#PxSimulationFilterCallback::pairFound()) for this collision pair.
321
322 @see PxSimulationFilterCallback
323 */
324 eCALLBACK = (1<<2),
325
326 /**
327 \brief Track this collision pair with the filter callback mechanism.
328
329 When the bounding volumes of the collision pair lose contact, the filter callback #PxSimulationFilterCallback::pairLost()
330 will be invoked. Furthermore, the filter status of the collision pair can be adjusted through #PxSimulationFilterCallback::statusChange()
331 once per frame (until a pairLost() notification occurs).
332
333 @see PxSimulationFilterCallback
334 */
335 eNOTIFY = (1<<3) | eCALLBACK,
336
337 /**
338 \brief Provided default to get standard behavior:
339
340 The application configure the pair's collision properties once when bounding volume overlap is found and
341 doesn't get asked again about that pair until overlap status or filter properties changes, or re-filtering is requested.
342
343 No notification is provided when bounding volume overlap is lost
344
345 The pair will not be killed or suppressed, so collision detection will be processed
346 */
347
348 eDEFAULT = 0
349 };
350};
351
352/**
353\brief Bitfield that contains a set of raised flags defined in PxFilterFlag.
354
355@see PxFilterFlag
356*/
357typedef PxFlags<PxFilterFlag::Enum, PxU16> PxFilterFlags;
358PX_FLAGS_OPERATORS(PxFilterFlag::Enum, PxU16)
359
360
361/**
362\brief PxFilterData is user-definable data which gets passed into the collision filtering shader and/or callback.
363
364@see PxShape.setSimulationFilterData() PxShape.getSimulationFilterData() PxSimulationFilterShader PxSimulationFilterCallback
365*/
366struct PxFilterData
367{
368//= ATTENTION! =====================================================================================
369// Changing the data layout of this class breaks the binary serialization format. See comments for
370// PX_BINARY_SERIAL_VERSION. If a modification is required, please adjust the getBinaryMetaData
371// function. If the modification is made on a custom branch, please change PX_BINARY_SERIAL_VERSION
372// accordingly.
373//==================================================================================================
374
375 PX_INLINE PxFilterData(const PxEMPTY&)
376 {
377 }
378
379 /**
380 \brief Default constructor.
381 */
382 PX_INLINE PxFilterData()
383 {
384 word0 = word1 = word2 = word3 = 0;
385 }
386
387 /**
388 \brief Constructor to set filter data initially.
389 */
390 PX_INLINE PxFilterData(PxU32 w0, PxU32 w1, PxU32 w2, PxU32 w3) : word0(w0), word1(w1), word2(w2), word3(w3) {}
391
392 /**
393 \brief (re)sets the structure to the default.
394 */
395 PX_INLINE void setToDefault()
396 {
397 *this = PxFilterData();
398 }
399
400 PxU32 word0;
401 PxU32 word1;
402 PxU32 word2;
403 PxU32 word3;
404};
405
406
407/**
408\brief Identifies each type of filter object.
409
410@see PxGetFilterObjectType()
411*/
412struct PxFilterObjectType
413{
414 enum Enum
415 {
416 /**
417 \brief A static rigid body
418 @see PxRigidStatic
419 */
420 eRIGID_STATIC,
421
422 /**
423 \brief A dynamic rigid body
424 @see PxRigidDynamic
425 */
426 eRIGID_DYNAMIC,
427
428 /**
429 \brief A particle system
430 @see PxParticleSystem
431 */
432 ePARTICLE_SYSTEM,
433
434 /**
435 \brief A particle fluid
436 @see PxParticleFluid
437 */
438 ePARTICLE_FLUID,
439
440 /**
441 \brief An articulation
442 @see PxArticulation
443 */
444 eARTICULATION,
445
446 /**
447 \brief A cloth object
448 @see PxCloth
449 */
450 eCLOTH,
451
452 //brief internal use only!
453 eMAX_TYPE_COUNT = 16,
454
455 //brief internal use only!
456 eUNDEFINED = eMAX_TYPE_COUNT-1
457 };
458};
459
460
461// For internal use only
462struct PxFilterObjectFlag
463{
464 enum Enum
465 {
466 eKINEMATIC = (1<<4),
467 eTRIGGER = (1<<5)
468 };
469};
470
471
472/**
473\brief Structure which gets passed into the collision filtering shader and/or callback providing additional information on objects of a collision pair
474
475@see PxSimulationFilterShader PxSimulationFilterCallback getActorType() PxFilterObjectIsKinematic() PxFilterObjectIsTrigger()
476*/
477typedef PxU32 PxFilterObjectAttributes;
478
479
480/**
481\brief Extract filter object type from the filter attributes of a collision pair object
482
483\param[in] attr The filter attribute of a collision pair object
484\return The type of the collision pair object.
485
486@see PxFilterObjectType
487*/
488PX_INLINE PxFilterObjectType::Enum PxGetFilterObjectType(PxFilterObjectAttributes attr)
489{
490 return static_cast<PxFilterObjectType::Enum>( (attr & (PxFilterObjectType::eMAX_TYPE_COUNT-1)) );
491}
492
493
494/**
495\brief Specifies whether the collision object belongs to a kinematic rigid body
496
497\param[in] attr The filter attribute of a collision pair object
498\return True if the object belongs to a kinematic rigid body, else false
499
500@see PxRigidBodyFlag::eKINEMATIC
501*/
502PX_INLINE bool PxFilterObjectIsKinematic(PxFilterObjectAttributes attr)
503{
504 return ((attr & PxFilterObjectFlag::eKINEMATIC) != 0);
505}
506
507
508/**
509\brief Specifies whether the collision object is a trigger shape
510
511\param[in] attr The filter attribute of a collision pair object
512\return True if the object is a trigger shape, else false
513
514@see PxShapeFlag::eTRIGGER_SHAPE
515*/
516PX_INLINE bool PxFilterObjectIsTrigger(PxFilterObjectAttributes attr)
517{
518 return ((attr & PxFilterObjectFlag::eTRIGGER) != 0);
519}
520
521
522/**
523\brief Filter shader to specify handling of collision pairs.
524
525Collision filtering is a mechanism to specify how a pair of potentially colliding objects should be processed by the
526simulation. A pair of objects is potentially colliding if the bounding volumes of the two objects overlap.
527In short, a collision filter decides whether a collision pair should get processed, temporarily ignored or discarded.
528If a collision pair should get processed, the filter can additionally specify how it should get processed, for instance,
529whether contacts should get resolved, which callbacks should get invoked or which reports should be sent etc.
530
531\note A default implementation of a filter shader is provided in the PhysX extensions library, see #PxDefaultSimulationFilterShader.
532
533@see PxSceneDesc.filterShader PxSimulationFilterCallback
534*/
535
536/**
537\brief Filter method to specify how a pair of potentially colliding objects should be processed.
538
539Return the PxFilterFlag flags and set the PxPairFlag flags to define what the simulation should do with the given collision pair.
540
541This methods gets called when:
542\li The bounding volumes of two objects start to overlap.
543\li The bounding volumes of two objects overlap and the filter data or filter attributes of one of the objects changed
544\li A re-filtering was forced through resetFiltering() (see #PxScene::resetFiltering())
545\li Filtering is requested in scene queries
546
547\note Certain pairs of objects are always ignored and this method does not get called. This is the case for the
548following pairs:
549
550\li Pair of static rigid actors
551\li A static rigid actor and a kinematic actor (unless one is a trigger or if explicitly enabled through #PxSceneFlag::eENABLE_KINEMATIC_STATIC_PAIRS)
552\li Two kinematic actors (unless one is a trigger or if explicitly enabled through #PxSceneFlag::eENABLE_KINEMATIC_PAIRS)
553\li Pair of particle systems
554\li Two jointed rigid bodies and the joint was defined to disable collision
555\li Two articulation links if connected through an articulation joint
556\li Cloth objects and rigid body actors
557
558\note This is a performance critical method and should be stateless. You should neither access external objects
559from within this method nor should you call external methods that are not inlined. If you need a more complex
560logic to filter a collision pair then use the filter callback mechanism for this pair (see #PxSimulationFilterCallback,
561#PxFilterFlag::eCALLBACK, #PxFilterFlag::eNOTIFY).
562
563\param[in] attributes0 The filter attribute of the first object
564\param[in] filterData0 The custom filter data of the first object
565\param[in] attributes1 The filter attribute of the second object
566\param[in] filterData1 The custom filter data of the second object
567\param[out] pairFlags Flags giving additional information on how an accepted pair should get processed
568\param[in] constantBlock The constant global filter data (see #PxSceneDesc.filterShaderData)
569\param[in] constantBlockSize Size of the global filter data (see #PxSceneDesc.filterShaderDataSize)
570\return Filter flags defining whether the pair should be discarded, temporarily ignored, processed and whether the
571filter callback should get invoked for this pair.
572
573@see PxSimulationFilterCallback PxFilterData PxFilterObjectAttributes PxFilterFlag PxFilterFlags PxPairFlag PxPairFlags
574*/
575
576typedef PxFilterFlags (*PxSimulationFilterShader)
577 (PxFilterObjectAttributes attributes0, PxFilterData filterData0,
578 PxFilterObjectAttributes attributes1, PxFilterData filterData1,
579 PxPairFlags& pairFlags, const void* constantBlock, PxU32 constantBlockSize);
580
581
582
583/**
584\brief Filter callback to specify handling of collision pairs.
585
586This class is provided to implement more complex and flexible collision pair filtering logic, for instance, taking
587the state of the user application into account. Filter callbacks also give the user the opportunity to track collision
588pairs and update their filter state.
589
590You might want to check the documentation on #PxSimulationFilterShader as well since it includes more general information
591on filtering.
592
593\note SDK state should not be modified from within the callbacks. In particular objects should not
594be created or destroyed. If state modification is needed then the changes should be stored to a buffer
595and performed after the simulation step.
596
597\note The callbacks may execute in user threads or simulation threads, possibly simultaneously. The corresponding objects
598may have been deleted by the application earlier in the frame. It is the application's responsibility to prevent race conditions
599arising from using the SDK API in the callback while an application thread is making write calls to the scene, and to ensure that
600the callbacks are thread-safe. Return values which depend on when the callback is called during the frame will introduce nondeterminism
601into the simulation. On PS3 use of this callback may compromise simulation performance.
602
603@see PxSceneDesc.filterCallback PxSimulationFilterShader
604*/
605class PxSimulationFilterCallback
606{
607public:
608
609 /**
610 \brief Filter method to specify how a pair of potentially colliding objects should be processed.
611
612 This method gets called when the filter flags returned by the filter shader (see #PxSimulationFilterShader)
613 indicate that the filter callback should be invoked (#PxFilterFlag::eCALLBACK or #PxFilterFlag::eNOTIFY set).
614 Return the PxFilterFlag flags and set the PxPairFlag flags to define what the simulation should do with the given
615 collision pair.
616
617 \param[in] pairID Unique ID of the collision pair used to issue filter status changes for the pair (see #statusChange())
618 \param[in] attributes0 The filter attribute of the first object
619 \param[in] filterData0 The custom filter data of the first object
620 \param[in] a0 Actor pointer of the first object
621 \param[in] s0 Shape pointer of the first object (NULL if the object has no shapes, for example in the case of a particle system)
622 \param[in] attributes1 The filter attribute of the second object
623 \param[in] filterData1 The custom filter data of the second object
624 \param[in] a1 Actor pointer of the second object
625 \param[in] s1 Shape pointer of the second object (NULL if the object has no shapes, for example in the case of a particle system)
626 \param[in,out] pairFlags In: Pair flags returned by the filter shader. Out: Additional information on how an accepted pair should get processed
627 \return Filter flags defining whether the pair should be discarded, temporarily ignored or processed and whether the pair
628 should be tracked and send a report on pair deletion through the filter callback
629
630 @see PxSimulationFilterShader PxFilterData PxFilterObjectAttributes PxFilterFlag PxPairFlag
631 */
632 virtual PxFilterFlags pairFound( PxU32 pairID,
633 PxFilterObjectAttributes attributes0, PxFilterData filterData0, const PxActor* a0, const PxShape* s0,
634 PxFilterObjectAttributes attributes1, PxFilterData filterData1, const PxActor* a1, const PxShape* s1,
635 PxPairFlags& pairFlags) = 0;
636
637 /**
638 \brief Callback to inform that a tracked collision pair is gone.
639
640 This method gets called when a collision pair disappears or gets re-filtered. Only applies to
641 collision pairs which have been marked as filter callback pairs (#PxFilterFlag::eNOTIFY set in #pairFound()).
642
643 \param[in] pairID Unique ID of the collision pair that disappeared
644 \param[in] attributes0 The filter attribute of the first object
645 \param[in] filterData0 The custom filter data of the first object
646 \param[in] attributes1 The filter attribute of the second object
647 \param[in] filterData1 The custom filter data of the second object
648 \param[in] objectRemoved True if the pair was lost because one of the objects got removed from the scene
649
650 @see pairFound() PxSimulationFilterShader PxFilterData PxFilterObjectAttributes
651 */
652 virtual void pairLost( PxU32 pairID,
653 PxFilterObjectAttributes attributes0,
654 PxFilterData filterData0,
655 PxFilterObjectAttributes attributes1,
656 PxFilterData filterData1,
657 bool objectRemoved) = 0;
658
659 /**
660 \brief Callback to give the opportunity to change the filter state of a tracked collision pair.
661
662 This method gets called once per simulation step to let the application change the filter and pair
663 flags of a collision pair that has been reported in #pairFound() and requested callbacks by
664 setting #PxFilterFlag::eNOTIFY. To request a change of filter status, the target pair has to be
665 specified by its ID, the new filter and pair flags have to be provided and the method should return true.
666
667 \note If this method changes the filter status of a collision pair and the pair should keep being tracked
668 by the filter callbacks then #PxFilterFlag::eNOTIFY has to be set.
669
670 \note The application is responsible to ensure that this method does not get called for pairs that have been
671 reported as lost, see #pairLost().
672
673 \param[out] pairID ID of the collision pair for which the filter status should be changed
674 \param[out] pairFlags The new pairFlags to apply to the collision pair
675 \param[out] filterFlags The new filterFlags to apply to the collision pair
676 \return True if the changes should be applied. In this case the method will get called again. False if
677 no more status changes should be done in the current simulation step. In that case the provided flags will be discarded.
678
679 @see pairFound() pairLost() PxFilterFlag PxPairFlag
680 */
681 virtual bool statusChange(PxU32& pairID, PxPairFlags& pairFlags, PxFilterFlags& filterFlags) = 0;
682
683protected:
684 virtual ~PxSimulationFilterCallback() {}
685};
686
687#ifndef PX_DOXYGEN
688} // namespace physx
689#endif
690
691/** @} */
692#endif
693