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, OfxMeshInputHandle *input, OfxPropertySetHandle *propertySet)#

Define an input to the effect.

  • pluginHandle - the handle passed into ‘describeInContext’ action

  • name - unique name of the input to define

  • input - where to return the input (if not NULL)

  • propertySet - a property handle for the input descriptor will be returned here (if not NULL)

This function defines an input to a host, the returned property set is used to describe various aspects of the input to the host. The input handle can be used to request specific attributes.

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 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,
   - \e name passed to inputDefine for this context,

Post

  • if meshEffect is a descriptor (i.e. we are inside the describe or describe in context actions), handle will be valid until the end of the action.

  • otherwise, if meshEffect is an instance, 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 (*inputRequestAttribute)(OfxMeshInputHandle input, const char *attachment, const char *name, int componentCount, const char *type, const char *semantic, int mandatory)#

Notify the host that this effect depends on a given attribute on the specified input.

  • input - the input to request an attribute for

  • attachment - attribute attachment (see attachments)

  • name - attribute name

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

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

  • semantic - optional semantic of the attribute data (see attachments), might be NULL

  • mandatory - whether the attribute is mandatory or not.

Requesting an attribute ensures that it will indeed be present in the mesh at cook time only if

mandatory is set to 1. Otherwise, it is the responsibility of the effect, to handle the default value.

For mandatory attributes, the component count at cook time can be equal or larger than the requested size, and for non mandatory ones, it is allowed to be lower. It is the responsibility of the effect to extrapole the missing components from the available ones.

The effect should also be ready to handle attributes that it did not requested but that the host decided to feed it (likely because they are needed by other effects located downstream). 

\pre
  - called from inside the describe or describe in context action
  - input was returned by inputGetHandle
  - inputRequestAttribute was not called with the same \e attachement and \e name combination

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 (*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, const char *semantic, OfxPropertySetHandle *attributeHandle)#

Ensure that an attribute is attached to a mesh.

  • meshHandle - mesh handle

  • attachment - attribute attachment (see attachments)

  • name - attribute name

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

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

  • semantic - optional semantic of the attribute data (see attachments), might be NULL

  • 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 attachment

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 attachment is not valid.

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

  • kOfxStatErrBadHandle - the mesh handle was invalid,

OfxStatus (*meshGetAttributeByIndex)(OfxMeshHandle meshHandle, int index, OfxPropertySetHandle *attributeHandle)#

Get an attribute handle by index from a mesh.

  • meshHandle - mesh handle

  • index - attribute index

  • attributeHandle - property set for returning attribute properties

Pre

  • meshHandle was returned by inputGetMesh

  • attachment is a valid attachment

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 attachment 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 by name and attachment from a mesh.

  • meshHandle - mesh handle

  • attachment - attribute attachment (see attachments)

  • name - attribute name

  • attributeHandle - property set for returning attribute properties

Pre

  • meshHandle was returned by inputGetMesh

  • attachment is a valid attachment

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 attachment 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, kOfxMeshPropCornerCount, 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