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