Document version 0.5
Copyright © 2006 Bruno Nicoletti
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 it's 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 dataOfxParameterSuiteV1::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 purposesOfxMemorySuiteV1::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 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.kOfxImageEffectInstancePropEffectDuration
— The duration of the effectkOfxImageEffectInstancePropSequentialRender
— Says whether an effect needs to be rendered sequentially or notkOfxImageEffectPluginPropFieldRenderTwiceAlways
— 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 renderskOfxImageEffectPropInAnalysis
— Indicates whether an effect is performing an analysis pass.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.kOfxImageEffectPropRenderScale
— The proxy render scale currently being applied.kOfxImageEffectPropRenderWindow
— The region to be rendered.kOfxImageEffectPropSetableFielding
— 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.kOfxInteractPropPixelScale
— The size of a real screen pixel under the interact's cannonical projection.kOfxInteractPropSlaveToParam
— The set of parameters on which a value change will trigger a redraw for an interact.kOfxInteractPropViewportSize
— The size of an interact's openGL viewportkOfxParamHostPropMaxPages
— 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 parameterskOfxParamHostPropSupportsStringAnimation
— 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 it's own data behind.kOfxParamPropDefault
— The default value of a parameter.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),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 prefered size of a parameter's custom interface.kOfxParamPropInteractSize
— The size of a parameter instance's custom interface in screen pixels.kOfxParamPropInteractSizeAspect
— The prefered 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.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.kOfxPluginPropFilePath
— The file path to the plugin.kOfxPluginPropParamPageOrder
— Sets the parameter pages and order of pages.kOfxPropChangeReason
— Indicates why a plug-in changed.kOfxPropEffectInstance
— A pointer to an effect instance.kOfxPropInstanceData
— A private data pointer that the plug-in can store it's 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.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 handleThis is a mostly complete reference guide to the OFX image effect plugin architecture.
THINGS TO DO!
OFX is actually several things. At its the base it is a generic plug-in architecture with 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 inOFX 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 functions 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 rguments 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 and instance, e.g: the object passed to the kOfxActionCreateInstance action.
The OFX Image Effect Plug-in API is a 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 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 the 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,
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 applications.
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 a plug-in and how to boostrap the two way comminications. 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 who 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
. 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
.
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 cstring 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 it's 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,
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 figured 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 five parameters up 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 from. 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 cstring
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 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 sequences 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 desposed 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 considerred to be static constant strings, when passed across the API the host/plug-in recieving the string neither needs to duplicate or 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
- key symbols used by 'Interacts' to represent keyboard events,
ofxMemory.h
- provides a simple memory allocation suite,
ofxMessage.h
- 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 defined via blind data handles, other via property sets, or 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 set 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 associated with it
a set of properties, a set of image clips and a set of properties. 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-ins
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.2
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 existance 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 values 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 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 are used to define the existance 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 associate 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 and 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 ontop 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 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 case 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 case 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...
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
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...
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.
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 \b 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 the host. It is defined in the ofxParam.h header file.
A plugin needs to define it's parameters during it's 'describe' call. It does this with the OfxParameterSuiteV1::paramDefine
function, which returns a handle to a parameter description. Parameters cannot 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. For more information on properties see \ref PropertiesPage.
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
or by paramDefine outside of a describe action will be a working instance of a parameter, you can still set (some) properties of the parameter, but all the get/set value functions are now useable.
There are sixteen 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 4
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 coverred in \ref ParametersInterfacesPagedLayouts.
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. For more information see \ref ExternalResourcesPage.
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 \b 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),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.
There are several values of the kOfxParamPropDoubleType
that allow a double parameters (1, 2 and 3 dimensional) to be made 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 \ref ImageEffectsCoordinates from more on coordinate systems and how to scale parameters.
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.
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 plugin's need to cache interframe behaviour to work correctly, for example: a particle system, an image stabilisation system.
In such cases a plugin instance will need to be rendered sequentially from frame 0 on single instance in a single computer.
Such plugins should set the
kOfxImageEffectInstancePropSequentialRender
instance property.
This property can be set to...
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 and hack an approximation together for UI purposes. When eventually rendering the sequence, the host must ignore all frames rendered out of order and not cache them for use in the final result.
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 \em 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
. 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.
For more details on on how to describe an OFX Image Effect, see the chapter Describing Image Effects. 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.
For more details on on how to describe an OFX Image Effect, see the chapter Describing Image Effects.
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...
kOfxImageEffectPropRegionOfDefinitiong
, 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 kOfxImageEffectPropTemporalClipAccessg
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 acion 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 renderredoutArgs
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 calloutArgs
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 calloutArgs
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,kOfxImagePropPixelAspectRatio
, 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,kOfxInteractPropViewportSize
- the openGL viewport size for the instancekOfxInteractPropPixelScale
- 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,kOfxInteractPropViewportSize
- the openGL viewport size for the instancekOfxInteractPropPixelScale
- 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,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,kOfxInteractPropViewportSize
- the openGL viewport size for the instancekOfxInteractPropPixelScale
- 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,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,kOfxInteractPropViewportSize
- the openGL viewport size for the instancekOfxInteractPropPixelScale
- 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,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,kOfxInteractPropViewportSize
- the openGL viewport size for the instance,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,kOfxInteractPropViewportSize
- the openGL viewport size for the instance,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 **value); OfxStatus (*propSetStringN) (OfxPropertySetHandle properties, const char *property, int count, const char **value); OfxStatus (*propSetDoubleN) (OfxPropertySetHandle properties, const char *property, int count, double *value); OfxStatus (*propSetIntN) (OfxPropertySetHandle properties, const char *property, int count, 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 **value) ; |
OfxPropertySuiteV1::propSetStringN
— Set multiple values of a string property
#include "ofxProperty.h"
OfxStatus(*propSetStringN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
const char **value) ; |
OfxPropertySuiteV1::propSetDoubleN
— Set multiple values of a double property
#include "ofxProperty.h"
OfxStatus(*propSetDoubleN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
double *value) ; |
OfxPropertySuiteV1::propSetIntN
— Set multiple values of an int property
#include "ofxProperty.h"
OfxStatus(*propSetIntN)( | OfxPropertySetHandleproperties, |
const char *property, | |
intcount, | |
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 it's 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, 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
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, | |
OfxRectD *region, | |
OfxPropertySetHandle *imageHandle) ; |
An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.
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) ; |
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.
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
.
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
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.
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.
OfxImageEffectSuiteV1::imageMemoryAlloc
, null is placed in returnedPtr
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, 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.
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, |
...) ; |
OfxParameterSuiteV1::paramGetValueAtTime
— Gets the value of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramGetValueAtTime)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
OfxParameterSuiteV1::paramGetDerivative
— Gets the derivative of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramGetDerivative)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
OfxParameterSuiteV1::paramGetIntegral
— Gets the integral of a parameter over a specific time range,
#include "ofxParam.h"
OfxStatus(*paramGetIntegral)( | OfxParamHandle paramHandle, |
OfxTimetime1, | |
OfxTimetime2, | |
...) ; |
OfxParameterSuiteV1::paramSetValue
— Sets the current value of a parameter
#include "ofxParam.h"
OfxStatus(*paramSetValue)( | OfxParamHandle paramHandle, |
...) ; |
OfxParameterSuiteV1::paramSetValueAtTime
— Keyframes the value of a parameter at a specific time.
#include "ofxParam.h"
OfxStatus(*paramSetValueAtTime)( | OfxParamHandle paramHandle, |
OfxTimetime, | |
...) ; |
OfxParameterSuiteV1::paramGetNumKeys
— Returns the number of keyframes in the parameter
#include "ofxParam.h"
OfxStatus(*paramGetNumKeys)( | OfxParamHandle paramHandle, |
unsigned int *numberOfKeys) ; |
This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
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) ; |
This function can be called the kOfxActionInstanceChanged
action and during image effect analysis render passes.
OfxParameterSuiteV1::paramCopy
— Copies one parameter to another, including any animation etc...
#include "ofxParam.h"
OfxStatus(*paramCopy)( | OfxParamHandle paramTo, |
OfxParamHandle paramFrom, | |
OfxTimedstOffset, | |
OfxRangeD *frameRange) ; |
OfxParameterSuiteV1::paramEditBegin
— Used to group any parameter changes for undo/redo purposes
#include "ofxParam.h"
OfxStatus(*paramEditBegin)( | OfxParamSetHandleparamSet, |
const char *name) ; |
OfxParameterSuiteV1::paramEditEnd
— Used to group any parameter changes for undo/redo purposes
#include "ofxParam.h"
OfxStatus(*paramEditEnd)( | OfxParamSetHandleparamSet) ; |
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.
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;
OfxMemorySuiteV1::memoryAlloc
— Allocate memory.
#include "ofxMemory.h"
OfxStatus(*memoryAlloc)( | void *handle, |
size_tnBytes, | |
void **allocatedData) ; |
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)(const 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)
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
.
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)( | const 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) ; |
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) ; |
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"
kOfxImageEffectInstancePropEffectDuration
— The duration of the effect
#include "/ofxImageEffect.h" #define kOfxImageEffectInstancePropEffectDuration "OfxImageEffectInstancePropEffectDuration"
kOfxImageEffectInstancePropSequentialRender
— Says whether an effect needs to be rendered sequentially or not
#include "/ofxImageEffect.h" #define kOfxImageEffectInstancePropSequentialRender "OfxImageEffectInstancePropSequentialRender"
This is a property that belongs to the plugin descriptor (read/write) or plugin instance (read/write).
This must be one of
Says whether an effect needs to be rendered sequentially or not
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.
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.
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).
kOfxImageEffectPropInAnalysis
— Indicates whether an effect is performing an analysis pass.
#include "/ofxImageEffect.h" #define kOfxImageEffectPropInAnalysis "OfxImageEffectPropInAnalysis"
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 ProjectCoordinateSystems 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 ProjectCoordinateSystems 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 ProjectCoordinateSystems 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.
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,.
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
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).
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.
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 it's 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.
kOfxInteractPropPixelScale
— The size of a real screen pixel under the interact's cannonical 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...)
kOfxInteractPropViewportSize
— The size of an interact's openGL viewport
#include "/ofxInteract.h" #define kOfxInteractPropViewportSize "OfxInteractPropViewport"
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"
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 it's 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
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),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.
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"
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 prefered 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 prefered 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 prefered 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 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 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"
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.
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),.
kOfxParamPropType
— The type of a parameter.
#include "/ofxParam.h" #define kOfxParamPropType "OfxParamPropType"
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"
kOfxPropChangeReason
— Indicates why a plug-in changed.
#include "/ofxCore.h" #define kOfxPropChangeReason "OfxPropChangeReason"
This is a property that belongs to the 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"
kOfxPropInstanceData
— A private data pointer that the plug-in can store it's 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 it's 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).
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"
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 positive 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.