Mesh Effect Suite

The Mesh Effect Suite is a set of function pointers that operate on the objects of the Mesh Effect API as they are defined in the section The Mesh Effect API.

struct OfxMeshEffectSuiteV1

The OFX suite for mesh effects.

This suite provides the functions needed by a plugin to defined and use a mesh effect plugin.

Public Members

OfxStatus (*getPropertySet)(OfxMeshEffectHandle meshEffect, OfxPropertySetHandle *propHandle)

Retrieves the property set for the given mesh effect.

  • meshEffect mesh effect to get the property set for

  • propHandle pointer to a the property set pointer, value is returned here

The property handle is for the duration of the mesh effect handle.

Return

  • kOfxStatOK - the property set was found and returned

  • kOfxStatErrBadHandle - if the paramter handle was invalid

  • kOfxStatErrUnknown - if the type is unknown

OfxStatus (*getParamSet)(OfxMeshEffectHandle meshEffect, OfxParamSetHandle *paramSet)

Retrieves the parameter set for the given mesh effect.

  • meshEffect mesh effect to get the property set for

  • paramSet pointer to a the parameter set, value is returned here

The param set handle is valid for the lifetime of the mesh effect handle.

Return

  • kOfxStatOK - the property set was found and returned

  • kOfxStatErrBadHandle - if the paramter handle was invalid

  • kOfxStatErrUnknown - if the type is unknown

OfxStatus (*inputDefine)(OfxMeshEffectHandle meshEffect, const char *name, OfxPropertySetHandle *propertySet)

Define an input to the effect.

  • pluginHandle - the handle passed into ‘describeInContext’ action

  • name - unique name of the input to define

  • propertySet - a property handle for the input descriptor will be returned here

This function defines an input to a host, the returned property set is used to describe various aspects of the input to the host. Note that this does not create an input instance.

Pre

  • we are inside the describe in context action.

Return

OfxStatus (*inputGetHandle)(OfxMeshEffectHandle meshEffect, const char *name, OfxMeshInputHandle *input, OfxPropertySetHandle *propertySet)

Get the propery handle of the named geometry input in the given instance.

  • meshEffect - an instance handle to the plugin

  • name - name of the input, previously used in an input define call

  • input - where to return the input

  • propertySet if not null, the descriptor handle for a parameter’s property set will be placed here.

The propertySet will have the same value as would be returned by

OfxMeshEffectSuiteV1::inputGetPropertySet
This return a input handle for the given instance, note that this will \em not be the same as the
input handle returned by inputDefine and will be distinct to input handles in any other instance
of the plugin.

Not a valid call in any of the describe actions.

Pre

  • create instance action called,

  • name passed to inputDefine for this context,

  • not inside describe or describe in context actions.

Post

  • handle will be valid for the life time of the instance.

OfxStatus (*inputGetPropertySet)(OfxMeshInputHandle input, OfxPropertySetHandle *propHandle)

Retrieves the property set for a given input.

  • input input effect to get the property set for

  • propHandle pointer to a the property set handle, value is returned here

The property handle is valid for the lifetime of the input, which is generally the lifetime of the instance.

Return

  • kOfxStatOK - the property set was found and returned

  • kOfxStatErrBadHandle - if the input handle was invalid

  • kOfxStatErrUnknown - if the type is unknown

OfxStatus (*inputGetMesh)(OfxMeshInputHandle input, OfxTime time, OfxMeshHandle *meshHandle, OfxPropertySetHandle *propertySet)

Get a handle for a mesh in an input at the indicated time.

  • input - the input to extract the mesh from

  • time - time to fetch the mesh at

  • meshHandle - mesh containing the mesh’s data

  • propertySet - property set containing the mesh properties (may be NULL)

A mesh is fetched from an input at the indicated time and returned in the meshHandle.

If inputGetMesh is called twice with the same parameters, then two separate mesh handles will be returned, each of which must be release. The underlying implementation could share mesh data pointers and use reference counting to maintain them.

Pre

  • input was returned by inputGetHandle

Post

  • mesh handle is only valid for the duration of the action inputGetMesh is called in

  • mesh handle to be disposed of by inputReleaseMesh before the action returns

Return

  • kOfxStatOK - the mesh was successfully fetched and returned in the handle,

  • kOfxStatFailed - the mesh could not be fetched because it does not exist in the input at the indicated time, the plugin should continue operation, but assume the mesh was empty.

  • kOfxStatErrBadHandle - the input handle was invalid,

  • kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

OfxStatus (*inputReleaseMesh)(OfxMeshHandle meshHandle)

Releases the mesh handle previously returned by inputGetMesh.

Pre

  • meshHandle was returned by inputGetMesh

Post

  • all operations on meshHandle will be invalid

Return

  • kOfxStatOK - the mesh was successfully released,

  • kOfxStatErrBadHandle - the mesh handle was invalid,

OfxStatus (*attributeDefine)(OfxMeshHandle meshHandle, const char *attachment, const char *name, int componentCount, const char *type, OfxPropertySetHandle *attributeHandle)

Ensure that an attribute is attached to a mesh.

  • meshHandle - mesh handle

  • attachment - attribute attachment (see attachements)

  • name - attribute name

  • componentCount - nomber of components in the attribute, from 1 to 4 (1 is a scalar attribtue, 2 is a vector2, etc.)

  • type - type of the attribute data (float or int, see attachements)

  • attributeHandle - property set for returning attribute properties, might be NULL.

By default, the attribute data is not owned by the mesh (kOfxMeshAttribPropIsOwner is 0)

Pre

  • meshHandle was returned by inputGetMesh

  • attachment is a valid attachement

Post

  • attributeHandle is a valid attribute handle

Return

  • kOfxStatOK - the attribute was successfully fetched and returned in the handle,

  • kOfxStatErrBadIndex - the attribute could not be fetched because it does not exist, or the attachement is not valid.

  • kOfxStatErrValue - the component count or type is not valid.

  • kOfxStatErrBadHandle - the mesh handle was invalid,

OfxStatus (*meshGetAttribute)(OfxMeshHandle meshHandle, const char *attachment, const char *name, OfxPropertySetHandle *attributeHandle)

Get an attribute handle from a mesh.

  • meshHandle - mesh handle

  • attachment - attribute attachement (see attachements)

  • name - attribute name

  • attributeHandle - property set for returning attribute properties

Pre

  • meshHandle was returned by inputGetMesh

  • attachment is a valid attachement

Post

  • attributeHandle is a valid attribute handle

Return

  • kOfxStatOK - the attribute was successfully fetched and returned in the handle,

  • kOfxStatErrBadIndex - the attribute could not be fetched because it does not exist, or the attachement is not valid.

  • kOfxStatErrBadHandle - the mesh handle was invalid,

OfxStatus (*meshGetPropertySet)(OfxMeshHandle mesh, OfxPropertySetHandle *propHandle)

Retrieves the property set for a given mesh.

  • mesh mesh to get the property set for

  • propHandle pointer to a the property set handle, value is returned here

The property handle is valid for the lifetime of the mesh.

Return

  • kOfxStatOK - the property set was found and returned

  • kOfxStatErrBadHandle - if the mesh handle was invalid

  • kOfxStatErrUnknown - if the type is unknown

OfxStatus (*meshAlloc)(OfxMeshHandle meshHandle)

Allocate memory of a mesh in an output input.

  • meshHandle - mesh handle

Pre

  • meshHandle was not allocated yet

  • meshHandle was returned by inputGetMesh

  • inputReleaseMesh has not been called yet

  • meshHandle kOfxMeshPropPointCount, kOfxMeshPropVertexCount, kOfxMeshPropFaceCount properties must have been set.

Post

  • all attribut data pointers for which kOfxMeshAttribPropIsOwner is 1 have been allocated

  • meshHandle attributes will no longer change (no call to meshDefineAttribute)

Return

  • kOfxStatOK - the mesh was successfully allocated,

  • kOfxStatErrBadHandle - the mesh handle was invalid,

  • kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

int (*abort)(OfxMeshEffectHandle meshEffect)

Returns whether to abort processing or not.

  • meshEffect - instance of the mesh effect

A host may want to signal to a plugin that it should stop whatever cooking it is doing and start again. Generally this is done in interactive threads in response to users tweaking some parameter.

This function indicates whether a plugin should stop whatever processing it is doing.

Return

  • 0 if the effect should continue whatever processing it is doing

  • 1 if the effect should abort whatever processing it is doing