eliemichel / openmfx

A low-overhead mesh-processing plug-in API for cross-software procedural effects

 

OpenMfx

Table of Contents

• What is this?
  • The OpenFX Mesh Effect API
  • Why a standard
• Quick Start
  • Download and run
  • Project layout
  • Writing a plugin
  • Writing an host
• Going further
  • Available implementations
  • Contributing
• License

What is this?

The OpenFX Mesh Effect API

OpenMfx is a plug-in standard for 3D mesh processing effects built on top of OpenFX, a standard originally designed for 2D image processing.

The official documentation of the API is located at https://openmesheffect.org

NB OpenMfx was first known as "Open Mesh Effect", we decided to rename it because "OpenMfx" is easier to abbreviate and was emerging from the usage anyways.

Why a standard?

Many 3D software feature some non destructive workflow, relying on procedural geometry effect being recomputed on the fly whenever the underlying mesh data is modified. One can quote for instance Houdini SOPs, some of Maya's nodes, or Blender's modifiers. Unfortunately, usual open exchange formats do not support these, as they might be implemented differently in different software, forcing geometries to be "baked" at export. This destructive step prevents one from tweaking the procedural parameters again. A standard description of such mesh effects will lead to effect that work exactly the same way in various software, enabling exchange formats to store meshes without baking them first.

OpenFX has been designed for 2D images, it is completely different from 3D meshes, so why using it?

The OpenFX standard has been cleverly separated into several parts, leaving its core very generic. This OpenFX Mesh Effect API leverage on this agnostic core (called ofxCore) but completely ignores the image related part (ofxImageEffect). Instead, it defined an ofxMeshEffect, following similar patterns where it is relevant.

For a more complete post about the motivations behind OpenMfx, see The need for Open Mesh Effect.

Quick Start

Download and run

1. OpenMfx is a plugin API. In order to run a plugin, you need an OpenMfx-compliant host. To quickly get started, we recommend to download a release of our Blender branch.

2. Then download a plugin, for instance the MfxExamples plugin. Unzip the archive so that you get a .ofx file. This is the plugin.

3. Start our Blender branch, add a modifier to the default cube. Select new type of modifier called "OpenMfx".

4. In the Plugin Path field, browse to the .ofx file that you downloaded at step 2.

5. A plugin file can contain multiple effects. If the plugin loaded correctly, you can chose one from the drop down menu bellow the Plugin Path field. Choose for instance the Explode effect. Otherwise, you should see an error message in the modifier's UI.

6. You may now play with the effect's parameters.

7. An other way of using an OpenMfx plugin is as a node in a Geometry Node graph. Go to the Geometry Nodes tab of Blender, and press New in the header of the node graph area.

8. Add a new node, search for "OpenMfx Plugin" in the Add menu. The same process as for the modifier goes, you first browse to the .ofx file, then select the effect and finally tune its parameters.

Project layout

The API itself is only a set of headers found in include/. To make the creation of hosts and plugins easier, an ecosystem of C and C++ libraries has been developed around, called the SDK.

Writing a plugin

The easiest way to write your own plug-in, is to follow the C++ SDK tutorial. You can also just start from the MfxExamples repository and adapt it to your needs.

Writing an host

There is no tutorial yet for this, but you can look at sdk/examples/cpp/host.

Going further

Available implementations

Hosts

Existing host software that supports OpenMfx are listed here.

Plug-ins

To use existing plug-ins, check out this list of existing plug-ins.

Contributing

Although the standard itself is getting more stable, help is welcome to improve the ecosystem of tools. Feel free to give some feedback through the GitHub issues of this repository.

License

OpenMfx is free and open source, and compatible with the use in commercial software. See LICENSE.md.

openmfx's Issues

Exceptions removal

Hi.

Is openmfx defined with functions, in games and such we prefer error codes.

Is it valid to remove the exception code?

Add a global transform property on meshes

As pointed out by @tkarabela in eliemichel/OpenMfxForBlender#35 there would be a fair need for a kOfxMeshPropTransform to provide a global transform matrix. So also we need a way to have matrices in properties maybe.

Attribute forwarding and memory safety

Follow-up on question from #6 on how to safely do attribute forwarding.

@eliemichel It is possible already to point the output at the same buffer as the input, for unchanged attributes, and in particular for connectivity information when the effect only is a modifier.

@tkarabela In terms of API, it might be a minor issue that by the time the output mesh is inputReleaseMesh()-ed, the mesh with the forwarded attribute may have already been inputReleaseMesh()-ed before, as order of releasing is undefined.

Presently, mesh releasing is done by the effect at end of cooking, one mesh at a time. We could simply say in the spec that if you are using attribute forwarding, you must not release the mesh you're forwarding from before releasing the mesh you're forwarding to.

In practice, a general rule of thumb "first release outputs, then inputs" should work fine, as long as you don't have multiple outputs forwarding between one another.

Let effects declare they depend on global transform

Now that we have #5, I've tried it in the Blender implementation and noticed that while the transform is passed correctly, it only gets passed in once when the modifier is created. Changing the transform interactively does not lead to re-cooking.

This seems like good default behavior and optimization, but it makes the transform kinda pointless.

We should let the effect declare at describe time that it depends on the transform, so that the host can re-cook it as needed. Should it be "global" like the deformer property, or tied to input mesh (so that the effect can depend on transform of some input, but not other input - would that be even useful)?

Variable number of inputs

We should extend the API to support effects that can take a variable number of inputs, like Houdini's Merge SOP, or to allow effects that take a collection as input (see OpenMfxForBlender#60).

Maybe rename "Vertex" into "Corner"

The terms point/vertex/face were originally chosen according to Houdini's naming convention, and it also matches Pixar's USD. But "vertex" is misleading to many people because in some softwares it may have a different meaning. In particular, in Blender, Maya and 3DS Max it means what we call "point", making everything a bit harder to follow.

A good candidate so far seems to be "Corner", as in "face corner", which already feels like the most natural way to explain what "vertices" are with respect to "points". Other existing names are "Loops" (quite unique to Blender, and a bit ill-named imho even though I understand why it is so) or "Elements" (as in "element buffer" using in graphic APIs, I find it more abstract).

Memo of things to change in case of such a renaming (it'll touch a lot of things):

• Rename in all ofxMeshEffect.h
• Rename in API reference
• Rename in C++ SDK
• Rename in SDK tutorial and figures
• Rename variables in host implementation

External input and thoughs are welcome here!

(Thanks @tkarabela for investingating about other APIs btw)

Ongoing design goals

This started as a follow up of #27 of the Blender Host, from which a lot of relevant insights and ideas emerged.

Already integrated:

• (2B) Add a kOfxMeshPropNoEdge boolean property turned on by default, that one must turn off when building a mesh with loose edges.
• (2C) Add a kOfxMeshPropConstantFaceCount property type to meshes to skip the use of the kOfxMeshAttribFaceCounts buffer when it is not -1.
• (2D) Add a kOfxMeshEffectPropIsDeformation boolean property turned off by default that one can turn on to speed up processing when the effect does not affect connectivity.
• (B) Add a way for effects to request attributes to the host
• Add semantics (kOfxMeshAttribPropSemantic) to attributes in order to flag their usage (UV, weight group, etc).

Summary of the proposals:

Unsolved issues:

• How to list the available attributes in a mesh

Rejected:

• (2E) Introduce arbitrary edge attributes (kOfxMeshAttribEdge) with no such attribute by default

A solution for (B) would indeed take place during the Describe action. And this is needed beyond just connectivity: an effect must be able to tell whether it needs UVs or not, or this or that specially named attribute, etc. It would enable sending only the relevant attributes, and also let the Host's UI tell the user about important missing attributes. I imagine this as a set of kOfxInputProp* maybe.

---

@tkarabela Regarding your issue (A), there's this little advertised fact: It is possible already to point the output at the same buffer as the input, for unchanged attributes, and in particular for connectivity information when the effect only is a modifier.

About the "knowing the exact edge count in mixed cases" problem, do you believe that iterating once over the faceCounts attribute prior to allocating teh mesh introduces too much overhead? I think that anyway that's how many plugin writers would fill the loose edge count property anyways.

Replace ad-hoc OfxSetBundleDirectory with the new OfxSetHost

For practical purposes, we had to add the OfxSetBundleDirectory entry point that is not part of the original OpenFX standard. This has been addressed upstream lately and the standard OfxSetHost has been introduced. Thus our OfxSetBundleDirectory is no longer needed.

This requires all the hosts and plugins that were using OfxSetBundleDirectory to change (e.g. MfxHoudini).

Blender 3.2 support

Hi, I wanted to test Blender <-> OpenMfx <-> Houdini as part of https://itch.io/jam/houdini-game-jam-2022.

When I tried installing into Blender 3.2, it failed. I'm lost. Can you investigate?

💯 OpenMfx is so cool!

Mention "kOfxMeshEffectPropContext" etc. in documentation

• https://github.com/eliemichel/OpenMfx/blob/e0807499328e78f4c8cad56689c554cb4776e5e9/doc/Reference/ofxMeshEffectActions.rst
  • this page should mention kOfxMeshEffectActionDescribeInContext in the "Actions specific to Mesh Effects" section
  • currently it only mentions in docs for kOfxActionDescribe that "kOfxImageEffectActionDescribeInContext will be called once for each context that the host and plug-in mutually support" which is not correct
• https://github.com/eliemichel/OpenMfx/blame/e0807499328e78f4c8cad56689c554cb4776e5e9/doc/Reference/ofxMeshEffectAPI.rst#L30-L41
  • kOfxMeshEffectPropContext, kOfxMeshEffectContextGenerator etc. have Doxygen documentation but are commented out in the Sphinx docs so they don't show up