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#ifndef PX_D6JOINT_CREATE_H
31#define PX_D6JOINT_CREATE_H
32
33#include "common/PxPhysXCommonConfig.h"
34
35/** \addtogroup extensions
36 @{
37*/
38
39#if !PX_DOXYGEN
40namespace physx
41{
42#endif
43
44class PxPhysics;
45class PxRigidActor;
46class PxJoint;
47
48/**
49 \brief Helper function to create a fixed joint, using either a PxD6Joint or PxFixedJoint.
50
51 For fixed joints it is important that the joint frames have the same orientation. This helper function uses an identity rotation for both.
52 It is also important that the joint frames have an equivalent position in world space. The function does not check this, so it is up to users
53 to ensure that this is the case.
54
55 \param[in] physics The physics SDK
56 \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
57 \param[in] localPos0 The position of the joint relative to actor0
58 \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
59 \param[in] localPos1 The position of the joint relative to actor1
60 \param[in] useD6 True to use a PxD6Joint, false to use a PxFixedJoint;
61
62 \return The created joint.
63
64 @see PxD6Joint PxFixedJoint
65*/
66PxJoint* PxD6JointCreate_Fixed(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, bool useD6);
67
68/**
69 \brief Helper function to create a distance joint, using either a PxD6Joint or PxDistanceJoint.
70
71 This helper function only supports a maximum distance constraint, because PxD6Joint does not support a minimum distance constraint (contrary
72 to PxDistanceJoint).
73
74 The distance is computed between the joint frames' world-space positions. The joint frames' orientations are irrelevant here so the function
75 sets them to identity.
76
77 \param[in] physics The physics SDK
78 \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
79 \param[in] localPos0 The position of the joint relative to actor0
80 \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
81 \param[in] localPos1 The position of the joint relative to actor1
82 \param[in] maxDist The maximum allowed distance
83 \param[in] useD6 True to use a PxD6Joint, false to use a PxDistanceJoint;
84
85 \return The created joint.
86
87 @see PxD6Joint PxDistanceJoint
88*/
89PxJoint* PxD6JointCreate_Distance(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, float maxDist, bool useD6);
90
91/**
92 \brief Helper function to create a prismatic joint, using either a PxD6Joint or PxPrismaticJoint.
93
94 This function enforces that the joint frames have the same orientation, which is a local frame whose X is the desired translation axis.
95 This orientation is computed by the function, so users only have to define the desired translation axis (typically 1;0;0 or 0;1;0 or 0;0;1).
96
97 The translation can be limited. Limits are enforced if minLimit<maxLimit. If minLimit=maxLimit the axis is locked. If minLimit>maxLimit the
98 limits are not enforced and the axis is free. The limit values are computed relative to the position of actor0's joint frame.
99
100 The function creates hard limits, and uses PhysX's default contact distance parameter.
101
102 \param[in] physics The physics SDK
103 \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
104 \param[in] localPos0 The position of the joint relative to actor0
105 \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
106 \param[in] localPos1 The position of the joint relative to actor1
107 \param[in] axis The axis along which objects are allowed to move, expressed in the actors' local space
108 \param[in] minLimit The minimum allowed position along the axis
109 \param[in] maxLimit The maximum allowed position along the axis
110 \param[in] useD6 True to use a PxD6Joint, false to use a PxPrismaticJoint;
111
112 \return The created joint.
113
114 @see PxD6Joint PxPrismaticJoint
115*/
116PxJoint* PxD6JointCreate_Prismatic(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, const PxVec3& axis, float minLimit, float maxLimit, bool useD6);
117
118/**
119 \brief Helper function to create a revolute joint, using either a PxD6Joint or PxRevoluteJoint.
120
121 This function enforces that the joint frames have the same orientation, which is a local frame whose X is the desired rotation axis.
122 This orientation is computed by the function, so users only have to define the desired rotation axis (typically 1;0;0 or 0;1;0 or 0;0;1).
123
124 The rotation can be limited. Limits are enforced if minLimit<maxLimit. If minLimit=maxLimit the axis is locked. If minLimit>maxLimit the
125 limits are not enforced and the axis is free. The limit values are computed relative to the rotation of actor0's joint frame.
126
127 The function creates hard limits, and uses PhysX's default contact distance parameter.
128
129 Limits are expressed in radians. Allowed range is ]-2*PI;+2*PI[
130
131 \param[in] physics The physics SDK
132 \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
133 \param[in] localPos0 The position of the joint relative to actor0
134 \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
135 \param[in] localPos1 The position of the joint relative to actor1
136 \param[in] axis The axis around which objects are allowed to move, expressed in the actors' local space
137 \param[in] minLimit The minimum allowed rotation along the axis
138 \param[in] maxLimit The maximum allowed rotation along the axis
139 \param[in] useD6 True to use a PxD6Joint, false to use a PxRevoluteJoint;
140
141 \return The created joint.
142
143 @see PxD6Joint PxRevoluteJoint
144*/
145PxJoint* PxD6JointCreate_Revolute(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, const PxVec3& axis, float minLimit, float maxLimit, bool useD6);
146
147/**
148 \brief Helper function to create a spherical joint, using either a PxD6Joint or PxSphericalJoint.
149
150 This function supports a cone limit shape, defined by a cone axis and two angular limit values.
151
152 This function enforces that the joint frames have the same orientation, which is a local frame whose X is the desired cone axis.
153 This orientation is computed by the function, so users only have to define the desired cone axis (typically 1;0;0 or 0;1;0 or 0;0;1).
154
155 The rotations can be limited. Limits are enforced if limit1>0 and limit2>0. Otherwise the motion is free. The limit values define an ellipse,
156 which is the cross-section of the cone limit shape.
157
158 The function creates hard limits, and uses PhysX's default contact distance parameter.
159
160 Limits are expressed in radians. Allowed range is ]0;PI[. Limits are symmetric around the cone axis.
161
162 The cone axis is equivalent to the twist axis for the D6 joint. The twist motion is not limited.
163
164 \param[in] physics The physics SDK
165 \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
166 \param[in] localPos0 The position of the joint relative to actor0
167 \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
168 \param[in] localPos1 The position of the joint relative to actor1
169 \param[in] axis The cone axis, expressed in the actors' local space
170 \param[in] limit1 Max angular limit for the ellipse along the joint frame's second axis (first axis = cone axis)
171 \param[in] limit2 Max angular limit for the ellipse along the joint frame's third axis (first axis = cone axis)
172 \param[in] useD6 True to use a PxD6Joint, false to use a PxSphericalJoint;
173
174 \return The created joint.
175
176 @see PxD6Joint PxSphericalJoint
177*/
178PxJoint* PxD6JointCreate_Spherical(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, const PxVec3& axis, float limit1, float limit2, bool useD6);
179
180/**
181 \brief Helper function to create a spherical joint, using either a PxD6Joint or PxSphericalJoint.
182
183 This function supports a cone limit shape, defined by two pairs of angular limit values. This can be used to create an asymmetric cone. If the
184 angular limit values are symmetric (i.e. minLimit1=-maxLimit1 and minLimit2=-maxLimit2) then the cone axis is the X axis in actor0's space.
185 If the limits are not symmetric, the function rotates the cone axis accordingly so that limits remain symmetric for PhysX. If this happens,
186 the initial joint frames will be different for both actors. By default minLimit1/maxLimit1 are limits around the joint's Y axis, and
187 minLimit2/maxLimit2 are limits around the joint's Z axis.
188
189 The function creates hard limits, and uses PhysX's default contact distance parameter.
190
191 Limits are expressed in radians. Allowed range is ]-PI;PI[.
192
193 The cone axis is equivalent to the twist axis for the D6 joint. The twist motion is not limited.
194
195 The returned apiroty and apirotz values can later be added to retrieved Y and Z swing angle values (from the joint), to remap
196 angle values to the given input range.
197
198 \param[out] apiroty Amount of rotation around Y used to setup actor0's joint frame
199 \param[out] apirotz Amount of rotation around Z used to setup actor0's joint frame
200 \param[in] physics The physics SDK
201 \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
202 \param[in] localPos0 The position of the joint relative to actor0
203 \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
204 \param[in] localPos1 The position of the joint relative to actor1
205 \param[in] minLimit1 Min angular limit along the joint frame's second axis (first axis = cone axis)
206 \param[in] maxLimit1 Max angular limit along the joint frame's second axis (first axis = cone axis)
207 \param[in] minLimit2 Min angular limit along the joint frame's third axis (first axis = cone axis)
208 \param[in] maxLimit2 Max angular limit along the joint frame's third axis (first axis = cone axis)
209 \param[in] useD6 True to use a PxD6Joint, false to use a PxSphericalJoint;
210
211 \return The created joint.
212
213 @see PxD6Joint PxSphericalJoint
214*/
215PxJoint* PxD6JointCreate_GenericCone(float& apiroty, float& apirotz, PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, float minLimit1, float maxLimit1, float minLimit2, float maxLimit2, bool useD6);
216
217
218/**
219 \brief Helper function to create a D6 joint with pyramidal swing limits.
220
221 This function supports a pyramid limit shape, defined by two pairs of angular limit values. This can be used to create an asymmetric pyramid. If the
222 angular limit values are symmetric (i.e. minLimit1=-maxLimit1 and minLimit2=-maxLimit2) then the pyramid axis is the X axis in actor0's space.
223 By default minLimit1/maxLimit1 are limits around the joint's Y axis, and minLimit2/maxLimit2 are limits around the joint's Z axis.
224
225 The function creates hard limits, and uses PhysX's default contact distance parameter.
226
227 Limits are expressed in radians. Allowed range is ]-PI;PI[.
228
229 The pyramid axis is equivalent to the twist axis for the D6 joint. The twist motion is not limited.
230
231 \param[in] physics The physics SDK
232 \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
233 \param[in] localPos0 The position of the joint relative to actor0
234 \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
235 \param[in] localPos1 The position of the joint relative to actor1
236 \param[in] axis The pyramid axis, expressed in the actors' local space
237 \param[in] minLimit1 Min angular limit along the joint frame's second axis (first axis = pyramid axis)
238 \param[in] maxLimit1 Max angular limit along the joint frame's second axis (first axis = pyramid axis)
239 \param[in] minLimit2 Min angular limit along the joint frame's third axis (first axis = pyramid axis)
240 \param[in] maxLimit2 Max angular limit along the joint frame's third axis (first axis = pyramid axis)
241
242 \return The created joint.
243
244 @see PxD6Joint
245*/
246PxJoint* PxD6JointCreate_Pyramid(PxPhysics& physics, PxRigidActor* actor0, const PxVec3& localPos0, PxRigidActor* actor1, const PxVec3& localPos1, const PxVec3& axis,
247 float minLimit1, float maxLimit1, float minLimit2, float maxLimit2);
248
249
250#if !PX_DOXYGEN
251} // namespace physx
252#endif
253
254/** @} */
255#endif
256

source code of qtquick3dphysics/src/3rdparty/PhysX/include/extensions/PxD6JointCreate.h