MDataHandle Class Reference
 
 
 
MDataHandle Class Reference

#include <MDataHandle.h>


Class Description

Data handle for information contained in a data block.

An MDataHandle is a smart pointer into a data block (MDataBlock). A data handle corresponds to the data for a particular attribute or plug. For array data (eg CVs of a curve) use an MArrayDataHandle. To get a data handle, request it from the data block.

Some simple numeric data is handled directly by the dependency graph. If the data is more complicated (eg surface geometry), then the data handle can supply a pointer that should be given to the appropriate data function set.

MDataHandle allows the manipulation and setting of generic attributes as created by the MFnGenericAttribute class. It is possible to create numeric generic attributes using two scenarios. A plug-in may request that the generic attribute support singleton types such as MFnNumericData::kFloat or kChar. Or a plug-in may request array types such as MFnNumericData::k2Float k2Double. In the singleton case, getting and setting the attribute using MDataHandle is done with the asGeneric*() or setGeneric*() methods. In the case of the array types, the MDataHandle.data() method can be used to retrieve the MObject for the attribute and to initialize the MFnNumericData function set. A call to MDataHandle::setData() on the updated attribute must be made to pass the information back to Maya. NOTE: It is not possible to distinguish the singleton generic types from one another. There is no method that can be called to return if the singleton generic attribute is a float, char etc.

MDataHandle methods cannot be assumed to be threadsafe.

Examples:

AbcImport/AlembicNode.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, AbcImport/NodeIteratorVisitorHelper.h, affectsNode/affectsNode.cpp, animCubeNode/animCubeNode.cpp, anisotropicShader/anisotropicShader.cpp, apiMeshShape/apiMeshCreator.cpp, apiMeshShape/apiMeshShape.cpp, apiMeshShape/apiMeshShape.h, arcLenNode/arcLenNode.cpp, AshliShader/GLSLShaderNode.cpp, backfillShader/backfillShader.cpp, blindDataShader/blindDataMesh.cpp, blindDataShader/blindDataShader.cpp, brickShader/brickShader.cpp, buildRotationNode/buildRotationNode.cpp, cellShader/cellShader.cpp, cgfxShaderNode.cpp, cgfxShaderNode.h, cgfxVector.cpp, checkerShader/checkerShader.cpp, circleNode/circleNode.cpp, clearcoat.cpp, closestPointOnCurve/closestPointOnCurveNode.cpp, compositingShader/compositingShader.cpp, contrastShader/contrastShader.cpp, customImagePlane/customImagePlane.cpp, cvColorNode/cvColorNode.cpp, cvColorShader/cvColorShader.cpp, depthShader/depthShader.cpp, displacementShader/displacementShader.cpp, dx11Shader/dx11ConeAngleToHotspotConverter.cpp, dx11Shader/dx11Shader.cpp, dx11Shader/dx11Shader.h, dynExprField/dynExprField.cpp, fileTexture/fileTexture.cpp, flameShader/flameShader.cpp, fullLoftNode/fullLoftNode.cpp, gameInputDevice/gameInputDevice.cpp, gammaShader/gammaShader.cpp, genericAttributeNode/genericAttributeNode.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, geomShader/geomShader.cpp, GLSLShaderNode.h, gpuCache/gpuCacheShapeNode.cpp, gpuCache/gpuCacheShapeNode.h, hlslShader/hlslShader.cpp, hlslShader/hlslShader.h, hwColorPerVertexShader/hwColorPerVertexShader.cpp, hwDecalBumpShader_NV20/hwDecalBumpShader_NV20.cpp, hwPhongShader/hwPhongShader.cpp, hwPhongShader/hwPhongShader.h, hwReflectBumpShader_NV20/hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20/hwRefractReflectShader_NV20.cpp, hwToonShader_NV20/hwToonShader_NV20.cpp, hwUnlitShader/hwUnlitShader.cpp, interpShader/interpShader.cpp, jitterNode/jitterNode.cpp, lambertShader/lambertShader.cpp, latticeNoise/latticeNoiseNode.cpp, lavaShader/lavaShader.cpp, lightShader/lightShader.cpp, manipOverride/rockingTransform2.cpp, manipOverride/rockingTransform2.h, meshOpCmd/meshOpNode.cpp, MetadataSample/tweakMetadataNode.cpp, mixtureShader/mixtureShader.cpp, multiCurveNode/multiCurveNode.cpp, multiPlugInfoCmd/multiPlugInfoCmd.cpp, noiseShader/noiseShader.cpp, offsetNode/offsetNode.cpp, ownerEmitter/ownerEmitter.cpp, ownerEmitter/ownerEmitter.h, phongShader/phongShader.cpp, pnTriangles/pnTrianglesNode.cpp, pnTriangles/pnTrianglesNode.h, pointOnMeshInfo/pointOnMeshInfoNode.cpp, pointOnSubdNode/pointOnSubdNode.cpp, quadricShape/quadricShape.cpp, randomizerDevice/randomizerDevice.cpp, renderAccessNode/renderAccessNode.cpp, rockingTransform/rockingTransform.cpp, rockingTransform/rockingTransform.h, rockingTransformCheck/rockingTransform.cpp, rockingTransformCheck/rockingTransform.h, rockingTransformCheck/rockingTransformCheck.cpp, sceneAssembly/assemblyReference.cpp, sceneAssembly/assemblyReference.h, selectClosestPointLocator/selectClosestPointLocator.cpp, shadowMatteShader/shadowMatteShader.cpp, shellNode/shellNode.cpp, shiftNode/shiftNode.cpp, simpleEmitter/simpleEmitter.cpp, simpleEmitter/simpleEmitter.h, simpleFluidEmitter/simpleFluidEmitter.cpp, simpleLoftNode/simpleLoftNode.cpp, simpleSpring/simpleSpring.h, sineNode/sineNode.cpp, slopeShader/slopeShaderNode.cpp, solidCheckerShader/solidCheckerShader.cpp, splatDeformer/splatDeformer.cpp, splitUVCmd/splitUVNode.cpp, sseDeformer/sseDeformer.cpp, stringFormatNode/stringFormatNode.cpp, sweptEmitter/sweptEmitter.cpp, sweptEmitter/sweptEmitter.h, testNobjectNode/testNobjectNode.cpp, testNpassiveNode/testNpassiveNode.cpp, torusField/torusField.cpp, torusField/torusField.h, transCircleNode/transCircleNode.cpp, udpDevice/udpDevice.cpp, volumeShader/volumeShader.cpp, weightListNode/weightListNode.cpp, and yTwistNode/yTwistNode.cpp.

List of all members.

Public Member Functions

  MDataHandle ()
  Constructor for MDataHandle.
bool  isNumeric () const
  Returns true if this handle is for simple numeric data.
bool  isGeneric (bool &isNumeric, bool &isNull) const
  Returns true if this handle is for generic data.
MFnNumericData::Type  numericType () const
  Returns the type of data represented by this handle.
MFnData::Type  type () const
  Returns the type of data represented by this handle.
MTypeId  typeId () const
  Returns the type of data represented by this handle as a type id.
MStatus  acceptedTypeIds (MUintArray &) const
  This method returns an array of MTypeId ids that the data handle can accept.
MObject  data ()
  Returns the data object from this handle.
MStatus  copy (const MDataHandle &src)
  Copies the attribute from the src attribute to the attribute referenced by this handle.
void  setClean ()
  Marks the data that is represented by this handle as being clean.
bool &  asBool () const
  Returns the data represented by this handle in the data block.
char &  asChar () const
  Returns the data represented by this handle in the data block.
unsigned char &  asUChar () const
  Returns the data represented by this handle in the data block.
short &  asShort () const
  Returns the data represented by this handle in the data block.
int &  asLong () const
  This method is obsolete.
int &  asInt () const
  Returns the data represented by this handle in the data block.
void *&  asAddr () const
  Returns the data represented by this handle in the data block.
float &  asFloat () const
  Returns the data represented by this handle in the data block.
double &  asDouble () const
  Returns the data represented by this handle in the data block.
MDistance  asDistance () const
  Returns the data represented by this handle in the data block.
MAngle  asAngle () const
  Returns the data represented by this handle in the data block.
MTime  asTime () const
  Returns the data represented by this handle in the data block.
short2 &  asShort2 () const
  Returns the data represented by this handle in the data block.
long2 &  asLong2 () const
  This method is obsolete.
int2 &  asInt2 () const
  Returns the data represented by this handle in the data block.
float2 &  asFloat2 () const
  Returns the data represented by this handle in the data block.
double2 &  asDouble2 () const
  Returns the data represented by this handle in the data block.
short3 &  asShort3 () const
  Returns the data represented by this handle in the data block.
long3 &  asLong3 () const
  This method is obsolete.
int3 &  asInt3 () const
  Returns the data represented by this handle in the data block.
float3 &  asFloat3 () const
  Returns the data represented by this handle in the data block.
double3 &  asDouble3 () const
  Returns the data represented by this handle in the data block.
MVector asVector () const
  Returns the data represented by this handle in the data block.
MFloatVector asFloatVector () const
  Returns the data represented by this handle in the data block.
MMatrix asMatrix () const
  Returns the data represented by this handle in the data block.
MFloatMatrix asFloatMatrix () const
  Returns the data represented by this handle in the data block.
MString asString () const
  Returns the data represented by this handle in the data block.
MObject  asNurbsCurve () const
  Returns the data represented by this handle in the data block.
MObject  asNurbsSurface () const
  Returns the data represented by this handle in the data block.
MObject  asMesh () const
  Returns the data represented by this handle in the data block.
MObject  asSubdSurface () const
  Returns the data represented by this handle in the data block.
MObject  asNurbsCurveTransformed () const
  Returns the data represented by this handle in the data block.
MObject  asNurbsSurfaceTransformed () const
  Returns the data represented by this handle in the data block.
MObject  asMeshTransformed () const
  Returns the data represented by this handle in the data block.
MObject  asSubdSurfaceTransformed () const
  Returns the data represented by this handle in the data block.
const MMatrix geometryTransformMatrix () const
  This method returns a reference to the local-to-world transformation matrix that can accompany a geometry data object.
MPxData asPluginData () const
  Returns the data represented by this handle in the data block.
void  set (bool)
  No script support.
void  set (char)
  No script support.
void  set (short)
  No script support.
void  set (int)
  No script support.
void  set (float)
  No script support.
void  set (double)
  No script support.
void  set (const MMatrix &)
  No script support.
void  set (const MFloatMatrix &)
  No script support.
void  set (const MVector &)
  No script support.
void  set (const MFloatVector &)
  No script support.
void  set (const MDistance &)
  No script support.
void  set (const MAngle &)
  No script support.
void  set (const MTime &)
  No script support.
void  set (short, short)
  No script support.
void  set (int, int)
  No script support.
void  set (float, float)
  No script support.
void  set (double, double)
  No script support.
void  set (short, short, short)
  No script support.
void  set (int, int, int)
  No script support.
void  set (float, float, float)
  No script support.
void  set (double, double, double)
  No script support.
void  set (const MString &)
  No script support.
MStatus  set (const MObject &data)
  No script support.
MStatus  set (MPxData *data)
  No script support.
void  setBool (bool)
  Set the data that this handle represents in the data block.
void  setChar (char)
  Set the data that this handle represents in the data block.
void  setShort (short)
  Set the data that this handle represents in the data block.
void  setInt (int)
  Set the data that this handle represents in the data block.
void  setFloat (float)
  Set the data that this handle represents in the data block.
void  setDouble (double)
  Set the data that this handle represents in the data block.
void  setMMatrix (const MMatrix &)
  Set the data that this handle represents in the data block.
void  setMFloatMatrix (const MFloatMatrix &)
  Set the data that this handle represents in the data block.
void  setMVector (const MVector &)
  Set the data that this handle represents in the data block.
void  setMFloatVector (const MFloatVector &)
  Set the data that this handle represents in the data block.
void  setMDistance (const MDistance &)
  Set the data that this handle represents in the data block.
void  setMAngle (const MAngle &)
  Set the data that this handle represents in the data block.
void  setMTime (const MTime &)
  Set the data that this handle represents in the data block.
void  set2Short (short, short)
  Set the data that this handle represents in the data block.
void  set2Int (int, int)
  Set the data that this handle represents in the data block.
void  set2Float (float, float)
  Set the data that this handle represents in the data block.
void  set2Double (double, double)
  Set the data that this handle represents in the data block.
void  set3Short (short, short, short)
  Set the data that this handle represents in the data block.
void  set3Int (int, int, int)
  Set the data that this handle represents in the data block.
void  set3Float (float, float, float)
  Set the data that this handle represents in the data block.
void  set3Double (double, double, double)
  Set the data that this handle represents in the data block.
void  setString (const MString &)
  Set the data that this handle represents in the data block.
MStatus  setMObject (const MObject &data)
  Set the data that this handle represents in the data block.
MStatus  setMPxData (MPxData *data)
  Set the data that this handle represents in the data block.
bool  asGenericBool () const
  Returns the generic data represented by this handle in the data block.
unsigned char  asGenericChar () const
  Returns the generic data represented by this handle in the data block.
double  asGenericDouble () const
  Returns the generic data represented by this handle in the data block.
float  asGenericFloat () const
  Returns the generic data represented by this handle in the data block.
short  asGenericShort () const
  Returns the generic data represented by this handle in the data block.
int  asGenericInt () const
  Returns the generic data represented by this handle in the data block.
void  setGenericBool (bool value, bool force)
  Set the data that this handle represents in the data block.
void  setGenericChar (unsigned char value, bool force)
  Set the data that this handle represents in the data block.
void  setGenericDouble (double value, bool force)
  Set the data that this handle represents in the data block.
void  setGenericFloat (float value, bool force)
  Set the data that this handle represents in the data block.
void  setGenericShort (short value, bool force)
  Set the data that this handle represents in the data block.
void  setGenericInt (int value, bool force)
  Set the data that this handle represents in the data block.
MDataHandle  child (const MPlug &plug)
  Get a handle to a child of this handle.
MDataHandle  child (const MObject &attribute)
  Get a handle to a child of this handle.
MDataHandle operator= (const MDataHandle &other)
  Assignment operator.
  MDataHandle (const MDataHandle &)
  Copy constructor.

Static Public Member Functions

static const char *  className ()
  Returns the name of this class.

Friends

class  MDataBlock
class  MArrayDataBuilder
class  MArrayDataHandle
class  MItGeometry

Constructor & Destructor Documentation

Constructor for MDataHandle.

Typically, data handles will be obtained from the data block (MDataBlock). A user constructed MDataHandle should not be used until a valid data handle has been assigned to it (ie. using the assignment operator).


Member Function Documentation

bool isNumeric ( ) const

Returns true if this handle is for simple numeric data.

That means that the numeric data is directly accessible through the non-generic as*() and set*() methods of this handle. For example, depending on handle initialization, the asBool() may be called but the asGenericBool() should not be called.

Returns:
Whether this handle points to simple numeric data
Examples:
multiPlugInfoCmd/multiPlugInfoCmd.cpp.
bool isGeneric ( bool &  isNumeric,
bool &  isNull 
) const

Returns true if this handle is for generic data.

There are 2 forms of generic data. The first is for simple data and is used if the isNumeric parameter returns true. In this case, the asGeneric*() and setGeneric*() methods of this class are used to query and set values. The second form of generic data is for more complex attribute types. As a result the type of the object must be checked and an appropriate attribute function set initialized with the object.

Parameters:
[out] isNumeric returns true if this handle is for simple generic numeric data
[out] isNull returns true if this handle is not set
Returns:
True will be returned if this handle points to a generic attribute
Examples:
genericAttributeNode/genericAttributeNode.cpp.
MFnNumericData::Type numericType ( ) const

Returns the type of data represented by this handle.

This method is only valid for data handles of simple numeric types.

Returns:
The numeric type
Examples:
multiPlugInfoCmd/multiPlugInfoCmd.cpp.
MFnData::Type type ( ) const

Returns the type of data represented by this handle.

Returns:
The data type
Examples:
splatDeformer/splatDeformer.cpp, and sseDeformer/sseDeformer.cpp.
MTypeId typeId ( ) const

Returns the type of data represented by this handle as a type id.

A type id is a four character code that is used to identify the data type. If no data exists for this handle, the type id will be 0x0.

Returns:
The data type
MStatus acceptedTypeIds ( MUintArray typids ) const

This method returns an array of MTypeId ids that the data handle can accept.

The MTypeId can be reconstructed using the unsigned int in id.

Parameters:
[out] typids an unsigned int array to copy the ids to
Returns:
Status code
Status Codes:
MStatus copy ( const MDataHandle src )

Copies the attribute from the src attribute to the attribute referenced by this handle.

This is the only method which can completely copy a compound attribute from one handle to another. The construct outputHandle.set (inputHandle.data()) will not work for compound or multi attributes.

Parameters:
[in] src the handle to the attribute to copy
Returns:
Status code
Status Codes:
Examples:
splatDeformer/splatDeformer.cpp, and sseDeformer/sseDeformer.cpp.
void setClean ( )

Marks the data that is represented by this handle as being clean.

This should be done after recalculating the data from the inputs.

Examples:
anisotropicShader/anisotropicShader.cpp, apiMeshShape/apiMeshShape.cpp, AshliShader/GLSLShaderNode.cpp, backfillShader/backfillShader.cpp, blindDataShader/blindDataShader.cpp, buildRotationNode/buildRotationNode.cpp, cellShader/cellShader.cpp, cgfxShaderNode.cpp, checkerShader/checkerShader.cpp, clearcoat.cpp, compositingShader/compositingShader.cpp, contrastShader/contrastShader.cpp, cvColorShader/cvColorShader.cpp, displacementShader/displacementShader.cpp, dx11Shader/dx11ConeAngleToHotspotConverter.cpp, fileTexture/fileTexture.cpp, flameShader/flameShader.cpp, gammaShader/gammaShader.cpp, genericAttributeNode/genericAttributeNode.cpp, geomShader/geomShader.cpp, hwDecalBumpShader_NV20/hwDecalBumpShader_NV20.cpp, hwPhongShader/hwPhongShader.cpp, hwReflectBumpShader_NV20/hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20/hwRefractReflectShader_NV20.cpp, hwToonShader_NV20/hwToonShader_NV20.cpp, hwUnlitShader/hwUnlitShader.cpp, interpShader/interpShader.cpp, lambertShader/lambertShader.cpp, lavaShader/lavaShader.cpp, lightShader/lightShader.cpp, manipOverride/rockingTransform2.cpp, meshOpCmd/meshOpNode.cpp, MetadataSample/tweakMetadataNode.cpp, mixtureShader/mixtureShader.cpp, noiseShader/noiseShader.cpp, phongShader/phongShader.cpp, renderAccessNode/renderAccessNode.cpp, rockingTransform/rockingTransform.cpp, rockingTransformCheck/rockingTransform.cpp, shadowMatteShader/shadowMatteShader.cpp, shiftNode/shiftNode.cpp, slopeShader/slopeShaderNode.cpp, solidCheckerShader/solidCheckerShader.cpp, splitUVCmd/splitUVNode.cpp, and volumeShader/volumeShader.cpp.
char & asChar ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as a char
unsigned char & asUChar ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an unsigned char
void *& asAddr ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an address
Examples:
cvColorShader/cvColorShader.cpp, lightShader/lightShader.cpp, and phongShader/phongShader.cpp.
MDistance asDistance ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an Distance
MAngle asAngle ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an MAngle
Examples:
dx11Shader/dx11ConeAngleToHotspotConverter.cpp.
MTime asTime ( ) const

Returns the data represented by this handle in the data block.

Even though this method does not return a reference to an MTime, modifications to the MTime instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

Returns:
The handle's data as an MTime
Examples:
AbcImport/AlembicNode.cpp, animCubeNode/animCubeNode.cpp, latticeNoise/latticeNoiseNode.cpp, ownerEmitter/ownerEmitter.h, simpleEmitter/simpleEmitter.h, sweptEmitter/sweptEmitter.h, testNobjectNode/testNobjectNode.cpp, testNsolverNode/testNsolverNode.cpp, and testNucleusNode/testNucleusNode.cpp.
short2 & asShort2 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of two short integers
long2 & asLong2 ( ) const

This method is obsolete.

Deprecated:
Use MDataHandle::asInt2 instead.
Returns:
The handle's data as an array of two int integers
int2 & asInt2 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of two int integers
float2 & asFloat2 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of two floats
Examples:
brickShader/brickShader.cpp, checkerShader/checkerShader.cpp, fileTexture/fileTexture.cpp, and shiftNode/shiftNode.cpp.
double2 & asDouble2 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of two doubles
short3 & asShort3 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of three short integers
long3 & asLong3 ( ) const

This method is obsolete.

Deprecated:
Use MDataHandle::asInt3 instead.
Returns:
The handle's data as an array of three int integers
int3 & asInt3 ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as an array of three int integers
float3 & asFloat3 ( ) const
MVector & asVector ( ) const

Returns the data represented by this handle in the data block.

Returns:
The handle's data as a vector
Examples:
buildRotationNode/buildRotationNode.cpp.
MMatrix & asMatrix ( ) const

Returns the data represented by this handle in the data block.

This method is only valid for attributes created using the MFnMatrixAttribute function set.

Returns:
The handle's data as a matrix
Examples:
offsetNode/offsetNode.cpp, ownerEmitter/ownerEmitter.cpp, simpleEmitter/simpleEmitter.cpp, and torusField/torusField.cpp.
MFloatMatrix & asFloatMatrix ( ) const

Returns the data represented by this handle in the data block.

This method is only valid for attributes created using the MFnMatrixAttribute function set.

Returns:
The handle's data as a matrix of floats
Examples:
anisotropicShader/anisotropicShader.cpp, cellShader/cellShader.cpp, flameShader/flameShader.cpp, lavaShader/lavaShader.cpp, noiseShader/noiseShader.cpp, slopeShader/slopeShaderNode.cpp, and solidCheckerShader/solidCheckerShader.cpp.
MObject asNurbsCurve ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the nurbs curve function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The curve returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the nurbs curve function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::geometryTransformMatrix() method.

Returns:
The handle's data as a nurbs curve
Examples:
closestPointOnCurve/closestPointOnCurveNode.cpp, fullLoftNode/fullLoftNode.cpp, and simpleLoftNode/simpleLoftNode.cpp.
MObject asNurbsSurface ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the nurbs surface function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the nurbs surface function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::geometryTransformMatrix() method.

Returns:
The handle's data as a nurbs surface
Examples:
cvColorNode/cvColorNode.cpp.
MObject asMesh ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the mesh function set and iterators. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the mesh function set and iterators.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::geometryTransformMatrix() method.

Returns:
The handle's data as a mesh (polygonal surface)
Examples:
geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, meshOpCmd/meshOpNode.cpp, MetadataSample/tweakMetadataNode.cpp, pointOnMeshInfo/pointOnMeshInfoNode.cpp, shellNode/shellNode.cpp, splitUVCmd/splitUVNode.cpp, sseDeformer/sseDeformer.cpp, testNobjectNode/testNobjectNode.cpp, and testNpassiveNode/testNpassiveNode.cpp.
MObject asSubdSurface ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the subdivision surface function set and iterator. Even though this method does not return a reference to an MObject, modifications to the MObject instance will update the contents of the handle in the data block. The method MDataHandle::setClean should be called after the data block has been modified.

The subdivision surface returned by this method will be in local space even if the connection is supplying world space geometry. This occurs mostly for efficiency reasons. In the case of a world space geometry connection, the MObject returned by this method will also contain the world space transformation matrix. This means that world space operations may be performed on this object using the subdivision surface function set and iterator.

It is possible to get the matrix that defines the local to world transformation for this geometry using the MDataHandle::geometryTransformMatrix() method.

Returns:
The handle's data as a subdivision surface
Examples:
pointOnSubdNode/pointOnSubdNode.cpp.
MObject asNurbsCurveTransformed ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the nurbs curve function set (MFnNurbsCurve) or the nurbs curve CV iterator (MItCurveCV).

If the incoming curve comes with world space transformation data, then it will be applied to the data that is returned. In other words, the curve that is returned will be the curve as it exists in world space.

The curve that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Returns:
The handle's data as a nurbs curve
Examples:
arcLenNode/arcLenNode.cpp, and multiCurveNode/multiCurveNode.cpp.
MObject asNurbsSurfaceTransformed ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the nurbs surface function set (MFnNurbsSurface) or the nurbs surface CV iterator (MItSurfaceCV).

If the incoming surface comes with world space transformation data, then it will be applied to the data that is returned. In other words, the surface that is returned will be the surface as it exists in world space.

The surface that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Returns:
The handle's data as a nurbs surface
MObject asMeshTransformed ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the mesh function set (MFnMesh) or any of the mesh iterators.

If the incoming mesh comes with world space transformation data, then it will be applied to the data that is returned. In other words, the mesh that is returned will be the mesh as it exists in world space.

The mesh that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Returns:
The handle's data as a mesh
Examples:
splatDeformer/splatDeformer.cpp.
MObject asSubdSurfaceTransformed ( ) const

Returns the data represented by this handle in the data block.

The object returned by this call may be used directly with the subdivision surface function set (MFnSubdSurface) or the subdivision surface iterators (MItSubdVertex, MItSubdFace, MItSubdEdge).

If the incoming surface comes with world space transformation data, then it will be applied to the data that is returned. In other words, the surface that is returned will be the surface as it exists in world space.

The surface that is returned from this method should not be modified. This method is only provided to make it easier to take world space geometry as input.

Returns:
The handle's data as a subdivision surface
const MMatrix & geometryTransformMatrix ( ) const

This method returns a reference to the local-to-world transformation matrix that can accompany a geometry data object.

Only use this method on handles to geometry data (curves, surfaces, and meshes).

If no local-to-world transformation information has been provided then this will be an identity matrix.

Returns:
The handle's transform data as a 4x4 matrix
MPxData * asPluginData ( ) const

Returns the data represented by this handle in the data block.

The object is returned as plugin data. This should be used to access data types defined by plugins.

Returns:
The handle's data
Examples:
apiMeshShape/apiMeshShape.cpp.
void set ( bool  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setBool method instead.

Parameters:
[in] val the new value
Examples:
AbcImport/AlembicNode.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, affectsNode/affectsNode.cpp, animCubeNode/animCubeNode.cpp, apiMeshShape/apiMeshCreator.cpp, apiMeshShape/apiMeshShape.cpp, arcLenNode/arcLenNode.cpp, AshliShader/GLSLShaderNode.cpp, blindDataShader/blindDataMesh.cpp, buildRotationNode/buildRotationNode.cpp, cgfxShaderNode.cpp, cgfxVector.cpp, circleNode/circleNode.cpp, closestPointOnCurve/closestPointOnCurveNode.cpp, customImagePlane/customImagePlane.cpp, cvColorNode/cvColorNode.cpp, dx11Shader/dx11ConeAngleToHotspotConverter.cpp, dx11Shader/dx11Shader.cpp, dynExprField/dynExprField.cpp, fullLoftNode/fullLoftNode.cpp, genericAttributeNode/genericAttributeNode.cpp, hlslShader/hlslShader.cpp, hwColorPerVertexShader/hwColorPerVertexShader.cpp, hwPhongShader/hwPhongShader.cpp, jitterNode/jitterNode.cpp, latticeNoise/latticeNoiseNode.cpp, manipOverride/rockingTransform2.cpp, meshOpCmd/meshOpNode.cpp, MetadataSample/tweakMetadataNode.cpp, multiCurveNode/multiCurveNode.cpp, ownerEmitter/ownerEmitter.cpp, pnTriangles/pnTrianglesNode.cpp, pointOnMeshInfo/pointOnMeshInfoNode.cpp, pointOnSubdNode/pointOnSubdNode.cpp, quadricShape/quadricShape.cpp, rockingTransform/rockingTransform.cpp, rockingTransformCheck/rockingTransform.cpp, rockingTransformCheck/rockingTransformCheck.cpp, sceneAssembly/assemblyReference.cpp, shellNode/shellNode.cpp, shiftNode/shiftNode.cpp, simpleEmitter/simpleEmitter.cpp, simpleLoftNode/simpleLoftNode.cpp, sineNode/sineNode.cpp, splitUVCmd/splitUVNode.cpp, stringFormatNode/stringFormatNode.cpp, sweptEmitter/sweptEmitter.cpp, testNobjectNode/testNobjectNode.cpp, testNpassiveNode/testNpassiveNode.cpp, torusField/torusField.cpp, transCircleNode/transCircleNode.cpp, and weightListNode/weightListNode.cpp.
void set ( char  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setChar method instead.

Parameters:
[in] val the new value
void set ( short  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setShort method instead.

Parameters:
[in] val the new value
void set ( int  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setInt method instead.

Parameters:
[in] val the new value
void set ( float  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setFloat method instead.

Parameters:
[in] val the new value
void set ( double  val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setDouble method instead.

Parameters:
[in] val the new value
void set ( const MMatrix val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block. This method is only valid for attributes created using the MFnMatrixAttribute function set.

Python Notes

This method is not available from Python. See setMMatrix method instead.

Parameters:
[in] val the new value
void set ( const MFloatMatrix val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMFloatMatrix method instead.

Parameters:
[in] val the new value
void set ( const MVector val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMVector method instead.

Parameters:
[in] val the new value
void set ( const MFloatVector val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMFloatVector method instead.

Parameters:
[in] val the new value
void set ( const MDistance val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMDistance method instead.

Parameters:
[in] val the new value
void set ( const MAngle val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMAngle method instead.

Parameters:
[in] val the new value
void set ( const MTime val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setMTime method instead.

Parameters:
[in] val the new value
void set ( short  val1,
short  val2 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set2Short method instead.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set ( int  val1,
int  val2 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set2Int method instead.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set ( float  val1,
float  val2 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set2Float method instead.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set ( double  val1,
double  val2 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set2Double method instead.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set ( short  val1,
short  val2,
short  val3 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set3Short method instead.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set ( int  val1,
int  val2,
int  val3 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set3Int method instead.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set ( float  val1,
float  val2,
float  val3 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set3Float method instead.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set ( double  val1,
double  val2,
double  val3 
)

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See set3Double method instead.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set ( const MString val )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block.

Python Notes

This method is not available from Python. See setString method instead.

Parameters:
[in] val the new string value
MStatus set ( const MObject data )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block. This method assumes that the MObject is a dependency graph data object. These objects can be created using the appropriate MFn..Data function set. Note that this method cannot be used to copy compound or multi attributes from one handle to another via the construct outputHandle.set (inputHandle.data()). To copy these user defined attributes, the method MDataHandle::copy must be used.

Python Notes

This method is not available from Python. See setMObject method instead.

Parameters:
[in] data the data object
Returns:
Status code
Status Codes:
MStatus set ( MPxData data )

No script support.

This method is not available in Python.

Set the data that this handle represents in the data block. This method takes a pointer to a user defined data object. The data block will become the new owner of the data object that you pass in. Do not delete it.

Python Notes

This method is not available from Python. See setMPxData method instead.

Parameters:
[in] data the data object
Returns:
Status code
Status Codes:
void setBool ( bool  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setChar ( char  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setShort ( short  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setInt ( int  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setFloat ( float  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setDouble ( double  val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMMatrix ( const MMatrix val )

Set the data that this handle represents in the data block.

This method is only valid for attributes created using the MFnMatrixAttribute function set.

Parameters:
[in] val the new value
void setMFloatMatrix ( const MFloatMatrix val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMVector ( const MVector val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMFloatVector ( const MFloatVector val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMDistance ( const MDistance val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMAngle ( const MAngle val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void setMTime ( const MTime val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new value
void set2Short ( short  val1,
short  val2 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set2Int ( int  val1,
int  val2 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set2Float ( float  val1,
float  val2 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set2Double ( double  val1,
double  val2 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the two element array
[in] val2 the second value in the two element array
void set3Short ( short  val1,
short  val2,
short  val3 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set3Int ( int  val1,
int  val2,
int  val3 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set3Float ( float  val1,
float  val2,
float  val3 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void set3Double ( double  val1,
double  val2,
double  val3 
)

Set the data that this handle represents in the data block.

Parameters:
[in] val1 the first value in the three element array
[in] val2 the second value in the three element array
[in] val3 the third value in the three element array
void setString ( const MString val )

Set the data that this handle represents in the data block.

Parameters:
[in] val the new string value
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and gpuCache/gpuCacheShapeNode.cpp.
MStatus setMObject ( const MObject data )

Set the data that this handle represents in the data block.

This method assumes that the MObject is a dependency graph data object. These objects can be created using the appropriate MFn..Data function set. Note that this method cannot be used to copy compound or multi attributes from one handle to another via the construct outputHandle.set (inputHandle.data()). To copy these user defined attributes, the method MDataHandle::copy must be used.

Parameters:
[in] data the data object
Returns:
Status code
Status Codes:
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and geometrySurfaceConstraint/geometrySurfaceConstraint.cpp.
MStatus setMPxData ( MPxData data )

Set the data that this handle represents in the data block.

This method takes a pointer to a user defined data object. The data block will become the new owner of the data object that you pass in. Do not delete it.

Parameters:
[in] data the data object
Returns:
Status code
Status Codes:
bool asGenericBool ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a bool
unsigned char asGenericChar ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a char
double asGenericDouble ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a double
float asGenericFloat ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a float
short asGenericShort ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a short
int asGenericInt ( ) const

Returns the generic data represented by this handle in the data block.

Returns:
The generic handle's data as a int
void setGenericBool ( bool  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new bool value
[in] force force the new type of the attribute to be bool
Examples:
AbcImport/AlembicNode.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
void setGenericChar ( unsigned char  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new char value
[in] force force the new type of the attribute to be char
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
void setGenericDouble ( double  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new double value
[in] force force the new type of the attribute to be double
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
void setGenericFloat ( float  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new float value
[in] force force the new type of the attribute to be float
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
void setGenericShort ( short  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new short value
[in] force force the new type of the attribute to be short
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
void setGenericInt ( int  value,
bool  force 
)

Set the data that this handle represents in the data block.

Parameters:
[in] value the new int value
[in] force force the new type of the attribute to be int
Examples:
AbcImport/NodeIteratorVisitorHelper.cpp, and genericAttributeNode/genericAttributeNode.cpp.
MDataHandle child ( const MObject attribute )

Get a handle to a child of this handle.

This is used if you have a handle to a compound attribute.

Parameters:
[in] attribute the attribute of the child
Returns:
The data handle for the child
MDataHandle & operator= ( const MDataHandle other ) [inline]

Assignment operator.

Parameters:
[in] other Data handle to copy from.
const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.

The documentation for this class was generated from the following files: