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_ARTICULATION
15#define PX_PHYSICS_NX_ARTICULATION
16/** \addtogroup physics
17@{ */
18
19#include "PxPhysXConfig.h"
20#include "common/PxBase.h"
21
22#ifndef PX_DOXYGEN
23namespace physx
24{
25#endif
26
27class PxArticulationLink;
28
29/**
30\brief Articulation drive cache
31
32This cache is used for making one or more impulse applications to the articulation.
33
34@see PxArticulation PxArticulation.createDriveCache
35*/
36class PxArticulationDriveCache
37{
38protected:
39 PxArticulationDriveCache();
40};
41
42/**
43\brief a tree structure of bodies connected by joints that is treated as a unit by the dynamics solver
44
45Articulations are more expensive to simulate than the equivalent collection of
46PxRigidDynamic and PxJoint structures, but because the dynamics solver treats
47each articulation as a single object, they are much less prone to separation and
48have better support for actuation.
49
50@see PxArticulationJoint PxArticulationLink PxPhysics.createArticulation
51*/
52class PxArticulation : public PxBase
53{
54public:
55 /**
56 \brief Deletes the articulation.
57
58 Do not keep a reference to the deleted instance.
59
60 @see PxPhysics.createArticulation()
61 */
62 virtual void release() = 0;
63
64 /**
65 \brief Retrieves the scene which this articulation belongs to.
66
67 \return Owner Scene. NULL if not part of a scene.
68
69 @see PxScene
70 */
71 virtual PxScene* getScene() const = 0;
72
73
74 /**
75 \brief sets maxProjectionIterations.
76
77 This is the maximum number of iterations to run projection on the articulation to bring
78 the links back together if the separation tolerance is exceeded.
79
80
81 \param[in] iterations the maximum number of projection iterations
82 <b>Default:</b> 4
83
84 @see getMaxProjectionIterations()
85 */
86 virtual void setMaxProjectionIterations(PxU32 iterations) = 0;
87
88 /**
89 \brief gets maxProjectionIterations.
90
91 \return the maximum number of projection iterations
92
93 @see setMaxProjectionIterations()
94 */
95
96 virtual PxU32 getMaxProjectionIterations() const = 0;
97
98 /**
99 \brief sets separationTolerance.
100
101 This is the maximum allowed separation of any joint in the articulation before projection is used
102
103 <b>Default: 0.1f, scaled by the tolerance scale </b>
104
105 \param[in] tolerance the separation tolerance for the articulation
106
107 @see getSeparationTolerance()
108 */
109 virtual void setSeparationTolerance(PxReal tolerance) = 0;
110
111 /**
112 \brief gets separationTolerance.
113
114 \return the separation tolerance
115
116 @see setSeparationTolerance()
117 */
118
119 virtual PxReal getSeparationTolerance() const = 0;
120
121
122 /**
123 \brief sets the number of iterations used to compute the drive response to internal forces
124
125 The drive model uses an iterative algorithm to determine the load on each joint of the articulation.
126 This is the number of iterations to use when computing response of the drive to internal forces.
127
128 \param[in] iterations the number of iterations used to compute the drive response to internal forces.
129
130 <b>Default:</b> 4
131
132 @see getInternalDriveIterations()
133 */
134 virtual void setInternalDriveIterations(PxU32 iterations) = 0;
135
136 /**
137 \brief gets internal driveIterations.
138
139 \return the number of iterations used to compute the drive response to internal forces
140
141 @see setInternalDriveIterations()
142 */
143
144 virtual PxU32 getInternalDriveIterations() const = 0;
145
146
147 /**
148 \brief sets the number of iterations for drive response to external forces.
149
150 The drive model uses an iterative algorithm to determine the load on each joint of the articulation.
151 This is the number of iterations to use when computing response of the drive to external forces.
152
153 \param[in] iterations the number of iterations used to compute the drive response to external forces.
154
155 <b>Default:</b> 4
156
157 @see getExternalDriveIterations()
158 */
159
160 virtual void setExternalDriveIterations(PxU32 iterations) = 0;
161
162 /**
163 \brief gets externalDriveIterations.
164
165 \return the number of iterations used to compute the drive response to external forces
166
167 @see setExternalDriveIterations()
168 */
169
170 virtual PxU32 getExternalDriveIterations() const = 0;
171
172
173
174 /**
175 \brief Sets the solver iteration counts for the articulation.
176
177 The solver iteration count determines how accurately joints and contacts are resolved.
178 If you are having trouble with jointed bodies oscillating and behaving erratically, then
179 setting a higher position iteration count may improve their stability.
180
181 If intersecting bodies are being depenetrated too violently, increase the number of velocity
182 iterations. More velocity iterations will drive the relative exit velocity of the intersecting
183 objects closer to the correct value given the restitution.
184
185 \param[in] minPositionIters Number of position iterations the solver should perform for this articulation. <b>Range:</b> [1,255]
186 \param[in] minVelocityIters Number of velocity iterations the solver should perform for this articulation. <b>Range:</b> [1,255]
187
188 @see getSolverIterationCounts()
189 */
190 virtual void setSolverIterationCounts(PxU32 minPositionIters, PxU32 minVelocityIters = 1) = 0;
191
192 /**
193 \brief Retrieves the solver iteration counts.
194
195 @see setSolverIterationCounts()
196 */
197 virtual void getSolverIterationCounts(PxU32 & minPositionIters, PxU32 & minVelocityIters) const = 0;
198
199 /**
200 \brief Returns true if this articulation is sleeping.
201
202 When an actor does not move for a period of time, it is no longer simulated in order to save time. This state
203 is called sleeping. However, because the object automatically wakes up when it is either touched by an awake object,
204 or a sleep-affecting property is changed by the user, the entire sleep mechanism should be transparent to the user.
205
206 An articulation can only go to sleep if all links are ready for sleeping. An articulation is guaranteed to be awake
207 if at least one of the following holds:
208
209 \li The wake counter is positive (see #setWakeCounter()).
210 \li The linear or angular velocity of any link is non-zero.
211 \li A non-zero force or torque has been applied to the articulation or any of its links.
212
213 If an articulation is sleeping, the following state is guaranteed:
214
215 \li The wake counter is zero.
216 \li The linear and angular velocity of all links is zero.
217 \li There is no force update pending.
218
219 When an articulation gets inserted into a scene, it will be considered asleep if all the points above hold, else it will
220 be treated as awake.
221
222 If an articulation is asleep after the call to PxScene::fetchResults() returns, it is guaranteed that the poses of the
223 links were not changed. You can use this information to avoid updating the transforms of associated of dependent objects.
224
225 \note It is invalid to use this method if the articulation has not been added to a scene already.
226
227 \return True if the articulation is sleeping.
228
229 @see isSleeping() wakeUp() putToSleep() getSleepThreshold()
230 */
231 virtual bool isSleeping() const = 0;
232
233 /**
234 \brief Sets the mass-normalized energy threshold below which an articulation may go to sleep.
235
236 The articulation will sleep if the energy of each body is below this threshold.
237
238 \param[in] threshold Energy below which an actor may go to sleep. <b>Range:</b> [0, PX_MAX_F32)
239
240 @see isSleeping() getSleepThreshold() wakeUp() putToSleep()
241 */
242 virtual void setSleepThreshold(PxReal threshold) = 0;
243
244 /**
245 \brief Returns the mass-normalized energy below which an articulation may go to sleep.
246
247 \return The energy threshold for sleeping.
248
249 @see isSleeping() wakeUp() putToSleep() setSleepThreshold()
250 */
251 virtual PxReal getSleepThreshold() const = 0;
252
253 /**
254 \brief Sets the mass-normalized kinetic energy threshold below which an articulation may participate in stabilization.
255
256 Articulation whose kinetic energy divided by their mass is above this threshold will not participate in stabilization.
257
258 This value has no effect if PxSceneFlag::eENABLE_STABILIZATION was not enabled on the PxSceneDesc.
259
260 <b>Default:</b> 0.01 * PxTolerancesScale::speed * PxTolerancesScale::speed
261
262 \param[in] threshold Energy below which an actor may participate in stabilization. <b>Range:</b> (0,inf]
263
264 @see getStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION
265 */
266 virtual void setStabilizationThreshold(PxReal threshold) = 0;
267
268 /**
269 \brief Returns the mass-normalized kinetic energy below which an articulation may participate in stabilization.
270
271 Articulations whose kinetic energy divided by their mass is above this threshold will not participate in stabilization.
272
273 \return The energy threshold for participating in stabilization.
274
275 @see setStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION
276 */
277 virtual PxReal getStabilizationThreshold() const = 0;
278
279 /**
280 \brief Sets the wake counter for the articulation.
281
282 The wake counter value determines the minimum amount of time until the articulation can be put to sleep. Please note
283 that an articulation will not be put to sleep if the energy is above the specified threshold (see #setSleepThreshold())
284 or if other awake objects are touching it.
285
286 \note Passing in a positive value will wake the articulation up automatically.
287
288 <b>Default:</b> 0.4 (which corresponds to 20 frames for a time step of 0.02)
289
290 \param[in] wakeCounterValue Wake counter value. <b>Range:</b> [0, PX_MAX_F32)
291
292 @see isSleeping() getWakeCounter()
293 */
294 virtual void setWakeCounter(PxReal wakeCounterValue) = 0;
295
296 /**
297 \brief Returns the wake counter of the articulation.
298
299 \return The wake counter of the articulation.
300
301 @see isSleeping() setWakeCounter()
302 */
303 virtual PxReal getWakeCounter() const = 0;
304
305 /**
306 \brief Wakes up the articulation if it is sleeping.
307
308 The articulation will get woken up and might cause other touching objects to wake up as well during the next simulation step.
309
310 \note This will set the wake counter of the articulation to the value specified in #PxSceneDesc::wakeCounterResetValue.
311
312 \note It is invalid to use this method if the articulation has not been added to a scene already.
313
314 @see isSleeping() putToSleep()
315 */
316 virtual void wakeUp() = 0;
317
318 /**
319 \brief Forces the articulation to sleep.
320
321 The articulation will stay asleep during the next simulation step if not touched by another non-sleeping actor.
322
323 \note This will set any applied force, the velocity and the wake counter of all bodies in the articulation to zero.
324
325 \note It is invalid to use this method if the articulation has not been added to a scene already.
326
327 @see isSleeping() wakeUp()
328 */
329 virtual void putToSleep() = 0;
330
331 /**
332 \brief adds a link to the articulation with default attribute values.
333
334 \param[in] parent the parent link of the articulation. Should be NULL if (and only if) this is the root link
335 \param[in] pose the pose of the new link
336
337 \return the new link, or NULL if the link cannot be created because the articulation has reached
338 its maximum link count
339
340 @see PxArticulationLink
341 */
342
343 virtual PxArticulationLink* createLink(PxArticulationLink* parent, const PxTransform& pose) = 0;
344
345
346 /**
347 \brief returns the number of links in the articulation
348 */
349
350 virtual PxU32 getNbLinks() const = 0;
351
352 /**
353 \brief returns the set of links in the articulation
354
355 \param[in] userBuffer buffer into which to write an array of articulation link pointers
356 \param[in] bufferSize the size of the buffer. If this is not large enough to contain all the pointers to links,
357 only as many as will fit are written.
358
359 \return the number of links written into the buffer.
360
361 @see PxsArticulationLink
362 */
363
364 virtual PxU32 getLinks(PxArticulationLink** userBuffer, PxU32 bufferSize) const = 0;
365
366 /**
367 \brief Sets a name string for the object that can be retrieved with getName().
368
369 This is for debugging and is not used by the SDK. The string is not copied by the SDK,
370 only the pointer is stored.
371
372 \param[in] name String to set the objects name to.
373
374 @see getName()
375 */
376 virtual void setName(const char* name) = 0;
377
378 /**
379 \brief Retrieves the name string set with setName().
380
381 \return Name string associated with object.
382
383 @see setName()
384 */
385 virtual const char* getName() const = 0;
386
387 /**
388 \brief Retrieves the axis aligned bounding box enclosing the articulation.
389
390 \param[in] inflation Scale factor for computed world bounds. Box extents are multiplied by this value.
391
392 \return The articulation's bounding box.
393
394 @see PxBounds3
395 */
396 virtual PxBounds3 getWorldBounds(float inflation=1.01f) const = 0;
397
398 /**
399 \brief Retrieves the aggregate the articulation might be a part of.
400
401 \return The aggregate the articulation is a part of, or NULL if the articulation does not belong to an aggregate.
402
403 @see PxAggregate
404 */
405 virtual PxAggregate* getAggregate() const = 0;
406
407 /**
408 \brief create a drive cache for applying impulses which are propagated to the entire articulation
409
410 \param[in] compliance the compliance value to use at all joints of the articulation. This is equivalent to the external compliance
411 parameter for articulation joints, as the impulse is treated as an external force
412 \param[in] driveIterations the number of iterations to use to evaluate the drive strengths
413
414 \return a drive cache
415
416 @see PxArticulationDriveCache updateDriveCache releaseDriveCache applyImpulse computeImpulseResponse
417
418 \note this call may only be made on articulations that are in a scene, and may not be made during simulation
419
420 */
421 virtual PxArticulationDriveCache*
422 createDriveCache(PxReal compliance, PxU32 driveIterations) const = 0;
423
424
425 /**
426 \brief update a drive cache
427
428 \param[in] driveCache the drive cache to update
429 \param[in] compliance the compliance value to use at all joints of the articulation.
430 \param[in] driveIterations the number of iterations to use to evaluate the drive strengths
431
432 \return a drive cache
433
434 @see releaseDriveCache createDriveCache applyImpulse computeImpulseResponse
435
436 \note this call may only be made on articulations that are in a scene, and may not be made during simulation
437
438 */
439 virtual void updateDriveCache(PxArticulationDriveCache& driveCache,
440 PxReal compliance,
441 PxU32 driveIterations) const = 0;
442
443 /**
444 \brief release a drive cache
445
446 \param[in] driveCache the drive cache to release
447
448 @see createDriveCache updateDriveCache
449 */
450 virtual void releaseDriveCache(PxArticulationDriveCache& driveCache) const = 0;
451
452 /**
453 \brief apply an impulse to an entire articulation
454
455 \param[in] link the link to which to apply the impulse
456 \param[in] driveCache the drive cache
457 \param[in] linearImpulse the linear impulse to apply
458 \param[in] angularImpulse the angular impulse to apply
459
460 @see computeImpulseResponse
461
462 \note this call may only be made on articulations that are in a scene, and may not be made during simulation
463
464 */
465 virtual void applyImpulse(PxArticulationLink* link,
466 const PxArticulationDriveCache& driveCache,
467 const PxVec3& linearImpulse,
468 const PxVec3& angularImpulse) = 0;
469
470 /**
471 \brief determine the effect of applying an impulse to an entire articulation, without applying the impulse
472
473 \param[in] link the link to which to apply the impulse
474 \param[out] linearResponse the change in linear velocity of the articulation link
475 \param[out] angularResponse the change in angular velocity of the articulation link
476 \param[in] driveCache the drive cache
477 \param[in] linearImpulse the linear impulse to apply
478 \param[in] angularImpulse the angular impulse to apply
479
480 @see applyImpulse
481
482 This call will wake up the articulation if it is asleep.
483
484 \note this call may only be made on articulations that are in a scene, and may not be made during simulation
485 */
486
487 virtual void computeImpulseResponse(PxArticulationLink*link,
488 PxVec3& linearResponse,
489 PxVec3& angularResponse,
490 const PxArticulationDriveCache& driveCache,
491 const PxVec3& linearImpulse,
492 const PxVec3& angularImpulse) const = 0;
493
494
495 //public variables:
496 void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
497
498 virtual const char* getConcreteTypeName() const { return "PxArticulation"; }
499
500protected:
501 PX_INLINE PxArticulation(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {}
502 PX_INLINE PxArticulation(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
503 virtual ~PxArticulation() {}
504 virtual bool isKindOf(const char* name) const { return !strcmp("PxArticulation", name) || PxBase::isKindOf(name); }
505
506
507};
508
509#ifndef PX_DOXYGEN
510} // namespace physx
511#endif
512
513/** @} */
514#endif
515