Public Types | Public Member Functions | Static Public Member Functions

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.
MRampAttributeoperator= (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) const
 Checks to see whether this ramp is a color ramp.
bool isCurveRamp (MStatus *returnStatus=NULL) const
 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

Interpolation methods.

Enumerator:
kNone 

 

kLinear 

 

kSmooth 

 

kSpline 

 


Constructor & Destructor Documentation

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]otherRamp 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]objPlug of a ramp
[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.
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]nodeNode that contains a ramp attribute
[in]attrThe ramp 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

MRampAttribute & operator= ( const MRampAttribute other)

Assignment operator.

Copies one ramp attribute to another.

Parameters:
[in]otherRamp attribute to be copied
Returns:
A reference to the copied ramp attribute
unsigned int getNumEntries ( MStatus ReturnStatus = NULL)

Gets the number of entries in the ramp attribute.

Parameters:
[out]ReturnStatusreturn status
Status Codes:
Returns:
The number of entries in the ramp attribute
void 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]indicesunique values that specify each entry in the ramp
[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]interpsarray of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]ReturnStatusStatus code.
Status Codes:
Examples:
volumeLightCmd.cpp.
void 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]indicesunique values that specify each entry in the ramp
[out]positionsthe positions of each entry (can range from 0 to 1)
[out]colorsthe colors of the entries at each position
[out]interpsarray of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]ReturnStatusStatus code.
Status Codes:
void 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]positionsthe positions of the new entries (can range from 0 to 1)
[in]colorsthe colors of the new entries at each position
[in]interpsarray of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]ReturnStatusStatus code.
Status Codes:
Examples:
volumeLightCmd.cpp.
void 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]positionsthe positions of the new entries (can range from 0 to 1)
[in]valuesthe values of the new entry at each position
[in]interpsarray of MRampAttribute::MInterpolation values giving the interpolations of the entries at each position.
[out]ReturnStatusStatus code.
Status Codes:
void 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.

A ramp 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 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 
)

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]colorthe new color 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.
Examples:
volumeLightCmd.cpp.
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. If this ramp is a color ramp, 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.
Examples:
volumeLightCmd.cpp.
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.
Examples:
volumeLightCmd.cpp.
void 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]interpthe new interpolation 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.
Examples:
volumeLightCmd.cpp.
bool isColorRamp ( MStatus ReturnStatus = NULL) const

Checks to see whether this ramp is a color ramp.

Parameters:
[out]ReturnStatusreturn 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) const

Checks to see whether this ramp is a curve ramp.

Parameters:
[out]ReturnStatusreturn 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 
)

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]positionthe desired position
[in]colorthe color at the position
[out]ReturnStatusStatus code
[in]contextcontext determining time at which to retrieve the value
Status Codes:
Examples:
volumeLightCmd.cpp.
void 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]positionthe desired position
[in]valuethe value at the position
[out]ReturnStatusStatus code
[in]contextcontext determining time at which to retrieve the value
Status Codes:
Examples:
volumeLightCmd.cpp.
MObject createCurveRamp ( const MString attrLongName,
const MString attrShortName,
MStatus ReturnStatus = NULL 
) [static]

This function creates the curve ramp attribute.

Parameters:
[in]attrLongNameLong name of the curve ramp attribute
[in]attrShortNameShort name of the curve ramp attribute
[out]ReturnStatusreturn status
Returns:
Curve ramp attribute, returned as MObject.
Status Codes:
Examples:
exampleMRampAttribute.cpp.
MObject createColorRamp ( const MString attrLongName,
const MString attrShortName,
MStatus ReturnStatus = NULL 
) [static]

This function creates the color ramp attribute.

Parameters:
[in]attrLongNameLong name of the curve ramp attribute
[in]attrShortNameShort name of the curve ramp attribute
[out]ReturnStatusreturn status
Returns:
Color ramp attribute, returned as MObject.
Status Codes:
Examples:
exampleMRampAttribute.cpp.
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute
MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute MRampAttribute