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_RIGIDACTOR
15#define PX_PHYSICS_NX_RIGIDACTOR
16/** \addtogroup physics
17@{
18*/
19
20#include "PxActor.h"
21#include "PxShape.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28class PxConstraint;
29class PxMaterial;
30class PxGeometry;
31
32/**
33\brief PxRigidActor represents a base class shared between dynamic and static rigid bodies in the physics SDK.
34
35PxRigidActor objects specify the geometry of the object by defining a set of attached shapes (see #PxShape, #createShape()).
36
37@see PxActor
38*/
39
40class PxRigidActor : public PxActor
41{
42public:
43 /**
44 \brief Deletes the rigid actor object.
45
46 Also releases any shapes associated with the actor.
47
48 Releasing an actor will affect any objects that are connected to the actor (constraint shaders like joints etc.).
49 Such connected objects will be deleted upon scene deletion, or explicitly by the user by calling release()
50 on these objects. It is recommended to always remove all objects that reference actors before the actors
51 themselves are removed. It is not possible to retrieve list of dead connected objects.
52
53 <b>Sleeping:</b> This call will awaken any sleeping actors contacting the deleted actor (directly or indirectly).
54
55 Calls #PxActor::release() so you might want to check the documentation of that method as well.
56
57 @see PxActor::release()
58 */
59 virtual void release() = 0;
60
61
62/************************************************************************************************/
63/** @name Global Pose Manipulation
64*/
65
66 /**
67 \brief Retrieves the actors world space transform.
68
69 The getGlobalPose() method retrieves the actor's current actor space to world space transformation.
70
71 \return Global pose of object.
72
73 @see PxRigidDynamic.setGlobalPose() PxRigidStatic.setGlobalPose()
74 */
75 virtual PxTransform getGlobalPose() const = 0;
76
77 /**
78 \brief Method for setting an actor's pose in the world.
79
80 This method instantaneously changes the actor space to world space transformation.
81
82 This method is mainly for dynamic rigid bodies (see #PxRigidDynamic). Calling this method on static actors is
83 likely to result in a performance penalty, since internal optimization structures for static actors may need to be
84 recomputed. In addition, moving static actors will not interact correctly with dynamic actors or joints.
85
86 To directly control an actor's position and have it correctly interact with dynamic bodies and joints, create a dynamic
87 body with the PxRigidBodyFlag::eKINEMATIC flag, then use the setKinematicTarget() commands to define its path.
88
89 Even when moving dynamic actors, exercise restraint in making use of this method. Where possible, avoid:
90
91 \li moving actors into other actors, thus causing overlap (an invalid physical state)
92
93 \li moving an actor that is connected by a joint to another away from the other (thus causing joint error)
94
95 <b>Sleeping:</b> This call wakes dynamic actors if they are sleeping and the autowake parameter is true (default).
96
97 \param[in] pose Transformation from the actors local frame to the global frame. <b>Range:</b> rigid body transform.
98 \param[in] autowake whether to wake the object if it is dynamic. This parameter has no effect for static or kinematic actors. If true and the current wake counter value is smaller than #PxSceneDesc::wakeCounterResetValue it will get increased to the reset value.
99
100 @see getGlobalPose()
101 */
102 virtual void setGlobalPose(const PxTransform& pose, bool autowake = true) = 0;
103
104
105/************************************************************************************************/
106/** @name Shapes
107*/
108
109
110 /**
111 \brief Creates a new shape with default properties and a list of materials and adds it to the list of shapes of this actor.
112
113 This is equivalent to the following
114
115 PxShape* shape(...) = PxGetPhysics().createShape(...); // reference count is 1
116 actor->attachShape(shape); // increments reference count
117 shape->release(); // releases user reference, leaving reference count at 1
118
119 As a consequence, detachShape() will result in the release of the last reference, and the shape will be deleted.
120
121 \note The default shape flags to be set are: eVISUALIZATION, eSIMULATION_SHAPE, eSCENE_QUERY_SHAPE (see #PxShapeFlag).
122 Triangle mesh, heightfield or plane geometry shapes configured as eSIMULATION_SHAPE are not supported for
123 non-kinematic PxRigidDynamic instances.
124
125 \note Creating compounds with a very large number of shapes may adversely affect performance and stability.
126
127 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
128
129 \param[in] geometry the geometry of the shape
130 \param[in] materials a pointer to an array of material pointers
131 \param[in] materialCount the count of materials
132 \param[in] shapeFlags optional PxShapeFlags
133
134 \return The newly created shape.
135
136 @see PxShape PxShape::release()
137 */
138
139 virtual PxShape* createShape(const PxGeometry& geometry, PxMaterial*const* materials, PxU16 materialCount, PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE) = 0;
140
141 /**
142 \deprecated
143 \brief Deprecated function to create shapes with an initial transform.
144
145 Use this instead:
146 PxShape* shape = actor->createShape(geometry, materials, materialCount);
147 if (shape)
148 shape->setLocalPose(transform);
149
150 @see PxShape, createShape(const PxGeometry& geometry, PxMaterial*const* materials, PxU16 materialCount, PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE)
151 */
152 PX_DEPRECATED PX_INLINE PxShape* createShape(const PxGeometry& geometry, PxMaterial*const* materials, PxU32 materialCount, const PxTransform& localPose)
153 {
154 PxShape* shape = createShape(geometry, materials, PxU16(materialCount));
155 if (shape)
156 shape->setLocalPose(localPose);
157 return shape;
158 }
159
160 /**
161 \brief Creates a new shape with default properties and a single material adds it to the list of shapes of this actor.
162
163 This is equivalent to the following
164
165 PxShape* shape(...) = PxGetPhysics().createShape(...); // reference count is 1
166 actor->attachShape(shape); // increments reference count
167 shape->release(); // releases user reference, leaving reference count at 1
168
169 As a consequence, detachShape() will result in the release of the last reference, and the shape will be deleted.
170
171 \note The default shape flags to be set are: eVISUALIZATION, eSIMULATION_SHAPE, eSCENE_QUERY_SHAPE (see #PxShapeFlag).
172 Triangle mesh, heightfield or plane geometry shapes configured as eSIMULATION_SHAPE are not supported for
173 non-kinematic PxRigidDynamic instances.
174
175 \note Creating compounds with a very large number of shapes may adversely affect performance and stability.
176
177 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
178
179 \param[in] geometry the geometry of the shape
180 \param[in] material the material for the shape
181 \param[in] shapeFlags optional PxShapeFlags
182
183 \return The newly created shape.
184
185 @see PxShape PxShape::release() detachShape()
186 */
187
188 PX_FORCE_INLINE PxShape* createShape(const PxGeometry& geometry, const PxMaterial& material, PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE)
189 {
190 PxMaterial* materialPtr = const_cast<PxMaterial*>(&material);
191 return createShape(geometry, &materialPtr, 1, shapeFlags);
192 }
193
194 /**
195 \deprecated
196 \brief Deprecated function to create shapes with an initial transform.
197
198 Use this instead:
199 PxShape* shape = actor->createShape(geometry, material);
200 if (shape)
201 shape->setLocalPose(transform);
202
203 @see PxShape, createShape(const PxGeometry& geometry, const PxMaterial& material, PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE)
204 */
205 PX_DEPRECATED PX_INLINE PxShape* createShape(const PxGeometry& geometry, const PxMaterial& material, const PxTransform& localPose)
206 {
207 PxShape* shape = createShape(geometry, material);
208 if (shape)
209 shape->setLocalPose(localPose);
210 return shape;
211 }
212
213
214 /** attach a shared shape to an actor
215
216 This call will increment the reference count of the shape.
217
218 \note Mass properties of dynamic rigid actors will not automatically be recomputed
219 to reflect the new mass distribution implied by the shape. Follow this call with a call to
220 the PhysX extensions method #PxRigidBodyExt::updateMassAndInertia() to do that.
221
222 Attaching a triangle mesh, heightfield or plane geometry shape configured as eSIMULATION_SHAPE is not supported for
223 non-kinematic PxRigidDynamic instances.
224
225
226 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
227
228 \param[in] shape the shape to attach.
229
230 */
231 virtual void attachShape(PxShape& shape) = 0;
232
233
234 /** detach a shape from an actor.
235
236 This will also decrement the reference count of the PxShape, and if the reference count is zero, will cause it to be deleted.
237
238 For static rigid actors it is not possible to detach all shapes associated with the actor.
239 An attempt to remove the last shape will be ignored.
240
241 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
242
243 \param[in] shape the shape to detach.
244 \param[in] wakeOnLostTouch Specifies whether touching objects from the previous frame should get woken up in the next frame. Only applies to PxArticulation and PxRigidActor types.
245
246 */
247 virtual void detachShape(PxShape& shape, bool wakeOnLostTouch = true) = 0;
248
249
250 /**
251 \brief Returns the number of shapes assigned to the actor.
252
253 You can use #getShapes() to retrieve the shape pointers.
254
255 \return Number of shapes associated with this actor.
256
257 @see PxShape getShapes()
258 */
259 virtual PxU32 getNbShapes() const = 0;
260
261
262 /**
263 \brief Retrieve all the shape pointers belonging to the actor.
264
265 These are the shapes used by the actor for collision detection.
266
267 You can retrieve the number of shape pointers by calling #getNbShapes()
268
269 Note: Removing shapes with #PxShape::release() will invalidate the pointer of the released shape.
270
271 \param[out] userBuffer The buffer to store the shape pointers.
272 \param[in] bufferSize Size of provided user buffer.
273 \param[in] startIndex Index of first shape pointer to be retrieved
274 \return Number of shape pointers written to the buffer.
275
276 @see PxShape getNbShapes() PxShape::release()
277 */
278 virtual PxU32 getShapes(PxShape** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
279
280/************************************************************************************************/
281/** @name Constraints
282*/
283
284 /**
285 \brief Returns the number of constraint shaders attached to the actor.
286
287 You can use #getConstraints() to retrieve the constraint shader pointers.
288
289 \return Number of constraint shaders attached to this actor.
290
291 @see PxConstraint getConstraints()
292 */
293 virtual PxU32 getNbConstraints() const = 0;
294
295
296 /**
297 \brief Retrieve all the constraint shader pointers belonging to the actor.
298
299 You can retrieve the number of constraint shader pointers by calling #getNbConstraints()
300
301 Note: Removing constraint shaders with #PxConstraint::release() will invalidate the pointer of the released constraint.
302
303 \param[out] userBuffer The buffer to store the constraint shader pointers.
304 \param[in] bufferSize Size of provided user buffer.
305 \param[in] startIndex Index of first constraint pointer to be retrieved
306 \return Number of constraint shader pointers written to the buffer.
307
308 @see PxConstraint getNbConstraints() PxConstraint::release()
309 */
310 virtual PxU32 getConstraints(PxConstraint** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
311
312protected:
313 PX_INLINE PxRigidActor(PxType concreteType, PxBaseFlags baseFlags) : PxActor(concreteType, baseFlags) {}
314 PX_INLINE PxRigidActor(PxBaseFlags baseFlags) : PxActor(baseFlags) {}
315 virtual ~PxRigidActor() {}
316 virtual bool isKindOf(const char* name) const { return !strcmp("PxRigidActor", name) || PxActor::isKindOf(name); }
317};
318
319PX_DEPRECATED PX_INLINE PxRigidActor* PxActor::isRigidActor() { return is<PxRigidActor>(); }
320PX_DEPRECATED PX_INLINE const PxRigidActor* PxActor::isRigidActor() const { return is<PxRigidActor>(); }
321
322
323#ifndef PX_DOXYGEN
324} // namespace physx
325#endif
326
327/** @} */
328#endif
329