C++ API Reference: MPxGPUStandardDeformer Class Reference

Introduced in 2023.0 More...

#include <MPxGPUStandardDeformer.h>

+ Inheritance diagram for MPxGPUStandardDeformer:

Public Member Functions

 MPxGPUStandardDeformer ()
 Constructor.
 
virtual ~MPxGPUStandardDeformer ()
 Destructor.
 
void terminate () override
 This method is called when the GPU deformer is being destroyed. More...
 
const MGPUDeformerBufferinputPositions () const
 This method returns the deformer buffer containing the input positions of the full geometry that is being deformed. More...
 
MGPUDeformerBufferoutputPositions ()
 This method returns the deformer buffer containing the output positions of the full geometry that is being deformed. More...
 
MOpenCLBufferaffectMapBuffer ()
 This method returns the OpenCL buffer containing the indices of the subset of the geometry that is being deformed. More...
 
MOpenCLBufferweightsBuffer ()
 This method returns the OpenCL buffer containing the weights for the subset of the geometry that is being deformed. More...
 
unsigned int affectCount () const
 This method returns the number of points in a subset of the geometry. More...
 
unsigned int fullCount () const
 This method returns the total number of points of the geometry. More...
 
bool isIdentityMap () const
 Returns whether the subset is the full geometry. More...
 
float envelope () const
 This method returns the current value of the envelope of the deformer. More...
 
bool hasEnvelopeWeights () const
 This method returns whether per vertex weights are being used on this deformer. More...
 
unsigned int multiIndex () const
 Introduced in 2024.0 More...
 
const MPluginputPlug () const
 Introduced in 2024.0 More...
 
const MIndexMapperindexMapper () const
 Introduced in 2024.0 More...
 
virtual bool passThroughWithZeroEnvelope () const
 Introduced in 2024.0 More...
 
DeformerStatus prepareEvaluation (MDataBlock &block, const MEvaluationNode &evaluationNode, const MPlug &outputPlug, const MPlugArray &inputPlugs, const MGPUDeformerData &inputData, MGPUDeformerData &outputData, MAutoCLEvent &syncEvent)
 Prepares the evaluation of this deformer. More...
 
DeformerStatus finishEvaluation (MAutoCLEvent &syncEvent, MGPUDeformerData &outputData)
 Finish the evaluation of this deformer. More...
 
cl_int initializeOutputPositions (MAutoCLEvent &syncEvent)
 Initialize the output positions with the input positions. More...
 
bool prepareAffectMapBuffer ()
 Uploads the affectMap to a GPU buffer if needed. More...
 
bool prepareWeightsBuffer (const MEvaluationNode &evaluationNode)
 Uploads the weights to a GPU buffer if needed. More...
 
- Public Member Functions inherited from MPxGPUDeformer
 MPxGPUDeformer ()
 Constructs an MPxGPUDeformer.
 
virtual ~MPxGPUDeformer ()
 Destructor.
 
virtual DeformerStatus evaluate (MDataBlock &block, const MEvaluationNode &evaluationNode, const MPlug &outputPlug, unsigned int numElements, const MAutoCLMem, const MAutoCLEvent, MAutoCLMem, MAutoCLEvent &)
 This method is deprecated and should no longer be used. More...
 
virtual DeformerStatus evaluate (MDataBlock &block, const MEvaluationNode &evaluationNode, const MPlug &outputPlug, const MGPUDeformerData &inputData, MGPUDeformerData &outputData)
 This method is deprecated and should no longer be used. More...
 
virtual DeformerStatus evaluate (MDataBlock &block, const MEvaluationNode &evaluationNode, const MPlug &outputPlug, const MPlugArray &inputPlugs, const MGPUDeformerData &inputData, MGPUDeformerData &outputData)
 Introduced in 2022.0 More...
 
MGPUDeformerBuffer createOutputBuffer (const MGPUDeformerBuffer &inputBuffer)
 This method creates an output buffer based on inputBuffer. More...
 
bool getIndexMapper (MIndexMapper &imap)
 Introduced in 2020.0 More...
 
MObject getFixedSetupData (const MString &name)
 Introduced in 2022.0 More...
 
bool isFalloffWeightsDirty () const
 Introduced in 2022.0 More...
 
cl_int uploadFixedSetupData (const MString &name, MOpenCLBuffer &buffer, cl_int &errorCode, unsigned int *arrayLength)
 Introduced in 2023.0 More...
 
bool lastEvaluatedOnGPU () const
 Introduced in 2024.0 More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 
- Static Public Member Functions inherited from MPxGPUDeformer
static bool hasAttributeBeenModified (const MEvaluationNode &evaluationNode, const MObject &attribute)
 This method returns true if the data for attribute on the overridden deformation node has been modified since the last call to MPxGPUDeformer::evaluate(). More...
 
static bool hasPlugBeenModified (const MPlug &plug)
 Introduced in 2022.0 More...
 
static MUniqueString sPositionsName ()
 This method returns the name of position buffers on the GPU. More...
 
static MUniqueString sGeometryMatrixName ()
 This method returns the name of geometry matrix buffers on the GPU. More...
 
static MUniqueString sInverseGeometryMatrixName ()
 This method returns the name of inverse geometry matrix buffers on the GPU. More...
 
static MUniqueString sAffectedVerticesName ()
 Introduced in 2020.0 More...
 
static bool isFalloffWeightsDependantOnCurrentGeometry (const MEvaluationNode &evaluationNode, unsigned int multiIndex)
 Introduced in 2022.0 More...
 
static bool isBufferUpdateNeeded (const MOpenCLBuffer &buffer, const MEvaluationNode &evaluationNode, const MObject &attribute)
 Introduced in 2023.0 More...
 
static MFnGeometryData::SubsetState getSubsetState (MDataBlock &block, unsigned int multiIndex, MStatus *ReturnStatus=NULL)
 Introduced in 2023.0 More...
 
static const char * className ()
 Introduced in 2023.0 More...
 

Detailed Description

Introduced in 2023.0

2023.0:
Introduced in this version.

Base class for user defined GPU deformer override evaluators.

MPxGPUStandardDeformer lets you create user-defined GPU deformer overrides in a way that simplifies working with weights and geometry subsets.

It is important that the CPU node with which this GPU deformer is associated is derived from either MPxGeometryFilter or MPxDeformerNode. It will use the internal functionality of these node types to get the subset that is being deformed and the envelope weights to be used.

+ Examples:

Member Function Documentation

void terminate ( )
overridevirtual

This method is called when the GPU deformer is being destroyed.

Any data stored on this object should be released.

Reimplemented from MPxGPUDeformer.

+ Examples:
const MGPUDeformerBuffer & inputPositions ( ) const

This method returns the deformer buffer containing the input positions of the full geometry that is being deformed.

Returns
the deformer buffer holding the input positions
MGPUDeformerBuffer & outputPositions ( )

This method returns the deformer buffer containing the output positions of the full geometry that is being deformed.

Returns
the deformer buffer holding the output positions
MOpenCLBuffer & affectMapBuffer ( )

This method returns the OpenCL buffer containing the indices of the subset of the geometry that is being deformed.

Returns
the buffer holding the affectMap
MOpenCLBuffer & weightsBuffer ( )

This method returns the OpenCL buffer containing the weights for the subset of the geometry that is being deformed.

This means that the length of the weights buffer is the same as the length of the affectMap buffer when envelope weights are being used. In case there are no envelope weights this buffer will be empty. See also: hasEnvelopeWeights.

Returns
the buffer holding the weights
unsigned int affectCount ( ) const

This method returns the number of points in a subset of the geometry.

Returns
the number of points in the subset of a geometry
unsigned int fullCount ( ) const

This method returns the total number of points of the geometry.

Returns
the number of points of the geometry
bool isIdentityMap ( ) const

Returns whether the subset is the full geometry.

This method checks whether the index mapper is an identity map which means that the subset is equal to the full geometry.

Returns
true if it is an identity map
float envelope ( ) const

This method returns the current value of the envelope of the deformer.

This will only hold the correct value after prepareEvaluation has been called.

Returns
the current envelope value
bool hasEnvelopeWeights ( ) const

This method returns whether per vertex weights are being used on this deformer.

This will only hold the correct value after prepareWeightsBuffer has been called. If this returns false the weightsBuffer one must assume the weightsBuffer will be empty.

Returns
true if per vertex weights are used
unsigned int multiIndex ( ) const

Introduced in 2024.0

This method returns the multiIndex of the deformer.

2024.0:
Introduced in this version.

This will only hold the correct value after prepareEvaluation has been called.

Returns
the multiIndex value
const MPlug & inputPlug ( ) const

Introduced in 2024.0

This method returns the inputPlug of the deformer.

2024.0:
Introduced in this version.

This will only hold the correct value after prepareEvaluation has been called.

Returns
the inputPluge
const MIndexMapper & indexMapper ( ) const

Introduced in 2024.0

This method returns the indexMapper of the deformer.

2024.0:
Introduced in this version.

This will only hold the correct value after prepareAffectMapBuffer has been called.

Returns
the index mapper
bool passThroughWithZeroEnvelope ( ) const
virtual

Introduced in 2024.0

This method returns whether this deformer will act as a passThrough when the envelope is equal to 0.0.

2024.0:
Introduced in this version.
Returns
true when this passes through with an envelope of 0.0, otherwise false
MPxGPUDeformer::DeformerStatus prepareEvaluation ( MDataBlock block,
const MEvaluationNode evaluationNode,
const MPlug outputPlug,
const MPlugArray inputPlugs,
const MGPUDeformerData inputData,
MGPUDeformerData outputData,
MAutoCLEvent syncEvent 
)

Prepares the evaluation of this deformer.

This should be called at the start of evaluation of this deformer. It will first check to see if this is passthrough deformer because either no components are being deformerd or the envelope is 0.0. If that is the case it will immediately return kDeformerPassThrough.

It will find the inputGeometry and retrieves the input deformer buffer. Then it will create the the output deformer buffer.

Parameters
[in]blockThe data block of the deformer node to be overridden.
[in]evaluationNodeThe evaluation node of the deformer to be overridden.
[in]outputPlugThe output plug of the deformer to be overridden.
[in]inputPlugsThe list of input plugs which have data in inputData.
[in]inputDataThe input data for this deformer, including geometry.
[in]outputDataThe output data for this deformer, including geometry.
[in,out]syncEventThe synchronization event
Returns
  • MPxGPUDeformer::kDeformerSuccess if the initialization was successful.
  • MPxGPUDeformer::kDeformerFailure if the initialization failed and CPU evaluation should be performed.
  • MPxGPUDeformer::kDeformerPassThrough if the inputPositionBuffer should be used as the inputPositionBuffer by the next deformer.
MPxGPUDeformer::DeformerStatus finishEvaluation ( MAutoCLEvent syncEvent,
MGPUDeformerData outputData 
)

Finish the evaluation of this deformer.

This should be called at the end of the evaluation of this deformer. It will flag the output buffer as ready and then set the outputData to use its content.

Parameters
[in]outputDataThe output data for this deformer
[in]syncEventThe synchronization event
Returns
  • MPxGPUDeformer::kDeformerSuccess if this was successful.
  • MPxGPUDeformer::kDeformerFailure if it failed and CPU evaluation should be performed.
cl_int initializeOutputPositions ( MAutoCLEvent syncEvent)

Initialize the output positions with the input positions.

If only a subset of the geometry is being deformed this ensures that the output buffer will have the unaltered positions of the input buffer for the verts outside the deformation subset.

This will do nothing if the input buffer will be used as the output buffer or if the entire geometry is being deformed since it assumes that in that case all the output positions will be overwritten anyway.

Parameters
[in,out]syncEventThe synchronization event
Returns
returns CL_SUCCESS if the array was uploaded successfully. Otherwise, it returns an OpenCL error code.
bool prepareAffectMapBuffer ( )

Uploads the affectMap to a GPU buffer if needed.

This method retrieves the affectMap using getIndexMapper from the CPU and uploads it to a GPU buffer. It will first check if the affectMap buffer is out-of-date before doing anything so this can be called each evaluation.

Returns
true if the affectMap buffer was updated, false if nothing changed.
bool prepareWeightsBuffer ( const MEvaluationNode evaluationNode)

Uploads the weights to a GPU buffer if needed.

This method retrieves the weights from the CPU and uploads them to a GPU buffer. It will first check if the weights buffer is out-of-date before doing anything so this can be called each evaluation.

Parameters
[in]evaluationNodeThe evaluation node of the deformer which is overridden.
Returns
true if the weights buffer was updated, false if nothing changed.
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:
  • MPxGPUStandardDeformer.h
  • MPxGPUStandardDeformer.cpp