Document version 1.3
Copyright © 2005-2012 The Open Effects Association
Table of Contents
OfxPropertySuiteV1::propSetPointer
— Set a single value in a pointer property OfxPropertySuiteV1::propSetString
— Set a single value in a string propertyOfxPropertySuiteV1::propSetDouble
— Set a single value in a double propertyOfxPropertySuiteV1::propSetInt
— Set a single value in an int property OfxPropertySuiteV1::propSetPointerN
— Set multiple values of the pointer propertyOfxPropertySuiteV1::propSetStringN
— Set multiple values of a string propertyOfxPropertySuiteV1::propSetDoubleN
— Set multiple values of a double propertyOfxPropertySuiteV1::propSetIntN
— Set multiple values of an int property OfxPropertySuiteV1::propGetPointer
— Get a single value from a pointer propertyOfxPropertySuiteV1::propGetString
— Get a single value of a string propertyOfxPropertySuiteV1::propGetDouble
— Get a single value of a double propertyOfxPropertySuiteV1::propGetInt
— Get a single value of an int propertyOfxPropertySuiteV1::propGetPointerN
— Get multiple values of a pointer property OfxPropertySuiteV1::propGetStringN
— Get multiple values of a string propertyOfxPropertySuiteV1::propGetDoubleN
— Get multiple values of a double propertyOfxPropertySuiteV1::propGetIntN
— Get multiple values of an int propertyOfxPropertySuiteV1::propReset
— Resets all dimensions of a property to its default valueOfxPropertySuiteV1::propGetDimension
— Gets the dimension of the propertyOfxImageEffectSuiteV1::getPropertySet
— Retrieves the property set for the given image effectOfxImageEffectSuiteV1::getParamSet
— Retrieves the parameter set for the given image effectOfxImageEffectSuiteV1::clipDefine
— Define a clip to the effect. OfxImageEffectSuiteV1::clipGetHandle
— Get the propery handle of the named input clip in the given instance OfxImageEffectSuiteV1::clipGetPropertySet
— Retrieves the property set for a given clipOfxImageEffectSuiteV1::clipGetImage
— Get a handle for an image in a clip at the indicated time and indicated regionOfxImageEffectSuiteV1::clipReleaseImage
— Releases the image handle previously returned by clipGetImageOfxImageEffectSuiteV1::clipGetRegionOfDefinition
— Returns the spatial region of definition of the clip at the given timeOfxImageEffectSuiteV1::abort
— Returns whether to abort processing or not.OfxImageEffectSuiteV1::imageMemoryAlloc
— Allocate memory from the host's image memory poolOfxImageEffectSuiteV1::imageMemoryFree
— Frees a memory handle and associated memory.OfxImageEffectSuiteV1::imageMemoryLock
— Lock the memory associated with a memory handle and make it available for use.OfxImageEffectSuiteV1::imageMemoryUnlock
— Unlock allocated image dataOfxProgressSuiteV1::progressStart
— Initiate a progress bar display.OfxProgressSuiteV1::progressUpdate
— Indicate how much of the processing task has been completed and reports on any abort status.OfxProgressSuiteV1::progressEnd
— Signal that we are finished with the progress meter.OfxTimeLineSuiteV1::getTime
— Get the time value of the timeline that is controlling to the indicated effect.OfxTimeLineSuiteV1::gotoTime
— Move the timeline control to the indicated time.OfxTimeLineSuiteV1::getTimeBounds
— Get the current bounds on a timelineOfxParameterSuiteV1::paramDefine
— Defines a new parameter of the given type in a describe actionOfxParameterSuiteV1::paramGetHandle
— Retrieves the handle for a parameter in a given parameter setOfxParameterSuiteV1::paramSetGetPropertySet
— Retrieves the property set handle for the given parameter setOfxParameterSuiteV1::paramGetPropertySet
— Retrieves the property set handle for the given parameterOfxParameterSuiteV1::paramGetValue
— Gets the current value of a parameter,OfxParameterSuiteV1::paramGetValueAtTime
— Gets the value of a parameter at a specific time.OfxParameterSuiteV1::paramGetDerivative
— Gets the derivative of a parameter at a specific time.OfxParameterSuiteV1::paramGetIntegral
— Gets the integral of a parameter over a specific time range,OfxParameterSuiteV1::paramSetValue
— Sets the current value of a parameterOfxParameterSuiteV1::paramSetValueAtTime
— Keyframes the value of a parameter at a specific time.OfxParameterSuiteV1::paramGetNumKeys
— Returns the number of keyframes in the parameterOfxParameterSuiteV1::paramGetKeyTime
— Returns the time of the nth keyOfxParameterSuiteV1::paramGetKeyIndex
— Finds the index of a keyframe at/before/after a specified time.OfxParameterSuiteV1::paramDeleteKey
— Deletes a keyframe if one exists at the given time.OfxParameterSuiteV1::paramDeleteAllKeys
— Deletes all keyframes from a parameter.OfxParameterSuiteV1::paramCopy
— Copies one parameter to another, including any animation etc...OfxParameterSuiteV1::paramEditBegin
— Used to group any parameter changes for undo/redo purposesOfxParameterSuiteV1::paramEditEnd
— Used to group any parameter changes for undo/redo purposesOfxParametricParameterSuiteV1::parametricParamGetValue
— Evaluates a parametric parameterOfxParametricParameterSuiteV1::parametricParamGetNControlPoints
— Returns the number of control points in the parametric param.OfxParametricParameterSuiteV1::parametricParamGetNthControlPoint
— Returns the key/value pair of the nth control point.OfxParametricParameterSuiteV1::parametricParamSetNthControlPoint
— Modifies an existing control point on a curveOfxParametricParameterSuiteV1::parametricParamAddControlPoint
— Adds a control point to the curve.OfxParametricParameterSuiteV1::parametricParamDeleteControlPoint
— Deletes the nth control point from a parametric param.OfxParametricParameterSuiteV1::parametricParamDeleteAllControlPoints
— Delete all curve control points on the given param.OfxMemorySuiteV1::memoryAlloc
— Allocate memory.OfxMemorySuiteV1::memoryFree
— Frees memory.OfxMultiThreadSuiteV1::multiThread
— Function to spawn SMP threadsOfxMultiThreadSuiteV1::multiThreadNumCPUs
— Function which indicates the number of CPUs available for SMP processingOfxMultiThreadSuiteV1::multiThreadIndex
— Function which indicates the index of the current threadOfxMultiThreadSuiteV1::multiThreadIsSpawnedThread
— Function to enquire if the calling thread was spawned by multiThreadOfxMultiThreadSuiteV1::mutexCreate
— Create a mutexOfxMultiThreadSuiteV1::mutexDestroy
— Destroy a mutexOfxMultiThreadSuiteV1::mutexLock
— Blocking lock on the mutexOfxMultiThreadSuiteV1::mutexUnLock
— Unlock the mutexOfxMultiThreadSuiteV1::mutexTryLock
— Non blocking attempt to lock the mutexOfxInteractSuiteV1::interactSwapBuffers
— Requests an openGL buffer swap on the interact instance OfxInteractSuiteV1::interactRedraw
— Requests a redraw of the interact instance OfxInteractSuiteV1::interactGetPropertySet
— Gets the property set handle for this interact handle OfxMessageSuiteV2::message
— Post a transient message on the host, using printf style varargs. Same as the V1 message suite call.OfxMessageSuiteV2::setPersistentMessage
— Post a persistent message on an effect, using printf style varargs, and set error states. New for V2 message suite.OfxMessageSuiteV2::clearPersistentMessage
Clears any persistent message on an effect handle that was set by OfxMessageSuiteV2::setPersistentMessage
. New for V2 message suite.OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture
— loads an image from an OFX clip as a texture into OpenGL
OfxImageEffectOpenGLRenderSuiteV1::clipFreeTexture
— Releases the texture handle previously returned by
OfxImageEffectOpenGLRenderSuiteV1::flushResources
— Request the host to minimize its GPU resource load
kOfxImageClipPropConnected
— Says whether the clip is actually connected at the moment.kOfxImageClipPropContinuousSamples
— Clip and action argument property which indicates that the clip can be sampled continouslykOfxImageClipPropFieldExtraction
— Controls how a plugin fetched fielded imagery from a clip.kOfxImageClipPropFieldOrder
— Which spatial field occurs temporally first in a frame.kOfxImageClipPropIsMask
— Indicates that a clip is intended to be used as a mask inputkOfxImageClipPropOptional
— Indicates if a clip is optional.kOfxImageClipPropUnmappedComponents
— Indicates the current 'raw' component type on a clip before any mapping by clip preferenceskOfxImageClipPropUnmappedPixelDepth
— Indicates the type of each component in a clip before any mapping by clip preferenceskOfxImageEffectFrameVarying
— Indicates whether an effect will generate different images from frame to frame.kOfxImageEffectHostPropIsBackground
— Indicates if a host is a background render.kOfxImageEffectHostPropNativeOrigin
— Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processingkOfxImageEffectInstancePropEffectDuration
— The duration of the effectkOfxImageEffectInstancePropSequentialRender
— Indicates whether a plugin needs sequential rendering, and a host support itkOfxImageEffectPluginPropFieldRenderTwiceAlways
— Controls how a plugin renders fielded footage.kOfxImageEffectPluginPropGrouping
— Indicates the effect group for this plugin.kOfxImageEffectPluginPropHostFrameThreading
— Indicates whether a plugin lets the host perform per frame SMP threadingkOfxImageEffectPluginPropOverlayInteractV1
— Sets the entry for an effect's overlay interactionkOfxImageEffectPluginPropSingleInstance
— Indicates whether only one instance of a plugin can exist at the same timekOfxImageEffectPluginRenderThreadSafety
— Indicates how many simultaneous renders the plugin can deal with.kOfxImageEffectPropClipPreferencesSlaveParam
— Indicates the set of parameters on which a value change will trigger a change to clip preferenceskOfxImageEffectPropComponents
— Indicates the current component type in a clip or image (after any mapping)kOfxImageEffectPropContext
— Indicates the context a plugin instance has been created for.kOfxImageEffectPropFieldToRender
— Indicates which field is being rendered.kOfxImageEffectPropFrameRange
— The frame range over which a clip has images.kOfxImageEffectPropFrameRate
— The frame rate of a clip or instance's project.kOfxImageEffectPropFrameStep
— The frame step used for a sequence of renderskOfxImageEffectPropInteractiveRenderStatus
— Property that indicates if a plugin is being rendered in response to user interaction.kOfxImageEffectPropOpenGLEnabled
— Indicates that an image effect SHOULD use OpenGL acceleration in
kOfxImageEffectPropOpenGLRenderSupported
— Indicates whether a host or plugin can support OpenGL accelerated
kOfxImageEffectPropOpenGLTextureIndex
— Indicates the texture index of an image turned into an OpenGL
kOfxImageEffectPropOpenGLTextureTarget
— Indicates the texture target enumerator of an image turned into
kOfxImageEffectPropPixelDepth
— Indicates the type of each component in a clip or image (after any mapping)kOfxImageEffectPropPluginHandle
— The plugin handle passed to the initial 'describe' action.kOfxImageEffectPropPreMultiplication
— Indicates the premultiplication state of a clip or imagekOfxImageEffectPropProjectExtent
— The extent of the current project in canonical coordinates.kOfxImageEffectPropProjectOffset
— The offset of the current project in canonical coordinates.kOfxImageEffectPropProjectPixelAspectRatio
— The pixel aspect ratio of the current projectkOfxImageEffectPropProjectSize
— The size of the current project in canonical coordinates.kOfxImageEffectPropRegionOfDefinition
— Used to indicate the region of definition of a plug-inkOfxImageEffectPropRegionOfInterest
— The value of a region of interest.kOfxImageEffectPropRenderQualityDraft
— Indicates whether an effect can take quality shortcuts to improve speed.kOfxImageEffectPropRenderScale
— The proxy render scale currently being applied.kOfxImageEffectPropRenderWindow
— The region to be rendered.kOfxImageEffectPropSequentialRenderStatus
— Property on all the render action that indicate the current sequential render status of a hostkOfxImageEffectPropSetableFielding
— Indicates whether the host will let a plugin set the fielding of the output clip.kOfxImageEffectPropSetableFrameRate
— Indicates whether the host will let a plugin set the frame rate of the output clip.kOfxImageEffectPropSupportedComponents
— Indicates the components supported by a clip or host,kOfxImageEffectPropSupportedContexts
— Indicates to the host the contexts a plugin can be used in.kOfxImageEffectPropSupportedPixelDepths
— Indicates the bit depths support by a plug-in or hostkOfxImageEffectPropSupportsMultiResolution
— Indicates whether a plugin or host support multiple resolution images.kOfxImageEffectPropSupportsMultipleClipDepths
— Indicates whether a host or plugin can support clips of differing component depths going into/out of an effectkOfxImageEffectPropSupportsMultipleClipPARs
— Indicates whether a host or plugin can support clips of differing pixel aspect ratios going into/out of an effectkOfxImageEffectPropSupportsOverlays
Indicates whether a host support image effect ImageEffectOverlays.kOfxImageEffectPropSupportsTiles
— Indicates whether a clip, plugin or host supports tiled imageskOfxImageEffectPropTemporalClipAccess
— Indicates support for random temporal access to images in a clip.kOfxImageEffectPropUnmappedFrameRange
— The unmaped frame range over which an output clip has images.kOfxImageEffectPropUnmappedFrameRate
— Indicates the original unmapped frame rate (frames/second) of a clipkOfxImagePropBounds
— The bounds of an image's pixels.kOfxImagePropData
— The pixel data pointer of an image.kOfxImagePropField
— Which fields are present in the imagekOfxImagePropPixelAspectRatio
— The pixel aspect ratio of a clip or image.kOfxImagePropRegionOfDefinition
— The full region of definition of an image.kOfxImagePropRowBytes
— The number of bytes in a row of an image.kOfxImagePropUniqueIdentifier
— Uniquely labels an image kOfxInteractPropBackgroundColour
— The background colour of the application behind an interact instancekOfxInteractPropBitDepth
— Indicates whether the dits per component in the interact's openGL frame bufferkOfxInteractPropHasAlpha
— Indicates whether the interact's frame buffer has an alpha component or notkOfxInteractPropPenPosition
— The position of the pen in an interact.kOfxInteractPropPenPressure
— The pressure of the pen in an interact.kOfxInteractPropPenViewportPosition
— The position of the pen in an interact in viewport coordinates.kOfxInteractPropPixelScale
— The size of a real screen pixel under the interact's canonical projection.kOfxInteractPropSlaveToParam
— The set of parameters on which a value change will trigger a redraw for an interact.kOfxInteractPropSuggestedColour
— The suggested colour to draw a widget in an interact, typically for overlays.kOfxOpenGLPropPixelDepth
— Indicates the bit depths supported by a plug-in during OpenGL renders.
kOfxParamHostPropMaxPages
— Indicates the maximum number of parameter pages.kOfxParamHostPropMaxParameters
— Indicates the maximum numbers of parameters available on the host.kOfxParamHostPropPageRowColumnCount
— This indicates the number of parameter rows and coloumns on a page.kOfxParamHostPropSupportsBooleanAnimation
— Indicates if the host supports animation of boolean paramskOfxParamHostPropSupportsChoiceAnimation
— Indicates if the host supports animation of choice params kOfxParamHostPropSupportsCustomAnimation
— Indicates if the host supports animation of custom parameters kOfxParamHostPropSupportsCustomInteract
— Indicates if the host supports custom interacts for parameterskOfxParamHostPropSupportsParametricAnimation
— Property on the host to indicate support for parametric parameter animation.kOfxParamHostPropSupportsStringAnimation
— Indicates if the host supports animation of string params kOfxParamPropAnimates
— Flags whether a parameter can animate.kOfxParamPropCacheInvalidation
— Specifies how modifying the value of a param will affect any output of an effect over time.kOfxParamPropCanUndo
— Flags whether changes to a parameter should be put on the undo/redo stackkOfxParamPropChoiceOption
— Set an option in a choice parameter.kOfxParamPropCustomInterpCallbackV1
— A pointer to a custom parameter's interpolation function.kOfxParamPropCustomValue
— Used by interpolating custom parameters to get and set interpolated values.kOfxParamPropDataPtr
— A private data pointer that the plug-in can store its own data behind.kOfxParamPropDefault
— The default value of a parameter.kOfxParamPropDefaultCoordinateSystem
— Describes in which coordinate system a spatial double parameter's default value is specified.kOfxParamPropDigits
— How many digits after a decimal point to display for a double param in a GUI.kOfxParamPropDimensionLabel
— Label for individual dimensions on a multidimensional numeric parameter.kOfxParamPropDisplayMax
— The maximum value for a numeric parameter on any user interface.kOfxParamPropDisplayMin
— The minimum value for a numeric parameter on any user interface.kOfxParamPropDoubleType
— Describes how the double parameter should be interpreted by a host. kOfxParamPropEnabled
— Used to enable a parameter in the user interface.kOfxParamPropEvaluateOnChange
— Flags whether changing a parameter's value forces an evalution (ie: render),kOfxParamPropGroupOpen
— Whether the initial state of a group is open or closed in a hierarchical layout. kOfxParamPropHasHostOverlayHandle
— A flag to indicate if there is a host overlay UI handle for the given parameter.kOfxParamPropHint
— A hint to the user as to how the parameter is to be used.kOfxParamPropIncrement
— The granularity of a slider used to represent a numeric parameter.kOfxParamPropInteractMinimumSize
— The minimum size of a parameter's custom interface, in screen pixels.kOfxParamPropInteractPreferedSize
— The preferred size of a parameter's custom interface.kOfxParamPropInteractSize
— The size of a parameter instance's custom interface in screen pixels.kOfxParamPropInteractSizeAspect
— The preferred aspect ratio of a parameter's custom interface.kOfxParamPropInteractV1
— Overrides the parameter's standard user interface with the given interact.kOfxParamPropInterpolationAmount
Property used by OfxCustomParamInterpFuncV1
to indicate the amount of interpolation to performkOfxParamPropInterpolationTime
— Used by interpolating custom parameters to indicate the time a key occurs at.kOfxParamPropIsAnimating
— Flags whether a parameter is currently animating.kOfxParamPropIsAutoKeying
— Will a value change on the parameter add automatic keyframes.kOfxParamPropMax
— The maximum value for a numeric parameter.kOfxParamPropMin
— The minimum value for a numeric parameter.kOfxParamPropPageChild
— The names of the parameters included in a page parameter.kOfxParamPropParametricDimension
— The dimension of a parametric paramkOfxParamPropParametricInteractBackground
— Interact entry point to draw the background of a parametric parameter.kOfxParamPropParametricRange
— Property to indicate the min and max range of the parametric input value.kOfxParamPropParametricUIColour
— The colour of parametric param curve interface in any UI.kOfxParamPropParent
— The name of a parameter's parent group.kOfxParamPropPersistant
— Flags whether the value of a parameter should persist.kOfxParamPropPluginMayWrite
— Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis passkOfxParamPropScriptName
— The value to be used as the id of the parameter in a host scripting language.kOfxParamPropSecret
— Flags whether a parameter should be exposed to a user,kOfxParamPropShowTimeMarker
— Enables the display of a time marker on the host's time line to indicate the value of the absolute time param.kOfxParamPropStringFilePathExists
— Indicates string parameters of file or directory type need that file to exist already.kOfxParamPropStringMode
— Used to indicate the type of a string parameter.kOfxParamPropType
— The type of a parameter.kOfxParamPropUseHostOverlayHandle
— A flag to indicate that the host should use a native UI overlay handle for the given parameter.kOfxPluginPropFilePath
— The file path to the plugin.kOfxPluginPropParamPageOrder
— Sets the parameter pages and order of pages.kOfxPropAPIVersion
— Property on the host descriptor, saying what API version of the API is being implementedkOfxPropChangeReason
— Indicates why a plug-in changed.kOfxPropEffectInstance
— A pointer to an effect instance.kOfxPropHostOSHandle
— A pointer to an operating system specific application handle.kOfxPropIcon
— If set this tells the host to use an icon instead of a label for some object in the interface.kOfxPropInstanceData
— A private data pointer that the plug-in can store its own data behind.kOfxPropIsInteractive
— Indicates if a host is actively editing the effect with some GUI.kOfxPropKeyString
— This property encodes a single keypresses that generates a unicode code point. The value is stored as a UTF8 string. kOfxPropKeySym
— Property used to indicate which a key on the keyboard or a button on a button device has been pressedkOfxPropLabel
— User visible name of an object.kOfxPropLongLabel
— Long user visible name of an object.kOfxPropName
— Unique name of an object.kOfxPropParamSetNeedsSyncing
— States whether the plugin needs to resync its private datakOfxPropPluginDescription
— Description of the plug-in to a user.kOfxPropShortLabel
— Short user visible name of an object.kOfxPropTime
— General property used to get/set the time of something.kOfxPropType
— General property, used to identify the kind of an object behind a handlekOfxPropVersion
— Identifies a specific version of a host or plugin.kOfxPropVersionLabel
— Unique user readable version string of a plugin or host.This is a mostly complete reference guide to the OFX image effect plugin architecture. It is a backwards compatible update to the 1.2 version of the API. The changes to the API are listed in an addendum.
OFX is actually several things. At its base it is a generic plug-in architecture which can be used to implement a variety of plug-in APIs. The first such API to be implemented on the core architecture is the OFX Image Effect Plug-in API.
It is all specified using the 'C' programming language. C and C++ are the languages mainly used to write visual effects applications (the initial target for OFX plug-in APIs) and have a very wide adoption across most operating systems with many available compilers. By making the API C, rather than C++, you remove the whole set of problems around C++ symbol mangling between the host and plug-in.
APIs are defined in OFX by only a set of C header files and associated documentation. There are no binary libraries for a plug-in or host to link against.
Hosts rely on two symbols within a plug-in, all other communication is boot strapped from those two symbols. The plug-in has no symbolic dependancies from the host. This minimal symbolic dependancy allows for run-time determination of what features to provide over the API, making implementation much more flexible and less prone to backwards compatibility problems.
Plug-ins, via the two exposed symbols, indicate the API they implement, the version of the API, their name, their version and their main entry point.
A host communicates with a plug-in via sending 'actions' to the plug-in's main entry function. Actions are C strings that indicate the specific operation to be carried out. They are associated with sets of properties, which allows the main entry function to behave as a generic function.
A plug-in communicates with a host by using sets of function pointers given it by the host. These sets of function pointers, known as 'suites', are named via a C string and a version number. They are returned on request from the host as pointers within a C struct.
Properties are typed value/name pairs that exist on the various OFX objects and are action argument values to the plug-in's main entry point. They are how a plug-in and host pass individual values back and forth to each other. The property suite, defined inside ofxProperty.h
is used to do this.
An OFX plug-in API is a named set of actions, properties and suites to perform some specific set of tasks. The first such API that has been defined on the OFX core is the OFX Image Effect API. The set of actions, properties and suites that constitute the API makes up the major part of this document.
Various suites and actions have been defined for the OFX image effect API, however many are actually quite generic and could be reused by other APIs. The property suite definitely has to be used by all other APIs, while the memory allocation suite, the parameter suite and several others would propably be useful for all other APIs. For example the paramter suite could be re-used to specify user visible parameters to the other APIs.
Several types are common to all OFX APIs, and as such are defined in ofxCore.h
. Most objects passed back to
a plug-in are generally specified by blind data handles, for example the OfxPropertySetHandle
. This allows for strong typing on functions
but allows the implementation of the object to be hidden from the plug-in.
Several general assumptions have been made about how hosts and plug-ins communicate, which specific APIs are allowed to break. The main is the distinction between...
In most APIs descriptors are typically passed from a host to a plug-in during the kOfxActionDescribe action, whilst all other actions are passed an instance, e.g: the object passed to the kOfxActionCreateInstance action.
The OFX Image Effect Plug-in API is designed for image effect plug-ins for 2D visual effects. This includes such host applications as compositors, editors, rotoscoping tools and colour grading sytems.
At heart the image effect API allows a host to send a plug-in a set of images, state the value of a set of parameters and get a resulting image back. However how it does this is somewhat complicated, as the plug-in and host have to negotiate what kind of images are handled, how they can be processed and much more.
Where a host application chooses to search for OFX plug ins, what binary format they are in and any directory hierarchy is entirely up to it. However, it is strongly recommended that the following scheme be followed.
Plug-ins should be distributed in the following formats, depending on the host operating system....
Each plug-in binary is distributed as a Mac OS X package style
directory hierarchy. Note that there are two distinct meanings of
'bundle', one referring to a binary file format, the other to a
directory hierarchy used to distribute software. We are distributing
binaries in a bundle package, and in the case of OSX, the binary is a
binary bundle. All the binaries must end with
".ofx"
, regardless of the host operating
system.
The directory hierarchy is as follows.....
Where...
pluginIdentifier
field in the
OfxPlugin
struct,
pluginIdentifier
field in the
OfxPlugin
struct,
Note that not all the above architectures need be supported, at least one.
This structure is necessary on OS X, but it also gives a nice skeleton to hang all other operating systems from in a single install, as well as a clean place to put resources.
The Info.plist
is specific to Apple and you
should consult the Apple developer's website for more details. It
should contain the following keys...
Plug ins are searched for in a variety of locations, both default and user specified. All such directories are examined for plug-in bundles and sub directories are also recursively examined.
A list of directories is supplied in the "OFX_PLUGIN_PATH" environment variable, these are examined, first to last, for plug ins, then the default location is examined.
On Microsoft Windows machines, the plug ins are searched for in,
getStdOFXPluginPath
in the following code snippet...
#include "shlobj.h" #include "tchar.h" const TCHAR *getStdOFXPluginPath(void) { static TCHAR buffer[MAX_PATH]; static int gotIt = 0; if(!gotIt) { gotIt = 1; SHGetFolderPath(NULL, CSIDL_PROGRAM_FILES_COMMON, NULL, SHGFP_TYPE_CURRENT, buffer); _tcscat(buffer, __T("\\OFX\\Plugins")); } return buffer; }
On Apple OSX machines, the plug ins are searched for in,
On UNIX, Linux and other UNIX like operating systems,
Any bundle or sub-directory name starting with the character '@' is to be ignored. Such directories or bundles must be skipped.
Some hosts may wish to display an icon associated with a plug-in on their interfaces. Any such icon must be in the Portable Network Graphics format (see http://www.libpng.org/) and must contain 32 bits of colour, including an alpha channel. Ideally it should be at least 128x128 pixels.
Host applications should dynamically resize the icon to fit their preferred icon size. The icon should not have it's aspect changed, rather the host should fill with some appropriate colour any blank areas due to aspect mis matches.
Ideally plug-in developers should not render the plug-in's name into the icon, as this may be changed by the resource file, especially for internationalisation purposes. Hosts should thus present the plug-in's name next to the icon in some way.
The icon file must be named as the corresponding
pluginIdentifier
field from the
OfxPlugin, post pended with '.png' and be
placed in the resources sub-directory.
Some plug-ins may supply an externally specified resource file.
Typically this is for tasks such as internationalising interfaces,
tweaking user interfaces for specific hosts and so on. These are XML
files and have DTD associated with the specific API, for example OFX
Image Effect DTD is found in ofx.dtd
.
The xml resource file is installed in the
Resources
sub directory of the bundle hierarchy.
It's name will be NAME.xml
, where name is the
base name of the bundle folder and the effect binaries.
The 'C' include files that define an OFX API are all that are needed by a plug-in or host to implement the API. Most include files define a set of independant 'suites' which are used by a plug-in to communicate with a host application.
There are two include files that are used with nearly every derived API. These are...
ofxCore.h
is used to define the basic communication mechanisms between a host and a plug-in. This includes the way in which a plug-in is defined to a host and how to bootstrap the two way communications. It also has several other basic action and property definitions.
ofxProperty.h
specifies the property suite, which is how a plug-in gets and sets values on various objects in a host application.
Plug-ins must implement two exported functions for a host to identify the plug-ins and to initiate the boot strapping of communication between the two. These functions are...
int OfxGetNumberOfPlugins(void)
- identifies how many plug-ins are implemented in the file,OfxPlugin *OfxGetPlugin(int N)
- returns a structure identifying the Nth plug-in in the file.
#include "ofxCore.h" OfxExport int OfxGetNumberOfPlugins(void);
This function returns the number of plug-ins contained in the binary. It is the very first function called by the host after the binary has been loaded.
This function must be exported by the
binary that contains OFX plug-ins. The
OfxExport defined in
ofxCore.h
is used as an export declaration for
those compilers that require it.
#include "ofxCore.h" OfxExport OfxPlugin *OfxGetPlugin(int nth);
This function returns a pointer to the nth
OfxPlugin struct in the binary.
nth
is between 0 and the number returned by
OfxGetNumberOfPlugins
, minus one. The returned structure
defines the plug-in to the host.
OfxGetNumberOfPlugins
has been previously called, nth
is between 0 and the value returned by OfxGetNumberOfPlugins
, minus one.
This structure is returned by a plugin to identify itself to the host.
typedef struct OfxPlugin { const char *pluginApi; int apiVersion; const char *pluginIdentifier; unsigned int pluginVersionMajor; unsigned int pluginVersionMinor; void (*setHost)(OfxHost *host); OfxPluginEntryPoint *mainEntry; } OfxPlugin;
pluginApi
This C string tells the host what API the plug-in implements.
apiVersion
This integer tells the host which version of its API the plug-in implements.
pluginIdentifier
This is the globally unique name for the plug-in.
pluginVersionMajor
Major version of this plug-in, this gets incremented whenever software is changed and breaks backwards compatibility.
pluginVersionMinor
Minor version of this plug-in, this gets incremented when software is changed, but does not break backwards compatibility.
setHost
Function used to set the host pointer (see below) which allows the plug-in to fetch suites associated with the API it implements.
mainEntry
The plug-in function that takes messages from the host telling it to do things.
When a host gets a pointer back from OfxGetPlugin, it examines
the string pluginApi
. This identifies what
kind of plug-in it is. Currently there is only one publicly specified
API that uses the OFX mechanism, this is
"OfxImageEffectPluginAPI"
, which is the image
effect API being discussed by this book. More APIs may be created at a
future date, for example "OfxImageImportPluginAPI". Knowing the type
of plug-in, the host then knows what suites and host handles are
required for that plug-in and what functions the plug-in itself will
have. The host passes a OfxHost structure
appropriate to that plug-in via its setHost
function. This allows for the same basic architecture to support
different plug-in types trivially.
OFX explicitly versions plug-in APIs. By examining the
apiVersion
, the host knows exactly what set
of functions the plug-in is going to supply and what version of what
suites it will need to provide. This also allows plug-ins to implement
several versions of themselves in the same binary, so it can take
advantages of new features in a V2 API, but present a V1 plug-in to
older hosts that only support V1.
If a host does not support the given plug-in type, or it does not support the given version it should simply ignore that plug-in.
A plug-in needs to uniquely identify itself to a host. This is
the job of pluginIdentifier
. This null
terminated ASCII C string should be unique among all plug-ins, it is
not necessarily meant to convey a sensible name to an end user. The
recommended format is the reverse domain name format of the developer,
for example "uk.co.thefoundry", followed by the developer's unique
name for the plug-in. e.g. "uk.co.thefoundry.F_Kronos".
A plug-in (as opposed to the API it implements) is versioned with two separate integers in the OfxPlugin struct. They serve two separate functions and are,
pluginVersionMajor
flags the functionality contained within a plug-in. Incrementing this number means that you have broken backwards compatibility of the plug-in. More specifically, this means a setup from an earlier version, when loaded into this version, will not yield the same result.
pluginVersionMinor
flags the release of a plug-in that does not break backwards compatibility, but otherwise enhances that plug-in. For example, increment this when you have fixed a bug or made it faster.
If a host encounters multiple versions of the same plug-in it should,
As a more concrete example of versioning: the plug-in identified by "org.wibble:Fred" is initially released as 1.0, However a few months later, wibble.org figure out how to make it faster and release it as 1.1. A year later, Fred can now do automatically what a user once needed to set up five parameters to do, thus making it much simpler to use. However this breaks backwards compatibility as the effect can no longer produce the same output as before, so wibble.org then release this as v2.0.
A user's host might now have three versions of the Fred plug-in on it, v1.0, v1.1 and v2.0. When creating a new instance of the plug-in, the host should always use v2.0. When loading an old project which has a setup from a v1.x plug-in, it should always use the latest, in this case being v1.1.
Note that plug-ins can change the set of parameters between minor version releases. If a plug-in does so, it should do so in a backwards compatible manner, such that the default value of any new parameter would yield the same results as previously. See the chapter below about parameters.
The OfxHost struct is how a host
provides plug-ins with access to the various suites that make up the
API they implement, as well as a host property set handle which a plug-in can ask
questions of. The setHost
function in the
OfxPlugin struct is passed a pointer to an
OfxHost as the first thing to boot-strapping
plug-in/host communication. The struct looks like...
typedef struct OfxHost { OfxPropertySetHandle host; void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion); } OfxHost;
The OfxHost contains two elements,
host
- a property set handle that holds a set of properties which describe the host for the plug-in's API fetchSuite
- a function handle used to fetch function suites from the host that implement the plug-in's API
The host
property set handle in the
OfxHost is not global across all plug-ins
defined in the binary. It is only applicable for the plug-in whose
'setHost' function was called. Use this handle to fetch things like
host application names, host capabilities and so on. The set of
properties on an OFX Image Effect host is found in the section Properties on the Image Effect Host
The fetchSuite
function is how a plug-in
gets a suite from the host. It asks for a suite by giving the C string
corresponding to that suite and the version of that suite. The host
will return a pointer to that suite, or NULL if it does not support
it. Please note that a suite cannot be fetched until the very first
action is called on the plug-in, which is the load action.
Actions are how a host communicates with a plug-in. They are in effect generic function calls. Actions are issued via a plug-in's mainEntry
function pointer found in its OfxPlugin
struct. The function signature for the main entry point is...
#include "ofxCore.h" typedef OfxStatus (OfxPluginEntryPoint)(const char *action, const void *handle, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs);
Where,
action
is a C string indicating the action to be taken,handle
is a handle to an object appropriate to that action, cast to void *
,inArgs
are a set of properties used as arguments to that action,outArgs
are a set of properties the plug-in should modify during the action.
The OfxStatus
value returned is dependant upon the action being called, however the value kOfxStatReplyDefault
is returned if the plug-in does not trap the action.
The exact set of actions passed to a plug-in's entry point are dependent upon the API the plug-in implements. However, there exists a core set of generic actions that most APIs would use.
Suites are how a plug-in communicates back to the host. A suite is simply a set of function pointers in a C struct. The set of suites a host needs to implement is defined by the API being implemented. A suite is fetched from a host via the OfxHost::fetchSuite
function. This returns a pointer (cast to void *
) to the named and versioned set of functions. By using this suite fetching mechanism, there is no symbolic dependancy from the plug-in to the host, and APIs can be easily expandable without causing backwards compatability issues.
If the host does not implement a requested suite, or the requested version of that suite, then it should return NULL.
The following sequence of operations needs to be performed by a
host before it can start telling a plug-in what to do via its
mainEntry
function.
OfxGetNumberOfPlugins
function,
OfxGetPlugin
is called,pluginApi
and
apiVersion
of the returned
OfxPlugin struct are examined,setHost
in the
returned OfxPlugin struct.
Objects are passed back and forth across the API, and in general, it is the thing that passes the data that is
responsible for destroying it. For example the property set handle in the OfxHost struct
is managed by the host.
There are a few explicit exceptions to this. For example, when an image effect asks for an image from a host it is passed back a property set handle which represents the image. That handle needs to later be disposed of by an effect, by an explicit function call back to the host. These few exceptions are documented with the suite functions that access the object.
A special case is made for strings. Strings are considered to be of two types, value strings and label strings. A label string is any string used by OFX to name a property or type. A value string is generally a string value of a property.
More specifically, a label string is a string passed across the API as one of the following...
paramType
argument to OfxParameterSuiteV1::paramDefine,
but not the name
argument)
Label strings are considered to be static constant strings. When passed across the API the host/plug-in receiving the string neither needs to duplicate nor free the string, it can simply retain the orginal pointer passed over and use that in future, as it will not change. A host must be aware that when it unloads a plug-in all such pointers will be invalid, and be prepared to cope with such a situation.
A value string is a string passed across the API as one of the following...
char *
argument to any other function.
Value strings have no assumptions made about them. When one is passed across the API, the thing that passed the string retains ownership of it. The thing getting the string is not responsible for freeing that string. The scope of the string's validity is until the next OFX API function is called. For example, within a plugin
// pointer to store the returned value of the host name char *returnedHostName; // get the host name propSuite->propGetString(hostHandle, kOfxPropName, 0, &returnedHostName); // now make a copy of that before the next API call, as it may not be valid after it char *hostName = strdup(returnedHostName); paramSuite->getParamValue(instance, "myParam", &value);
In general, image effects plug-ins take zero or more input clips and produce an output clip. So far so simple, however there are many devils hiding in the details. Several supporting suites are required from the host and the plug-in needs to respond to a range of actions to work correctly. How an effect is intended to be used also complicates the issue, forcing sets of behaviours depending on the context of an effect.
Plug-ins that implement the image effect API set the pluginApi
member of the OfxPlugin struct
returned by the global OfxGetPlugin
to be kOfxImageEffectPluginApi
.
The current version of the API is 1. This is enough to label the plug-in as an image effect plug-in.
The header files used to define the OFX Image Effect API are...
ofxCore.h
- provides the core definitions of the general OFX architecture that allow the bootstrapping of specific APIs, as well as several core actions,
ofxProperty.h
- provides generic property fetching suite used to get and set values about objects in the API,
ofxParam.h
- provides the suite for defining user visible parameters to an effect,
ofxMultiThread.h
- provides the suite for basic multi-threading capabilities,
ofxInteract.h
- provides the suite that allows a plug-in to use OpenGL to draw their own interactive GUI tools,
ofxKeySyms.h
- provides key symbols used by 'Interacts' to represent keyboard events,
ofxMemory.h
- provides a simple memory allocation suite,
ofxMessage.h
- provides a simple messaging suite to communicate with an end user,
ofxImageEffect.h
- defines a suite and set of actions that draws all the above together to create an visual effect plug-in.
These contain the suite definitions, property definitions and action definitions that are used by the API.
All image effect plug-ins have a main entry point. This is used to trap all the standard actions used to drive the plug-in. They can also have other optional entry points that allow the plug-in to create custom user interface widgets. These interact entry points are specified during the two description actions.
The following actions can be passed to a plug-in's main entry point...
The image effect API uses a variety of different objects. Some are defined via blind data handles, others via property sets, and some by a combination of the two. These objects are...
The host descriptor is represented by the properties found on the host
property set handle
in the OfxHost struct
. The complete set of read only
properties are found in the section Properties on the Image Effect Host.
These sets of properties are there to describe the capabilities of the host to a plug-in, thus giving a plug-in the ability to modify its behaviour depending on the capabilities of the host.
A host descriptor is valid while a plug-in is loaded.
An effect is an object in the OFX Image Effect API that represents an image processing plug-in. It has associated with it
a set of properties, a set of image clips and a set of parameters. These component objects of an effect are defined and used by an effect
to do whatever processing it needs to. A handle to an image effect (instance or descriptor) is passed into a plug-in's
main entry point handle
argument.
The functions that directly manipulate an image effect handle are specified in the image effect suite
found in the header file ofxImageEffect.h
.
An effect descriptor is an object of type OfxImageEffectHandle
passed into an effect's main
entry point handle
argument. The two actions
it is passed to are...
A effect descriptor does not refer to a 'live' effect, it is a handle which the effect uses to describe itself back to the host. It does this by setting a variety of properties on an associated property handle, and specifying a variety of objects (such as clips and parameters) using functions in the available suites.
Once described, a host should cache away the description in some manner so that when an instance is made, it simply looks at the description and creates the necessary objects needed by that instance. This stops the overhead of having every instance be forced to describe itself over the API.
Effect descriptors are only valid in a effect for the duration of the instance they were passed into.
The properties on an effect descriptor can be found in the section Properties on an Effect Descriptor.
A effect instance is an object of type OfxImageEffectHandle
passed into an effect's
main entry point handle
argument. The handle
argument should be statically cast to this type. It is passed into all actions of an image effect that a
descriptor is not passed into.
The effect instance represents a 'live' instance of an effect. Because an effect has previously been described, via a effect descriptor, an instance does not have to respecify the parameters, clips and properties that it needs. These means, that when an instance is passed to an effect, all the objects previously described will have been created.
Generally multiple instances of an effect can be in existence at the same time, each with a different set of parameters, clips and properties.
Effect instances are valid between the calls to kOfxActionCreateInstance and
kOfxActionDestroyInstance, for which it is passed as the handle
argument.
The properties on an effect instance can be found in the section Properties on an Effect Instance.
A clip is a sequential set of images attached to an effect. They are used to fetch images from a host and to specify how a plug-in wishes to manage the sequence.
Clip descriptors are returned by the OfxImageEffectSuiteV1::clipDefine
function. They are used during the kOfxActionDescribe action by an effect
to indicate the presence of an input or output clip and how that clip behaves.
A clip descriptor is only valid for the duration of the action it was created in.
The properties on a clip descriptor can be found in the section Properties on a Clip Descriptor.
Clip instances are returned by the OfxImageEffectSuiteV1::clipGetHandle
function. They are are used to access images and and manipulate properties on an effect instance's input and output clips. A variety of functions
in the OfxImageEffectSuiteV1
are used to manipulate them.
A clip instance is valid while the related effect instance is valid.
The properties on a clip instance can be found in the section Properties on a Clip Instance.
Parameters are user visible objects that an effect uses to specify its state, for example a floating point value used to control the
blur size in a blur effect. Parameters (both descriptors and instances) are represented as blind data handles of type OfxParamHandle
.
Parameter sets are the collection of parameters that an effect has associated with it. They are represented by the type OfxParamSetHandle
.
The contents of an effect's parameter set are defined during the
kOfxImageEffectActionDescribeInContext
action. Parameters cannot be
dynamically added to, or deleted from an effect instance.
Parameters can be of a wide range of types, each of which have their own unique capabilities and property sets. For example a colour parameter differs from a boolean parameter.
Parameters and parameter sets are manipulated via the calls and properties in the parameter suite
specified in ofxParam.h
header file. The properties on parameter instances and descriptors can
be found in the section Properties on Parameter Descriptors and Instances.
Parameter set descriptors are returned by the OfxImageEffectSuiteV1::getParamSet
function. This returns a handle associated with an image effect descriptor which can be used by the parameter suite routines to create and describe
parameters to a host.
A parameter set descriptor is valid for the duration of the
kOfxImageEffectActionDescribeInContext
action in which it is fetched.
Parameter descriptors are returned by the OfxParameterSuiteV1::paramDefine
function. They are used to define the existence of a parameter to the host, and to set the various attributes of that parameter. Later,
when an effect instance is created, an instance of the described parameter will also be created.
A parameter descriptor is valid for the duration of the
kOfxImageEffectActionDescribeInContext
action in which it is created.
Parameter set instances are returned by the OfxImageEffectSuiteV1::getParamSet
function. This returns a handle associated with an image effect instance which can be used by the parameter suite routines to fetch and describe
parameters to a host.
A parameter set handle instance is valid while the associated effect instance remains valid.
Parameter instances are returned by the OfxParameterSuiteV1::paramGetHandle
function. This function fetches a previously described parameter back from the parameter set. The handle can then be passed back to the
various functions in the OfxParameterSuite1V
to manipulate it.
A parameter instance handle remains valid while the associated effect instance remains valid.
An image instance is an object returned by the OfxImageEffectSuiteV1::clipGetImage
function. This fetches an image out of a clip and returns it as a property set to the plugin. The image can be accessed by looking up the property
values in that set, which includes the data pointer to the image.
An image instance is valid until the effect calls
OfxImageEffectSuiteV1::clipReleaseImage
on the property handle. The effect
must release all fetched images before it returns from the action.
The set of properties that make up an image can be found in the section Properties on an Image.
An interact is an OFX object that is used to draw custom user interface elements, for example overlays on top of a host's image viewer
or custom parameter widgets. Interacts have their own main entry point, which is separate to the
effect's main entry point. Typically an interact's main entry point is specified as a pointer property on an OFX object, for example
the kOfxImageEffectPluginPropOverlayInteractV1
property on an effect descriptor.
The functions that directly manipulate interacts are in the interact suite
found in the header file ofxInteract.h
, as well as the properties and
specific actions that apply to interacts.
Interact descriptors are blind handles passed to the describe action sent to
an interact's separate main entry point. They should be cast to the type OfxInteractHandle
.
The properties found on a descriptor are found in section Properties on Interact Descriptors.
Interact instances are blind handles passed to all actions but the describe action sent to
an interact's separate main entry point. They should be cast to the type OfxInteractHandle
.
The properties found on an instance are found in section Properties on Interact Instance.
OFX supports a range of image processing architectures. The simpler ones being special cases of the most complex one. Levels of support, in both plug-in and host, are signalled by setting appropriate properties in the plugin and host.
This chapter describes the most general architecture that OFX can support, with simpler cases just being specialisations of the general case.
At it's most generalised, OFX allows for a complex imaging architecture based around an infinite 2D plane on which we are filling in pixels.
Firstly, there is some subsection of this infinite plane that the user wants to be the end result of their work, call this the project extent. The project extent is always rooted, on its bottom left, at the origin of the image plane. The project extent defines the upper right hand corner of the project window. For example a PAL sized project spans (0, 0) to (768, 576) on the image plane.
We define an image effect as something that can fill in a rectangle of pixels in this infinite plane, possibly using images defined at other locations on this image plane.
An effect has a "Region of Definition" (RoD), this is is the maximum area of the plane that the effect can fill in. for example: a 'read source media' effect would only be able to fill an area as big as it's source media. An effect's RoD may need to be based on the RoD of its inputs, for example: the RoD of a contrast/brightness colour corrector would generally be the RoD of it's input, while the RoD of a rotation effect would be bigger than that of it's input image.
The purpose of the kOfxImageEffectActionGetRegionOfDefinition
action is for the host to ask an effect what its region of definition is. An effect calculates this by looking at its input clips and the
values of its current parameters.
Hosts are not obliged to render all an effects RoD, as it may have fixed frame sizes, or any number of other issues.
Infinite RoDs are used to indicate an effect can fill pixels in anywhere on the image plane it is asked to. For example
a no-input noise generator that generates random colours on a per pixel basis.
An infinite RoD is flagged by setting the minimums to be kOfxFlagInfiniteMin
and the maxmimums to be kOfxFlagInfiniteMax
,
for both double and integer rects.
Hosts and plug-ins need to be infinite RoD aware. Hosts need to clip such RoDs to an appropriate rectangle, typically the
project extent. Plug-ins need to check for infinite RoDs when asking input clips for them and to pass them through unless
they explictly clamp them. To indicate an infinite RoD set it as indicated in the following code snippet.
outputRoD.x1 = kOfxFlagInfiniteMin; outputRoD.y1 = kOfxFlagInfiniteMin; outputRoD.x2 = kOfxFlagInfiniteMax; outputRoD.y2 = kOfxFlagInfiniteMax;
PICTURES
An effect will be asked to fill in some region of this infinite plane. The section it is being asked to fill in is called the "Region of Interest" (RoI).
Before an effect has been asked to process a given RoI, it will be asked to specify the area of each input clip it will need to process that area. For example: a simple colour correction effect only needs as much input as it does output, while a blur will need an area that is larger than the specified RoI by a border of the same width as the blur radius.
The purpose of the kOfxImageEffectActionGetRegionsOfInterest
action is for the host to ask an effect what areas it needs from each input clip, to render a specific output region. An effect needs
to examine its set of parameters and the region it has been asked to render to determine how much of each input
clip it needs.
PICTURES
Tiling is the ability of an effect to manage images that are less than full frame (or in our current nomenclature, less than the full Region of Definition). By tiling the images it renders, a host will render an effect in several passes, say by doing the bottom half, then the top half.
Hosts may tile rendering for a variety of reasons. Usually it is in an attempt to reduce memory demands or to distribute rendering of an effect to several different CPUs or computers.
Effects that in effect only perform per pixel calculations (for example a simple colour gain effect) tile very easily. However in the most general case for effects, tiling may be self defeating, as an effect, in order to render a tile, may need significantly more from its input clips than the tile in question. For example, an effect that performs an 2D transform on its input image, may need to sample all that image even when rendering a very small tile on output, as the input image may have been scaled down so that it only covers a few pixels on output.
PICTURES
The most general compositing hosts allow images to be of any size at any location on our image plane. They also plumb the output of effects into other effects, to create effect trees. When evaluating this tree of effects, a general host will want to render the minimum number of pixels it needs to fill in the final desired image. Typically the top level of this compositing tree is being rendered at a certain project size, for example PAL SD, 2K film and so on. This is where the RoD/RoI calls come in handy.
The host asks the top effect how much picture information it can produce, which in turn asks effects below it their RoDs and so on until leaf effects are reached, which report back up the tree until the top effect calculates its RoD and reports back to the host. The host typically clips that RoD to its project size.
Having determined in this way the window it wants rendered at the top effect, the host asks the top node the regions of interest on each of it's inputs. This again propagates down the effect tree until leaf nodes are encountered. These regions of interest are cached at effect for later use.
At this point the host can start rendering, from the bottom of the tree upwards, by asking each effect to fill in the region of interest that was previously specified in the RoI walk. These regions are then passed to the next level up to render and so on.
Another complication is tiling. If a host tiles, it will need to walk the tree and perform the RoI calculation for each tile that it renders.
The details may differ on specific hosts, but this is more or less the most generic way compositing hosts currently work.
PICTURES
The above architecture is quite complex, as the inputs supplied can lie anywhere on the image plane, as can the output, and they can be subsections of the 'complete' image. Not all hosts work in this way, generally it is only the more advance compositing systems working on large resolution images.
Some other systems allow for images to be anywhere on the image plane, but always pass around full RoD images, never tiles.
The simplest systems, don't have any of of the above complexity. The RoDs, RoIs, images and project sizes in such systems are exactly the same, always. Often these are editting, as opposed to compositing, systems.
Similarly, some plugin effects cannot handle sub RoD images, or even images not rooted at the origin.
The OFX architecture is meant to support all of them. Assuming a plugin supports the most general architecture, it will trivially run on hosts with simpler architectures. However, if a plugin does not support tiled, or arbitarily positioned images, they may not run cleanly on hosts that expect them to do so.
To this end, two properties are provided that flag the capabilities of a plugin or host...
kOfxImageEffectPropSupportsMultiResolution
- which indicates support for images of differing sizes not centred on the origin,kOfxImageEffectPropSupportsTiles
- which indicates support for images that contain less than full frame pixel data
A plug-in should flag these appropriately, so that hosts know how to deal with the effect. A host can either choose to refuse to load a plugin, or, preferentially, pad images with an appropriate amount of black/transparent pixels to enable them to work.
The kOfxImageEffectActionGetRegionsOfInterest
is redundant for plugins that do not support tiled rendering,
as the plugin is asking that it be given the full Region of Definition of all its inputs. A host may have
difficulty doing this (for example with an input that is attached to an effect that can create infinite images
such as a random noise generator), if so, it should clamp images to some a size in some manner.
The RoD/RoI actions are potentially redundant on simpler hosts. For example fixed frame size hosts. If a host has no need to call these actions, it simply should not.
How an image effect is used by an end user affects how it should interact with a host application. For example an effect that is to be used as a transition between two clips works differently to an effect that is a simple filter. One must have two inputs and know how much to mix between the two input clips, the other has fewer constraints on it. Within OFX we have standardised several different uses and have called them contexts.
More specifically, a context mandates certain behaviours from an effect when it is described or instantiated in that context. The major issue is the number of input clips it takes, and how it can interact with those input clips.
All OFX contexts have a single output clip and zero or more input clips. The current contexts defined in OFX are..
A host or plug-in need not support all contexts. For example a host that does not have any paint facility within it should not need to support the paint context, or a simple blur effect need not support the retimer context.
An effect may say that it can be used in more than one context, for example a blur effect that acts as a filter, with a single input to blur, and a general effect, with an input to blur and an optional input to act as a mask to attenuate the blur. In such cases a host should choose the most appropriate context for the way that host's architecture. With our blur example, a tree based compositing host should simply ignore the filter context and always use it in the general context.
Plugins and hosts inform each other what contexts they work in via the multidimensional
kOfxImageEffectPropSupportedContexts
property.
It must be set to at least one of the following values...
kOfxImageEffectContextGenerator
kOfxImageEffectContextFilter
kOfxImageEffectContextTransition
kOfxImageEffectContextPaint
kOfxImageEffectContextGeneral
kOfxImageEffectContextRetimer
A host indicates which contexts it supports by setting the kOfxImageEffectPropSupportedContexts
property in
the global host descriptor. A plugin indicates which contexts it supports by setting this on the effect descriptor passed to
the kOfxActionDescribe
action.
Because a plugin can work in different ways, it needs the ability to describe itself to the host in different ways. This
is the purpose of the kOfxImageEffectActionDescribeInContext
action. This action is called once for each context that the effect supports, and the effect gets to describe the input clips and
parameters appropriate to that context. This means that an effect can have different sets of parameters and clips in different contexts,
though it will most likely have a core set of parameters that it uses in all contexts. From our blur example, both the filter and general
contexts would have a 'blur radius' parameter, but the general context might have an 'invert matte' parameter.
During the kOfxImageEffectActionDescribeInContext
action, an effect must describe all clips and parameters that it
intends to use. This includes the mandated clips and parameters for that context.
A plugin instance is created in a specific contex which will not changed over the lifetime of that instance. The context
can be retrieved from the instance via the kOfxImageEffectPropContext
property on the instance handle.
A generator context is for cases where a plugin can create images without any input clips, eg: a colour bar generator.
In this context, a plugin has the following mandated clips,
Any input clips that are specified must be optional.
A host is responsible for setting the initial preferences of the output clip, it must do this in a manner that is transparent to the plugin. So the pixel depths, components, fielding, frame rate and pixel aspect ratio are under the control of the host. How it arrives at these is a matter for the host, but as a plugin specifies what components it can produce on output, as well as the pixel depths it supports, the host must choose one of these.
Generators still have Regions of Definition. This should generally be,
The pixel preferences action is constrained in this context by the following,
A filter effect is the ordinary way most effects are used with a single input. They allow track or layer based hosts that cannot present extra input to use an effect.
In this context, a plugin has the following mandated objects...
Other input clips may be described, which must all be optional. However there is no way to guarantee that all hosts will be able to wire in such clips, so it is suggested that in cases where effects can take single or multiple inputs, they expose themselves in the filter context with a single input and the general context with multiple inputs.
The pixel preferences action is constrained in this context by the following,
Transitions are effects that blend from one clip to another over time, eg: a wipe or a cross dissolve.
In this context, a plugin has the following mandated objects...
Any other input clips that are specified must be optional. Though it is suggested for simplicity's sake that only the two mandated clips be used.
The 'Transition' parameter cannot be labelled, positioned or controlled by the plug-in in anyway, it can only have it's value read, which will have a number returned between the value of 0 and 1. This number indicates how far through the transition the effect is, at 0 it should output all of 'SourceFrom', at 1 it should output all of 'SourceTo', in the middle some appropriate blend.
The pixel preferences action is constrained in this context by the following,
Paint effects are effects used inside digital painting system, where the effect is limited to a small area of the source image via a masking image. Perhaps 'brush' would have been a better choice for the name of the context.
In this context, a plugin has the following mandated objects...
Any other input clips that are specified must be optional.
The masking images consists of pixels from 0 to the white point of the pixel depth. Where the mask is zero the effect should not occur, where the effect is whitepoint the effect should be 'full on', where it is grey the effect should blend with the source in some manner.
The masking image may be smaller than the source image, even if the effect states that it cannot support multi-resolution images.
The pixel preferences action is constrained in this context by the following,
The retimer context is for effects that change the length of a clip by interpolating frames from the source clip to create an inbetween output frame.
In this context, a plugin has the following mandated objects...
Any other input clips that are specified must be optional.
The 'SourceTime' parameter cannot be labelled, positioned or controlled by the plug-in in anyway, it can only have it's value read. Its value is how the source time to maps to the output time. So if the output time is '3' and the 'SourceTime' parameter returns 8.5 at this time, the resulting image should be an interpolated between source frames 8 and 9.
The pixel preferences action is constrained in this context by the following,
The general context is to some extent a catch all context, but is generally how a 'tree' effect should be instantiated. It has no constraints on its input clips, nor on the pixel preferences actions.
In this context, has the following mandated objects...
The retimer and transition context both mandate a parameter be declared, the double params 'SourceTime' and 'Transition'. The purpose of these parameters is for the host to communicate with the plug-in, they are not meant to be treated as normal parameters, exposed on the user plug-in's user interface.
For example, the purpose of a transition effect is to dissolve in some interesting way between two separate clips, under control of the host application. Typically this is done on systems that edit. The mandated 'Transition' double pseudo-parameter is not a normal one exposed on the plug-in UI, rather it is the way the host indicates how far through the transition the effect is. For example, think about two clips on a time line based editor with a transition between them, the host would set the value value of the 'Transition' parameter implicitly by how far the frame being rendered is from the start of the transition, something along the lines of...
Transition = (currrentFrame - startOfTransition)/lengthOfTransition;
This means that the host is completely responsible for any user interface for that parameter, either implicit (as in the above editing example) or explicit (with a curve).
Similarly with the 'SourceTime' double parameter in the retimer context. It is up to the host to provide a UI for this, either implicitly (say by stretching a clip's length on the time line) or via an explicit curve. Note that the host is not limitted to using a UI that exposes the 'SourceTime' as a curve, alternately it could present a 'speed' parameter, and integrate that to derive a value for 'SourceTime'.
Hosts are generally multi-threaded, those with a GUI will most likely have an interactive thread and a rendering thread, while any host running on a multi-CPU machine may have a render thread per CPU. Host may batch effects off to a render farm, where the same effect has separate frames rendered on completely different machines. OFX needs to address all these situations.
Threads in the host application can be broken into two categories...
For a given effect instance, there can be only one main thread and zero or more render threads.
An instance must be able to handle simultaneous actions called on the main and render threads.
A plugin can control the number of simultaneous render threads via the
kOfxImageEffectPluginRenderThreadSafety
effect descriptor property.
The only actions that can be called on a render thread are...
If a plugin cannot support this multi-threading behaviour, it will need to perform explicit locking itself, using the locking mechanisms in the suites defined in ofxMultiThread.h
This will also mean that the host may need to perform locking on the various function calls over the API. For example, a main and render thread may both simultaneously attempt to access a parameter from a single effect instance. The locking should...
For example, a render thread will only cause a parameter to lock out writes only for the duration of the call that reads the parameter, not for the duration of the whole render action. This will allow a main thread to continue writing to the parameter during a render. This is especially important if you have a custom interactive GUI that you want to keep working during a render call.
Note that a main thread should generally issue an abort to any linked render thread when a parameter or other value affecting the effect (eg: time) has been changed by the user. A re-render should then be issued so that a correct frame is created.
How an effect handles simulanteous calls to render is dealt with in \ref ImageEffectsMultiThreadingRendering.
Many hosts get around the problem of sharing a single instance in a UI thread and a render thread by having two instances, one for the user to interact with and a render only one that shadows the UI instance.
When running on a main thread, some actions may end up being called recursively. A plug-in must be able to deal with this. For example consider the following sequence of events in a plugin...
kOfxActionInstanceChanged
actionkOfxActionInstanceChanged
action for parameter BkOfxInteractActionDraw
issued to the effect's overlaykOfxInteractActionDraw
returnskOfxActionInstanceChanged
action for parameter B returnskOfxActionInstanceChanged
action returns
The image effect actions which may trigger a recursive action call on a single instance are...
The interact actions which may trigger a recursive action to be called on the associated plugin instance are...
The image effect actions which may be called recursively are...
kOfxActionBeginInstanceChanged
kOfxActionInstanceChanged
kOfxActionEndInstanceChanged
kOfxImageEffectActionGetClipPreferences
kOfxImageEffectActionGetRegionOfDefinition
(as a result of calling OfxImageEffectSuiteV1::clipGetImage
from kOfxActionInstanceChanged
)kOfxImageEffectActionGetRegionsOfInterest
(as a result of calling OfxImageEffectSuiteV1::clipGetImage
from kOfxActionInstanceChanged
)
The interact actions which may be called recursively are...
All OFX spatial coordinate systems have the positive Y axis pointing up, and the positive X axis pointing right.
As stated above, images are simply some rectangle in a potentially infinite plane of pixels. However, this is an idealisation of what really goes on, as images composed of real pixels have to take into account pixel aspect ratios and proxy render scales, as such they will not be in the same space as the image plane. To deal with this, OFX has three spatial coordinate systems
The idealised image plane is always in a coordinate system of square unscaled pixels. For example a PAL D1 frame occupies (0,0) to (768,576). We call this the Canonical Coordinate System.
Many operations take place in canonical coordinates, parameter values are expressed in them while the and RoD and RoI actions report their values back in them.
The Canonical coordinate system is always referenced by double floating point values, generally via a OfxRectD
structure.
'Real' images, where we have to deal with addressable pixels in memory, are in a coordinate system of non-square proxy scaled integer values. So a PAL D1 image, being renderred as a half resolution proxy would be (0,0) to (360, 288), which takes into account both the pixel aspect ratio of 1.067 and a scale factor of 0.5f. We call this the Pixel Coordinate System.
The Pixel coordinate system is always referenced by integer values, generally via a OfxRectI structure. It is used when refering to operations on actual pixels, and so is how the bounds of images are described and the render window passed to the render action.
To map between the two the pixel aspect ratio and the render scale need to be known, and it is a simple case of multiplication and rounding. More specifically, given...
kOfxImagePropPixelAspectRatio
kOfxImageEffectPropRenderScale
kOfxImageEffectPropRenderScale
kOfxImagePropField
is kOfxImageFieldLower
or kOfxImageFieldUpper
To map an X and Y coordinates from Pixel coordinates to Canonical coordinates, we perform the following multiplications...
X' = (X * PAR)/SX Y' = Y/(SY * FS)
To map an X and Y coordinates from Canonical coordinates to Pixel coordinates, we perform the following multiplications...
X' = (X * SX)/PAR Y' = Y * SY * FS
Note, normalised parameters and the normalised coordinate system are being deprecated in favour of spatial parameters which can handle the project rescaling without the problems of converting to/from normalised coordinates.
On most editing an compositing systems projects can be moved on resolutions, for example a project may be set up at high definition then have several versions rendered out at different sizes, say a PAL SD version, an NTSC SD version and an HD 720p version.
This causes problems with parameters that describe spatial coordinates. If they are expressed as absolute positions, the values will be incorrect as the project is moved from resolution to resolution. For example, a circle drawn at (384,288) in PAL SD canonical coordinates will be in the centre of the output. Re-render that at 2K film, it will be in the bottom left hand corner, which is probably not the correct spot.
To get around this, OFX allows parameters to be flagged as normalised, which is a resolution independant method of representing spatial coordinates. In this coordinate system, a point expressed as (0.5, 0.5) will appear in the centre of the screen, always.
To transform between normalised and canonical coordinates a simple linear equation is required. What that is requires a certain degree of explanation. It involves three two dimensional values...
As described above, the project extent is the section of the image plane that is coverred by an image that is the desired output of the project, so for a PAL SD project you get an extent of 0,0 to 768,576. As the project is always rooted at the origin, so the extent is actually a size.
Project sizes and offsets are a bit less obvious. Consider a project that is going to be output as PAL D1 imagery, the extent will be 0,0 to 768,576. However our example is a letter box 16:9 project, which leaves a strip of black at bottom and top. The size of the letter box is 768 by 432, while the bottom left of the letter box is offset from the origin by 0,77. The ASCII art below shows the details.....
(768,576) --------------------------------------- | | | BLACK | |.....................................| (768, 504) | | | | | LETTER BOXED IMAGERY | | | | | (0,72) |.....................................| | | | BLACK | | | --------------------------------------- (0,0)
So in this example...
The properties on an effect instance handle allow you to fetch these values...
kOfxImageEffectPropProjectExtent
for the extent of the current project,kOfxImageEffectPropProjectSize
for the size of the current project,kOfxImageEffectPropProjectOffset
for the offset of the current project.
So to map from normalised coordinates to canonical coordinates, you use the project size and offset...
To flag to the host that a parameter as normalised, we use the
kOfxParamPropDoubleType
property. Parameters
that are so flagged have values set and retrieved by an effect in normalized coordinates. However a host
can choose to represent them to the user in whatever space it chooses. The values that this property can
take are...
kOfxParamDoubleTypeX
- a size in the X dimension dimension (1D only), new for 1.2kOfxParamDoubleTypeXAbsolute
- a position in the X dimension (1D only), new for 1.2kOfxParamDoubleTypeY
- a size in the Y dimension dimension (1D only), new for 1.2kOfxParamDoubleTypeYAbsolute
- a position in the X dimension (1D only), new for 1.2 kOfxParamDoubleTypeXY
- a size in the X and Y dimension (2D only), new for 1.2kOfxParamDoubleTypeXYAbsolute
- a position in the X and Y dimension (2D only), new for 1.2kOfxParamDoubleTypeNormalisedX
- normalised size with respect to the project's X dimension (1D only), deprecated for 1.2kOfxParamDoubleTypeNormalisedXAbsolute
- normalised absolute position on the X axis (1D only), deprecated for 1.2kOfxParamDoubleTypeNormalisedY
- normalised size wrt to the project's Y dimension (1D only), deprecated for 1.2kOfxParamDoubleTypeNormalisedYAbsolute
- normalised absolute position on the Y axis (1D only), deprecated for 1.2kOfxParamDoubleTypeNormalisedXY
- normalised to the project's X and Y size (2D only), deprecated for 1.2kOfxParamDoubleTypeNormalisedXYAbsolute
- normalised to the projects X and Y size, and is an absolute position on the image plane, deprecated for 1.2.
For example, we have an effect that draws a circle. It has two parameters a 1D double radius parametere and a 2D double position parameter.
It would flag the radius to be kOfxParamDoubleTypeNormalisedX
, fetch the value and scale that by the project size before we render the circle. The host should present such normalised parameters to the user in a 'sensible' range. So for a PAL project, it would be from 0..768, where the plug-in sees 0..1.
The position can be handled by the kOfxParamDoubleTypeNormalisedXYAbsolute
case. In which case the plugin must scale the parameter's value by the project size and add in the project offset. This will allow the positional parameter to be moved between projects transparently.
Within OFX Image Effects, there is only one temporal coordinate system, this is in output frames referenced to the start of the effect (so the first affected frame = 0). All times within the API are in that coordinate system.
All clip instances have a property that indicates the frames for which they can generate image data.
This is kOfxImageEffectPropFrameRange
, a 2D
double property, with the first dimension being the first, and
the second being last the time at which the clip will generate data.
Consider the example below, it is showing an effect of 10 frames duration applied to a clip lasting 20 frames. The first frame of the effect is infact the 5th frame of the clip. Both the input and output have the same frame rate.
Effect 0 1 2 3 4 5 6 7 8 9 Source 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
In this example, if the effect asks for the source image at time '4', the host will actually return the 9th image of that clip. When queried the output and source clip instances would report the following...
range[0] range[1] FPS Output 0 9 25 Source -4 15 25
Consider the slightly more complex example below, where the output has a frame rate twice the input's
Effect 0 1 2 3 4 5 6 7 8 9 Source 0 1 2 3 4 5 6 7
When queried the output and source clips would report the following.
range[0] range[1] FPS Output 0 9 50 Source -2 12 25
Using simple arithmetic, any effect that needs to access a specific frame of an input, can do so with the formula...
f' = (f - range[0]) * srcFPS/outFPS
Image Effects process images (funny that), this chapeter describes images and clips of images, how they behave and how to deal with them.
Firstly some definitions...
Images and clips contain pixels, these pixels can currently be of the following types...
The components of the pixels can be of the following types...
Components are packed per pixel in the following manner...
There are several structs for pixel types in ofxCore.h that can be used for raw pixels in OFX.
Images are always left to right, bottom to top, with the pixel data pointer being at the bottom left of the image. The pixels in a scan line are contiguously packed.
Scanlines need not be contiguously packed. The number of bytes between between a pixel in the same column, but separated by a scan line is known as the rowbytes of an image. Rowbytes can be negative, allowing for compositing systems with a native top to bottom scanline order to trivially support bottom to top images.
Clips and images also have a pixel aspect ratio, this is how much an actual addressable pixel must be stretched by in X to be square. For example PAL SD images have a pixel aspect ratio of 1.06666.
Images are rectangular, whose integral bounds are in Pixel coordinates, with the image being X1 <= X < X2 and Y1 <= Y < Y2,
ie: exclusive on the top and right. The bounds represent the amount of data present in the image, which may be larger,
smaller or equal to the Region of Definition of the image, depending on the architecture supported by the plugin.
The kOfxImagePropBounds
property on an image holds this information.
An image also contains it's RoD in image coordinates,
in the kOfxImagePropRegionOfDefinition
property. The RoD is the maximum area that an image may have pixels in, t
he bounds are the actual addressable pixels present in an image. This allows for tiled rendering an so on.
Clips have a frame rate, which is the number of frames per second they are to be displayed at. Some clips may be continously samplable (for example, if they are connected to animating geometry that can be rendered at arbitrary times), if this is so, the frame rate for these clips is set to 0.
Images may be composed of full frames, two fields or a single field, depending on its source and how the effect requests the image be processed. Clips are either full frame sequences or fielded sequences.
Images and clips also have a premultiplication state, this represents how the alpha component and the RGB/YUV components may have interacted.
During an the effect's describe in context action an effect must define the clips mandated for
that context, it can also define extra clips that it may need for that context. It does this using the
OfxImageEffectSuiteV1::clipDefine
function, the property handle returned by this function is purely for definition
purposes only. It has not persistance outside the describe in context action and is distinct to the clip property handles
used by instances. The name parameter is how you can later access that clip in a plugin instance via the
OfxImageEffectSuiteV1::clipGetHandle
function.
During the describe in context action, the plugin sets properties on a clip to control its use. The properties that can be set during a describe in context call are...
kOfxPropLabel
to give a user readable name to the clip (the host need not use this, for example in a transition it is redundant),kOfxImageEffectPropSupportedComponents
to specify which components it is willing to accept on that clip,kOfxImageClipPropOptional
to specify if the clip is optional,kOfxImageClipPropFieldExtraction
specifies how to extract fielded images from a clip, see \ref ImageEffectsFieldRendering for more details on field and field rendering,kOfxImageEffectPropTemporalClipAccess
whether the effect wants to access images from the clip at times other that the frame being renderred.
Plugins must indicate which pixel depths they can process by setting the
kOfxImageEffectPropSupportedPixelDepths
on the plugin handle during the describe action.
Pixel Aspect Ratios, frame rates, fielding, components and pixel depths are constant for the duration of a clip, they cannot changed from frame to frame.
kOfxImageEffectPropSupportedPixelDepths
plugin property during its describe actionkOfxImageEffectPropSupportedComponents
on an input clip during describe in context
Clips in instances are retrieved via the OfxImageEffectSuiteV1::clipGetHandle
function.
This returns a property handle for the clip in a specific instance. This handle is valid
for the duration of the instance.
Images are fetched from a clip via the OfxImageEffectSuiteV1::clipGetImage
function. This
takes a time and an optional region to extract an image at from a given clip. This returns,
in a property handle, an image fetched from the clip at a specfic time. The handle contains
all the information relevant to dealing with that image.
Once fetched, an image must be released via the OfxImageEffectSuiteV1::clipReleaseImage
function. All images must be released within the action they were fetched in. You cannot retain an
image after an action has returned.
Images may be fetched from an attached clip in the following situations...
kOfxImageEffectActionRender
actionkOfxActionInstanceChanged
and kOfxActionEndInstanceChanged
actions with a kOfxPropChangeReason
of kOfxChangeUserEdited
A host may not be able to support random temporal access, it flags its ability to do so via the
kOfxImageEffectPropTemporalClipAccess
property. A plugin that wishes to perform random temporal
access must set a property of that name on the plugin handle and the clip it wishes to perform random access from.
All images and clips have a premultiplication state. This is used to indicate how the image should interpret RGB (or YUV) pixels, with respect to alpha. The premultiplication state can be...
kOfxImageOpaque
- the image is opaque and so has no premultiplication state, but the alpha component in all pixels is set to the white point,kOfxImagePreMultiplied
- the image is premultiplied by it's alpha,kOfxImageUnPreMultiplied
- the image is unpremultiplied.
This document won't go into the details of premultiplication, but will simply state that OFX takes notice of it and flags images and clips accordingly.
The premultiplication state of a clip is constant over the entire duration of that clip.
All clips and images have a pixel aspect ratio, this is how much a 'real' pixel must be stretched by in X to be square. For example PAL D1 images have a pixel aspect ratio of 1.06666.
The property kOfxImageEffectPropSupportsMultipleClipPARs
is used to control how a plugin deals with
pixel aspect ratios. This is both a host and plugin property. For a host it can be set to...
For a plugin it can be set to...
If a plugin does not accept clips of differing PARs, then the host must resample all images fed to that effect to agree with the output's PAR.
If a plugin does accept clips of differing PARs, it will need to specify the output clip's PAR in the
kOfxImageEffectActionGetClipPreferences
action.
Under OFX, the images you fetch from the host have already had their memory allocated. If a plug-in needs to define its owns temporary images buffers during processing, or to cache images between actions, then the plug-in should use the image memory allocation routines declared in OfxImageEffectSuiteV1. The reason for this is that many host have special purpose memory pools they manage to optimise memory usage as images can chew up memory very rapidly (eg: a 2K RGBA floating point film plate is 48 MBytes).
For general purpose (as in less than a megabyte) memory allocation, you should use the memory suite in ofxMemory.h
OFX provides four functions to deal with image memory. These are,
A host needs to be able defragment its image memory pool, potentially moving the contents of the memory you have allocated to another address, even saving it to disk under its own virtual memory caching scheme. Because of this when you request a block of memory, you are actually returned a handle to the memory, not the memory itself. To use the memory you must first lock the memory via the imageMemoryLock call, which will then return a pointer to the locked block of memory.
During an single action, there is generally no need to lock/unlock any temporary buffers you may have allocated via this mechanism. However image memory that is cached between actions should always be unlocked while it is not actually being used. This allows a host to do what it needs to do to optimise memory usage.
Note that locks and unlocks nest. This implies that there is a lock count kept on the memory handle, also not that this lock count cannot be negative. So unlocking a completely unlocked handle has no effect.
An example is below....
// get a memory handle OfxImageMemoryHandle memHandle; gEffectSuite->imageMemoryAlloc(0, imageSize, &memHandle); // lock the handle and get a pointer void *memPtr; gEffectSuite->imageMemoryLock(memHandle, &memPtr); ... // do stuff with our pointer // now unlock it gEffectSuite->imageMemoryUnlock(memHandle); // lock it again, note that this may give a completely different address to the last lock gEffectSuite->imageMemoryLock(memHandle, &memPtr); ... // do more stuff // unlock it again gEffectSuite->imageMemoryUnlock(memHandle); // delete it all gEffectSuite->imageMemoryFree(memHandle);
Nearly all plug-ins have some sort of parameters that control their behaviour, the radius of a circle drawer, the frequencies to filter out of an audio signal, the colour of a lens flare and so on.
Seeing as hosts already provide for the general management of their own native parameters (eg: persistance, interface, animation etc...), it would make no sense to force plug-ins to do this all themselves.
The OFX Parameters Suite is the means by which parameters are defined and used by the plug-in but maintained by the host. It is defined in the ofxParam.h header file.
Note that the entire state of the plugin is encoded in the value of its parameter set. If you need to persist some sort of private data, you must do so by setting param values in the effects. The Sync Private Data Action is an action that tells you when to flush any values that need persisting out to the effects param set. You can reconstruct your private data during the Create Instance Action.
A plugin needs to define it's parameters during a describe action. It does this with the OfxParameterSuiteV1::paramDefine
function, which returns a handle to a parameter description. Parameters cannot currently be defined outside of the plugins describe actions.
Parameters are uniquely labelled within a plugin with an ASCII null terminated C-string. This name is not necassarily meant to be end-user readable, various properties are provided to set the user visible labels on the param.
All parameters hold properties, though the exact set of properties on a parameter is dependant on the type of the parameter.
A parameter's handle comes in two slightly different flavours. The handle returned inside a plugin's describe action is not an actual instance of a parameter, it is there for the purpose description only. You can only set properties on that handle (eg: label, min/max value, default ...), you cannot get values from it or set values in it. The parameters defined in the describe action will common to all instances of a plugin.
The handle returned by OfxParameterSuiteV1::paramGetHandle
outside of a describe action will be a working instance of a parameter, you can still set (some) properties of the parameter, and all the get/set value functions are now useable.
There are seventeen types of parameter. These are
Some parameter types are multi dimensional, these are...
kOfxParamTypeDouble2D
- 2 doubleskOfxParamTypeInteger2D
- int X 2kOfxParamTypeDouble3D
- double X 3kOfxParamTypeInteger3D
- int X 3kOfxParamTypeRGB
- double X 3kOfxParamTypeRGBA
- double X 4kOfxParamTypeParametric
- variable dimension
These parameters are treated in an atomic manner, so that all dimensions are set/retrieved simultaneously. This applies to keyframes as well.
The non colour parameters have an implicit 'X', 'Y' and 'Z' dimension, and any interface should display them with such labels.
These are typed by kOfxParamTypeInteger
, kOfxParamTypeInteger2D
and kOfxParamTypeInteger3D
.
Integer parameters are of 1, 2 and 3D varieties and contain integer values, between INT_MIN and INT_MAX.
These are typed by kOfxParamTypeDouble
, kOfxParamTypeDouble2D
and kOfxParamTypeDouble3D
.
Double parameters are of 1, 2 and 3D varieties and contain double precision floating point values.
These are typed by kOfxParamTypeRGB
and kOfxParamTypeRGBA
.
Colour parameters are 3 or 4 dimensional double precision floating point parameters. They are displayed using the host's appropriate interface for a colour. Values are always normalised in the range [0 .. 1], with 0 being the nominal black point and 1 being the white point.
This is typed by kOfxParamTypeBoolean
.
Boolean parameters are integer values that can have only one of two values, 0 or 1.
This is typed by kOfxParamTypeChoice
.
Choice parameters are integer values from 0 to N-1, which correspond to N labeled options.
Choice parameters have their individual options set via the kOfxParamPropChoiceOption
property, for example
gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice"); gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice"); gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3nd Choice"); ... gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, n, "nth Choice");
It is an error to have gaps in the choices after the describe action has returned.
This is typed by kOfxParamTypeString
.
String parameters contain null terminated char *
UTF8 C strings. They can be of several different variants, which is controlled by the kOfxParamPropStringMode
property, these are
kOfxParamStringIsSingleLine
- single line stringkOfxParamStringIsMultiLine
- multi line stringkOfxParamStringIsFilePath
- single line string interpretted as a file path on the computer
this should have appropriate file browser UIs availablekOfxParamStringIsDirectoryPath
- similar to the above, but refers to a directory rather than a filekOfxParamStringIsLabel
- string behaves as a pseudo parameter and acts as a label on the interface in this case the string is not editable by the user
This is typed by kOfxParamTypeGroup
.
Group parameters allow all parameters to be arranged in a tree hierarchy. They have no value, they are purely a grouping element.
All parameters have a kOfxParamPropParent
property, which is a string property naming the group parameter which is its parent.
The empty string "" is used to label the root of the parameter hierarchy, which is the default parent for all parameters.
Parameters inside a group are ordered by their order of addition to that group, which implies parameters in the root group are added in order of definition.
Any host based hierarchical GUI should use this hierarchy to order parameters (eg: animation sheets).
This is typed by kOfxParamTypePage
.
Page parameters are covered in detail in their own section..
This is typed by kOfxParamTypeCustom
.
Custom parameters contain null terminated char * C strings, and may animate. They are designed to provide plugins with a way of storing data that is too complicated or impossible to store in a set of ordinary parameters.
If a custom parameter animates, it must set its kOfxParamPropCustomInterpCallbackV1
property, which points to a OfxCustomParamInterpFuncV1 function. This function is used to interpolate keyframes in custom params.
Custom parameters have no interface by default. However,
kOfxParamPropInteractV1
property, this should be used by the host in any normal (ie: paged or hierarchical) interface for the parameter.Custom parameters are mandatory, as they are simply ASCII C strings. However, animation of custom parameters an support for an in editor interact is optional.
This is typed by kOfxParamTypePushButton
.
Push button parameters have no value, they are there so a plugin can detect if they have been pressed and perform some action. If pressed, a kOfxActionInstanceChanged
action will be issued on the parameter with a kOfxPropChangeReason
of kOfxChangeUserEdited
.
By default the following parameter types animate...
kOfxParamTypeInteger
kOfxParamTypeInteger2D
kOfxParamTypeInteger3D
kOfxParamTypeDouble
kOfxParamTypeDouble2D
kOfxParamTypeDouble3D
kOfxParamTypeRGBA
kOfxParamTypeRGB
The following types cannot animate...
kOfxParamTypeGroup
kOfxParamTypePage
kOfxParamTypePushButton
The following may animate, depending on the host. Properties exist on the host to check this. If the host does support animation on them, then they do _not_ animate by default. They are...
kOfxParamTypeCustom
kOfxParamTypeString
kOfxParamTypeBoolean
kOfxParamTypeChoice
By default the OfxParameterSuiteV1::paramGetValue
will get the 'current' value of the parameter. To access values in a potentially animating parameter, use the OfxParameterSuiteV1::paramGetValueAtTime
function.
Keys can be manipulated in a parameter using a variety of functions, these are...
Parameters will be presented to the user in some form of interface. Typically on most host systems, this comes in three varieties...
Most systems have an animation sheet and present one of either the paged or the hierarchical layouts.
Because a hierarchy of controls is explicitly set during plugin definition, the case of the animation sheet and hierarchial GUIs are taken care of explicitly.
A paged layout of controls is difficult to standardise, as the size of the page and controls, how the controls are positioned on the page, how many controls appear on a page etc... depend very much upon the host implementation. A paged layout is ideally best described in the .XML resource supplied by the plugin, however a fallback page layout can be specified in OFX via the kOfxParamTypePage
parameter type.
Several host properties are associated with paged layouts, these are...
kOfxParamHostPropMaxPages
- the maximum number of pages you may use, 0 implies an unpaged layoutkOfxParamHostPropPageRowColumnCount
- the number of rows and columns for parameters in the paged layout.
Each page parameter represents a page of controls. The controls in that page are set by the plugin using the kOfxParamPropPageChild
multi-dimensional string. For example...
OfxParamHandle page; gHost->paramDefine(plugin, kOfxParamTypePage, "Main", &page); propHost->propSetString(page, kOfxParamPropPageChild, 0, "size"); // add the size parameter to the top left of the page propHost->propSetString(page, kOfxParamPropPageChild, 1, kOfxParamPageSkipRow); // skip a row propHost->propSetString(page, kOfxParamPropPageChild, 2, "centre"); // add the centre parameter propHost->propSetString(page, kOfxParamPropPageChild, 3, kOfxParamPageSkipColumn); // skip a column, we are now at the top of the next column propHost->propSetString(page, kOfxParamPropPageChild, 4, "colour"); // add the colour parameter
The host then places the parameters on that page in the order they were added, starting at the top left and going down columns, then across rows as they fill.
Note that there are two pseudo parameters names used to help control layout, the kOfxParamPageSkipRow
and kOfxParamPageSkipColumn
. These will help control how parameters are added to a page, allowing vertical or horizontal slots to be skipped.
A host sets the order of pages by using the instance's kOfxPluginPropParamPageOrder
property. Note that this property can vary from context to context, so you can exclude pages in contexts they are not useful in. For example...
OfxStatus describeInContext(OfxImageEffectHandle plugin) { ... // order our pages of controls propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 0, "Main"); propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 1, "Sampling"); propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 2, "Colour Correction"); if(isGeneralContext) propHost->propSetString(paramSetProp, kOfxPluginPropParamPageOrder, 3, "Dance! Dance! Dance!"); ... }
Hosts usually retain an undo/redo stack, so users can undo changes they make to a parameter. Often undos and redos are grouped together into an undo/redo block, where multiple parameters are dealt with as a single undo/redo event. Plugins need to be able to deal with this cleanly.
Parameters can be excluded from being undone/redone if they set the kOfxParamPropCanUndo
property to 0.
If the plugin changes parameters' values by calling the get and set value functions, they will ordinarily be put on the undo stack, one event per parameter that is changed. If the plugin wants to group sets of parameter changes into a single undo block and label that block, it should use the OfxParameterSuiteV1::paramEditBegin
and OfxParameterSuiteV1::paramEditEnd
functions.
An example would be a 'preset' choice parameter in a sky simulation whose job is to set other parameters to values that achieve certain looks, eg "Dusk", "Midday", "Stormy", "Night" etc... This parameter has a value change callback which looks for kOfxParamEventUserEdited
then sets other parameters, sky colour, cloud density, sun position etc.... It also resets itself to the first choice, which says "Example Skys...".
Rather than have many undo events appear on the undo stack for each individual parameter change, the effect groups them via the paramEditBegin/paramEditEnd and gets a single undo event. The 'preset' parameter would also not want to be undoable as it such an event is redunant. Note that as the 'preset' has been changed it will be sent another instance changed action, however it will have a reason of kOfxChangePluginEdited
, which it ignores and so stops an infinite loop occuring.
Parameters can have various properties overriden via a seperate XML based resource file.
All parameters flagged with the kOfxParamPropPersistant
property will persist when an effect is saved. How the effect is saved is completely up to the host, it may be in a file, a data base, where ever. We call a saved set of parameters a setup. A host will need to save the major version number of the plugin, as well as the plugin's unique identifier, in any setup.
When an host loads a set up it should do so in the following manner...
It is not an error for a parameter to exist in the plugin but not the setup, and vice versa. This allows a plugin developer to modify parameter sets between point releases, generally by adding new params. The developer should be sure that the default values of any new parameters yield the same behaviour as before they were added, otherwise it would be a breach of the 'major version means compatibility' rule.
Some properties type depends on the kind of the parameter, eg: kOfxParamPropDefault
is an int for a integer parameter but a double X 2 for a kOfxParamTypeDouble2D
parameter.
The variant property types are as follows....
kOfxParamTypeInteger
- int X 1kOfxParamTypeDouble
- double X 1kOfxParamTypeBoolean
- int X 1kOfxParamTypeChoice
- int X 1kOfxParamTypeRGBA
- double X 4 (normalised to 0..1 range)kOfxParamTypeRGB
- double X 3 (normalised to 0..1 range)kOfxParamTypeDouble2D
- double X 2kOfxParamTypeInteger2D
- int X 2kOfxParamTypeDouble3D
- double X 3kOfxParamTypeInteger3D
- int X 3kOfxParamTypeString
- char * X 1kOfxParamTypeCustom
- char * X 1kOfxParamTypePushButton
- none
Double parameters can be used to represent a variety of data, by flagging what a double parameter is representing, a plug-in allows a host to represent to the user a more appropriate interface than a raw numerical value. Double parameters have the kOfxParamPropDoubleType
property, which gives some meaning to the value. This can be one of...
kOfxParamDoubleTypePlain
- parameter has no special interpretation,kOfxParamDoubleTypeAngle
- parameter is to be interpretted as an angle,kOfxParamDoubleTypeScale
- parameter is to be interpretted as a scale factor,kOfxParamDoubleTypeTime
- parameter represents a time value (1D only),kOfxParamDoubleTypeAbsoluteTime
- parameter represents an absolute time value (1D only),kOfxParamDoubleTypeX
- size in the X dimension, in canonical coords (1D double only),kOfxParamDoubleTypeXAbsolute
- positing in the X axis, in canonical coords (1D double only)kOfxParamDoubleTypeY
- size in the Y dimension, in canonical coords (1D double only),kOfxParamDoubleTypeYAbsolute
- positing in the Y axis, in canonical coords (1D double only)kOfxParamDoubleTypeXY
- 2D size, in canonical coords (2D double only),kOfxParamDoubleTypeXYAbsolute
- 2D position, in canonical coords. (2D double only)kOfxParamDoubleTypeNormalisedX
- normalised size with respect to the project's X dimension (1D only),kOfxParamDoubleTypeNormalisedXAbsolute
- normalised absolute position on the X axis (1D only)kOfxParamDoubleTypeNormalisedY
- normalised size wrt to the project's Y dimension(1D only),kOfxParamDoubleTypeNormalisedYAbsolute
- normalised absolute position on the Y axis (1D only)kOfxParamDoubleTypeNormalisedXY
- normalised to the project's X and Y size (2D only),kOfxParamDoubleTypeNormalisedXYAbsolute
- normalised to the projects X and Y size, and is an absolute position on the image plane.
Double parameters with their kOfxParamPropDoubleType
property set to kOfxParamDoubleTypePlain
are uninterpretted. The values represented to the user are what is reported back to the effect when values are retrieved. 1, 2 and 3D parameters can be flagged as kOfxParamDoubleTypePlain
, which is the default.
For example a physical simulation plugin might have a 'mass' double parameter, which is in kilograms, which should be displayed and used as a raw value.
Double parameters with their kOfxParamPropDoubleType
property set to kOfxParamDoubleTypeAngle
are interpretted as angles. The host could use some fancy angle widget in it's interface, representing degrees, angles mils whatever. However, the values returned to a plugin are always in degrees. Applicable to 1, 2 and 3D parameters.
For example a plugin that rotates an image in 3D would declare a 3D double parameter and flag that as an angle parameter and use the values as Euler angles for the rotation.
Double parameters with their kOfxParamPropDoubleType
property set to kOfxParamDoubleTypeScale
are interpretted as scale factors. The host can represent these as 1..100 percentages, 0..1 scale factors, fractions or whatever is appropriate for its interface. However, the plugin sees these as a straight scale factor, in the 0..1 range. Applicable to 1, 2 and 3D parameters.
For example a plugin that scales the size of an image would declare a 'image scale' parameter and use the raw value of that to scale the image.
Double parameters with their kOfxParamPropDoubleType
property set to kOfxParamDoubleTypeTime
are interpretted as a time. The host can represent these as frames, seconds, milliseconds, millenia or whatever it feels is appropriate. However, a visual effect plugin sees such values in 'frames'. Applicable only to 1D double parameters. It is an error to set this on any other type of double parameter.
For example a plugin that does motion blur would have a 'shutter time' parameter and flags that as a time parameter. The value returned would be used as the length of the shutter, in frames.
Double parameters with their kOfxParamPropDoubleType
property set to kOfxParamDoubleTypeAbsoluteTime
are interpretted as an absolute time from the begining of the effect. The host can represent these as frames, seconds, milliseconds, millenia or whatever it feels is appropriate. However, a plugin sees such values in 'frames' from the beginning of a clip. Applicable only to 1D double parameters. It is an error to set this on any other type of double parameter.
For example a plugin that stabalises all the images in a clip to a specific frame would have a 'reference frame' parameter and declare that as an absolute time parameter and use its value to fetch a frame to stablise against.
Parameters that can represent a size or position are essential. To that end there are several values of the kOfxParamPropDoubleType
that say it should be interpretted as a size or position, in either one or two dimensions.
The original OFX API only specifed normalised parameters, this proved to be somewhat more of a problem than expected. With the 1.2 version of the API, spatial parameters were introduced. Ideally these should be used and the normalised parameter types should be deprecated.
Plugins can check kOfxPropAPIVersion to see if these new parameter types are supported, in hosts with version 1.2 or greater they will be.
See the section on coordinate systems to understand some of the terms being discussed.
These parameter types represent a size or position in one or two dimensions in Canonical Coordinate. The host and plug-in get and set values in this coordinate system. Scaling to Pixel Coordinate is the reponsibility of the effect.
The default value of a spatial parameter can be set in either a normalised coordinate system or the canonical coordinate system. This is controlled by the kOfxParamPropDefaultCoordinateSystem on the parameter descriptor.
Parameters can choose to be spatial in several ways...
kOfxParamDoubleTypeX
- size in the X dimension, in canonical coords (1D double only),kOfxParamDoubleTypeXAbsolute
- positing in the X axis, in canonical coords (1D double only)kOfxParamDoubleTypeY
- size in the Y dimension, in canonical coords (1D double only),kOfxParamDoubleTypeYAbsolute
- positing in the Y axis, in canonical coords (1D double only)kOfxParamDoubleTypeXY
- 2D size, in canonical coords (2D double only),kOfxParamDoubleTypeXYAbsolute
- 2D position, in canonical coords. (2D double only).
Ideally, normalised parameters should be deprecated and no longer used if spatial parameters are available.
There are several values of the kOfxParamPropDoubleType
that say it should be interpretted as a size or position. These are expressed and proportional to the current project's size. This will allow the parameter to scale cleanly with project size changes and to be represented to the user in an appropriate range.
For example, the sensible X range of a visual effect plugin is the project's width, say 768 pixels for a PAL D1 definition video project. The user sees the parameter as 0..768, the effect sees it as 0..1. So if the plug-in wanted to set the default value of an effect to be the centre of the image, it would flag a 2D parameter as normalised and set the defaults to be 0.5. The user would see this in the centre of the image, no matter the resolution of the project in question. The plugin would retrieve the parameter as 0..1 and scale it up to the project size to size to use.
Parameters can choose to be normalised in several ways...
kOfxParamDoubleTypeNormalisedX
- normalised size wrt to the project's X dimension (1D only),kOfxParamDoubleTypeNormalisedXAbsolute
- normalised absolute position on the X axis (1D only)kOfxParamDoubleTypeNormalisedY
- normalised size wrt to the project's Y dimension(1D only),kOfxParamDoubleTypeNormalisedYAbsolute
- normalised absolute position on the Y axis (1D only)kOfxParamDoubleTypeNormalisedXY
- normalised to the project's X and Y size (2D only),kOfxParamDoubleTypeNormalisedXYAbsolute
- normalised to the projects X and Y size, and is an absolute position on the image plane.
See the section on coordinate systems on how to scale between normalised, cannonical and pixel coordinates.
In all cases double parameters' defaults, minimums and maximums are specified in the same space as the parameter, as is the increment in all cases but normalised parameters.
Normalised parameters specify thier increments in cannonical coordinates, rather than in normalised coordinates. So an increment of '1' means 1 pixel, not '1 project width', otherwise sliders would be a bit wild.
Parametric params are new for 1.2 and are optinally supported by host applications. They are specified via the
kOfxParamTypeParametric
identifier passed into
OfxParameterSuiteV1::paramDefine
.
These parameters are somewhat more complex than normal parameters and require their own set of functions to manage and manipulate them. The new OfxParametricParameterSuiteV1 is there to do that.
All the defines and suite definitions for parameteric parameters are defined in the file ofxParametricParam.h
Parametric parameters are in effect 'functions' a plug-in can ask a host to arbitrarily evaluate for some value 'x'. A classic use case would be for constructing look-up tables, a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that to fill an array.
A host would probably represent this to a user as a cubic curve in a standard curve editor interface, or possibly through scripting. The user would then use this to define the 'shape' of the parameter.
The evaluation of such params is not the same as animation, they are returning values based on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass a parametric position and time.
Often, you would want such a parametric parameter to be multi-dimensional, for example, a colour look-up table might want three values, one for red, green and blue. Rather than declare three separate parametric parameters, so a parametric parameter can be multi-dimensional.
Due to the nature of the underlying data, you cannot call certain functions in the ordinary parameter suite when manipulating a parametric parameter. All functions in the standard parameter suite are valid when called on a parametric parameter, with the exception of the following....
OfxParameterSuiteV1::paramDefine
.
The descriptor returned by this call have several non standard parameter properties available. These are
Seeing as we need to pass in the parametric position and dimenstion to evaluate, parametric parameters need a new evaluation mechanism. They do this with the OfxParametricParameterSuiteV1::parametricParamGetValue function. This function returns the value of the parameter at the given time, for the given dimension, adt the given parametric position,.
Parametric parameters are effectively interfaces to some sort of host based curve library. To get/set/delete points in the curve that represents a parameter, the new suite has several functions available to manipulate control points of the underlying curve.
To set the default value of a parametric parameter to anything but the identity, you use the control point setting functions in the new suite to
set up a curve on the descriptor returned by OfxParameterSuiteV1::paramDefine
.
Any instances later created, will have that curve as a default.
This simple example defines a colour lookup table, defines a default, and show how to evaluate the curve
// describe our parameter in static OfxStatus describeInContext( OfxImageEffectHandle effect, OfxPropertySetHandle inArgs) { .... // define it OfxPropertySetHandle props; gParamHost->paramDefine(paramSet, kOfxParamTypeParametric, "lookupTable", & props); // set standard names and labeles gPropHost->propSetString(props, kOfxParamPropHint, 0, "Colour lookup table"); gPropHost->propSetString(props, kOfxParamPropScriptName, 0, "lookupTable"); gPropHost->propSetString(props, kOfxPropLabel, 0, "Lookup Table"); // define it as three dimensional gPropHost->propSetInt(props, kOfxParamPropParametricDimension, 0, 3); // label our dimensions are r/g/b gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 0, "red"); gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 1, "green"); gPropHost->propSetString(props, kOfxParamPropDimensionLabel, 2, "blue"); // set the UI colour for each dimension for(int component = 0; component < 3; ++component) { gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 0, component % 3 == 0 ? 1 : 0); gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 1, component % 3 == 1 ? 1 : 0); gPropHost->propSetDouble(props, kOfxParamPropParametricUIColour, component * 3 + 2, component % 3 == 2 ? 1 : 0); } // set the min/max parametric range to 0..1 gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 0, 0.0); gPropHost->propSetDouble(props, kOfxParamPropParametricRange, 1, 1.0); // set a default curve, this example sets an invert OfxParamHandle descriptor; gParamHost->paramGetHandle(paramSet, "lookupTable", &descriptor, NULL); for(int component = 0; component < 3; ++component) { // add a control point at 0, value is 1 gParametricParamHost->parametricParamAddControlPoint(descriptor, component, // curve to set 0.0, // time, ignored in this case, as we are not adding a ket 0.0, // parametric position, zero 1.0, // value to be, 1 false); // don't add a key // add a control point at 1, value is 0 gParametricParamHost->parametricParamAddControlPoint(descriptor, component, 0.0, 1.0, 0.0, false); } ... } void render8Bits(double currentFrame, otherStuff...) { ... // make three luts from our curves unsigned char lut[3][256]; OfxParamHandle param; gParamHost->paramGetHandle(paramSet, "lookupTable", ¶m, NULL); for(int component = 0; component < 3; ++component) { for(int position = 0; position < 256; ++position) { // position to evaluate the param at float parametricPos = float(position)/255.0f; // evaluate the parametric param float value; gParametricParamHost->parametricParamGetValue(param, component, currentFrame, parametricPos, &value); value = value * 255; value = clamp(value, 0, 255); // set that in the lut lut[dimension][position] = (unsigned char)value; } } ... }
Plugins are free to set parameters in limited set of circumstances, typically relating to user interaction. You can only set parameters in the following actions passed to the plug-in's main entry function...
Plugins can also set parameter values during the following actions passed to any of its interacts main entry function...
The kOfxImageEffectActionRender
action is
passed to plugins, when the host requires them to render an output frame.
All calls to the kOfxImageEffectActionRender
are bracketed by a pair of
kOfxImageEffectActionBeginSequenceRender
and kOfxImageEffectActionEndSequenceRender
actions. This is to allow plugins to prepare themselves for rendering long sequences by setting up any tables etc.. it may need.
The kOfxImageEffectActionBeginSequenceRender
will
indicate the frame range that is to be renderred, and whether this is purely a single frame render due to interactive feedback
from a user in a GUI.
The render action is used in conjunction with the optional
If an effect does nothing to its input clips (for example a blur with blur size set to '0') it can indicate
that it is an identity function via the kOfxImageEffectActionIsIdentity
action. The plugin indicates which input the host should use for the region in question. This allows a host to short circuit
the processing of an effect.
Many hosts attempt to minimise the areas that they render by using regions of interest and regions of definition, while some of the simpler hosts do not attempt to do so. In general the order of actions, per frame rendered, is something along the lines of....
A host can ask an effect to render an arbitrary window of pixels, generally these should be clipped
to an effect's region of definition, however, depending on the host, they may not be. The actual region
to render is indicated by the kOfxImageEffectPropRenderWindow
render action argument. If an effect is asked to render outside of its region of definition, it should fill those pixels
in with black transparent pixels.
Note thate OfxImageEffectSuiteV1::clipGetImage
function
takes an optional region parameter. This is a region, in Canonical coordinates, that the effect would like on
that input clip.
If not used in a render action, then the image returned should be based on the previous get region of interest action. If used,
then the image returned will be based on this (usually be clipped to the input's region of definition). Generally a plugin should
not use the region parameter in the render action, but should leave it to the 'default' region.
Multiple render actions may be passed to an effect at the same time. A plug-in states it's level of render thread
safety by setting the kOfxImageEffectPluginRenderThreadSafety
string property. This can be set to one of three states....
kOfxImageEffectRenderUnsafe
- indicating that only a single 'render' action can be made at any time amoung all instances,kOfxImageEffectRenderInstanceSafe
- indicating that any instance can have a single 'render' action at any one time,kOfxImageEffectRenderFullySafe
- indicating that any instance of a plugin can have multiple renders running simultaneously
When rendering on computers that have more that once CPU (or this new-fangled hyperthreading), hosts and effects will want to take advantage of all that extra CPU goodness to speed up rendering. This means multi-threading of the render function in some way.
If the plugin has set kOfxImageEffectPluginRenderThreadSafety
to kOfxImageEffectRenderFullySafe
, the host may choose to render a
single frame across multiple CPUs by having each CPU render a different window. However, the plugin may wish to remain in charge of
multithreading a single frame. The plugin set property
kOfxImageEffectPluginPropHostFrameThreading
informs the host as to whether the host should perform SMP on the effect. It can be set to either...
A host may have a render farm of computers. Depending exactly how the host works with it's render farm, it may have multiple copies on an instance spread over the farm rendering separate frame ranges, 1-100 on station A, 101 to 200 on station B and so on...
Some plugins need the output of the previous frame to render the next, typically they cache some information about the last render and use that somehow on the next frame. Some temporally averaging degraining algorithms work that way. Such effects cannot render correctly unless they are strictly rendered in order, from first to last frame, on a single instance.
Other plugins are able to render correctly when called in an arbitrary frame order, but render much more efficiently if rendered in order. For example a particle system which mantains the state of the particle system in an instance would simply increment the simulation by a frame if rendering in-order, but would need to restart the particle system from scratch if the frame jumped backwards.
Most plug-ins do not have any sequential dependence. For example, a simple gain operation has no dependence on the previous frame.
Similarly, host applications, due to their architectures, may or may not be able to guarantee that a plugin can be rendered strictly in-order. Node based applications typically have much more difficulty in guaranteeing such behaviour.
To indicate whether a plugin needs to be rendered in a strictly sequential order, and to indicate whether a host supports such behaviour we have a property,
kOfxImageEffectInstancePropSequentialRender
. For plug-ins this can be one of three values...
For hosts, this property takes three values...
When rendering, a host will set the in args property on kOfxImageEffectPropSequentialRenderStatus
to indicate whether the host is currently supporting sequential renders. This will be passed to the following actions,
Hosts may still render sequential effects with random frame access in interactive sessions, for example when the user
scrubs the current frame on the timeline and the host asks an effect to render a preview frame. In such cases,
the plugin can detect that the instance is being interactively manipulated via the kOfxImageEffectPropInteractiveRenderStatus
property and hack an approximation together for UI purposes.
If eventually rendering the sequence, the host must ignore all frames rendered out of order and not cache them
for use in the final result.
A host may set the in args property kOfxImageEffectPropRenderQualityDraft
in the sequence render action to asj for a 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.
Fields are evil, but until the world decides to adopt sensible video standard and casts the current ones into the same pit as 2 inch video tape, we are stuck with them.
Before we start, some nomenclature. The Y-Axis is considerred to be up, so in a fielded image,
We don't call them odd and even, so as to avoid confusion with video standard, which have scanline 0 at the top, and so have the opposite sense of our 'odd' and 'even'.
Clips and images from those clips are flagged as to whether they are fielded or not, and if so what is the
spatial/temporal ordering of the fields in that image. The
kOfxImageClipPropFieldOrder
clip and image instance property can be...
kOfxImageFieldNone
- the material is unfieldedkOfxImageFieldLower
- the material is fielded, with scan line 0,2,4.... occuring first in a framekOfxImageFieldUpper
- the material is fielded, with scan line 1,3,5.... occuring first in a frame
Images extracted from a clip flag what their fieldedness is with the property
kOfxImagePropField
, this can be....
kOfxImageFieldNone
- the image is an unfielded framekOfxImageFieldBoth
- the image is fielded and contains both interlaced fields kOfxImageFieldLower
- the image is fielded and contains a single field, being the lower field (lines 0,2,4...)kOfxImageFieldUpper
- the image is fielded and contains a single field, being the upper field (lines 1,3,5...)
The plugin specifies how it deals with fielded imagery by setting the
kOfxImageEffectPluginPropFieldRenderTwiceAlways
property. This can be,
The reason for this is an optimisation. Imagine a text generator with no animation being asked to render into a fielded output clip, it can treat an interlaced fielded image as an unfielded frame. So the host can get the effect to render both fields in one hit and save on the overhead required to do the rendering in two passes.
If called twice per frame, the time passed to the render action will be frame and frame+0.5. So 0.0 0.5 1.0 1.5 etc...
When rendering unfielded footage, the host will only ever call the effect's render action once per frame, with the time being at the integers, 0.0, 1.0, 2.0 and so on.
The render action's argument property
kOfxImageEffectPropFieldToRender
tells the effect which field it should render, this can be one of...
kOfxImageFieldNone
- there are no fields to deal with, the image is full framekOfxImageFieldBoth
- the imagery is fielded and both scan lines should be renderredkOfxImageFieldLower
- the lower field is being rendered (lines 0,2,4...)kOfxImageFieldUpper
- the upper field is being rendered (lines 1,3,5...)
kOfxImageEffectPropFieldToRender
will be set
to kOfxImageFieldBoth
if
kOfxImageEffectPluginPropFieldRenderTwiceAlways
is set to 0 on the plugin,
A plugin can specify how it wishes fielded footage to be fetched from a clip via the clip descriptor property
kOfxImageClipPropFieldExtraction
. This can be one of...
kOfxImageFieldBoth
fetch a full frame interlaced imagekOfxImageFieldSingle
fetch a single field, making a half height imagekOfxImageFieldDoubled
fetch a single field, but doubling each line and so making a full height image (default)
If fetching a single field, the actual field fetched from the source frame is...
To illustrate this last behaviour, the two examples below show an output with twice the frame rate of the input and how clipGetImage maps to the input. The .0 and .5 mean first and second temporal fields.
Behaviour with unfielded footage output 0 1 2 3 source 0 0 1 1Behaviour with fielded footage output 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 source 0.0 0.0 0.5 0.5 1.0 1.0 1.5 1.5
Any host with an interface will most likely have an interactive thread and a rendering thread. This allows an effect to be manipulated while having renders batched off to a background thread. This will mean that some degree of locking will go on to prevent simultaneous read/writes occuring, see \ref ImageEffectsThreadSafety for more on thread safety.
A host may need to abort a backgrounded render, typically in response to a user changing a parameter value.
An effect should occasionally poll the OfxImageEffectSuiteV1::abort
function to see if it should give up on rendering.
When a host presents a graphical user interface to an image effect, it may optionally
give it the chance to draw its own custom GUI tools and to be able to interact with pen and
keyboard input. In OFX this is done via the OfxInteract suite, which is found in the file
ofxInteract.h
.
OFX interacts rely on openGL to perform all drawing in interacts, due to its portabilty, robustness and wide implementation.
Each object that can have their own interact a pointer property in it which should point to a separate main entry point. This entry point is not the same as the one in the OfxPlugin struct, as it needs to respond to a different set of actions to the effect.
There are two things in an image effect can have their own interact, these are...
kOfxImageEffectPluginPropOverlayInteractV1
propertykOfxParamPropInteractV1
property
Hosts might not be able to support interacts, to indicate this, two properties exist on the host descriptor which an effect should examine at description time so as to determine its own behaviour. These are...
Interacts are separate objects to the effect they are associated with,
they have their own descriptor and instance handles
passed into their separate main entry point
.
An interact instance cannot exist without a plugin instance, an interact's instance, once created, is bound to a single instance of a plugin until the interact instance is destroyed.
All interacts of the same type share openGL display lists, even if they are in different openGL contexts.
All interacts of the same type will have the same pixel types (this is a side effect of the last point), this will always be double buffered with at least RGB components. Alpha and the exact bit depth is left to the implementation.
So for example, all image effect overlays share the same display lists and have the same pixel depth, and all custom parameter GUIs share the same display list and have the same pixel depth, but overlays and custom parameter GUIs do not necassarily share the same display list/pixel depths.
An interact instance may be used in more than one view. Consider an image effect overlay interact in a host that supports multiple viewers to an effect instance. The same interact instance will be used in all views, the relevant properties controlling the view being changed before any action is passed to the interact. In this example, the draw action would be called once for each view open on the instance, with the projection, viewport and pixel scale being set appropriately for the view before each action.
Hosts will generally display images (both input and output) in user their interfaces.
A plugin can put an interact in this display by setting the effect descriptor kOfxImageEffectPluginPropOverlayInteractV1
property to point to a main entry.
The viewport for such interacts will depend completely on the host.
The GL_PROJECTION matrix will be set up so that it maps openGL coordinates to canonical image coordinates.
The GL_MODELVIEW matrix will be the identity matrix.
An overlay's interact draw action should assume that it is sharing the openGL context and viewport with other objects that belong to the host. It should not blank the background and it should never swap buffers, that is for the host to do.
All parameters, except for custom parameters, have some default interface that the host creates for them.
Be it a numeric slider, colour swatch etc... Effects can override the default interface
(or set an interface for a custom parameter) by setting the kOfxParamPropInteractV1
.
This will completely replace the parameters default user interface in the 'paged' and 'hierarchical'
interfaces, but it will not replace the parameter's interface in any animation sheet.
Properties affecting custom interacts for parameters are...
The viewport for such interacts will be dependant upon the various properties above, and possibly a per host override in any XML resource file.
The GL_PROJECTION matrix will be an orthographic 2D view with -0.5,-0.5 at the bottom left and viewport width-0.5, viewport height-0.5 at the top right.
The GL_MODELVIEW matrix will be the identity matrix.
The bit depth will be double buffered 24 bit RGB.
A parameter's interact draw function will have full responsibility for drawing the interact, including clearing the background and swapping buffers.
The following actions are passed to any interact entry point in an image effect plug-in.
An interact cannot be described until an effect has been described.
An interact instance must always be associated with an effect instance. So it gets created after an effect and destroyed before one.
An interact instance should be issued a gain focus action before any key or pen actions are issued, and a lose focus action when it goes.
The kOfxImageEffectActionGetClipPreferences
action is passed to an effect to allow a plugin to specify how it wishes to deal with it's input clips and to set
properties in it's output clip. This is especially important when there are multiple inputs of which my have differing properties, eg; pixel depth.
More specifically, there are six properties that can be set during the clip preferences action, some on the input clip, some on the output clip, some on both. These are...
The behaviour specified by OFX means that a host may need to cast images from their native data format into one suitable for the plugin. It is better that the host do any of this pixel shuffling because,
A plugin gets to assert its clip preferences in several situations. Firstly whenever a clip is attached to a plugin, secondly whenever one of the parameters in the plugin property kOfxImageEffectPropClipPreferencesSlaveParam
has its value changed. The clip preferences action is never called until all non optional clips have been attached to the plugin.
Some plugins can generate differing output frames at different times, even if no parameters animate or no input images change. The kOfxImageEffectFrameVarying
property set in the clip preferences action is used to flag this.
A counter example is a solid colour generator. If it has no animating parameters, the image generated at frame 0 will be the same as the image generated at any other frame. Intellegent hosts can render a single frame and cache that for use at all other times.
On the other hand, a plugin that generates random noise at each frame, and seeds its random number generator with the render time, will create different images at different times. The host cannot render a single frame and cache that for use at subsequent times.
To differentiate between these two cases the kOfxImageEffectFrameVarying
is used. If set to 1, it indicates that the effect will need to be rendered at each frame, even if no input images or parameters are varying. If set to 0, then a single frame can be rendered and used for all times if no input images or parameters vary. The default value is 0.
Some effects can generate images at non frame boundaries, even if the inputs to the effect are frame based and there is no animation.
For example a fractal cloud generator whose pattern evolves with a speed parameter can be rendered at arbitrary times, not just on frame boundaries. Hosts that are interested in sub frame rendering can determine this by behaviour by examining the kOfxImageClipPropContinuousSamples
property set in the clip preferences action. By default this is false.
Implicitly, all retimers effects can be continuously sampled.
Hosts and plugins flag whether whether they can deal with input/output clips of differing pixel depths via the kOfxImageEffectPropSupportsMultipleClipDepths
property.
If the host sets this to 0, then all effect's input and output clips will always have the same component depth, and the plugin may not remap them.
If the plugin sets this to 0, then the host will transparently map all of an effect's input and output clips to a single depth, even if the actual clips are of differing depths.In the above two cases, the common component depth chosen will be the deepest depth of any input clip mapped to a depth the plugin supports that loses the least precision. eg: if a plugin supported 8 bit and float images, but the deepest clip attached to it was 16 bit, the host would transparently map all clips to float.
If both the plugin and host set this to 1, then the plugin can, during the kOfxImageEffectActionGetClipPreferences
, specify how the host is to map each clip, including the output clip. Note that this is the only case where a plugin may set the output depth.
A plugin specifies what components it is willing to accept on a clip via the kOfxImageEffectPropSupportedComponents
on the clip's descriptor during the kOfxImageEffectActionDescribeInContext
. This is one or more of RGBA, YUVA and A.
If an effect has multiple inputs, and each can be a range of component types, the effect may end up with component types that are incompatible for its purposes. In this case the effect will want to have the host remap the components of the inputs and to specify the components in the output.
For example, a general effect that blends two images will have have two inputs, each of which may be RGBA or A. In operation, if presented with RGBA on one and A on the other, it will most likely request that the A clip be mapped to RGBA by the host and the output be RGBA as well.
In all contexts, except for the general context, mandated input clips cannot have their component types remapped, nor can the output. Optional input clips can always have their component types remapped.
In the general context, all input clips may be remapped, as can the output clip. The output clip has it's default components set to be, - RGBA if any of the inputs is RGBA, - otherwise YUVA if any of the inputs is YUVA, - otherwise A if the effect has any inputs, - otherwise RGBA if there are no inputs.
It a host implementation detail as to how a host actually attaches real clips to a plugin. For instance, a host may allow a YUVA clip to be wired to an input that asks for RGBA only. However it must map the clip to RGBA in a manner that is transparent to the plugin. Similarly for any other component types that the plugin does not support on an input.
Hosts and plugins flag whether whether they can deal with input/output clips of differing pixel aspect ratios via the kOfxImageEffectPropSupportsMultipleClipPARs
property.
If the host sets this to 0, then all effect's input and output clips will always have the same pixel aspect ratio, and the plugin may not remap them.
If the plugin sets this to 0, then the host will transparently map all of an effect's input and output clips to a single pixel aspect ratio, even if the actual clips are of differring PARs.
In the above two cases, the common pixel aspect ratio chosen will be the smallest on all the inputs, as this preserves image data.
If both the plugin and host set this to 1, then the plugin can, during kOfxImageEffectActionGetClipPreferences
, specify how the host is to map each clip, including the output clip.
The kOfxImageEffectPropSetableFielding
host property indicates if a plugin is able to change the fielding of the output clip from the default.
The default value of the output clip's fielding is host dependant, but in general,
If the host allows a plugin to specify the fielding of the output clip, then a plugin may do so during the kOfxImageEffectActionGetClipPreferences
by setting the property kOfxImageClipPropFieldOrder
in the out args argumment of the action. For example a defielding plugin will want to indicate that the output is frame based rather than fielded.
The kOfxImageEffectPropSetableFrameRate
host property indicates if a plugin is able to change the frame rate of the output clip from the default.
The default value of the output clip's frame rate is host dependant, but in general, it will be based on the input clips frame rates.
If the host allows a plugin to specify the frame rate of the output clip, then a plugin may do so during the kOfxImageEffectActionGetClipPreferences
. For example a deinterlace plugin that separates both fields from fielded footage will want to do double the frame rate of the output clip.
If a plugin changes the frame rate, it is effectively changing the number of frames in the output clip. If our hypothetical deinterlace plugin doubles the frame rate of the output clip, it will be doubling the number of frames in that clip. The timing diagram below should help, showing how our fielded input has been turned into twice the number of frames on output.
FIELDED SOURCE 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5 .... DEINTELACED OUTPUT 0 1 2 3 4 5 6 7 8 9
The maping of the number of output frames is...
nFrames' = nFrames * FPS' / FPS
All clips have a premultiplication state (see http://www.teamten.com/lawrence/graphics/premultiplication/ for a nice explanation). An effect cannot map the premultiplication state of the input clips, but it can specify the premultiplication state of the output clip.
The output's default premultiplication state is...
Actions passed to an OFX Image Effect's plug-in main entry point are from two categories...
ofxCore.h
ofxImageEffect.h
For generic actions, the handle
passed to to main entry point will depend on the API being impemented, for all generic actions passed to an OFX Image Effect plug-in, it will nearly alway be an OfxImageEffectHandle
.
Because interacts are a special case, they are dealt with in a separate chapter, this chapter will deal with actions issued to an image effect plug-ins main entry point.
#include "ofxCore.h" #define kOfxActionLoad "OfxActionLoad"
The handle
, inArgs
and outArgs
arguments to the main entry are redundant and should be set to NULL.
kOfxActionLoad
is the first action passed to a plug-in after the binary containing the plug-in has been loaded. It is there to allow a plug-in to create any global data structures it may need and is also when the plug-in should fetch suites from the host.
The plugin's OfxPlugin::setHost function has been called
This action will not be called again while the binary containing the plug-in remains loaded.
#include "ofxCore.h" #define kOfxActionUnload "OfxActionUnload"
kOfxActionUnload is the last action passed to the plug-in before the binary containing the plug-in is unloaded. It is there to allow a plug-in to destroy any global data structures it may have created.
The handle
, inArgs
and outArgs
arguments to the main entry are redundant and should be set to NULL.
No other actions will be called.
#include "ofxCore.h" #define kOfxActionDescribe "OfxActionDescribe"
handle
handle to the plug-in descriptor, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
The kOfxActionDescribe is the second action passed to a plug-in. It is where a plugin defines how it behaves and the resources it needs to function.
Note that the handle passed in acts as a descriptor for, rather than an instance of the plugin. The handle is global and unique. The plug-in is at liberty to cache the handle away for future reference until the plug-in is unloaded.
Most importantly, the effect must set what image effect contexts it is capable of working in.
This action must be trapped, it is not optional.
kOfxActionLoad has been called
kOfxImageEffectActionDescribeInContext
will be called once for each context that the host and plug-in mutually support.
#include "ofxCore.h" #define kOfxActionCreateInstance "OfxActionCreateInstance"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
The kOfxActionCreateInstance is the first action passed to a plug-in's instance after its creation. It is there to allow a plugin to create any per-instance data structures it may need.
kOfxActionDestroyInstance
action is passed to the plug-in with the same instance handle
#include "ofxCore.h" #define kOfxActionDestroyInstance "OfxActionDestroyInstance"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
This action is the last passed to a plug-in's instance before its destruction. It is there to allow a plugin to destroy any per-instance data structures it may have created.
kOfxActionCreateInstance
has been called on the handle,
To some extent, what is returned is moot, a bit like throwing an exception in a C++ destructor, so the host should continue destruction of the instance regardless. However...
#include "ofxCore.h" #define kOfxActionBeginInstanceChanged "OfxActionBeginInstanceChanged" #define kOfxActionEndInstanceChanged "OfxActionEndInstanceChanged"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
has the following properties...
outArgs
is redundant and is set to NULL.
kOfxActionBeginInstanceChanged
and kOfxActionEndInstanceChanged
are used to bracket all kOfxActionInstanceChanged
actions, whether a single change or multiple changes.
Some changes to a plugin instance can be grouped logically (eg: a 'reset all' button resetting all the instance's parameters), the begin/end instance changed actions allow a plugin to respond appropriately to a large set of changes.
For example, a plugin that maintains a complex internal state can delay any changes to that state until all parameter changes have completed.
For kOfxActionBeginInstanceChanged,
For kOfxActionEndInstanceChanged,
For kOfxActionBeginInstanceChanged,
#include "ofxCore.h" #define kOfxActionInstanceChanged "OfxActionInstanceChanged"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
has the following properties...
outArgs
is redundant and is set to NULL.
This action signals that something has changed in a plugin's instance, either by user action, the host or the plugin itself. All change actions are bracketed by a pair of kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged actions. The inArgs
property set is used to determine what was the thing inside the instance that was changed.
#include "ofxCore.h" #define kOfxActionPurgeCaches "OfxActionPurgeCaches"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
The kOfxActionPurgeCaches is an action that may be passed to a plug-in instance from time to time in low memory situations. Instances recieving this action should destroy any data structures they may have and release the associated memory, they can later reconstruct this from the effect's parameter set and associated information.
For Image Effects, it is generally a bad idea to call this after each render, but rather it should be called after kOfxImageEffectActionEndSequenceRender
. Some effects, typically those flagged with the kOfxImageEffectInstancePropSequentialRender property, may need to cache information from previously rendered frames to function correctly, or have data structures that are expensive to reconstruct at each frame (eg: a particle system). Ideally, such effect should free such structures during the kOfxImageEffectActionEndSequenceRender
action.
#include "ofxCore.h" #define kOfxActionSyncPrivateData "OfxActionSyncPrivateData"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
This action is called when a plugin should synchronise any private data structures to its parameter set. This generally occurs when an effect is about to be saved or copied, but it could occur in other situations as well.
#include "ofxCore.h" #define kOfxActionBeginInstanceEdit "OfxActionBeginInstanceEdit"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
This is called when an instance is first actively edited by a user, ie: and interface is open and parameter values and input clips can be modified. It is there so that effects can create private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously.
#include "ofxCore.h" #define kOfxActionEndInstanceEdit "OfxActionEndInstanceEdit"
handle
handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
This is called when the last user interface on an instance closed. It is there so that effects can destroy private user interface structures when necassary. Note that some hosts can have multiple editors open on the same effect instance simulateously, this will only be called when the last of those editors are closed.
#include "ofxImageEffect.h" #define kOfxImageEffectActionDescribeInContext "OfxImageEffectActionDescribeInContext"
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.
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionGetRegionOfDefinition "OfxImageEffectActionGetRegionOfDefinition"
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.
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.
outArgs
property set
If the effect did not trap this, it means the host should use the default RoD instead, which depends on the context. This is...
#include "ofxImageEffect.h" #define kOfxImageEffectActionGetRegionsOfInterest "OfxImageEffectActionGetRegionsOfInterest"
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 example "OfxImageClipPropRoI_Source". These are initialised to the default RoI.
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. Form more details see Image Effect Architectures.
outArgs
property set
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionGetFramesNeeded "OfxImageEffectActionGetFramesNeeded"
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 inputoutArgs
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.
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.
outArgs
property set
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionIsIdentity "OfxImageEffectActionIsIdentity"
handle
handle to the instance, cast to an OfxImageEffectHandle
,inArgs
has the following properties...
kOfxPropTime
- the time at which to test for identitykOfxImageEffectPropFieldToRender
- the field to test for identitykOfxImageEffectPropRenderWindow
- the window (in \ref PixelCoordinates) to test for identity underkOfxImageEffectPropRenderScale
- the scale factor being applied to the images being renderredoutArgs
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 stringkOfxPropTime
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
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.
outArgs
indicate what frame from which clip to use instead
The default action is to call the render action on the effect.
#include "ofxImageEffect.h" #define kOfxImageEffectActionRender "OfxImageEffectActionRender"
handle
handle to the instance, cast to an OfxImageEffectHandle
,inArgs
has the following properties...
kOfxPropTime
- the time at which to test for identitykOfxImageEffectPropFieldToRender
- the field to test for identitykOfxImageEffectPropRenderWindow
- the window (in \ref PixelCoordinates) to test for identity underkOfxImageEffectPropRenderScale
- the scale factor being applied to the images being renderredkOfxImageEffectPropSequentialRenderStatus
- whether the effect is currently being rendered in strict frame order on a single instancekOfxImageEffectPropInteractiveRenderStatus
- if the render is in response to a user modifying the effect in an interactive sessionkOfxImageEffectPropRenderQualityDraft
- if the render should be done in draft mode (e.g. for faster scrubbing)outArgs
is redundant and should be set to NULL.
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionBeginSequenceRender "OfxImageEffectActionBeginSequenceRender"
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 callkOfxImageEffectPropSequentialRenderStatus
- whether the effect is currently being rendered in strict frame order on a single instancekOfxImageEffectPropInteractiveRenderStatus
- if the render is in response to a user modifying the effect in an interactive sessionoutArgs
is redundant and is set to NULL.
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionEndSequenceRender "OfxImageEffectActionEndSequenceRender"
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 callkOfxImageEffectPropSequentialRenderStatus
- whether the effect is currently being rendered in strict frame order on a single instancekOfxImageEffectPropInteractiveRenderStatus
- if the render is in response to a user modifying the effect in an interactive sessionoutArgs
is redundant and is set to NULL.
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.
#include "ofxImageEffect.h" #define kOfxImageEffectActionGetClipPreferences "OfxImageEffectActionGetClipPreferences"
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...
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.
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.
outArgs
was changed from its default value
#include "ofxImageEffect.h" #define kOfxImageEffectActionGetTimeDomain "OfxImageEffectActionGetTimeDomain"
handle
handle to the instance, cast to an OfxImageEffectHandle
,inArgs
is redundant and is nulloutArgs
has the following property
kOfxImageEffectPropFrameRange
- the frame range an effect can produce images for
This action allows a host to ask an effect what range of frames it can produce images over. Only effects instantiated in the General Contextcan have this called on them. In all other the host is in strict control over the temporal duration of the effect.
outArgs
property set
The default is,
This chapter describes the actions that can be issued to an interact's main entry point. Interact actions are also generic in character, they could be issued to other plug-in types rather than just Image Effects, however they are not issued directly to an effect's main entry point, they are rather issued to separate entry points which exist on specific 'interact' objects that a plugin may create.
For nearly all the actions the handle
passed to to main entry point for an interact will be either NULL, or a value
that should be cast to an OfxInteractHandle
.
#include "ofxCore.h" #define kOfxActionDescribe "OfxActionDescribe"
handle
handle to the interact descriptor, cast to an OfxInteractHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
The kOfxActionDescribe is the first action passed to an interact. It is where an interact defines how it behaves and the resources it needs to function.
Note that the handle passed in acts as a descriptor for, rather than an instance of the interact.
The plugin has been loaded and the effect described.
kOfxStatOK
, the action was trapped and all was wellkOfxStatErrMemory
, in which case describe may be called again after a memory purgekOfxStatFailed
, something was wrong, the host should ignore the interactkOfxStatErrFatal
If not trapped, the default action is for the host to carry on as normal
#include "ofxCore.h" #define kOfxActionCreateInstance "OfxActionCreateInstance"
handle
handle to the interact instance, cast to an OfxInteractHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
The kOfxActionCreateInstance
is the first action passed to an interact instance after its creation.
It is there to allow a plugin to create any per-instance data structures it may need.
kOfxActionDescribe
has been called on this interact
kOfxActionDestroyInstance
action is passed to the plug-in with the same instance handle
kOfxStatOK
, the action was trapped and all was wellkOfxStatReplyDefault
, the action was ignored, but all was well anywaykOfxStatErrFatal
kOfxStatErrMemory
, in which case this may be called again after a memory purgekOfxStatFailed
, in which case the host should ignore this interact
#include "ofxCore.h" #define kOfxActionDestroyInstance "OfxActionDestroyInstance"
handle
handle to the interact instance, cast to an OfxInteractHandle
inArgs
is redundant and is set to NULL,outArgs
is redundant and is set to NULL.
This action is the last passed to an interact's instance before its destruction. It is there to allow a plugin to destroy any per-instance data structures it may have created.
kOfxActionCreateInstance
has been called on the handle,
To some extent, what is returned is moot, a bit like throwing an exception in a C++ destructor, so the host should continue destruction of the instance regardless. However...
kOfxStatOK
, the action was trapped and all was well,kOfxStatErrFatal
,kOfxStatFailed
, something went wrong, but no error code appropriate.
#include "ofxCore.h" #define kOfxInteractActionDraw "OfxInteractActionDraw"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixelskOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued to an interact whenever the host needs the plugin to redraw the given interact. The interact should issue any openGL calls it needs at this point.
Note that the interact may (in the case of custom parameter GUIS) or may not (in the case of image effect overlays) be required to swap buffers, that is up to the kind of interact.
kOfxActionCreateInstance
has been called on the instance handle,
kOfxStatOK
, the action was trapped and all was wellkOfxStatReplyDefault
, the action was ignoredkOfxStatErrFatal
, kOfxStatFailed
, something went wrong, the host should ignore this interact in future
#include "ofxCore.h" #define kOfxInteractActionPenMotion "OfxInteractActionPenMotion"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixelskOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedkOfxInteractPropPenPosition
- postion of the pen in,kOfxInteractPropPenViewportPosition
- postion of the pen in,kOfxInteractPropPenPressure
- the pressure of the pen,outArgs
is redundant and is set to NULL.
This action is issued whenever the pen moves an the interact's has focus. It should be issued whether the pen is currently up or down.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same view.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionPenDown "OfxInteractActionPenDown"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixelskOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedkOfxInteractPropPenPosition
- postion of the pen in,kOfxInteractPropPenViewportPosition
- postion of the pen in,kOfxInteractPropPenPressure
- the pressure of the pen,outArgs
is redundant and is set to NULL.
This action is issued when a pen transitions for the 'up' to the 'down' state.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same view.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionPenUp "OfxInteractActionPenUp"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixelskOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedkOfxInteractPropPenPosition
- postion of the pen in,kOfxInteractPropPenViewportPosition
- postion of the pen in,kOfxInteractPropPenPressure
- the pressure of the pen,outArgs
is redundant and is set to NULL.
This action is issued when a pen transitions for the 'down' to the 'up' state.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same view.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionKeyDown "OfxInteractActionKeyDown"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxPropKeySym
- single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)kOfxPropKeyString
- UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""kOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued when a key on the keyboard is depressed.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same focus.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionKeyUp "OfxInteractActionKeyUp"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxPropKeySym
- single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)kOfxPropKeyString
- UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""kOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued when a key on the keyboard is released.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same focus.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionKeyRepeat "OfxInteractActionKeyRepeat"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact has been,kOfxPropKeySym
- single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)kOfxPropKeyString
- UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""kOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued when a key on the keyboard is held down an a key repeat is issued.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,kOfxInteractActionGainFocus
called on it
kOfxStatOK
, the host should not pass
the pen motion to any other interactive object it may own that shares the same focus.
kOfxStatOK
, the action was trapped and the host should not pass the event to other objects it may ownkOfxStatReplyDefault
, the action was not trapped and the host can deal with it if it wants
#include "ofxCore.h" #define kOfxInteractActionGainFocus "OfxInteractActionGainFocus"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact is being used on,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixels,kOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued when an interact gains input focus.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,
kOfxStatOK
, the action was trapped kOfxStatReplyDefault
, the action was not trapped
#include "ofxCore.h" #define kOfxInteractActionLoseFocus "OfxInteractActionLoseFocus"
handle
handle to an interact instance, cast to an OfxInteractHandle
inArgs
has the following properties on an image effect plugin,
kOfxPropEffectInstance
- a handle to the effect for which the interact is being used on,kOfxInteractPropPixelScale
- the scale factor to convert cannonical pixels to screen pixels,kOfxInteractPropBackgroundColour
- the background colour of the application behind the current viewkOfxPropTime
- the effect time at which changed occuredkOfxImageEffectPropRenderScale
- the render scale applied to any image fetchedoutArgs
is redundant and is set to NULL.
This action is issued when an interact loses input focus.
No openGL calls should be issued by the plug-in during this action.
kOfxActionCreateInstance
has been called on the instance handle,
kOfxStatOK
, the action was trapped kOfxStatReplyDefault
, the action was not trapped
The files ofxCore.h
and ofxProperty.h
contain the basic definitions for the property suite.
The property suite is the most basic and important suite in OFX, it is used to get and set the values of various objects defined by other suites.
A property is a named value of a specific data type, such values can be multi-dimensional, but is typically of one dimension. The name
is a 'C' string literal, typically #defined in one of the various OFX header files. For example, the property labeled by the string literal "OfxPropName"
is a 'C' string which holds the name of some object.
Properties are not accessed in isolation, but are grouped and accessed through a property set handle. The number and types of properties on a specific property set handle are currently strictly defined by the API that the properties are being used for. There is no scope to add new properties.
There is a naming convention for property labels and the macros #defined to them. The scheme is,
"OfxProp"
+ name of the property, e.g. "OfxPropTime"."Ofx"
+ object name + "Prop"
+ name of the property, e.g. "OfxParamPropAnimates"."k"
prepended to the name. For example, #define kOfxPropLabel "OfxPropLabel"
OfxPropertySetHandle — Blind data type used to hold sets of properties
#include "ofxCore.h" typedef struct OfxPropertySetStruct *OfxPropertySetHandle;
Properties are not accessed on their own, nor do they exist on their own. They are grouped and manipulated via an OfxPropertySetHandle.
Any object that has properties can be made to return it's property set handle via some call on the relevant suite. Individual properties are then manipulated with the property suite through that handle.
OfxPropertySuiteV1
— The OFX suite used to access properties on OFX objects.
#include "ofxProperty.h" typedef struct OfxPropertySuiteV1 { OfxStatus (*propSetPointer)(OfxPropertySetHandle properties, const char *property, int index, void *value); OfxStatus (*propSetString) (OfxPropertySetHandle properties, const char *property, int index, const char *value); OfxStatus (*propSetDouble) (OfxPropertySetHandle properties, const char *property, int index, double value); OfxStatus (*propSetInt) (OfxPropertySetHandle properties, const char *property, int index, int value); OfxStatus (*propSetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void *const*value); OfxStatus (*propSetStringN) (OfxPropertySetHandle properties, const char *property, int count, const char *const*value); OfxStatus (*propSetDoubleN) (OfxPropertySetHandle properties, const char *property, int count, const double *value); OfxStatus (*propSetIntN) (OfxPropertySetHandle properties, const char *property, int count, const int *value); OfxStatus (*propGetPointer)(OfxPropertySetHandle properties, const char *property, int index, void **value); OfxStatus (*propGetString) (OfxPropertySetHandle properties, const char *property, int index, char **value); OfxStatus (*propGetDouble) (OfxPropertySetHandle properties, const char *property, int index, double *value); OfxStatus (*propGetInt) (OfxPropertySetHandle properties, const char *property, int index, int *value); OfxStatus (*propGetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void **value); OfxStatus (*propGetStringN) (OfxPropertySetHandle properties, const char *property, int count, char **value); OfxStatus (*propGetDoubleN) (OfxPropertySetHandle properties, const char *property, int count, double *value); OfxStatus (*propGetIntN) (OfxPropertySetHandle properties, const char *property, int count, int *value); OfxStatus (*propReset) (OfxPropertySetHandle properties, const char *property); OfxStatus (*propGetDimension) (OfxPropertySetHandle properties, const char *property, int *count); } OfxPropertySuiteV1;
OfxPropertySuiteV1::propSetPointer
— Set a single value in a pointer property
#include "ofxProperty.h"
OfxStatus(*propSetPointer)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
void *value) ; |
OfxPropertySuiteV1::propSetString
— Set a single value in a string property
#include "ofxProperty.h"
OfxStatus(*propSetString)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
const char *value) ; |
OfxPropertySuiteV1::propSetDouble
— Set a single value in a double property
#include "ofxProperty.h"
OfxStatus(*propSetDouble)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
doublevalue) ; |
OfxPropertySuiteV1::propSetInt
— Set a single value in an int property
#include "ofxProperty.h"
OfxStatus(*propSetInt)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
intvalue) ; |
OfxPropertySuiteV1::propSetPointerN
— Set multiple values of the pointer property
#include "ofxProperty.h"
OfxStatus(*propSetPointerN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
void *const*value) ; |
OfxPropertySuiteV1::propSetStringN
— Set multiple values of a string property
#include "ofxProperty.h"
OfxStatus(*propSetStringN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
const char *const*value) ; |
OfxPropertySuiteV1::propSetDoubleN
— Set multiple values of a double property
#include "ofxProperty.h"
OfxStatus(*propSetDoubleN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
const double *value) ; |
OfxPropertySuiteV1::propSetIntN
— Set multiple values of an int property
#include "ofxProperty.h"
OfxStatus(*propSetIntN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
const int *value) ; |
OfxPropertySuiteV1::propGetPointer
— Get a single value from a pointer property
#include "ofxProperty.h"
OfxStatus(*propGetPointer)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
void **value) ; |
OfxPropertySuiteV1::propGetString
— Get a single value of a string property
#include "ofxProperty.h"
OfxStatus(*propGetString)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
char **value) ; |
OfxPropertySuiteV1::propGetDouble
— Get a single value of a double property
#include "ofxProperty.h"
OfxStatus(*propGetDouble)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
double *value) ; |
OfxPropertySuiteV1::propGetInt
— Get a single value of an int property
#include "ofxProperty.h"
OfxStatus(*propGetInt)( | OfxPropertySetHandleproperties, |
const char *property, | |
intindex, | |
int *value) ; |
OfxPropertySuiteV1::propGetPointerN
— Get multiple values of a pointer property
#include "ofxProperty.h"
OfxStatus(*propGetPointerN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
void **value) ; |
OfxPropertySuiteV1::propGetStringN
— Get multiple values of a string property
#include "ofxProperty.h"
OfxStatus(*propGetStringN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
char **value) ; |
OfxPropertySuiteV1::propGetDoubleN
— Get multiple values of a double property
#include "ofxProperty.h"
OfxStatus(*propGetDoubleN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
double *value) ; |
OfxPropertySuiteV1::propGetIntN
— Get multiple values of an int property
#include "ofxProperty.h"
OfxStatus(*propGetIntN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
int *value) ; |
OfxPropertySuiteV1::propReset
— Resets all dimensions of a property to its default value
#include "ofxProperty.h"
OfxStatus(*propReset)( | OfxPropertySetHandleproperties, |
const char *property) ; |
OfxPropertySuiteV1::propGetDimension
— Gets the dimension of the property
#include "ofxProperty.h"
OfxStatus(*propGetDimension)( | OfxPropertySetHandleproperties, |
const char *property, | |
int *count) ; |
OfxImageEffectSuiteV1
— The OFX suite for image effects
#include "ofxImageEffect.h" typedef struct OfxImageEffectSuiteV1 { OfxStatus (*getPropertySet)(OfxImageEffectHandle imageEffect, OfxPropertySetHandle *propHandle); OfxStatus (*getParamSet)(OfxImageEffectHandle imageEffect, OfxParamSetHandle *paramSet); OfxStatus (*clipDefine)(OfxImageEffectHandle imageEffect, const char *name, OfxPropertySetHandle *propertySet); OfxStatus (*clipGetHandle)(OfxImageEffectHandle imageEffect, const char *name, OfxImageClipHandle *clip, OfxPropertySetHandle *propertySet); OfxStatus (*clipGetPropertySet)(OfxImageClipHandle clip, OfxPropertySetHandle *propHandle); OfxStatus (*clipGetImage)(OfxImageClipHandle clip, OfxTime time, const OfxRectD *region, OfxPropertySetHandle *imageHandle); OfxStatus (*clipReleaseImage)(OfxPropertySetHandle imageHandle); OfxStatus (*clipGetRegionOfDefinition)(OfxImageClipHandle clip, OfxTime time, OfxRectD *bounds); int (*abort)(OfxImageEffectHandle imageEffect); OfxStatus (*imageMemoryAlloc)(OfxImageEffectHandle instanceHandle, size_t nBytes, OfxImageMemoryHandle *memoryHandle); OfxStatus (*imageMemoryFree)(OfxImageMemoryHandle memoryHandle); OfxStatus (*imageMemoryLock)(OfxImageMemoryHandle memoryHandle, void **returnedPtr); OfxStatus (*imageMemoryUnlock)(OfxImageMemoryHandle memoryHandle); } OfxImageEffectSuiteV1;
OfxImageEffectSuiteV1::getPropertySet
— Retrieves the property set for the given image effect
#include "ofxImageEffect.h"
OfxStatus(*getPropertySet)( | OfxImageEffectHandleimageEffect, |
OfxPropertySetHandle *propHandle) ; |
kOfxStatOK
- the property set was found and returnedkOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxImageEffectSuiteV1::getParamSet
— Retrieves the parameter set for the given image effect
#include "ofxImageEffect.h"
OfxStatus(*getParamSet)( | OfxImageEffectHandleimageEffect, |
OfxParamSetHandle *paramSet) ; |
kOfxStatOK
- the property set was found and returnedkOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxImageEffectSuiteV1::clipDefine
— Define a clip to the effect.
#include "ofxImageEffect.h"
OfxStatus(*clipDefine)( | OfxImageEffectHandleimageEffect, |
const char *name, | |
OfxPropertySetHandle *propertySet) ; |
OfxImageEffectSuiteV1::clipGetHandle
— Get the propery handle of the named input clip in the given instance
#include "ofxImageEffect.h"
OfxStatus(*clipGetHandle)( | OfxImageEffectHandleimageEffect, |
const char *name, | |
OfxImageClipHandle *clip, | |
OfxPropertySetHandle *propertySet) ; |
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 m 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
\post
OfxImageEffectSuiteV1::clipGetPropertySet
— Retrieves the property set for a given clip
#include "ofxImageEffect.h"
OfxStatus(*clipGetPropertySet)( | OfxImageClipHandleclip, |
OfxPropertySetHandle *propHandle) ; |
The property handle is valid for the lifetime of the clip, which is generally the lifetime of the instance.
kOfxStatOK
- the property set was found and returnedkOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxImageEffectSuiteV1::clipGetImage
— Get a handle for an image in a clip at the indicated time and indicated region
#include "ofxImageEffect.h"
OfxStatus(*clipGetImage)( | OfxImageClipHandleclip, |
OfxTime time, | |
const OfxRectD *region, | |
OfxPropertySetHandle *imageHandle) ; |
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 m at m 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
\post
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 pluginshould 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.
OfxImageEffectSuiteV1::clipReleaseImage
— Releases the image handle previously returned by clipGetImage
#include "ofxImageEffect.h"
OfxStatus(*clipReleaseImage)( | OfxPropertySetHandleimageHandle) ; |
\pre
\post
kOfxStatOK
- the image was successfully fetched and returned in the handle,kOfxStatErrBadHandle
- the image handle was invalid,
OfxImageEffectSuiteV1::clipGetRegionOfDefinition
— Returns the spatial region of definition of the clip at the given time
#include "ofxImageEffect.h"
OfxStatus(*clipGetRegionOfDefinition)( | OfxImageClipHandleclip, |
OfxTimetime, | |
OfxRectD *bounds) ; |
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 m at m 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
\post
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 pluginshould 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.
OfxImageEffectSuiteV1::abort
— Returns whether to abort processing or not.
#include "ofxImageEffect.h"
int(*abort)( | OfxImageEffectHandleimageEffect) ; |
OfxImageEffectSuiteV1::imageMemoryAlloc
— Allocate memory from the host's image memory pool
#include "ofxImageEffect.h"
OfxStatus(*imageMemoryAlloc)( | OfxImageEffectHandleinstanceHandle, |
size_tnBytes, | |
OfxImageMemoryHandle *memoryHandle) ; |
Memory handles allocated by this should be freed by OfxImageEffectSuiteV1::imageMemoryFree
.
To access the memory behind the handle you need to call OfxImageEffectSuiteV1::imageMemoryLock
.
OfxImageEffectSuiteV1::imageMemoryFree
— Frees a memory handle and associated memory.
#include "ofxImageEffect.h"
OfxStatus(*imageMemoryFree)( | OfxImageMemoryHandlememoryHandle) ; |
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.
OfxImageEffectSuiteV1::imageMemoryAlloc
OfxImageEffectSuiteV1::imageMemoryLock
— Lock the memory associated with a memory handle and make it available for use.
#include "ofxImageEffect.h"
OfxStatus(*imageMemoryLock)( | OfxImageMemoryHandlememoryHandle, |
void **returnedPtr) ; |
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.
OfxImageEffectSuiteV1::imageMemoryAlloc
, null is placed in returnedPtr
OfxImageEffectSuiteV1::imageMemoryUnlock
— Unlock allocated image data
#include "ofxImageEffect.h"
OfxStatus(*imageMemoryUnlock)( | OfxImageMemoryHandlememoryHandle) ; |
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.
OfxImageEffectSuiteV1::imageMemoryAlloc
, null is placed in returnedPtr
OfxProgressSuiteV1
— A suite that provides progress feedback from a plugin to an application
#include "ofxProgress.h" typedef struct OfxProgressSuiteV1 { OfxStatus (*progressStart)(void *effectInstance, const char *label); OfxStatus (*progressUpdate)(void *effectInstance, double progress); OfxStatus (*progressEnd)(void *effectInstance); } OfxProgressSuiteV1 ;
A plugin instance can initiate, update and close a progress indicator with this suite.
This is an optional suite in the Image Effect API.
API V1.4: Amends the documentation of progress suite V1 so that it is expected that it can be raised in a modal manner and have a "cancel" button when invoked in instanceChanged. Plugins that perform analysis post an appropriate message, raise the progress monitor in a modal manner and should poll to see if processing has been aborted. Any cancellation should be handled gracefully by the plugin (eg: reset analysis parameters to default values), clear allocated memory...
Many hosts already operate as described above. kOfxStatReplyNo should be returned to the plugin during progressUpdate when the user presses cancel.
Suite V2: Adds an ID that can be looked up for internationalisation and so on. When a new version is introduced, because plug-ins need to support old versions, and plug-in's new releases are not necessary in synch with hosts (or users don't immediately update), best practice is to support the 2 suite versions. That is, the plugin should check if V2 exists; if not then check if V1 exists. This way a graceful transition is guaranteed. So plugin should fetchSuite passing 2, (OfxProgressSuiteV2) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); and if no success pass (OfxProgressSuiteV1) fetchSuite(mHost->mHost->host, kOfxProgressSuite,1);
OfxProgressSuiteV1::progressStart
— Initiate a progress bar display.
#include "ofxProgress.h"
OfxStatus(*progressStart)( | void *effectInstance, |
const char *label) ; |
Call this to initiate the display of a progress bar.
\pre - There is no currently ongoing progress display for this instance.
\returns
kOfxStatOK
- the handle is now valid for usekOfxStatFailed
- the progress object failed for some reasonkOfxStatErrBadHandle
- effectInstance was invalid
OfxProgressSuiteV1::progressUpdate
— Indicate how much of the processing task has been completed and reports on any abort status.
#include "ofxProgress.h"
OfxStatus(*progressUpdate)( | void *effectInstance, |
doubleprogress) ; |
\returns
kOfxStatOK
- the progress object was successfully updated and the task should continuekOfxStatReplyNo
- the progress object was successfully updated and the task should abortkOfxStatErrBadHandle
- the progress handle was invalid,
OfxProgressSuiteV1::progressEnd
— Signal that we are finished with the progress meter.
#include "ofxProgress.h"
OfxStatus(*progressEnd)( | void *effectInstance) ; |
Call this when you are done with the progress meter and no longer need it displayed.
\post - you can no longer call progressUpdate on the instance
\returns
kOfxStatOK
- the progress object was successfully closedkOfxStatErrBadHandle
- the progress handle was invalid,
OfxTimeLineSuiteV1
— Suite to control timelines
#include "ofxTimeLine.h" typedef struct OfxTimeLineSuiteV1 { OfxStatus (*getTime)(void *instance, double *time); OfxStatus (*gotoTime)(void *instance, double time); OfxStatus (*getTimeBounds)(void *instance, double *firstTime, double *lastTime); } OfxTimeLineSuiteV1;
OfxTimeLineSuiteV1::getTime
— Get the time value of the timeline that is controlling to the indicated effect.
#include "ofxTimeLine.h"
OfxStatus(*getTime)( | void *instance, |
double *time) ; |
This function returns the current time value of the timeline associated with the effect instance.
kOfxStatOK
- the time enquiry was sucessfulkOfxStatFailed
- the enquiry failed for some host specific reasonkOfxStatErrBadHandle
- the effect handle was invalid
OfxTimeLineSuiteV1::gotoTime
— Move the timeline control to the indicated time.
#include "ofxTimeLine.h"
OfxStatus(*gotoTime)( | void *instance, |
doubletime) ; |
This function moves the timeline to the indicated frame and returns. Any side effects of the timeline change are also triggered and completed before this returns (for example instance changed actions and renders if the output of the effect is being viewed).
kOfxStatOK
- the time was changed sucessfully, will all side effects if the change completedkOfxStatFailed
- the change failed for some host specific reasonkOfxStatErrBadHandle
- the effect handle was invalidkOfxStatErrValue
- the time was an illegal value
OfxTimeLineSuiteV1::getTimeBounds
— Get the current bounds on a timeline
#include "ofxTimeLine.h"
OfxStatus(*getTimeBounds)( | void *instance, |
double *firstTime, | |
double *lastTime) ; |
kOfxStatOK
- the time enquiry was sucessfulkOfxStatFailed
- the enquiry failed for some host specific reasonkOfxStatErrBadHandle
- the effect handle was invalid
OfxParameterSuiteV1
— The OFX suite used to define and manipulate user visible parameters
#include "ofxParam.h" typedef struct OfxParameterSuiteV1 { OfxStatus (*paramDefine)(OfxParamSetHandle paramSet, const char *paramType, const char *name, OfxPropertySetHandle *propertySet); OfxStatus (*paramGetHandle)(OfxParamSetHandle paramSet, const char *name, OfxParamHandle *param, OfxPropertySetHandle *propertySet); OfxStatus (*paramSetGetPropertySet)(OfxParamSetHandle paramSet, OfxPropertySetHandle *propHandle); OfxStatus (*paramGetPropertySet)(OfxParamHandle param, OfxPropertySetHandle *propHandle); OfxStatus (*paramGetValue)(OfxParamHandle paramHandle, ...); OfxStatus (*paramGetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...); OfxStatus (*paramGetDerivative)(OfxParamHandle paramHandle, OfxTime time, ...); OfxStatus (*paramGetIntegral)(OfxParamHandle paramHandle, OfxTime time1, OfxTime time2, ...); OfxStatus (*paramSetValue)(OfxParamHandle paramHandle, ...); OfxStatus (*paramSetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, // time in frames ...); OfxStatus (*paramGetNumKeys)(OfxParamHandle paramHandle, unsigned int *numberOfKeys); OfxStatus (*paramGetKeyTime)(OfxParamHandle paramHandle, unsigned int nthKey, OfxTime *time); OfxStatus (*paramGetKeyIndex)(OfxParamHandle paramHandle, OfxTime time, int direction, int *index); OfxStatus (*paramDeleteKey)(OfxParamHandle paramHandle, OfxTime time); OfxStatus (*paramDeleteAllKeys)(OfxParamHandle paramHandle); OfxStatus (*paramCopy)(OfxParamHandle paramTo, OfxParamHandle paramFrom, OfxTime dstOffset, const OfxRangeD *frameRange); OfxStatus (*paramEditBegin)(OfxParamSetHandle paramSet, const char *name); OfxStatus (*paramEditEnd)(OfxParamSetHandle paramSet); } OfxParameterSuiteV1;
OfxParameterSuiteV1::paramDefine
— Defines a new parameter of the given type in a describe action
#include "ofxParam.h"
OfxStatus(*paramDefine)( | OfxParamSetHandleparamSet, |
const char *paramType, | |
const char *name, | |
OfxPropertySetHandle *propertySet) ; |
This function defines a parameter in a parameter set and returns a property set which is used to describe that parameter.
This function does not actually create a parameter, it only says that one should exist in any subsequent instances. To fetch an parameter instance paramGetHandle must be called on an instance.
This function can always be called in one of a plug-in's "describe" functions which defines the parameter sets common to all instances of a plugin.
kOfxStatOK
- the parameter was created correctlykOfxStatErrBadHandle
- if the plugin handle was invalidkOfxStatErrExists
- if a parameter of that name exists already in this pluginkOfxStatErrUnknown
- if the type is unknownkOfxStatErrUnsupported
- if the type is known but unsupported
OfxParameterSuiteV1::paramGetHandle
— Retrieves the handle for a parameter in a given parameter set
#include "ofxParam.h"
OfxStatus(*paramGetHandle)( | OfxParamSetHandleparamSet, |
const char *name, | |
OfxParamHandle *param, | |
OfxPropertySetHandle *propertySet) ; |
Parameter handles retrieved from an instance are always distinct in each instance. The paramter handle is valid for the life-time of the instance. Parameter handles in instances are distinct from paramter handles in plugins. You cannot call this in a plugin's describe function, as it needs an instance to work on.
kOfxStatOK
- the parameter was found and returnedkOfxStatErrBadHandle
- if the plugin handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParameterSuiteV1::paramSetGetPropertySet
— Retrieves the property set handle for the given parameter set
#include "ofxParam.h"
OfxStatus(*paramSetGetPropertySet)( | OfxParamSetHandleparamSet, |
OfxPropertySetHandle *propHandle) ; |
\note The property handle belonging to a parameter set is the same as the property handle belonging to the plugin instance.
kOfxStatOK
- the property set was found and returnedkOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParameterSuiteV1::paramGetPropertySet
— Retrieves the property set handle for the given parameter
#include "ofxParam.h"
OfxStatus(*paramGetPropertySet)( | OfxParamHandleparam, |
OfxPropertySetHandle *propHandle) ; |
The property handle is valid for the lifetime of the parameter, which is the lifetime of the instance that owns the parameter
kOfxStatOK
- the property set was found and returnedkOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParameterSuiteV1::paramGetValue
— Gets the current value of a parameter,
#include "ofxParam.h"
OfxStatus(*paramGetValue)( | OfxParamHandle paramHandle, |
...) ; |
This gets the current value of a parameter. The varargs ... argument needs to be pointer to C variables of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example...
OfxParamHandle myDoubleParam, myColourParam; ofxHost->paramGetHandle(instance, "myDoubleParam", &myDoubleParam); double myDoubleValue; ofxHost->paramGetValue(myDoubleParam, &myDoubleValue); ofxHost->paramGetHandle(instance, "myColourParam", &myColourParam); double myR, myG, myB; ofxHost->paramGetValue(myColourParam, &myR, &myG, &myB);
\note paramGetValue should only be called from within a kOfxActionInstanceChanged
or interact action and never from the render actions (which should always use paramGetValueAtTime).
OfxParameterSuiteV1::paramGetValueAtTime
— Gets the value of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramGetValueAtTime)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
This gets the current value of a parameter. The varargs needs to be pointer to C variables
of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue
for notes on
the varags list
OfxParameterSuiteV1::paramGetDerivative
— Gets the derivative of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramGetDerivative)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
This gets the derivative of the parameter at the indicated time.
The varargs needs to be pointer to C variables
of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue
for notes on
the varags list.
Only double and colour params can have their derivatives found.
OfxParameterSuiteV1::paramGetIntegral
— Gets the integral of a parameter over a specific time range,
#include "ofxParam.h"
OfxStatus(*paramGetIntegral)( | OfxParamHandle paramHandle, |
OfxTimetime1, | |
OfxTimetime2, | |
...) ; |
This gets the integral of the parameter over the specified time range.
The varargs needs to be pointer to C variables
of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue
for notes on
the varags list.
Only double and colour params can be integrated.
OfxParameterSuiteV1::paramSetValue
— Sets the current value of a parameter
#include "ofxParam.h"
OfxStatus(*paramSetValue)( | OfxParamHandle paramHandle, |
...) ; |
This sets the current value of a parameter. The varargs ... argument needs to be values of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example...
ofxHost->paramSetValue(instance, "myDoubleParam", double(10)); ofxHost->paramSetValue(instance, "myColourParam", double(pix.r), double(pix.g), double(pix.b));
\note paramSetValue should only be called from within a kOfxActionInstanceChanged
or interact action.
OfxParameterSuiteV1::paramSetValueAtTime
— Keyframes the value of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramSetValueAtTime)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
This sets a keyframe in the parameter at the indicated time to have the indicated value.
The varargs ... argument needs to be values of the relevant type for this parameter. See the note on
OfxParameterSuiteV1::paramSetValue
for more detail
\note paramSetValueAtTime should only be called from within a kOfxActionInstanceChanged
or interact action.
V1.3: This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
V1.4: This function can be called the kOfxActionInstanceChanged
action
OfxParameterSuiteV1::paramGetNumKeys
— Returns the number of keyframes in the parameter
#include "ofxParam.h"
OfxStatus(*paramGetNumKeys)( | OfxParamHandle paramHandle, |
unsigned int *numberOfKeys) ; |
V1.3: This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
V1.4: This function can be called the kOfxActionInstanceChanged
action
Returns the number of keyframes in the parameter.
OfxParameterSuiteV1::paramGetKeyTime
— Returns the time of the nth key
#include "ofxParam.h"
OfxStatus(*paramGetKeyTime)( | OfxParamHandle paramHandle, |
unsigned intnthKey, | |
OfxTime *time) ; |
kOfxStatOK
- all was OKkOfxStatErrBadHandle
- if the parameter handle was invalidkOfxStatErrBadIndex
- the nthKey does not exist
OfxParameterSuiteV1::paramGetKeyIndex
— Finds the index of a keyframe at/before/after a specified time.
#include "ofxParam.h"
OfxStatus(*paramGetKeyIndex)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
int direction, | |
int *index) ; |
kOfxStatOK
- all was OKkOfxStatFailed
- if the search failed to find a keykOfxStatErrBadHandle
- if the parameter handle was invalid
OfxParameterSuiteV1::paramDeleteKey
— Deletes a keyframe if one exists at the given time.
#include "ofxParam.h"
OfxStatus(*paramDeleteKey)( | OfxParamHandle paramHandle, |
OfxTimetime) ; |
kOfxStatOK
- all was OKkOfxStatErrBadHandle
- if the parameter handle was invalidkOfxStatErrBadIndex
- no key at the given time
OfxParameterSuiteV1::paramDeleteAllKeys
— Deletes all keyframes from a parameter.
#include "ofxParam.h"
OfxStatus(*paramDeleteAllKeys)( | OfxParamHandle paramHandle) ; |
V1.3: This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
V1.4: This function can be called the kOfxActionInstanceChanged
action
OfxParameterSuiteV1::paramCopy
— Copies one parameter to another, including any animation etc...
#include "ofxParam.h"
OfxStatus(*paramCopy)( | OfxParamHandle paramTo, |
OfxParamHandle paramFrom, | |
OfxTimedstOffset, | |
const OfxRangeD *frameRange) ; |
This copies the value of paramFrom to paramTo, including any animation it may have. All the previous values in paramTo will be lost.
To choose all animation in paramFrom set frameRange to [0, 0]
V1.3: This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
V1.4: This function can be called the kOfxActionInstanceChanged
action
\pre
\return
kOfxStatOK
- all was OKkOfxStatErrBadHandle
- if the parameter handle was invalid
OfxParameterSuiteV1::paramEditBegin
— Used to group any parameter changes for undo/redo purposes
#include "ofxParam.h"
OfxStatus(*paramEditBegin)( | OfxParamSetHandleparamSet, |
const char *name) ; |
If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the start of a set of a parameter changes that should be considered part of a single undo/redo block.
\note paramEditBegin should only be called from within a kOfxActionInstanceChanged
or interact action.
See also OfxParameterSuiteV1::paramEditEnd
\return
kOfxStatOK
- all was OKkOfxStatErrBadHandle
- if the instance handle was invalid
OfxParameterSuiteV1::paramEditEnd
— Used to group any parameter changes for undo/redo purposes
#include "ofxParam.h"
OfxStatus(*paramEditEnd)( | OfxParamSetHandleparamSet) ; |
If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the end of a set of parameter changes that should be considerred part of a single undo/redo block
\note paramEditEnd should only be called from within a kOfxActionInstanceChanged
or interact action.
See also OfxParameterSuiteV1::paramEditBegin
OfxCustomParamInterpFuncV1 — Typedef for functions set as the ::kOfxParamPropCustomInterpCallbackV1 on custom params.
#include "ofxParam.h"
typedef OfxStatus(OfxCustomParamInterpFuncV1)( | OfxParamSetHandle instance, |
OfxPropertySetHandle inArgs, | |
OfxPropertySetHandle outArgs) ; |
This function allows custom parameters to animate by performing interpolation between keys.
The plugin needs to parse the two strings encoding keyframes on either side of the time
we need a value for. It should then interpolate a new value for it, encode it into a string and set
the kOfxParamPropCustomValue
property with this on the outArgs handle.
The interp value is a linear interpolation amount, however his may be derived from a cubic (or other) curve.
OfxParametricParameterSuiteV1
— The OFX suite used to define and manipulate 'parametric' parameters.
#include "ofxParametricParam.h" typedef struct OfxParametricParameterSuiteV1 { OfxStatus (*parametricParamGetValue)(OfxParamHandle param, int curveIndex, OfxTime time, double parametricPosition, double *returnValue); OfxStatus (*parametricParamGetNControlPoints)(OfxParamHandle param, int curveIndex, double time, int *returnValue); OfxStatus (*parametricParamGetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double *key, double *value); OfxStatus (*parametricParamSetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double key, double value, bool addAnimationKey); OfxStatus (*parametricParamAddControlPoint)(OfxParamHandle param, int curveIndex, double time, double key, double value, bool addAnimationKey); OfxStatus (*parametricParamDeleteControlPoint)(OfxParamHandle param, int curveIndex, int nthCtl); OfxStatus (*parametricParamDeleteAllControlPoints)(OfxParamHandle param, int curveIndex); } OfxParametricParameterSuiteV1;
This is an optional suite.
Parametric parameters are in effect 'functions' a plug-in can ask a host to arbitrarily evaluate for some value 'x'. A classic use case would be for constructing look-up tables, a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that to fill an array.
A host would probably represent this to a user as a cubic curve in a standard curve editor interface, or possibly through scripting. The user would then use this to define the 'shape' of the parameter.
The evaluation of such params is not the same as animation, they are returning values based on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass a parametric position and time.
Often, you would want such a parametric parameter to be multi-dimensional, for example, a colour look-up table might want three values, one for red, green and blue. Rather than declare three separate parametric parameters, it would be better to have one such parameter with multiple values in it.
The major complication with these parameters is how to allow a plug-in to set values, and defaults. The default default value of a parametric curve is to be an identity lookup. If a plugin wishes to set a different default value for a curve, it can use the suite to set key/value pairs on the m descriptor of the param. When a new instance is made, it will have these curve values as a default.
OfxParametricParameterSuiteV1::parametricParamGetValue
— Evaluates a parametric parameter
#include "ofxParametricParam.h"
OfxStatus(*parametricParamGetValue)( | OfxParamHandleparam, |
int curveIndex, | |
OfxTimetime, | |
doubleparametricPosition, | |
double *returnValue) ; |
kOfxStatOK
- all was fine kOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrBadIndex
- the curve index was invalid
OfxParametricParameterSuiteV1::parametricParamGetNControlPoints
— Returns the number of control points in the parametric param.
#include "ofxParametricParam.h"
OfxStatus(*parametricParamGetNControlPoints)( | OfxParamHandleparam, |
int curveIndex, | |
doubletime, | |
int *returnValue) ; |
kOfxStatOK
- all was fine kOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrBadIndex
- the curve index was invalid
OfxParametricParameterSuiteV1::parametricParamGetNthControlPoint
— Returns the key/value pair of the nth control point.
#include "ofxParametricParam.h"
OfxStatus(*parametricParamGetNthControlPoint)( | OfxParamHandleparam, |
int curveIndex, | |
doubletime, | |
int nthCtl, | |
double *key, | |
double *value) ; |
kOfxStatOK
- all was fine kOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParametricParameterSuiteV1::parametricParamSetNthControlPoint
— Modifies an existing control point on a curve
#include "ofxParametricParam.h"
OfxStatus(*parametricParamSetNthControlPoint)( | OfxParamHandleparam, |
int curveIndex, | |
doubletime, | |
int nthCtl, | |
doublekey, | |
doublevalue, | |
booladdAnimationKey) ; |
This modifies an existing control point. Note that by changing key, the order of the control point may be modified (as you may move it before or after anther point). So be careful when iterating over a curves control points and you change a key.
kOfxStatOK
- all was fine kOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParametricParameterSuiteV1::parametricParamAddControlPoint
— Adds a control point to the curve.
#include "ofxParametricParam.h"
OfxStatus(*parametricParamAddControlPoint)( | OfxParamHandleparam, |
int curveIndex, | |
doubletime, | |
doublekey, | |
doublevalue, | |
booladdAnimationKey) ; |
This will add a new control point to the given dimension of a parametric parameter. If a key exists sufficiently close to 'key', then it will be set to the indicated control point.
kOfxStatOK
- all was fine kOfxStatErrBadHandle
- if the paramter handle was invalidkOfxStatErrUnknown
- if the type is unknown
OfxParametricParameterSuiteV1::parametricParamDeleteControlPoint
— Deletes the nth control point from a parametric param.
#include "ofxParametricParam.h"
OfxStatus(*parametricParamDeleteControlPoint)( | OfxParamHandleparam, |
int curveIndex, | |
int nthCtl) ; |
OfxMemorySuiteV1
— The OFX suite that implements general purpose memory management.
#include "ofxMemory.h" typedef struct OfxMemorySuiteV1 { OfxStatus (*memoryAlloc)(void *handle, size_t nBytes, void **allocatedData); OfxStatus (*memoryFree)(void *allocatedData); } OfxMemorySuiteV1;
Use this suite for ordinary memory management functions, where you would normally use malloc/free or new/delete on ordinary objects.
For images, you should use the memory allocation functions in the image effect suite, as many hosts have specific image memory pools.
\note C++ plugin developers will need to redefine new and delete as skins ontop of this suite.
OfxMemorySuiteV1::memoryAlloc
— Allocate memory.
#include "ofxMemory.h"
OfxStatus(*memoryAlloc)( | void *handle, |
size_tnBytes, | |
void **allocatedData) ; |
This function has the host allocate memory using its own memory resources and returns that to the plugin.
kOfxStatOK
the memory was sucessfully allocatedkOfxStatErrMemory
the request could not be met and no memory was allocated
OfxMemorySuiteV1::memoryFree
— Frees memory.
#include "ofxMemory.h"
OfxStatus(*memoryFree)( | void *allocatedData) ; |
This function frees any memory that was previously allocated via OfxMemorySuiteV1::memoryAlloc
.
kOfxStatOK
the memory was sucessfully freedkOfxStatErrBadHandle
allocatedData was not a valid pointer returned by OfxMemorySuiteV1::memoryAlloc
This chapter describes the multithreading suite designed for simple SMP multi-processing.
OfxThreadFunctionV1 — Typedef for functions passed to the multithreading suite
#include "ofxMultiThread.h"
typedef OfxStatus(OfxThreadFunctionV1)( | unsigned intthreadIndex, |
unsigned intthreadMax, | |
void *customArg) ; |
OfxMultiThreadSuiteV1::multiThread
Typedef for functions that are used to spawn SMP threads must have this function signature. Such functions are passed to
OfxMultiThreadSuiteV1::multiThread
.
OfxMultiThreadSuiteV1
— OFX suite that provides simple SMP style multi-processing
#include "ofxMultiThread.h" typedef struct OfxMultiThreadSuiteV1 { OfxStatus (*multiThread)(OfxThreadFunctionV1 func, unsigned int nThreads, void *customArg); OfxStatus (*multiThreadNumCPUs)(unsigned int *nCPUs); OfxStatus (*multiThreadIndex)(unsigned int *threadIndex); int (*multiThreadIsSpawnedThread)(void); OfxStatus (*mutexCreate)(OfxMutexHandle *mutex, int lockCount); OfxStatus (*mutexDestroy)(const OfxMutexHandle mutex); OfxStatus (*mutexLock)(const OfxMutexHandle mutex); OfxStatus (*mutexUnLock)(const OfxMutexHandle mutex); OfxStatus (*mutexTryLock)(const OfxMutexHandle mutex); } OfxMultiThreadSuiteV1;
OfxMultiThreadSuiteV1::multiThread
— Function to spawn SMP threads
#include "ofxMultiThread.h"
OfxStatus(*multiThread)( | OfxThreadFunctionV1func, |
unsigned intnThreads, | |
void *customArg) ; |
This function will spawn nThreads separate threads of computation (typically one per CPU) to allow something to perform symmetric multi processing. Each thread will call 'func' passing in the index of the thread and the number of threads actually launched.
multiThread will not return until all the spawned threads have returned. It is up to the host how it waits for all the threads to return (busy wait, blocking, whatever).
nThreads can be more than the value returned by multiThreadNumCPUs, however the threads will be limitted to the number of CPUs returned by multiThreadNumCPUs.
This function cannot be called recursively.
kOfxStatOK
, the function func has executed and returned sucessfullykOfxStatFailed
, the threading function failed to launchkOfxStatErrExists
, failed in an attempt to call multiThread recursively,
OfxMultiThreadSuiteV1::multiThreadNumCPUs
— Function which indicates the number of CPUs available for SMP processing
#include "ofxMultiThread.h"
OfxStatus(*multiThreadNumCPUs)( | unsigned int *nCPUs) ; |
This value may be less than the actual number of CPUs on a machine, as the host may reserve other CPUs for itself.
kOfxStatOK
, all was OK and the maximum number of threads is in nThreads.kOfxStatFailed
, the function failed to get the number of CPUs
OfxMultiThreadSuiteV1::multiThreadIndex
— Function which indicates the index of the current thread
#include "ofxMultiThread.h"
OfxStatus(*multiThreadIndex)( | unsigned int *threadIndex) ; |
This function returns the thread index, which is the same as the threadIndex argument passed to the OfxThreadFunctionV1
.
If there are no threads currently spawned, then this function will set threadIndex to 0
kOfxStatOK
, all was OK and the maximum number of threads is in nThreads.kOfxStatFailed
, the function failed to return an index
OfxMultiThreadSuiteV1::multiThreadIsSpawnedThread
— Function to enquire if the calling thread was spawned by multiThread
#include "ofxMultiThread.h"
int(*multiThreadIsSpawnedThread)( | void) ; |
OfxMultiThreadSuiteV1::mutexCreate
— Create a mutex
#include "ofxMultiThread.h"
OfxStatus(*mutexCreate)( | OfxMutexHandle *mutex, |
intlockCount) ; |
OfxMultiThreadSuiteV1::mutexDestroy
— Destroy a mutex
#include "ofxMultiThread.h"
OfxStatus(*mutexDestroy)( | const OfxMutexHandlemutex) ; |
OfxMultiThreadSuiteV1::mutexLock
— Blocking lock on the mutex
#include "ofxMultiThread.h"
OfxStatus(*mutexLock)( | const OfxMutexHandlemutex) ; |
OfxMultiThreadSuiteV1::mutexUnLock
— Unlock the mutex
#include "ofxMultiThread.h"
OfxStatus(*mutexUnLock)( | const OfxMutexHandlemutex) ; |
OfxMultiThreadSuiteV1::mutexTryLock
— Non blocking attempt to lock the mutex
#include "ofxMultiThread.h"
OfxStatus(*mutexTryLock)( | const OfxMutexHandlemutex) ; |
OfxInteractSuiteV1
— OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.
#include "ofxInteract.h" typedef struct OfxInteractSuiteV1 { OfxStatus (*interactSwapBuffers)(OfxInteractHandle interactInstance); OfxStatus (*interactRedraw)(OfxInteractHandle interactInstance); OfxStatus (*interactGetPropertySet)(OfxInteractHandle interactInstance, OfxPropertySetHandle *property); } OfxInteractSuiteV1;
OfxInteractSuiteV1::interactSwapBuffers
— Requests an openGL buffer swap on the interact instance
#include "ofxInteract.h"
OfxStatus(*interactSwapBuffers)( | OfxInteractHandleinteractInstance) ; |
Version 2 of the message suite is a backwards compatible replacement for the V1 message suite. It extends V1 by adding support for persistent users messages, typically to indicate a plugin is in an error state.
OfxMessageSuiteV2
— The OFX suite that allows a plug-in to pass messages back to a user.
#include "ofxMessage.h" typedef struct OfxMessageSuiteV2 { OfxStatus (*message)(void *handle, const char *messageType, const char *messageId, const char *format, ...); OfxStatus (*setPersistentMessage)(void *handle, const char *messageType, const char *messageId, const char *format, ...); OfxStatus (*clearPersistentMessage)(void *handle); } OfxMessageSuiteV2;
OfxMessageSuiteV2::message
— Post a transient message on the host, using printf style varargs. Same as the V1 message suite call.
#include "ofxMessage.h"
OfxStatus(*message)( | void *handle, |
const char *messageType, | |
const char *messageId, | |
const char *format, | |
...) ; |
\returns
kOfxStatOK
- if the message was sucessfully posted kOfxStatReplyYes
- if the message was of type kOfxMessageQuestion and the user reply yeskOfxStatReplyNo
- if the message was of type kOfxMessageQuestion and the user reply nokOfxStatFailed
- if the message could not be posted for some reason
OfxMessageSuiteV2::setPersistentMessage
— Post a persistent message on an effect, using printf style varargs, and set error states. New for V2 message suite.
#include "ofxMessage.h"
OfxStatus(*setPersistentMessage)( | void *handle, |
const char *messageType, | |
const char *messageId, | |
const char *format, | |
...) ; |
\returns
kOfxStatOK
- if the message was sucessfully posted kOfxStatErrBadHandle
- the handle was rubbishkOfxStatFailed
- if the message could not be posted for some reason
Persistent messages are associated with an effect handle until explicitly cleared by an effect. So if an error message is posted the error state, and associated message will persist and be displayed on the effect appropriately. (eg: draw a node in red on a node based compostor and display the message when clicked on).
If messageType is error or warning, associated error states should be flagged on host applications. Posting an error message implies that the host cannot proceeed, a warning allows the host to proceed, whilst a simple message should have no stop anything.
OfxMessageSuiteV2::clearPersistentMessage
— Clears any persistent message on an effect handle that was set by OfxMessageSuiteV2::setPersistentMessage
. New for V2 message suite.
#include "ofxMessage.h"
OfxStatus(*clearPersistentMessage)( | void *handle) ; |
\returns
kOfxStatOK
- if the message was sucessfully clearedkOfxStatErrBadHandle
- the handle was rubbishkOfxStatFailed
- if the message could not be cleared for some reason
Clearing a message will clear any associated error state.
The OpenGL Render Suite is used to transfer images between host and plug-in using OpenGL. This speeds processing when the host and plug-in can both process on the GPU.
OfxImageEffectOpenGLRenderSuiteV1
— OFX suite that provides image to texture conversion for OpenGL
#include "ofxOpenGLRender.h" typedef struct OfxImageEffectOpenGLRenderSuiteV1 { OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip, OfxTime time, const char *format, const OfxRectD *region, OfxPropertySetHandle *textureHandle); OfxStatus (*clipFreeTexture)(OfxPropertySetHandle textureHandle); OfxStatus (*flushResources)( ); } OfxImageEffectOpenGLRenderSuiteV1;
OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture
— loads an image from an OFX clip as a texture into OpenGL
#include "ofxOpenGLRender.h"
OfxStatus(*clipLoadTexture)( | OfxImageClipHandleclip, |
OfxTime time, | |
const char *format, | |
const OfxRectD *region, | |
OfxPropertySetHandle *textureHandle) ; |
kOfxOpenGLPropPixelDepth
setting.
An image is fetched from a clip at the indicated time for the given region
and loaded into an OpenGL texture. When a specific format is requested, the
host ensures it gives the requested format.
When the clip specified is the "Output" clip, the format is ignored and
the host must bind the resulting texture as the current color buffer
(render target). This may also be done prior to calling the
kOfxImageEffectActionRender
action.
If the m region parameter is set to non-NULL, then it will be clipped to
the clip's Region of Definition for the given time.
The returned image will be m at m least as big as this region.
If the region parameter is not set or is NULL, then the region fetched will be at
least the Region of Interest the effect has previously specified, clipped to
the clip's Region of Definition.
Information about the texture, including the texture index, is returned in
the m textureHandle argument.
The properties on this handle will be...
kOfxImageEffectPropOpenGLTextureIndex
kOfxImageEffectPropOpenGLTextureTarget
kOfxImageEffectPropPixelDepth
kOfxImageEffectPropComponents
kOfxImageEffectPropPreMultiplication
kOfxImageEffectPropRenderScale
kOfxImagePropPixelAspectRatio
kOfxImagePropBounds
kOfxImagePropRegionOfDefinition
kOfxImagePropRowBytes
kOfxImagePropField
kOfxImagePropUniqueIdentifier
With the exception of the OpenGL specifics, these properties are the same as the properties in an image handle returned by clipGetImage in the image effect suite. \pre
\post
returns
the host must bind the resulting texture as the current color buffer (render target). This may also be done prior to calling the render action.
\note
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
- not enough OpenGL memory was available for the
effect to load the texture.
The plugin should abort the GL render and
return kOfxStatErrMemory
, after which the host can
decide to retry the operation with CPU based processing.
OfxImageEffectOpenGLRenderSuiteV1::clipFreeTexture
— Releases the texture handle previously returned by
#include "ofxOpenGLRender.h"
OfxStatus(*clipFreeTexture)( | OfxPropertySetHandle textureHandle) ; |
clipLoadTexture
For input clips, this also deletes the texture from OpenGL. This should also be called on the output clip; for the Output clip, it just releases the handle but does not delete the texture (since the host will need to read it).
\pre
\post
it referred to has been deleted (for source clips)
kOfxStatOK
- the image was successfully fetched and returned in the
handle,
kOfxStatFailed
- general failure for some reason,
kOfxStatErrBadHandle
- the image handle was invalid,
OfxImageEffectOpenGLRenderSuiteV1::flushResources
— Request the host to minimize its GPU resource load
#include "ofxOpenGLRender.h"
OfxStatus(*flushResources)( | ) ; |
When a plugin fails to allocate GPU resources, it can call this function to request the host to flush it's GPU resources if it holds any. After the function the plugin can try again to allocate resources which then might succeed if the host actually has released anything.
\pre \post
kOfxStatOK
- the host has actually released some
resources,
kOfxStatReplyDefault
- nothing the host could do..
This chapter lists all the properties on each OFX object.
All OfxImageClipHandle accessed inside the kOfxActionDescribe
or kOfxActionDescribeInContext
are clip descriptors, used to describe the behaviour of clips in a specific context.
All images are instances, there is no such thing as an image descriptor.
kOfxTypeParameter
(read only)This chapter lists each property in the OFX Image Effect API by name.
kOfxImageClipPropConnected
— Says whether the clip is actually connected at the moment.
#include "/ofxImageEffect.h" #define kOfxImageClipPropConnected "OfxImageClipPropConnected"
Says whether the clip is actually connected at the moment.
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 m always be connected during a render action. However, during interface actions, even non optional clips may be unconnected.
kOfxImageClipPropContinuousSamples
— Clip and action argument property which indicates that the clip can be sampled continously
#include "/ofxImageEffect.h" #define kOfxImageClipPropContinuousSamples "OfxImageClipPropContinuousSamples"
This is a property that belongs to the clip instance (read only), as an out argument to kOfxImageEffectActionGetClipPreferences
action (read/write).
The default value is 0 as an out argument to the kOfxImageEffectActionGetClipPreferences
action.
kOfxImageClipPropFieldExtraction
— Controls how a plugin fetched fielded imagery from a clip.
#include "/ofxImageEffect.h" #define kOfxImageClipPropFieldExtraction "OfxImageClipPropFieldExtraction"
This must be one of
Controls how a plugin fetched fielded imagery from a clip.
This controls how a plug-in wishes to fetch images from a fielded clip, so it can tune it behaviour when it renders fielded footage.
Note that if it fetches kOfxImageFieldSingle and the host stores images natively as both fields interlaced, it can return a single image by doubling rowbytes and tweaking the starting address of the image data. This saves on a buffer copy.
kOfxImageClipPropFieldOrder
— Which spatial field occurs temporally first in a frame.
#include "/ofxImageEffect.h" #define kOfxImageClipPropFieldOrder "OfxImageClipPropFieldOrder"
kOfxImageClipPropIsMask
— Indicates that a clip is intended to be used as a mask input
#include "/ofxImageEffect.h" #define kOfxImageClipPropIsMask "OfxImageClipPropIsMask"
Indicates that a clip is intended to be used as a mask input
Set this property on any clip which will only ever have single channel alpha images fetched from it. Typically on an optional clip such as a junk matte in a keyer.
This property acts as a hint to hosts indicating that they could feed the effect from a rotoshape (or similar) rather than an 'ordinary' clip.
kOfxImageClipPropOptional
— Indicates if a clip is optional.
#include "/ofxImageEffect.h" #define kOfxImageClipPropOptional "OfxImageClipPropOptional"
kOfxImageClipPropUnmappedComponents
— Indicates the current 'raw' component type on a clip before any mapping by clip preferences
#include "/ofxImageEffect.h" #define kOfxImageClipPropUnmappedComponents "OfxImageClipPropUnmappedComponents"
kOfxImageClipPropUnmappedPixelDepth
— Indicates the type of each component in a clip before any mapping by clip preferences
#include "/ofxImageEffect.h" #define kOfxImageClipPropUnmappedPixelDepth "OfxImageClipPropUnmappedPixelDepth"
kOfxImageEffectFrameVarying
— Indicates whether an effect will generate different images from frame to frame.
#include "/ofxImageEffect.h" #define kOfxImageEffectFrameVarying "OfxImageEffectFrameVarying"
This is a property that belongs to the out argument to kOfxImageEffectActionGetClipPreferences
action (read/write)..
Indicates whether an effect will generate different images from frame to frame.
This property indicates whether a plugin will generate a different image from frame to frame, even if no parameters or input image changes. For example a generater that creates random noise pixel at each frame.
kOfxImageEffectHostPropIsBackground
— Indicates if a host is a background render.
#include "/ofxImageEffect.h" #define kOfxImageEffectHostPropIsBackground "OfxImageEffectHostPropIsBackground"
kOfxImageEffectHostPropNativeOrigin
— Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processing
#include "/ofxImageEffect.h" #define kOfxImageEffectHostPropNativeOrigin "OfxImageEffectHostPropNativeOrigin"
"kOfxImageEffectHostPropNativeOriginBottomLeft" - 0,0 bottom left "kOfxImageEffectHostPropNativeOriginTopLeft" - 0,0 top left "kOfxImageEffectHostPropNativeOriginCenter" - 0,0 center (screen space)
Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processing
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).
kOfxImageEffectInstancePropEffectDuration
— The duration of the effect
#include "/ofxImageEffect.h" #define kOfxImageEffectInstancePropEffectDuration "OfxImageEffectInstancePropEffectDuration"
kOfxImageEffectInstancePropSequentialRender
— Indicates whether a plugin needs sequential rendering, and a host support it
#include "/ofxImageEffect.h" #define kOfxImageEffectInstancePropSequentialRender "OfxImageEffectInstancePropSequentialRender"
This is a property that belongs to the plugin descriptor (read/write) or plugin instance (read/write), and host descriptor (read only).
kOfxImageEffectPropSequentialRenderStatus
on the relevant actions
Indicates whether a plugin needs sequential rendering, and a host support it
Some effects have temporal dependancies, some information from from the rendering of frame N-1 is needed to render frame N correctly. This property is set by an effect to indicate such a situation. Also, some effects are more efficient if they run sequentially, but can still render correct images even if they do not, eg: a complex particle system.
During an interactive session a host may attempt to render a frame out of sequence (for example when the user scrubs the current time), and the effect needs to deal with such a situation as best it can to provide feedback to the user.
However if a host caches output, any frame frame generated in random temporal order needs to be considered invalid and needs to be re-rendered when the host finally performs a first to last render of the output sequence.
In all cases, a host will set the kOfxImageEffectPropSequentialRenderStatus flag to indicate its sequential render status.
kOfxImageEffectPluginPropFieldRenderTwiceAlways
— Controls how a plugin renders fielded footage.
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginPropFieldRenderTwiceAlways "OfxImageEffectPluginPropFieldRenderTwiceAlways"
kOfxImageEffectPluginPropFieldRenderTwiceAlways
is of type integer, and has only a single dimension.
kOfxImageEffectPluginPropGrouping
— Indicates the effect group for this plugin.
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginPropGrouping "OfxImageEffectPluginPropGrouping"
kOfxImageEffectPluginPropHostFrameThreading
— Indicates whether a plugin lets the host perform per frame SMP threading
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginPropHostFrameThreading "OfxImageEffectPluginPropHostFrameThreading"
kOfxImageEffectPluginPropOverlayInteractV1
— Sets the entry for an effect's overlay interaction
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginPropOverlayInteractV1 "OfxImageEffectPluginPropOverlayInteractV1"
kOfxImageEffectPluginPropSingleInstance
— Indicates whether only one instance of a plugin can exist at the same time
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginPropSingleInstance "OfxImageEffectPluginPropSingleInstance"
kOfxImageEffectPluginRenderThreadSafety
— Indicates how many simultaneous renders the plugin can deal with.
#include "/ofxImageEffect.h" #define kOfxImageEffectPluginRenderThreadSafety "OfxImageEffectPluginRenderThreadSafety"
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
kOfxImageEffectPropClipPreferencesSlaveParam
— Indicates the set of parameters on which a value change will trigger a change to clip preferences
#include "/ofxImageEffect.h" #define kOfxImageEffectPropClipPreferencesSlaveParam "OfxImageEffectPropClipPreferencesSlaveParam"
Indicates the set of parameters on which a value change will trigger a change to clip preferences
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...)
kOfxImageEffectPropComponents
— Indicates the current component type in a clip or image (after any mapping)
#include "/ofxImageEffect.h" #define kOfxImageEffectPropComponents "OfxImageEffectPropComponents"
This is a property that belongs to the clip instance (read only), image instance (read only).
kOfxImageEffectPropContext
— Indicates the context a plugin instance has been created for.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropContext "OfxImageEffectPropContext"
kOfxImageEffectPropFieldToRender
— Indicates which field is being rendered.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropFieldToRender "OfxImageEffectPropFieldToRender"
This is a property that belongs to the a read only in argument property to kOfxImageEffectActionRender
and kOfxImageEffectActionIsIdentity
.
this must be one of
kOfxImageEffectPropFrameRange
— The frame range over which a clip has images.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropFrameRange "OfxImageEffectPropFrameRange"
kOfxImageEffectPropFrameRate
— The frame rate of a clip or instance's project.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropFrameRate "OfxImageEffectPropFrameRate"
This is a property that belongs to the clip instance (read only), effect instance (read only) and kOfxImageEffectActionGetClipPreferences
action out args property (read/write).
The frame rate of a clip or instance's project.
For an input clip this is the frame rate of the clip.
For an output clip, the frame rate mapped via pixel preferences.
For an instance, this is the frame rate of the project the effect is in.
For the outargs property in the kOfxImageEffectActionGetClipPreferences
action, it is used to change the frame rate of the ouput clip.
kOfxImageEffectPropFrameStep
— The frame step used for a sequence of renders
#include "/ofxImageEffect.h" #define kOfxImageEffectPropFrameStep "OfxImageEffectPropFrameStep"
This is a property that belongs to the an in argument for the kOfxImageEffectActionBeginSequenceRender
action (read only).
kOfxImageEffectPropInteractiveRenderStatus
— Property that indicates if a plugin is being rendered in response to user interaction.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropInteractiveRenderStatus "OfxImageEffectPropInteractiveRenderStatus"
This is a property that belongs to the read only property on the inArgs of the following actions....
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.
kOfxImageEffectPropOpenGLEnabled
— Indicates that an image effect SHOULD use OpenGL acceleration in
#include "/ofxOpenGLRender.h" #define kOfxImageEffectPropOpenGLEnabled "OfxImageEffectPropOpenGLEnabled"
This is a property that belongs to the inArgs property set of the following actions... .
Indicates that an image effect SHOULD use OpenGL acceleration in the current action
When a plugin and host have established they can both use OpenGL renders then when this property has been set the host expects the plugin to render its result into the buffer it has setup before calling the render. The plugin can then also safely use the 'OfxImageEffectOpenGLRenderSuite'
kOfxImageEffectActionRender
kOfxImageEffectActionBeginSequenceRender
kOfxImageEffectActionEndSequenceRender
and may use the OpenGL suite functions.
\note Once this property is set, the host and plug-in have agreed to use OpenGL, so the effect SHOULD access all its images through the OpenGL suite.
v1.4: kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture
kOfxImageEffectPropOpenGLRenderSupported
— Indicates whether a host or plugin can support OpenGL accelerated
#include "/ofxOpenGLRender.h" #define kOfxImageEffectPropOpenGLRenderSupported "OfxImageEffectPropOpenGLRenderSupported"
This is a property that belongs to the plugin descriptor (read/write), host descriptor (read .
Indicates whether a host or plugin can support OpenGL accelerated rendering
only) - plugin instance change (read/write) accelerated rendering
rendering, in the case of plug-ins this also means that it is capable of CPU based rendering in the absence of a GPU
OpenGL support, without which it cannot work.
V1.4: It is now expected from host reporting v1.4 that the plugin can during instance change switch from true to false and false to true.
kOfxImageEffectPropOpenGLTextureIndex
— Indicates the texture index of an image turned into an OpenGL
#include "/ofxOpenGLRender.h" #define kOfxImageEffectPropOpenGLTextureIndex "OfxImageEffectPropOpenGLTextureIndex"
Indicates the texture index of an image turned into an OpenGL texture by the host
` OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture
(read only)
This value should be cast to a GLuint and used as the texture index when performing OpenGL texture operations.
The property set of the following actions should contain this property:
kOfxImageEffectPropOpenGLTextureTarget
— Indicates the texture target enumerator of an image turned into
#include "/ofxOpenGLRender.h" #define kOfxImageEffectPropOpenGLTextureTarget "OfxImageEffectPropOpenGLTextureTarget"
Indicates the texture target enumerator of an image turned into an OpenGL texture by the host
OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture
(read only)
This value should be cast to a GLenum and used as the texture target
when performing OpenGL texture operations.
The property set of the following actions should contain this property:
kOfxImageEffectPropPixelDepth
— Indicates the type of each component in a clip or image (after any mapping)
#include "/ofxImageEffect.h" #define kOfxImageEffectPropPixelDepth "OfxImageEffectPropPixelDepth"
This is a property that belongs to the clip instance (read only), image instance (read only).
kOfxImageEffectPropPluginHandle
— The plugin handle passed to the initial 'describe' action.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropPluginHandle "OfxImageEffectPropPluginHandle"
kOfxImageEffectPropPreMultiplication
— Indicates the premultiplication state of a clip or image
#include "/ofxImageEffect.h" #define kOfxImageEffectPropPreMultiplication "OfxImageEffectPropPreMultiplication"
This is a property that belongs to the clip instance (read only), image instance (read only), out args property in the kOfxImageEffectActionGetClipPreferences
action (read/write).
This must be one of
Indicates the premultiplication state of a clip or image
See the documentation on clip preferences for more details on how this is used with the kOfxImageEffectActionGetClipPreferences
action.
kOfxImageEffectPropProjectExtent
— The extent of the current project in canonical coordinates.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropProjectExtent "OfxImageEffectPropProjectExtent"
The extent of the current project in canonical coordinates.
The extent is the size of the 'output' for the current project. See NormalisedCoordinateSystem for more infomation on the project extent.
The extent is in canonical coordinates and only returns the top right position, as the extent is always rooted at 0,0.
For example a PAL SD project would have an extent of 768, 576.
kOfxImageEffectPropProjectOffset
— The offset of the current project in canonical coordinates.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropProjectOffset "OfxImageEffectPropProjectOffset"
The offset of the current project in canonical coordinates.
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
#include "/ofxImageEffect.h" #define kOfxImageEffectPropProjectPixelAspectRatio "OfxImageEffectPropPixelAspectRatio"
kOfxImageEffectPropProjectSize
— The size of the current project in canonical coordinates.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropProjectSize "OfxImageEffectPropProjectSize"
The size of the current project in canonical coordinates.
The size of a project is a sub set of the kOfxImageEffectPropProjectExtent
. For example a project may be a PAL SD project, but only be a letter-box within that. The project size is the size of this sub window.
The project size is in canonical coordinates.
See NormalisedCoordinateSystem for more infomation on the project extent.
kOfxImageEffectPropRegionOfDefinition
— Used to indicate the region of definition of a plug-in
#include "/ofxImageEffect.h" #define kOfxImageEffectPropRegionOfDefinition "OfxImageEffectPropRegionOfDefinition"
This is a property that belongs to the a read/write out argument property to the kOfxImageEffectActionGetRegionOfDefinition
action.
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.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropRegionOfInterest "OfxImageEffectPropRegionOfInterest"
This is a property that belongs to the a read only in argument property to the kOfxImageEffectActionGetRegionsOfInterest
action.
The value of a region of interest.
A host passes this value into the region of interest action to specify the region it is interested in rendering.
The order of the values is x1, y1, x2, y2.
This will be in CanonicalCoordinates.
kOfxImageEffectPropRenderQualityDraft
— Indicates whether an effect can take quality shortcuts to improve speed.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropRenderQualityDraft "OfxImageEffectPropRenderQualityDraft"
Indicates whether an effect can take quality shortcuts to improve speed.
This property indicates that the host provides the plug-in the option to render in Draft/Preview mode. This is useful for applications that must support fast scrubbing. These allow a plug-in to take short-cuts for improved performance when the situation allows and it makes sense, for example to generate thumbnails with effects applied. For example switch to a cheaper interpolation type or rendering mode. A plugin should expect frames rendered in this manner that will not be stucked in host cache unless the cache is only used in the same draft situations. If an host does not support that property a value of 0 is assumed. Also note that some hosts do implement kOfxImageEffectPropRenderScale - these two properties can be used independently.
kOfxImageEffectPropRenderScale
— The proxy render scale currently being applied.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropRenderScale "OfxImageEffectPropRenderScale"
This is a property that belongs to the an image instance (read only) and as read only an in argument on the following actions,.
The proxy render scale currently being applied.
kOfxImageEffectActionRender
kOfxImageEffectActionBeginSequenceRender
kOfxImageEffectActionEndSequenceRender
kOfxImageEffectActionIsIdentity
kOfxImageEffectActionGetRegionOfDefinition
kOfxImageEffectActionGetRegionsOfInterest
kOfxActionInstanceChanged
kOfxInteractActionDraw
kOfxInteractActionPenMotion
kOfxInteractActionPenDown
kOfxInteractActionPenUp
kOfxInteractActionKeyDown
kOfxInteractActionKeyUp
kOfxInteractActionKeyRepeat
kOfxInteractActionGainFocus
kOfxInteractActionLoseFocus
This should be applied to any spatial parameters to position them correctly. Not that the 'x' value does not include any pixel aspect ratios.
kOfxImageEffectPropRenderWindow
— The region to be rendered.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropRenderWindow "OfxImageEffectPropRenderWindow"
This is a property that belongs to the a read only in argument property to the kOfxImageEffectActionRender
and kOfxImageEffectActionIsIdentity
actions.
The region to be rendered.
The order of the values is x1, y1, x2, y2.
This will be in PixelCoordinates
kOfxImageEffectPropSequentialRenderStatus
— Property on all the render action that indicate the current sequential render status of a host
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSequentialRenderStatus "OfxImageEffectPropSequentialRenderStatus"
This is a property that belongs to the read only property on the inArgs of the following actions....
Property on all the render action that indicate the current sequential render status of a host
This property is set to indicate whether the effect is currently being rendered in frame order on a single effect instance. See kOfxImageEffectInstancePropSequentialRender
for more details on sequential rendering.
kOfxImageEffectPropSetableFielding
— Indicates whether the host will let a plugin set the fielding of the output clip.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSetableFielding "OfxImageEffectPropSetableFielding"
This must be one of
kOfxImageEffectActionGetClipPreferences
action.
kOfxImageEffectPropSetableFrameRate
— Indicates whether the host will let a plugin set the frame rate of the output clip.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSetableFrameRate "OfxImageEffectPropSetableFrameRate"
This must be one of
kOfxImageEffectActionGetClipPreferences
action.
Indicates whether the host will let a plugin set the frame rate of the output clip.
See ImageEffectClipPreferences.
If a clip can be continously sampled, the frame rate will be set to 0.
kOfxImageEffectPropSupportedComponents
— Indicates the components supported by a clip or host,
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportedComponents "OfxImageEffectPropSupportedComponents"
This is a property that belongs to the host descriptor (read only), clip descriptor (read/write).
kOfxImageEffectPropSupportedContexts
— Indicates to the host the contexts a plugin can be used in.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportedContexts "OfxImageEffectPropSupportedContexts"
This is a property that belongs to the image effect descriptor passed to kOfxActionDescribe (read/write).
kOfxImageEffectPropSupportedPixelDepths
— Indicates the bit depths support by a plug-in or host
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportedPixelDepths "OfxImageEffectPropSupportedPixelDepths"
This is a property that belongs to the host descriptor (read only), plugin descriptor (read/write).
kOfxImageEffectPropSupportsMultiResolution
— Indicates whether a plugin or host support multiple resolution images.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportsMultiResolution "OfxImageEffectPropSupportsMultiResolution"
This is a property that belongs to the host descriptor (read only), plugin descriptor (read/write).
kOfxImageEffectPropSupportsMultipleClipDepths
— Indicates whether a host or plugin can support clips of differing component depths going into/out of an effect
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportsMultipleClipDepths "OfxImageEffectPropMultipleClipDepths"
This is a property that belongs to the plugin descriptor (read/write), host descriptor (read only).
This must be one of
Indicates whether a host or plugin can support clips of differing component depths going into/out of an effect
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
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportsMultipleClipPARs "OfxImageEffectPropSupportsMultipleClipPARs"
This is a property that belongs to the plugin descriptor (read/write), host descriptor (read only).
This must be one of
Indicates whether a host or plugin can support clips of differing pixel aspect ratios going into/out of an effect
If a host indicates that it can support multiple pixel aspect ratios, then it will allow the plugin to explicitly set
the output clip's aspect ratio in the kOfxImageEffectActionGetClipPreferences
action. See ImageEffectClipPreferences.
kOfxImageEffectPropSupportsOverlays
— Indicates whether a host support image effect ImageEffectOverlays.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportsOverlays "OfxImageEffectPropSupportsOverlays"
kOfxImageEffectPropSupportsTiles
— Indicates whether a clip, plugin or host supports tiled images
#include "/ofxImageEffect.h" #define kOfxImageEffectPropSupportsTiles "OfxImageEffectPropSupportsTiles"
This is a property that belongs to the host descriptor (read only), plugin descriptor (read/write), clip descriptor (read/write), instance (read/write).
Indicates whether a clip, plugin or host supports tiled images
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.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropTemporalClipAccess "OfxImageEffectPropTemporalClipAccess"
kOfxImageEffectPropUnmappedFrameRange
— The unmaped frame range over which an output clip has images.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropUnmappedFrameRange "OfxImageEffectPropUnmappedFrameRange"
The unmaped frame range over which an output clip has images.
Dimension 0 is the first frame for which the clip can produce valid data.
Dimension 1 is the last frame for which the clip can produce valid data.
If a plugin changes the output frame rate in the pixel preferences action, it will affect the frame range of the output clip, this property allows a plugin to get to the original value.
kOfxImageEffectPropUnmappedFrameRate
— Indicates the original unmapped frame rate (frames/second) of a clip
#include "/ofxImageEffect.h" #define kOfxImageEffectPropUnmappedFrameRate "OfxImageEffectPropUnmappedFrameRate"
kOfxImagePropBounds
— The bounds of an image's pixels.
#include "/ofxImageEffect.h" #define kOfxImagePropBounds "OfxImagePropBounds"
The bounds of an image's pixels.
The bounds, in PixelCoordinates, are of the addressable pixels in an image's data pointer.
The order of the values is x1, y1, x2, y2.
X values are x1 <= X < x2 Y values are y1 <= Y < y2
For less than full frame images, the pixel bounds will be contained by the kOfxImagePropRegionOfDefinition
bounds.
kOfxImagePropData
— The pixel data pointer of an image.
#include "/ofxImageEffect.h" #define kOfxImagePropData "OfxImagePropData"
kOfxImagePropField
— Which fields are present in the image
#include "/ofxImageEffect.h" #define kOfxImagePropField "OfxImagePropField"
This must be one of
kOfxImageFieldNone
- the image is an unfielded framekOfxImageFieldBoth
- 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...)
kOfxImagePropPixelAspectRatio
— The pixel aspect ratio of a clip or image.
#include "/ofxImageEffect.h" #define kOfxImagePropPixelAspectRatio "OfxImagePropPixelAspectRatio"
This is a property that belongs to the clip instance (read only), image instance (read only) and kOfxImageEffectActionGetClipPreferences
action out args property (read/write).
kOfxImagePropRegionOfDefinition
— The full region of definition of an image.
#include "/ofxImageEffect.h" #define kOfxImagePropRegionOfDefinition "OfxImagePropRegionOfDefinition"
The full region of definition of an image.
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.
#include "/ofxImageEffect.h" #define kOfxImagePropRowBytes "OfxImagePropRowBytes"
The number of bytes in a row of an image.
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 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.
kOfxImagePropUniqueIdentifier
— Uniquely labels an image
#include "/ofxImageEffect.h" #define kOfxImagePropUniqueIdentifier "OfxImagePropUniqueIdentifier"
Uniquely labels an image
This is host set and allows a plug-in to differentiate between images. This is especially useful if a plugin caches analysed information about the image (for example motion vectors). The plugin can label the cached information with this identifier. If a user connects a different clip to the analysed input, or the image has changed in some way then the plugin can detect this via an identifier change and re-evaluate the cached information.
kOfxInteractPropBackgroundColour
— The background colour of the application behind an interact instance
#include "/ofxInteract.h" #define kOfxInteractPropBackgroundColour "OfxInteractPropBackgroundColour"
This is a property that belongs to the read only on the interact instance and in argument to the kOfxInteractActionDraw
action.
kOfxInteractPropBitDepth
— Indicates whether the dits per component in the interact's openGL frame buffer
#include "/ofxInteract.h" #define kOfxInteractPropBitDepth "OfxInteractPropBitDepth"
kOfxInteractPropHasAlpha
— Indicates whether the interact's frame buffer has an alpha component or not
#include "/ofxInteract.h" #define kOfxInteractPropHasAlpha "OfxInteractPropHasAlpha"
kOfxInteractPropPenPosition
— The position of the pen in an interact.
#include "/ofxInteract.h" #define kOfxInteractPropPenPosition "OfxInteractPropPenPosition"
This is a property that belongs to the read only in argument to the kOfxInteractActionPenMotion
, kOfxInteractActionPenDown
and kOfxInteractActionPenUp
actions.
kOfxInteractPropPenPressure
— The pressure of the pen in an interact.
#include "/ofxInteract.h" #define kOfxInteractPropPenPressure "OfxInteractPropPenPressure"
This is a property that belongs to the read only in argument to the kOfxInteractActionPenMotion
, kOfxInteractActionPenDown
and kOfxInteractActionPenUp
actions.
kOfxInteractPropPenViewportPosition
— The position of the pen in an interact in viewport coordinates.
#include "/ofxInteract.h" #define kOfxInteractPropPenViewportPosition "OfxInteractPropPenViewportPosition"
This is a property that belongs to the read only in argument to the kOfxInteractActionPenMotion
, kOfxInteractActionPenDown
and kOfxInteractActionPenUp
actions.
kOfxInteractPropPixelScale
— The size of a real screen pixel under the interact's canonical projection.
#include "/ofxInteract.h" #define kOfxInteractPropPixelScale "OfxInteractPropPixelScale"
kOfxInteractPropSlaveToParam
— The set of parameters on which a value change will trigger a redraw for an interact.
#include "/ofxInteract.h" #define kOfxInteractPropSlaveToParam "OfxInteractPropSlaveToParam"
The set of parameters on which a value change will trigger a redraw for an interact.
If the interact is representing the state of some set of OFX parameters, then is will need to be redrawn if any of those parameters' values change. This multi-dimensional property links such parameters to the interact.
The interact can be slaved to multiple parameters (setting index 0, then index 1 etc...)
kOfxInteractPropSuggestedColour
— The suggested colour to draw a widget in an interact, typically for overlays.
#include "/ofxInteract.h" #define kOfxInteractPropSuggestedColour "OfxInteractPropSuggestedColour"
The suggested colour to draw a widget in an interact, typically for overlays.
Some applications allow the user to specify colours of any overlay via a colour picker, this property represents the value of that colour. Plugins are at liberty to use this or not when they draw an overlay.
If a host does not support such a colour, it should return kOfxStatReplyDefault
kOfxOpenGLPropPixelDepth
— Indicates the bit depths supported by a plug-in during OpenGL renders.
#include "/ofxOpenGLRender.h" #define kOfxOpenGLPropPixelDepth "OfxOpenGLPropPixelDepth"
Indicates the bit depths supported by a plug-in during OpenGL renders.
This is analogous to kOfxImageEffectPropSupportedPixelDepths
. When a
plug-in sets this property, the host will try to provide buffers/textures
in one of the supported formats. Additionally, the target buffers where
the plug-in renders to will be set to one of the supported formats.
Unlike kOfxImageEffectPropSupportedPixelDepths
, this property is
optional. Shader-based effects might not really care about any
format specifics when using OpenGL textures, so they can leave this unset
and allow the host the decide the format.
image)
kOfxParamHostPropMaxPages
— Indicates the maximum number of parameter pages.
#include "/ofxParam.h" #define kOfxParamHostPropMaxPages "OfxParamHostPropMaxPages"
kOfxParamHostPropMaxParameters
— Indicates the maximum numbers of parameters available on the host.
#include "/ofxParam.h" #define kOfxParamHostPropMaxParameters "OfxParamHostPropMaxParameters"
kOfxParamHostPropPageRowColumnCount
— This indicates the number of parameter rows and coloumns on a page.
#include "/ofxParam.h" #define kOfxParamHostPropPageRowColumnCount "OfxParamHostPropPageRowColumnCount"
kOfxParamHostPropSupportsBooleanAnimation
— Indicates if the host supports animation of boolean params
#include "/ofxParam.h" #define kOfxParamHostPropSupportsBooleanAnimation "OfxParamHostPropSupportsBooleanAnimation"
kOfxParamHostPropSupportsChoiceAnimation
— Indicates if the host supports animation of choice params
#include "/ofxParam.h" #define kOfxParamHostPropSupportsChoiceAnimation "OfxParamHostPropSupportsChoiceAnimation"
kOfxParamHostPropSupportsCustomAnimation
— Indicates if the host supports animation of custom parameters
#include "/ofxParam.h" #define kOfxParamHostPropSupportsCustomAnimation "OfxParamHostPropSupportsCustomAnimation"
kOfxParamHostPropSupportsCustomInteract
— Indicates if the host supports custom interacts for parameters
#include "/ofxParam.h" #define kOfxParamHostPropSupportsCustomInteract "OfxParamHostPropSupportsCustomInteract"
kOfxParamHostPropSupportsParametricAnimation
— Property on the host to indicate support for parametric parameter animation.
#include "/ofxParametricParam.h" #define kOfxParamHostPropSupportsParametricAnimation "OfxParamHostPropSupportsParametricAnimation"
kOfxParamHostPropSupportsStringAnimation
— Indicates if the host supports animation of string params
#include "/ofxParam.h" #define kOfxParamHostPropSupportsStringAnimation "OfxParamHostPropSupportsStringAnimation"
kOfxParamPropAnimates
— Flags whether a parameter can animate.
#include "/ofxParam.h" #define kOfxParamPropAnimates "OfxParamPropAnimates"
kOfxParamPropCacheInvalidation
— Specifies how modifying the value of a param will affect any output of an effect over time.
#include "/ofxParam.h" #define kOfxParamPropCacheInvalidation "OfxParamPropCacheInvalidation"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read only),.
This must be one of
kOfxParamInvalidateValueChange
kOfxParamInvalidateValueChangeToEnd
kOfxParamInvalidateAll
Specifies how modifying the value of a param will affect any output of an effect over time.
Imagine an effect with an animating parameter in a host that caches rendered output. Think of the what happens when you add a new key frame.
kOfxParamPropCanUndo
— Flags whether changes to a parameter should be put on the undo/redo stack
#include "/ofxParam.h" #define kOfxParamPropCanUndo "OfxParamPropCanUndo"
kOfxParamPropChoiceOption
— Set an option in a choice parameter.
#include "/ofxParam.h" #define kOfxParamPropChoiceOption "OfxParamPropChoiceOption"
kOfxParamPropCustomInterpCallbackV1
— A pointer to a custom parameter's interpolation function.
#include "/ofxParam.h" #define kOfxParamPropCustomInterpCallbackV1 "OfxParamPropCustomCallbackV1"
kOfxParamPropCustomValue
— Used by interpolating custom parameters to get and set interpolated values.
#include "/ofxParam.h" #define kOfxParamPropCustomValue "OfxParamPropCustomValue"
This is a property that belongs to the plugin string parameter descriptor (read/write) and instance (read only),.
Used by interpolating custom parameters to get and set interpolated values.
This property is on the inArgs property and outArgs property of a OfxCustomParamInterpFuncV1
and in both cases contains the encoded value of a custom parameter. As an inArgs property it will have two values, being the two keyframes to interpolate. As an outArgs property it will have a single value and the plugin should fill this with the encoded interpolated value of the parameter.
kOfxParamPropDataPtr
— A private data pointer that the plug-in can store its own data behind.
#include "/ofxParam.h" #define kOfxParamPropDataPtr "OfxParamPropDataPtr"
kOfxParamPropDefault
— The default value of a parameter.
#include "/ofxParam.h" #define kOfxParamPropDefault "OfxParamPropDefault"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write only),.
The default value of a parameter.
The exact type and dimension is dependant on the type of the parameter. These are....
kOfxParamTypeInteger
- integer property of one dimensionkOfxParamTypeDouble
- double property of one dimensionkOfxParamTypeBoolean
- integer property of one dimensionkOfxParamTypeChoice
- integer property of one dimensionkOfxParamTypeRGBA
- double property of four dimensionskOfxParamTypeRGB
- double property of three dimensionskOfxParamTypeDouble2D
- double property of two dimensionskOfxParamTypeInteger2D
- integer property of two dimensionskOfxParamTypeDouble3D
- double property of three dimensionskOfxParamTypeInteger3D
- integer property of three dimensionskOfxParamTypeString
- string property of one dimensionkOfxParamTypeCustom
- string property of one dimensionkOfxParamTypeGroup
- does not have this propertykOfxParamTypePage
- does not have this propertykOfxParamTypePushButton
- does not have this property
kOfxParamPropDefaultCoordinateSystem
— Describes in which coordinate system a spatial double parameter's default value is specified.
#include "/ofxParam.h" #define kOfxParamPropDefaultCoordinateSystem "OfxParamPropDefaultCoordinateSystem"
This is a property that belongs to the Non normalised spatial double parameters, ie: any double param who's kOfxParamPropDoubleType
is set to one of....
This must be one of
Describes in which coordinate system a spatial double parameter's default value is specified.
This allows a spatial param to specify what its default is, so by saying normalised and "0.5" it would be in the 'middle', by saying canonical and 100 it would be at value 100 independent of the size of the image being applied to.
kOfxParamPropDigits
— How many digits after a decimal point to display for a double param in a GUI.
#include "/ofxParam.h" #define kOfxParamPropDigits "OfxParamPropDigits"
kOfxParamPropDimensionLabel
— Label for individual dimensions on a multidimensional numeric parameter.
#include "/ofxParam.h" #define kOfxParamPropDimensionLabel "OfxParamPropDimensionLabel"
kOfxParamPropDisplayMax
— The maximum value for a numeric parameter on any user interface.
#include "/ofxParam.h" #define kOfxParamPropDisplayMax "OfxParamPropDisplayMax"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write),.
kOfxParamPropDisplayMin
— The minimum value for a numeric parameter on any user interface.
#include "/ofxParam.h" #define kOfxParamPropDisplayMin "OfxParamPropDisplayMin"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write),.
kOfxParamPropDoubleType
— Describes how the double parameter should be interpreted by a host.
#include "/ofxParam.h" #define kOfxParamPropDoubleType "OfxParamPropDoubleType"
This is a property that belongs to the 1D, 2D and 3D float plugin parameter descriptor (read/write) and instance (read only),.
This must be one of
kOfxParamDoubleTypePlain
- parameter has no special interpretation,kOfxParamDoubleTypeAngle
- parameter is to be interpretted as an angle,kOfxParamDoubleTypeScale
- parameter is to be interpretted as a scale factor,kOfxParamDoubleTypeTime
- parameter represents a time value (1D only),kOfxParamDoubleTypeAbsoluteTime
- parameter represents an absolute time value (1D only),
Describes how the double parameter should be interpreted by a host.
kOfxParamDoubleTypeX
- size wrt to the project's X dimension (1D only), in canonical coordinates,kOfxParamDoubleTypeXAbsolute
- absolute position on the X axis (1D only), in canonical coordinates,kOfxParamDoubleTypeY
- size wrt to the project's Y dimension(1D only), in canonical coordinates,kOfxParamDoubleTypeYAbsolute
- absolute position on the Y axis (1D only), in canonical coordinates,kOfxParamDoubleTypeXY
- size in 2D (2D only), in canonical coordinates,kOfxParamDoubleTypeXYAbsolute
- an absolute position on the image plane, in canonical coordinates.
Double parameters can be interpreted in several different ways, this property tells the host how to do so and thus gives hints as to the interface of the parameter.
kOfxParamPropEnabled
— Used to enable a parameter in the user interface.
#include "/ofxParam.h" #define kOfxParamPropEnabled "OfxParamPropEnabled"
kOfxParamPropEvaluateOnChange
— Flags whether changing a parameter's value forces an evalution (ie: render),
#include "/ofxParam.h" #define kOfxParamPropEvaluateOnChange "OfxParamPropEvaluateOnChange"
kOfxParamPropGroupOpen
— Whether the initial state of a group is open or closed in a hierarchical layout.
#include "/ofxParam.h" #define kOfxParamPropGroupOpen "OfxParamPropGroupOpen"
kOfxParamPropHasHostOverlayHandle
— A flag to indicate if there is a host overlay UI handle for the given parameter.
#include "/ofxParam.h" #define kOfxParamPropHasHostOverlayHandle "OfxParamPropHasHostOverlayHandle"
kOfxParamPropHint
— A hint to the user as to how the parameter is to be used.
#include "/ofxParam.h" #define kOfxParamPropHint "OfxParamPropHint"
kOfxParamPropIncrement
— The granularity of a slider used to represent a numeric parameter.
#include "/ofxParam.h" #define kOfxParamPropIncrement "OfxParamPropIncrement"
kOfxParamPropInteractMinimumSize
— The minimum size of a parameter's custom interface, in screen pixels.
#include "/ofxParam.h" #define kOfxParamPropInteractMinimumSize "OfxParamPropInteractMinimumSize"
kOfxParamPropInteractPreferedSize
— The preferred size of a parameter's custom interface.
#include "/ofxParam.h" #define kOfxParamPropInteractPreferedSize "OfxParamPropInteractPreferedSize"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read only).
The preferred size of a parameter's custom interface.
A host should attempt to set a parameter's custom interface on a parameter to be this size if possible, otherwise it will be of kOfxParamPropInteractSizeAspect
aspect but larger than kOfxParamPropInteractMinimumSize
.
kOfxParamPropInteractSize
— The size of a parameter instance's custom interface in screen pixels.
#include "/ofxParam.h" #define kOfxParamPropInteractSize "OfxParamPropInteractSize"
kOfxParamPropInteractSizeAspect
— The preferred aspect ratio of a parameter's custom interface.
#include "/ofxParam.h" #define kOfxParamPropInteractSizeAspect "OfxParamPropInteractSizeAspect"
kOfxParamPropInteractV1
— Overrides the parameter's standard user interface with the given interact.
#include "/ofxParam.h" #define kOfxParamPropInteractV1 "OfxParamPropInteractV1"
kOfxParamPropInterpolationAmount
— Property used by OfxCustomParamInterpFuncV1
to indicate the amount of interpolation to perform
#include "/ofxParam.h" #define kOfxParamPropInterpolationAmount "OfxParamPropInterpolationAmount"
This is a property that belongs to the inArgs parameter of a OfxCustomParamInterpFuncV1
(read only).
Property used by <link linkend="OfxCustomParamInterpFuncV1"><code>OfxCustomParamInterpFuncV1</code></link> to indicate the amount of interpolation to perform
This property indicates how far between the two kOfxParamPropCustomValue
keys to interpolate.
kOfxParamPropInterpolationTime
— Used by interpolating custom parameters to indicate the time a key occurs at.
#include "/ofxParam.h" #define kOfxParamPropInterpolationTime "OfxParamPropInterpolationTime"
This is a property that belongs to the inArgs parameter of a OfxCustomParamInterpFuncV1
(read only).
Used by interpolating custom parameters to indicate the time a key occurs at.
The two values indicate the absolute times the surrounding keyframes occur at. The keyframes are encoded in a kOfxParamPropCustomValue
property.
kOfxParamPropIsAnimating
— Flags whether a parameter is currently animating.
#include "/ofxParam.h" #define kOfxParamPropIsAnimating "OfxParamPropIsAnimating"
Flags whether a parameter is currently animating.
Set by a host on a parameter instance to indicate if the parameter has a non-constant value set on it. This can be as a consequence of animation or of scripting modifying the value, or of a parameter being connected to an expression in the host.
kOfxParamPropIsAutoKeying
— Will a value change on the parameter add automatic keyframes.
#include "/ofxParam.h" #define kOfxParamPropIsAutoKeying "OfxParamPropIsAutoKeying"
kOfxParamPropMax
— The maximum value for a numeric parameter.
#include "/ofxParam.h" #define kOfxParamPropMax "OfxParamPropMax"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write),.
kOfxParamPropMin
— The minimum value for a numeric parameter.
#include "/ofxParam.h" #define kOfxParamPropMin "OfxParamPropMin"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write),.
The default value is the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter).
The minimum value for a numeric parameter.
Setting this will also reset kOfxParamPropDisplayMin
.
kOfxParamPropPageChild
— The names of the parameters included in a page parameter.
#include "/ofxParam.h" #define kOfxParamPropPageChild "OfxParamPropPageChild"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read only).
the names of any parameter that is not a group or page, as well as kOfxParamPageSkipRow
and kOfxParamPageSkipColumn
The names of the parameters included in a page parameter.
This is a property on parameters of type kOfxParamTypePage
, and tells the page what parameters it contains. The parameters are added to the page from the top left, filling in columns as we go. The two pseudo param names kOfxParamPageSkipRow
and kOfxParamPageSkipColumn
are used to control layout.
Note parameters can appear in more than one page.
kOfxParamPropParametricDimension
— The dimension of a parametric param
#include "/ofxParametricParam.h" #define kOfxParamPropParametricDimension "OfxParamPropParametricDimension"
kOfxParamPropParametricInteractBackground
— Interact entry point to draw the background of a parametric parameter.
#include "/ofxParametricParam.h" #define kOfxParamPropParametricInteractBackground "OfxParamPropParametricInteractBackground"
This is a property that belongs to the plug-in parametric parameter descriptor (read/write) and instance (read only),.
Interact entry point to draw the background of a parametric parameter.
Defines a pointer to an interact which will be used to draw the background of a parametric parameter's user interface. None of the pen or keyboard actions can ever be called on the interact.
The openGL transform will be set so that it is an orthographic transform that maps directly to the 'parametric' space, so that 'x' represents the parametric position and 'y' represents the evaluated value.
kOfxParamPropParametricRange
— Property to indicate the min and max range of the parametric input value.
#include "/ofxParametricParam.h" #define kOfxParamPropParametricRange "OfxParamPropParametricRange"
kOfxParamPropParametricUIColour
— The colour of parametric param curve interface in any UI.
#include "/ofxParametricParam.h" #define kOfxParamPropParametricUIColour "OfxParamPropParametricUIColour"
This is a property that belongs to the parametric param descriptor (read/write) and instance (read only).
The colour of parametric param curve interface in any UI.
kOfxParamPropParametricDimension
)being interpretted as R, G and B of the colour for each curve drawn in the UI.
This sets the colour of a parametric param curve drawn a host user interface. A colour triple is needed for each dimension of the oparametric param.
If not set, the host should generally draw these in white.
kOfxParamPropParent
— The name of a parameter's parent group.
#include "/ofxParam.h" #define kOfxParamPropParent "OfxParamPropParent"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read only),.
The name of a parameter's parent group.
Hosts that have hierarchical layouts of their params use this to recursively group parameter.
By default parameters are added in order of declaration to the 'root' hierarchy. This property is used to reparent params to a predefined param of type kOfxParamTypeGroup
.
kOfxParamPropPersistant
— Flags whether the value of a parameter should persist.
#include "/ofxParam.h" #define kOfxParamPropPersistant "OfxParamPropPersistant"
kOfxParamPropPluginMayWrite
— Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis pass
#include "/ofxParam.h" #define kOfxParamPropPluginMayWrite "OfxParamPropPluginMayWrite"
kOfxParamPropScriptName
— The value to be used as the id of the parameter in a host scripting language.
#include "/ofxParam.h" #define kOfxParamPropScriptName "OfxParamPropScriptName"
kOfxParamPropSecret
— Flags whether a parameter should be exposed to a user,
#include "/ofxParam.h" #define kOfxParamPropSecret "OfxParamPropSecret"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write).
Flags whether a parameter should be exposed to a user,
If secret, a parameter is not exposed to a user in any interface, but should otherwise behave as a normal parameter.
Secret params are typically used to hide important state detail that would otherwise be unintelligible to a user, for example the result of a statical analysis that might need many parameters to store.
kOfxParamPropShowTimeMarker
— Enables the display of a time marker on the host's time line to indicate the value of the absolute time param.
#include "/ofxParam.h" #define kOfxParamPropShowTimeMarker "OfxParamPropShowTimeMarker"
This is a property that belongs to the plugin parameter descriptor (read/write) and instance (read/write).
Enables the display of a time marker on the host's time line to indicate the value of the absolute time param.
If a double parameter is has kOfxParamPropDoubleType
set to kOfxParamDoubleTypeAbsoluteTime
, then this indicates whether
any marker should be made visible on the host's time line.
kOfxParamPropStringFilePathExists
— Indicates string parameters of file or directory type need that file to exist already.
#include "/ofxParam.h" #define kOfxParamPropStringFilePathExists "OfxParamPropStringFilePathExists"
kOfxParamPropStringMode
— Used to indicate the type of a string parameter.
#include "/ofxParam.h" #define kOfxParamPropStringMode "OfxParamPropStringMode"
This is a property that belongs to the plugin string parameter descriptor (read/write) and instance (read only),.
This must be one of the following
kOfxParamStringIsSingleLine
kOfxParamStringIsMultiLine
kOfxParamStringIsFilePath
kOfxParamStringIsDirectoryPath
kOfxParamStringIsLabel
kOfxParamStringIsRichTextFormat
kOfxParamPropType
— The type of a parameter.
#include "/ofxParam.h" #define kOfxParamPropType "OfxParamPropType"
kOfxParamPropUseHostOverlayHandle
— A flag to indicate that the host should use a native UI overlay handle for the given parameter.
#include "/ofxParam.h" #define kOfxParamPropUseHostOverlayHandle "kOfxParamPropUseHostOverlayHandle"
This is a property that belongs to the plugin parameter descriptor (read/write only) and instance (read only).
A flag to indicate that the host should use a native UI overlay handle for the given parameter.
If set to 1, then a plugin is flaging to the host that the host should use a native UI overlay handle for the given parameter. A plugin can use this to keep a native look and feel for parameter handles. A plugin can use kOfxParamPropHasHostOverlayHandle
to see if handles are available on the given parameter.
kOfxPluginPropFilePath
— The file path to the plugin.
#include "/ofxCore.h" #define kOfxPluginPropFilePath "OfxPluginPropFilePath"
The file path to the plugin.
This is a string that indicates the file path where the plug-in was found by the host. The path is in the native path format for the host OS (eg: UNIX directory separators are forward slashes, Windows ones are backslashes).
The path is to the bundle location, see InstallationLocation. eg: '/usr/OFX/Plugins/AcmePlugins/AcmeFantasticPlugin.ofx.bundle'
kOfxPluginPropParamPageOrder
— Sets the parameter pages and order of pages.
#include "/ofxParam.h" #define kOfxPluginPropParamPageOrder "OfxPluginPropParamPageOrder"
kOfxPropAPIVersion
— Property on the host descriptor, saying what API version of the API is being implemented
#include "/ofxCore.h" #define kOfxPropAPIVersion "OfxPropAPIVersion"
Property on the host descriptor, saying what API version of the API is being implemented
This is a version string that will specify which version of the API is being implemented by a host. It can have multiple values. For example "1.0", "1.2.4" etc.....
If this is not present, it is safe to assume that the version of the API is "1.0".
kOfxPropChangeReason
— Indicates why a plug-in changed.
#include "/ofxCore.h" #define kOfxPropChangeReason "OfxPropChangeReason"
This is a property that belongs to the inArgs parameter on the kOfxActionInstanceChanged
action..
this can be...
kOfxChangeUserEdited
- the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resetskOfxChangePluginEdited
- the plug-in itself has changed the value of the object in some actionkOfxChangeTime
- the time has changed and this has affected the value of the object because it varies over time
Indicates why a plug-in changed.
Argument property for the kOfxActionInstanceChanged
action.
kOfxPropEffectInstance
— A pointer to an effect instance.
#include "/ofxCore.h" #define kOfxPropEffectInstance "OfxPropEffectInstance"
kOfxPropHostOSHandle
— A pointer to an operating system specific application handle.
#include "/ofxCore.h" #define kOfxPropHostOSHandle "OfxPropHostOSHandle"
A pointer to an operating system specific application handle.
Some plug-in vendor want raw OS specific handles back from the host so they can do interesting things with host OS APIs. Typically this is to control windowing properly on Microsoft Windows. This property returns the appropriate 'root' window handle on the current operating system. So on Windows this would be the hWnd of the application main window.
kOfxPropIcon
— If set this tells the host to use an icon instead of a label for some object in the interface.
#include "/ofxCore.h" #define kOfxPropIcon "OfxPropIcon"
If set this tells the host to use an icon instead of a label for some object in the interface.
The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon.
The first dimension, if set, will the name of and SVG file, the second a PNG file.
kOfxPropInstanceData
— A private data pointer that the plug-in can store its own data behind.
#include "/ofxCore.h" #define kOfxPropInstanceData "OfxPropInstanceData"
kOfxPropIsInteractive
— Indicates if a host is actively editing the effect with some GUI.
#include "/ofxCore.h" #define kOfxPropIsInteractive "OfxPropIsInteractive"
Indicates if a host is actively editing the effect with some GUI.
If false the effect currently has no interface, however this may be because the effect is loaded in a background render host, or it may be loaded on an interactive host that has not yet opened an editor for the effect.
The output of an effect should only ever depend on the state of its parameters, not on the interactive flag. The interactive flag is more a courtesy flag to let a plugin know that it has an interace. If a plugin want's to have its behaviour dependant on the interactive flag, it can always make a secret parameter which shadows the state if the flag.
kOfxPropKeyString
— This property encodes a single keypresses that generates a unicode code point. The value is stored as a UTF8 string.
#include "/ofxKeySyms.h" #define kOfxPropKeyString "kOfxPropKeyString"
This is a property that belongs to the an read only in argument for the actions kOfxInteractActionKeyDown
, kOfxInteractActionKeyUp
and kOfxInteractActionKeyRepeat
..
This property encodes a single keypresses that generates a unicode code point. The value is stored as a UTF8 string.
This property represents the UTF8 encode value of a single key press by a user in an OFX interact.
This property is associated with a kOfxPropKeySym
which represents an integer value for the key press. Some keys (for example arrow keys) have no UTF8 equivalant,
in which case this is set to the empty string "", and the associate kOfxPropKeySym
is set to the equivilant raw key press.
Some keys, especially on non-english language systems, may have a UTF8 value, but m not a keysym values, in these
cases, the keysym will have a value of kOfxKey_Unknown, but the kOfxPropKeyString
property will still be set with
the UTF8 value.
kOfxPropKeySym
— Property used to indicate which a key on the keyboard or a button on a button device has been pressed
#include "/ofxKeySyms.h" #define kOfxPropKeySym "kOfxPropKeySym"
This is a property that belongs to the an read only in argument for the actions kOfxInteractActionKeyDown
, kOfxInteractActionKeyUp
and kOfxInteractActionKeyRepeat
..
Property used to indicate which a key on the keyboard or a button on a button device has been pressed
This property represents a raw key press, it does not represent the 'character value' of the key.
This property is associated with a kOfxPropKeyString
property, which encodes the UTF8
value for the keypress/button press. Some keys (for example arrow keys) have no UTF8 equivalant.
Some keys, especially on non-english language systems, may have a UTF8 value, but m not a keysym values, in these
cases, the keysym will have a value of kOfxKey_Unknown, but the kOfxPropKeyString
property will still be set with
the UTF8 value.
kOfxPropLabel
— User visible name of an object.
#include "/ofxCore.h" #define kOfxPropLabel "OfxPropLabel"
This is a property that belongs to the on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases..
User visible name of an object.
The label is what a user sees on any interface in place of the object's name.
Note that resetting this will also reset kOfxPropShortLabel
and kOfxPropLongLabel
.
kOfxPropLongLabel
— Long user visible name of an object.
#include "/ofxCore.h" #define kOfxPropLongLabel "OfxPropLongLabel"
This is a property that belongs to the on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases..
The default value is initially kOfxPropName
, but will be reset if kOfxPropLabel
is changed..
kOfxPropName
— Unique name of an object.
#include "/ofxCore.h" #define kOfxPropName "OfxPropName"
This is a property that belongs to the on many objects (descriptors and instances), see PropertiesByObject (read only).
kOfxPropParamSetNeedsSyncing
— States whether the plugin needs to resync its private data
#include "/ofxParam.h" #define kOfxPropParamSetNeedsSyncing "OfxPropParamSetNeedsSyncing"
States whether the plugin needs to resync its private data
The plugin should set this flag to true whenever any internal state has not been flushed to the set of params.
The host will examine this property each time it does a copy or save operation on the instance. If it is set to 1, the host will call SyncPrivateData and then set it to zero before doing the copy/save. If it is set to 0, the host will assume that the param data correctly represents the private state, and will not call SyncPrivateData before copying/saving. If this property is not set, the host will always call SyncPrivateData before copying or saving the effect (as if the property were set to 1 -- but the host will not create or modify the property).
kOfxPropPluginDescription
— Description of the plug-in to a user.
#include "/ofxCore.h" #define kOfxPropPluginDescription "OfxPropPluginDescription"
kOfxPropShortLabel
— Short user visible name of an object.
#include "/ofxCore.h" #define kOfxPropShortLabel "OfxPropShortLabel"
This is a property that belongs to the on many objects (descriptors and instances), see PropertiesByObject. Typically readable and writable in most cases..
The default value is initially kOfxPropName
, but will be reset if kOfxPropLabel
is changed..
kOfxPropTime
— General property used to get/set the time of something.
#include "/ofxCore.h" #define kOfxPropTime "OfxPropTime"
kOfxPropType
— General property, used to identify the kind of an object behind a handle
#include "/ofxCore.h" #define kOfxPropType "OfxPropType"
kOfxPropVersion
— Identifies a specific version of a host or plugin.
#include "/ofxCore.h" #define kOfxPropVersion "OfxPropVersion"
This is a property that belongs to the host descriptor (read only), plugin descriptor (read/write).
Identifies a specific version of a host or plugin.
This is a multi dimensional integer property that represents the version of a host (host descriptor), or plugin (plugin descriptor). These represent a version number of the form '1.2.3.4', with each dimension adding another 'dot' on the right.
A version is considered to be more recent than another if its ordered set of values is lexicographically greater than another, reading left to right. (ie: 1.2.4 is smaller than 1.2.6). Also, if the number of dimensions is different, then the values of the missing dimensions are considered to be zero (so 1.2.4 is greater than 1.2).
kOfxPropVersionLabel
— Unique user readable version string of a plugin or host.
#include "/ofxCore.h" #define kOfxPropVersionLabel "OfxPropVersionLabel"
This is a property that belongs to the host descriptor (read only), plugin descriptor (read/write).
Unique user readable version string of a plugin or host.
This is purely for user feedback, a plugin or host should use kOfxPropVersion
if they need
to check for specific versions.
Status codes are returned by most functions in OFX suites and all
plug-in actions to indicate the sucess or failure of the operation. All
status codes are defined in ofxCore.h
and
#defined
to be integers.
OfxStatus — type returned to indicate success or failure of an operation.
#include "ofxCore.h" typedef int OfxStatus;
kOfxStatOK — (0), indicates an operation completed sucessfully.
#include "ofxCore.h" #define kOfxStatOK 0
kOfxStatFailed — (1), indicates a failed operation.
#include "ofxCore.h" #define kOfxStatFailed ((int)1)
kOfxStatErrFatal — (2), indicates a fatal operation.
#include "ofxCore.h" #define kOfxStatErrFatal ((int)2)
kOfxStatErrUnknown — (3), status error code for an unknown object.
#include "ofxCore.h" #define kOfxStatErrUnknown ((int)3)
This error is returned when an operation is attempted on an unknown object or an unknown object was requested. For example, a host may not support a property on an object because it is written to a slightly earlier version of an API, in which case it should return with kOfxStatErrUnknown.
kOfxStatErrMissingHostFeature — (4) returned by a plug-in if a host is inadequate.
#include "ofxCore.h" #define kOfxStatErrMissingHostFeature ((int) 4)
This status is returned by plug-ins'
mainEntry
if the host is missing a feature they
need to operate. For example, a plug-in may need an overlay GUI to
operate sucessfully, which is an optional feature.
This should be returned from the
kOfxActionLoad
,
kOfxActionDescribe
or
kOfxImageEffectActionDescribeInContext
actions, so
a host can unload the plug-in before it attempts to create an instance
of the plug-in.
kOfxStatErrUnsupported — (5), error code for an unsupported feature/operation
#include "ofxCore.h" #define kOfxStatErrUnsupported ((int) 5)
kOfxStatErrExists — (6), something already exists.
#include "ofxCore.h" #define kOfxStatErrExists ((int) 6)
kOfxStatErrFormat — (7), indicates an incorrect format.
#include "ofxCore.h" #define kOfxStatErrFormat ((int) 7)
kOfxStatErrMemory — (8), a memory shortage was encountered.
#include "ofxCore.h" #define kOfxStatErrMemory ((int) 8)
kOfxStatErrBadHandle — (9), indicates a bad handle
#include "ofxCore.h" #define kOfxStatErrBadHandle ((int) 9)
kOfxStatErrBadIndex — (10), a property index was invalid.
#include "ofxCore.h" #define kOfxStatErrBadIndex ((int)10)
kOfxStatErrValue — (11), an illegal value was passed.
#include "ofxCore.h" #define kOfxStatErrValue ((int) 11)
kOfxStatReplyYes — (12), returned to indicate a positive response.
#include "ofxCore.h" #define kOfxStatReplyYes ((int) 12)
kOfxStatReplyNo — (13), returned to indicate a negative response.
#include "ofxCore.h" #define kOfxStatReplyNo ((int) 13)
kOfxStatReplyDefault — (14), indicates the default should occur.
#include "ofxCore.h" #define kOfxStatReplyDefault ((int) 14)
This is returned by plug-ins' mainEntry
function to indicate that they did not trap the action passed and that
the default operation should occur. It does not imply failure.
A subtle but specific use of this is made by plug-in interacts
GUIs. If they return this value from any event actions (eg:
kOfxInteractActionPenDown
), then the host is free
to pass the event on to another GUI element in the interact
window.
This chapter lists the changes and extensions between the 1.1 version of the API and the 1.2 version of the API. The extension are backwards compatible, so that a 1.2 plugin will run on an earlier version of a host, provided a bit of care is taken. A 1.2 host will easily support a plugin written to an earlier API.
A new architecture directory was added to the bundle heirarchy to specifically contain Mac OSX 64 bit builds. The current 'MacOS' architecture is a fall back for 32 bit only and/or universal binary builds.
Three new properties are provided to identify and version a plugin and/or host. These are...
Before 1.2 there was no way to identify the version of a host application, which a plugin could use to work around known bugs and problems in known versions. kOfxPropVersion provides a way to do that.
Group parameters are typically displayed in a hierarchical manner on many applications, with 'twirlies' to open and close the group. The new property kOfxParamPropGroupOpen is used to specify if a group parameter should be initially open or closed.
Some applications are able to display icons instead of text when labelling parameters. The new property, kOfxPropIcon, specifies an SVG file and/or a PNG file to use as an icon in such host applications.
A new message suite has been specified, OfxMessageSuiteV2, this adds two new functions. One to set a persistent message on an effect, and a second to clear that message. This would typically be used to flag an error on an effects.
A new property has been added to parameter sets, kOfxPropParamSetNeedsSyncing. This is used by plugins with internal data structures that need syncing back to parameters for persistance and so on. This property should be set whenever the plugin changes it's internal state to inform the host that a sync will be required before the next serialisation of the plugin. Without this property, the host would have to continually force the plugin to sync it's private data, whether that was a redundant operation or not. For large data sets, this can be a significant overhead.
Flagging sequential rendering has been slightly modified. The kOfxImageEffectInstancePropSequentialRender
property has had a third allowed state added, which indicate that a plugin would prefer to be sequentially rendered if possible, but need not be.
The kOfxImageEffectInstancePropSequentialRender
propery has also been added to the host descriptor, to indicate whether the host can support sequential rendering.
The new property kOfxImageEffectPropSequentialRenderStatus
is now passed to the render actions to indicate that a host is currently sequentially rendering or not.
A new property has been added to flag a render as being in response to an interactive change by a user, as opposed to a batch render. This is kOfxImageEffectPropInteractiveRenderStatus.
A new property has been added to allow a plugin to request the host operating system specific application handle (ie: on Windows (tm) this would be the application's root hWnd). This is kOfxPropHostOSHandle
.
Normalised double parameters have proved to be more of a problem than expected. The major idea was to provide resolution independence for spatial parameters. However, in practice, having to specify parameters as a fraction of a yet to be determined resolution is problematic. For example, if you want to set something to be explicitly '20', there is no way of doing that. The main problem stems from normalised params conflating two separate issues, flagging to the host that a parameter was spatial, and being able to specify defaults in a normalised co-ordinate system.
With 1.2 new spatial double parameter types are defined. These have their values manipulated in cannonical coordinates, however, they have an option to specify their default values in a normalise coordinate system. These are....
These new double parameter types are....
kOfxParamDoubleTypeX
- a size in the X dimension dimension (1D only), new for 1.2kOfxParamDoubleTypeXAbsolute
- a position in the X dimension (1D only), new for 1.2kOfxParamDoubleTypeY
- a size in the Y dimension dimension (1D only), new for 1.2kOfxParamDoubleTypeYAbsolute
- a position in the X dimension (1D only), new for 1.2 kOfxParamDoubleTypeXY
- a size in the X and Y dimension (2D only), new for 1.2kOfxParamDoubleTypeXYAbsolute
- a position in the X and Y dimension (2D only), new for 1.2
These new parameter types can set their defaults in one of two coordinate systems, the property kOfxParamPropDefaultCoordinateSystem
. Specifies the coordinate system the default value is being specified in.
Plugins can check kOfxPropAPIVersion to see if these new parameter types are supported