#include <MCurveAttribute.h>

Class 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.

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...

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...

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...

Constructor & Destructor Documentation

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] other Curve 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]	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.

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]	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.

Member Function Documentation

MCurveAttribute & operator= ( const MCurveAttribute & other )

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

void getEntries	(	MIntArray &	indices,
		MFloatArray &	positions,
		MFloatArray &	values,
		MStatus *	ReturnStatus = `NULL`
	)

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

void addEntries	(	MFloatArray &	positions,
		MFloatArray &	values,
		MStatus *	ReturnStatus = `NULL`
	)

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

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]	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.

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]	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.

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]	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.

MObject createCurveAttr	(	const MString &	attrLongName,
		const MString &	attrShortName,
		MStatus *	ReturnStatus = `NULL`
	)

static

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

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]	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

MCurveAttribute Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation