MFnAttribute Class Reference
[OpenMaya - API module for common classes, FunctionSet classes]

#include <MFnAttribute.h>
Inheritance diagram for MFnAttribute:
Inheritance graph
[legend]
Collaboration diagram for MFnAttribute:
Collaboration graph
[legend]

List of all members.

Detailed Description

Dependency node attribute function set.

MFnAttribute is the function set for dependency node attributes.

An attribute of a dependency node describes a piece of data that belongs to nodes of that type. For example, a node that makes a sphere might have a radius attribute. A node's attributes describe connections sites on the node that can be used in the dependency graph.

Attributes typically belong to a class of nodes, rather than to an individual node. For example, all sphere nodes have a radius. Even though a single attribute may be shared by all nodes of a given type, each node will have its own value for the attribute.

Attributes are heirarchical. For example, the translate scale attribute of a transform has x, y, and z child attributes.

By default, attributes are:

Examples:

animExportUtil.cpp, apiMeshShape.cpp, cgfxAttrDef.cpp, dagPoseInfoCmd.cpp, getAttrAffectsCmd.cpp, and maTranslator.cpp.


Public Types
enum   DisconnectBehavior { kDelete, kReset, kNothing }
  Attribute behaviour on disconnect. More...

Public Member Functions
virtual MFn::Type  type () const
  Function set type.
virtual  ~MFnAttribute ()
  Destructor.
  MFnAttribute ()
  Default constructor.
  MFnAttribute (MObject &object, MStatus *ReturnStatus=NULL)
  Constructor.
bool  isReadable (MStatus *ReturnStatus=NULL) const
bool  isWritable (MStatus *ReturnStatus=NULL) const
bool  isConnectable (MStatus *ReturnStatus=NULL) const
bool  isStorable (MStatus *ReturnStatus=NULL) const
bool  isCached (MStatus *ReturnStatus=NULL) const
bool  isArray (MStatus *ReturnStatus=NULL) const
bool  indexMatters (MStatus *ReturnStatus=NULL) const
bool  isKeyable (MStatus *ReturnStatus=NULL) const
bool  isChannelBoxFlagSet (MStatus *ReturnStatus=NULL) const
bool  isHidden (MStatus *ReturnStatus=NULL) const
bool  isUsedAsColor (MStatus *ReturnStatus=NULL) const
bool  isIndeterminant (MStatus *ReturnStatus=NULL) const
bool  isRenderSource (MStatus *ReturnStatus=NULL) const
bool  isDynamic (MStatus *ReturnStatus=NULL) const
bool  isWorldSpace (MStatus *ReturnStatus=NULL) const
bool  isAffectsWorldSpace (MStatus *ReturnStatus=NULL) const
DisconnectBehavior  disconnectBehavior (MStatus *ReturnStatus=NULL) const
bool  usesArrayDataBuilder (MStatus *ReturnStatus=NULL) const
bool  internal (MStatus *ReturnStatus=NULL) const
MStatus  setReadable (bool state)
MStatus  setWritable (bool state)
MStatus  setConnectable (bool state)
MStatus  setStorable (bool state)
MStatus  setCached (bool state)
MStatus  setArray (bool state)
MStatus  setIndexMatters (bool state)
MStatus  setKeyable (bool state)
MStatus  setChannelBox (bool state)
MStatus  setHidden (bool state)
MStatus  setUsedAsColor (bool state)
MStatus  setIndeterminant (bool state)
MStatus  setRenderSource (bool state)
MStatus  setWorldSpace (bool state)
MStatus  setAffectsWorldSpace (bool state)
MStatus  setDisconnectBehavior (DisconnectBehavior behavior)
MStatus  setUsesArrayDataBuilder (bool state)
MStatus  setInternal (bool state)
bool  accepts (MFnData::Type type, MStatus *ReturnStatus=NULL) const
bool  accepts (const MTypeId &id, MStatus *ReturnStatus=NULL) const
MObject  parent (MStatus *ReturnStatus=NULL) const
MStatus  setParent (const MObject &parent)
MString  name (MStatus *ReturnStatus=NULL) const
MString  shortName (MStatus *ReturnStatus=NULL) const
MString  getAddAttrCmd (bool useLongName=false, MStatus *status=NULL) const
  MFnAttribute (const MObject &object, MStatus *ReturnStatus=NULL)
  NO SCRIPT SUPPORT.

Protected Member Functions
virtual const char *  className () const
  Class name.

Member Enumeration Documentation

enum MFnAttribute::DisconnectBehavior

Attribute behaviour on disconnect.

Enumerator:
kDelete  Delete array element (array attributes only).
kReset  Reset the attribute to its default.
kNothing  Do nothing to the attribute's value.

Constructor & Destructor Documentation

MFnAttribute::MFnAttribute ( MObject &  object,
MStatus *  ReturnStatus = NULL  
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:
[in]  object  The MObject to attach the function set to
[out]  ReturnStatus  the return status
Status Codes:

MFnAttribute::MFnAttribute ( const MObject &  object,
MStatus *  ReturnStatus = NULL  
)

NO SCRIPT SUPPORT.

Constructor

Class constructor that initializes the function set to the given MObject.

Parameters:
[in]  object  The MObject to attach the function set to
[out]  ReturnStatus  the return status
Status Codes:

Member Function Documentation

MFn::Type MFnAttribute::type (  )  const [virtual]

Function set type.

Return the class type : MFn::kAttribute

Reimplemented from MFnBase.

Reimplemented in MFnCompoundAttribute, MFnEnumAttribute, MFnGenericAttribute, MFnLightDataAttribute, MFnMatrixAttribute, MFnMessageAttribute, MFnNumericAttribute, MFnTypedAttribute, and MFnUnitAttribute.

const char * MFnAttribute::className (  )  const [protected, virtual]

Class name.

Return the class name : "MFnAttribute"

Reimplemented from MFnBase.

Reimplemented in MFnCompoundAttribute, MFnEnumAttribute, MFnGenericAttribute, MFnLightDataAttribute, MFnMatrixAttribute, MFnMessageAttribute, MFnNumericAttribute, MFnTypedAttribute, and MFnUnitAttribute.

bool MFnAttribute::isReadable ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is readable. If an attribute is readable, then it can be used as the source in a dependency graph connection.

Attributes are readable by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is readable
Status Codes:

bool MFnAttribute::isWritable ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is writable. If an attribute is writable, then it can be used as the destination in a dependency graph connection.

Attributes are writable by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is writable
Status Codes:

bool MFnAttribute::isConnectable ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute accepts dependency graph connections. If it does, then the readable and writable methods will indicate what types of connections are accepted.

Attributes are connectable by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is connectable
Status Codes:

bool MFnAttribute::isStorable ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is to be stored when the node is saved to a file.

Attributes are storable by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is storable
Status Codes:
  • kSuccess operation successful
  • kFailure this function set does not have a valid attribute object

bool MFnAttribute::isCached ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is cached locally in the node's data block. The default for this is true. Caching a node locally causes a copy of the attribute value for the node to be cached with the node. This removes the need to traverse through the graph to get the value each time it is requested.

Caching the value locally gives a speed increase at the cost of more memory.

Attributes are cached by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is cached locally
Status Codes:
  • kSuccess operation successful
  • kFailure this function set does not have a valid attribute object

bool MFnAttribute::isArray ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute supports an array of data.

Attributes are single elements by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute stores an array of data
Status Codes:

bool MFnAttribute::indexMatters ( MStatus *  ReturnStatus = NULL  )  const

Determines whether the user must specify an index when connecting to this attribute, or whether the next available index can be used. This method only applies to array attributes which are non readable, i.e. destination attributes.

This corresponds with the connectAttr command's -na/nextAvailable flag. If the destination attribute has set the indexMatters to be false with this flag specified, a connection is made to the next available index. No index need be specified

The index matters to attributes by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
  • true The user must specify the index when connecting to this attribute using connectAttr
  • false The next available index can be used when connecting to this attribute using connectAttr -na
Status Codes:

bool MFnAttribute::isKeyable ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is keyable. Keyable attributes will be keyed by AutoKey and the Set Keyframe UI. Non-keyable attributes prevent the user from setting keys via the obvious UI provided for keying. Being non-keyable is not a hard block against adding keys to an attribute.

This method determines the default keyability of a plug. The keyability can be changed after it is created. Use the MPlug::isKeyable method to determine whether or not a specific plug is keyable.

Attributes are not keyable by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is keyable
Status Codes:

bool MFnAttribute::isChannelBoxFlagSet ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute has its channel box flag set. Attributes will appear in the channel box if their channel box flag is set or if they are keyable.

This method returns the default channel box display state of a plug. The display can be changed after it is created. Use the MPlug::isChannelBox method to determine whether or not a specific plug is displayed in the channel box.

Attributes are not in the channel box by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating the status of the channel box flag on this attribute
Status Codes:

bool MFnAttribute::isHidden ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is to hidden from the UI. The attribute will not show up in attribute editors.

Attributes are not hidden by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is hidden
Status Codes:

bool MFnAttribute::isUsedAsColor ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is to be presented as a color in the UI.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is used as a color
Status Codes:

bool MFnAttribute::isIndeterminant ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is indeterminant. If an attribute may or may not be used during an evaluation then it is indeterminant. This attribute classification is mainly used on rendering nodes to indicate that some attributes are not always used.

Attributes are not indeterminant by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is indeterminant
Status Codes:

bool MFnAttribute::isRenderSource ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is a render source. This attribute is used on rendering nodes to override the rendering sampler info.

Attributes are not render source by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is render source
Status Codes:

bool MFnAttribute::isDynamic ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is a dynamic attribute.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is dynamic
Status Codes:

bool MFnAttribute::isWorldSpace ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute is worldspace.

Attributes are not worldspace by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute is worldspace
Status Codes:

bool MFnAttribute::isAffectsWorldSpace ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute affects worldspace.

Attributes do not affect worldspace by default.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute affects worldspace
Status Codes:

MFnAttribute::DisconnectBehavior MFnAttribute::disconnectBehavior ( MStatus *  ReturnStatus = NULL  )  const

Returns the behavior of this attribute when it is disconnected. The possible settings are as follows:

  • kDelete delete the element of the array that was connected. This is only used for array attributes
  • kReset reset the attribute to its default value
  • kNothing leave the attribute set to its last known value
Attributes have a default disconnect behavior of kNothing.
Parameters:
[out]  ReturnStatus  return status
Returns:
The disconnect behavior
Status Codes:

bool MFnAttribute::usesArrayDataBuilder ( MStatus *  ReturnStatus = NULL  )  const

Returns true if this attribute uses an array data builder. If so, then the MArrayDataBuilder class may be used with this attribute.

By default array attributes do not use an array data builder.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute uses an array data builder.
Status Codes:

bool MFnAttribute::internal ( MStatus *  ReturnStatus = NULL  )  const

Returns true if a node has internal member data representing this attribute.

Parameters:
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether this attribute uses internal data
Status Codes:

MStatus MFnAttribute::setReadable ( bool  state  ) 

Sets whether this attribute should be readable. If an attribute is readable, then it can be used as the source in a dependency graph connection.

Attributes are readable by default.

Parameters:
[in]  state  whether the attribute is to be readable
Returns:
Return status
Status Codes:
Examples:
anisotropicShader.cpp, backfillShader.cpp, clearcoat.cpp, closestPointOnCurveNode.cpp, curvedArrowsNode.cpp, cvColorShader.cpp, displacementShader.cpp, dynExprField.cpp, geometrySurfaceConstraint.cpp, hwDecalBumpShader_NV20.cpp, hwReflectBumpShader_NV20.cpp, hwToonShader_NV20.cpp, interpShader.cpp, lambertShader.cpp, lightShader.cpp, multiCurveNode.cpp, phongShader.cpp, pointOnMeshInfoNode.cpp, pointOnSubdNode.cpp, shadowMatteShader.cpp, shiftNode.cpp, slopeShaderNode.cpp, stringFormatNode.cpp, volumeShader.cpp, and weightListNode.cpp.

MStatus MFnAttribute::setWritable ( bool  state  ) 

Sets whether this attribute should be writable. If an attribute is writable, then it can be used as the destination in a dependency graph connection. If an attribute is not writable then setAttr commands will fail to change the attribute.

If both keyable and writable for an attribute are set to true it will be displayed in the channel box when the node is selected.

Attributes are writable by default.

Parameters:
[in]  state  whether the attribute is to be writable
Returns:
Return status
Status Codes:
Examples:
anisotropicShader.cpp, arcLenNode.cpp, backfillShader.cpp, cgfxVector.cpp, circleNode.cpp, clearcoat.cpp, closestPointOnCurveNode.cpp, curvedArrowsNode.cpp, cvColorShader.cpp, displacementShader.cpp, dynExprField.cpp, footPrintManip.cpp, genericAttributeNode.cpp, geometrySurfaceConstraint.cpp, GLSLShaderNode.cpp, hlslShader.cpp, hwDecalBumpShader_NV20.cpp, hwReflectBumpShader_NV20.cpp, hwToonShader_NV20.cpp, interpShader.cpp, jitterNode.cpp, lambertShader.cpp, latticeNoiseNode.cpp, lightShader.cpp, meshOpNode.cpp, multiCurveNode.cpp, particleAttrNode.cpp, phongShader.cpp, pointOnMeshInfoNode.cpp, pointOnSubdNode.cpp, renderAccessNode.cpp, shadowMatteShader.cpp, shellNode.cpp, shiftNode.cpp, sineNode.cpp, slopeShaderNode.cpp, splitUVNode.cpp, stringFormatNode.cpp, swissArmyManip.cpp, testNobjectNode.cpp, testNucleusNode.cpp, transCircleNode.cpp, and volumeShader.cpp.

MStatus MFnAttribute::setConnectable ( bool  state  ) 

Sets whether this attribute should allow dependency graph connections. This should only get called in the initialize call of your node creator.

Attributes are connectable by default.

Parameters:
[in]  state  whether the attribute is to be connectable
Returns:
Return status
Status Codes:
Examples:
buildRotationNode.cpp, cgfxShaderNode.cpp, GLSLShaderNode.cpp, and offsetNode.cpp.

MStatus MFnAttribute::setStorable ( bool  state  ) 

Sets whether this attribute should be storable. If an attribute is storable, then it will be writen out when the node is stored to a file. This should only get called in the initialize call of your node creator.

Attributes are storable by default.

NOTE: Typed attributes of setting MFnData::kDynArrayAttrs are not storable.

Parameters:
[in]  state  whether the attribute is to be storable
Returns:
Return status
Status Codes:
Examples:
animCubeNode.cpp, anisotropicShader.cpp, backfillShader.cpp, blindDataMesh.cpp, buildRotationNode.cpp, cgfxVector.cpp, circleNode.cpp, clearcoat.cpp, closestPointOnCurveNode.cpp, curvedArrowsNode.cpp, customImagePlane.cpp, cvColorShader.cpp, displacementShader.cpp, dynExprField.cpp, footPrintManip.cpp, fullLoftNode.cpp, genericAttributeNode.cpp, geomShader.cpp, GLSLShaderNode.cpp, hlslShader.cpp, hwAnisotropicShader_NV20.cpp, hwColorPerVertexShader.cpp, hwDecalBumpShader_NV20.cpp, hwPhongShader.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, interpShader.cpp, jitterNode.cpp, lambertShader.cpp, lightShader.cpp, meshOpNode.cpp, offsetNode.cpp, particleAttrNode.cpp, phongShader.cpp, pnTrianglesNode.cpp, pointOnMeshInfoNode.cpp, pointOnSubdNode.cpp, renderAccessNode.cpp, shadowMatteShader.cpp, shellNode.cpp, shiftNode.cpp, simpleLoftNode.cpp, sineNode.cpp, slopeShaderNode.cpp, splitUVNode.cpp, stringFormatNode.cpp, swissArmyManip.cpp, testNobjectNode.cpp, testNucleusNode.cpp, transCircleNode.cpp, and volumeShader.cpp.

MStatus MFnAttribute::setCached ( bool  state  ) 

Sets whether the data for this attribute is cached locally in the node's data block. The default for this is true. Caching a node locally causes a copy of the attribute value for the node to be cached with the node. This removes the need to traverse through the graph to get the value each time it is requested. This should only get called in the initialize call of your node creator.

Caching the value locally gives a speed increase at the cost of more memory.

Attributes are cached by default.

Parameters:
[in]  state  whether the attribute is to be cached locally
Returns:
Return status
Status Codes:
Examples:
closestPointOnCurveNode.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, pointOnMeshInfoNode.cpp, pointOnSubdNode.cpp, and shellNode.cpp.

MStatus MFnAttribute::setArray ( bool  state  ) 

Sets whether this attribute should have an array of data. This should be set to true if the attribute needs to accept multiple incoming connections.

Attributes are single elements by default.

Parameters:
[in]  state  whether the attribute is to have an array of data
Returns:
Return status
Status Codes:
Examples:
anisotropicShader.cpp, backfillShader.cpp, cgfxShaderNode.cpp, fullLoftNode.cpp, geometrySurfaceConstraint.cpp, lambertShader.cpp, multiCurveNode.cpp, phongShader.cpp, shadowMatteShader.cpp, slopeShaderNode.cpp, stringFormatNode.cpp, testNucleusNode.cpp, and weightListNode.cpp.

MStatus MFnAttribute::setIndexMatters ( bool  state  ) 

If the attribute is an array, then this method specifies whether to force the user to specify an index when connecting to this attribute, or to use the next available index.

This corresponds with the connectAttr command's -na/nextAvailable flag. If the destination attribute has set the indexMatters to be false with this flag specified, a connection is made to the next available index. No index need be specified

This method will only affect array attributes with setReadable set to false, i.e. destination attributes.

The index matters to attributes by default.

Parameters:
[in]  state  whether the attribute's index must be specified when connecting to this attribute using the connectAttr command
Returns:
Return status
Status Codes:
Examples:
slopeShaderNode.cpp, and stringFormatNode.cpp.

MStatus MFnAttribute::setKeyable ( bool  state  ) 

Sets whether this attribute should accept keyframe data. This should only get called in the initialize call of your node creator. Keyable attributes will be keyed by AutoKey and the Set Keyframe UI. Non-keyable attributes prevent the user from setting keys via the obvious UI provided for keying. Being non-keyable is not a hard block against adding keys to an attribute.

This method changes the default state of a plug. The keyability of a specific plug can be changed using the MPlug::setKeyable method.

If both keyable and writable for an attribute are set to true it will be displayed in the channel box when the node is selected.

Attributes are not keyable by default.

Parameters:
[in]  state  whether the attribute is to be keyable
Returns:
Return status
Status Codes:
Examples:
apiMeshCreator.cpp, cgfxAttrDef.cpp, cgfxShaderNode.cpp, cgfxVector.cpp, closestPointOnCurveNode.cpp, curvedArrowsNode.cpp, customImagePlane.cpp, displacementShader.cpp, dynExprField.cpp, genericAttributeNode.cpp, geometrySurfaceConstraint.cpp, GLSLShaderNode.cpp, hlslShader.cpp, hwAnisotropicShader_NV20.cpp, hwColorPerVertexShader.cpp, hwDecalBumpShader_NV20.cpp, hwPhongShader.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, interpShader.cpp, lambertShader.cpp, lightShader.cpp, meshOpNode.cpp, multiCurveNode.cpp, pnTrianglesNode.cpp, pointOnMeshInfoNode.cpp, pointOnSubdNode.cpp, quadricShape.cpp, rockingTransform.cpp, shadowMatteShader.cpp, shellNode.cpp, simpleSpring.cpp, slopeShaderNode.cpp, stringFormatNode.cpp, torusField.cpp, volumeShader.cpp, weightListNode.cpp, and yTwistNode.cpp.

MStatus MFnAttribute::setChannelBox ( bool  state  ) 

Sets whether this attribute should appear in the channel box when the node is selected. This should only get called in the initialize call of your node creator. Keyable attributes are always shown in the channel box so this flag is ignored on keyable attributes. It is for intended for use on non-keyable attributes which you want to appear in the channel box.

This method changes the default state of a plug. Channel box visibility for a specific plug can be changed using the MPlug::setChannelBox method.

Attributes are not in the channel box by default unless they are keyable.

Parameters:
[in]  state  whether the attribute is to appear in the channel box
Returns:
Return status
Status Codes:

MStatus MFnAttribute::setHidden ( bool  state  ) 

Sets whether this attribute should be hidden from the UI. This is useful if the attribute is being used for blind data, or if it is being used as scratch space for a geometry calculation (should also be marked non-connectable in that case).

Attributes are not hidden by default.

Parameters:
[in]  state  whether the attribute is to be hidden
Returns:
Return status
Status Codes:
Examples:
anisotropicShader.cpp, apiMeshCreator.cpp, backfillShader.cpp, brickShader.cpp, cellShader.cpp, cgfxShaderNode.cpp, checkerShader.cpp, clearcoat.cpp, cvColorShader.cpp, depthShader.cpp, displacementShader.cpp, flameShader.cpp, geomShader.cpp, GLSLShaderNode.cpp, hwDecalBumpShader_NV20.cpp, hwReflectBumpShader_NV20.cpp, hwToonShader_NV20.cpp, interpShader.cpp, lambertShader.cpp, lavaShader.cpp, lightShader.cpp, meshOpNode.cpp, noiseShader.cpp, phongShader.cpp, quadricShape.cpp, shadowMatteShader.cpp, shiftNode.cpp, slopeShaderNode.cpp, solidCheckerShader.cpp, testNobjectNode.cpp, testNucleusNode.cpp, and volumeShader.cpp.

MStatus MFnAttribute::setUsedAsColor ( bool  state  ) 

Sets whether this attribute should be presented as a color in the UI.

Parameters:
[in]  state  whether the attribute is to be presented as a color
Returns:
Return status
Status Codes:
Examples:
cgfxAttrDef.cpp, hwAnisotropicShader_NV20.cpp, hwDecalBumpShader_NV20.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, interpShader.cpp, lambertShader.cpp, and slopeShaderNode.cpp.

MStatus MFnAttribute::setIndeterminant ( bool  state  ) 

Sets whether this attribute is indeterminant. If an attribute may or may not be used during an evaluation then it is indeterminant. This attribute classification is mainly used on rendering nodes to indicate that some attributes are not always used.

Attributes are not indeterminant by default.

Parameters:
[in]  state  whether the attribute indeterminant
Returns:
Return status
Status Codes:

MStatus MFnAttribute::setRenderSource ( bool  state  ) 

Sets whether this attribute should be used as a render source attribute. When writing shader plug-ins, it is sometimes useful to be able to modify the sampler info, so upstream shading network can be re- evaluated with different sampler info values.

For example, if a shading node takes a 2D texture as input, the result color of the 2D texture is evaluated at the current sample's UV coordinates. Initializing uvCoords attributes as render source and modifing the U and V values, then setting it as output will modify the sampler info. Re-evaluating the input plug will cause the 2D texture to re-evaluate with the new U and V values, and return a different color to the shading node.

Only valid Maya rendering attributes can be set to render source.

The following code example demonstrates how this is done:

initialize()

...

creates attributes for uvCoord and set them to be render source

u = nAttr.create( "uCoord", "u", MFnNumericData::kFloat, 0.0 ); nAttr.setStorable(false); nAttr.setWritable(true); nAttr.setRenderSource(true); v = nAttr.create( "vCoord", "v", MFnNumericData::kFloat, 0.0 ); nAttr.setStorable(false); nAttr.setWritable(true); nAttr.setRenderSource(true); uv = nAttr.create( "uvCoord", "uv", u, v ); nAttr.setStorable(false); nAttr.setWritable(true); nAttr.setRenderSource(true);

need to have the output uv affect the input uv because we want the new uv values we set to cause other inputs to this node to evaluate

attributeAffects ( uv, uv );

...

compute()

...

get uv coordinates from the sampler

MDataHandle uH = data.inputValue( u, &stat); MDataHandle vH = data.inputValue( v, &stat); float oldU = uH.asFloat(); float oldV = vH.asFloat();

get shading color input at the current sampler's uv coordinates

MDataHandle colorH = data.inputValue( inColor, &stat); MFloatVector color = colorH.asFloatVector(); // color at the sampled uv location

evaluate input color at a different uv location:

set output uv coordinates back to sampler this is only possible because we've set uv to be render source

MDataHandle outUV = data.outputValue( uv ); outUV.set( oldU-0.01, oldV-0.01 );

get newly evaluated inColor at uv(oldU-0.01, oldV-0.01)

any shading node connected to inColor will get uvCoord values as we've supplied. Calling data.inputValue( inColor, &stat) causes it to re-evaluate the network again with the new uvCoord values.

colorH = data.inputValue( inColor, &stat); // evaluate again color = colorH.asFloatVector(); // color at the new uv location

...

outUV.set( oldU, oldV ); // set the values back before we exit

...

Parameters:
[in]  state  whether the attribute is to be a render source
Returns:
Return status
Status Codes:
Examples:
shiftNode.cpp.

MStatus MFnAttribute::setWorldSpace ( bool  state  ) 

Sets whether this attribute should be treated as worldspace. Being worldspace indicates the attribute is dependent on the worldSpace transformation of this node, and will be marked dirty by any attribute changes in the hierarchy that affects the worldSpace transformation. The attribute needs to be an array since during instancing there are multiple worldSpace paths to the node & Maya requires one array element per path for worldSpace attributes.

NOTES: 1. Can only be used on array attributes. 2. This property is ignored on non-dag nodes.

Parameters:
[in]  state  whether the attribute is to be presented as worldspace
Returns:
Return status
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure this function set does not have a valid attribute object or the attribute is not an array

MStatus MFnAttribute::setAffectsWorldSpace ( bool  state  ) 

Sets whether this attribute should affect worldspace. NOTES: This property is ignored on non-dag nodes.

Parameters:
[in]  state  whether the attribute should affect worldspace
Returns:
Return status
Status Codes:
Examples:
rockingTransform.cpp.

MStatus MFnAttribute::setDisconnectBehavior ( MFnAttribute::DisconnectBehavior  behavior  ) 

Sets the disconnection behavior for this attribute. This determines what happens when a connection to this attribute is deleted. This should only get called in the initialize call of your node creator.

The settings are as follows:

  • kDelete delete the element of the array that was connected. This is only used for array attributes
  • kReset reset the attribute to its default value
  • kNothing leave the attribute set to its last known value
Attributes have a default disconnect behavior of kNothing.
Parameters:
[in]  behavior  the new disconnect behavior
Returns:
Return status
Status Codes:
Examples:
cvColorShader.cpp, and geometrySurfaceConstraint.cpp.

MStatus MFnAttribute::setUsesArrayDataBuilder ( bool  state  ) 

Sets whether this attribute uses an array data builder. If true, then the MArrayDataBuilder class may be used with this attribute to generate its data. If false, MArrayDataHandle::builder will fail.

By default array attributes do not use an array data builder.

Parameters:
[in]  state  whether the attribute uses an array data builder
Returns:
Return status
Status Codes:
Examples:
multiCurveNode.cpp, slopeShaderNode.cpp, and weightListNode.cpp.

MStatus MFnAttribute::setInternal ( bool  state  ) 

The function controls an attribute's data storage. When set to true, the virtual methods MPxNode::setInternalValueInContext() and MPxNode::getInternalValueInContext() are invoked whenever the attribute value is set or queried, respectively. By default, attributes are not internal.

There are two reasons to set an attribute as 'internal'. The first, and simplest, is when you want notification that the attribute has been set, or queried. This allows you to invoke some related action. In this case getInternalValueInContext() and setInternalValueInContext() should return false to indicate that Maya can store the attribute's value in the data block, instead of your own custom structure.

The second use of internal attributes is to store the data in a structure other than the datablock. When MPxNode::setInternalValueInContext() is called, the attribute's data can be transferred into your custom data structure. When getInternalValueInContext() is called, you can return your data. In this case getInternalValueInContext() and setInternalValueInContext() should return true to indicate that Maya should not store the attribute's value in the data block but use your own custom structure instead.

Parameters:
[in]  state  whether the attribute uses internal data
Returns:
Return status
Status Codes:
Examples:
cgfxShaderNode.cpp, customImagePlane.cpp, GLSLShaderNode.cpp, hlslShader.cpp, hwColorPerVertexShader.cpp, hwPhongShader.cpp, and pnTrianglesNode.cpp.

bool MFnAttribute::accepts ( MFnData::Type  type,
MStatus *  ReturnStatus = NULL  
) const

Returns true if this attribute can accept a connection of the given type.

Parameters:
[in]  type  data type
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether a connection of that type is valid
Status Codes:

bool MFnAttribute::accepts ( const MTypeId &  id,
MStatus *  ReturnStatus = NULL  
) const

Returns true if this attribute can accept a connection of the given type.

Parameters:
[in]  id  data type id
[out]  ReturnStatus  return status
Returns:
A boolean value indicating whether a connection of that type is valid
Status Codes:

MObject MFnAttribute::parent ( MStatus *  ReturnStatus = NULL  )  const

Get the parent of this attribute, if it has one.

Parameters:
[out]  ReturnStatus  return status
Returns:
The parent attribute
Status Codes:

MStatus MFnAttribute::setParent ( const MObject &  parent  ) 

Sets the parent attribute for this attribute. If the attribute was already a member of a compound, it will be removed from that attribute structure, and added to the specified one.

Parameters:
[in]  parent  the parent attribute
Returns:
Return status
Status Codes:

MString MFnAttribute::name ( MStatus *  ReturnStatus = NULL  )  const

Returns the long name of the attribute. If the attribute has no long name then its short name is returned.

Parameters:
[out]  ReturnStatus  The status of the resulting operation.
Returns:
The name of the attribute.
Status Codes:
Examples:
cgfxAttrDef.cpp, and getAttrAffectsCmd.cpp.

MString MFnAttribute::shortName ( MStatus *  ReturnStatus = NULL  )  const

Returns the short name of the attribute. If the attribute has no short name then its long name is returned.

Parameters:
[out]  ReturnStatus  The status of the resulting operation.
Returns:
The name of the attribute.
Status Codes:

MString MFnAttribute::getAddAttrCmd ( bool  useLongName = false,
MStatus *  status = NULL  
) const

Returns a string containing the addAttr command which would be required to recreate the attribute on a node. The command includes the terminating semicolon and is formatted as if for use with a selected node, meaning that it contains no node name.

To get the addAttr commands for a compound attribute and its children, use MFnCompoundAttribute::getAddAttrCmds.

Parameters:
[in]  useLongName  if true, use the attribute's long name rather than its short name
[in]  status  The status of the resulting operation. addAttr command
Returns:
Return status
Status Codes:
Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6