MRampAttribute Class Reference

Search for all occurrences

---

Detailed Description

Create and manipulate ramp attributes.

A ramp attribute consists of a set of entries describing a 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 that position maps onto, and an enumerator indicating the type of interpolation to use between that position and the next.

Currently two types of output values are a supported: a float, in which case the attribute is displayed as a curve in the Attribute Editor, or a color, in which case the attribute is displayed as a color gradient, similar to how a ramp texture node is displayed.

A ramp must always have at least one entry. A newly-created ramp attribute will automatically be given a default entry at position 0.0 with a value of 0.0 or black, depending upon the ramp type.

Any attempt to delete the last of a ramp's entries will fail. This means that if you want to initialize a newly-created ramp attribute with a specific set of entries you must add at least one of your new entries first before deleting the default entry. Alternatively, you can modify the default entry to match one of your new entries and then add your remaining entries.

Examples:

volumeLightCmd.cpp.

#include <MRampAttribute.h>

List of all members.

Public Types
enum	MInterpolation { kNone = 0, kLinear = 1, kSmooth = 2, kSpline = 3 }
	Interpolation methods. More...
Public Member Functions
	MRampAttribute ()
	Creates an emptry Ramp Attribute class.
	MRampAttribute (const MRampAttribute &other)
	Copy constructor operator.
	MRampAttribute (const MPlug &obj, MStatus *ReturnStatus=NULL)
	Creates a new Ramp Attribute class.
	MRampAttribute (const MObject &node, const MObject &attr, MStatus *ReturnStatus=NULL)
	Creates a new Ramp Attribute class.
MRampAttribute &	operator= (const MRampAttribute &other)
	Assignment operator.
	~MRampAttribute ()
	Destructor.
unsigned int	getNumEntries (MStatus *returnStatus=NULL)
	Gets the number of entries in the ramp attribute.
void	getEntries (MIntArray &indexes, MFloatArray &positions, MFloatArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
	Gets all the entries in a ramp attribute.
void	getEntries (MIntArray &indexes, MFloatArray &positions, MColorArray &colors, MIntArray &interps, MStatus *returnStatus=NULL)
	Gets all the entries in a ramp attribute.
void	addEntries (MFloatArray &positions, MColorArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
	Adds entries into a ramp attribute.
void	addEntries (MFloatArray &positions, MFloatArray &values, MIntArray &interps, MStatus *returnStatus=NULL)
	Adds entries into a ramp attribute.
void	deleteEntries (MIntArray &indexes, MStatus *returnStatus=NULL)
	Deletes entries in the ramp attribute.
void	setColorAtIndex (MColor &color, unsigned int index, MStatus *returnStatus=NULL)
	Sets the color of a given entry.
void	setValueAtIndex (float value, unsigned int index, MStatus *returnStatus=NULL)
	Sets the value of a given entry.
void	setPositionAtIndex (float position, unsigned int index, MStatus *returnStatus=NULL)
	Sets the position of a given entry.
void	setInterpolationAtIndex (MRampAttribute::MInterpolation interp, unsigned int index, MStatus *returnStatus=NULL)
	Sets the interpolation of a given entry.
bool	isColorRamp (MStatus *returnStatus=NULL)
	Checks to see whether this ramp is a color ramp.
bool	isCurveRamp (MStatus *returnStatus=NULL)
	Checks to see whether this ramp is a curve ramp.
void	getColorAtPosition (float position, MColor &color, MStatus *returnStatus=NULL, MDGContext &=MDGContext::fsNormal)
	Gets the color at a position.
void	getValueAtPosition (float position, float &value, MStatus *returnStatus=NULL, MDGContext &=MDGContext::fsNormal)
	Gets the value at position.
Static Public Member Functions
static MObject	createCurveRamp (const MString &attrLongName, const MString &attrShortName, MStatus *ReturnStatus=NULL)
	This function creates the curve ramp attribute.
static MObject	createColorRamp (const MString &attrLongName, const MString &attrShortName, MStatus *ReturnStatus=NULL)
	This function creates the color ramp attribute.
static const char *	className ()
	Returns the name of this class.

---

Member Enumeration Documentation

enum MInterpolation

Search for all occurrences

Interpolation methods.

Enumerator:

kNone	Search for all occurrences
kLinear	Search for all occurrences
kSmooth	Search for all occurrences
kSpline	Search for all occurrences

---

Constructor & Destructor Documentation

MRampAttribute

(

)

Creates an emptry Ramp Attribute class.

Initializes it as a null Object.

Status Codes:

None

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

---

Member Function Documentation

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 getNumEntries

(

MStatus *

ReturnStatus = NULL

)

Search for all occurrences

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 getEntries	(	MIntArray &	indices,
		MFloatArray &	positions,
		MFloatArray &	values,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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	array of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]	ReturnStatus	Status code.

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 getEntries	(	MIntArray &	indices,
		MFloatArray &	positions,
		MColorArray &	colors,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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	array of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]	ReturnStatus	Status code.

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 addEntries	(	MFloatArray &	positions,
		MColorArray &	colors,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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	array of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]	ReturnStatus	Status code.

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 addEntries	(	MFloatArray &	positions,
		MFloatArray &	values,
		MIntArray &	interps,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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	array of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]	ReturnStatus	Status code.

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 deleteEntries	(	MIntArray &	indices,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

Deletes entries in the ramp attribute.

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

A ramp 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 ramp entries. It is not valid to delete all entries in a ramp.

Examples:

volumeLightCmd.cpp.

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

Search for all occurrences

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

Examples:

volumeLightCmd.cpp.

void setValueAtIndex	(	float	value,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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

Examples:

volumeLightCmd.cpp.

void setPositionAtIndex	(	float	position,
		unsigned int	index,
		MStatus *	ReturnStatus = NULL
	)

Search for all occurrences

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.

Examples:

volumeLightCmd.cpp.

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

Search for all occurrences

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

Examples:

volumeLightCmd.cpp.

bool isColorRamp

(

MStatus *

ReturnStatus = NULL

)

Search for all occurrences

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 isCurveRamp

(

MStatus *

ReturnStatus = NULL

)

Search for all occurrences

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

Search for all occurrences

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	Status code
[in]	context	context determining time at which to retrieve the value

Status Codes:

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

Examples:

volumeLightCmd.cpp.

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

Search for all occurrences

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	Status code
[in]	context	context determining time at which to retrieve the value

Status Codes:

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

Examples:

volumeLightCmd.cpp.

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

Search for all occurrences

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 createColorRamp	(	const MString &	attrLongName,
		const MString &	attrShortName,
		MStatus *	ReturnStatus = NULL
	)		[static]

Search for all occurrences

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.

const char * className

(

)

[static]

Search for all occurrences

Returns the name of this class.

Returns:

The name of this class.