MCurveAttribute Class Reference
#include <MCurveAttribute.h>
Create and manipulate curve attributes.
A curve attribute consists of a set of entries describing a 3rd degree NURBS curve which is used to map an input value onto an output value. Each entry consists of an input position ranging from 0 to 1, an output value that position maps onto. The (position, value) pairs form a control vertex for the NURBS curve.
The preferred way of creating a curve attribute is to use the createCurve or createCurveAttr methods. Once created, curve widgets can be created for those attributes using the falloffCurve or falloffCurveAttr MEL commands.
A curve must always have at least four control vertices since it is a third degree NURBS curve.
MCurveAttribute ()
Creates an empty Curve Attribute class. More...
MCurveAttribute (const MCurveAttribute &other)
Copy constructor operator. More...
MCurveAttribute (const MPlug &obj, MStatus *ReturnStatus=NULL)
Creates a new Curve Attribute class. More...
MCurveAttribute (const MObject &node, const MObject &attr, MStatus *ReturnStatus=NULL)
Creates a new Curve Attribute class. More...
MCurveAttribute & operator= (const MCurveAttribute &other)
Assignment operator. More...
~MCurveAttribute ()
Destructor.
unsigned int getNumEntries (MStatus *returnStatus=NULL)
Gets the number of entries in the curve attribute. More...
void getEntries (MIntArray &indexes, MFloatArray &positions, MFloatArray &values, MStatus *returnStatus=NULL)
Gets all the entries in a curve attribute. More...
void addEntries (MFloatArray &positions, MFloatArray &values, MStatus *returnStatus=NULL)
Adds entries into a curve attribute. More...
void deleteEntries (MIntArray &indexes, MStatus *returnStatus=NULL)
Deletes entries in the curve attribute. More...
void setValueAtIndex (float value, unsigned int index, MStatus *returnStatus=NULL)
Sets the value of a given entry. More...
void setPositionAtIndex (float position, unsigned int index, MStatus *returnStatus=NULL)
Sets the position of a given entry. More...
void getValuesAtPositions (const MFloatArray &positions, MFloatArray &values, MStatus *returnStatus=NULL)
Gets the values (y-axis) at the given positions (x-axis) More...
void getValueAtPosition (float position, float &value, MStatus *returnStatus=NULL)
Gets the value (y-axis) at the given position (x-axis) x If this curve is empty, then this method will return a failure. More...
void sampleValueCurve (unsigned int numberOfSamples, MFloatArray &values, MStatus *returnStatus=NULL)
Perform a linear sampling of this curve ramp and return the results. More...
bool hasIndex (unsigned int index, MStatus *ReturnStatus=NULL) const
Returns true if this curve attribute has an entry defined with a given index. More...
MStatus sort (bool ascending=true)
Sort the curve attribute entries by position in ascending or descending order, other arrays are sorted accordingly. More...
MStatus pack ()
Change the indices numbering by re-ordering them from 0. More...
MStatus setCurve (const MFloatArray &values, const MFloatArray &positions)
Sets this curve attribute with entries defined from a set of float, position value arrays. More...
Creates an empty Curve Attribute class.
Initializes it as a null Object.
Status Codes: None
Copy constructor operator.
Duplicates the given curve attribute.
Parameters
[in] other Curve attribute to be copied
Returns A reference to the copied curve attribute
Creates a new Curve Attribute class.
If the plug is not of a Curve, then the constructor will return a failure.
Parameters
[in] obj Plug of a curve
[out] ReturnStatus return status
Status Codes:
MS::kSuccess operation successful
MS::kFailure the new node could not be added to the model, or the function set could not be properly initialized with the new object.
Creates a new Curve Attribute class.
If the node does not have that attribute then the constructor will return a failure. If the attribute is not of a curve the constructor will also fail.
Parameters
[in] node Node that contains a ramp attribute
[in] attr The curve attribute
[out] ReturnStatus return status
Status Codes:
MS::kSuccess operation successful
MS::kFailure the new node could not be added to the model, or the function set could not be properly initialized with the new object.
Assignment operator.
Copies one curve attribute to another.
Parameters
[in] other Curve attribute to be copied
Returns A reference to the copied curve attribute
unsigned int getNumEntries
(
MStatus *
ReturnStatus = NULL
)
Gets the number of entries in the curve attribute.
Parameters
[out] ReturnStatus return status
Status Codes:
MS::kSuccess operation successful
MS::kFailure an error occurred while querying the curve
Returns The number of entries in the curve attribute
Gets all the entries in a curve attribute.
Parameters
[out] indices unique values that specify each entry in the curve
[out] positions the positions of each entry (can range from 0 to 1)
[out] values the values of the entries at each position (can range from 0 to 1)
[out] ReturnStatus Status code.
Status Codes:
MS::kSuccess operation successful
MS::kInvalidParameter the specified attribute is not a curve attribute
MS::kFailure an error occurred while retrieving the curve entries
Adds entries into a curve attribute.
Parameters
[in] positions the positions of the new entries (can range from 0 to 1)
[in] values the values of the new entry at each position
[out] ReturnStatus Status code.
Status Codes:
MS::kSuccess operation successful
MS::kInvalidParameter the attribute is not a curve curve attribute or array sizes do not match
MS::kFailure an error occurred while adding curve entries
Deletes entries in the curve attribute.
If any one of the indices is incorrect, then this function will not delete any of the entries.
A curve attribute must always have at least one entry. Any attempt to delete the last remaining entry will fail.
Parameters
[in] indices the entries that need to be deleted
[out] ReturnStatus Status code.
Status Codes:
MS::kSuccess operation successful
MS::kFailure an error occured while deleting curve entries. It is not valid to delete all entries in a curve.
void setValueAtIndex
(
float
value ,
unsigned int
index ,
MStatus *
ReturnStatus = NULL
)
Sets the value of a given entry.
If there is no entry at the given index, then this method will return a failure.
Parameters
[in] value the new value for the entry
[in] index index of entry to change
[out] ReturnStatus return status
Status Codes:
MS::kSuccess operation successful
MS::kFailure the new node could not be added to the model, or the function set could not be properly initialized with the new object.
void setPositionAtIndex
(
float
position ,
unsigned int
index ,
MStatus *
ReturnStatus = NULL
)
Sets the position of a given entry.
If there is no entry at the given index, then this method will return a failure.
Parameters
[in] position the new position for the entry
[in] index index of entry to change
[out] ReturnStatus return status
Status Codes:
MS::kSuccess operation successful
MS::kFailure the new node could not be added to the model, or the function set could not be properly initialized with the new object.
Gets the values (y-axis) at the given positions (x-axis)
If this curve is empty, then this method will return a failure. If any position is out of range, either the start or end value will be returned at the corresponding index in the value array.
Parameters
[in] positions the desired x-axis positions
[in] values the y-axis values at the positions
[out] ReturnStatus Status code
Status Codes:
MS::kSuccess operation successful
MS::kFailure this was not a curve ramp, or the ramp was empty
void getValueAtPosition
(
float
position ,
float &
value ,
MStatus *
ReturnStatus = NULL
)
Gets the value (y-axis) at the given position (x-axis) x If this curve is empty, then this method will return a failure.
If the position is out of range, either the start or end value will be returned.
Parameters
[in] position the desired position (x-axis)
[in] value the y-axis value at the position
[out] ReturnStatus Status code
Status Codes:
MS::kSuccess operation successful
MS::kFailure this was not a curve ramp, or the ramp was empty
void sampleValueCurve
(
unsigned int
numberOfSamples ,
MFloatArray &
values ,
MStatus *
ReturnStatus = NULL
)
Perform a linear sampling of this curve ramp and return the results.
If this curve is empty, then this method will return a failure. If the number of samples is less than two this method will return a failure.
Parameters
[in] numberOfSamples The number of times to sample the ramp
[out] values The returned ramp samples
[out] ReturnStatus Status code
Status Codes:
MS::kSuccess Operation successful
MS::kFailure The curve was empty, or too few samples were specified.
bool hasIndex
(
unsigned int
index ,
MStatus *
ReturnStatus = NULL
)
const
Returns true if this curve attribute has an entry defined with a given index.
Parameters
[in] index Index to query.
[out] ReturnStatus Status code
Returns True if the index exists, false otherwise.
Status Codes:
MS::kSuccess Index found.
MS::kFailure Underlying object is invalid. No failure is raised if the index is not found.
MStatus sort
(
bool
ascending = true
)
Sort the curve attribute entries by position in ascending or descending order, other arrays are sorted accordingly.
Indices are also compressed during the operation.
Parameters
[in] ascending Option for sorting in ascending (default) or descending order.
Returns Status code
Status Codes:
MS::kSuccess Operation successful.
MS::kFailure Underlying object is invalid or error while querying the curve.
Change the indices numbering by re-ordering them from 0.
Returns Status code
Status Codes:
MS::kSuccess Operation successful.
MS::kFailure Underlying object is invalid.
Sets this curve attribute with entries defined from a set of float, position value arrays.
Existing entries are deleted before the new ones are added.
Parameters
[in] values Array of float value.
[in] positions Array of desired positions.
Returns Status code
Status Codes:
MS::kSuccess Operation successful
MS::kFailure Not a curve attribute.
MS::kInvalidParameter Array sizes don't match.
This function creates the curve attribute.
Parameters
[in] attrLongName Long name of the curve attribute
[in] attrShortName Short name of the curve attribute
[out] ReturnStatus Return status
Returns Curve ramp attribute, returned as MObject .
Status Codes:
MS::kSuccess operation successful
MS::kFailure when the creation of the attr fails
Creates a new curve attribute initialized with entries defined from a set of float, position value arrays.
Parameters
[in] attrLongName Long name of the new curve attribute
[in] attrShortName Short name of the new curve attribute
[in] node The node to which the new attribute will be added
[in] values Array of float value.
[in] positions Array of desired positions.
[out] ReturnStatus Status code
Status Codes:
MS::kSuccess Operation successful
MS::kFailure Not a curve attribute
MS::kFailure Failure when adding the new entry
MS::kInvalidParameter node is invalid
MS::kInvalidParameter Array sizes don't match.
const char * className
(
)
static
Returns the name of this class.
Returns The name of this class.
The documentation for this class was generated from the following files:
MCurveAttribute.h
MCurveAttribute.cpp