Standard Changes

Several aspects of the API were, in their original conception, perceived to be fixed for the whole temporal duration of an effect, and generally under the control of the application. This, unfortunately, is not true, and has caused problems for various plug-in hosts and developers.

Initially this consisted of what pixel formats and data types were present on input clips and how they should be...

Some effects are continuous distortions of an image (eg: a lens correction tool), the simplest case being an effect that performs a simple matrix based transform (eg: a stablisation tool).

A user often applies a series of such effects in a row, and if each effect processes the image, you end up with a significantly degraded image, as each effect will separately filter the image.

If an effect...

Some plug-in developers wish to have a variable number of input clips to their effects. At run time a user would be able to keep wiring more and more input to the effect. Not all hosts could support this, but many could.

To do this you would need to have properties indicating whether the host was capable of doing this, and whether the plug-in wanted such behaviour.

Given the current 'fetch by...

Being able to amend the parameter set on a plugin instance after creation would be a useful feature for many plugin developers. In response to user initiated action (eg: a button press), a plugin should be able to both define new parameters or destroy existing parameters on the given instance.

Currently, entry points need to be unique. For example, multiple plug-ins in the same binary cannot use the same main entry point. Similarly, any custom parameter interact, each parameter needs it's own entry point. This makes it difficult to wrap the plugin API with generic support code.

The reason for this is that there is no information passed back to a plug-in from the host, which allows it...

The current ImageEffect architecture abstracts what comes out of the effect as the output clip. 

Thus the A.P.I makes multiple assumptions that are not clearly indicated as to which functions a plug-in may call on the output clip and when.

For instance:

- The clipGetImage function on the output clip takes the same parameters as if it were called on a source clip,...

There is no way to set Parameter Interpolation Type in OFX

Example:  In Nuke (example of an host that does not support animated popup menus), we need to make an animated menu create an associated integer parameter that we set when user change the popup.  However the expected behavior would be Constant_Step, now the integer is interpolated, so somewhere between menu 3 and 1 we get menu...

I was under the impression that paramEditBegin would be interpreted by host not just in terms of grouping parameters for undo but as well as indicator that we are about to write a bunch of key-frames.  So tested in Nuke, Fusion and Natron and same, even within EditBegin-End each time we add a key-frame within InstanceChanged which is what happens during a sequence analysis, InstanceChanged...

Private data is parameter data a plugin keeps in its own data structures. These are for large or complex data types that can't be represented with the current parameter set. For example a custom roto-spline parameter. For persistance, and possibly animation, private data needs to be synced back into a plugin's actual parameter set at some point so the host can deal with the data appropriately....

A range of spatial values, which refer to regions on the image plane or pixels in the UI, are specified as doubles rather than ints. These are are both properties on several actions’ in and out args, as well as a returned value from a function in a suite.

The following properties should have been integers rather than doubles….

• kOfxImageEffectPropRegionOfDefinition

• ...

This is complement to: kOfxParamPropModifiable proposal

http://openeffects.org/standard_changes/property-to-hint-that-parameter-properties-can-be-dynamically-changed

The purpose is to list possible ambiguities in API regarding parameters

1) Apparently we do not specify that we expect Boolean and Choice to be "step" animation (as opposed to linearly interpolated as if they were regular int)...

Plugins with private data currently save their values into custom params, which are simply strings. It would be more efficient to allow plugins to encode/decode serialised data with a binary blob.

There is a need for a suite that allows a plug-in to cache internal data during render calls for retrieval in a subsequent render call, e.g. retimer caching motion vectors. This is especially important if we split off separate render object from the persistent instance.

A new Caching Suite should be created, that allows plugins to use host side data caching. Basically a giant key/value pair...

(sept 23, 2016) - this is to be simultaneously addressed with caching and multi-processing.

Currently only one kind of plug-in instance is recognised, this is used for everything, interface, caching state, rendering etc… Many host applications have severe problems with this model, as they typically have separate render objects that are either lightweight special purpose render objects,...

There is little to no information about the colour space (tone curve and RGB chromaticities) in which image sample values are to be interpreted.

Historically there has been some assumption that the tone curve is probably linear, with a nominal black point at 0.0 and nominal white point at 1.0, but this is not specified and is often not the case.

Depending on the host, unmodified images...

See OpenCL notes (should be similar)

(september 23, 2016): This is to be merged with Multi-View

A recent trend is to embed multiple image types in the same image stream, for example depth information as well as colour data. The current version 1.4 OFX Image Effect API only presents a single colour image buffer from any clip, either input or output. This prevents hosts with rich image streams from passing such data to plug-ins...

(sept 23, 2016): This to be co-addressed with Spatial Formats are broken

Generators, as conceived, are not very good. They need to be broken into two types…..

• generators that determine their own formats, e.g. a file reading plug-in
• generators that leave format determination to the host application, eg: a spatial noise generator that can make noise anywhere on the image plane.

...

Below is 5 different topics that can be considered. It does not have to end up all in one suite but it should maybe be discussed at same time.

-       CPU based effect registering GPU ressource usage

Host that render multiple frames at once and switch GPU per frame, could report the GPUid so we don't load the same GPU making it easier on the host in...

I think for host that have in and out trim points in their user interface, it should be documented what the host should then.

And because this is essentially what it does and there is no API to capture that.

We need to maintain the integrity of the OFX time regarding the source clip (e.g. changing the trim in-point does not affect then where a particular frame is in OFX Frame time - so...

With modern VFX systems, arbitrary extra metadata is available on the clips passed to an effect, such as camera shot on, colour space, and much much more. Some of this data is very useful to effects and they may need to transform the metadata that is presented on output. Currently OFX does not support metadata, and it should.

(jan 22, 2017, Pierre Jasmin):  Adding some notes, 

We have...

Stereo motion pictures are now common, and various visual effects applications have been updated to include a stereo work flow. Typically this is done by embedding multiple views within an image stream.

The Foundry has implemented an unpublished extension to the OFX API in its Nuke compositing application to deal with multiple views within a clip. We are proposing cleaned up versions of these...

(sept 23, 2016) - this has been merged in multi-view/ multi-plane discussion

It would be useful for some plugins to be able to produce multiple outputs, such as a Degrain plugin that can produce a degrained image and a grain map that could be added later by a matching Regrain plugin. Currently there is no way for a plugin to tell the host that it has more than one output, since clips are...

For hosts and plug-ins that support OpenCL rendering, it would be good to have an OpenCL equivalent of the OpenGL rendering suite. This would remove performance issues with pushing data needlessly into OpenGL.

Given OpenCL and OpenGL suites, it would be good to make sure both are compatible and are capable of resource sharing where needed.

1) Flushing in current V1 suite is likely to be addressed via GPU utility suite.  It has become not sufficient in an age where a GPU can have 24 GB of VRAM.

2) The currently suggested fallback in documentation are likely to be superseeded by a GPU utility suite fallback hand shake

3) Option to disable/enable suite in Instance Changed action is not well documented in v1.4

4) Multi-Threading...

This was formely Property to hint that parameter properties can be dynamically changed and has now been superseded to include other properties.

Overview to redo, new proposed solution is to have a PropTesting suite -  INFO only  - which allows us to check
1) If host supports that (anything with Prop in name basically) 
2) In case of parameters this extends to write-able properties,...

I think RE:Vision and Foundry via API email thread had a reasonable compromise. Paste in our discussion as reference. Imagineer has offered interest in such suite. This is an old discussion at this point, might have changed my mind and some of the supporting visuals are gone. I repaste anyway as reference. (Sorry for formatting)

 
Essentially we need a single shape parameter and a dynamic...

Regions of definition are well defined concepts within OFX, the ‘format’ of a clip is not. For example a clip may be HD, 4K, SD etc… while the RoD need not be congruent to the ‘format’ at all. Furthermore, effects have no way of changing the spatial format. For example an effect that up scales images from SD to 4K would want to flag the change in format as well as...

Some hosts support 3d compositing with cameras and lights. AE even has this. The OFX API could allow plug-ins to use the host's camera and lighting information, where available, to create interesting effects.

Nuke has a private suite for Camera already.

It has been suggested that the threading API needs to be extended radically or deprecated entirely and replaced with host OS threading. There are pros and cons to each option.

In case of deprecation, the plug-in should be informed of the maximum number of threads it should be using by the host application.

There can be multiple reasons for a plugin not wanting to get loaded in an host.version. For example the plugin might depend on a feature not supported by an host (e.g. a camera suite)

It is suggested that the OFFICIAL way of doing this would be to simply not support any context and return StatDefault.

This needs to be clearly documented somewhere so effect developers are aware of this.

The API is meant to be called in a parallel manner, so that a host application may call actions on a plugin from any number of threads and have the API work. The only constraint on a plugin is that any calls back to the host via a suite must be from the thread the initial action was invoked from. 

This problem arises when a host calls actions in parallel. It may have some private data...

renamed for consistency:

kOfxImageEffectHostPropNativeOrigin

Sometimes it is good for a plugin to know where the native origin of the host is and whether the coordinate system is Y-Up or Y-Down. This is strictly a UI hint to plugin.

It's good we have a simple base image / frame buffer model (lower-left, RGBA, rowbytes...) - however some applications are natively not lower-left which...

The Message Suite takes a unique messageID with each message posted, along with a text string. That messageID can be used to lookup alternate text strings in a companion XML file for use instead. This can be used to present internationalised messages and so on. The progress suite does not do this, it takes a hard coded string and so we can't internationalise any progress message.

This is just a reminder

Aside a few minor doc things t (like good programming notes for example that paramGetValue without time is an issue for some hosts with multiple render threads so it's safer not to use in render calls..)  and PropRenderScale is probably missing note about Interact Callbacks 

kOfxParamPropInteractMinimumSize  is now a double like...

Suggested Solution For Plugin Instances

The following properties, currently only settable in the describe actions, should be dynamically setable in an instance.

• kOfxImageEffectPropSupportsTiles

• kOfxImageEffectOpenGLRenderSupported

For example a plugin might support tiles in CPU but not in GPU

For example an host might be GPU centric but a driver comes up and break plug-in...

We amend the documentation of progress suite so that it is expected that it can be raised in a modal manner and have a ‘cancel’ button. Plugins that perform analysis post an appropriate message, raise the progress monitor in a modal manner and should poll to see if processing has been aborted. Any cancellation should be handled gracefully by the plugin (eg: reset analysis parameters...

We removed the concept of analysis pass early on, but the property kOfxImageEffectPropInAnalysis is still specified, and the documentation still mentions it.

Render action InArgs property. Draft/Preview is typical for scrubbing, Best is typical for render. These allow a plug-in to take short-cuts for improved performance when the situation allows.

Note (by Pierre Jasmin):  Gary from Genarts was saying this need to be changed. Not the proper way to do this.

Gary (2015-04-30): Consulting with the team here, I now think the API functions are OK, but need better documentation of what's supposed to be passed where and when.  I'll work on an update.  Need an interested host partner to implement. (Assimilate has a version but...