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_DISTANCEJOINT_H
15#define PX_DISTANCEJOINT_H
16/** \addtogroup extensions
17 @{
18*/
19
20#include "extensions/PxJoint.h"
21
22#ifndef PX_DOXYGEN
23namespace physx
24{
25#endif
26
27class PxDistanceJoint;
28
29/**
30\brief Create a distance Joint.
31
32 \param[in] physics the physics SDK
33 \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
34 \param[in] localFrame0 the position and orientation of the joint relative to actor0
35 \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
36 \param[in] localFrame1 the position and orientation of the joint relative to actor1
37
38@see PxDistanceJoint
39*/
40
41PxDistanceJoint* PxDistanceJointCreate(PxPhysics& physics,
42 PxRigidActor* actor0, const PxTransform& localFrame0,
43 PxRigidActor* actor1, const PxTransform& localFrame1);
44
45
46/**
47\brief flags for configuring the drive of a PxDistanceJoint
48
49@see PxDistanceJoint
50*/
51
52struct PxDistanceJointFlag
53{
54 enum Enum
55 {
56 eMAX_DISTANCE_ENABLED = 1<<1,
57 eMIN_DISTANCE_ENABLED = 1<<2,
58 eSPRING_ENABLED = 1<<3
59 };
60};
61
62typedef PxFlags<PxDistanceJointFlag::Enum, PxU16> PxDistanceJointFlags;
63PX_FLAGS_OPERATORS(PxDistanceJointFlag::Enum, PxU16)
64
65/**
66\brief a joint that maintains an upper or lower bound (or both) on the distance between two points on different objects
67
68@see PxDistanceJointCreate PxJoint
69*/
70class PxDistanceJoint : public PxJoint
71{
72public:
73
74
75 /**
76 \brief Return the current distance of the joint
77 */
78
79 virtual PxReal getDistance() const = 0;
80
81 /**
82 \brief Set the allowed minimum distance for the joint.
83
84 The minimum distance must be no more than the maximum distance
85
86 <b>Default</b> 0.0f
87 <b>Range</b> [0, PX_MAX_F32)
88
89 \param[in] distance the minimum distance
90
91 @see PxDistanceJoint::minDistance, PxDistanceJointFlag::eMIN_DISTANCE_ENABLED getMinDistance()
92 */
93
94 virtual void setMinDistance(PxReal distance) = 0;
95
96 /**
97 \brief Get the allowed minimum distance for the joint.
98
99 \return the allowed minimum distance
100
101 @see PxDistanceJoint::minDistance, PxDistanceJointFlag::eMIN_DISTANCE_ENABLED setMinDistance()
102 */
103
104 virtual PxReal getMinDistance() const = 0;
105
106
107 /**
108 \brief Set the allowed maximum distance for the joint.
109
110 The maximum distance must be no less than the minimum distance.
111
112 <b>Default</b> 0.0f
113 <b>Range</b> [0, PX_MAX_F32)
114
115 \param[in] distance the maximum distance
116
117 @see PxDistanceJoint::maxDistance, PxDistanceJointFlag::eMAX_DISTANCE_ENABLED getMinDistance()
118 */
119
120 virtual void setMaxDistance(PxReal distance) = 0;
121
122 /**
123 \brief Get the allowed maximum distance for the joint.
124
125 \return the allowed maximum distance
126
127 @see PxDistanceJoint::maxDistance, PxDistanceJointFlag::eMAX_DISTANCE_ENABLED setMaxDistance()
128 */
129
130 virtual PxReal getMaxDistance() const = 0;
131
132
133 /**
134 \brief Set the error tolerance of the joint.
135
136 \param[in] tolerance the distance beyond the allowed range at which the joint becomes active
137
138 @see PxDistanceJoint::tolerance, getTolerance()
139 */
140
141 virtual void setTolerance(PxReal tolerance) = 0;
142
143
144 /**
145 \brief Get the error tolerance of the joint.
146
147 \brief the distance beyond the joint's [min, max] range before the joint becomes active.
148
149 <b>Default</b> 0.25f * PxTolerancesScale::length
150 <b>Range</b> (0, PX_MAX_F32)
151
152 This value should be used to ensure that if the minimum distance is zero and the
153 spring function is in use, the rest length of the spring is non-zero.
154
155 @see PxDistanceJoint::tolerance, setTolerance()
156 */
157 virtual PxReal getTolerance() const = 0;
158
159 /**
160 \brief Set the strength of the joint spring.
161
162 The spring is used if enabled, and the distance exceeds the range [min-error, max+error].
163
164 <b>Default</b> 0.0f
165 <b>Range</b> [0, PX_MAX_F32)
166
167 \param[in] stiffness the spring strength of the joint
168
169 @see PxDistanceJointFlag::eSPRING_ENABLED getStiffness()
170 */
171
172 virtual void setStiffness(PxReal stiffness) = 0;
173
174 /**
175 \brief Get the strength of the joint spring.
176
177 \return stiffness the spring strength of the joint
178
179 @see PxDistanceJointFlag::eSPRING_ENABLED setStiffness()
180 */
181
182 virtual PxReal getStiffness() const = 0;
183
184
185 /**
186 \brief Set the damping of the joint spring.
187
188 The spring is used if enabled, and the distance exceeds the range [min-error, max+error].
189
190 <b>Default</b> 0.0f
191 <b>Range</b> [0, PX_MAX_F32)
192
193 \param[in] damping the degree of damping of the joint spring of the joint
194
195 @see PxDistanceJointFlag::eSPRING_ENABLED setDamping()
196 */
197
198 virtual void setDamping(PxReal damping) = 0;
199
200
201 /**
202 \brief Get the damping of the joint spring.
203
204 \return the degree of damping of the joint spring of the joint
205
206 @see PxDistanceJointFlag::eSPRING_ENABLED setDamping()
207 */
208
209 virtual PxReal getDamping() const = 0;
210
211 /**
212 \brief Set the flags specific to the Distance Joint.
213
214 <b>Default</b> PxDistanceJointFlag::eMAX_DISTANCE_ENABLED
215
216 \param[in] flags The joint flags.
217
218 @see PxDistanceJointFlag setFlag() getFlags()
219 */
220
221 virtual void setDistanceJointFlags(PxDistanceJointFlags flags) = 0;
222
223
224 /**
225 \brief Set a single flag specific to a Distance Joint to true or false.
226
227 \param[in] flag The flag to set or clear.
228 \param[in] value the value to which to set the flag
229
230 @see PxDistanceJointFlag, getFlags() setFlags()
231 */
232
233 virtual void setDistanceJointFlag(PxDistanceJointFlag::Enum flag, bool value) = 0;
234
235 /**
236 \brief Get the flags specific to the Distance Joint.
237
238 \return the joint flags
239
240 @see PxDistanceJoint::flags, PxDistanceJointFlag setFlag() setFlags()
241 */
242
243 virtual PxDistanceJointFlags getDistanceJointFlags(void) const = 0;
244
245 /**
246 \brief Returns string name of PxDistanceJoint, used for serialization
247 */
248 virtual const char* getConcreteTypeName() const { return "PxDistanceJoint"; }
249
250protected:
251
252 //serialization
253
254 /**
255 \brief Constructor
256 */
257 PX_INLINE PxDistanceJoint(PxType concreteType, PxBaseFlags baseFlags) : PxJoint(concreteType, baseFlags) {}
258
259 /**
260 \brief Deserialization constructor
261 */
262 PX_INLINE PxDistanceJoint(PxBaseFlags baseFlags) : PxJoint(baseFlags) {}
263
264 /**
265 \brief Returns whether a given type name matches with the type of this instance
266 */
267 virtual bool isKindOf(const char* name) const { return !strcmp("PxDistanceJoint", name) || PxJoint::isKindOf(name); }
268
269 //~serialization
270};
271
272#ifndef PX_DOXYGEN
273} // namespace physx
274#endif
275
276/** @} */
277#endif
278