- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MRampAttribute Class Reference
OpenMaya - API module for common classes

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

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` | ) | const

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` | ) | const

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.

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