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