Properties Reference

kOfxImageClipPropColourspace

The colourspace used for this clip.

  • Type - string X 1

  • Property Set - clip instance (read/write)

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

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.

kOfxImageClipPropConnected

Says whether the clip is actually connected at the moment.

  • Type - int X 1

  • Property Set - clip instance (read only)

  • Valid Values - This must be one of 0 or 1

An instance may have a clip may not be connected to an object that can produce image data. Use this to find out.

Any clip that is not optional will always be connected during a render action. However, during interface actions, even non optional clips may be unconnected.

kOfxImageClipPropContinuousSamples

Clip and action argument property which indicates that the clip can be sampled continously.

  • Type - int X 1

  • Property Set - clip instance (read only), as an out argument to kOfxImageEffectActionGetClipPreferences action (read/write)

  • Default - 0 as an out argument to the kOfxImageEffectActionGetClipPreferences action

  • Valid Values - This must be one of…

    • 0 if the images can only be sampled at discreet times (eg: the clip is a sequence of frames),

    • 1 if the images can only be sampled continuously (eg: the clip is infact an animating roto spline and can be rendered anywhen).

If this is set to true, then the frame rate of a clip is effectively infinite, so to stop arithmetic errors the frame rate should then be set to 0.

kOfxImageClipPropFieldExtraction

Controls how a plugin fetched fielded imagery from a clip.

  • Type - string X 1

  • Property Set - a clip descriptor (read/write)

  • Default - kOfxImageFieldDoubled

  • Valid Values - This must be one of

    • kOfxImageFieldBoth - fetch a full frame interlaced image

    • kOfxImageFieldSingle - fetch a single field, making a half height image

    • kOfxImageFieldDoubled - fetch a single field, but doubling each line and so making a full height image

This controls how a plug-in wishes to fetch images from a fielded clip, so it can tune it behaviour when it renders fielded footage.

Note that if it fetches kOfxImageFieldSingle and the host stores images natively as both fields interlaced, it can return a single image by doubling rowbytes and tweaking the starting address of the image data. This saves on a buffer copy.

kOfxImageClipPropFieldOrder

Which spatial field occurs temporally first in a frame.

  • Type - string X 1

  • Property Set - a clip instance (read only)

  • Valid Values - This must be one of

kOfxImageClipPropIsMask

Indicates that a clip is intended to be used as a mask input.

  • Type - int X 1

  • Property Set - clip descriptor (read/write)

  • Default - 0

  • Valid Values - This must be one of 0 or 1

Set this property on any clip which will only ever have single channel alpha images fetched from it. Typically on an optional clip such as a junk matte in a keyer.

This property acts as a hint to hosts indicating that they could feed the effect from a rotoshape (or similar) rather than an ‘ordinary’ clip.

kOfxImageClipPropOptional

Indicates if a clip is optional.

  • Type - int X 1

  • Property Set - clip descriptor (read/write)

  • Default - 0

  • Valid Values - This must be one of 0 or 1

kOfxImageClipPropPreferredColourspaces

The preferred colourspace for this clip.

  • Type - string X N

  • Property Set - clip instance (read only) and kOfxImageEffectActionGetClipPreferences action out args property (read/write)

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

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.

kOfxImageClipPropUnmappedComponents

Indicates the current ‘raw’ component type on a clip before any mapping by clip preferences.

  • Type - string X 1

  • Property Set - clip instance (read only),

  • Valid Values - This must be one of

    • kOfxImageComponentNone (implying a clip is unconnected)

    • kOfxImageComponentRGBA

    • kOfxImageComponentRGB

    • kOfxImageComponentAlpha

kOfxImageClipPropUnmappedPixelDepth

Indicates the type of each component in a clip before any mapping by clip preferences.

  • Type - string X 1

  • Property Set - clip instance (read only)

  • Valid Values - This must be one of

    • kOfxBitDepthNone (implying a clip is unconnected image)

    • kOfxBitDepthByte

    • kOfxBitDepthShort

    • kOfxBitDepthHalf

    • kOfxBitDepthFloat

This is the actual value of the component depth, before any mapping by clip preferences.

kOfxImageEffectFrameVarying

Indicates whether an effect will generate different images from frame to frame.

This property indicates whether a plugin will generate a different image from frame to frame, even if no parameters or input image changes. For example a generater that creates random noise pixel at each frame.

kOfxImageEffectHostPropIsBackground

Indicates if a host is a background render.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - This must be one of

    • 0 if the host is a foreground host, it may open the effect in an interactive session (or not)

    • 1 if the host is a background ‘processing only’ host, and the effect will never be opened in an interactive session.

kOfxImageEffectInstancePropEffectDuration

The duration of the effect.

  • Type - double X 1

  • Property Set - a plugin instance (read only)

This contains the duration of the plug-in effect, in frames.

kOfxImageEffectInstancePropSequentialRender

Indicates whether a plugin needs sequential rendering, and a host support it.

  • Type - int X 1

  • Property Set - plugin descriptor (read/write) or plugin instance (read/write), and host descriptor (read only)

  • Default - 0

  • Valid Values -

    • 0 - for a plugin, indicates that a plugin does not need to be sequentially rendered to be correct, for a host, indicates that it cannot ever guarantee sequential rendering,

    • 1 - for a plugin, indicates that it needs to be sequentially rendered to be correct, for a host, indicates that it can always support sequential rendering of plugins that are sequentially rendered,

    • 2 - for a plugin, indicates that it is best to render sequentially, but will still produce correct results if not, for a host, indicates that it can sometimes render sequentially, and will have set kOfxImageEffectPropSequentialRenderStatus on the relevant actions

Some effects have temporal dependancies, some information from from the rendering of frame N-1 is needed to render frame N correctly. This property is set by an effect to indicate such a situation. Also, some effects are more efficient if they run sequentially, but can still render correct images even if they do not, eg: a complex particle system.

During an interactive session a host may attempt to render a frame out of sequence (for example when the user scrubs the current time), and the effect needs to deal with such a situation as best it can to provide feedback to the user.

However if a host caches output, any frame frame generated in random temporal order needs to be considered invalid and needs to be re-rendered when the host finally performs a first to last render of the output sequence.

In all cases, a host will set the kOfxImageEffectPropSequentialRenderStatus flag to indicate its sequential render status.

kOfxImageEffectPluginPropFieldRenderTwiceAlways

Controls how a plugin renders fielded footage.

  • Type - integer X 1

  • Property Set - a plugin descriptor (read/write)

  • Default - 1

  • Valid Values - This must be one of

    • 0 - the plugin is to have its render function called twice, only if there is animation in any of its parameters

    • 1 - the plugin is to have its render function called twice always

kOfxImageEffectPluginPropGrouping

Indicates the effect group for this plugin.

  • Type - UTF8 string X 1

  • Property Set - plugin descriptor (read/write)

  • Default - “”

This is purely a user interface hint for the host so it can group related effects on any menus it may have.

kOfxImageEffectPluginPropHostFrameThreading

Indicates whether a plugin lets the host perform per frame SMP threading.

  • Type - int X 1

  • Property Set - plugin descriptor (read/write)

  • Default - 1

  • Valid Values - This must be one of

    • 0 - which means that the plugin will perform any per frame SMP threading

    • 1 - which means the host can call an instance’s render function simultaneously at the same frame, but with different windows to render.

kOfxImageEffectPluginPropOverlayInteractV1

Sets the entry for an effect’s overlay interaction.

  • Type - pointer X 1

  • Property Set - plugin descriptor (read/write)

  • Default - NULL

  • Valid Values - must point to an OfxPluginEntryPoint

The entry point pointed to must be one that handles custom interaction actions.

kOfxImageEffectPluginPropOverlayInteractV2

Sets the entry for an effect’s overlay interaction. Unlike kOfxImageEffectPluginPropOverlayInteractV1, the overlay interact in the plug-in is expected to implement the kOfxInteractActionDraw using the OfxDrawSuiteV1.

  • Type - pointer X 1

  • Property Set - plugin descriptor (read/write)

  • Default - NULL

  • Valid Values - must point to an OfxPluginEntryPoint

The entry point pointed to must be one that handles custom interaction actions.

kOfxImageEffectPluginPropSingleInstance

Indicates whether only one instance of a plugin can exist at the same time.

  • Type - int X 1

  • Property Set - plugin descriptor (read/write)

  • Default - 0

  • Valid Values - This must be one of

    • 0 - which means multiple instances can exist simultaneously,

    • 1 - which means only one instance can exist at any one time.

Some plugins, for whatever reason, may only be able to have a single instance in existance at any one time. This plugin property is used to indicate that.

kOfxImageEffectPluginRenderThreadSafety

Indicates how many simultaneous renders the plugin can deal with.

kOfxImageEffectPropClipPreferencesSlaveParam

Indicates the set of parameters on which a value change will trigger a change to clip preferences.

  • Type - string X N

  • Property Set - plugin descriptor (read/write)

  • Default - none set

  • Valid Values - the name of any described parameter

The plugin uses this to inform the host of the subset of parameters that affect the effect’s clip preferences. A value change in any one of these will trigger a call to the clip preferences action.

The plugin can be slaved to multiple parameters (setting index 0, then index 1 etc…)

kOfxImageEffectPropColourManagementAvailableConfigs

What native mode configs are supported?

  • Type - string X N

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

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

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.

kOfxImageEffectPropColourManagementConfig

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

  • Type - string X 1

  • Property Set - image effect instance (read only)

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

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.

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.

kOfxImageEffectPropComponents

Indicates the current component type in a clip or image (after any mapping)

  • Type - string X 1

  • Property Set - clip instance (read only), image instance (read only)

  • Valid Values - This must be one of

    • kOfxImageComponentNone (implying a clip is unconnected, not valid for an image)

    • kOfxImageComponentRGBA

    • kOfxImageComponentRGB

    • kOfxImageComponentAlpha

Note that for a clip, this is the value set by the clip preferences action, not the raw ‘actual’ value of the clip.

kOfxImageEffectPropContext

Indicates the context a plugin instance has been created for.

kOfxImageEffectPropCudaEnabled

Indicates that a plug-in SHOULD use CUDA render in the current action.

If a plug-in and host have both set kOfxImageEffectPropCudaRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as CUDA memory pointers.

kOfxImageEffectPropCudaRenderSupported

Indicates whether a host or plug-in can support CUDA render.

  • Type - string X 1

  • Property Set - plug-in descriptor (read/write), host descriptor (read only)

  • Default - “false” for a plug-in

  • Valid Values - This must be one of

    • ”false” - the host or plug-in does not support CUDA render

    • ”true” - the host or plug-in can support CUDA render

kOfxImageEffectPropCudaStream

The CUDA stream to be used for rendering.

This property will only be set if the host and plug-in both support CUDA streams.

If set:

  • this property contains a pointer to the stream of CUDA render (cudaStream_t). In order to use it, reinterpret_cast<cudaStream_t>(pointer) is needed.

  • the plug-in SHOULD ensure that its render action enqueues any asynchronous CUDA operations onto the supplied queue.

  • the plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action, and SHOULD NOT call cudaDeviceSynchronize() at any time.

If not set:

  • the plug-in SHOULD ensure that any asynchronous operations it enqueues have completed before returning from the render action.

kOfxImageEffectPropCudaStreamSupported

Indicates whether a host or plug-in can support CUDA streams.

  • Type - string X 1

  • Property Set - plug-in descriptor (read/write), host descriptor (read only)

  • Default - “false” for a plug-in

  • Valid Values - This must be one of

    • ”false” - in which case the host or plug-in does not support CUDA streams

    • ”true” - which means a host or plug-in can support CUDA streams

kOfxImageEffectPropDisplayColourspace

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

  • Type - string X 1

  • Property Set - image effect instance (read only)

  • Valid Values - any colourspace from the config header

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.

kOfxImageEffectPropFieldToRender

Indicates which field is being rendered.

  • Type - string X 1

  • Property Set - a read only in argument property to kOfxImageEffectActionRender and kOfxImageEffectActionIsIdentity

  • Valid Values - this must be one of

    • kOfxImageFieldNone - there are no fields to deal with, all images are full frame

    • kOfxImageFieldBoth - the imagery is fielded and both scan lines should be renderred

    • kOfxImageFieldLower - the lower field is being rendered (lines 0,2,4…)

    • kOfxImageFieldUpper - the upper field is being rendered (lines 1,3,5…)

kOfxImageEffectPropFrameRange

The frame range over which a clip has images.

  • Type - double X 2

  • Property Set - clip instance (read only)

Dimension 0 is the first frame for which the clip can produce valid data.

Dimension 1 is the last frame for which the clip can produce valid data.

kOfxImageEffectPropFrameRate

The frame rate of a clip or instance’s project.

For an input clip this is the frame rate of the clip.

For an output clip, the frame rate mapped via pixel preferences.

For an instance, this is the frame rate of the project the effect is in.

For the outargs property in the kOfxImageEffectActionGetClipPreferences action, it is used to change the frame rate of the ouput clip.

kOfxImageEffectPropFrameStep

The frame step used for a sequence of renders.

  • Type - double X 1

  • Property Set - an in argument for the kOfxImageEffectActionBeginSequenceRender action (read only)

  • Valid Values - can be any positive value, but typically

    • 1 for frame based material

    • 0.5 for field based material

kOfxImageEffectPropInAnalysis

Indicates whether an effect is performing an analysis pass. &#8212;ofxImageEffects.h.

  • Type - int X 1

  • Property Set - plugin instance (read/write)

  • Default - to 0

  • Valid Values - This must be one of 0 or 1

Deprecated:

  • This feature has been deprecated - officially commented out v1.4.

kOfxImageEffectPropInteractiveRenderStatus

Property that indicates if a plugin is being rendered in response to user interaction.

This property is set to 1 on all render calls that have been triggered because a user is actively modifying an effect (or up stream effect) in an interactive session. This typically means that the effect is not being rendered as a part of a sequence, but as a single frame.

kOfxImageEffectPropMetalCommandQueue

The command queue of Metal render.

This property contains a pointer to the command queue to be used for Metal rendering (id<MTLCommandQueue>). In order to use it, reinterpret_cast<id<MTLCommandQueue>>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous Metal operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

kOfxImageEffectPropMetalEnabled

Indicates that a plug-in SHOULD use Metal render in the current action.

If a plug-in and host have both set kOfxImageEffectPropMetalRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as Metal buffers.

kOfxImageEffectPropMetalRenderSupported

Indicates whether a host or plug-in can support Metal render.

  • Type - string X 1

  • Property Set - plug-in descriptor (read/write), host descriptor (read only)

  • Default - “false” for a plug-in

  • Valid Values - This must be one of

    • ”false” - the host or plug-in does not support Metal render

    • ”true” - the host or plug-in can support Metal render

kOfxImageEffectPropOCIOConfig

The path to the OCIO config used for this instance.

  • Type - string X 1

  • Property Set - image effect instance (read only)

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

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.

kOfxImageEffectPropOCIODisplay

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

  • Type - string X 1

  • Property Set - image effect instance (read only)

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

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.

kOfxImageEffectPropOCIOView

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

  • Type - string X 1

  • Property Set - image effect instance (read only)

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

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.

kOfxImageEffectPropOpenCLCommandQueue

Indicates the OpenCL command queue that should be used for rendering.

This property contains a pointer to the command queue to be used for OpenCL rendering (cl_command_queue). In order to use it, reinterpret_cast<cl_command_queue>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous OpenCL operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

kOfxImageEffectPropOpenCLEnabled

Indicates that a plug-in SHOULD use OpenCL render in the current action.

If a plug-in and host have both set kOfxImageEffectPropOpenCLRenderSupported=”true” or have both set kOfxImageEffectPropOpenCLSupported=”true” then the host MAY set this property to indicate that it is passing images as OpenCL Buffers or Images.

When rendering using OpenCL Buffers, the cl_mem of the buffers are retrieved using kOfxImagePropData. When rendering using OpenCL Images, the cl_mem of the images are retrieved using kOfxImageEffectPropOpenCLImage. If both kOfxImageEffectPropOpenCLSupported (Buffers) and kOfxImageEffectPropOpenCLRenderSupported (Images) are enabled by the plug-in, it should use kOfxImageEffectPropOpenCLImage to determine which is being used by the host.

kOfxImageEffectPropOpenCLRenderSupported

Indicates whether a host or plug-in can support OpenCL Buffers render.

  • Type - string X 1

  • Property Set - plug-in descriptor (read/write), host descriptor (read only)

  • Default - “false” for a plug-in

  • Valid Values - This must be one of

    • ”false” - the host or plug-in does not support OpenCL Buffers render

    • ”true” - the host or plug-in can support OpenCL Buffers render

kOfxImageEffectPropOpenGLEnabled

Indicates that a plug-in SHOULD use OpenGL acceleration in the current action.

When a plug-in and host have established they can both use OpenGL renders then when this property has been set the host expects the plug-in to render its result into the buffer it has setup before calling the render. The plug-in can then also safely use the ‘OfxImageEffectOpenGLRenderSuite’

v1.4: kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture

Note

Once this property is set, the host and plug-in have agreed to use OpenGL, so the effect SHOULD access all its images through the OpenGL suite.

kOfxImageEffectPropOpenGLRenderSupported

Indicates whether a host or plug-in can support OpenGL accelerated rendering.

  • Type - C string X 1

  • Property Set - plug-in descriptor (read/write), host descriptor (read only) - plug-in instance change (read/write)

  • Default - “false” for a plug-in

  • Valid Values - This must be one of

    • ”false” - in which case the host or plug-in does not support OpenGL accelerated rendering

    • ”true” - which means a host or plug-in can support OpenGL accelerated rendering, in the case of plug-ins this also means that it is capable of CPU based rendering in the absence of a GPU

    • ”needed” - only for plug-ins, this means that an plug-in has to have OpenGL support, without which it cannot work.

V1.4: It is now expected from host reporting v1.4 that the plug-in can during instance change switch from true to false and false to true.

kOfxImageEffectPropOpenGLTextureIndex

Indicates the texture index of an image turned into an OpenGL texture by the host.

kOfxImageEffectPropOpenGLTextureTarget

Indicates the texture target enumerator of an image turned into an OpenGL texture by the host.

The property set of the following actions should contain this property:

kOfxImageEffectPropPixelDepth

Indicates the type of each component in a clip or image (after any mapping)

  • Type - string X 1

  • Property Set - clip instance (read only), image instance (read only)

  • Valid Values - This must be one of

    • kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)

    • kOfxBitDepthByte

    • kOfxBitDepthShort

    • kOfxBitDepthHalf

    • kOfxBitDepthFloat

Note that for a clip, this is the value set by the clip preferences action, not the raw ‘actual’ value of the clip.

kOfxImageEffectPropPluginHandle

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.

kOfxImageEffectPropPreMultiplication

Indicates the premultiplication state of a clip or image.

  • Type - string X 1

  • Property Set - clip instance (read only), image instance (read only), out args property in the kOfxImageEffectActionGetClipPreferences action (read/write)

  • Valid Values - This must be one of

    • kOfxImageOpaque - the image is opaque and so has no premultiplication state

    • kOfxImagePreMultiplied - the image is premultiplied by its alpha

    • kOfxImageUnPreMultiplied - the image is unpremultiplied

See the documentation on clip preferences for more details on how this is used with the kOfxImageEffectActionGetClipPreferences action.

kOfxImageEffectPropProjectExtent

The extent of the current project in canonical coordinates.

  • Type - double X 2

  • Property Set - a plugin instance (read only)

The extent is the size of the ‘output’ for the current project. See NormalisedCoordinateSystem for more infomation on the project extent.

The extent is in canonical coordinates and only returns the top right position, as the extent is always rooted at 0,0.

For example a PAL SD project would have an extent of 768, 576.

kOfxImageEffectPropProjectOffset

The offset of the current project in canonical coordinates.

  • Type - double X 2

  • Property Set - a plugin instance (read only)

The offset is related to the kOfxImageEffectPropProjectSize and is the offset from the origin of the project ‘subwindow’.

For example for a PAL SD project that is in letterbox form, the project offset is the offset to the bottom left hand corner of the letter box.

The project offset is in canonical coordinates.

See NormalisedCoordinateSystem for more infomation on the project extent.

kOfxImageEffectPropProjectPixelAspectRatio

The pixel aspect ratio of the current project.

  • Type - double X 1

  • Property Set - a plugin instance (read only)

kOfxImageEffectPropProjectSize

The size of the current project in canonical coordinates.

  • Type - double X 2

  • Property Set - a plugin instance (read only)

The size of a project is a sub set of the kOfxImageEffectPropProjectExtent. For example a project may be a PAL SD project, but only be a letter-box within that. The project size is the size of this sub window.

The project size is in canonical coordinates.

See NormalisedCoordinateSystem for more infomation on the project extent.

kOfxImageEffectPropRegionOfDefinition

Used to indicate the region of definition of a plug-in.

The order of the values is x1, y1, x2, y2.

This will be in CanonicalCoordinates

kOfxImageEffectPropRegionOfInterest

The value of a region of interest.

A host passes this value into the region of interest action to specify the region it is interested in rendering.

The order of the values is x1, y1, x2, y2.

This will be in CanonicalCoordinates.

kOfxImageEffectPropRenderQualityDraft

Indicates whether an effect can take quality shortcuts to improve speed.

  • Type - int X 1

  • Property Set - render calls, host (read-only)

  • Default - 0 - 0: Best Quality (1: Draft)

  • Valid Values - This must be one of 0 or 1

This property indicates that the host provides the plug-in the option to render in Draft/Preview mode. This is useful for applications that must support fast scrubbing. These allow a plug-in to take short-cuts for improved performance when the situation allows and it makes sense, for example to generate thumbnails with effects applied. For example switch to a cheaper interpolation type or rendering mode. A plugin should expect frames rendered in this manner that will not be stucked in host cache unless the cache is only used in the same draft situations. If an host does not support that property a value of 0 is assumed. Also note that some hosts do implement kOfxImageEffectPropRenderScale - these two properties can be used independently.

kOfxImageEffectPropRenderScale

The proxy render scale currently being applied.

This should be applied to any spatial parameters to position them correctly. Not that the ‘x’ value does not include any pixel aspect ratios.

kOfxImageEffectPropRenderWindow

The region to be rendered.

The order of the values is x1, y1, x2, y2.

This will be in PixelCoordinates

kOfxImageEffectPropSequentialRenderStatus

Property on all the render action that indicate the current sequential render status of a host.

This property is set to indicate whether the effect is currently being rendered in frame order on a single effect instance. See kOfxImageEffectInstancePropSequentialRender for more details on sequential rendering.

kOfxImageEffectPropSetableFielding

Indicates whether the host will let a plugin set the fielding of the output clip.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - This must be one of

    • 0 - in which case the plugin may not change the fielding of the output clip,

    • 1 - which means a plugin is able to change the output clip’s fielding in the kOfxImageEffectActionGetClipPreferences action.

See ImageEffectClipPreferences.

kOfxImageEffectPropSetableFrameRate

Indicates whether the host will let a plugin set the frame rate of the output clip.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - This must be one of

    • 0 - in which case the plugin may not change the frame rate of the output clip,

    • 1 - which means a plugin is able to change the output clip’s frame rate in the kOfxImageEffectActionGetClipPreferences action.

See ImageEffectClipPreferences.

If a clip can be continously sampled, the frame rate will be set to 0.

kOfxImageEffectPropSupportedComponents

Indicates the components supported by a clip or host,.

  • Type - string X N

  • Property Set - host descriptor (read only), clip descriptor (read/write)

  • Valid Values - This must be one of

    • kOfxImageComponentNone (implying a clip is unconnected)

    • kOfxImageComponentRGBA

    • kOfxImageComponentRGB

    • kOfxImageComponentAlpha

This list of strings indicate what component types are supported by a host or are expected as input to a clip.

The default for a clip descriptor is to have none set, the plugin must define at least one in its define function

kOfxImageEffectPropSupportedContexts

Indicates to the host the contexts a plugin can be used in.

kOfxImageEffectPropSupportedPixelDepths

Indicates the bit depths support by a plug-in or host.

  • Type - string X N

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - plugin descriptor none set

  • Valid Values - This must be one of

    • kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)

    • kOfxBitDepthByte

    • kOfxBitDepthShort

    • kOfxBitDepthHalf

    • kOfxBitDepthFloat

The default for a plugin is to have none set, the plugin must define at least one in its describe action.

kOfxImageEffectPropSupportsMultiResolution

Indicates whether a plugin or host support multiple resolution images.

  • Type - int X 1

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - 1 for plugins

  • Valid Values - This must be one of

    • 0 - the plugin or host does not support multiple resolutions

    • 1 - the plugin or host does support multiple resolutions

Multiple resolution images mean…

  • input and output images can be of any size

  • input and output images can be offset from the origin

kOfxImageEffectPropSupportsMultipleClipDepths

Indicates whether a host or plugin can support clips of differing component depths going into/out of an effect.

  • Type - int X 1

  • Property Set - plugin descriptor (read/write), host descriptor (read only)

  • Default - 0 for a plugin

  • Valid Values - This must be one of

    • 0 - in which case the host or plugin does not support clips of multiple pixel depths,

    • 1 - which means a host or plugin is able to to deal with clips of multiple pixel depths,

If a host indicates that it can support multiple pixels depths, then it will allow the plugin to explicitly set the output clip’s pixel depth in the kOfxImageEffectActionGetClipPreferences action. See ImageEffectClipPreferences.

kOfxImageEffectPropSupportsMultipleClipPARs

Indicates whether a host or plugin can support clips of differing pixel aspect ratios going into/out of an effect.

  • Type - int X 1

  • Property Set - plugin descriptor (read/write), host descriptor (read only)

  • Default - 0 for a plugin

  • Valid Values - This must be one of

    • 0 - in which case the host or plugin does not support clips of multiple pixel aspect ratios

    • 1 - which means a host or plugin is able to to deal with clips of multiple pixel aspect ratios

If a host indicates that it can support multiple pixel aspect ratios, then it will allow the plugin to explicitly set the output clip’s aspect ratio in the kOfxImageEffectActionGetClipPreferences action. See ImageEffectClipPreferences.

kOfxImageEffectPropSupportsOverlays

Indicates whether a host support image effect ImageEffectOverlays.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - This must be one of

    • 0 - the host won’t allow a plugin to draw a GUI over the output image,

    • 1 - the host will allow a plugin to draw a GUI over the output image.

kOfxImageEffectPropSupportsTiles

Indicates whether a clip, plugin or host supports tiled images.

  • Type - int X 1

  • Property Set - host descriptor (read only), plugin descriptor (read/write), clip descriptor (read/write), instance (read/write)

  • Default - to 1 for a plugin and clip

  • Valid Values - This must be one of 0 or 1

Tiled images mean that input or output images can contain pixel data that is only a subset of their full RoD.

If a clip or plugin does not support tiled images, then the host should supply full RoD images to the effect whenever it fetches one.

V1.4: It is now possible (defined) to change OfxImageEffectPropSupportsTiles in Instance Changed

kOfxImageEffectPropTemporalClipAccess

Indicates support for random temporal access to images in a clip.

  • Type - int X 1

  • Property Set - host descriptor (read only), plugin descriptor (read/write), clip descriptor (read/write)

  • Default - to 0 for a plugin and clip

  • Valid Values - This must be one of 0 or 1

On a host, it indicates whether the host supports temporal access to images.

On a plugin, indicates if the plugin needs temporal access to images.

On a clip, it indicates that the clip needs temporal access to images.

kOfxImageEffectPropUnmappedFrameRange

The unmaped frame range over which an output clip has images.

  • Type - double X 2

  • Property Set - clip instance (read only)

Dimension 0 is the first frame for which the clip can produce valid data.

Dimension 1 is the last frame for which the clip can produce valid data.

If a plugin changes the output frame rate in the pixel preferences action, it will affect the frame range of the output clip, this property allows a plugin to get to the original value.

kOfxImageEffectPropUnmappedFrameRate

Indicates the original unmapped frame rate (frames/second) of a clip.

  • Type - double X 1

  • Property Set - clip instance (read only),

If a plugin changes the output frame rate in the pixel preferences action, this property allows a plugin to get to the original value.

kOfxImagePropBounds

The bounds of an image’s pixels.

  • Type - integer X 4

  • Property Set - an image instance (read only)

The bounds, in PixelCoordinates, are of the addressable pixels in an image’s data pointer.

The order of the values is x1, y1, x2, y2.

X values are x1 <= X < x2 Y values are y1 <= Y < y2

For less than full frame images, the pixel bounds will be contained by the kOfxImagePropRegionOfDefinition bounds.

kOfxImagePropData

The pixel data pointer of an image.

  • Type - pointer X 1

  • Property Set - an image instance (read only)

This property contains one of:

  • a pointer to memory that is the lower left hand corner of an image

  • a pointer to CUDA memory, if the Render action arguments includes kOfxImageEffectPropCudaEnabled=1

  • an id<MTLBuffer>, if the Render action arguments includes kOfxImageEffectPropMetalEnabled=1

  • a cl_mem, if the Render action arguments includes kOfxImageEffectPropOpenCLEnabled=1

See kOfxImageEffectPropCudaEnabled, kOfxImageEffectPropMetalEnabled and kOfxImageEffectPropOpenCLEnabled

kOfxImagePropField

Which fields are present in the image.

  • Type - string X 1

  • Property Set - an image instance (read only)

  • Valid Values - This must be one of

kOfxImagePropPixelAspectRatio

The pixel aspect ratio of a clip or image.

kOfxImagePropRegionOfDefinition

The full region of definition of an image.

  • Type - integer X 4

  • Property Set - an image instance (read only)

An image’s region of definition, in PixelCoordinates, is the full frame area of the image plane that the image covers.

The order of the values is x1, y1, x2, y2.

X values are x1 <= X < x2 Y values are y1 <= Y < y2

The kOfxImagePropBounds property contains the actuall addressable pixels in an image, which may be less than its full region of definition.

kOfxImagePropRowBytes

The number of bytes in a row of an image.

  • Type - integer X 1

  • Property Set - an image instance (read only)

For various alignment reasons, a row of pixels may need to be padded at the end with several bytes before the next row starts in memory.

This property indicates the number of bytes in a row of pixels. This will be at least sizeof(PIXEL) * (bounds.x2-bounds.x1). Where bounds is fetched from the kOfxImagePropBounds property.

Note that (for CPU images only, not CUDA/Metal/OpenCL Buffers, nor OpenGL textures accessed via the OpenGL Render Suite) row bytes can be negative, which allows hosts with a native top down row order to pass image into OFX without having to repack pixels. Row bytes is not supported for OpenCL Images.

kOfxImagePropUniqueIdentifier

Uniquely labels an image.

  • Type - ASCII string X 1

  • Property Set - image instance (read only)

This is host set and allows a plug-in to differentiate between images. This is especially useful if a plugin caches analysed information about the image (for example motion vectors). The plugin can label the cached information with this identifier. If a user connects a different clip to the analysed input, or the image has changed in some way then the plugin can detect this via an identifier change and re-evaluate the cached information.

kOfxInteractPropBackgroundColour

The background colour of the application behind an interact instance.

  • Type - double X 3

  • Property Set - read only on the interact instance and in argument to the kOfxInteractActionDraw action

  • Valid Values - from 0 to 1

The components are in the order red, green then blue.

kOfxInteractPropBitDepth

Indicates whether the dits per component in the interact’s openGL frame buffer.

  • Type - int X 1

  • Property Set - interact instance and descriptor (read only)

kOfxInteractPropDrawContext

The Draw Context handle.

  • Type - pointer X 1

  • Property Set - read only property on the inArgs of the following actions…

  • kOfxInteractActionDraw

kOfxInteractPropHasAlpha

Indicates whether the interact’s frame buffer has an alpha component or not.

  • Type - int X 1

  • Property Set - interact instance and descriptor (read only)

  • Valid Values - This must be one of

    • 0 indicates no alpha component

    • 1 indicates an alpha component

kOfxInteractPropPenPosition

The position of the pen in an interact.

This value passes the postion of the pen into an interact. This is in the interact’s canonical coordinates.

kOfxInteractPropPenPressure

The pressure of the pen in an interact.

This is used to indicate the status of the ‘pen’ in an interact. If a pen has only two states (eg: a mouse button), these should map to 0.0 and 1.0.

kOfxInteractPropPenViewportPosition

The position of the pen in an interact in viewport coordinates.

This value passes the postion of the pen into an interact. This is in the interact’s openGL viewport coordinates, with 0,0 being at the bottom left.

kOfxInteractPropPixelScale

The size of a real screen pixel under the interact’s canonical projection.

  • Type - double X 2

  • Property Set - interact instance and actions (read only)

kOfxInteractPropSlaveToParam

The set of parameters on which a value change will trigger a redraw for an interact.

  • Type - string X N

  • Property Set - interact instance property (read/write)

  • Default - no values set

  • Valid Values - the name of any parameter associated with this interact.

If the interact is representing the state of some set of OFX parameters, then is will need to be redrawn if any of those parameters’ values change. This multi-dimensional property links such parameters to the interact.

The interact can be slaved to multiple parameters (setting index 0, then index 1 etc…)

kOfxInteractPropSuggestedColour

The suggested colour to draw a widget in an interact, typically for overlays.

  • Type - double X 3

  • Property Set - read only on the interact instance

  • Default - 1.0

  • Valid Values - greater than or equal to 0.0

Some applications allow the user to specify colours of any overlay via a colour picker, this property represents the value of that colour. Plugins are at liberty to use this or not when they draw an overlay.

If a host does not support such a colour, it should return kOfxStatReplyDefault

kOfxInteractPropViewportSize

The size of an interact’s openGL viewport &#8212; ofxInteract.h.

  • Type - int X 2

  • Property Set - read only property on the interact instance and in argument to all the interact actions.

Deprecated:

  • V1.3: This property is the redundant and its use will be deprecated in future releases. V1.4: Removed

kOfxOpenGLPropPixelDepth

Indicates the bit depths supported by a plug-in during OpenGL renders.

This is analogous to kOfxImageEffectPropSupportedPixelDepths. When a plug-in sets this property, the host will try to provide buffers/textures in one of the supported formats. Additionally, the target buffers where the plug-in renders to will be set to one of the supported formats.

Unlike kOfxImageEffectPropSupportedPixelDepths, this property is optional. Shader-based effects might not really care about any format specifics when using OpenGL textures, so they can leave this unset and allow the host the decide the format.

kOfxParamHostPropMaxPages

Indicates the maximum number of parameter pages.

  • Type - int X 1

  • Property Set - host descriptor (read only)

If there is no limit to the number of pages on a host, set this to -1.

Hosts that do not support paged parameter layout should set this to zero.

kOfxParamHostPropMaxParameters

Indicates the maximum numbers of parameters available on the host.

  • Type - int X 1

  • Property Set - host descriptor (read only)

If set to -1 it implies unlimited number of parameters.

kOfxParamHostPropPageRowColumnCount

This indicates the number of parameter rows and coloumns on a page.

  • Type - int X 2

  • Property Set - host descriptor (read only)

If the host has supports paged parameter layout, used dimension 0 as the number of columns per page and dimension 1 as the number of rows per page.

kOfxParamHostPropSupportsBooleanAnimation

Indicates if the host supports animation of boolean params.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

kOfxParamHostPropSupportsChoiceAnimation

Indicates if the host supports animation of choice params.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

kOfxParamHostPropSupportsCustomAnimation

Indicates if the host supports animation of custom parameters.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Value Values - 0 or 1

kOfxParamHostPropSupportsCustomInteract

Indicates if the host supports custom interacts for parameters.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.

kOfxParamHostPropSupportsParametricAnimation

Property on the host to indicate support for parametric parameter animation.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values

    • 0 indicating the host does not support animation of parmetric params,

    • 1 indicating the host does support animation of parmetric params,

kOfxParamHostPropSupportsStrChoice

Indicates if the host supports the StrChoice param type.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

Since

Version 1.5

kOfxParamHostPropSupportsStrChoiceAnimation

Indicates if the host supports animation of string choice params.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

Since

Version 1.5

kOfxParamHostPropSupportsStringAnimation

Indicates if the host supports animation of string params.

  • Type - int X 1

  • Property Set - host descriptor (read only)

  • Valid Values - 0 or 1

kOfxParamPropAnimates

Flags whether a parameter can animate.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 1

  • Valid Values - 0 or 1

A plug-in uses this property to indicate if a parameter is able to animate.

kOfxParamPropCacheInvalidation

Specifies how modifying the value of a param will affect any output of an effect over time.

Imagine an effect with an animating parameter in a host that caches rendered output. Think of the what happens when you add a new key frame. -If the parameter represents something like an absolute position, the cache will only need to be invalidated for the range of frames that keyframe affects.

  • If the parameter represents something like a speed which is integrated, the cache will be invalidated from the keyframe until the end of the clip.

  • There are potentially other situations where the entire cache will need to be invalidated (though I can’t think of one off the top of my head).

kOfxParamPropCanUndo

Flags whether changes to a parameter should be put on the undo/redo stack.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 1

  • Valid Values - 0 or 1

kOfxParamPropChoiceEnum

Set a enumeration string in a StrChoice (string-valued choice) parameter.

  • Type - UTF8 C string X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the property is empty with no options set.

This property contains the set of enumeration strings stored by the host in the project corresponding to the options that will be presented to a user from a StrChoice parameter. See ParametersChoice for more details.

Since

Version 1.5

kOfxParamPropChoiceOption

Set options of a choice parameter.

  • Type - UTF8 C string X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the property is empty with no options set.

This property contains the set of options that will be presented to a user from a choice parameter. See ParametersChoice for more details.

kOfxParamPropChoiceOrder

Set values the host should store for a choice parameter.

  • Type - int X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - Zero-based ordinal list of same length as OfxParamPropChoiceOption

This property specifies the order in which the options are presented. See “Choice Parameters” for more details. This property is optional; if not set, the host will present the options in their natural order.

This property is useful when changing order of choice param options, or adding new options in the middle, in a new version of the plugin.

  Plugin v1:
  Option = {"OptA", "OptB", "OptC"}
  Order = {1, 2, 3}

  Plugin v2:
  // will be shown as OptA / OptB / NewOpt / OptC
  Option = {"OptA", "OptB", "OptC", NewOpt"}
  Order = {1, 2, 4, 3}

Note that this only affects the host UI’s display order; the project still stores the index of the selected option as always. Plugins should never reorder existing options if they desire backward compatibility.

Values may be arbitrary 32-bit integers. Behavior is undefined if the same value occurs twice in the list; plugins should not do that.

Since

Version 1.5

kOfxParamPropCustomInterpCallbackV1

A pointer to a custom parameter’s interpolation function.

  • Type - pointer X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only),

  • Default - NULL

  • Valid Values - must point to a OfxCustomParamInterpFuncV1

It is an error not to set this property in a custom parameter during a plugin’s define call if the custom parameter declares itself to be an animating parameter.

kOfxParamPropCustomValue

Used by interpolating custom parameters to get and set interpolated values.

  • Type - C string X 1 or 2

This property is on the inArgs property and outArgs property of a OfxCustomParamInterpFuncV1 and in both cases contains the encoded value of a custom parameter. As an inArgs property it will have two values, being the two keyframes to interpolate. As an outArgs property it will have a single value and the plugin should fill this with the encoded interpolated value of the parameter.

kOfxParamPropDataPtr

A private data pointer that the plug-in can store its own data behind.

  • Type - pointer X 1

  • Property Set - plugin parameter instance (read/write),

  • Default - NULL

This data pointer is unique to each parameter instance, so two instances of the same parameter do not share the same data pointer. Use it to hang any needed private data structures.

kOfxParamPropDefault

The default value of a parameter.

  • Type - The type is dependant on the parameter type as is the dimension.

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write only),

  • Default - 0 cast to the relevant type (or “” for strings and custom parameters)

The exact type and dimension is dependant on the type of the parameter. These are….

kOfxParamPropDefaultCoordinateSystem

Describes in which coordinate system a spatial double parameter’s default value is specified.

  • Type - C string X 1

  • Default - kOfxParamCoordinatesCanonical

  • Property Set - Non normalised spatial double parameters, ie: any double param who’s kOfxParamPropDoubleType is set to one of…

    • kOfxParamDoubleTypeX

    • kOfxParamDoubleTypeXAbsolute

    • kOfxParamDoubleTypeY

    • kOfxParamDoubleTypeYAbsolute

    • kOfxParamDoubleTypeXY

    • kOfxParamDoubleTypeXYAbsolute

  • Valid Values - This must be one of

    • kOfxParamCoordinatesCanonical - the default is in canonical coords

    • kOfxParamCoordinatesNormalised - the default is in normalised coordinates

This allows a spatial param to specify what its default is, so by saying normalised and “0.5” it would be in the ‘middle’, by saying canonical and 100 it would be at value 100 independent of the size of the image being applied to.

kOfxParamPropDigits

How many digits after a decimal point to display for a double param in a GUI.

  • Type - int X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - 2

  • Valid Values - any greater than 0.

This applies to double params of any dimension.

kOfxParamPropDimensionLabel

Label for individual dimensions on a multidimensional numeric parameter.

  • Type - UTF8 C string X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only),

  • Default - “x”, “y” and “z”

  • Valid Values - any

Use this on 2D and 3D double and integer parameters to change the label on an individual dimension in any GUI for that parameter.

kOfxParamPropDisplayMax

The maximum value for a numeric parameter on any user interface.

  • Type - int or double X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter)

If a user interface represents a parameter with a slider or similar, this should be the maximum bound on that slider.

kOfxParamPropDisplayMin

The minimum value for a numeric parameter on any user interface.

  • Type - int or double X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter)

If a user interface represents a parameter with a slider or similar, this should be the minumum bound on that slider.

kOfxParamPropDoubleType

Describes how the double parameter should be interpreted by a host.

Double parameters can be interpreted in several different ways, this property tells the host how to do so and thus gives hints as to the interface of the parameter.

kOfxParamPropEnabled

Used to enable a parameter in the user interface.

  • Type - int X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - 1

  • Valid Values - 0 or 1

When set to 0 a user should not be able to modify the value of the parameter. Note that the plug-in itself can still change the value of a disabled parameter.

kOfxParamPropEvaluateOnChange

Flags whether changing a parameter’s value forces an evalution (ie: render),.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write only)

  • Default - 1

  • Valid Values - 0 or 1

This is used to indicate if the value of a parameter has any affect on an effect’s output, eg: the parameter may be purely for GUI purposes, and so changing its value should not trigger a re-render.

kOfxParamPropGroupOpen

Whether the initial state of a group is open or closed in a hierarchical layout.

  • Type - int X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 1

  • Valid Values - 0 or 1

This is a property on parameters of type kOfxParamTypeGroup, and tells the group whether it should be open or closed by default.

kOfxParamPropHasHostOverlayHandle

A flag to indicate if there is a host overlay UI handle for the given parameter.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read only)

  • Valid Values - 0 or 1

If set to 1, then the host is flagging that there is some sort of native user overlay interface handle available for the given parameter.

kOfxParamPropHint

A hint to the user as to how the parameter is to be used.

  • Type - UTF8 C string X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - “”

kOfxParamPropIncrement

The granularity of a slider used to represent a numeric parameter.

  • Type - double X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - 1

  • Valid Values - any greater than 0.

This value is always in canonical coordinates for double parameters that are normalised.

kOfxParamPropInteractMinimumSize

The minimum size of a parameter’s custom interface, in screen pixels.

  • Type - double x 2

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 10,10

  • Valid Values - greater than (0, 0)

Any custom interface will not be less than this size.

kOfxParamPropInteractPreferedSize

The preferred size of a parameter’s custom interface.

  • Type - int x 2

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 10,10

  • Valid Values - greater than (0, 0)

A host should attempt to set a parameter’s custom interface on a parameter to be this size if possible, otherwise it will be of kOfxParamPropInteractSizeAspect aspect but larger than kOfxParamPropInteractMinimumSize.

kOfxParamPropInteractSize

The size of a parameter instance’s custom interface in screen pixels.

  • Type - double x 2

  • Property Set - plugin parameter instance (read only)

This is set by a host to indicate the current size of a custom interface if the plug-in has one. If not this is set to (0,0).

kOfxParamPropInteractSizeAspect

The preferred aspect ratio of a parameter’s custom interface.

  • Type - double x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 1.0

  • Valid Values - greater than or equal to 0.0

If set to anything other than 0.0, the custom interface for this parameter will be of a size with this aspect ratio (x size/y size).

kOfxParamPropInteractV1

Overrides the parameter’s standard user interface with the given interact.

  • Type - pointer X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - NULL

  • Valid Values - must point to a OfxPluginEntryPoint

If set, the parameter’s normal interface is replaced completely by the interact gui.

Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.

kOfxParamPropInterpolationAmount

Property used by OfxCustomParamInterpFuncV1 to indicate the amount of interpolation to perform.

This property indicates how far between the two kOfxParamPropCustomValue keys to interpolate.

kOfxParamPropInterpolationTime

Used by interpolating custom parameters to indicate the time a key occurs at.

The two values indicate the absolute times the surrounding keyframes occur at. The keyframes are encoded in a kOfxParamPropCustomValue property.

kOfxParamPropIsAnimating

Flags whether a parameter is currently animating.

  • Type - int x 1

  • Property Set - plugin parameter instance (read only)

  • Valid Values - 0 or 1

Set by a host on a parameter instance to indicate if the parameter has a non-constant value set on it. This can be as a consequence of animation or of scripting modifying the value, or of a parameter being connected to an expression in the host.

kOfxParamPropIsAutoKeying

Will a value change on the parameter add automatic keyframes.

  • Type - int X 1

  • Property Set - plugin parameter instance (read only),

  • Valid Values - 0 or 1

This is set by the host simply to indicate the state of the property.

kOfxParamPropMax

The maximum value for a numeric parameter.

  • Type - int or double X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter)

Setting this will also reset :;kOfxParamPropDisplayMax.

kOfxParamPropMin

The minimum value for a numeric parameter.

  • Type - int or double X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write),

  • Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter)

Setting this will also reset kOfxParamPropDisplayMin.

kOfxParamPropPageChild

The names of the parameters included in a page parameter.

  • Type - C string X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - “”

  • Valid Values - the names of any parameter that is not a group or page, as well as kOfxParamPageSkipRow and kOfxParamPageSkipColumn

This is a property on parameters of type kOfxParamTypePage, and tells the page what parameters it contains. The parameters are added to the page from the top left, filling in columns as we go. The two pseudo param names kOfxParamPageSkipRow and kOfxParamPageSkipColumn are used to control layout.

Note parameters can appear in more than one page.

kOfxParamPropParametricDimension

The dimension of a parametric param.

  • Type - int X 1

  • Property Set - parametric param descriptor (read/write) and instance (read only)

  • default - 1

  • Value Values - greater than 0

This indicates the dimension of the parametric param.

kOfxParamPropParametricInteractBackground

Interact entry point to draw the background of a parametric parameter.

  • Type - pointer X 1

  • Property Set - plug-in parametric parameter descriptor (read/write) and instance (read only),

  • Default - NULL, which implies the host should draw its default background.

Defines a pointer to an interact which will be used to draw the background of a parametric parameter’s user interface. None of the pen or keyboard actions can ever be called on the interact.

The openGL transform will be set so that it is an orthographic transform that maps directly to the ‘parametric’ space, so that ‘x’ represents the parametric position and ‘y’ represents the evaluated value.

kOfxParamPropParametricRange

Property to indicate the min and max range of the parametric input value.

  • Type - double X 2

  • Property Set - parameter descriptor (read/write only), and instance (read only)

  • Default Value - (0, 1)

  • Valid Values - any pair of numbers so that the first is less than the second.

This controls the min and max values that the parameter will be evaluated at.

kOfxParamPropParametricUIColour

The colour of parametric param curve interface in any UI.

  • Type - double X N

  • Property Set - parametric param descriptor (read/write) and instance (read only)

  • default - unset,

  • Value Values - three values for each dimension (see kOfxParamPropParametricDimension) being interpretted as R, G and B of the colour for each curve drawn in the UI.

This sets the colour of a parametric param curve drawn a host user interface. A colour triple is needed for each dimension of the oparametric param.

If not set, the host should generally draw these in white.

kOfxParamPropParent

The name of a parameter’s parent group.

  • Type - C string X 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only),

  • Default - “”, which implies the “root” of the hierarchy,

  • Valid Values - the name of a parameter with type of kOfxParamTypeGroup

Hosts that have hierarchical layouts of their params use this to recursively group parameter.

By default parameters are added in order of declaration to the ‘root’ hierarchy. This property is used to reparent params to a predefined param of type kOfxParamTypeGroup.

kOfxParamPropPersistant

Flags whether the value of a parameter should persist.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 1

  • Valid Values - 0 or 1

This is used to tell the host whether the value of the parameter is important and should be save in any description of the plug-in.

kOfxParamPropPluginMayWrite

Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis pass.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - 0

  • Valid Values - 0 or 1

This is used to tell the host whether the plug-in is going to attempt to set the value of the parameter.

Deprecated:

  • v1.4: deprecated - to be removed in 1.5

kOfxParamPropScriptName

The value to be used as the id of the parameter in a host scripting language.

  • Type - ASCII C string X 1,

  • Property Set - plugin parameter descriptor (read/write) and instance (read only),

  • Default - the unique name the parameter was created with.

  • Valid Values - ASCII string unique to all parameters in the plug-in.

Many hosts have a scripting language that they use to set values of parameters and more. If so, this is the name of a parameter in such scripts.

kOfxParamPropSecret

Flags whether a parameter should be exposed to a user,.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write)

  • Default - 0

  • Valid Values - 0 or 1

If secret, a parameter is not exposed to a user in any interface, but should otherwise behave as a normal parameter.

Secret params are typically used to hide important state detail that would otherwise be unintelligible to a user, for example the result of a statical analysis that might need many parameters to store.

kOfxParamPropShowTimeMarker

Enables the display of a time marker on the host’s time line to indicate the value of the absolute time param.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write) and instance (read/write)

  • Default - 0

  • Valid Values - 0 or 1

If a double parameter is has kOfxParamPropDoubleType set to kOfxParamDoubleTypeAbsoluteTime, then this indicates whether any marker should be made visible on the host’s time line.

kOfxParamPropStringMode

Used to indicate the type of a string parameter.

kOfxParamPropType

The type of a parameter.

  • Type - C string X 1

  • Property Set - plugin parameter descriptor (read only) and instance (read only)

This string will be set to the type that the parameter was create with.

kOfxParamPropUseHostOverlayHandle

A flag to indicate that the host should use a native UI overlay handle for the given parameter.

  • Type - int x 1

  • Property Set - plugin parameter descriptor (read/write only) and instance (read only)

  • Default - 0

  • Valid Values - 0 or 1

If set to 1, then a plugin is flaging to the host that the host should use a native UI overlay handle for the given parameter. A plugin can use this to keep a native look and feel for parameter handles. A plugin can use kOfxParamPropHasHostOverlayHandle to see if handles are available on the given parameter.

kOfxPluginPropFilePath

The file path to the plugin.

  • Type - C string X 1

  • Property Set - effect descriptor (read only)

This is a string that indicates the file path where the plug-in was found by the host. The path is in the native path format for the host OS (eg: UNIX directory separators are forward slashes, Windows ones are backslashes).

The path is to the bundle location, see InstallationLocation. eg: ‘/usr/OFX/Plugins/AcmePlugins/AcmeFantasticPlugin.ofx.bundle’

kOfxPluginPropParamPageOrder

Sets the parameter pages and order of pages.

  • Type - C string X N

  • Property Set - plugin parameter descriptor (read/write) and instance (read only)

  • Default - “”

  • Valid Values - the names of any page param in the plugin

This property sets the preferred order of parameter pages on a host. If this is never set, the preferred order is the order the parameters were declared in.

kOfxPropAPIVersion

Property on the host descriptor, saying what API version of the API is being implemented.

  • Type - int X N

  • Property Set - host descriptor.

This is a version string that will specify which version of the API is being implemented by a host. It can have multiple values. For example “1.0”, “1.2.4” etc…..

If this is not present, it is safe to assume that the version of the API is “1.0”.

kOfxPropChangeReason

Indicates why a plug-in changed.

  • Type - ASCII C string X 1

  • Property Set - inArgs parameter on the kOfxActionInstanceChanged action.

  • Valid Values - this can be…

    • kOfxChangeUserEdited - the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resets

    • kOfxChangePluginEdited - the plug-in itself has changed the value of the object in some action

    • kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time

Argument property for the kOfxActionInstanceChanged action.

kOfxPropEffectInstance

A pointer to an effect instance.

  • Type - pointer X 1

  • Property Set - on an interact instance (read only)

This property is used to link an object to the effect. For example if the plug-in supplies an openGL overlay for an image effect, the interact instance will have one of these so that the plug-in can connect back to the effect the GUI links to.

kOfxPropHostOSHandle

A pointer to an operating system specific application handle.

  • Type - pointer X 1

  • Property Set - host descriptor.

Some plug-in vendor want raw OS specific handles back from the host so they can do interesting things with host OS APIs. Typically this is to control windowing properly on Microsoft Windows. This property returns the appropriate ‘root’ window handle on the current operating system. So on Windows this would be the hWnd of the application main window.

kOfxPropIcon

If set this tells the host to use an icon instead of a label for some object in the interface.

  • Type - string X 2

  • Property Set - various descriptors in the API

  • Default - “”

  • Valid Values - ASCII string

The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon.

The first dimension, if set, will the name of and SVG file, the second a PNG file.

kOfxPropInstanceData

A private data pointer that the plug-in can store its own data behind.

  • Type - pointer X 1

  • Property Set - plugin instance (read/write),

  • Default - NULL

This data pointer is unique to each plug-in instance, so two instances of the same plug-in do not share the same data pointer. Use it to hang any needed private data structures.

kOfxPropIsInteractive

Indicates if a host is actively editing the effect with some GUI.

  • Type - int X 1

  • Property Set - effect instance (read only)

  • Valid Values - 0 or 1

If false the effect currently has no interface, however this may be because the effect is loaded in a background render host, or it may be loaded on an interactive host that has not yet opened an editor for the effect.

The output of an effect should only ever depend on the state of its parameters, not on the interactive flag. The interactive flag is more a courtesy flag to let a plugin know that it has an interace. If a plugin want’s to have its behaviour dependant on the interactive flag, it can always make a secret parameter which shadows the state if the flag.

kOfxPropKeyString

This property encodes a single keypresses that generates a unicode code point. The value is stored as a UTF8 string.

This property represents the UTF8 encode value of a single key press by a user in an OFX interact.

This property is associated with a kOfxPropKeySym which represents an integer value for the key press. Some keys (for example arrow keys) have no UTF8 equivalant, in which case this is set to the empty string “”, and the associate kOfxPropKeySym is set to the equivilant raw key press.

Some keys, especially on non-english language systems, may have a UTF8 value, but not a keysym values, in these cases, the keysym will have a value of kOfxKey_Unknown, but the kOfxPropKeyString property will still be set with the UTF8 value.

kOfxPropKeySym

Property used to indicate which a key on the keyboard or a button on a button device has been pressed.

This property represents a raw key press, it does not represent the ‘character value’ of the key.

This property is associated with a kOfxPropKeyString property, which encodes the UTF8 value for the keypress/button press. Some keys (for example arrow keys) have no UTF8 equivalant.

Some keys, especially on non-english language systems, may have a UTF8 value, but not a keysym values, in these cases, the keysym will have a value of kOfxKey_Unknown, but the kOfxPropKeyString property will still be set with the UTF8 value.

kOfxPropLabel

User visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - the kOfxPropName the object was created with.

The label is what a user sees on any interface in place of the object’s name.

Note that resetting this will also reset kOfxPropShortLabel and kOfxPropLongLabel.

kOfxPropLongLabel

Long user visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - initially kOfxPropName, but will be reset if kOfxPropLabel is changed.

This is a longer version of the label, typically 32 character glyphs or so. Hosts should use this if they have mucg display space for their object labels.

kOfxPropName

Unique name of an object.

  • Type - ASCII C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject (read only)

This property is used to label objects uniquely amoung objects of that type. It is typically set when a plugin creates a new object with a function that takes a name.

kOfxPropParamSetNeedsSyncing

States whether the plugin needs to resync its private data.

  • Type - int X 1

  • Property Set - param set instance (read/write)

  • Default - 0

  • Valid Values -

    • 0 - no need to sync

    • 1 - paramset is not synced

The plugin should set this flag to true whenever any internal state has not been flushed to the set of params.

The host will examine this property each time it does a copy or save operation on the instance. If it is set to 1, the host will call SyncPrivateData and then set it to zero before doing the copy/save. If it is set to 0, the host will assume that the param data correctly represents the private state, and will not call SyncPrivateData before copying/saving. If this property is not set, the host will always call SyncPrivateData before copying or saving the effect (as if the property were set to 1 &#8212; but the host will not create or modify the property).

kOfxPropPluginDescription

Description of the plug-in to a user.

  • Type - string X 1

  • Property Set - plugin descriptor (read/write) and instance (read only)

  • Default - “”

  • Valid Values - UTF8 string

This is a string giving a potentially verbose description of the effect.

kOfxPropShortLabel

Short user visible name of an object.

  • Type - UTF8 C string X 1

  • Property Set - on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases.

  • Default - initially kOfxPropName, but will be reset if kOfxPropLabel is changed.

This is a shorter version of the label, typically 13 character glyphs or less. Hosts should use this if they have limitted display space for their object labels.

kOfxPropTime

General property used to get/set the time of something.

  • Type - double X 1

  • Default - 0, if a setable property

  • Property Set - commonly used as an argument to actions, input and output.

kOfxPropType

General property, used to identify the kind of an object behind a handle.

kOfxPropVersion

Identifies a specific version of a host or plugin.

  • Type - int X N

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - “0”

  • Valid Values - positive integers

This is a multi dimensional integer property that represents the version of a host (host descriptor), or plugin (plugin descriptor). These represent a version number of the form ‘1.2.3.4’, with each dimension adding another ‘dot’ on the right.

A version is considered to be more recent than another if its ordered set of values is lexicographically greater than another, reading left to right. (ie: 1.2.4 is smaller than 1.2.6). Also, if the number of dimensions is different, then the values of the missing dimensions are considered to be zero (so 1.2.4 is greater than 1.2).

kOfxPropVersionLabel

Unique user readable version string of a plugin or host.

  • Type - string X 1

  • Property Set - host descriptor (read only), plugin descriptor (read/write)

  • Default - none, the host needs to set this

  • Valid Values - ASCII string

This is purely for user feedback, a plugin or host should use kOfxPropVersion if they need to check for specific versions.