class MArrayDataHandle

Jump to documentation

public members:

	MArrayDataHandle ( const MDataHandle & in, MStatus * ReturnStatus = NULL )
MDataHandle	inputValue ( MStatus *ReturnStatus = NULL)
MDataHandle	outputValue ( MStatus *ReturnStatus = NULL)
MArrayDataHandle	inputArrayValue ( MStatus * ReturnStatus = NULL )
MArrayDataHandle	outputArrayValue ( MStatus * ReturnStatus = NULL )
MStatus	next ()
unsigned int	elementCount ( MStatus *ReturnStatus = NULL)
unsigned int	elementIndex ( MStatus *ReturnStatus = NULL)
MStatus	jumpToElement ( unsigned int index )
MStatus	jumpToArrayElement ( unsigned int position )
MStatus	setClean ()
MStatus	setAllClean ()
MArrayDataBuilder	builder ( MStatus *ReturnStatus = NULL)
MStatus	set ( MArrayDataBuilder & builder )
	MArrayDataHandle ( const MArrayDataHandle &other )
MArrayDataHandle &	operator= ( const MArrayDataHandle & other )

Documentation

Description

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.

Functions

MArrayDataHandle:: MArrayDataHandle ( const MDataHandle & in, MStatus * ReturnStatus )

Description

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.

Arguments

• in Handle to the child array attribute.
• ReturnStatus return status

Status Codes

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

MDataHandle MArrayDataHandle:: inputValue ( MStatus *ReturnStatus)

Description

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.

Arguments

• ReturnStatus return status

Return Value

• 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 MArrayDataHandle:: outputValue ( MStatus *ReturnStatus)

Description

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.

Arguments

• ReturnStatus return status

Return Value

• data handle for the current element's data

Status Codes

• kSuccess operation successful
• kFailure an object error has occurred

MArrayDataHandle MArrayDataHandle:: inputArrayValue ( MStatus * ReturnStatus )

Description

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.

Arguments

• ReturnStatus return status

Return Value

• 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

MArrayDataHandle MArrayDataHandle:: outputArrayValue ( MStatus * ReturnStatus )

Description

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.

Arguments

• ReturnStatus return status

Return Value

• 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 MArrayDataHandle:: next ()

Description

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.

Return Value

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

unsigned int MArrayDataHandle:: elementCount ( MStatus *ReturnStatus)

Description

Returns the number of elements in the array.

Arguments

• ReturnStatus return status

Return Value

• the number of elements

Status Codes

• kSuccess operation successful
• kFailure an object error has occurred

unsigned int MArrayDataHandle:: elementIndex ( MStatus *ReturnStatus)

Description

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.

Arguments

• ReturnStatus return status

Return Value

• 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

MStatus MArrayDataHandle:: jumpToElement ( unsigned int index )

Description

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.

Arguments

• index the logical index to jump to

Return Value

• status code

Status Codes

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

MStatus MArrayDataHandle:: jumpToArrayElement ( unsigned int position )

Description

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.

Arguments

• position the array position to jump to

Return Value

• 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

MStatus MArrayDataHandle:: setClean ()

Description

Marks the data that is represented by this handle as being clean. This should be done after recalculating the data from the inputs.

Return Value

• return status

Status Codes

• kSuccess operation successful
• kFailure an object error has occurred

MStatus MArrayDataHandle:: setAllClean ()

Description

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.

Return Value

• return status

Status Codes

• kSuccess operation successful
• kFailure an object error has occurred

MArrayDataBuilder MArrayDataHandle:: builder ( MStatus *ReturnStatus)

Description

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.

Arguments

• ReturnStatus return status

Return Value

• the builder object

Status Codes

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

MStatus MArrayDataHandle:: set ( MArrayDataBuilder & builder )

Description

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

Arguments

• builder the builder object

Return Value

• return status

Status Codes

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

MArrayDataHandle:: MArrayDataHandle ( const MArrayDataHandle &other )

Description

Copy constructor.

MArrayDataHandle & MArrayDataHandle:: operator= ( const MArrayDataHandle & other )

Description

Assignment operator.

Arguments

• other the source object to copy from.

This class has no child classes.