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 | |
31 | #ifndef PX_PHYSICS_NX_ARTICULATION_BASE |
32 | #define PX_PHYSICS_NX_ARTICULATION_BASE |
33 | /** \addtogroup physics |
34 | @{ */ |
35 | |
36 | #include "PxPhysXConfig.h" |
37 | #include "common/PxBase.h" |
38 | |
39 | #if !PX_DOXYGEN |
40 | namespace physx |
41 | { |
42 | #endif |
43 | |
44 | class PxArticulationImpl; |
45 | |
46 | /** |
47 | \brief a tree structure of bodies connected by joints that is treated as a unit by the dynamics solver |
48 | |
49 | Articulations are more expensive to simulate than the equivalent collection of |
50 | PxRigidDynamic and PxJoint structures, but because the dynamics solver treats |
51 | each articulation as a single object, they are much less prone to separation and |
52 | have better support for actuation. An articulation may have at most 64 links. |
53 | |
54 | @see PxArticulationJoint PxArticulationLink PxPhysics.createArticulation |
55 | */ |
56 | class PxArticulationBase : public PxBase |
57 | { |
58 | public: |
59 | |
60 | /** |
61 | \brief Retrieves the scene which this articulation belongs to. |
62 | |
63 | \return Owner Scene. NULL if not part of a scene. |
64 | |
65 | @see PxScene |
66 | */ |
67 | virtual PxScene* getScene() const = 0; |
68 | |
69 | /** |
70 | \brief Sets the solver iteration counts for the articulation. |
71 | |
72 | The solver iteration count determines how accurately joints and contacts are resolved. |
73 | If you are having trouble with jointed bodies oscillating and behaving erratically, then |
74 | setting a higher position iteration count may improve their stability. |
75 | |
76 | If intersecting bodies are being depenetrated too violently, increase the number of velocity |
77 | iterations. More velocity iterations will drive the relative exit velocity of the intersecting |
78 | objects closer to the correct value given the restitution. |
79 | |
80 | \param[in] minPositionIters Number of position iterations the solver should perform for this articulation. <b>Range:</b> [1,255] |
81 | \param[in] minVelocityIters Number of velocity iterations the solver should perform for this articulation. <b>Range:</b> [1,255] |
82 | |
83 | @see getSolverIterationCounts() |
84 | */ |
85 | virtual void setSolverIterationCounts(PxU32 minPositionIters, PxU32 minVelocityIters = 1) = 0; |
86 | |
87 | /** |
88 | \brief Retrieves the solver iteration counts. |
89 | |
90 | @see setSolverIterationCounts() |
91 | */ |
92 | virtual void getSolverIterationCounts(PxU32 & minPositionIters, PxU32 & minVelocityIters) const = 0; |
93 | |
94 | /** |
95 | \brief Returns true if this articulation is sleeping. |
96 | |
97 | When an actor does not move for a period of time, it is no longer simulated in order to save time. This state |
98 | is called sleeping. However, because the object automatically wakes up when it is either touched by an awake object, |
99 | or a sleep-affecting property is changed by the user, the entire sleep mechanism should be transparent to the user. |
100 | |
101 | An articulation can only go to sleep if all links are ready for sleeping. An articulation is guaranteed to be awake |
102 | if at least one of the following holds: |
103 | |
104 | \li The wake counter is positive (see #setWakeCounter()). |
105 | \li The linear or angular velocity of any link is non-zero. |
106 | \li A non-zero force or torque has been applied to the articulation or any of its links. |
107 | |
108 | If an articulation is sleeping, the following state is guaranteed: |
109 | |
110 | \li The wake counter is zero. |
111 | \li The linear and angular velocity of all links is zero. |
112 | \li There is no force update pending. |
113 | |
114 | When an articulation gets inserted into a scene, it will be considered asleep if all the points above hold, else it will |
115 | be treated as awake. |
116 | |
117 | If an articulation is asleep after the call to PxScene::fetchResults() returns, it is guaranteed that the poses of the |
118 | links were not changed. You can use this information to avoid updating the transforms of associated of dependent objects. |
119 | |
120 | \note It is invalid to use this method if the articulation has not been added to a scene already. |
121 | |
122 | \return True if the articulation is sleeping. |
123 | |
124 | @see isSleeping() wakeUp() putToSleep() getSleepThreshold() |
125 | */ |
126 | virtual bool isSleeping() const = 0; |
127 | |
128 | /** |
129 | \brief Sets the mass-normalized energy threshold below which an articulation may go to sleep. |
130 | |
131 | The articulation will sleep if the energy of each body is below this threshold. |
132 | |
133 | \param[in] threshold Energy below which an actor may go to sleep. <b>Range:</b> [0, PX_MAX_F32) |
134 | |
135 | @see isSleeping() getSleepThreshold() wakeUp() putToSleep() |
136 | */ |
137 | virtual void setSleepThreshold(PxReal threshold) = 0; |
138 | |
139 | /** |
140 | \brief Returns the mass-normalized energy below which an articulation may go to sleep. |
141 | |
142 | \return The energy threshold for sleeping. |
143 | |
144 | @see isSleeping() wakeUp() putToSleep() setSleepThreshold() |
145 | */ |
146 | virtual PxReal getSleepThreshold() const = 0; |
147 | |
148 | /** |
149 | \brief Sets the mass-normalized kinetic energy threshold below which an articulation may participate in stabilization. |
150 | |
151 | Articulation whose kinetic energy divided by their mass is above this threshold will not participate in stabilization. |
152 | |
153 | This value has no effect if PxSceneFlag::eENABLE_STABILIZATION was not enabled on the PxSceneDesc. |
154 | |
155 | <b>Default:</b> 0.01 * PxTolerancesScale::speed * PxTolerancesScale::speed |
156 | |
157 | \param[in] threshold Energy below which an actor may participate in stabilization. <b>Range:</b> [0,inf) |
158 | |
159 | @see getStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION |
160 | */ |
161 | virtual void setStabilizationThreshold(PxReal threshold) = 0; |
162 | |
163 | /** |
164 | \brief Returns the mass-normalized kinetic energy below which an articulation may participate in stabilization. |
165 | |
166 | Articulations whose kinetic energy divided by their mass is above this threshold will not participate in stabilization. |
167 | |
168 | \return The energy threshold for participating in stabilization. |
169 | |
170 | @see setStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION |
171 | */ |
172 | virtual PxReal getStabilizationThreshold() const = 0; |
173 | |
174 | /** |
175 | \brief Sets the wake counter for the articulation. |
176 | |
177 | The wake counter value determines the minimum amount of time until the articulation can be put to sleep. Please note |
178 | that an articulation will not be put to sleep if the energy is above the specified threshold (see #setSleepThreshold()) |
179 | or if other awake objects are touching it. |
180 | |
181 | \note Passing in a positive value will wake the articulation up automatically. |
182 | |
183 | <b>Default:</b> 0.4 (which corresponds to 20 frames for a time step of 0.02) |
184 | |
185 | \param[in] wakeCounterValue Wake counter value. <b>Range:</b> [0, PX_MAX_F32) |
186 | |
187 | @see isSleeping() getWakeCounter() |
188 | */ |
189 | virtual void setWakeCounter(PxReal wakeCounterValue) = 0; |
190 | |
191 | /** |
192 | \brief Returns the wake counter of the articulation. |
193 | |
194 | \return The wake counter of the articulation. |
195 | |
196 | @see isSleeping() setWakeCounter() |
197 | */ |
198 | virtual PxReal getWakeCounter() const = 0; |
199 | |
200 | /** |
201 | \brief Wakes up the articulation if it is sleeping. |
202 | |
203 | The articulation will get woken up and might cause other touching objects to wake up as well during the next simulation step. |
204 | |
205 | \note This will set the wake counter of the articulation to the value specified in #PxSceneDesc::wakeCounterResetValue. |
206 | |
207 | \note It is invalid to use this method if the articulation has not been added to a scene already. |
208 | |
209 | @see isSleeping() putToSleep() |
210 | */ |
211 | virtual void wakeUp() = 0; |
212 | |
213 | /** |
214 | \brief Forces the articulation to sleep. |
215 | |
216 | The articulation will stay asleep during the next simulation step if not touched by another non-sleeping actor. |
217 | |
218 | \note This will set any applied force, the velocity and the wake counter of all bodies in the articulation to zero. |
219 | |
220 | \note It is invalid to use this method if the articulation has not been added to a scene already. |
221 | |
222 | @see isSleeping() wakeUp() |
223 | */ |
224 | virtual void putToSleep() = 0; |
225 | |
226 | /** |
227 | \brief adds a link to the articulation with default attribute values. |
228 | |
229 | \param[in] parent the parent link of the articulation. Should be NULL if (and only if) this is the root link |
230 | \param[in] pose the initial pose of the new link. Must be a valid transform |
231 | |
232 | \return the new link, or NULL if the link cannot be created because the articulation has reached |
233 | its maximum link count (currently 64). |
234 | |
235 | @see PxArticulationLink |
236 | */ |
237 | virtual PxArticulationLink* createLink(PxArticulationLink* parent, const PxTransform& pose) = 0; |
238 | |
239 | /** |
240 | \brief returns the number of links in the articulation |
241 | */ |
242 | virtual PxU32 getNbLinks() const = 0; |
243 | |
244 | /** |
245 | \brief returns the set of links in the articulation |
246 | |
247 | \param[in] userBuffer buffer into which to write an array of articulation link pointers |
248 | \param[in] bufferSize the size of the buffer. If this is not large enough to contain all the pointers to links, |
249 | only as many as will fit are written. |
250 | \param[in] startIndex Index of first link pointer to be retrieved |
251 | |
252 | \return the number of links written into the buffer. |
253 | |
254 | @see ArticulationLink |
255 | */ |
256 | virtual PxU32 getLinks(PxArticulationLink** userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0; |
257 | |
258 | /** |
259 | \brief Sets a name string for the object that can be retrieved with getName(). |
260 | |
261 | This is for debugging and is not used by the SDK. The string is not copied by the SDK, |
262 | only the pointer is stored. |
263 | |
264 | \param[in] name String to set the objects name to. |
265 | |
266 | @see getName() |
267 | */ |
268 | virtual void setName(const char* name) = 0; |
269 | |
270 | /** |
271 | \brief Retrieves the name string set with setName(). |
272 | |
273 | \return Name string associated with object. |
274 | |
275 | @see setName() |
276 | */ |
277 | virtual const char* getName() const = 0; |
278 | |
279 | /** |
280 | \brief Retrieves the axis aligned bounding box enclosing the articulation. |
281 | |
282 | \param[in] inflation Scale factor for computed world bounds. Box extents are multiplied by this value. |
283 | |
284 | \return The articulation's bounding box. |
285 | |
286 | @see PxBounds3 |
287 | */ |
288 | virtual PxBounds3 getWorldBounds(float inflation = 1.01f) const = 0; |
289 | |
290 | /** |
291 | \brief Retrieves the aggregate the articulation might be a part of. |
292 | |
293 | \return The aggregate the articulation is a part of, or NULL if the articulation does not belong to an aggregate. |
294 | |
295 | @see PxAggregate |
296 | */ |
297 | virtual PxAggregate* getAggregate() const = 0; |
298 | |
299 | virtual PxArticulationImpl* getImpl() = 0; |
300 | virtual const PxArticulationImpl* getImpl() const = 0; |
301 | |
302 | void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object. |
303 | |
304 | virtual ~PxArticulationBase() {} |
305 | |
306 | protected: |
307 | PX_INLINE PxArticulationBase(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {} |
308 | PX_INLINE PxArticulationBase(PxBaseFlags baseFlags) : PxBase(baseFlags) {} |
309 | |
310 | public: |
311 | virtual PxArticulationJointBase* createArticulationJoint(PxArticulationLink& parent, const PxTransform& parentFrame, PxArticulationLink& child, const PxTransform& childFrame) = 0; |
312 | virtual void releaseArticulationJoint(PxArticulationJointBase* joint) = 0; |
313 | }; |
314 | |
315 | #if !PX_DOXYGEN |
316 | } // namespace physx |
317 | #endif |
318 | |
319 | /** @} */ |
320 | #endif |
321 | |