The Mesh Effect API#

kOfxMeshEffectPluginApi#

String used to label OFX Mesh Effect Plug-ins.

Set the pluginApi member of the OfxPluginHeader inside any OfxMeshEffectPluginStruct to be this so that the host knows the plugin is an image effect.

Mesh Effect API Header Files#

The Mesh Effect API itself is provided in the ofxMeshEffect.h header file. Other header files are the same as the one provided with the Image Effect API:

The reminder of this page focuses on the objects defined in ofxMeshEffect.h. For the functions that operate on these object, see Mesh Effect Suite.

Mesh Effect#

A Mesh Effect is an operator that expects zero or more meshes as inputs and provides zero or more other meshes as outputs. The behavior of such effect is tunned using parameters as defined in ofxParam.h. They roughly correspond to a node in a node-based 3D modeling tool like Houdini or a modifier in a stack-based generation like in Blender or Cinema 4D. A mesh effect is manipulated using the OfxMeshEffectHandle type.

typedef struct OfxMeshEffectStruct *OfxMeshEffectHandle#

Blind declaration of an OFX mesh effect.

Properties:

kOfxMeshEffectPropIsDeformation#

Tells whether the effect only deforms meshes.

  • Type - bool X 1

  • Property Set - image effect instance (read only)

A deformation-only effect does not alter the connectivity of its main input and always forwards it to its main and only output. This flag is false by default and turning it true might enable optimizations from the host.

kOfxMeshEffectPropPluginHandle#

The plugin handle passed to the initial ‘describe’ action.

  • Type - pointer X 1

  • Property Set - plugin instance, (read only)

This value will be the same for all instances of a plugin.

Mesh Data#

Mesh effects operate on mesh data represented by the OfxMeshHandle type:

typedef struct OfxMeshStruct *OfxMeshHandle#

Blind declaration of an OFX geometry data.

A mesh is the data that flows through the inputs at cook time. They are not available at describe time.

Properties:

kOfxMeshPropPointCount#

The number of points in a mesh.

  • Type - integer X 1

  • Property Set - a mesh instance (read only)

This property is the number of points allocated in the mesh object.

kOfxMeshPropCornerCount#

The number of corners in a mesh.

  • Type - integer X 1

  • Property Set - a mesh instance

This property is the number of face corners allocated in the mesh object.

kOfxMeshPropFaceCount#

The number of faces in a mesh.

  • Type - integer X 1

  • Property Set - a mesh instance

This property is the number of faces allocated in the mesh object.

kOfxMeshPropAttributeCount#

The number of attributes in a mesh.

  • Type - integer X 1

  • Property Set - a mesh instance

This property is the number of attributes stored in the mesh object. Attributes can be attached to either points, corners, faces or the whole mesh. There are at least three attributes in a geometry namely the point’s position, the corner’s point association and the face’s corner count.

kOfxMeshPropNoLooseEdge#

Whether the is loose-edge free or not.

  • Type - bool X 1

  • Property Set - a mesh instance

This property is true by default and must be turned false when the mesh has loose edges, namely edges that are not part of any face (a loose edge is a 2-corners faces). Turning this false when there is actually no loose edge must not change any behavior but may affect performances since a host might use this information to speed up processing of loose-edge free meshes.

kOfxMeshPropConstantFaceSize#

Number of corners per face, or -1.

  • Type - int X 1

  • Property Set - a mesh instance

When all faces have the same number of corners, this property may be set to this number in place of using the kOfxMeshAttribFaceSize attribute, thus reducing memory allocation and potentially enabling speed-ups on host side. This property is -1 when faces have a varying number of corners.

kOfxMeshPropTransformMatrix#

Matrix converting the mesh’s local coordinates into world coordinates.

  • Type - pointer X 1

  • Property Set - a mesh instance (read only)

This points to an array of 16 doubles representing a transform matrix in row major order. Some mesh effect inputs may be used only for their location or matrix. Some others might ignore this property as they operate in local coordinates. This pointer may be NULL in which case the transform is assumed to be the identity.

kOfxInputPropRequestGeometry#

Whether the input depend on the mesh geometry.

  • Type - bool X 1

  • Property Set - an input’s property set

Default to true, may be switched to false when the input is used solely for its transform (in which case

See

kOfxInputPropRequestTransform is turned true).

kOfxInputPropRequestTransform#

Whether the input depend on the transform matrix of the mesh.

  • Type - bool X 1

  • Property Set - an input’s property set

Can be set in describe mode to tell the host to fill in the

See

OfxMeshPropTransformMatrix property at cook time. This will also trigger recooking every time this input’s transform changes. Default to false.

Inputs and outputs#

Inputs and outputs of a mesh effect are the same type of object, both manipulated using the OfxMeshInputHandle type:

typedef struct OfxMeshInputStruct *OfxMeshInputHandle#

Blind declaration of an OFX mesh effect input.

An “input” is a slot of the effect that can actually also be an output. Such a slot can require at describe time specific information from the host so that the host can cook it again every time these information change (e.g. if the effect depends on the location of the object its kOfxMeshPropTransformMatrix) and to only transfer geometry attributes that are actually needed by this effect.

Some hosts may give a special meaning to kOfxMeshMainInput and kOfxMeshMainOutput, in particular if they only support the filter context (like Blender’s modifiers).

kOfxMeshMainInput#

Identifier of the main mesh input of a mesh effect.

kOfxMeshMainOutput#

Identifier of the main mesh output of a mesh effect.

Custom Attributes#

The OpenMfx API supports attaching any custom attribute to either points, corners or faces. A fourth attribute attachment is for attributes with only one instance (the equivalent of detail attributes in Houdini). Some of these attributes are conventional and expected to always be present.

Attribute attachments:

kOfxMeshAttribPoint#

Mesh attribute attachment to points.

kOfxMeshAttribCorner#

Mesh attribute attachment to corner.

kOfxMeshAttribFace#

Mesh attribute attachment to faces.

kOfxMeshAttribMesh#

Mesh attribute attachment to the whole mesh.

Conventional attributes:

kOfxMeshAttribPointPosition#

Name of the point attribute for position.

kOfxMeshAttribCornerPoint#

Name of the corner attribute for point index.

kOfxMeshAttribFaceSize#

Name of the face attribute for corner count.

This is ignored if the mesh’s kOfxMeshPropConstantFaceSize property is different from -1.

Attribute request:

Attribute request using inputRequestAttribute is a mean for the effect to tell the host at describe time that it will need a particular attribute to be available at cook time. It can also notify the host from attributes that are not mandatory but that it would make good use of, to have the host recook the effect any time this attribute changes.

Attribute properties:

An attribute is represented by a generic OfxPropertySetHandle that provides the following keys:

kOfxMeshAttribPropData#

The data pointer of an attribute.

  • Type - pointer X 1

  • Property Set - a mesh attribute

This property contains a pointer to memory where attribute data is stored, whose size depend on the attribute attachment (point/corner/face/mesh) and attribute type (int, float, vector, etc.)

kOfxMeshAttribPropIsOwner#

Whether the mesh effect owns its data.

  • Type - bool X 1

  • Property Set - a mesh attribute (read only)

The mesh effect must free its data on destruction iff it owns it. In most cases, it is recommended to use the mesh effect attributes as proxies to data structures owned by the underlying host mesh structures, so this is 0, but in some cases where the data layout does not allow it, some memory is allocated in the mesh and this flag must hence be set to 1, so that memory is automatically freed on mesh release.

kOfxMeshAttribPropStride#

The stride of an attribute.

  • Type - int X 1

  • Property Set - a mesh attribute (read only)

This property contains the number of bytes between the beginning of two values of the attributes in the buffer to which the data property points.

kOfxMeshAttribPropComponentCount#

The number of components an attribute.

  • Type - int X 1

  • Property Set - a mesh attribute (read only)

An attribute can have between 1 and 4 components.

kOfxMeshAttribPropType#

The type of an attribute.

  • Type - string X 1

  • Property Set - a mesh attribute (read only)

Possible values are kOfxMeshAttribTypeFloat, kOfxMeshAttribTypeInt or kOfxMeshAttribTypeUByte

NB The plugin_support code in the Implementation section provides fonctions to more easily access this information for plugin writers.

Attributes types:

kOfxMeshAttribTypeUByte#

Attribute type unsigned integer 8 bit.

kOfxMeshAttribTypeInt#

Attribute type integer 32 bit.

kOfxMeshAttribTypeFloat#

Attribute type float 32 bit.

Attributes semantics:

Attribute semantics tell what the intended usage of the attribute data is prior to and beyond the effect.

kOfxMeshAttribSemanticTextureCoordinate#

Attribute semantic for texture coordinates (sometimes called “UV”)

Such attribute is usually attached to corners (or sometimes to points), has 2 floats or 3 floats (when using Udims) and is softly limited to the (0,1) range for each.

kOfxMeshAttribSemanticNormal#

Attribute semantic for normal vectors.

Such attribute is usually a 3 float unit (i.e. normalized) vector attached to corners or points, but may also be computed for faces. They represent the orthogonal to the local surface and are used for instance for shading.

kOfxMeshAttribSemanticColor#

Attribute semantic for colors.

Colors can be attached to any entity. They are may be 3 or 4 floats softly limited to the (0,1) range, or 3 or 4 integers/ubyte in the (0,255) range, or 1 integer encoding an RGBA color on its bytes.

kOfxMeshAttribSemanticWeight#

Attribute semantic for weights.

Weights are simple scalar values (i.e. 1-component floats), often softly limited to the (0,1) range.