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_REVOLUTEJOINT_H
15#define PX_REVOLUTEJOINT_H
16/** \addtogroup extensions
17 @{
18*/
19
20#include "extensions/PxJoint.h"
21#include "extensions/PxJointLimit.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28class PxRevoluteJoint;
29
30/**
31\brief Create a revolute joint.
32
33 \param[in] physics the physics SDK
34 \param[in] actor0 an actor to which the joint is attached. NULL may be used to attach the joint to a specific point in the world frame
35 \param[in] localFrame0 the position and orientation of the joint relative to actor0
36 \param[in] actor1 an actor to which the joint is attached. NULL may be used to attach the joint to a specific point in the world frame
37 \param[in] localFrame1 the position and orientation of the joint relative to actor1
38
39@see PxRevoluteJoint
40*/
41
42PxRevoluteJoint* PxRevoluteJointCreate(PxPhysics& physics,
43 PxRigidActor* actor0, const PxTransform& localFrame0,
44 PxRigidActor* actor1, const PxTransform& localFrame1);
45
46
47/**
48\brief Flags specific to the Revolute Joint.
49
50@see PxRevoluteJoint
51*/
52
53struct PxRevoluteJointFlag
54{
55 enum Enum
56 {
57 eLIMIT_ENABLED = 1<<0, //< enable the limit
58 eDRIVE_ENABLED = 1<<1, //< enable the drive
59 eDRIVE_FREESPIN = 1<<2 //< if the existing velocity is beyond the drive velocity, do not add force
60 };
61};
62
63typedef PxFlags<PxRevoluteJointFlag::Enum, PxU16> PxRevoluteJointFlags;
64PX_FLAGS_OPERATORS(PxRevoluteJointFlag::Enum, PxU16)
65
66
67/**
68
69\brief A joint which behaves in a similar way to a hinge or axle.
70
71 A hinge joint removes all but a single rotational degree of freedom from two objects.
72 The axis along which the two bodies may rotate is specified with a point and a direction
73 vector.
74
75 The position of the hinge on each body is specified by the origin of the body's joint frame.
76 The axis of the hinge is specified as the direction of the x-axis in the body's joint frame.
77
78 \image html revoluteJoint.png
79
80 A revolute joint can be given a motor, so that it can apply a force to rotate the attached actors.
81 It may also be given a limit, to restrict the revolute motion to within a certain range. In
82 addition, the bodies may be projected together if the distance or angle between them exceeds
83 a given threshold.
84
85 Projection, drive and limits are activated by setting the appropriate flags on the joint.
86
87 @see PxRevoluteJointCreate() PxJoint
88*/
89
90class PxRevoluteJoint : public PxJoint
91{
92public:
93
94 /**
95 \brief return the angle of the joint, in the range (-Pi, Pi]
96 */
97 virtual PxReal getAngle() const = 0;
98
99
100 /**
101 \brief return the velocity of the joint
102 */
103 virtual PxReal getVelocity() const = 0;
104
105 /**
106 \brief set the joint limit parameters.
107
108 The limit is activated using the flag PxRevoluteJointFlag::eLIMIT_ENABLED
109
110 The limit angle range is (-2*PI, 2*PI) and the extent of the limit must be strictly less than 2*PI
111
112 \param[in] limits The joint limit parameters.
113
114
115 @see PxJointAngularLimitPair getLimit()
116 */
117
118 virtual void setLimit(const PxJointAngularLimitPair& limits) = 0;
119
120 /**
121 \brief get the joint limit parameters.
122
123 \return the joint limit parameters
124
125 @see PxJointAngularLimitPair setLimit()
126 */
127 virtual PxJointAngularLimitPair getLimit() const = 0;
128
129
130
131 /**
132 \brief set the target velocity for the drive model.
133
134 The motor will only be able to reach this velocity if the maxForce is sufficiently large.
135 If the joint is spinning faster than this velocity, the motor will actually try to brake
136 (see PxRevoluteJointFlag::eDRIVE_FREESPIN.)
137
138 If you set this to infinity then the motor will keep speeding up, unless there is some sort
139 of resistance on the attached bodies. The sign of this variable determines the rotation direction,
140 with positive values going the same way as positive joint angles.
141
142 \param[in] velocity the drive target velocity
143
144 <b>Range:</b> [0, PX_MAX_F32)<br>
145 <b>Default:</b> 0.0
146
147 @see PxRevoluteFlags::eDRIVE_FREESPIN
148 */
149
150 virtual void setDriveVelocity(PxReal velocity) = 0;
151
152 /**
153 \brief gets the target velocity for the drive model.
154
155 \return the drive target velocity
156
157 @see setDriveVelocity()
158 */
159 virtual PxReal getDriveVelocity() const = 0;
160
161
162 /**
163 \brief sets the maximum torque the drive can exert.
164
165 Setting this to a very large value if velTarget is also very large may cause unexpected results.
166
167 The value set here may be used either as an impulse limit or a force limit, depending on the flag PxConstraintFlag::eDRIVE_LIMITS_ARE_FORCES
168
169 <b>Range:</b> [0, PX_MAX_F32)<br>
170 <b>Default:</b> PX_MAX_F32
171
172 @see setDriveVelocity()
173 */
174 virtual void setDriveForceLimit(PxReal limit) = 0;
175
176 /**
177 \brief gets the maximum torque the drive can exert.
178
179 \return the torque limit
180
181 @see setDriveVelocity()
182 */
183 virtual PxReal getDriveForceLimit() const = 0;
184
185
186 /**
187 \brief sets the gear ratio for the drive.
188
189 When setting up the drive constraint, the velocity of the first actor is scaled by this value, and its response to drive torque is scaled down.
190 So if the drive target velocity is zero, the second actor will be driven to the velocity of the first scaled by the gear ratio
191
192 <b>Range:</b> [0, PX_MAX_F32)<br>
193 <b>Default:</b> 1.0
194
195 \param[in] ratio the drive gear ratio
196
197 @see getDriveGearRatio()
198 */
199 virtual void setDriveGearRatio(PxReal ratio) = 0;
200
201 /**
202 \brief gets the gear ratio.
203
204 \return the drive gear ratio
205
206 @see setDriveGearRatio()
207 */
208 virtual PxReal getDriveGearRatio() const = 0;
209
210
211 /**
212 \brief sets the flags specific to the Revolute Joint.
213
214 <b>Default</b> PxRevoluteJointFlags(0)
215
216 \param[in] flags The joint flags.
217
218 @see PxRevoluteJointFlag setFlag() getFlags()
219 */
220
221 virtual void setRevoluteJointFlags(PxRevoluteJointFlags flags) = 0;
222
223 /**
224 \brief sets a single flag specific to a Revolute Joint.
225
226 \param[in] flag The flag to set or clear.
227 \param[in] value the value to which to set the flag
228
229 @see PxRevoluteJointFlag, getFlags() setFlags()
230 */
231
232 virtual void setRevoluteJointFlag(PxRevoluteJointFlag::Enum flag, bool value) = 0;
233
234 /**
235 \brief gets the flags specific to the Revolute Joint.
236
237 \return the joint flags
238
239 @see PxRevoluteJoint::flags, PxRevoluteJointFlag setFlag() setFlags()
240 */
241
242 virtual PxRevoluteJointFlags getRevoluteJointFlags(void) const = 0;
243
244 /**
245 \brief Set the linear tolerance threshold for projection. Projection is enabled if PxConstraintFlag::ePROJECTION
246 is set for the joint.
247
248 If the joint separates by more than this distance along its locked degrees of freedom, the solver
249 will move the bodies to close the distance.
250
251 Setting a very small tolerance may result in simulation jitter or other artifacts.
252
253 Sometimes it is not possible to project (for example when the joints form a cycle).
254
255 <b>Range:</b> [0, PX_MAX_F32)<br>
256 <b>Default:</b> 1e10f
257
258 \param[in] tolerance the linear tolerance threshold
259
260 @see getProjectionLinearTolerance() PxJoint::setConstraintFlags() PxConstraintFlag::ePROJECTION
261 */
262
263 virtual void setProjectionLinearTolerance(PxReal tolerance) = 0;
264
265
266 /**
267 \brief Get the linear tolerance threshold for projection.
268
269 \return the linear tolerance threshold
270
271 @see setProjectionLinearTolerance()
272 */
273
274 virtual PxReal getProjectionLinearTolerance() const = 0;
275
276 /**
277 \brief Set the angular tolerance threshold for projection. Projection is enabled if
278 PxConstraintFlag::ePROJECTION is set for the joint.
279
280 If the joint deviates by more than this angle around its locked angular degrees of freedom,
281 the solver will move the bodies to close the angle.
282
283 Setting a very small tolerance may result in simulation jitter or other artifacts.
284
285 Sometimes it is not possible to project (for example when the joints form a cycle).
286
287 <b>Range:</b> [0,Pi] <br>
288 <b>Default:</b> Pi
289
290 \param[in] tolerance the angular tolerance threshold in radians
291
292 @see getProjectionAngularTolerance() PxJoint::setConstraintFlag() PxConstraintFlag::ePROJECTION
293 */
294
295 virtual void setProjectionAngularTolerance(PxReal tolerance) = 0;
296
297 /**
298 \brief gets the angular tolerance threshold for projection.
299
300 \return the angular tolerance threshold in radians
301
302 @see setProjectionAngularTolerance()
303 */
304
305 virtual PxReal getProjectionAngularTolerance() const = 0;
306
307 /**
308 \brief Returns string name of PxRevoluteJoint, used for serialization
309 */
310 virtual const char* getConcreteTypeName() const { return "PxRevoluteJoint"; }
311
312protected:
313
314 //serialization
315
316 /**
317 \brief Constructor
318 */
319 PX_INLINE PxRevoluteJoint(PxType concreteType, PxBaseFlags baseFlags) : PxJoint(concreteType, baseFlags) {}
320
321 /**
322 \brief Deserialization constructor
323 */
324 PX_INLINE PxRevoluteJoint(PxBaseFlags baseFlags) : PxJoint(baseFlags) {}
325
326 /**
327 \brief Returns whether a given type name matches with the type of this instance
328 */
329 virtual bool isKindOf(const char* name) const { return !strcmp("PxRevoluteJoint", name) || PxJoint::isKindOf(name); }
330
331 //~serialization
332};
333
334#ifndef PX_DOXYGEN
335} // namespace physx
336#endif
337
338/** @} */
339#endif
340