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#ifndef PX_PHYSICS_NX_SHAPE
31#define PX_PHYSICS_NX_SHAPE
32/** \addtogroup physics
33@{
34*/
35
36#include "PxPhysXConfig.h"
37#include "common/PxBase.h"
38#include "geometry/PxGeometry.h"
39#include "geometry/PxGeometryHelpers.h"
40
41#if !PX_DOXYGEN
42namespace physx
43{
44#endif
45
46class PxBoxGeometry;
47class PxSphereGeometry;
48class PxCapsuleGeometry;
49class PxPlaneGeometry;
50class PxConvexMeshGeometry;
51class PxTriangleMeshGeometry;
52class PxHeightFieldGeometry;
53class PxRigidActor;
54struct PxFilterData;
55struct PxRaycastHit;
56struct PxSweepHit;
57
58/**
59\brief Flags which affect the behavior of PxShapes.
60
61@see PxShape PxShape.setFlag()
62*/
63struct PxShapeFlag
64{
65 enum Enum
66 {
67 /**
68 \brief The shape will partake in collision in the physical simulation.
69
70 \note It is illegal to raise the eSIMULATION_SHAPE and eTRIGGER_SHAPE flags.
71 In the event that one of these flags is already raised the sdk will reject any
72 attempt to raise the other. To raise the eSIMULATION_SHAPE first ensure that
73 eTRIGGER_SHAPE is already lowered.
74
75 \note This flag has no effect if simulation is disabled for the corresponding actor (see #PxActorFlag::eDISABLE_SIMULATION).
76
77 @see PxSimulationEventCallback.onContact() PxScene.setSimulationEventCallback() PxShape.setFlag(), PxShape.setFlags()
78 */
79 eSIMULATION_SHAPE = (1<<0),
80
81 /**
82 \brief The shape will partake in scene queries (ray casts, overlap tests, sweeps, ...).
83 */
84 eSCENE_QUERY_SHAPE = (1<<1),
85
86 /**
87 \brief The shape is a trigger which can send reports whenever other shapes enter/leave its volume.
88
89 \note Triangle meshes and heightfields can not be triggers. Shape creation will fail in these cases.
90
91 \note Shapes marked as triggers do not collide with other objects. If an object should act both
92 as a trigger shape and a collision shape then create a rigid body with two shapes, one being a
93 trigger shape and the other a collision shape. It is illegal to raise the eTRIGGER_SHAPE and
94 eSIMULATION_SHAPE flags on a single PxShape instance. In the event that one of these flags is already
95 raised the sdk will reject any attempt to raise the other. To raise the eTRIGGER_SHAPE flag first
96 ensure that eSIMULATION_SHAPE flag is already lowered.
97
98 \note Trigger shapes will no longer send notification events for interactions with other trigger shapes.
99
100 \note Shapes marked as triggers are allowed to participate in scene queries, provided the eSCENE_QUERY_SHAPE flag is set.
101
102 \note This flag has no effect if simulation is disabled for the corresponding actor (see #PxActorFlag::eDISABLE_SIMULATION).
103
104 @see PxSimulationEventCallback.onTrigger() PxScene.setSimulationEventCallback() PxShape.setFlag(), PxShape.setFlags()
105 */
106 eTRIGGER_SHAPE = (1<<2),
107
108 /**
109 \brief Enable debug renderer for this shape
110
111 @see PxScene.getRenderBuffer() PxRenderBuffer PxVisualizationParameter
112 */
113 eVISUALIZATION = (1<<3)
114 };
115};
116
117/**
118\brief collection of set bits defined in PxShapeFlag.
119
120@see PxShapeFlag
121*/
122typedef PxFlags<PxShapeFlag::Enum,PxU8> PxShapeFlags;
123PX_FLAGS_OPERATORS(PxShapeFlag::Enum,PxU8)
124
125
126/**
127\brief Abstract class for collision shapes.
128
129Shapes are shared, reference counted objects.
130
131An instance can be created by calling the createShape() method of the PxRigidActor class, or
132the createShape() method of the PxPhysics class.
133
134<h3>Visualizations</h3>
135\li PxVisualizationParameter::eCOLLISION_AABBS
136\li PxVisualizationParameter::eCOLLISION_SHAPES
137\li PxVisualizationParameter::eCOLLISION_AXES
138
139@see PxPhysics.createShape() PxRigidActor.createShape() PxBoxGeometry PxSphereGeometry PxCapsuleGeometry PxPlaneGeometry PxConvexMeshGeometry
140PxTriangleMeshGeometry PxHeightFieldGeometry
141*/
142class PxShape : public PxBase
143{
144public:
145
146 /**
147 \brief Decrements the reference count of a shape and releases it if the new reference count is zero.
148
149 Note that in releases prior to PhysX 3.3 this method did not have reference counting semantics and was used to destroy a shape
150 created with PxActor::createShape(). In PhysX 3.3 and above, this usage is deprecated, instead, use PxRigidActor::detachShape() to detach
151 a shape from an actor. If the shape to be detached was created with PxActor::createShape(), the actor holds the only counted reference,
152 and so when the shape is detached it will also be destroyed.
153
154 @see PxRigidActor::createShape() PxPhysics::createShape() PxRigidActor::attachShape() PxRigidActor::detachShape()
155 */
156 virtual void release() = 0;
157
158 /**
159 \brief Returns the reference count of the shape.
160
161 At creation, the reference count of the shape is 1. Every actor referencing this shape increments the
162 count by 1. When the reference count reaches 0, and only then, the shape gets destroyed automatically.
163
164 \return the current reference count.
165 */
166 virtual PxU32 getReferenceCount() const = 0;
167
168 /**
169 \brief Acquires a counted reference to a shape.
170
171 This method increases the reference count of the shape by 1. Decrement the reference count by calling release()
172 */
173 virtual void acquireReference() = 0;
174
175 /**
176 \brief Get the geometry type of the shape.
177
178 \return Type of shape geometry.
179
180 @see PxGeometryType
181 */
182 virtual PxGeometryType::Enum getGeometryType() const = 0;
183
184 /**
185 \brief Adjust the geometry of the shape.
186
187 \note The type of the passed in geometry must match the geometry type of the shape.
188 \note It is not allowed to change the geometry type of a shape.
189 \note This function does not guarantee correct/continuous behavior when objects are resting on top of old or new geometry.
190
191 \param[in] geometry New geometry of the shape.
192
193 @see PxGeometry PxGeometryType getGeometryType()
194 */
195 virtual void setGeometry(const PxGeometry& geometry) = 0;
196
197
198 /**
199 \brief Retrieve the geometry from the shape in a PxGeometryHolder wrapper class.
200
201 \return a PxGeometryHolder object containing the geometry;
202
203 @see PxGeometry PxGeometryType getGeometryType() setGeometry()
204 */
205
206 virtual PxGeometryHolder getGeometry() const = 0;
207
208
209 /**
210 \brief Fetch the geometry of the shape.
211
212 \note If the type of geometry to extract does not match the geometry type of the shape
213 then the method will return false and the passed in geometry descriptor is not modified.
214
215 \param[in] geometry The descriptor to save the shape's geometry data to.
216 \return True on success else false
217
218 @see PxGeometry PxGeometryType getGeometryType()
219 */
220 virtual bool getBoxGeometry(PxBoxGeometry& geometry) const = 0;
221
222 /**
223 \brief Fetch the geometry of the shape.
224
225 \note If the type of geometry to extract does not match the geometry type of the shape
226 then the method will return false and the passed in geometry descriptor is not modified.
227
228 \param[in] geometry The descriptor to save the shape's geometry data to.
229 \return True on success else false
230
231 @see PxGeometry PxGeometryType getGeometryType()
232 */
233 virtual bool getSphereGeometry(PxSphereGeometry& geometry) const = 0;
234
235 /**
236 \brief Fetch the geometry of the shape.
237
238 \note If the type of geometry to extract does not match the geometry type of the shape
239 then the method will return false and the passed in geometry descriptor is not modified.
240
241 \param[in] geometry The descriptor to save the shape's geometry data to.
242 \return True on success else false
243
244 @see PxGeometry PxGeometryType getGeometryType()
245 */
246 virtual bool getCapsuleGeometry(PxCapsuleGeometry& geometry) const = 0;
247
248 /**
249 \brief Fetch the geometry of the shape.
250
251 \note If the type of geometry to extract does not match the geometry type of the shape
252 then the method will return false and the passed in geometry descriptor is not modified.
253
254 \param[in] geometry The descriptor to save the shape's geometry data to.
255 \return True on success else false
256
257 @see PxGeometry PxGeometryType getGeometryType()
258 */
259 virtual bool getPlaneGeometry(PxPlaneGeometry& geometry) const = 0;
260
261 /**
262 \brief Fetch the geometry of the shape.
263
264 \note If the type of geometry to extract does not match the geometry type of the shape
265 then the method will return false and the passed in geometry descriptor is not modified.
266
267 \param[in] geometry The descriptor to save the shape's geometry data to.
268 \return True on success else false
269
270 @see PxGeometry PxGeometryType getGeometryType()
271 */
272 virtual bool getConvexMeshGeometry(PxConvexMeshGeometry& geometry) const = 0;
273
274 /**
275 \brief Fetch the geometry of the shape.
276
277 \note If the type of geometry to extract does not match the geometry type of the shape
278 then the method will return false and the passed in geometry descriptor is not modified.
279
280 \param[in] geometry The descriptor to save the shape's geometry data to.
281 \return True on success else false
282
283 @see PxGeometry PxGeometryType getGeometryType()
284 */
285 virtual bool getTriangleMeshGeometry(PxTriangleMeshGeometry& geometry) const = 0;
286
287
288 /**
289 \brief Fetch the geometry of the shape.
290
291 \note If the type of geometry to extract does not match the geometry type of the shape
292 then the method will return false and the passed in geometry descriptor is not modified.
293
294 \param[in] geometry The descriptor to save the shape's geometry data to.
295 \return True on success else false
296
297 @see PxGeometry PxGeometryType getGeometryType()
298 */
299 virtual bool getHeightFieldGeometry(PxHeightFieldGeometry& geometry) const = 0;
300
301 /**
302 \brief Retrieves the actor which this shape is associated with.
303
304 \return The actor this shape is associated with, if it is an exclusive shape, else NULL
305
306 @see PxRigidStatic, PxRigidDynamic, PxArticulationLink
307 */
308 virtual PxRigidActor* getActor() const = 0;
309
310
311/************************************************************************************************/
312
313/** @name Pose Manipulation
314*/
315//@{
316
317 /**
318 \brief Sets the pose of the shape in actor space, i.e. relative to the actors to which they are attached.
319
320 This transformation is identity by default.
321
322 The local pose is an attribute of the shape, and so will apply to all actors to which the shape is attached.
323
324 <b>Sleeping:</b> Does <b>NOT</b> wake the associated actor up automatically.
325
326 <i>Note:</i> Does not automatically update the inertia properties of the owning actor (if applicable); use the
327 PhysX extensions method #PxRigidBodyExt::updateMassAndInertia() to do this.
328
329 <b>Default:</b> the identity transform
330
331 \param[in] pose The new transform from the actor frame to the shape frame. <b>Range:</b> rigid body transform
332
333 @see getLocalPose()
334 */
335 virtual void setLocalPose(const PxTransform& pose) = 0;
336
337 /**
338 \brief Retrieves the pose of the shape in actor space, i.e. relative to the actor they are owned by.
339
340 This transformation is identity by default.
341
342 \return Pose of shape relative to the actor's frame.
343
344 @see setLocalPose()
345 */
346 virtual PxTransform getLocalPose() const = 0;
347
348//@}
349/************************************************************************************************/
350
351/** @name Collision Filtering
352*/
353//@{
354
355 /**
356 \brief Sets the user definable collision filter data.
357
358 <b>Sleeping:</b> Does wake up the actor if the filter data change causes a formerly suppressed
359 collision pair to be enabled.
360
361 <b>Default:</b> (0,0,0,0)
362
363 @see getSimulationFilterData()
364 */
365 virtual void setSimulationFilterData(const PxFilterData& data) = 0;
366
367 /**
368 \brief Retrieves the shape's collision filter data.
369
370 @see setSimulationFilterData()
371 */
372 virtual PxFilterData getSimulationFilterData() const = 0;
373
374 /**
375 \brief Sets the user definable query filter data.
376
377 <b>Default:</b> (0,0,0,0)
378
379 @see getQueryFilterData()
380 */
381 virtual void setQueryFilterData(const PxFilterData& data) = 0;
382
383 /**
384 \brief Retrieves the shape's Query filter data.
385
386 @see setQueryFilterData()
387 */
388 virtual PxFilterData getQueryFilterData() const = 0;
389
390//@}
391/************************************************************************************************/
392
393 /**
394 \brief Assigns material(s) to the shape.
395
396 <b>Sleeping:</b> Does <b>NOT</b> wake the associated actor up automatically.
397
398 \param[in] materials List of material pointers to assign to the shape. See #PxMaterial
399 \param[in] materialCount The number of materials provided.
400
401 @see PxPhysics.createMaterial() getMaterials()
402 */
403 virtual void setMaterials(PxMaterial*const* materials, PxU16 materialCount) = 0;
404
405 /**
406 \brief Returns the number of materials assigned to the shape.
407
408 You can use #getMaterials() to retrieve the material pointers.
409
410 \return Number of materials associated with this shape.
411
412 @see PxMaterial getMaterials()
413 */
414 virtual PxU16 getNbMaterials() const = 0;
415
416 /**
417 \brief Retrieve all the material pointers associated with the shape.
418
419 You can retrieve the number of material pointers by calling #getNbMaterials()
420
421 Note: Removing materials with #PxMaterial::release() will invalidate the pointer of the released material.
422
423 \param[out] userBuffer The buffer to store the material pointers.
424 \param[in] bufferSize Size of provided user buffer.
425 \param[in] startIndex Index of first material pointer to be retrieved
426 \return Number of material pointers written to the buffer.
427
428 @see PxMaterial getNbMaterials() PxMaterial::release()
429 */
430 virtual PxU32 getMaterials(PxMaterial** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
431
432 /**
433 \brief Retrieve material from given triangle index.
434
435 The input index is the internal triangle index as used inside the SDK. This is the index
436 returned to users by various SDK functions such as raycasts.
437
438 This function is only useful for triangle meshes or heightfields, which have per-triangle
439 materials. For other shapes the function returns the single material associated with the
440 shape, regardless of the index.
441
442 \param[in] faceIndex The internal triangle index whose material you want to retrieve.
443 \return Material from input triangle
444
445 \note If faceIndex value of 0xFFFFffff is passed as an input for mesh and heightfield shapes, this function will issue a warning and return NULL.
446 \note Scene queries set the value of PxQueryHit::faceIndex to 0xFFFFffff whenever it is undefined or does not apply.
447
448 @see PxMaterial getNbMaterials() PxMaterial::release()
449 */
450 virtual PxMaterial* getMaterialFromInternalFaceIndex(PxU32 faceIndex) const = 0;
451
452 /**
453 \brief Sets the contact offset.
454
455 Shapes whose distance is less than the sum of their contactOffset values will generate contacts. The contact offset must be positive and
456 greater than the rest offset. Having a contactOffset greater than than the restOffset allows the collision detection system to
457 predictively enforce the contact constraint even when the objects are slightly separated. This prevents jitter that would occur
458 if the constraint were enforced only when shapes were within the rest distance.
459
460 <b>Default:</b> 0.02f * PxTolerancesScale::length
461
462 <b>Sleeping:</b> Does <b>NOT</b> wake the associated actor up automatically.
463
464 \param[in] contactOffset <b>Range:</b> [maximum(0,restOffset), PX_MAX_F32)
465
466 @see getContactOffset PxTolerancesScale setRestOffset
467 */
468 virtual void setContactOffset(PxReal contactOffset) = 0;
469
470 /**
471 \brief Retrieves the contact offset.
472
473 \return The contact offset of the shape.
474
475 @see setContactOffset()
476 */
477 virtual PxReal getContactOffset() const = 0;
478
479 /**
480 \brief Sets the rest offset.
481
482 Two shapes will come to rest at a distance equal to the sum of their restOffset values. If the restOffset is 0, they should converge to touching
483 exactly. Having a restOffset greater than zero is useful to have objects slide smoothly, so that they do not get hung up on irregularities of
484 each others' surfaces.
485
486 <b>Default:</b> 0.0f
487
488 <b>Sleeping:</b> Does <b>NOT</b> wake the associated actor up automatically.
489
490 \param[in] restOffset <b>Range:</b> (-PX_MAX_F32, contactOffset)
491
492 @see getRestOffset setContactOffset
493 */
494 virtual void setRestOffset(PxReal restOffset) = 0;
495
496 /**
497 \brief Retrieves the rest offset.
498
499 \return The rest offset of the shape.
500
501 @see setRestOffset()
502 */
503 virtual PxReal getRestOffset() const = 0;
504
505
506 /**
507 \brief Sets torsional patch radius.
508
509 This defines the radius of the contact patch used to apply torsional friction. If the radius is 0, no torsional friction
510 will be applied. If the radius is > 0, some torsional friction will be applied. This is proportional to the penetration depth
511 so, if the shapes are separated or penetration is zero, no torsional friction will be applied. It is used to approximate
512 rotational friction introduced by the compression of contacting surfaces.
513
514 <b>Default:</b> 0.0
515
516 \param[in] radius <b>Range:</b> (0, PX_MAX_F32)
517 */
518 virtual void setTorsionalPatchRadius(PxReal radius) = 0;
519
520 /**
521 \brief Gets torsional patch radius.
522
523 This defines the radius of the contact patch used to apply torsional friction. If the radius is 0, no torsional friction
524 will be applied. If the radius is > 0, some torsional friction will be applied. This is proportional to the penetration depth
525 so, if the shapes are separated or penetration is zero, no torsional friction will be applied. It is used to approximate
526 rotational friction introduced by the compression of contacting surfaces.
527
528 \return The torsional patch radius of the shape.
529 */
530 virtual PxReal getTorsionalPatchRadius() const = 0;
531
532 /**
533 \brief Sets minimum torsional patch radius.
534
535 This defines the minimum radius of the contact patch used to apply torsional friction. If the radius is 0, the amount of torsional friction
536 that will be applied will be entirely dependent on the value of torsionalPatchRadius.
537
538 If the radius is > 0, some torsional friction will be applied regardless of the value of torsionalPatchRadius or the amount of penetration.
539
540 <b>Default:</b> 0.0
541
542 \param[in] radius <b>Range:</b> (0, PX_MAX_F32)
543 */
544 virtual void setMinTorsionalPatchRadius(PxReal radius) = 0;
545
546 /**
547 \brief Gets minimum torsional patch radius.
548
549 This defines the minimum radius of the contact patch used to apply torsional friction. If the radius is 0, the amount of torsional friction
550 that will be applied will be entirely dependent on the value of torsionalPatchRadius.
551
552 If the radius is > 0, some torsional friction will be applied regardless of the value of torsionalPatchRadius or the amount of penetration.
553
554 \return The minimum torsional patch radius of the shape.
555 */
556 virtual PxReal getMinTorsionalPatchRadius() const = 0;
557
558
559/************************************************************************************************/
560
561 /**
562 \brief Sets shape flags
563
564 <b>Sleeping:</b> Does <b>NOT</b> wake the associated actor up automatically.
565
566 \param[in] flag The shape flag to enable/disable. See #PxShapeFlag.
567 \param[in] value True to set the flag. False to clear the flag specified in flag.
568
569 <b>Default:</b> PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSIMULATION_SHAPE | PxShapeFlag::eSCENE_QUERY_SHAPE
570
571 @see PxShapeFlag getFlags()
572 */
573 virtual void setFlag(PxShapeFlag::Enum flag, bool value) = 0;
574
575 /**
576 \brief Sets shape flags
577
578 @see PxShapeFlag getFlags()
579 */
580 virtual void setFlags(PxShapeFlags inFlags) = 0;
581
582 /**
583 \brief Retrieves shape flags.
584
585 \return The values of the shape flags.
586
587 @see PxShapeFlag setFlag()
588 */
589 virtual PxShapeFlags getFlags() const = 0;
590
591 /**
592 \brief Returns true if the shape is exclusive to an actor.
593
594 @see PxPhysics::createShape()
595 */
596 virtual bool isExclusive() const = 0;
597
598 /**
599 \brief Sets a name string for the object that can be retrieved with #getName().
600
601 This is for debugging and is not used by the SDK.
602 The string is not copied by the SDK, only the pointer is stored.
603
604 <b>Default:</b> NULL
605
606 \param[in] name The name string to set the objects name to.
607
608 @see getName()
609 */
610 virtual void setName(const char* name) = 0;
611
612
613 /**
614 \brief retrieves the name string set with setName().
615 \return The name associated with the shape.
616
617 @see setName()
618 */
619 virtual const char* getName() const = 0;
620
621
622 virtual const char* getConcreteTypeName() const { return "PxShape"; }
623
624/************************************************************************************************/
625
626 void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
627
628protected:
629 PX_INLINE PxShape(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
630 PX_INLINE PxShape(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {}
631 virtual ~PxShape() {}
632 virtual bool isKindOf(const char* name) const { return !::strcmp(s1: "PxShape", s2: name) || PxBase::isKindOf(superClass: name); }
633
634};
635
636#if !PX_DOXYGEN
637} // namespace physx
638#endif
639
640/** @} */
641#endif
642

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