MnCloth Class Reference

MnCloth Class Reference
OpenMayaFX - API module for effects
Public Member Functions | Friends

#include <MnCloth.h>

Class Description

Class for wrapping N cloth objects.

This class wraps the internal Maya representation of N cloth objects suitable for use with the Nucleus solver.

+ Examples:
+ Inheritance diagram for MnCloth:

Public Member Functions

 MnCloth ()
 Default constructor. More...
 
virtual ~MnCloth ()
 The class destructor.
 
MStatus createNCloth ()
 Creates the underlying Maya TnCloth and sets this class to wrap it. More...
 
MStatus setTopology (const int numFaces, int *numVertsPerFace, int *faces, const int numEdges, int *edges)
 sets the topology of the underlying N Object. More...
 
MStatus setPositions (const MFloatPointArray &positions, bool startFrame=true)
 Sets the positions of the vertices of the underlying N cloth object. More...
 
MStatus setVelocities (const MFloatPointArray &velocities)
 Sets the velocities of the vertices of the underlying Ncloth object. More...
 
MStatus setBendRestAngleFromPositions (const MFloatPointArray &positions)
 Sets the the bend rest angle from the list of positions for the underlying N Object This sets the shape that bend resistance is trying to achieve. More...
 
MStatus setLinksRestLengthFromPositions (const MFloatPointArray &positions)
 Sets the the rest length from the list of positions for the underlying N Object. More...
 
MStatus setInputMeshAttractPositions (const MFloatPointArray &positions)
 Sets the positions for input mesh attract. More...
 
MStatus setInputMeshAttractDamping (float damping)
 Defines how springy the effect of Input Mesh Attract is. More...
 
MStatus setInputMeshAttractAndRigidStrength (float *inputAttractArray, float *rigidArray, float *deformArray)
 Sets on a per particle basis, the amount by which each particle is affected by the input mesh attract, rigidity, and deformability. More...
 
MStatus setComputeRestLength (const bool b)
 Sets whether rest lengths will be automatically computed, or overridden manually. More...
 
MStatus setComputeRestAngles (const bool b)
 Sets whether rest angles will be automatically computed, or overridden manually. More...
 
MStatus setThickness (float radius)
 sets a radius on each point of the mesh for collision purposes. More...
 
MStatus setThickness (float *radius)
 sets a radius (thickness) on a per point basis for the mesh for collision purposes. More...
 
MStatus setInverseMass (float invMass)
 sets the mass for every point in this mesh More...
 
MStatus setInverseMass (float *invMass)
 sets the mass on a per point basis in this mesh More...
 
MStatus setBounce (float bounce)
 sets the bounce for every point in this mesh More...
 
MStatus setBounce (float *bounce)
 sets the bounce on a per point basis in this mesh More...
 
MStatus setFriction (float friction)
 sets the friction for every point in this mesh More...
 
MStatus setFriction (float *friction)
 sets the friction on a per point basis for this mesh More...
 
MStatus setDamping (float damping)
 sets the damping for every point in this mesh More...
 
MStatus setDamping (float *damping)
 sets the on a per point basis in this mesh More...
 
MStatus setSelfCollisionFlags (const bool vertToVert, const bool vertToEdge=false, const bool vertToFace=false, const bool edgeToEdge=false, const bool edgeToFace=false)
 Sets how (or if) this object will collide with itself. More...
 
MStatus setCollisionFlags (const bool vertToVert, const bool edgeToEdge=false, const bool faceToFace=false)
 Sets how (or if) this object will collide with other objects. More...
 
MStatus setDisableGravity (const bool b)
 Sets whether gravity will affect this object. More...
 
MStatus setMaxIterations (const int it)
 Sets the number of iterations the solver will perform on various dynamic properties like drag, damping, stretch and bend. More...
 
MStatus setMaxSelfCollisionIterations (const int it)
 Sets the number of iterations the solver will perform for self collisions on this object. More...
 
MStatus setSelfCollisionSoftness (float softness)
 This allows one to lower the repulsive force of self collisions such that some interpenetration within the collide width is allowed. More...
 
MStatus setSelfTrappedCheck (bool on)
 This tracks self collision crossovers and attempts to push the crossed over points back. More...
 
MStatus setSelfCrossoverPush (float val)
 See node documentation. More...
 
MStatus setDragAndLift (float drag, float lift)
 Sets the drag and lift values for the cloth. More...
 
MStatus setTangentialDrag (float tangentialDrag)
 Sets the tangential drag values for the cloth. More...
 
MStatus setStartPressure (float startPressure)
 With the volume tracking pressure method this defines the relative air pressure inside the object at the startframe. More...
 
MStatus setSealHoles (bool seal)
 When the volume tracking pressure method is used this determines if physical holes in the cloth model are treated as being capped or not. More...
 
MStatus setPressure (float pressure)
 Sets the pressure within the cloth. More...
 
MStatus setTrackVolume (bool track)
 
MStatus setIncompressibility (float v)
 When the volume tracking pressure model is used this defines how incompressible the internal volume of fluid is. More...
 
MStatus setPressureDamping (float damp)
 Sets the damping value for pressure. More...
 
MStatus setPumpRate (float pump)
 Defines the rate at which air pressure is added to the object. More...
 
MStatus setAirTightness (float airTightness)
 Defines the rate at which air can escape from the object, or how permiable the surface is. More...
 
MStatus setAddCrossLinks (float addCrossLinks)
 For faces with more than 3 vertices this will create additional stretch and bends links such that each vertex is connected to each other vertex. More...
 
MStatus setBendAngleDropoff (float dropoff)
 Defines the way bend resistance changes with the angle. More...
 
MStatus setShearResistance (float resistance)
 Sets the shear resistance. More...
 
MStatus setStretchAndCompressionResistance (float stretchResist, float compressionResist)
 Stretch Resistance: More...
 
MStatus setStretchAndCompressionResistance (float *stretchResist, float *compressionResist)
 Sets the stretch and compression resistance for the mesh on a per vertex basis. More...
 
MStatus setBendAngleScale (float scale)
 Defines the amount by which the rest state of the bend angle is scaled. More...
 
MStatus setRestitutionAngle (float angle)
 Defines how far we can bend across an edge before it will fail to go back to the rest angle when there are no forces acting on the cloth. More...
 
MStatus setRestitutionTension (float tension)
 How far can the links be stretched before they fail to go back to their rest length when there are no forces acting on the cloth. More...
 
MStatus setSelfCollideWidth (float width)
 Sets the self collision width. More...
 
MStatus setBendResistance (float strength)
 Bend resistance measures the amount of attraction to the restAngle, which is defined between cvs on either side of an edge. More...
 
MStatus getNumVertices (unsigned int &numVerts) const
 Returns the number of vertices in the underlying n Cloth. More...
 
MStatus getPositions (MFloatPointArray &positions) const
 gets the positions of the points of the underlying N Object. More...
 
MStatus getVelocities (MFloatPointArray &velocities) const
 gets the velocities of the points of the underlying N cloth object. More...
 
MStatus getThickness (MFloatArray &radius) const
 gets the thickness at each point of the underlying N cloth object. More...
 
MStatus getInverseMass (MFloatArray &inverseMass) const
 gets the inverseMass at each point of the underlying N cloth object. More...
 
MStatus getBounce (MFloatArray &bounce) const
 gets the bounce at each point of the underlying N cloth object. More...
 
MStatus getFriction (MFloatArray &friction) const
 gets the friction at each point of the underlying N cloth object. More...
 
- Public Member Functions inherited from MnObject
 MnObject ()
 Default constructor. More...
 
virtual ~MnObject ()
 The class destructor.
 

Friends

class MFnNObjectData
 

Constructor & Destructor Documentation

MnCloth ( )

Default constructor.

The instance is set to contain nothing.

Member Function Documentation

MStatus createNCloth ( )

Creates the underlying Maya TnCloth and sets this class to wrap it.

Returns
MStatus setTopology ( const int  numFaces,
int *  numVertsPerFace,
int *  faces,
const int  numEdges,
int *  edges 
)

sets the topology of the underlying N Object.

Before calling other methods, this must be the first method you call once the cloth object is created.

Parameters
[in]numFacesnumber of faces
[in]numVertsPerFacean array of size numFaces, where each element describes the number of verts on that face
[in]facesan array containing the actual face description. Each element is a vertex index.
[in]numEdgesnumber of edges
[in]edgesan array containing the edge description. Each element is a vertex index.
Returns
MStatus setPositions ( const MFloatPointArray &  positions,
bool  startFrame = true 
)

Sets the positions of the vertices of the underlying N cloth object.

Parameters
[in]positionsthe array containing the position information
[in]startFramewhether this information represents the state of the object at the start frame.
Returns
+ Examples:
MStatus setVelocities ( const MFloatPointArray &  velocities)

Sets the velocities of the vertices of the underlying Ncloth object.

Parameters
[in]velocitiesthe array containing the velocity information
Returns
MStatus setBendRestAngleFromPositions ( const MFloatPointArray &  positions)

Sets the the bend rest angle from the list of positions for the underlying N Object This sets the shape that bend resistance is trying to achieve.

Parameters
[in]positionsthe array containing the position information
Returns
MStatus setLinksRestLengthFromPositions ( const MFloatPointArray &  positions)

Sets the the rest length from the list of positions for the underlying N Object.

This sets the shape that the stretch/compression resistance are trying to achieve.

Parameters
[in]positionsthe array containing the position information
Returns
MStatus setInputMeshAttractPositions ( const MFloatPointArray &  positions)

Sets the positions for input mesh attract.

Parameters
[in]positionsthe array containing the position information
Returns
MStatus setInputMeshAttractDamping ( float  damping)

Defines how springy the effect of Input Mesh Attract is.

At a value of zero input mesh attract will behave like a spring connection from the input mesh to the output dynamic mesh. The cloth will tend to wiggle about the input mesh position. As the Input Attract Damp is increased to 1 the cloth mesh will still move to the input mesh position but not have the momentum to travel past it, so will no longer occillate about the input position.

Parameters
[in]dampingthe damping value
Returns
MStatus setInputMeshAttractAndRigidStrength ( float *  inputAttractArray,
float *  rigidArray,
float *  deformArray 
)

Sets on a per particle basis, the amount by which each particle is affected by the input mesh attract, rigidity, and deformability.

High values for the input mesh attract will make points stick closely to the input mesh. High values for the rigidArray will make the object behave like a rigid body.

These arguments actually encode 2 pieces of information in 1. It contains instructions for:

A) The number of iterations and B) The strength of the effect

The number of iterations is the maximum value over the array passed in. The relative strength, measured from 0 to 1, is the normalized value of each element of the array.

For example, if for the inputAttractArray one were to specify a value of 10.0 for the first element, and 1.0 for the rest, it means that the solver should take 10 steps to compute inputMeshAttract, and the first particle has a strength of 1 while the rest have a strength of 0.1.

Parameters
[in]inputAttractArrayvalues for the input mesh attract
[in]rigidArrayvalues for rigidity
[in]deformArrayvalues for deformability
Returns
MStatus setComputeRestLength ( const bool  b)

Sets whether rest lengths will be automatically computed, or overridden manually.

If this is set to false, then you must call setLinksRestLengthFromPositions() to set the rest lengths.

Parameters
[in]bwhether to compute rest lengths
Returns
MStatus setComputeRestAngles ( const bool  b)

Sets whether rest angles will be automatically computed, or overridden manually.

If this is set to false, then you must call setBendRestAngleFromPositions() to set the rest lengths.

Parameters
[in]bwhether to compute rest angles
Returns
MStatus setThickness ( float  radius)

sets a radius on each point of the mesh for collision purposes.

The bigger the radius/thickness, the more easily things collide.

Parameters
[in]radiusthe radius to set
Returns
MStatus setThickness ( float *  radius)

sets a radius (thickness) on a per point basis for the mesh for collision purposes.

The bigger the radius, the more easily things collide.

Parameters
[in]radiusthe radius to set
Returns
MStatus setInverseMass ( float  invMass)

sets the mass for every point in this mesh

Parameters
[in]invMassthe inverse of the mass. A value of 0 means an infinitely heave object.
Returns
MStatus setInverseMass ( float *  invMass)

sets the mass on a per point basis in this mesh

Parameters
[in]invMassthe inverse of the mass. A value of 0 means an infinitely heave object.
Returns
MStatus setBounce ( float  bounce)

sets the bounce for every point in this mesh

Parameters
[in]bouncevalue of bounce to set
Returns
MStatus setBounce ( float *  bounce)

sets the bounce on a per point basis in this mesh

Parameters
[in]bouncevalue of bounce to set
Returns
MStatus setFriction ( float  friction)

sets the friction for every point in this mesh

Parameters
[in]frictionthe friction to set
Returns
MStatus setFriction ( float *  friction)

sets the friction on a per point basis for this mesh

Parameters
[in]frictionthe friction to set
Returns
MStatus setDamping ( float  damping)

sets the damping for every point in this mesh

Parameters
[in]dampingthe damping value to set
Returns
MStatus setDamping ( float *  damping)

sets the on a per point basis in this mesh

Parameters
[in]dampingthe damping value to set
Returns
MStatus setSelfCollisionFlags ( const bool  vertToVert,
const bool  vertToEdge = false,
const bool  vertToFace = false,
const bool  edgeToEdge = false,
const bool  edgeToFace = false 
)

Sets how (or if) this object will collide with itself.

Parameters
[in]vertToVertwhether to calculate vertex - vertex collisions
[in]vertToEdgewhether to calculate vertex - edge collisions
[in]vertToFacewhether to calculate vertex - face collisions
[in]edgeToEdgewhether to calculate edge - edge collisions
[in]edgeToFacewhether to calculate edge - face collisions
Returns
MStatus setCollisionFlags ( const bool  vertToVert,
const bool  edgeToEdge = false,
const bool  faceToFace = false 
)

Sets how (or if) this object will collide with other objects.

Parameters
[in]vertToVertwhether to calculate vertex - vertex collisions
[in]edgeToEdgewhether to calculate edge - edge collisions
[in]faceToFacewhether to calculate face - face collisions
Returns
MStatus setDisableGravity ( const bool  b)

Sets whether gravity will affect this object.

Parameters
[in]bwhether to calculate gravity
Returns
MStatus setMaxIterations ( const int  it)

Sets the number of iterations the solver will perform on various dynamic properties like drag, damping, stretch and bend.

Higher iterations take longer, and the primary use of this attribute is to keep things from locking up should high iteration values be requested.

Parameters
[in]itnumber of iterations
Returns
+ Examples:
MStatus setMaxSelfCollisionIterations ( const int  it)

Sets the number of iterations the solver will perform for self collisions on this object.

Parameters
[in]itnumber of iterations
Returns
MStatus setSelfCollisionSoftness ( float  softness)

This allows one to lower the repulsive force of self collisions such that some interpenetration within the collide width is allowed.

This can in some cases reduce jitter due to self collision with low selfCollideIterations. In general its use should be avoided, however.

Parameters
[in]softnessvalue to set.
Returns
MStatus setSelfTrappedCheck ( bool  on)

This tracks self collision crossovers and attempts to push the crossed over points back.

It assumes that the surface is in a good state at the start and attempts to preserve that relative state. It is useful in cases where cloth can get caught between passive objects than interpenetrate (for example an elbow passing through a chest). Rather than get stuck on the wrong side this allows the cloth to push back to the correct side when the passive objects later separate.

Parameters
[in]onwhether to turn on self trapped check.
Returns
MStatus setSelfCrossoverPush ( float  val)

See node documentation.

Parameters
[in]valvalue for crossover push
Returns
MStatus setDragAndLift ( float  drag,
float  lift 
)

Sets the drag and lift values for the cloth.

Parameters
[in]dragvalue of drag
[in]liftvalue of lift
Returns
MStatus setTangentialDrag ( float  tangentialDrag)

Sets the tangential drag values for the cloth.

Defines the component of drag tangent to the surface. With a value of zero a flat plane will slice through air with no resistance and only have drag when moving along its normal axis. With a value of 1.0 the effect of drag will be equal in all directions.

Parameters
[in]tangentialDragthe tangential drag
Returns
MStatus setStartPressure ( float  startPressure)

With the volume tracking pressure method this defines the relative air pressure inside the object at the startframe.

Parameters
[in]startPressurethe start pressure
Returns
MStatus setSealHoles ( bool  seal)

When the volume tracking pressure method is used this determines if physical holes in the cloth model are treated as being capped or not.

If holes are not sealed, then air can escape out them, which also has the effect of pushing the cloth. For example, this can simulate a rubber balloon that is suddenly released. It also allows for inflow based on motion of the cloth. The opening in a parachute will allow air to flow in as it falls down, causing sideways pressure that inflates it. Note that drag alone cannot achieve this sort of effect

Parameters
[in]sealwhether to seal holes
Returns
MStatus setPressure ( float  pressure)

Sets the pressure within the cloth.

This defines a force applied along the surface normal direction

Parameters
[in]pressurethe value of pressure to set
Returns
MStatus setTrackVolume ( bool  track)
Parameters
[in]trackwhether to track volume
Returns
MStatus setIncompressibility ( float  v)

When the volume tracking pressure model is used this defines how incompressible the internal volume of fluid is.

This also will affect how much force is applied to the cloth when air is pumped in. In the case of a balloon higher values of incompressibility will overcome higher stretch resistance. Note that higher incompressibility may require more calculation time.

Parameters
[in]vhow incompressible the cloth is
Returns
MStatus setPressureDamping ( float  damp)

Sets the damping value for pressure.

Parameters
[in]dampvalue to set
Returns
MStatus setPumpRate ( float  pump)

Defines the rate at which air pressure is added to the object.

Parameters
[in]pumpvalue to set
Returns
MStatus setAirTightness ( float  airTightness)

Defines the rate at which air can escape from the object, or how permiable the surface is.

This is in addition to any physical holes in the model, which can be be capped or not using the seal holes method.

Parameters
[in]airTightnessvalue to set
Returns
MStatus setAddCrossLinks ( float  addCrossLinks)

For faces with more than 3 vertices this will create additional stretch and bends links such that each vertex is connected to each other vertex.

If this is off then the links will exactly match the meshes list of edges. For a quad meshes having addCrossLinks off would allow the cloth to shear, unless shear resistance was used.

Parameters
[in]addCrossLinksvalue to set
Returns
MStatus setBendAngleDropoff ( float  dropoff)

Defines the way bend resistance changes with the angle.

At higher values the bend will resist more at high angles then when the surface is nearly flat.

Parameters
[in]dropoffvalue to set
Returns
MStatus setShearResistance ( float  resistance)

Sets the shear resistance.

Shear can be thought of as the bend in the plane of the cloth.

Parameters
[in]resistancevalue to set
Returns
MStatus setStretchAndCompressionResistance ( float  stretchResist,
float  compressionResist 
)

Stretch Resistance:

Defines the amount that the material will resist stretching when under tension. Large values generally require more computation, so they may result in longer simulation times. Note that the scalingRelation attribute affects how this value is defined. Also one may need to additionally make the both collision iterations on the solver and constraint strength values high to keep stretching low.

Compression Resistance:

Defines the amount that the material will resist compression. Note that sometimes it is useful to have this value be lower than the Stretch Resistance, because the mesh resolution is only an approximation to a true surface, which could possibly fold within the length of a triangle. If one has a rest position for a cloth that is not flat and the compression and stretch resistance are both high then this can make cloth appear too stiff because the topology locks up. This problem is most noticable when the faces have relatively high angles relative to each other. Having a low compression resistance allows the material keep from locking up, yet still not appear to stretchy. Large values generally require more computation, so they may result in longer simulation times.

Parameters
[in]stretchResistvalue to set for stretch
[in]compressionResistvalue to set for compression
Returns
MStatus setStretchAndCompressionResistance ( float *  stretchResist,
float *  compressionResist 
)

Sets the stretch and compression resistance for the mesh on a per vertex basis.

Parameters
[in]stretchResistvalue to set for stretch
[in]compressionResistvalue to set for compression
Returns
MStatus setBendAngleScale ( float  scale)

Defines the amount by which the rest state of the bend angle is scaled.

Parameters
[in]scalevalue to set
Returns
MStatus setRestitutionAngle ( float  angle)

Defines how far we can bend across an edge before it will fail to go back to the rest angle when there are no forces acting on the cloth.

Parameters
[in]anglevalue to set
Returns
MStatus setRestitutionTension ( float  tension)

How far can the links be stretched before they fail to go back to their rest length when there are no forces acting on the cloth.

When the tension is greater than the defined value the defined rest length will increase until the tension is equal this value. For very low values the material will pull apart like taffy, yet still resist stretching under mild forces.

Parameters
[in]tensionvalue to set
Returns
MStatus setSelfCollideWidth ( float  width)

Sets the self collision width.

Parameters
[in]widthvalue to set
Returns
MStatus setBendResistance ( float  strength)

Bend resistance measures the amount of attraction to the restAngle, which is defined between cvs on either side of an edge.

Larger values will tend to make the surface more rigid and will take longer to compute.

Parameters
[in]strengthvalue to set
Returns
MStatus getNumVertices ( unsigned int &  numVerts) const

Returns the number of vertices in the underlying n Cloth.

Parameters
[out]numVertsNumber of vertices.
Returns
MStatus getPositions ( MFloatPointArray &  positions) const

gets the positions of the points of the underlying N Object.

Parameters
[out]positionsthe array will be filled with the positions.
Returns
+ Examples:
MStatus getVelocities ( MFloatPointArray &  velocities) const

gets the velocities of the points of the underlying N cloth object.

Parameters
[in]velocitiesthe array will be filled with the positions.
Returns
MStatus getThickness ( MFloatArray &  radius) const

gets the thickness at each point of the underlying N cloth object.

Parameters
[in]radiusthe array will be filled with the thickness.
Returns
MStatus getInverseMass ( MFloatArray &  inverseMass) const

gets the inverseMass at each point of the underlying N cloth object.

Parameters
[in]inverseMassthe array will be filled with the inverse masses.
Returns
MStatus getBounce ( MFloatArray &  bounce) const

gets the bounce at each point of the underlying N cloth object.

Parameters
[in]bouncethe array will be filled with the bounce.
Returns
MStatus getFriction ( MFloatArray &  friction) const

gets the friction at each point of the underlying N cloth object.

Parameters
[in]frictionthe array will be filled with the friction.
Returns
The documentation for this class was generated from the following files:
  • MnCloth.h
  • MnCloth.cpp
Please send us your comment about this page