C++ API Reference
MCurveAttribute Class Reference

Create and manipulate curve attributes. More...

#include <MCurveAttribute.h>

Public Member Functions

 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...
 
MCurveAttributeoperator= (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...
 

Static Public Member Functions

static MObject createCurveAttr (const MString &attrLongName, const MString &attrShortName, MStatus *ReturnStatus=NULL)
 This function creates the curve attribute. More...
 
static MObject createCurve (const MString &attrLongName, const MString &attrShortName, const MObject &node, const MFloatArray &values, const MFloatArray &positions, MStatus *ReturnStatus=NULL)
 Creates a new curve attribute initialized with entries defined from a set of float, position value arrays. More...
 
static const char * className ()
 Returns the name of this class. More...
 

Detailed Description

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.

Examples:
exampleRampAttribute/exampleMRampAttribute.cpp.

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MCurveAttribute ( )

Creates an empty Curve Attribute class.

Initializes it as a null Object.

Status Codes:
None
MCurveAttribute ( const MCurveAttribute other)

Copy constructor operator.

Duplicates the given curve attribute.

Parameters
[in]otherCurve attribute to be copied
Returns
A reference to the copied curve attribute
MCurveAttribute ( const MPlug obj,
MStatus ReturnStatus = NULL 
)

Creates a new Curve Attribute class.

If the plug is not of a Curve, then the constructor will return a failure.

Parameters
[in]objPlug of a curve
[out]ReturnStatusreturn 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.
MCurveAttribute ( const MObject node,
const MObject attr,
MStatus ReturnStatus = NULL 
)

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]nodeNode that contains a ramp attribute
[in]attrThe curve attribute
[out]ReturnStatusreturn 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.

Member Function Documentation

MCurveAttribute & operator= ( const MCurveAttribute other)

Assignment operator.

Copies one curve attribute to another.

Parameters
[in]otherCurve 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]ReturnStatusreturn 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
void getEntries ( MIntArray indices,
MFloatArray positions,
MFloatArray values,
MStatus ReturnStatus = NULL 
)

Gets all the entries in a curve attribute.

Parameters
[out]indicesunique values that specify each entry in the curve
[out]positionsthe positions of each entry (can range from 0 to 1)
[out]valuesthe values of the entries at each position (can range from 0 to 1)
[out]ReturnStatusStatus 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
void addEntries ( MFloatArray positions,
MFloatArray values,
MStatus ReturnStatus = NULL 
)

Adds entries into a curve attribute.

Parameters
[in]positionsthe positions of the new entries (can range from 0 to 1)
[in]valuesthe values of the new entry at each position
[out]ReturnStatusStatus 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
void deleteEntries ( MIntArray indices,
MStatus ReturnStatus = NULL 
)

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]indicesthe entries that need to be deleted
[out]ReturnStatusStatus 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]valuethe new value for the entry
[in]indexindex of entry to change
[out]ReturnStatusreturn 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]positionthe new position for the entry
[in]indexindex of entry to change
[out]ReturnStatusreturn 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 getValuesAtPositions ( const MFloatArray positions,
MFloatArray values,
MStatus ReturnStatus = NULL 
)

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]positionsthe desired x-axis positions
[in]valuesthe y-axis values at the positions
[out]ReturnStatusStatus 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]positionthe desired position (x-axis)
[in]valuethe y-axis value at the position
[out]ReturnStatusStatus 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]numberOfSamplesThe number of times to sample the ramp
[out]valuesThe returned ramp samples
[out]ReturnStatusStatus 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]indexIndex to query.
[out]ReturnStatusStatus 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]ascendingOption 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.
MStatus pack ( )

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.
MStatus setCurve ( const MFloatArray values,
const MFloatArray positions 
)

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]valuesArray of float value.
[in]positionsArray 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.
MObject createCurveAttr ( const MString attrLongName,
const MString attrShortName,
MStatus ReturnStatus = NULL 
)
static

This function creates the curve attribute.

Parameters
[in]attrLongNameLong name of the curve attribute
[in]attrShortNameShort name of the curve attribute
[out]ReturnStatusReturn status
Returns
Curve ramp attribute, returned as MObject.
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure when the creation of the attr fails
Examples:
exampleRampAttribute/exampleMRampAttribute.cpp.
MObject createCurve ( const MString attrLongName,
const MString attrShortName,
const MObject node,
const MFloatArray values,
const MFloatArray positions,
MStatus ReturnStatus = NULL 
)
static

Creates a new curve attribute initialized with entries defined from a set of float, position value arrays.

Parameters
[in]attrLongNameLong name of the new curve attribute
[in]attrShortNameShort name of the new curve attribute
[in]nodeThe node to which the new attribute will be added
[in]valuesArray of float value.
[in]positionsArray of desired positions.
[out]ReturnStatusStatus 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: