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_CLOTH_FABRIC
15#define PX_PHYSICS_NX_CLOTH_FABRIC
16/** \addtogroup cloth
17 @{
18*/
19
20
21#include "common/PxBase.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28/**
29\brief Describe type of phase in cloth fabric.
30\see PxClothFabric for an explanation of concepts on phase and set.
31*/
32struct PxClothFabricPhaseType
33{
34 enum Enum
35 {
36 eINVALID, //!< invalid type
37 eVERTICAL, //!< resists stretching or compression, usually along the gravity
38 eHORIZONTAL, //!< resists stretching or compression, perpendicular to the gravity
39 eBENDING, //!< resists out-of-plane bending in angle-based formulation
40 eSHEARING, //!< resists in-plane shearing along (typically) diagonal edges,
41 eCOUNT // internal use only
42 };
43};
44
45/**
46\brief References a set of constraints that can be solved in parallel.
47\see PxClothFabric for an explanation of the concepts on phase and set.
48*/
49struct PxClothFabricPhase
50{
51 PxClothFabricPhase(PxClothFabricPhaseType::Enum type =
52 PxClothFabricPhaseType::eINVALID, PxU32 index = 0);
53
54 /**
55 \brief Type of constraints to solve.
56 */
57 PxClothFabricPhaseType::Enum phaseType;
58
59 /**
60 \brief Index of the set that contains the particle indices.
61 */
62 PxU32 setIndex;
63};
64
65PX_INLINE PxClothFabricPhase::PxClothFabricPhase(
66 PxClothFabricPhaseType::Enum type, PxU32 index)
67 : phaseType(type)
68 , setIndex(index)
69{}
70
71/**
72\brief References all the data required to create a fabric.
73\see PxPhysics.createClothFabric(), PxClothFabricCooker.getDescriptor()
74*/
75class PxClothFabricDesc
76{
77public:
78 /** \brief The number of particles needed when creating a PxCloth instance from the fabric. */
79 PxU32 nbParticles;
80
81 /** \brief The number of solver phases. */
82 PxU32 nbPhases;
83 /** \brief Array defining which constraints to solve each phase. See #PxClothFabric.getPhases(). */
84 const PxClothFabricPhase* phases;
85
86 /** \brief The number of sets in the fabric. */
87 PxU32 nbSets;
88 /** \brief Array with an index per set which points one entry beyond the last constraint of the set. See #PxClothFabric.getSets(). */
89 const PxU32* sets;
90
91 /** \brief Array of particle indices which specifies the pair of constrained vertices. See #PxClothFabric.getParticleIndices(). */
92 const PxU32* indices;
93 /** \brief Array of rest values for each constraint. See #PxClothFabric.getRestvalues(). */
94 const PxReal* restvalues;
95
96 /** \brief Size of tetherAnchors and tetherLengths arrays, needs to be multiple of nbParticles. */
97 PxU32 nbTethers;
98 /** \brief Array of particle indices specifying the tether anchors. See #PxClothFabric.getTetherAnchors(). */
99 const PxU32* tetherAnchors;
100 /** \brief Array of rest distance between tethered particle pairs. See #PxClothFabric.getTetherLengths(). */
101 const PxReal* tetherLengths;
102
103 /**
104 \brief constructor sets to default.
105 */
106 PX_INLINE PxClothFabricDesc();
107
108 /**
109 \brief (re)sets the structure to the default.
110 */
111 PX_INLINE void setToDefault();
112
113 /**
114 \brief Returns true if the descriptor is valid.
115 \return True if the current settings are valid
116 */
117 PX_INLINE bool isValid() const;
118};
119
120PX_INLINE PxClothFabricDesc::PxClothFabricDesc()
121{
122 setToDefault();
123}
124
125PX_INLINE void PxClothFabricDesc::setToDefault()
126{
127 memset(this, 0, sizeof(PxClothFabricDesc));
128}
129
130PX_INLINE bool PxClothFabricDesc::isValid() const
131{
132 return nbParticles && nbPhases && phases && restvalues && nbSets
133 && sets && indices && (!nbTethers || (tetherAnchors && tetherLengths));
134}
135
136
137/**
138\brief A cloth fabric is a structure that contains all the internal solver constraints of a cloth mesh.
139\details A fabric consists of \c phases that represent a group of internal constraints of the same type.
140Each phase references an array of \c rest-values and a \c set of particle indices.
141The data representation for the fabric has layers of indirect indices:
142\arg All particle indices for the constraints of the fabric are stored in one linear array and referenced by the sets.
143\arg Each constraint (particle index pair) has one entry in the restvalues array.
144\arg The set array holds the prefix sum of the number of constraints per set and is referenced by the phases.
145\arg A phase consists of the type of constraints, the index of the set referencing the indices.
146
147Additionally, a fabric also stores the data for the tether constraints, which limit the distances
148between two particles. The tether constraints are stored in an array, and the index of a constraint
149determines which particle is affected: element i affects particle i%N, where N is the number of particles.
150The tether anchor is the index of the other particle, and the tether length is the maximum distance that
151these two particles are allowed to be away from each other. A tether constraint is momentum conserving
152if the anchor particle has infinite mass (zero inverse weight).
153
154@see The fabric structure can be created from a mesh using PxClothFabricCreate. Alternatively, the fabric data can
155be saved into a stream (see PxClothFabricCooker.save()) and later created from the stream using PxPhysics.createClothFabric(PxInputStream&).
156*/
157class PxClothFabric : public PxBase
158{
159public:
160 /**
161 \brief Release the cloth fabric.
162 \details Releases the application's reference to the cloth fabric.
163 The fabric is destroyed when the application's reference is released and all cloth instances referencing the fabric are destroyed.
164 \see PxPhysics.createClothFabric()
165 */
166 virtual void release() = 0;
167
168 /**
169 \brief Returns number of particles.
170 \return The number of particles needed when creating a PxCloth instance from the fabric.
171 */
172 virtual PxU32 getNbParticles() const = 0;
173
174 /**
175 \brief Returns number of phases.
176 \return The number of solver phases.
177 */
178 virtual PxU32 getNbPhases() const = 0;
179
180 /**
181 \brief Returns number of rest values.
182 \return The size of the rest values array.
183 */
184 virtual PxU32 getNbRestvalues() const = 0;
185
186 /**
187 \brief Returns number of sets.
188 \return The size of the set array.
189 */
190 virtual PxU32 getNbSets() const = 0;
191
192 /**
193 \brief Get number of particle indices.
194 \return The size of the particle indices array.
195 */
196 virtual PxU32 getNbParticleIndices() const = 0;
197
198 /**
199 \brief Get number of tether constraints.
200 \return The size of the tether anchors and lengths arrays.
201 */
202 virtual PxU32 getNbTethers() const = 0;
203
204 /**
205 \brief Copies the phase array to a user specified buffer.
206 \details The phase array is a mapping of the phase index to the corresponding phase.
207 The array has the same length as getNbPhases().
208 \param [in] userPhaseBuffer Destination buffer to copy the phase data to.
209 \param [in] bufferSize Size of userPhaseBuffer, should be at least getNbPhases().
210 \return getNbPhases() if the copy was successful, 0 otherwise.
211 \note This function is potentially slow. Consider caching
212 the (static) result instead of retrieving it multiple times.
213 */
214 virtual PxU32 getPhases(PxClothFabricPhase* userPhaseBuffer, PxU32 bufferSize) const = 0;
215
216 /**
217 \brief Copies the set array to a user specified buffer.
218 \details The set array is the inclusive prefix sum of the number of constraints per set.
219 It has the same length as getNbSets().
220 \param [in] userSetBuffer Destination buffer to copy the set data to.
221 \param [in] bufferSize Size of userSetBuffer, should be at least getNbSets().
222 \return getNbSets() if the copy was successful, 0 otherwise.
223 \note Indices of the i-th set are stored at indices [i?2*set[i-1]:0, 2*set[i]) in the indices array.
224 \note This function is potentially slow. Consider caching
225 the (static) result instead of retrieving it multiple times.
226 */
227 virtual PxU32 getSets(PxU32* userSetBuffer, PxU32 bufferSize) const = 0;
228
229 /**
230 \brief Copies the particle indices array to a user specified buffer.
231 \details The particle indices array determines which particles are affected by each constraint.
232 It has the same length as getNbParticleIndices() and twice the number of constraints.
233 \param [in] userParticleIndexBuffer Destination buffer to copy the set data to.
234 \param [in] bufferSize Size of userParticleIndexBuffer, should be at least getNbParticleIndices().
235 \return getNbParticleIndices() if the copy was successful, 0 otherwise.
236 \note This function is potentially slow. Consider caching
237 the (static) result instead of retrieving it multiple times.
238 */
239 virtual PxU32 getParticleIndices(PxU32* userParticleIndexBuffer, PxU32 bufferSize) const = 0;
240
241 /**
242 \brief Copies the rest values array to a user specified buffer.
243 \details The rest values array holds the target value of the constraint in rest state,
244 for example edge length for stretch constraints.
245 It stores one value per constraint, so its length is half of getNbParticleIndices(), and
246 it has the same length as getNbRestvalues(). The rest-values are stored in the order
247 they are (indirectly) referenced by the phases.
248 \param [in] userRestvalueBuffer Destination buffer to copy the set data to.
249 \param [in] bufferSize Size of userRestvalueBuffer, should be at least getNbRestvalues().
250 \return getNbRestvalues() if the copy was successful, 0 otherwise.
251 \note This function is potentially slow. Between calling scaleRestlengths(),
252 consider caching the result instead of retrieving it multiple times.
253 */
254 virtual PxU32 getRestvalues(PxReal* userRestvalueBuffer, PxU32 bufferSize) const = 0;
255
256 /**
257 \brief Copies the tether anchors array to a user specified buffer.
258 \details The tether anchors array stores for each particle the index of
259 another particle from which it cannot move further away than specified by the
260 tether lengths array.
261 \param [in] userAnchorBuffer Destination buffer to copy the set data to.
262 \param [in] bufferSize Size of userAnchorBuffer, should be at least getNbTethers().
263 \return getNbTethers() if the copy was successful, 0 otherwise.
264 \note This function is potentially slow, consider caching the
265 result instead of retrieving the data multiple times.
266 \see getTetherLengths, getNbTethers
267 */
268 virtual PxU32 getTetherAnchors(PxU32* userAnchorBuffer, PxU32 bufferSize) const = 0;
269
270 /**
271 \brief Copies the tether lengths array to a user specified buffer.
272 \details The tether lengths array stores for each particle how far it is
273 allowed to move away from the particle specified by the tether anchor array.
274 \param [in] userLengthBuffer Destination buffer to copy the set data to.
275 \param [in] bufferSize Size of userLengthBuffer, should be at least getNbTethers().
276 \return getNbTethers() if the copy was successful, 0 otherwise.
277 \note This function is potentially slow. Between calling scaleRestlengths(),
278 consider caching the result instead of retrieving it multiple times.
279 \see getTetherAnchors, getNbTethers
280 */
281 virtual PxU32 getTetherLengths(PxReal* userLengthBuffer, PxU32 bufferSize) const = 0;
282
283 /**
284 \deprecated
285 \brief Returns the type of a phase.
286 \param [in] phaseIndex The index of the phase to return the type for.
287 \return The phase type as PxClothFabricPhaseType::Enum.
288 \note If phase index is invalid, PxClothFabricPhaseType::eINVALID is returned.
289 */
290 PX_DEPRECATED virtual PxClothFabricPhaseType::Enum getPhaseType(PxU32 phaseIndex) const = 0;
291
292 /**
293 \brief Scale all rest values of length dependent constraints.
294 \param[in] scale The scale factor to multiply each rest value with.
295 */
296 virtual void scaleRestlengths(PxReal scale) = 0;
297
298 /**
299 \brief Reference count of the cloth instance
300 \details At creation, the reference count of the fabric is 1. Every cloth instance referencing this fabric increments the
301 count by 1. When the reference count reaches 0, and only then, the fabric gets released automatically.
302 \see PxCloth
303 */
304 virtual PxU32 getReferenceCount() const = 0;
305
306 virtual const char* getConcreteTypeName() const { return "PxClothFabric"; }
307
308protected:
309
310 PX_INLINE PxClothFabric(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {}
311 PX_INLINE PxClothFabric(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
312 virtual ~PxClothFabric() {}
313 virtual bool isKindOf(const char* name) const { return !strcmp("PxClothFabric", name) || PxBase::isKindOf(name); }
314};
315
316#ifndef PX_DOXYGEN
317} // namespace physx
318#endif
319
320/** @} */
321#endif
322