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
15#define PX_PHYSICS_NX_CLOTH
16/** \addtogroup cloth
17@{
18*/
19
20#include "PxPhysXConfig.h"
21#include "PxActor.h"
22#include "PxLockedData.h"
23#include "PxFiltering.h"
24#include "cloth/PxClothFabric.h"
25#include "cloth/PxClothTypes.h"
26#include "cloth/PxClothCollisionData.h"
27
28#ifndef PX_DOXYGEN
29namespace physx
30{
31#endif
32
33class PxScene;
34
35/**
36\brief Solver configuration parameters for the vertical and horizontal stretch phase types.
37\see PxCloth.setStretchConfig()
38\see PxClothFabric for information on actual phase data in cloth fabric
39*/
40struct PxClothStretchConfig
41{
42 /**
43 \brief Stiffness of the stretch constraints.
44 \details Defines for the constraint edges how much of the distance error between current length
45 and rest length to correct per stiffness period (see PxCloth::setStiffnessFrequency).
46 A value of 0 means no correction, a value of 1 corrects to rest length.
47 The default is 1.
48 */
49 PxReal stiffness;
50
51 /**
52 \brief Stiffness multiplier of the cloth solver under certain limits.
53 \details The valid range is [0, 1], the default multiplier is 1.0.
54 \see stretchLimit
55 */
56 PxReal stiffnessMultiplier;
57
58 /**
59 \brief Limit to control when stiffnessMultiplier has to be applied.
60 \details stiffnessMultiplier multiplies the normal stiffness if the ratio
61 between constraint edge length and rest length lies in the [compressionLimit, 1] range.
62 The valid range is [0, 1], the default limit is 1.0.
63 */
64 PxReal compressionLimit;
65
66 /**
67 \brief Limit to control when stiffnessMultiplier has to be applied.
68 \details stiffnessMultiplier multiplies the normal stiffness if the ratio
69 between constraint edge length and rest length lies in the [1, stretchLimit] range.
70 The valid range is [1, PX_MAX_F32), the default limit is 1.0.
71 */
72 PxReal stretchLimit;
73
74 /**
75 \brief Constructor initializes to default values.
76 */
77 PX_INLINE PxClothStretchConfig( PxReal stiffness_=1.0f,
78 PxReal stiffnessMultiplier_=1.0f, PxReal compressionLimit_=1.0f, PxReal stretchLimit_=1.0f)
79 : stiffness(stiffness_)
80 , stiffnessMultiplier(stiffnessMultiplier_)
81 , compressionLimit(compressionLimit_)
82 , stretchLimit(stretchLimit_)
83 {}
84};
85
86/**
87\brief Solver configuration parameters for the tether phases.
88\see PxCloth.setTetherConfig()
89\see PxClothFabric for information on actual tether constraints in cloth fabric.
90*/
91struct PxClothTetherConfig
92{
93 /**
94 \brief Stiffness of the tether constraints.
95 \details Defines for the tether constraints how much of the error between current
96 distance and tether length to correct per stiffness period (see PxCloth::setStiffnessFrequency).
97 A value of 0 means no correction, a value of 1 corrects to rest length.
98 The default stiffness is 1.0.
99 */
100 PxReal stiffness;
101
102 /**
103 \brief Scale of tether lengths when applying tether constraints.
104 \details The limit distance of a tether constraint is computed
105 as the product of stretchLimit and the tether length.
106 The default limit is 1.0.
107 */
108 PxReal stretchLimit;
109
110 /**
111 \brief Constructor sets to default.
112 */
113 PX_INLINE PxClothTetherConfig(PxReal stiffness_ = 1.0f, PxReal stretchLimit_ = 1.0f)
114 : stiffness(stiffness_), stretchLimit(stretchLimit_)
115 {}
116};
117
118/**
119\brief Solver configuration parameters for the tether phases.
120\see PxCloth.setTetherConfig()
121\see PxClothFabric for information on actual tether constraints in cloth fabric.
122*/
123struct PxClothMotionConstraintConfig
124{
125 /**
126 \brief Scale of motion constraint radii.
127 \details The motion constraint radius is computed
128 as constraint.radius * config.scale + config.bias.
129 The default scale is 1.0.
130 */
131 PxReal scale;
132
133 /**
134 \brief Bias of motion constraint radii.
135 \details The motion constraint radius is computed
136 as constraint.radius * config.scale + config.bias.
137 The default bias is 0.0.
138 */
139 PxReal bias;
140
141 /**
142 \brief Stiffness of the motion constraints.
143 \details Defines for the motion constraints how much of the error between current
144 distance and constraint radius to correct per stiffness period (see PxCloth::setStiffnessFrequency).
145 A value of 0 means no correction, a value of 1 corrects to rest length.
146 The default stiffness is 1.
147 */
148 PxReal stiffness;
149
150 /**
151 \brief Constructor sets to default.
152 */
153 PX_INLINE PxClothMotionConstraintConfig(PxReal radiiScale = 1.0f, PxReal radiiBias = 0.0f, PxReal consStiffness = 1.0f)
154 : scale(radiiScale), bias(radiiBias), stiffness(consStiffness)
155 {}
156};
157
158/**
159\brief Set of connected particles tailored towards simulating character cloth.
160\details A cloth object consists of the following components:
161\arg A set of particles that sample the cloth. The sampling does not need to be regular.
162Particles are simulated in local space, which allows tuning the effect of changes to the global pose on the particles.
163\arg Distance, bending, shearing, and tether constraints between particles.
164These are stored in a PxClothFabric instance which can be shared across cloth instances.
165\arg Spheres, capsules, convexes, and triangle collision shapes.
166These shapes are all treated separately to the main PhysX rigid body scene.
167\arg Virtual particles can be used to improve collision at a finer scale than the cloth sampling.
168\arg Motion and separation constraints are used to limit the particle movement within or outside of a sphere.
169
170@see PxPhysics.createCloth
171*/
172class PxCloth : public PxActor
173{
174public:
175 /**
176 \brief Deletes the cloth.
177 Do not keep a reference to the deleted instance.
178 */
179 virtual void release() = 0;
180
181 /**
182 \brief Returns a pointer to the corresponding cloth fabric.
183 \return The associated cloth fabric.
184 */
185 virtual PxClothFabric* getFabric() const = 0;
186
187 /**
188 \brief Returns world space bounding box.
189 \param[in] inflation Scale factor for computed world bounds. Box extents are multiplied by this value.
190 \return Particle bounds in global coordinates.
191 */
192 virtual PxBounds3 getWorldBounds(float inflation=1.01f) const = 0;
193
194 /**
195 \brief Returns the number of particles.
196 \return Number of particles.
197 */
198 virtual PxU32 getNbParticles() const = 0;
199
200 /**
201 \brief Acquires access to the cloth particle data.
202 \details This function returns a pointer to a PxClothParticleData instance providing access to the
203 PxClothParticle array of the current and previous iteration. The user is responsible for calling
204 PxClothParticleData::unlock() after reading or updating the data. In case the lock has been
205 requested using PxDataAccessFlag::eWRITABLE, the unlock() call copies the arrays pointed to by
206 PxClothParticleData::particles/previousParticles back to the internal particle buffer.
207 Updating the data when a read-only lock has been requested results in undefined behavior.
208 Requesting multiple concurrent read-only locks is supported, but no other lock may be active
209 when requesting a write lock.
210
211 If PxDataAccessFlag::eDEVICE is set in flags then the returned pointers will be to GPU
212 device memory, this can be used for direct interop with graphics APIs. Note that these pointers
213 should only be considered valid until PxClothParticleData::unlock() is called and should not
214 be stored. PxDataAccessFlag::eDEVICE implies read and write access, and changing the
215 particles/previousParticles members results in undefined behavior.
216
217 \param flags Specifies if particle data is read or written.
218 \return PxClothParticleData pointer which provides access to positions and weight.
219 */
220 virtual PxClothParticleData* lockParticleData(PxDataAccessFlags flags) = 0;
221 /**
222 \brief Acquires read access to the cloth particle data.
223 \return PxClothParticleData pointer which provides access to positions and weight.
224 \note This function is equivalent to lockParticleData(PxDataAccessFlag::eREADABLE).
225 */
226 virtual PxClothParticleData* lockParticleData() const = 0;
227
228 /**
229 \brief Updates cloth particle location or inverse weight for current and previous particle state.
230 \param [in] currentParticles The particle data for the current particle state or NULL if the state should not be changed.
231 \param [in] previousParticles The particle data for the previous particle state or NULL if the state should not be changed.
232 \note The invWeight stored in \a previousParticles is the new particle inverse mass, or zero for a static particle.
233 However, if invWeight stored in \a currentParticles is non-zero, it is still used once for the next particle integration and fabric solve.
234 \note If <b>currentParticles</b> or <b>previousParticles</b> are non-NULL then they must be the length specified by getNbParticles().
235 \note This can be used to teleport particles (use same positions for current and previous).
236 \see PxClothParticle
237 */
238 virtual void setParticles(const PxClothParticle* currentParticles, const PxClothParticle* previousParticles) = 0;
239
240 /**
241 \brief Sets cloth flags (e.g. use GPU for simulation, enable CCD, collide against scene).
242 \param [in] flag Mask of which flags to set.
243 \param [in] value Value to set flags to.
244 */
245 virtual void setClothFlag(PxClothFlag::Enum flag, bool value) = 0;
246 /**
247 \brief Set all cloth flags
248 \param [in] inFlags Bit mask of flag values
249 */
250 virtual void setClothFlags(PxClothFlags inFlags) = 0;
251 /**
252 \brief Returns cloth flags.
253 \return Cloth flags.
254 */
255 virtual PxClothFlags getClothFlags() const = 0;
256
257 /** @name Integration
258 * Functions related to particle integration.
259 */
260 /// @{
261
262 /**
263 \brief Sets pose that the cloth should move to by the end of the next simulate() call.
264 \details This function will move the cloth in world space. The resulting
265 simulation may reflect inertia effect as a result of pose acceleration.
266 \param [in] pose Target pose at the end of the next simulate() call.
267 \see setGlobalPose() to move cloth without inertia effect.
268 */
269 virtual void setTargetPose(const PxTransform& pose) = 0;
270 /**
271 \brief Sets current pose of the cloth without affecting inertia.
272 \details Use this to reset the pose (e.g. teleporting).
273 \param [in] pose New global pose.
274 \note No pose interpolation is performed.
275 \note Inertia is not preserved.
276 \see setTargetPose() for inertia preserving method.
277 */
278 virtual void setGlobalPose(const PxTransform& pose) = 0;
279 /**
280 \brief Returns global pose.
281 \return Global pose as specified by the last setGlobalPose() or setTargetPose() call.
282 */
283 virtual PxTransform getGlobalPose() const = 0;
284
285 /**
286 \brief Sets the solver frequency parameter.
287 \details Solver frequency specifies how often the simulation step is computed per second.
288 For example, a value of 60 represents one simulation step per frame
289 in a 60fps scene. A value of 120 will represent two simulation steps per frame, etc.
290 \param [in] frequency Solver frequency per second (default: 60.0).
291 */
292 virtual void setSolverFrequency(PxReal frequency) = 0;
293 /**
294 \brief Returns solver frequency.
295 \return Solver frequency.
296 */
297 virtual PxReal getSolverFrequency() const = 0;
298
299 /**
300 \brief Returns previous time step size.
301 \details Time between sampling of previous and current particle positions for computing particle velocity.
302 \return Previous time step size.
303 */
304 virtual PxReal getPreviousTimeStep() const = 0;
305
306 /**
307 \brief Sets the stiffness frequency parameter.
308 \details The stiffness frequency controls the power-law nonlinearity of all rate of change parameters
309 (stretch stiffness, shear stiffness, bending stiffness, tether stiffness, self-collision
310 stiffness, motion constraint stiffness, damp coefficient, linear and angular drag coefficients).
311 Increasing the frequency avoids numerical cancellation for values near zero or one, but increases the
312 non-linearity of the parameter. It is not recommended to change this parameter after cloth initialization.
313 For example, the portion of edge overstretch removed per second is
314 equal to the stretch stiffness raised to the power of the stiffness frequency.
315 \param [in] frequency Stiffness frequency per second (default: 10.0).
316 */
317 virtual void setStiffnessFrequency(PxReal frequency) = 0;
318 /**
319 \brief Returns stiffness frequency.
320 \return Stiffness frequency.
321 \see setStiffnessFrequency() for details.
322 */
323 virtual PxReal getStiffnessFrequency() const = 0;
324
325 /**
326 \brief Sets the acceleration scale factor to adjust inertia effect from global pose changes.
327 \param [in] scale New scale factor between 0.0 (no inertia) and 1.0 (full inertia) (default: 1.0).
328 \note The scale is specified independently for each local coordinate axis.
329 \note A value of 0.0 disables all inertia effects of translations applied through setTargetPos().
330 \see setTargetPose()
331 */
332 virtual void setLinearInertiaScale(PxVec3 scale) = 0;
333 /**
334 \brief Returns linear acceleration scale parameter.
335 \return Linear acceleration scale parameter.
336 */
337 virtual PxVec3 getLinearInertiaScale() const = 0;
338 /**
339 \brief Sets the acceleration scale factor to adjust inertia effect from global pose changes.
340 \param [in] scale New scale factor between 0.0 (no inertia) and 1.0 (full inertia) (default: 1.0).
341 \note The scale is specified independently for each local rotation axis.
342 \note A value of 0.0 disables all inertia effects of rotations applied through setTargetPos().
343 \see setTargetPose()
344 */
345 virtual void setAngularInertiaScale(PxVec3 scale) = 0;
346 /**
347 \brief Returns angular acceleration scale parameter.
348 \return Angular acceleration scale parameter.
349 */
350 virtual PxVec3 getAngularInertiaScale() const = 0;
351 /**
352 \brief Sets the acceleration scale factor to adjust inertia effect from global pose changes.
353 \param [in] scale New scale factor between 0.0 (no centrifugal force) and 1.0 (full centrifugal force) (default: 1.0).
354 \note The scale is specified independently for each local rotation axis.
355 \note A value of 0.0 disables all centrifugal forces of rotations applied through setTargetPos().
356 \see setTargetPose()
357 */
358 virtual void setCentrifugalInertiaScale(PxVec3 scale) = 0;
359 /**
360 \brief Returns centrifugal acceleration scale parameter.
361 \return Centrifugal acceleration scale parameter.
362 */
363 virtual PxVec3 getCentrifugalInertiaScale() const = 0;
364 /**
365 \brief Same as <code>setLinearInertiaScale(PxVec3(scale));
366 setAngularInertiaScale(PxVec3(scale)); getCentrifugalInertiaScale(PxVec3(scale)); </code>
367 */
368 virtual void setInertiaScale(PxReal scale) = 0;
369
370 /**
371 \brief Sets the damping coefficient.
372 \details The damping coefficient is the portion of local particle velocity
373 that is canceled per stiffness period (see PxCloth::setStiffnessFrequency).
374 \note The scale is specified independently for each local space axis.
375 \param [in] dampingCoefficient New damping coefficient between 0.0 and 1.0 (default: 0.0).
376 */
377 virtual void setDampingCoefficient(PxVec3 dampingCoefficient) = 0;
378 /**
379 \brief Returns the damping coefficient.
380 \return Damping coefficient.
381 */
382 virtual PxVec3 getDampingCoefficient() const = 0;
383
384 /**
385 \brief Sets the linear drag coefficient.
386 \details The linear drag coefficient is the portion of the pose translation
387 that is applied to each particle per stiffness period (see PxCloth::setStiffnessFrequency).
388 \note The scale is specified independently for each local space axis.
389 \param [in] dragCoefficient New linear drag coefficient between 0.0f and 1.0 (default: 0.0).
390 \note The drag coefficient shouldn't be set higher than the damping coefficient.
391 */
392 virtual void setLinearDragCoefficient(PxVec3 dragCoefficient) = 0;
393 /**
394 \brief Returns the linear drag coefficient.
395 \return Linear drag coefficient.
396 */
397 virtual PxVec3 getLinearDragCoefficient() const = 0;
398 /**
399 \brief Sets the angular drag coefficient.
400 \details The angular drag coefficient is the portion of the pose rotation
401 that is applied to each particle per stiffness period (see PxCloth::setStiffnessFrequency).
402 \note The scale is specified independently for each local rotation axis.
403 \param [in] dragCoefficient New angular drag coefficient between 0.0f and 1.0 (default: 0.0).
404 \note The drag coefficient shouldn't be set higher than the damping coefficient.
405 */
406 virtual void setAngularDragCoefficient(PxVec3 dragCoefficient) = 0;
407 /**
408 \brief Returns the angular drag coefficient.
409 \return Angular drag coefficient.
410 */
411 virtual PxVec3 getAngularDragCoefficient() const = 0;
412 /**
413 \brief Same as <code>setLinearDragCoefficient(PxVec3(coefficient));
414 setAngularDragCoefficient(PxVec3(coefficient));</code>
415 */
416 virtual void setDragCoefficient(PxReal scale) = 0;
417
418 /**
419 \brief Sets external particle accelerations.
420 \param [in] acceleration New acceleration in global coordinates (default: 0.0).
421 \note Use this to implement simple wind etc.
422 */
423 virtual void setExternalAcceleration(PxVec3 acceleration) = 0;
424 /**
425 \brief Returns external acceleration.
426 \return External acceleration in global coordinates.
427 */
428 virtual PxVec3 getExternalAcceleration() const = 0;
429
430 /**
431 \brief Updates particle accelerations, w component is ignored.
432 \param [in] particleAccelerations New particle accelerations.
433 \note The <b>particleAccelerations</b> must either be null to disable accelerations,
434 or be the same length as the number of particles, see getNbParticles().
435 */
436 virtual void setParticleAccelerations(const PxVec4* particleAccelerations) = 0;
437 /**
438 \brief Copies particle accelerations to the user provided buffer.
439 \param [out] particleAccelerationsBuffer Destination buffer, must be at least getNbParticleAccelerations().
440 \return true if the copy was successful.
441 */
442 virtual bool getParticleAccelerations(PxVec4* particleAccelerationsBuffer) const = 0;
443 /**
444 \brief Returns the number of particle accelerations.
445 \return Number of particle accelerations (same as getNbParticles() if enabled, 0 otherwise).
446 */
447 virtual PxU32 getNbParticleAccelerations() const = 0;
448
449 /// @}
450
451 /** @name Constraints
452 * Functions related to particle and distance constaints.
453 */
454 /// @{
455
456 /**
457 \brief Updates motion constraints (position and radius of the constraint sphere).
458 \param [in] motionConstraints motion constraints at the end of the next simulate() call.
459 \note The <b>motionConstraints</b> must either be null to disable motion constraints,
460 or be the same length as the number of particles, see getNbParticles().
461 \see clearInterpolation()
462 */
463 virtual void setMotionConstraints(const PxClothParticleMotionConstraint* motionConstraints) = 0;
464 /**
465 \brief Copies motion constraints to the user provided buffer.
466 \param [out] motionConstraintsBuffer Destination buffer, must be at least getNbMotionConstraints().
467 \return True if the copy was successful.
468 */
469 virtual bool getMotionConstraints(PxClothParticleMotionConstraint* motionConstraintsBuffer) const = 0;
470 /**
471 \brief Returns the number of motion constraints.
472 \return Number of motion constraints (same as getNbParticles() if enabled, 0 otherwise).
473 */
474 virtual PxU32 getNbMotionConstraints() const = 0;
475 /**
476 \brief Specifies motion constraint scale, bias, and stiffness.
477 \param [in] config Motion constraints solver parameters.
478 */
479 virtual void setMotionConstraintConfig(const PxClothMotionConstraintConfig& config) = 0;
480 /**
481 \brief Reads back scale and bias factor for motion constraints.
482 \see setMotionConstraintConfig()
483 */
484 virtual PxClothMotionConstraintConfig getMotionConstraintConfig() const = 0;
485
486 /**
487 \brief Updates separation constraints (position and radius of the constraint sphere).
488 \param [in] separationConstraints separation constraints at the end of the next simulate() call.
489 \note The <b>separationConstraints</b> must either be null to disable separation constraints,
490 or be the same length as the number of particles, see getNbParticles().
491 \see clearInterpolation()
492 */
493 virtual void setSeparationConstraints(const PxClothParticleSeparationConstraint* separationConstraints) = 0;
494 /**
495 \brief Copies separation constraints to the user provided buffer.
496 \param [out] separationConstraintsBuffer Destination buffer, must be at least getNbSeparationConstraints().
497 \return True if the copy was successful.
498 */
499 virtual bool getSeparationConstraints(PxClothParticleSeparationConstraint* separationConstraintsBuffer) const = 0;
500 /**
501 \brief Returns the number of separation constraints.
502 \return Number of separation constraints (same as getNbParticles() if enabled, 0 otherwise).
503 */
504 virtual PxU32 getNbSeparationConstraints() const = 0;
505
506 /**
507 \brief Assign current to previous positions for collision shapes, motion constraints, and separation constraints.
508 \details This allows to prevent false interpolation after leaping to an animation frame, for example.
509 After calling clearInterpolation(), the current positions will be used without interpolation.
510 New positions can be set afterwards to interpolate to by the end of the next frame.
511 */
512 virtual void clearInterpolation() = 0;
513
514 /**
515 \brief Sets the solver parameters for the vertical solver phases.
516 \param [in] config Stretch solver parameters.
517 \param [in] type Type of phases to set config for.
518 */
519 virtual void setStretchConfig(PxClothFabricPhaseType::Enum type, const PxClothStretchConfig& config) = 0;
520 /**
521 \brief Returns the solver parameters for one of the phase types.
522 \param [in] type Type of phases to return the config for.
523 \return Vertical solver parameters.
524 */
525 virtual PxClothStretchConfig getStretchConfig(PxClothFabricPhaseType::Enum type) const = 0;
526 /**
527 \brief Sets the stiffness parameters for the tether constraints.
528 \param [in] config Tether constraints solver parameters.
529 */
530 virtual void setTetherConfig(const PxClothTetherConfig& config) = 0;
531 /**
532 \brief Returns the stiffness parameters for the tether constraints.
533 \return Tether solver parameters.
534 */
535 virtual PxClothTetherConfig getTetherConfig() const = 0;
536
537 /// @}
538
539 /** @name Collision
540 * Functions related to particle collision.
541 */
542 /// @{
543
544 /**
545 \brief Adds a new collision sphere.
546 \param [in] sphere New collision sphere.
547 \note A maximum of 32 spheres are supported.
548 */
549 virtual void addCollisionSphere(const PxClothCollisionSphere& sphere) = 0;
550 /**
551 \brief Removes collision sphere.
552 \param [in] index Index of sphere to remove.
553 \note The indices of spheres added after \c index are decremented by 1.
554 \note Capsules made from the sphere to be removed are removed as well.
555 */
556 virtual void removeCollisionSphere(PxU32 index) = 0;
557 /**
558 \brief Updates location and radii of collision spheres.
559 \param [in] spheresBuffer New sphere positions and radii by the end of the next simulate() call.
560 \param [in] count New number of collision spheres.
561 \note You can also use this function to change the number of collision spheres.
562 \note A maximum of 32 spheres are supported.
563 \see clearInterpolation()
564 */
565 virtual void setCollisionSpheres(const PxClothCollisionSphere* spheresBuffer, PxU32 count) = 0;
566 /**
567 \brief Returns the number of collision spheres.
568 \return Number of collision spheres.
569 */
570 virtual PxU32 getNbCollisionSpheres() const = 0;
571
572 /**
573 \brief Adds a new collision capsule.
574 \details A collision capsule is defined as the bounding volume of two spheres.
575 \param [in] first Index of first sphere.
576 \param [in] second Index of second sphere.
577 \note A maximum of 32 capsules are supported.
578 \note Spheres referenced by a capsule need to be defined
579 before simulating the scene, see addCollisionSphere/setCollisionSpheres.
580 */
581 virtual void addCollisionCapsule(PxU32 first, PxU32 second) = 0;
582 /**
583 \brief Removes a collision capsule.
584 \param [in] index Index of capsule to remove.
585 \note The indices of capsules added after \c index are decremented by 1.
586 */
587 virtual void removeCollisionCapsule(PxU32 index) = 0;
588 /**
589 \brief Returns the number of collision capsules.
590 \return Number of collision capsules.
591 */
592 virtual PxU32 getNbCollisionCapsules() const = 0;
593
594 /**
595 \brief Adds a collision plane.
596 \param [in] plane New collision plane.
597 \note Planes are not used for collision until they are added to a convex object, see addCollisionConvex().
598 \note A maximum of 32 planes are supported.
599 */
600 virtual void addCollisionPlane(const PxClothCollisionPlane& plane) = 0;
601 /**
602 \brief Removes a collision plane.
603 \param [in] index Index of plane to remove.
604 \note The indices of planes added after \c index are decremented by 1.
605 \note Convexes that reference the plane will have the plane removed from their mask.
606 If after removal a convex consists of zero planes, it will also be removed.
607 */
608 virtual void removeCollisionPlane(PxU32 index) = 0;
609 /**
610 \brief Updates positions of collision planes.
611 \param [in] planesBuffer New plane positions by the end of the next simulate() call.
612 \param [in] count New number of collision planes.
613 \note You can also use this function to change the number of collision planes.
614 \note A maximum of 32 planes are supported.
615 \see clearInterpolation()
616 */
617 virtual void setCollisionPlanes(const PxClothCollisionPlane* planesBuffer, PxU32 count) = 0;
618 /**
619 \brief Returns the number of collision planes.
620 \return Number of collision planes.
621 */
622 virtual PxU32 getNbCollisionPlanes() const = 0;
623
624 /**
625 \brief Adds a new collision convex.
626 \details A collision convex is defined as the intersection of planes.
627 \param [in] mask The bitmask of the planes that make up the convex.
628 \note Planes referenced by a collision convex need to be defined
629 before simulating the scene, see addCollisionPlane/setCollisionPlanes.
630 */
631 virtual void addCollisionConvex(PxU32 mask) = 0;
632 /**
633 \brief Removes a collision convex.
634 \param [in] index Index of convex to remove.
635 \note The indices of convexes added after \c index are decremented by 1.
636 \note Planes referenced by this convex will not be removed.
637 */
638 virtual void removeCollisionConvex(PxU32 index) = 0;
639 /**
640 \brief Returns the number of collision convexes.
641 \return Number of collision convexes.
642 */
643 virtual PxU32 getNbCollisionConvexes() const = 0;
644
645 /**
646 \brief Adds a new collision triangle.
647 \param [in] triangle New collision triangle.
648 \note GPU cloth is limited to 500 triangles per instance.
649 */
650 virtual void addCollisionTriangle(const PxClothCollisionTriangle& triangle) = 0;
651 /**
652 \brief Removes a collision triangle.
653 \param [in] index Index of triangle to remove.
654 \note The indices of triangles added after \c index are decremented by 1.
655 */
656 virtual void removeCollisionTriangle(PxU32 index) = 0;
657 /**
658 \brief Updates positions of collision triangles.
659 \param [in] trianglesBuffer New triangle positions by the end of the next simulate() call.
660 \param [in] count New number of collision triangles.
661 \note You can also use this function to change the number of collision triangles.
662 \note GPU cloth is limited to 500 triangles per instance.
663 \see clearInterpolation()
664 */
665 virtual void setCollisionTriangles(const PxClothCollisionTriangle* trianglesBuffer, PxU32 count) = 0;
666 /**
667 \brief Returns the number of collision triangles.
668 \return Number of collision triangles.
669 */
670 virtual PxU32 getNbCollisionTriangles() const = 0;
671
672 /**
673 \brief Retrieves the collision shapes.
674 \details Returns collision spheres, capsules, convexes, and triangles that were added through
675 the addCollision*() methods and modified through the setCollision*() methods.
676 \param [out] spheresBuffer Spheres destination buffer, must be NULL or the same length as getNbCollisionSpheres().
677 \param [out] capsulesBuffer Capsules destination buffer, must be NULL or the same length as 2*getNbCollisionCapsules().
678 \param [out] planesBuffer Planes destination buffer, must be NULL or the same length as getNbCollisionPlanes().
679 \param [out] convexesBuffer Convexes destination buffer, must be NULL or the same length as getNbCollisionConvexes().
680 \param [out] trianglesBuffer Triangles destination buffer, must be NULL or the same length as getNbCollisionTriangles().
681 \note Returns the positions at the end of the next simulate() call as specified by the setCollision*() methods.
682 */
683 virtual void getCollisionData(PxClothCollisionSphere* spheresBuffer, PxU32* capsulesBuffer,
684 PxClothCollisionPlane* planesBuffer, PxU32* convexesBuffer, PxClothCollisionTriangle* trianglesBuffer) const = 0;
685
686 /**
687 \brief Assigns virtual particles.
688 \details Virtual particles provide more robust and accurate collision handling against collision spheres and capsules.
689 More virtual particles will generally increase the accuracy of collision handling, and thus
690 a sufficient number of virtual particles can mimic triangle-based collision handling.\n
691 Virtual particles are specified as barycentric interpolation of real particles:
692 The position of a virtual particle is w0 * P0 + w1 * P1 + w2 * P2, where P0, P1, P2 real particle positions.
693 The barycentric weights w0, w1, w2 are stored in a separate table so they can be shared across multiple virtual particles.
694 \param [in] numVirtualParticles total number of virtual particles.
695 \param [in] indices Each virtual particle has four indices, the first three for real particle indices, and the last
696 for the weight table index. Thus, the length of <b>indices</b> needs to be 4*numVirtualParticles.
697 \param [in] numWeights total number of unique weights triples.
698 \param [in] weights array for barycentric weights.
699 \note Virtual particles only incur a runtime cost during the collision stage. Still, it is advisable to
700 only use virtual particles for areas where high collision accuracy is desired. (e.g. sleeve around elbow).
701 */
702 virtual void setVirtualParticles(PxU32 numVirtualParticles, const PxU32* indices, PxU32 numWeights, const PxVec3* weights) = 0;
703 /**
704 \brief Returns the number of virtual particles.
705 \return Number of virtual particles.
706 */
707 virtual PxU32 getNbVirtualParticles() const = 0;
708 /**
709 \brief Copies index array of virtual particles to the user provided buffer.
710 \param [out] indicesBuffer Destination buffer, must be at least 4*getNbVirtualParticles().
711 \see setVirtualParticles()
712 */
713 virtual void getVirtualParticles(PxU32* indicesBuffer) const = 0;
714 /**
715 \brief Returns the number of the virtual particle weights.
716 \return Number of virtual particle weights.
717 */
718 virtual PxU32 getNbVirtualParticleWeights() const = 0;
719 /**
720 \brief Copies weight table of virtual particles to the user provided buffer.
721 \param [out] weightsBuffer Destination buffer, must be at least getNbVirtualParticleWeights().
722 */
723 virtual void getVirtualParticleWeights(PxVec3* weightsBuffer) const = 0;
724
725 /**
726 \brief Sets the collision friction coefficient.
727 \param [in] frictionCoefficient New friction coefficient between 0.0 and 1.0 (default: 0.0).
728 \note Currently only spheres and capsules impose friction on the colliding particles.
729 */
730 virtual void setFrictionCoefficient(PxReal frictionCoefficient) = 0;
731 /**
732 \brief Returns the friction coefficient.
733 \return Friction coefficient.
734 */
735 virtual PxReal getFrictionCoefficient() const = 0;
736
737 /**
738 \brief Sets the collision mass scaling coefficient.
739 \details During collision it is possible to artificially increase the
740 mass of a colliding particle, this has an effect comparable to making
741 constraints attached to the particle stiffer and can help reduce stretching
742 and interpenetration around collision shapes.
743 \param [in] scalingCoefficient Unitless multiplier that can take on values > 1 (default: 0.0).
744 */
745 virtual void setCollisionMassScale(PxReal scalingCoefficient) = 0;
746 /**
747 \brief Returns the mass-scaling coefficient.
748 \return Mass-scaling coefficient.
749 */
750 virtual PxReal getCollisionMassScale() const = 0;
751
752 /// @}
753
754 /** @name Self-Collision
755 * Functions related to particle against particle collision.
756 */
757 /// @{
758
759 /**
760 \brief Sets the self collision distance.
761 \details A value larger than 0.0 enables particle versus particle collision.
762 \param [in] distance Minimum distance at which two particles repel each other (default: 0.0).
763 */
764 virtual void setSelfCollisionDistance(PxReal distance) = 0;
765 /**
766 \brief Returns the self-collision distance.
767 \return Self-collision distance.
768 */
769 virtual PxReal getSelfCollisionDistance() const = 0;
770 /**
771 \brief Sets the self collision stiffness.
772 \details Self-collision stiffness controls how much two particles repel
773 each other when they are closer than the self-collision distance.
774 \param [in] stiffness Fraction of distance residual to resolve per iteration (default: 1.0).
775 */
776 virtual void setSelfCollisionStiffness(PxReal stiffness) = 0;
777 /**
778 \brief Returns the self-collision stiffness.
779 \return Self-collision stiffness.
780 */
781 virtual PxReal getSelfCollisionStiffness() const = 0;
782
783 /**
784 \brief Sets a subset of cloth particles which participate in self-collision.
785 \details If non-null the cloth self-collision will consider a subset of particles
786 instead of all the particles. This can be used to improve self-collision performance
787 or to increase the minimum distance between two self-colliding particles
788 (and therefore the maximum sensible self-collision distance).
789 \param [in] indices array of particle indices which participate in self-collision.
790 \param [in] nbIndices number of particle indices, or 0 to use all particles for self-collision.
791 \note These indices will also be used if cloth inter-collision is enabled.
792 */
793 virtual void setSelfCollisionIndices(const PxU32* indices, PxU32 nbIndices) = 0;
794 /**
795 \brief Copies array of particles participating in self-collision to the user provided buffer.
796 \param [out] indices Destination buffer, must be at least getNbSelfCollisionIndices() in length.
797 \return true if the copy was successful.
798 */
799 virtual bool getSelfCollisionIndices(PxU32* indices) const = 0;
800
801 /**
802 \brief Returns the number of particles participating in self-collision.
803 \return Size of particle subset participating in self-collision, or 0 if all particles are used.
804 */
805 virtual PxU32 getNbSelfCollisionIndices() const = 0;
806
807 /**
808 \brief Sets the cloth particles rest positions.
809 \details If non-null the cloth self-collision will consider the rest positions by
810 discarding particle->particle collision where the distance between the associated
811 rest particles is < the self collision distance. This allows self-collision distances
812 that are larger than the minimum edge length in the mesh. Typically this function
813 should be called with the same positions used to construct the cloth instance.
814 \param [in] restPositions Undeformed particle positions, the w component will be ignored
815 \note <b>restPositions</b> must either be null to disable rest position consideration,
816 or be the same length as the number of particles, see getNbParticles().
817 */
818 virtual void setRestPositions(const PxVec4* restPositions) = 0;
819 /**
820 \brief Copies array of rest positions to the user provided buffer.
821 \param [out] restPositions Destination buffer, must be at least getNbParticles() in length.
822 \return true if the copy was successful.
823 */
824 virtual bool getRestPositions(PxVec4* restPositions) const = 0;
825 /**
826 \brief Returns the number of rest positions.
827 \return Number of rest positions (same as getNbParticles() if enabled, 0 otherwise).
828 */
829 virtual PxU32 getNbRestPositions() const = 0;
830
831 /// @}
832
833 /** @name Inter-Collision
834 * Functions related to collision between cloth instances.
835 */
836 /// @{
837
838 /**
839 \brief Sets the user definable collision filter data.
840 \param data The data that will be returned in the PxScene filter shader callback.
841 \note To disable collision on a cloth actor it is sufficient to set the
842 filter data to some non-zero value (if using the SDK's default filter shader).
843 @see PxSimulationFilterShader PxFilterData
844 */
845 virtual void setSimulationFilterData(const PxFilterData& data) = 0;
846
847 /**
848 \brief Retrieves the object's collision filter data.
849 \return Associated filter data
850 @see setSimulationFilterData() PxFilterData
851 */
852 virtual PxFilterData getSimulationFilterData() const = 0;
853
854 /// @}
855
856 /** @name Scene-Collision
857 * Functions related to collision against scene objects.
858 */
859 /// @{
860
861 /**
862 \brief Sets the width by which the cloth bounding box is increased to find nearby scene collision shapes.
863 \details The cloth particles collide against shapes in the scene that intersect the cloth bounding box enlarged by
864 the contact offset (if the eSCENE_COLLISION flag is set). <b>Default:</b> 0.0f
865 \param[in] offset <b>Range:</b> [0, PX_MAX_F32)
866 @see getContactOffset setRestOffset
867 */
868 virtual void setContactOffset(PxReal offset) = 0;
869
870 /**
871 \brief Returns cloth contact offset.
872 @see setContactOffset
873 */
874 virtual PxReal getContactOffset() const = 0;
875
876 /**
877 \brief Sets the minimum distance between colliding cloth particles and scene shapes.
878 \details Cloth particles colliding against shapes in the scene get no closer to the shape's surface
879 than specified by the rest offset (if the eSCENE_COLLISION flag is set). <b>Default:</b> 0.0f
880 \param[in] offset <b>Range:</b> [0, PX_MAX_F32)
881 @see getRestOffset setContactOffset
882 */
883 virtual void setRestOffset(PxReal offset) = 0;
884
885 /**
886 \brief Returns cloth rest offset.
887 @see setRestOffset
888 */
889 virtual PxReal getRestOffset() const = 0;
890
891 /// @}
892
893 /** @name Sleeping
894 * Functions related to sleeping.
895 */
896 /// @{
897
898 /**
899 \brief Sets the velocity threshold for putting cloth in sleep state.
900 \details If none of the particles moves faster (in local space)
901 than the threshold for a while, the cloth will be put in
902 sleep state and simulation will be skipped.
903 \param [in] threshold Velocity threshold (default: 0.0f)
904 */
905 virtual void setSleepLinearVelocity(PxReal threshold) = 0;
906 /**
907 \brief Returns the velocity threshold for putting cloth in sleep state.
908 \return Velocity threshold for putting cloth in sleep state.
909 */
910 virtual PxReal getSleepLinearVelocity() const = 0;
911 /**
912 \brief Sets the wake counter for the cloth.
913 \details The wake counter value determines how long all particles need to move less than the velocity threshold until the cloth
914 is put to sleep (see #setSleepLinearVelocity()).
915 \note Passing in a positive value will wake the cloth up automatically.
916 <b>Default:</b> 0.395 (which corresponds to 20 frames for a time step of 0.02)
917 \param[in] wakeCounterValue Wake counter value. <b>Range:</b> [0, PX_MAX_F32)
918 @see isSleeping() getWakeCounter()
919 */
920 virtual void setWakeCounter(PxReal wakeCounterValue) = 0;
921 /**
922 \brief Returns the wake counter of the cloth.
923 \return The wake counter of the cloth.
924 @see isSleeping() setWakeCounter()
925 */
926 virtual PxReal getWakeCounter() const = 0;
927 /**
928 \brief Forces cloth to wake up from sleep state.
929 \note This will set the wake counter of the cloth to the value specified in #PxSceneDesc::wakeCounterResetValue.
930 \note It is invalid to use this method if the cloth has not been added to a scene already.
931 @see isSleeping() putToSleep()
932 */
933 virtual void wakeUp() = 0;
934 /**
935 \brief Forces cloth to be put in sleep state.
936 \note It is invalid to use this method if the cloth has not been added to a scene already.
937 */
938 virtual void putToSleep() = 0;
939 /**
940 \brief Returns true if cloth is in sleep state
941 \note It is invalid to use this method if the cloth has not been added to a scene already.
942 \return True if cloth is in sleep state.
943 */
944 virtual bool isSleeping() const = 0;
945
946 /// @}
947
948 virtual const char* getConcreteTypeName() const { return "PxCloth"; }
949
950protected:
951 PX_INLINE PxCloth(PxType concreteType, PxBaseFlags baseFlags) : PxActor(concreteType, baseFlags) {}
952 PX_INLINE PxCloth(PxBaseFlags baseFlags) : PxActor(baseFlags) {}
953 virtual ~PxCloth() {}
954 virtual bool isKindOf(const char* name) const { return !strcmp("PxCloth", name) || PxActor::isKindOf(name); }
955};
956
957PX_DEPRECATED PX_INLINE PxCloth* PxActor::isCloth() { return is<PxCloth>(); }
958PX_DEPRECATED PX_INLINE const PxCloth* PxActor::isCloth() const { return is<PxCloth>(); }
959
960#ifndef PX_DOXYGEN
961} // namespace physx
962#endif
963
964/** @} */
965#endif
966