#include <MArrayDataHandle.h>

Class Description

Data block handle for array data.

An MArrayDataHandle is a smart pointer into a data block (MDataBlock) that handles access to array data. MArrayDataHandle supports attributes that can have an array of data.

The array indices do not have to be continuous. The array can be sparse. Thus, an array could have four elements with the indicies 1, 6, 8, and 10.

MArrayDataHandle methods cannot be assumed to be threadsafe. The jumpToElement() method sets an internal pointer so definitely cannot be called by multiple threads simultaneously.

Examples:: AbcImport/AlembicNode.cpp, anisotropicShader/anisotropicShader.cpp, apiMeshShape/apiMeshShape.cpp, apiMeshShape/apiMeshShape.h, backfillShader/backfillShader.cpp, basicBlendShape/basicBlendShape.cpp, basicSkinCluster/basicSkinCluster.cpp, constraintEvaluator/constraintEvaluator.cpp, dynExprField/dynExprField.cpp, footPrintNode/footPrintNode.cpp, fullLoftNode/fullLoftNode.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, lambertShader/lambertShader.cpp, multiCurveNode/multiCurveNode.cpp, multiPlugInfoCmd/multiPlugInfoCmd.cpp, offsetNode/offsetNode.cpp, onbShader/onbShader.cpp, ownerEmitter/ownerEmitter.cpp, ownerEmitter/ownerEmitter.h, phongShader/phongShader.cpp, shadowMatteShader/shadowMatteShader.cpp, simpleEmitter/simpleEmitter.cpp, simpleEmitter/simpleEmitter.h, splatDeformer/splatDeformer.cpp, sseDeformer/sseDeformer.cpp, stringFormatNode/stringFormatNode.cpp, sweptEmitter/sweptEmitter.cpp, sweptEmitter/sweptEmitter.h, testNsolverNode/testNsolverNode.cpp, testNucleusNode/testNucleusNode.cpp, torusField/torusField.cpp, and weightListNode/weightListNode.cpp.

Public Member Functions
	MArrayDataHandle (const MDataHandle &in, MStatus *ReturnStatus=NULL)
	Copy constructor. More...

MDataHandle	inputValue (MStatus *ReturnStatus=NULL)
	Gets a handle into this data block for the current array element. More...

MDataHandle	outputValue (MStatus *ReturnStatus=NULL)
	Gets a handle into this data block for the current array element. More...

MArrayDataHandle	inputArrayValue (MStatus *ReturnStatus=NULL)
	Gets a handle into this data block for the current array element. More...

MArrayDataHandle	outputArrayValue (MStatus *ReturnStatus=NULL)
	Gets a handle into this data block for the current array element. More...

MStatus	next ()
	Advance to the next element in the array. More...

unsigned int	elementCount (MStatus *ReturnStatus=NULL)
	Returns the number of elements in the array. More...

unsigned int	elementIndex (MStatus *ReturnStatus=NULL)
	Returns the index that we are currently at in the array. More...

MStatus	jumpToElement (unsigned int index)
	Jump to a specific element in the array. More...

MStatus	jumpToArrayElement (unsigned int position)
	Jump to a specific array element in the array. More...

MStatus	setClean ()
	Marks the data that is represented by this handle as being clean. More...

MStatus	setAllClean ()
	Marks every element of the array attribute represented by the handle as clean. More...

MArrayDataBuilder	builder (MStatus *ReturnStatus=NULL)
	Returns a builder for this handle's array so that it can be expanded. More...

MStatus	set (MArrayDataBuilder &builder)
	Sets the data for this array from the data in the builder object. More...

	MArrayDataHandle (const MArrayDataHandle &other)
	Copy constructor. More...

MArrayDataHandle &	operator= (const MArrayDataHandle &other)
	Assignment operator. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

Friends
class	MDataBlock

class	MArrayDataBuilder

Constructor & Destructor Documentation

MArrayDataHandle	(	const MDataHandle &	in,
		MStatus *	ReturnStatus = `NULL`
	)

Copy constructor.

Creates an new array data handle from the specified data handle.

This method can be used to access an array attribute that is a child of a compound array. Example: weightList[].weights[]

This method will only work for data handles to attributes that are arrays.

Parameters

[in]	in	Handle to the child array attribute.
[out]	ReturnStatus	return status

Status Codes:

kSuccess operation successful
kInvalidParameter source handle is null or is not an array

MArrayDataHandle ( const MArrayDataHandle & other )

inline

Copy constructor.

Parameters

[in] other the source object to copy from.

Member Function Documentation

MDataHandle inputValue ( MStatus * ReturnStatus = NULL )

Gets a handle into this data block for the current array element.

The data represented by the handle will be valid. If the data is from an dirty connection, then the connection will be evaluated.

It is important to note that you can not call inputValue on an element that is greater than the elementCount in this arrayDataHandle. That is, calls to inputValue must be protected by a call to elementCount to ensure the element exists. If this is not done, the call to inputValue will fail with an invalidParameter error.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Parameters

[out] ReturnStatus return status

Returns: Data handle for the current element's data

Status Codes:

kSuccess operation successful
kInvalidParameter the requested element is out of range
kFailure an object error has occurred

MDataHandle outputValue ( MStatus * ReturnStatus = NULL )

Gets a handle into this data block for the current array element.

The data is not guaranteed to be valid. Therefore, this handle should only be used for writing over the data.

This method can also be used to retrieve handles to individual elements of non-datablock array handles, such as those returned by MPlug::getValue() and MPlug::asMDataHandle().

Parameters

[out] ReturnStatus return status

Returns: Data handle for the current element's data

Status Codes:

kSuccess operation successful
kFailure an object error has occurred

Examples:: AbcImport/AlembicNode.cpp, apiMeshShape/apiMeshShape.cpp, and weightListNode/weightListNode.cpp.

MArrayDataHandle inputArrayValue ( MStatus * ReturnStatus = NULL )

Gets a handle into this data block for the current array element.

This method should be used when the array elements are also arrays. The data represented by the handle will be valid. If the data is from an dirty connection, then the connection will be evailuated.

It is important to note that you can not call inputArrayValue on an element that is greater than the elementCount in this arrayDataHandle. That is, calls to inputValue must be protected by a call to elementCount to ensure the element exists. If this is not done, the the call to inputArrayValue will fail with an invalidParameter error.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Parameters

[out] ReturnStatus return status

Returns: Data handle for the current element's data

Status Codes:

kSuccess operation successful
kInvalidParameter the current item is not an array or the requested element is out of range.
kFailure an object error has occurred

Examples:: apiMeshShape/apiMeshShape.cpp.

MArrayDataHandle outputArrayValue ( MStatus * ReturnStatus = NULL )

Gets a handle into this data block for the current array element.

This method should be used when the array elements are also arrays. The data is not guaranteed to be valid. Therefore, this handle should only be used for writing over the data.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Parameters

[out] ReturnStatus return status

Returns: Data handle for the current element's data

Status Codes:

kSuccess operation successful
kInvalidParameter the current item is not an array
kFailure an object error has occurred

MStatus next ( )

Advance to the next element in the array.

These may be sparse arrays so the next consecutive element may not necessarily have a consecutive index.

Returns

MS::kSuccess if there was a next element
MS::kFailure if the object is invalid or there is no next element

Examples:: AbcImport/AlembicNode.cpp, anisotropicShader/anisotropicShader.cpp, apiMeshShape/apiMeshShape.cpp, backfillShader/backfillShader.cpp, basicBlendShape/basicBlendShape.cpp, basicSkinCluster/basicSkinCluster.cpp, fullLoftNode/fullLoftNode.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, lambertShader/lambertShader.cpp, offsetNode/offsetNode.cpp, onbShader/onbShader.cpp, phongShader/phongShader.cpp, shadowMatteShader/shadowMatteShader.cpp, splatDeformer/splatDeformer.cpp, and sseDeformer/sseDeformer.cpp.

unsigned int elementCount ( MStatus * ReturnStatus = NULL )

Returns the number of elements in the array.

Parameters

[out] ReturnStatus return status

Returns: The number of elements

Status Codes:

kSuccess operation successful
kFailure an object error has occurred

Examples:: AbcImport/AlembicNode.cpp, anisotropicShader/anisotropicShader.cpp, backfillShader/backfillShader.cpp, basicBlendShape/basicBlendShape.cpp, basicSkinCluster/basicSkinCluster.cpp, constraintEvaluator/constraintEvaluator.cpp, fullLoftNode/fullLoftNode.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, lambertShader/lambertShader.cpp, offsetNode/offsetNode.cpp, onbShader/onbShader.cpp, phongShader/phongShader.cpp, shadowMatteShader/shadowMatteShader.cpp, testNsolverNode/testNsolverNode.cpp, and weightListNode/weightListNode.cpp.

unsigned int elementIndex ( MStatus * ReturnStatus = NULL )

Returns the index that we are currently at in the array.

It is possible for the index to be invalid, in which case the return status will report an error. These may be sparse arrays so the element index returned will be a logical index.

Parameters

[out] ReturnStatus return status

Returns: The current element's logical index

Status Codes:

kSuccess operation successful
kFailure current element has an invalid index, or this function set has an invalid object

Examples:: AbcImport/AlembicNode.cpp, apiMeshShape/apiMeshShape.cpp, offsetNode/offsetNode.cpp, splatDeformer/splatDeformer.cpp, and sseDeformer/sseDeformer.cpp.

MStatus jumpToElement ( unsigned int index )

Jump to a specific element in the array.

The array is sparse, so the indices may not be consecutive.

NOTE: The index is the logical element index, which may be sparse.

Jumping to an element is done through a binary search, with heuristics that improve the starting point for the search for simpler cases, such as:

where the elements are contiguous (or at least mostly contiguous), or
if you ask for the element that immediately follows the previously searched result.

In those cases the search will be more likely to find the right spot in one or two guesses instead of always needing to search over the entire range. The algorithm is therefore still O(logn) in the worst case (as a typical binary search), but it should average closer to O(1) if the dataset is not very sparse and if it is being searched iteratively, in order.

Parameters

[in] index the logical index to jump to

Returns: Status code

Status Codes:

MS::kSuccess the operation was successful
MS::kInvalidParameter the given index does not exist
kFailure an object error has occurred

Examples:: basicBlendShape/basicBlendShape.cpp, basicSkinCluster/basicSkinCluster.cpp, constraintEvaluator/constraintEvaluator.cpp, dynExprField/dynExprField.cpp, fullLoftNode/fullLoftNode.cpp, offsetNode/offsetNode.cpp, ownerEmitter/ownerEmitter.h, simpleEmitter/simpleEmitter.h, stringFormatNode/stringFormatNode.cpp, sweptEmitter/sweptEmitter.h, testNsolverNode/testNsolverNode.cpp, testNucleusNode/testNucleusNode.cpp, torusField/torusField.cpp, and weightListNode/weightListNode.cpp.

MStatus jumpToArrayElement ( unsigned int position )

Jump to a specific array element in the array.

This method can be used to iterate over the entire array.

NOTE: Jumping to an array element does not require a search, since the array indices are non-sparse. The MArrayDataHandle::elementIndex() method can be used to determine the logical index related to the current array index.

Parameters

[in] position the array position to jump to

Returns: Status code

Status Codes:

MS::kSuccess the operation was successful
MS::kInvalidParameter the given array element does not exist
kFailure an object error has occurred

Examples:: basicBlendShape/basicBlendShape.cpp, splatDeformer/splatDeformer.cpp, sseDeformer/sseDeformer.cpp, and weightListNode/weightListNode.cpp.

MStatus setClean ( )

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

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

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Returns: Return status

Status Codes:

kSuccess operation successful
kFailure an object error has occurred

MStatus setAllClean ( )

Marks every element of the array attribute represented by the handle as clean.

This method should be used if a compute function is asked to compute a single element of a multi, but instead calculates all the elements. Calling setAllClean in this situation will prevent further calls to the node's compute method for the other elements of the multi.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Returns: Return status

Status Codes:

kSuccess operation successful
kFailure an object error has occurred

Examples:: AbcImport/AlembicNode.cpp, apiMeshShape/apiMeshShape.cpp, footPrintNode/footPrintNode.cpp, and multiCurveNode/multiCurveNode.cpp.

MArrayDataBuilder builder ( MStatus * ReturnStatus = NULL )

Returns a builder for this handle's array so that it can be expanded.

This method will fail if the current array does not support array data builders. This can be changed in a node's initialize routine using the setUsesArrayDataBuilder method in MFnAttribute.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Parameters

[out] ReturnStatus return status

Returns: The builder object

Status Codes:

kSuccess operation successful
kInvalidParameter This item does not support array data builders
kFailure an object error has occurred

Examples:: apiMeshShape/apiMeshShape.cpp, ownerEmitter/ownerEmitter.cpp, simpleEmitter/simpleEmitter.cpp, sweptEmitter/sweptEmitter.cpp, and torusField/torusField.cpp.

MStatus set ( MArrayDataBuilder & builder )

Sets the data for this array from the data in the builder object.

The data handle that this arrayDataHandle represents must come from a valid data block, such as one returned from one of the MDataBlock methods like MDataBlock::inputValue(). If a data handle created and returned from MPlug::getValue() or MPlug::asMDataHandle() is passed to this arrayDataHandle, then the use of this method will be invalid.

Parameters

[in] builder the builder object

Returns: Return status

Status Codes:

kSuccess operation successful
kInvalidParameter the builder passed is invalid
kFailure an object error has occurred

Examples:: apiMeshShape/apiMeshShape.cpp, and multiCurveNode/multiCurveNode.cpp.

MArrayDataHandle & operator= ( const MArrayDataHandle & other )

inline

Assignment operator.

Parameters

[in] other the source object 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:

MArrayDataHandle.h
MArrayDataHandle.cpp

MArrayDataHandle Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation