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
kOfxPropTime the effect time for which a region of definition is being requested
kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this action
outArgs – has the following property which the plug-in may set
kOfxImageEffectPropRegionOfDefinition the calculated region of definition, initially set by the host to the default RoD (see below), in Canonical Coordinates.
- Returns:
kOfxStatOK the action was trapped and the RoD was set in the outArgs property set
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
-
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 theoutArgs
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
kOfxPropTime the effect time for which a region of definition is being requested
kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this action
kOfxImageEffectPropRegionOfInterest the region to be rendered in the output image, in Canonical Coordinates.
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 exampleOfxImageClipPropRoI_Source
. These are initialised to the default RoI.
- Returns:
kOfxStatOK, the action was trapped and at least one RoI was set in the outArgs property set
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
-
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:
handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – is redundant and is null
outArgs – has the following property
kOfxImageEffectPropFrameRange the frame range an effect can produce images for
- Pre:
kOfxActionCreateInstance has been called on the instance
the effect instance has been created in the general effect context
- Returns:
kOfxStatOK, the action was trapped and the kOfxImageEffectPropFrameRange was set in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the default value
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
-
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 theoutArgs
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 exampleOfxImageClipPropFrameRange_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:
kOfxStatOK, the action was trapped and at least one frame range in the outArgs property set
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
-
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 inputa 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 supportsa 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
-
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:
handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
kOfxPropTime the time at which to test for identity
kOfxImageEffectPropFieldToRender the field to test for identity
kOfxImageEffectPropRenderWindow the window (in \ref PixelCoordinates) to test for identity under
kOfxImageEffectPropRenderScale the scale factor being applied to the images being renderred
outArgs – has the following properties which the plugin can set
kOfxPropName this to the name of the clip that should be used if the effect is an identity transform, defaults to the empty string
kOfxPropTime the time to use from the indicated source clip as an identity image (allowing time slips to happen), defaults to the value in kOfxPropTime in inArgs
- 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
-
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:
handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
kOfxPropTime the time at which to render
kOfxImageEffectPropFieldToRender the field to render
kOfxImageEffectPropRenderWindow the window (in \ref PixelCoordinates) to render
kOfxImageEffectPropRenderScale the scale factor being applied to the images being renderred
kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance
kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session
kOfxImageEffectPropRenderQualityDraft if the render should be done in draft mode (e.g. for faster scrubbing)
outArgs – is redundant and should be set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance
kOfxImageEffectActionBeginSequenceRender has been called on the instance
- Post:
kOfxImageEffectActionEndSequenceRender action will be called on the instance
- Returns:
kOfxStatOK, the effect rendered happily
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
-
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:
handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be renderred
kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders)
kOfxPropIsInteractive is this a single frame render due to user interaction in a GUI, or a proper full sequence render.
kOfxImageEffectPropRenderScale the scale factor to apply to images for this call
kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance
kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance
- Post:
kOfxImageEffectActionRender action will be called at least once on the instance
kOfxImageEffectActionEndSequenceRender action will be called on the instance
- Returns:
kOfxStatOK, the action was trapped and handled cleanly by the effect,
kOfxStatReplyDefault, the action was not trapped, but all is well anyway,
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,
-
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:
handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be rendered
kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders),
is this a single frame render due to user interaction in a GUI, or a proper full sequence render.
the scale factor to apply to images for this call
whether the effect is currently being rendered in strict frame order on a single instance
if the render is in response to a user modifying the effect in an interactive session
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionCreateInstance has been called on the instance
kOfxImageEffectActionEndSequenceRender action was called on the instance
kOfxImageEffectActionRender action was called at least once on the instance
- Returns:
kOfxStatOK, the action was trapped and handled cleanly by the effect,
kOfxStatReplyDefault, the action was not trapped, but all is well anyway,
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,
-
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:
handle – handle to the context descriptor, cast to an OfxImageEffectHandle this may or may not be the same as passed to kOfxActionDescribe
inArgs – has the following property:
kOfxImageEffectPropContext the context being described
outArgs – is redundant and is set to NULL
- Pre:
kOfxActionDescribe has been called on the descriptor handle,
kOfxActionCreateInstance has not been called
- Returns:
kOfxStatOK, the action was trapped and all was well
kOfxStatErrMissingHostFeature, in which the context will be ignored by the host, the plugin may post a message
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
-
kOfxImageEffectPropSupportedContexts
Indicates to the host the contexts a plugin can be used in.
Type - string X N
Property Set - image effect descriptor passed to kOfxActionDescribe (read/write)
Default - this has no defaults, it must be set
Valid Values - This must be one of
-
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.
Type - string X 1
Property Set - plugin descriptor (read/write)
Default - kOfxImageEffectRenderInstanceSafe
Valid Values - This must be one of
kOfxImageEffectRenderUnsafe - indicating that only a single ‘render’ call can be made at any time amoung all instances,
kOfxImageEffectRenderInstanceSafe - indicating that any instance can have a single ‘render’ call at any one time,
kOfxImageEffectRenderFullySafe - indicating that any instance of a plugin can have multiple renders running simultaneously
-
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.
Type - int X 1
Property Set - read only property on the inArgs of the following actions…
Valid Values -
0 - the host is not currently sequentially rendering,
1 - the host is currentely rendering in a way so that it guarantees sequential rendering.
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.
Type - int X 1
Property Set - read only property on the inArgs of the following actions…
Valid Values -
0 - the host is rendering the instance due to some reason other than an interactive tweak on a UI,
1 - the instance is being rendered because a user is modifying parameters in an interactive session.
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.
Type - string X 1
Property Set - image effect instance (read only)
Valid Values - This must be one of
-
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.
Type - double X 1
Property Set - clip instance (read only), image instance (read only) and kOfxImageEffectActionGetClipPreferences action out args property (read/write)
-
kOfxImageEffectPropFrameRate
The frame rate of a clip or instance’s project.
Type - double X 1
Property Set - clip instance (read only), effect instance (read only) and kOfxImageEffectActionGetClipPreferences action out args property (read/write)
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.
Type - int X 1
Property Set - out argument to kOfxImageEffectActionGetClipPreferences action (read/write).
Default - 0
Valid Values - This must be one of 0 or 1
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.
Type - double X 2
Property Set - an image instance (read only) and as read only an in argument on the following actions,
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
kOfxImageFieldNone - the material is unfielded
kOfxImageFieldLower - the material is fielded, with image rows 0,2,4…. occuring first in a frame
kOfxImageFieldUpper - the material is fielded, with image rows line 1,3,5…. occuring first in a frame
-
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
kOfxImageFieldNone - the image is an unfielded frame
kOfxImageFieldBoth - the image is fielded and contains both interlaced fields
kOfxImageFieldLower - the image is fielded and contains a single field, being the lower field (rows 0,2,4…)
kOfxImageFieldUpper - the image is fielded and contains a single field, being the upper field (rows 1,3,5…)
-
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.
Type - double X 4
Property Set - a read/write out argument property to the kOfxImageEffectActionGetRegionOfDefinition action
Default - see kOfxImageEffectActionGetRegionOfDefinition
The order of the values is x1, y1, x2, y2.
This will be in CanonicalCoordinates
-
kOfxImageEffectPropRegionOfInterest
The value of a region of interest.
Type - double X 4
Property Set - a read only in argument property to the kOfxImageEffectActionGetRegionsOfInterest action
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.
Type - integer X 4
Property Set - a read only in argument property to the kOfxImageEffectActionRender and kOfxImageEffectActionIsIdentity actions
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 forpropHandle
pointer to a the property set pointer, value is returned here
- Return:
kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the paramter handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
OfxStatus (*getParamSet)(OfxImageEffectHandle imageEffect, OfxParamSetHandle *paramSet)
Retrieves the parameter set for the given image effect.
imageEffect
image effect to get the property set forparamSet
pointer to a the parameter set, value is returned here
- Return:
kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the paramter handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
OfxStatus (*clipDefine)(OfxImageEffectHandle imageEffect, const char *name, OfxPropertySetHandle *propertySet)
Define a clip to the effect.
pluginHandle
handle passed into ‘describeInContext’ actionname
unique name of the clip to definepropertySet
property handle for the clip descriptor will be returned here
- 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 pluginname
name of the clip, previously used in a clip define callclip
where to return the clippropertySet
if not NULL, the descriptor handle for a parameter’s property set will be placed here.
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 forpropHandle
pointer to a the property set handle, value is returedn her
- Return:
kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the paramter handle was invalid
kOfxStatErrUnknown - if the type is unknown
-
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 fromtime
time to fetch the image atregion
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
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:
kOfxStatOK - the image was successfully fetched and returned in the handle,
kOfxStatErrBadHandle - the image handle was invalid,
-
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 fromtime
time to fetch the image atregion
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
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
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 allocatememoryHandle
pointer to the memory handle where a return value is placed
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
If there are outstanding locks, these are ignored and the handle and memory are freed anyway.
See ImageEffectsMemoryAllocation.
- Return:
kOfxStatOK if the memory was cleanly deleted
kOfxStatErrBadHandle if the value of memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc
-
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 imageMemoryAllocreturnedPtr
where to the pointer to the locked memory
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
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
-
OfxStatus (*getPropertySet)(OfxImageEffectHandle imageEffect, OfxPropertySetHandle *propHandle)