File ofxColour.h

Contains the API for colourspace data exchange.

Defines

kOfxImageEffectPropColourManagementStyle

What style of colour management does the host or plug-in offer?

Define OFX_NO_DEFAULT_COLORSPACE_HEADER if you want to manage the colourspace headers yourself. If this is not defined, the latest ofx-native config will be included.

Hosts should set this property if they will provide colourspace information to plug-ins. Plug-ins should set this property if they can use host-provided colourspace information. Collectively, the full, core and basic styles are referred to as native colour management. OCIO is used as the reference for the colour management API, but is not required to implement the native styles.

The colourspace strings used in the native styles are from an OFX-specific OCIO config which is currently based on the OCIO ACES Studio built-in config, studio-config-v2.1.0_aces-v1.3_ocio-v2.3, and stored for OFX purposes in ofx-native-v1.5_aces-v1.3_ocio-v2.3.h (referred to as the config header). Additionally, there is a scheme for cross-referencing between clips, and a set of “basic colourspaces”, which are designed to be generic names for a family of colourspaces. When a basic colourspace is used, this means the host is free to choose any colourspace with the same encoding and reference space (scene vs display).

The assumption is that OCIO > Full > Core > Basic, so the highest style supported by both host and plug-in should usually be chosen by the host. The chosen style must be set by the host using this property on an image effect instance.

kOfxImageEffectColourManagementNone
kOfxImageEffectColourManagementBasic
kOfxImageEffectColourManagementCore
kOfxImageEffectColourManagementFull
kOfxImageEffectColourManagementOCIO
kOfxImageEffectPropColourManagementAvailableConfigs

What native mode configs are supported?

While the API for colour management is expected to be stable, the set of colourspaces will evolve over time. This property must be set by both plug-ins and hosts specifying the list of native mode configs that are available on each side.

  • Valid Values - A list of config identifiers. The only currently supported value is ofx-native-v1.5_aces-v1.3_ocio-v2.3.

kOfxImageEffectPropColourManagementConfig

The native colour management config to be used for this instance.

The host must set this property to indicate the native colour management config the plug-in should be used to look up colourspace strings. It is important to set this even in OCIO mode, to define the basic colourspaces.

  • Valid Values - any string provided by the plug-in in kOfxImageEffectPropColourManagementAvailableConfigs

kOfxImageEffectPropOCIOConfig

The path to the OCIO config used for this instance.

A host must set this property on any effect instances where it has negotiated OCIO colour management (kOfxImageEffectColourManagementOCIO). Use of URIs for built-in configs, such as ocio://default is permitted.

  • Valid Values - Filesystem path to the config or URI starting ocio://

kOfxImageClipPropColourspace

The colourspace used for this clip.

Hosts should set this property to the colourspace of the input clip. Typically it will be set to the working colourspace of the host but could be any valid colourspace.

Both host and plug-in should use the value of kOfxImageClipPropPreferredColourspace where reasonable.

In OCIO mode, a basic colourspace may have been requested via kOfxImageClipPropPreferredColourspaces, but the actual colourspace used should be reported in this property. If an OCIO host has added the basic colourspaces to its config as roles or aliases, they would be permitted here.

Cross-referencing between clips is possible by setting this property to “OfxColourspace_<clip>”. For example a plug-in may set this property during kOfxImageEffectActionGetOutputColourspace to “OfxColourspace_Source”, telling he host that the colourspace of the output matches the “Source” input clip. In the basic style, plug-ins are recommended to use cross-referencing for their output clip unless kOfxColourspaceRaw is required.

If a clip sets OfxImageClipPropIsMask or it only supports OfxImageComponentAlpha, colour management is disabled and this property must be unset.

  • Valid Values - colourspace that is permitted under the style in use. For OCIO, any string acceptable to Config::getColorSpace()

kOfxImageClipPropPreferredColourspaces

The preferred colourspace for this clip.

Plug-ins may set this property during kOfxImageEffectActionGetClipPreferences to request images in a colourspace which is convenient for them. The property is an ordered set of colourspace identifiers, which may be any of the names or aliases supported by the colour management style in use. If plug-ins prefer more esoteric colourspaces, they are encouraged to also include basic colourspacesas a fallback. For example a colour grading plug-in which supports a specific camera and expects a log colourspace might list:

“arri_logc4”, “arri_logc3_ei800”, “ACEScct”, “ofx_scene_log”

The host is free to choose any colourspace from this list, but should favour the first mutually agreeable colourspace, and set kOfxImageClipPropColourspace to tell the plug-in which colourspace has been selected. A host does not need to convert into the first choice just because it can, as this might be inefficient, and should avoid scene-to-display or display-to-scene conversions where possible.

In the event that the host cannot supply images in a requested colourspace, it may supply images in any valid colourspace. Plug-ins must check kOfxImageClipPropColourspace to see if their request was satisfied.

In both native and OCIO modes, it is recommended to include basic colourspaces in this list, because this gives the host more flexibility to avoid unnecessary colourspace conversions.

Hosts can invoke kOfxImageEffectActionGetOutputColourspace to set this on an output clip, which could be helpful in a generator context, and plug-ins should follow the same logic as hosts when deciding which colourspace to use.

It might be much less costly for a host to perform a conversion than a plug-in, so in the example of a plug-in which performs all internal processing in scene linear, it is sensible for the plug-in to universally assert that preference by preferring kOfxColourspaceOfxSceneLinear, and for the host to honour it if possible. However, if a plug-in is capable of adapting to any input colourspace, it should not set this preference.

Cross-referencing between clips is possible by setting this property to “OfxColourspace_<clip>”. For example, a plug-in in a transition context may set this property on its “SourceTo” clip to “OfxColourspace_SourceFrom”, telling the host it would like both input clips to be in the same colourspace.

If a plug-in has inputs which expect motion vectors, depth values or other non-colour channels, it should set the preferred colourspace to kOfxColourspaceRaw. Similarly, if a host requests outputs in a typical scene colourspace, but the plug-in is producing motion vectors, it should ignore the request and set kOfxImageClipPropColourspace to kOfxColourspaceRaw.

  • Valid Values - colourspace that is permitted under the style in use. For Basic, any colourspace from the config header where IsBasic is true. For Core, any colourspace from the config header where IsCore is true. For Full, any colourspace from the config header. For OCIO, any string acceptable to Config::getColorSpace(), or a basic colourspace.

kOfxImageEffectPropDisplayColourspace

The display colourspace used in the plug-in’s viewport.

Used with native colour management styles, this property is relevant for plug-ins which have their own viewport in a custom window. Plug-ins should not expect this to be available during a render event. Hosts should set this property to a display colourspace which matches that used in its own viewport. For a multi-display system, choose the colourspace for the display device where a native window would appear by default. A host which supports OCIO should use the OCIO-specific display and view properties instead.

  • Valid Values - any colourspace from the config header

kOfxImageEffectPropOCIODisplay

The OCIO display to be used in the plug-in’s viewport.

This OCIO-specific property allows the host to specify which OCIO display should be used. If not defined, the default rules for choosing a display will be followed.

  • Valid Values - OCIO display that is present in the config

kOfxImageEffectPropOCIOView

The OCIO view to be used in the plug-in’s viewport.

This OCIO-specific property allows the host to specify which OCIO view should be used. If not defined, the default rules for choosing a view will be followed.

  • Valid Values - OCIO view for the display specified by kOfxImageEffectPropOCIODisplay

kOfxImageEffectActionGetOutputColourspace

This action allows a host to ask an effect, given a list of preferred colourspaces, what colourspace will be used for its output clip. This should be called after first gathering the plug-in’s preferred input colourspaces via OfxImageEffectActionGetClipPreferences.

Cross-references to input clip colourspaces are permitted, for example in a filter context, the host might request “OfxColourspace_Source”.

If a host wants to rely on the output clip colourspace, it must call this action whenever the effect instance is changed. Do not assume that the output colourspace will be the same across all instances of an effect, or even for the lifetime of an effect instance, because a plug-in may change its output colourspace based on a user changing a parameter. Assume that the plug-in will check kOfxImageClipPropColourspace on its input clips during this action in order to decide the output clip colourspace, so the action must be called again if the host changes any of the other colour properties.

On a successful return from this action, the host must set kOfxImageClipPropColourspace on the instance’s output clip to the value from outArgs.

Parameters:
Returns:

  • kOfxStatOK, the action was trapped and the colourspace was set in the outArgs property set

  • kOfxStatReplyDefault, the action was not trapped and the host should use the colourspace of the first input clip

  • kOfxStatErrMemory, in which case the action may be called again after a memory purge

  • kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message

  • kOfxStatErrFatal