MRampAttribute Class Reference
[OpenMaya - API module for common classes]

#include <MRampAttribute.h>

List of all members.

---

Detailed Description

Ramp data attribute function wrapper class.

Function object for RampData attributes. A RampData attribute describes a ramp specified by a set of positions and values. Currently there is support for curve ramps and color ramps.

Examples:

volumeLightCmd.cpp.

Public Types
enum	MInterpolation { kLinear = 0, kNone = 1, kSpline = 2, kSmooth = 3 }
	Interpolation methods. More...
Public Member Functions
	MRampAttribute ()
	MRampAttribute (const MRampAttribute &other)
	MRampAttribute (const MPlug &obj, MStatus *ReturnStatus=NULL)
	MRampAttribute (const MObject &node, const MObject &attr, MStatus *ReturnStatus=NULL)
MRampAttribute &	operator= (const MRampAttribute &other)
	~MRampAttribute ()
unsigned int	getNumEntries (MStatus *returnStatus=NULL)
void	getEntries (MIntArray &indexes, MFloatArray &positions, MFloatArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
void	getEntries (MIntArray &indexes, MFloatArray &positions, MColorArray &colors, MIntArray &interps, MStatus *returnStatus=NULL)
void	addEntries (MFloatArray &positions, MColorArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
void	addEntries (MFloatArray &positions, MFloatArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
void	deleteEntries (MIntArray &indexes, MStatus *returnStatus=NULL)
void	setColorAtIndex (MColor &color, unsigned int index, MStatus *returnStatus=NULL)
void	setValueAtIndex (float value, unsigned int index, MStatus *returnStatus=NULL)
void	setPositionAtIndex (float position, unsigned int index, MStatus *returnStatus=NULL)
void	setInterpolationAtIndex (MRampAttribute::MInterpolation interp, unsigned int index, MStatus *returnStatus=NULL)
bool	isColorRamp (MStatus *returnStatus=NULL)
bool	isCurveRamp (MStatus *returnStatus=NULL)
void	getColorAtPosition (float position, MColor &color, MStatus *returnStatus=NULL, MDGContext &=MDGContext::fsNormal)
void	getValueAtPosition (float position, float &value, MStatus *returnStatus=NULL, MDGContext &=MDGContext::fsNormal)
Static Public Member Functions
static MObject	createCurveRamp (const MString &attrLongName, const MString &attrShortName, MStatus *ReturnStatus=NULL)
static MObject	createColorRamp (const MString &attrLongName, const MString &attrShortName, MStatus *ReturnStatus=NULL)

---

Member Enumeration Documentation

enum MRampAttribute::MInterpolation

Interpolation methods.

Enumerator:

kLinear
kNone
kSpline
kSmooth

---

Constructor & Destructor Documentation

MRampAttribute::MRampAttribute

(

)

Creates an emptry Ramp Attribute class.

Initializes it as a null Object.

Status Codes:

None

MRampAttribute::MRampAttribute

(

const MRampAttribute &

other

)

Copy constructor operator. Duplicates the given ramp attribute.

Parameters:

[in]

other

Ramp attribute to be copied

Returns:

A reference to the copied ramp attribute

MRampAttribute::MRampAttribute	(	const MPlug &	obj,
		MStatus *	ReturnStatus = NULL
	)

Creates a new Ramp Attribute class. If the plug is not of a ramp, then the constructor will return a failure.

Parameters:

[in]	obj	Plug of a ramp
[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.

MRampAttribute::MRampAttribute	(	const MObject &	node,
		const MObject &	attr,
		MStatus *	ReturnStatus = NULL
	)

Creates a new Ramp Attribute class. If the node does not have that attribute then the constructor will return a failure. If the attribute is not of a ramp the constructor will also fail.

Parameters:

[in]	node	Node that contains a ramp attribute
[in]	attr	The ramp 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.

MRampAttribute::~MRampAttribute

(

)

Destructor

---

Member Function Documentation

MRampAttribute & MRampAttribute::operator=

(

const MRampAttribute &

other

)

Assignment operator. Copies one ramp attribute to another.

Parameters:

[in]

other

Ramp attribute to be copied

Returns:

A reference to the copied ramp attribute

unsigned int MRampAttribute::getNumEntries

(

MStatus *

ReturnStatus = NULL

)

Gets the number of entries in the ramp attribute.

Parameters:

[out]

ReturnStatus

return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure an error occurred while querying the ramp

Returns:

The number of entries in the ramp attribute

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

Gets all the entries in a ramp attribute. If the ramp is a color ramp, then this function will return a failure.

Parameters:

[out]	indices	unique values that specify each entry in the ramp
[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]	interps	the interpolations of the entries at each position. Possible values:

• MRampAttribute::kSpline
• MRampAttribute::kSmooth
• MRampAttribute::kLinear
• MRampAttribute::kNone

• ReturnStatus return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the specified attribute is not a curve ramp attribute
• MS::kFailure an error occurred while retrieving the ramp entries

Examples:

volumeLightCmd.cpp.

void MRampAttribute::getEntries	(	MIntArray &	indices,
		MFloatArray &	positions,
		MColorArray &	colors,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Gets all the entries in a ramp attribute. If the ramp is a curve ramp, then this function will return a failure.

Parameters:

[out]	indices	unique values that specify each entry in the ramp
[out]	positions	the positions of each entry (can range from 0 to 1)
[out]	colors	the colors of the entries at each position
[out]	interps	the interpolations of the entries at each position. Possible values:

• MRampAttribute::kSpline
• MRampAttribute::kSmooth
• MRampAttribute::kLinear
• MRampAttribute::kNone

• ReturnStatus return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the specified attribute is not a color ramp attribute
• MS::kFailure an error occurred while retrieving the ramp entries

void MRampAttribute::addEntries	(	MFloatArray &	positions,
		MColorArray &	colors,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Adds entries into a ramp attribute. If the ramp is a curve ramp, then this function will return a failure.

Parameters:

[in]	positions	the positions of the new entries (can range from 0 to 1)
[in]	colors	the colors of the new entries at each position
[in]	interps	the interpolations of the new entries at each position. Possible values:

• MRampAttribute::kSpline
• MRampAttribute::kSmooth
• MRampAttribute::kLinear
• MRampAttribute::kNone

• ReturnStatus return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the attribute is not a color ramp attribute or array sizes do not match
• MS::kFailure an error occurred while adding ramp entries

Examples:

volumeLightCmd.cpp.

void MRampAttribute::addEntries	(	MFloatArray &	positions,
		MFloatArray &	values,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Adds entries into a ramp attribute. If the ramp is a color ramp, then this function will return a failure.

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
[in]	interps	the interpolations of the new entry at each position. Possible values:

• MRampAttribute::kSpline
• MRampAttribute::kSmooth
• MRampAttribute::kLinear
• MRampAttribute::kNone

• ReturnStatus return status

Status Codes:

• MS::kSuccess operation successful
• MS::kInvalidParameter the attribute is not a curve ramp attribute or array sizes do not match
• MS::kFailure an error occurred while adding ramp entries

void MRampAttribute::deleteEntries	(	MIntArray &	indices,
		MStatus *	ReturnStatus = NULL
	)

Deletes entries in the ramp attribute.

If any one of the indices is incorrect, then this function will not delete any of the entries.

Parameters:

[in]	indices	the entries that need to be deleted
[out]	ReturnStatus	return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure an error occured while deleting ramp entries. It is not valid to delete all entries in a ramp.

Examples:

volumeLightCmd.cpp.

void MRampAttribute::setColorAtIndex	(	MColor &	color,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)

Sets the color of a given entry

If there is no entry at the given index, then this method will return a failure. If this ramp is a curve ramp, then this method will return a failure.

Parameters:

[in]	color	the new color for the entry
[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.

Examples:

volumeLightCmd.cpp.

void MRampAttribute::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. If this ramp is a color ramp, then this method will return a failure.

Parameters:

[in]	value	the new value for the entry
[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.

Examples:

volumeLightCmd.cpp.

void MRampAttribute::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
[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.

Examples:

volumeLightCmd.cpp.

void MRampAttribute::setInterpolationAtIndex	(	MRampAttribute::MInterpolation	interp,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)

Sets the interpolation of a given entry

If there is no entry at the given index, then this method will return a failure.

Parameters:

[in]	interp	the new interpolation for the entry
[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.

Examples:

volumeLightCmd.cpp.

bool MRampAttribute::isColorRamp

(

MStatus *

ReturnStatus = NULL

)

Checks to see whether this ramp is a color ramp.

Parameters:

[out]

ReturnStatus

return status

Returns:

true if the ramp is a color ramp, false otherwise

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.

bool MRampAttribute::isCurveRamp

(

MStatus *

ReturnStatus = NULL

)

Checks to see whether this ramp is a curve ramp.

Parameters:

[out]

ReturnStatus

return status

Returns:

true if the ramp is a curve ramp, false otherwise

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 MRampAttribute::getColorAtPosition	(	float	position,
		MColor &	color,
		MStatus *	ReturnStatus = NULL,
		MDGContext &	context = MDGContext::fsNormal
	)

Gets the color at a position

If this ramp is a curve ramp, then this method will return a failure. If this ramp 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
[in]	color	the color at the position
[out]	ReturnStatus	return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this was not a color ramp, or the ramp was empty

Examples:

volumeLightCmd.cpp.

void MRampAttribute::getValueAtPosition	(	float	position,
		float &	value,
		MStatus *	ReturnStatus = NULL,
		MDGContext &	context = MDGContext::fsNormal
	)

Gets the value at position

If this ramp is a color ramp, then this method will return a failure. If this ramp 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
[in]	value	the value at the position
[out]	ReturnStatus	return status

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure this was not a curve ramp, or the ramp was empty

Examples:

volumeLightCmd.cpp.

MObject MRampAttribute::createCurveRamp	(	const MString &	attrLongName,
		const MString &	attrShortName,
		MStatus *	ReturnStatus = NULL
	)			[static]

This function creates the curve ramp attribute.

Parameters:

[in]	attrLongName	Long name of the curve ramp attribute
[in]	attrShortName	Short name of the curve ramp 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:

exampleMRampAttribute.cpp.

MObject MRampAttribute::createColorRamp	(	const MString &	attrLongName,
		const MString &	attrShortName,
		MStatus *	ReturnStatus = NULL
	)			[static]

This function creates the color ramp attribute.

Parameters:

[in]	attrLongName	Long name of the curve ramp attribute
[in]	attrShortName	Short name of the curve ramp attribute
[out]	ReturnStatus	return status

Returns:

Color ramp attribute, returned as MObject.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure when the creation of the attr fails

Examples:

exampleMRampAttribute.cpp.