File ofxImageEffect.h

Defines

_ofxImageEffect_h_
kOfxImageEffectPluginApi

String used to label OFX Image Effect Plug-ins.

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

kOfxImageEffectPluginApiVersion

The current version of the Image Effect API.

kOfxImageComponentNone

String to label something with unset components.

kOfxImageComponentRGBA

String to label images with RGBA components.

kOfxImageComponentRGB

String to label images with RGB components.

kOfxImageComponentAlpha

String to label images with only Alpha components.

kOfxImageEffectContextGenerator

Use to define the generator image effect context. See kOfxImageEffectPropContext.

kOfxImageEffectContextFilter

Use to define the filter effect image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextTransition

Use to define the transition image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextPaint

Use to define the paint image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextGeneral

Use to define the general image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextRetimer

Use to define the retimer effect context See kOfxImageEffectPropContext.

kOfxTypeImageEffectHost

Used as a value for kOfxPropType on image effect host handles.

kOfxTypeImageEffect

Used as a value for kOfxPropType on image effect plugin handles.

kOfxTypeImageEffectInstance

Used as a value for kOfxPropType on image effect instance handles

kOfxTypeClip

Used as a value for kOfxPropType on image effect clips.

kOfxTypeImage

Used as a value for kOfxPropType on image effect images.

kOfxImageEffectActionGetRegionOfDefinition

The region of definition for an image effect is the rectangular section of the 2D image plane that it is capable of filling, given the state of its input clips and parameters. This action is used to calculate the RoD for a plugin instance at a given frame. For more details on regions of definition see Image Effect Architectures.

Note that hosts that have constant sized imagery need not call this action, only hosts that allow image sizes to vary need call this.

If the effect did not trap this, it means the host should use the default RoD instead, which depends on the context. This is…

  • generator context - defaults to the project window,

  • filter and paint contexts - defaults to the RoD of the ‘Source’ input clip at the given time,

  • transition context - defaults to the union of the RoDs of the ‘SourceFrom’ and ‘SourceTo’ input clips at the given time,

  • general context - defaults to the union of the RoDs of all the non optional input clips and the ‘Source’ input clip (if it exists and it is connected) at the given time, if none exist, then it is the project window

  • retimer context - defaults to the union of the RoD of the ‘Source’ input clip at the frame directly preceding the value of the ‘SourceTime’ double parameter and the frame directly after it

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

  • outArgs – has the following property which the plug-in may set

Returns:

kOfxImageEffectActionGetRegionsOfInterest

This action allows a host to ask an effect, given a region I want to render, what region do you need from each of your input clips. In that way, depending on the host architecture, a host can fetch the minimal amount of the image needed as input. Note that there is a region of interest to be set in outArgs for each input clip that exists on the effect. For more details see Image EffectArchitectures”.

The default RoI is simply the value passed in on the kOfxImageEffectPropRegionOfInterest inArgs property set. All the RoIs in the outArgs property set must initialised to this value before the action is called.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following properties

  • outArgs – has a set of 4 dimensional double properties, one for each of the input clips to the effect. The properties are each named OfxImageClipPropRoI_ with the clip name post pended, for example OfxImageClipPropRoI_Source. These are initialised to the default RoI.

Returns:

kOfxImageEffectActionGetTimeDomain

This action allows a host to ask an effect what range of frames it can produce images over. Only effects instantiated in the GeneralContext” can have this called on them. In all other the host is in strict control over the temporal duration of the effect.

The default is:

  • the union of all the frame ranges of the non optional input clips,

  • infinite if there are no non optional input clips.

Parameters:
Pre:

  • kOfxActionCreateInstance has been called on the instance

  • the effect instance has been created in the general effect context

Returns:

kOfxImageEffectActionGetFramesNeeded

This action lets the host ask the effect what frames are needed from each input clip to process a given frame. For example a temporal based degrainer may need several frames around the frame to render to do its work.

This action need only ever be called if the plugin has set the kOfxImageEffectPropTemporalClipAccess property on the plugin descriptor to be true. Otherwise the host assumes that the only frame needed from the inputs is the current one and this action is not called.

Note that each clip can have it’s required frame range specified, and that you can specify discontinuous sets of ranges for each clip, for example

// The effect always needs the initial frame of the source as well as the previous and current frame
double rangeSource[4];

// required ranges on the source
rangeSource[0] = 0; // we always need frame 0 of the source
rangeSource[1] = 0;
rangeSource[2] = currentFrame - 1; // we also need the previous and current frame on the source
rangeSource[3] = currentFrame;

gPropHost->propSetDoubleN(outArgs, "OfxImageClipPropFrameRange_Source", 4, rangeSource);

Which sets two discontinuous range of frames from the 'Source' clip
required as input.

The default frame range is simply the single frame, kOfxPropTime..kOfxPropTime, found on the inArgs property set. All the frame ranges in the outArgs property set must initialised to this value before the action is called.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – has the following property

    • kOfxPropTime the effect time for which we need to calculate the frames needed on input

    • outArgs has a set of properties, one for each input clip, named OfxImageClipPropFrameRange_ with the name of the clip post-pended. For example OfxImageClipPropFrameRange_Source. All these properties are multi-dimensional doubles, with the dimension is a multiple of two. Each pair of values indicates a continuous range of frames that is needed on the given input. They are all initalised to the default value.

Returns:

kOfxImageEffectActionGetClipPreferences

This action allows a plugin to dynamically specify its preferences for input and output clips. Please see Image Effect Clip Preferences for more details on the behaviour. Clip preferences are constant for the duration of an effect, so this action need only be called once per clip, not once per frame.

This should be called once after creation of an instance, each time an input clip is changed, and whenever a parameter named in the kOfxImageEffectPropClipPreferencesSlaveParam has its value changed.

Parameters:

  • handle – handle to the instance, cast to an OfxImageEffectHandle

  • inArgs – is redundant and is set to NULL

  • outArgs – has the following properties which the plugin can set

    • a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropComponents_ post pended with the clip’s name. This must be set to one of the component types which the host supports and the effect stated it can accept on that input

    • a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropDepth_ post pended with the clip’s name. This must be set to one of the pixel depths both the host and plugin supports

    • a set of double X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropPAR_ post pended with the clip’s name. This is the pixel aspect ratio of the input and output clips. This must be set to a positive non zero double value,

    • kOfxImageEffectPropFrameRate the frame rate of the output clip, this must be set to a positive non zero double value

    • kOfxImageClipPropFieldOrder the fielding of the output clip

    • kOfxImageEffectPropPreMultiplication the premultiplication of the output clip

    • kOfxImageClipPropContinuousSamples whether the output clip can produce different images at non-frame intervals, defaults to false,

    • kOfxImageEffectFrameVarying whether the output clip can produces different images at different times, even if all parameters and inputs are constant, defaults to false.

Returns:

  • kOfxStatOK, the action was trapped and at least one of the properties in the outArgs was changed from its default value

  • kOfxStatReplyDefault, the action was not trapped and the host should use the default values

  • 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

kOfxImageEffectActionIsIdentity

Sometimes an effect can pass through an input uprocessed, for example a blur effect with a blur size of 0. This action can be called by a host before it attempts to render an effect to determine if it can simply copy input directly to output without having to call the render action on the effect.

If the effect does not need to process any pixels, it should set the value of the kOfxPropName to the clip that the host should us as the output instead, and the kOfxPropTime property on outArgs to be the time at which the frame should be fetched from a clip.

The default action is to call the render action on the effect.

Parameters:
Returns:

  • kOfxStatOK, the action was trapped and the effect should not have its render action called, the values in outArgs indicate what frame from which clip to use instead

  • kOfxStatReplyDefault, the action was not trapped and the host should call the render action

  • 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

kOfxImageEffectActionRender

This action is where an effect gets to push pixels and turn its input clips and parameter set into an output image. This is possibly quite complicated and covered in the Rendering Image Effects chapter.

The render action must be trapped by the plug-in, it cannot return kOfxStatReplyDefault. The pixels needs be pushed I’m afraid.

Parameters:
Pre:

Post:

Returns:

kOfxImageEffectActionBeginSequenceRender

This action is passed to an image effect before it renders a range of frames. It is there to allow an effect to set things up for a long sequence of frames. Note that this is still called, even if only a single frame is being rendered in an interactive environment.

Parameters:
Pre:

Post:

Returns:

kOfxImageEffectActionEndSequenceRender

This action is passed to an image effect after is has rendered a range of frames. It is there to allow an effect to free resources after a long sequence of frame renders. Note that this is still called, even if only a single frame is being rendered in an interactive environment.

Parameters:
Pre:

Returns:

kOfxImageEffectActionDescribeInContext

This action is unique to OFX Image Effect plug-ins. Because a plugin is able to exhibit different behaviour depending on the context of use, each separate context will need to be described individually. It is within this action that image effects describe which parameters and input clips it requires.

This action will be called multiple times, one for each of the contexts the plugin says it is capable of implementing. If a host does not support a certain context, then it need not call kOfxImageEffectActionDescribeInContext for that context.

This action must be trapped, it is not optional.

Parameters:
Pre:

Returns:

kOfxImageEffectPropSupportedContexts

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

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.

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.

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.

kOfxImageEffectRenderUnsafe

String used to label render threads as un thread safe, see, kOfxImageEffectPluginRenderThreadSafety.

kOfxImageEffectRenderInstanceSafe

String used to label render threads as instance thread safe, kOfxImageEffectPluginRenderThreadSafety.

kOfxImageEffectRenderFullySafe

String used to label render threads as fully thread safe, kOfxImageEffectPluginRenderThreadSafety.

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.

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.

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…)

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.

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.

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.

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.

kOfxHostNativeOriginBottomLeft
kOfxHostNativeOriginTopLeft
kOfxHostNativeOriginCenter
kOfxImageEffectHostPropNativeOrigin

Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processing.

  • Type - UTF8 string X 1

  • Property Set - read only property (host)

    • Valid Values - “kOfxImageEffectHostPropNativeOriginBottomLeft” - 0,0 bottom left “kOfxImageEffectHostPropNativeOriginTopLeft” - 0,0 top left “kOfxImageEffectHostPropNativeOriginCenter” - 0,0 center (screen space)

This property is set to kOfxHostNativeOriginBottomLeft pre V1.4 and was to be discovered by plug-ins. This is useful for drawing overlay for points… so everything matches the rest of the app (for example expression linking to other tools, or simply match the reported location of the host viewer).

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.

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.

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.

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.

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

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.

kOfxImageEffectPropContext

Indicates the context a plugin instance has been created for.

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.

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.

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.

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.

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.

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

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.

kOfxImageOpaque

Used to flag the alpha of an image as opaque

kOfxImagePreMultiplied

Used to flag an image as premultiplied

kOfxImageUnPreMultiplied

Used to flag an image as unpremultiplied

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.

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

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

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.

kOfxImagePropPixelAspectRatio

The pixel aspect ratio of a clip or image.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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)

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.

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

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

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.

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.

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

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

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.

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…)

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.

kOfxImageEffectPropRenderWindow

The region to be rendered.

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

This will be in PixelCoordinates

kOfxImageFieldNone

String used to label imagery as having no fields

kOfxImageFieldLower

String used to label the lower field (scan lines 0,2,4…) of fielded imagery

kOfxImageFieldUpper

String used to label the upper field (scan lines 1,3,5…) of fielded imagery

kOfxImageFieldBoth

String used to label both fields of fielded imagery, indicating interlaced footage

kOfxImageFieldSingle

String used to label an image that consists of a single field, and so is half height

kOfxImageFieldDoubled

String used to label an image that consists of a single field, but each scan line is double, and so is full height

kOfxImageEffectOutputClipName

String that is the name of the standard OFX output clip.

kOfxImageEffectSimpleSourceClipName

String that is the name of the standard OFX single source input clip.

kOfxImageEffectTransitionSourceFromClipName

String that is the name of the ‘from’ clip in the OFX transition context.

kOfxImageEffectTransitionSourceToClipName

String that is the name of the ‘from’ clip in the OFX transition context.

kOfxImageEffectTransitionParamName

the name of the mandated ‘Transition’ param for the transition context

kOfxImageEffectRetimerParamName

the name of the mandated ‘SourceTime’ param for the retime context

kOfxImageEffectSuite

the string that names image effect suites, passed to OfxHost::fetchSuite

kOfxStatErrImageFormat

Error code for incorrect image formats.

Typedefs

typedef struct OfxImageEffectStruct *OfxImageEffectHandle

Blind declaration of an OFX image effect.

typedef struct OfxImageClipStruct *OfxImageClipHandle

Blind declaration of an OFX image effect.

typedef struct OfxImageMemoryStruct *OfxImageMemoryHandle

Blind declaration for an handle to image memory returned by the image memory management routines.

typedef struct OfxImageEffectSuiteV1 OfxImageEffectSuiteV1

The OFX suite for image effects.

This suite provides the functions needed by a plugin to defined and use an image effect plugin.

struct OfxImageEffectSuiteV1
#include <ofxImageEffect.h>

The OFX suite for image effects.

This suite provides the functions needed by a plugin to defined and use an image effect plugin.

Public Members

OfxStatus (*getPropertySet)(OfxImageEffectHandle imageEffect, OfxPropertySetHandle *propHandle)

Retrieves the property set for the given image effect.

  • imageEffect image effect to get the property set for

  • propHandle pointer to a the property set pointer, value is returned here

The property handle is for the duration of the image effect handle.

Return:

OfxStatus (*getParamSet)(OfxImageEffectHandle imageEffect, OfxParamSetHandle *paramSet)

Retrieves the parameter set for the given image effect.

  • imageEffect image effect to get the property set for

  • paramSet pointer to a the parameter set, value is returned here

The param set handle is valid for the lifetime of the image effect handle.

Return:

OfxStatus (*clipDefine)(OfxImageEffectHandle imageEffect, const char *name, OfxPropertySetHandle *propertySet)

Define a clip to the effect.

  • pluginHandle handle passed into ‘describeInContext’ action

  • name unique name of the clip to define

  • propertySet property handle for the clip descriptor will be returned here

This function defines a clip to a host, the returned property set is used to describe various aspects of the clip to the host. Note that this does not create a clip instance.

Pre:

  • we are inside the describe in context action.

Return:

OfxStatus (*clipGetHandle)(OfxImageEffectHandle imageEffect, const char *name, OfxImageClipHandle *clip, OfxPropertySetHandle *propertySet)

Get the propery handle of the named input clip in the given instance.

  • imageEffect an instance handle to the plugin

  • name name of the clip, previously used in a clip define call

  • clip where to return the clip

  • propertySet if not NULL, the descriptor handle for a parameter’s property set will be placed here.

The propertySet will have the same value as would be returned by OfxImageEffectSuiteV1::clipGetPropertySet 
This return a clip handle for the given instance, note that this will \em not be the same as the
clip handle returned by clipDefine and will be distanct to clip handles in any other instance
of the plugin.

Not a valid call in any of the describe actions.

Pre:

  • create instance action called,

  • name passed to clipDefine for this context,

  • not inside describe or describe in context actions.

Post:

  • handle will be valid for the life time of the instance.

OfxStatus (*clipGetPropertySet)(OfxImageClipHandle clip, OfxPropertySetHandle *propHandle)

Retrieves the property set for a given clip.

  • clip clip effect to get the property set for

  • propHandle pointer to a the property set handle, value is returedn her

The property handle is valid for the lifetime of the clip, which is generally the lifetime of the instance.

Return:

OfxStatus (*clipGetImage)(OfxImageClipHandle clip, OfxTime time, const OfxRectD *region, OfxPropertySetHandle *imageHandle)

Get a handle for an image in a clip at the indicated time and indicated region.

  • clip clip to extract the image from

  • time time to fetch the image at

  • region region to fetch the image from (optional, set to NULL to get a ‘default’ region) this is in the CanonicalCoordinates.

  • imageHandle property set containing the image’s data

An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.

If the region parameter is not set to NULL, then it will be clipped to the clip’s Region of Definition for the given time. The returned image will be at least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip’s Region of Definition.

If clipGetImage is called twice with the same parameters, then two separate image handles will be returned, each of which must be release. The underlying implementation could share image data pointers and use reference counting to maintain them.

Pre:

  • clip was returned by clipGetHandle

Post:

  • image handle is only valid for the duration of the action clipGetImage is called in

  • image handle to be disposed of by clipReleaseImage before the action returns

Return:

  • kOfxStatOK - the image was successfully fetched and returned in the handle,

  • kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plugin should continue operation, but assume the image was black and transparent.

  • kOfxStatErrBadHandle - the clip handle was invalid,

  • kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

OfxStatus (*clipReleaseImage)(OfxPropertySetHandle imageHandle)

Releases the image handle previously returned by clipGetImage.

Pre:

  • imageHandle was returned by clipGetImage

Post:

  • all operations on imageHandle will be invalid

Return:

OfxStatus (*clipGetRegionOfDefinition)(OfxImageClipHandle clip, OfxTime time, OfxRectD *bounds)

Returns the spatial region of definition of the clip at the given time.

  • clipHandle clip to extract the image from

  • time time to fetch the image at

  • region region to fetch the image from (optional, set to NULL to get a ‘default’ region) this is in the CanonicalCoordinates.

  • imageHandle handle where the image is returned

An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.

If the region parameter is not set to NULL, then it will be clipped to the clip’s Region of Definition for the given time. The returned image will be at least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip’s Region of Definition.

Pre:

  • clipHandle was returned by clipGetHandle

Post:

  • bounds will be filled the RoD of the clip at the indicated time

Return:

  • kOfxStatOK - the image was successfully fetched and returned in the handle,

  • kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time, the plugin should continue operation, but assume the image was black and transparent.

  • kOfxStatErrBadHandle - the clip handle was invalid,

  • kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

int (*abort)(OfxImageEffectHandle imageEffect)

Returns whether to abort processing or not.

  • imageEffect instance of the image effect

A host may want to signal to a plugin that it should stop whatever rendering it is doing and start again. Generally this is done in interactive threads in response to users tweaking some parameter.

This function indicates whether a plugin should stop whatever processing it is doing.

Return:

  • 0 if the effect should continue whatever processing it is doing

  • 1 if the effect should abort whatever processing it is doing

OfxStatus (*imageMemoryAlloc)(OfxImageEffectHandle instanceHandle, size_t nBytes, OfxImageMemoryHandle *memoryHandle)

Allocate memory from the host’s image memory pool.

  • instanceHandle effect instance to associate with this memory allocation, may be NULL.

  • nBytes number of bytes to allocate

  • memoryHandle pointer to the memory handle where a return value is placed

Memory handles allocated by this should be freed by OfxImageEffectSuiteV1::imageMemoryFree. To access the memory behind the handle you need to call OfxImageEffectSuiteV1::imageMemoryLock.

See ImageEffectsMemoryAllocation.

Return:

  • kOfxStatOK if all went well, a valid memory handle is placed in memoryHandle

  • kOfxStatErrBadHandle if instanceHandle is not valid, memoryHandle is set to NULL

  • kOfxStatErrMemory if there was not enough memory to satisfy the call, memoryHandle is set to NULL

OfxStatus (*imageMemoryFree)(OfxImageMemoryHandle memoryHandle)

Frees a memory handle and associated memory.

  • memoryHandle memory handle returned by imageMemoryAlloc

This function frees a memory handle and associated memory that was previously allocated via OfxImageEffectSuiteV1::imageMemoryAlloc

If there are outstanding locks, these are ignored and the handle and memory are freed anyway.

See ImageEffectsMemoryAllocation.

Return:

OfxStatus (*imageMemoryLock)(OfxImageMemoryHandle memoryHandle, void **returnedPtr)

Lock the memory associated with a memory handle and make it available for use.

  • memoryHandle memory handle returned by imageMemoryAlloc

  • returnedPtr where to the pointer to the locked memory

This function locks them memory associated with a memory handle and returns a pointer to it. The memory will be 16 byte aligned, to allow use of vector operations.

Note that memory locks and unlocks nest.

After the first lock call, the contents of the memory pointer to by returnedPtr is undefined. All subsequent calls to lock will return memory with the same contents as the previous call.

Also, if unlocked, then relocked, the memory associated with a memory handle may be at a different address.

See also OfxImageEffectSuiteV1::imageMemoryUnlock and ImageEffectsMemoryAllocation.

Return:

  • kOfxStatOK if the memory was locked, a pointer is placed in returnedPtr

  • kOfxStatErrBadHandle if the value of memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc, null is placed in *returnedPtr

  • kOfxStatErrMemory if there was not enough memory to satisfy the call, *returnedPtr is set to NULL

OfxStatus (*imageMemoryUnlock)(OfxImageMemoryHandle memoryHandle)

Unlock allocated image data.

  • allocatedData pointer to memory previously returned by OfxImageEffectSuiteV1::imageAlloc

This function unlocks a previously locked memory handle. Once completely unlocked, memory associated with a memoryHandle is no longer available for use. Attempting to use it results in undefined behaviour.

Note that locks and unlocks nest, and to fully unlock memory you need to match the count of locks placed upon it.

Also note, if you unlock a completely unlocked handle, it has no effect (ie: the lock count can’t be negative).

If unlocked, then relocked, the memory associated with a memory handle may be at a different address, however the contents will remain the same.

See also OfxImageEffectSuiteV1::imageMemoryLock and ImageEffectsMemoryAllocation.

Return:

  • kOfxStatOK if the memory was unlocked cleanly,

  • kOfxStatErrBadHandle if the value of memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc, null is placed in *returnedPtr