#include <MPxThreadedDeviceNode.h>

Class Description

Base class for threaded node creation.

MPxThreadedDeviceNode is the base class used for creating threaded maya device nodes.

Maya handles thread management. The plug-in needs to implement the threadHandler() and threadShutdownHandler(). Maya will call these handlers as it manages the thread.

The interface implements a memory queue system where data pointers are acquired, filled, then pushed into the node using mutex locking. This is done from a separate, secondary thread. When the data has been acquired, the thread will mark the output attribute as dirty so that the compute in the main thread will be called. The main thread will pop the oldest data buffer, process it, then release the thread data. The helper class MCharBuffer is used with the memory methods.

The "live" attribute allows finer control over the secondary thread. It can be used to stop the handling of incoming data without disconnecting the output attributes. Note that the thread continues to run even if the the live attribute is set to false.

To implement an MPxThreadedDeviceNode plug-in, you must: 1. Use the post constructor to call setRefreshOutputAttributes() and createMemoryPools() 2. Implement the destructor to destroy the memory pools 3. Implement the threadHandler() virtual. Maya will call this handler when it creates the thread. Typically the thread handler will implement a loop for collecting data. This class contains a "done" state which is accessible via the isDone() and setDone() methods. Loop while isDone() is false 4. Implement the threadShutdownHandler(). This method would be called by Maya on File -> New and Exit for example. Call setDone( true ) to stop the isDone() loop implemented in the threadHandler if the plug-in uses the done state 5. The secondary thread should call beginThreadLoop() and endThreadLoop() with the data operations happening in-between. The endThreadLoop() method will perform the throttling based on the frame rate attribute and additionally cause the output attribute to be marked dirty. This in turn will cause compute() to be called in the main thread once Maya processes the dirty message 6. The thread loop should acquireDataStorage() to get a buffer, populate the buffer with information and then call pushThreadData() 8. The compute method should popThreadData() and if it's valid, process the data and release the data pointer by calling releaseDataStorage().

The live and frameRate attributes are included in this class. Changes to these attributes will cause the thread to be shutdown and restarted so that the new settings can be in effect.

If this node is deleted then the thread will automatically be shutdown when the node is placed on the undo queue. Undoing the delete will restart the thread if it was running at the time of the delete.

NOTE: This class relies on the idle event queue to perform the node attribute updating. As a result, it will not work in Maya batch mode.

Examples:: gameInputDevice/gameInputDevice.cpp, and randomizerDevice/randomizerDevice.cpp.

Inheritance diagram for MPxThreadedDeviceNode:

Public Member Functions
	MPxThreadedDeviceNode ()
	Constructor. More...

virtual	~MPxThreadedDeviceNode ()
	Class destructor.

virtual MPxNode::Type	type () const
	Returns the type of node that this is. More...

virtual void	threadHandler ()
	This method should be overridden in user defined nodes. More...

virtual void	threadShutdownHandler ()
	This method should be overridden in user defined nodes. More...

bool	isLive ()
	Returns the true if the node is live.

bool	isDone ()
	Returns the true if the node has finished running.

MStatus	setDone (bool done)
	This method is used to set done state of the thread. More...

MStatus	beginThreadLoop ()
	This method should be called at the beginning of the loop in the secondary thread. More...

MStatus	endThreadLoop ()
	This method should be called at the end of the loop in the secondary thread. More...

MStatus	createMemoryPools (int nCount, int nElements, long nSize)
	This method should be called from the post constructor to create the memory buffers required. More...

MStatus	destroyMemoryPools ()
	This method should be called to destroy the memory pools. More...

MStatus	acquireDataStorage (MCharBuffer &buffer)
	This method is used to acquire a pointer to a block of storage that was allocated by the createMemoryPools() method. More...

MStatus	pushThreadData (MCharBuffer &buffer)
	This method is used to push the block of storage onto the internal queue. More...

MStatus	popThreadData (MCharBuffer &buffer)
	This method is used to pop the block of storage from the internal queue. More...

long	threadDataCount ()
	This method returns the number of pieces of thread data that are currently in the node's queue. More...

MStatus	releaseDataStorage (MCharBuffer &buffer)
	After popThreadData() is called, the pointer should be released so that it can be used again. More...

MStatus	setRefreshOutputAttributes (const MObjectArray &attributeList)
	This method is used to set the list of output attributes which will be marked dirty by the secondary thread. More...

Public Member Functions inherited from MPxNode
	MPxNode ()
	Constructor. More...

virtual	~MPxNode ()
	Destructor.

virtual void	postConstructor ()
	Post constructor. More...

virtual MStatus	compute (const MPlug &plug, MDataBlock &dataBlock)
	This method should be overridden in user defined nodes. More...

virtual bool	getInternalValueInContext (const MPlug &plug, MDataHandle &dataHandle, MDGContext &ctx)
	This method is overridden by nodes that store attribute data in some internal format. More...

virtual bool	setInternalValueInContext (const MPlug &plug, const MDataHandle &dataHandle, MDGContext &ctx)
	This method is overridden by nodes that store attribute data in some internal format. More...

virtual bool	getInternalValue (const MPlug &plug, MDataHandle &dataHandle)
	This method is obsolete. More...

virtual bool	setInternalValue (const MPlug &plug, const MDataHandle &dataHandle)
	This method is obsolete. More...

virtual int	internalArrayCount (const MPlug &plug, const MDGContext &ctx) const
	This method is overridden by nodes that have internal array attributes which are not stored in Maya's datablock. More...

virtual void	copyInternalData (MPxNode *)
	This method is overridden by nodes that store attribute data in some internal format. More...

virtual MStatus	legalConnection (const MPlug &plug, const MPlug &otherPlug, bool asSrc, bool &isLegal) const
	This method allows you to check for legal connections being made to attributes of this node. More...

virtual MStatus	legalDisconnection (const MPlug &plug, const MPlug &otherPlug, bool asSrc, bool &isLegal) const
	This method allows you to check for legal disconnections being made to attributes of this node. More...

virtual MStatus	setDependentsDirty (const MPlug &plug, MPlugArray &plugArray)
	This method can be overridden in user defined nodes to specify which plugs should be set dirty based upon an input plug {plugBeingDirtied} which Maya is marking dirty. More...

virtual MStatus	preEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode)
	Prepare a node's internal state for threaded evaluation. More...

virtual MStatus	postEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode, PostEvaluationType evalType)
	Clean up node's internal state after threaded evaluation. More...

virtual SchedulingType	schedulingType () const
	When overridden this method controls the degree of parallelism supported by the node during threaded evaluation. More...

virtual MStatus	connectionMade (const MPlug &plug, const MPlug &otherPlug, bool asSrc)
	This method gets called when connections are made to attributes of this node. More...

virtual MStatus	connectionBroken (const MPlug &plug, const MPlug &otherPlug, bool asSrc)
	This method gets called when connections are broken with attributes of this node. More...

virtual MStatus	dependsOn (const MPlug &plug, const MPlug &otherPlug, bool &depends) const
	This method may be overridden by the user defined node. More...

virtual bool	isPassiveOutput (const MPlug &plug) const
	This method may be overridden by the user defined node if it wants to provide output attributes which do not prevent value modifications to the destination attribute. More...

virtual MStatus	shouldSave (const MPlug &plug, bool &isSaving)
	This method may be overridden by the user defined node. More...

virtual MPlug	passThroughToOne (const MPlug &plug) const
	This method may be overridden by nodes that have a one-to-one relationship between an input attribute and a corresponding output attribute. More...

virtual bool	passThroughToMany (const MPlug &plug, MPlugArray &plugArray) const
	This method is overridden by nodes that want to control the traversal behavior of some Maya search algorithms which traverse the history/future of shape nodes looking for directly related nodes. More...

virtual bool	isAbstractClass () const
	Override this class to return true if this node is an abstract node. More...

virtual MStringArray	getFilesToArchive (bool shortName=false, bool unresolvedName=false, bool markCouldBeImageSequence=false) const
	Use this method to return all external files used by this node. More...

virtual void	getExternalContent (MExternalContentInfoTable &table) const
	Returns the external content (files) that this node depends on. More...

bool	addExternalContentForFileAttr (MExternalContentInfoTable &table, const MObject &attr) const
	Adds content info to the specified table from a file path attribute. More...

bool	setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &table)
	Sets content info in the specified attribute from the table. More...

virtual void	setExternalContent (const MExternalContentLocationTable &table)
	Changes the location of external content in batch. More...

virtual MTypeId	typeId () const
	Returns the TYPEID of this node. More...

virtual MString	typeName () const
	Returns the type name of this node. More...

virtual MString	name () const
	Returns the name of this particular instance of this class. More...

virtual MObject	thisMObject () const
	Returns the MObject associated with this user defined node. More...

virtual MStatus	setExistWithoutInConnections (bool flag)
	This method specifies whether or not the node can exist without input connections. More...

virtual bool	existWithoutInConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without input connections. More...

virtual MStatus	setExistWithoutOutConnections (bool flag)
	This method specifies whether or not the node can exist without output connections. More...

virtual bool	existWithoutOutConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without output connections. More...

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

Static Public Member Functions inherited from MPxNode
static MStatus	addAttribute (const MObject &attr)
	This method adds a new attribute to a user defined node type during the type's initialization. More...

static MStatus	inheritAttributesFrom (const MString &parentClassName)
	This method allows a class of plugin node to inherit all of the attributes of a second class of plugin node. More...

static MStatus	attributeAffects (const MObject &whenChanges, const MObject &isAffected)
	This method specifies that a particular input attribute affects a specific output attribute. More...

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

Static Public Attributes
static MObject	output
	Output data, generic attribute.

static MObject	live
	Makes node live, boolean attribute.

static MObject	frameRate
	Capture frame rate, double attribute.

Static Public Attributes inherited from MPxNode
static MObject	message
	message attribute

static MObject	isHistoricallyInteresting
	is historically interesting attribute

static MObject	caching
	caching attribute

static MObject	state
	state attribute

static MObject	frozen
	frozen attribute

Additional Inherited Members
Public Types inherited from MPxNode
enum	Type { kDependNode, kLocatorNode, kDeformerNode, kManipContainer, kSurfaceShape, kFieldNode, kEmitterNode, kSpringNode, kIkSolverNode, kHardwareShader, kHwShaderNode, kTransformNode, kObjectSet, kFluidEmitterNode, kImagePlaneNode, kParticleAttributeMapperNode, kCameraSetNode, kConstraintNode, kManipulatorNode, kMotionPathNode, kClientDeviceNode, kThreadedDeviceNode, kAssembly, kSkinCluster, kGeometryFilter, kBlendShape, kLast }
	Defines the type of node. More...

enum	SchedulingType { kParallel, kSerial, kGloballySerial, kUntrusted, kDefaultScheduling = kSerial }
	Defines the degree of parallelism of a node. More...

Protected Member Functions inherited from MPxNode
virtual MDataBlock	forceCache (MDGContext &ctx=MDGContext::fsNormal)
	USE _forceCache() IN SCRIPT. More...

virtual void	setMPSafe (bool flag)
	USE _setMPSafe() IN SCRIPT. More...

virtual MStatus	setDoNotWrite (bool flag)
	USE _setDoNotWrite() IN SCRIPT. More...

virtual bool	doNotWrite (MStatus *ReturnStatus=NULL) const
	USE _doNotWrite() IN SCRIPT. More...

Constructor & Destructor Documentation

MPxThreadedDeviceNode ( )

Constructor.

The constructor should never call any methods from MPxNode or make any calls that require the existence of the MObject associated with the user defined node. The postConstructor method should be used to do any initialization of this kind.

For example, the postConstructor method would be used to call: setRefreshOutputAttributes()

Member Function Documentation

MPxNode::Type type ( ) const

virtual

Returns the type of node that this is.

This is used to differentiate user defined nodes that are derived off different MPx base classes.

It is not necessary to override this method.

Returns: Type of the node

Reimplemented from MPxNode.

Reimplemented in MPxClientDeviceNode.

void threadHandler ( )

virtual

This method should be overridden in user defined nodes.

Thread management( creation/destruction/shutdown ) will be handled by Maya. This method will be called when the thread has been created. In a typical implementation, the thread handler will implement a loop for reading information from an external device.

Examples:: gameInputDevice/gameInputDevice.cpp, randomizerDevice/randomizerDevice.cpp, and udpDevice/udpDevice.cpp.

void threadShutdownHandler ( )

virtual

This method should be overridden in user defined nodes.

This method is used to shutdown the loop running in the thread handler.

Examples:: gameInputDevice/gameInputDevice.cpp, randomizerDevice/randomizerDevice.cpp, and udpDevice/udpDevice.cpp.

MStatus setDone ( bool done )

This method is used to set done state of the thread.

Parameters

[in] done bool to set

Status Codes:

MS::kSuccess operation successful
MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

MStatus beginThreadLoop ( )

This method should be called at the beginning of the loop in the secondary thread.

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly.

MStatus endThreadLoop ( )

This method should be called at the end of the loop in the secondary thread.

This method will throttle the thread loop based on the frame rate attribute value. For example, if you set the frameTime attribute to 1 and the processing of your thread loop body takes .25 seconds, then this method will cause a delay of .75 seconds before the thread loop restarts. This method will also mark the refresh output attribute as dirty which will make compute() be called in the main thread.

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or this method is not being called in the same thread as beginThreadLoop()

MStatus createMemoryPools	(	int	nCount,
		int	nElements,
		long	nSize
	)

This method should be called from the post constructor to create the memory buffers required.

Parameters

[in]	nCount	the number of pools to create
[in]	nElements	the number of elements in each pool
[in]	nSize	the size of each elememt

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or the creation of the memory pool failed

MStatus destroyMemoryPools ( )

This method should be called to destroy the memory pools.

This can be done in the destructor.

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or the destruction of the memory pool failed

MStatus acquireDataStorage ( MCharBuffer & buffer )

This method is used to acquire a pointer to a block of storage that was allocated by the createMemoryPools() method.

Parameters

[out] buffer contains a pointer to the buffer that should be written into

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or there are no blocks of storage available

MStatus pushThreadData ( MCharBuffer & buffer )

This method is used to push the block of storage onto the internal queue.

This is usually done by a secondary thread.

NOTE: the buffer parameter will be cleared upon the successful return of this method. This is to avoid reusing the pointer.

Parameters

[in,out] buffer contains a pointer to the buffer that should be put onto the internal queue

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or the push failed or the buffer size was 0 or the buffer pointer was NULL

MStatus popThreadData ( MCharBuffer & buffer )

This method is used to pop the block of storage from the internal queue.

This is usually done in the main thread's compute() method.

Parameters

[out] buffer contains a pointer to the buffer that should be processed

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or the pop failed

long threadDataCount ( )

This method returns the number of pieces of thread data that are currently in the node's queue.

For example if you called pushThreadData() 10 times but only called popThreadData() 3 times, you would have a thread data count of 7.

Returns: thread data count

MStatus releaseDataStorage ( MCharBuffer & buffer )

After popThreadData() is called, the pointer should be released so that it can be used again.

This is usually done in the main thread's compute() method. NOTE: the buffer pointer will be reset to NULL if this method succeeds.

Parameters

[in,out] buffer contains a pointer to the buffer that has been processed and should now be released

Returns: Status code

Status Codes:

MS::kSuccess Operation successful
MS::kFailure this MPxNode has not been initialized properly or the release of the memory buffer failed or the buffer pointer is NULL

MStatus setRefreshOutputAttributes ( const MObjectArray & attributeList )

This method is used to set the list of output attributes which will be marked dirty by the secondary thread.

After the secondary thread receives data, it sends a message to dirty the attributes specified in the parameter list. This will then cause a refresh to make the object update.

Parameters

[in] attributeList a list of output attributes that will cause the node to refresh automatically. NOTE: Currently, only one attribute is supported

Status Codes:

MS::kSuccess operation successful
MS::kFailure this MPxNode has not been initialized properly. Make sure this method is not being called from the constructor.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

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

MPxThreadedDeviceNode.h
MPxThreadedDeviceNode.cpp

MPxThreadedDeviceNode Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Static Public Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation