The OFX Image Effect Plug-in API, 1.1, Programming Reference. Including extension.

Bruno Nicoletti

Document version 0.6


Table of Contents

Foreword
1. Structure of The OFX and the Image Effect API
The Structure Of The Generic OFX API
OFX APIs
The OFX Image Effect API.
2. The Generic Core API
Packaging OFX Plug-ins
Binary Types
Installation Directory Hierarchy
Installation Location
Plug-in Icons
Externally Specified Resources
OFX Include Files
Identifying and Loading Plug-ins
OfxGetNumberOfPlugins
OfxGetPlugin
The OfxPlugin Struct
Interpreting the OfxPlugin Struct
The OfxHost Struct
The Plug-in Main Entry Point And Actions
Suites
Sequences of Operations Required to Load a Plug-in
Who Owns The Data?
Strings
3. The Image Effect API
Introduction
Image Effect API Header Files
Actions Used by the API
Main Objects Used by the API
Host Descriptors
Effects
Effect Descriptors
Effect Instances
Clips
Clip Descriptors
Clip Instances
Parameters
Parameter Set Descriptors
Parameter Descriptors
Parameter Set Instances
Parameter Instances
Image Instances
Interacts
Interact Descriptors
Interact Instances
4. Image Processing Architectures
The Image Plane
Regions of Definition
Infinite RoDs
Regions Of Interest
Tiled Rendering
Tree Based Architectures
Simpler Architectures
5. Image Effect Contexts
The Generator Context
The Filter Context
The Transition Context
The Paint Context
The Retimer Context
The General Context
Parameters Mandated In A Context
6. Thread and Recursion Safety
Recursive Actions
7. Coordinate Systems
Spatial Coordinates
Canonical Coordinates
Pixel Coordinates
Mapping Between The Spatial Coordinate Systems
The Normalized Coordinate System
Temporal Coordinates
8. Images and Clips
What Is An Image?
Defining Clips
Getting Images From Clips
Premultiplication And Alpha
Clips and Pixel Aspect Ratios
Allocating Your Own Images
9. Effect Parameters
Introduction
Defining Parameters
Parameter Types
Multidimensional Parameters
Integer Parameters
Double Parameters
Colour Parameters
Boolean Parameters
Choice Parameters
String Parameters
Group Parameters
Page Parameters
Custom Parameters
Push Button Parameters
Animation
Parameter Interfaces
Paged Parameter Editors
Parameter Undo/Redo
XML Resource Specification for Parameters
Parameter Persistance
Parameter Properties Whose Type Vary
Types of Double Parameters
Plain Double Parameters
Angle Double Parameters
Scale Double Parameters
Time Double Parameters
Absolute Time Double Parameters
Normalised Double Parameters
Double Parameters Defaults, Increments, Mins and Maxs
10. Rendering
Identity Effects
Rendering and The Get Region Actions
Multi-threaded Rendering
Rendering in a Symetric Multi Processing Enviroment
Rendering Sequential Effects
OFX : Fields and Field Rendering
Rendering In An Interactive Environment
11. Interacts
Overlay Interacts
Parameter Interacts
Interact Actions
12. Image Effect Clip Preferences
Frame Varying Effects
Continuously Sampled Effects
Specifying Pixel Depths
Specifying Pixel Components
Specifying Pixel Aspect Ratios
Specifying Fielding
Specifying Frame Rates
Specifying Premultiplication
13. Actions Passed to An Image Effect
The Generic Load Action
The Generic Unload Action
The Generic Describe Action
The Generic Create Instance Action
The Generic Destroy Instance Action
The Generic Begin/End Instance Changed Actions
The Generic Instance Changed Action
The Generic Purge Caches Action>
The Sync Private Data Action
The Generic Begin Instance Edit Action
The Generic End Instance Edit Action
The Describe In Context Action
The Get Region of Definition Action
The Get Regions Of Interest Action
The Get Frames Needed Action
The Is Identity Action
The Render Action
The Begin Sequence Render Action
The End Sequence Render Action
The Get Clip Preferences Action
The Get Time Domain Action
14. Actions Passed to an Interact
The Describe Action
The Create Instance Action
The Destroy Instance Action
The Draw Action
kOfxInteractActionPenMotion
kOfxInteractActionPenDown
kOfxInteractActionPenUp
kOfxInteractActionKeyDown
kOfxInteractActionKeyUp
kOfxInteractActionKeyRepeat
kOfxInteractActionGainFocus
kOfxInteractActionLoseFocus
15. Property Suite
OfxPropertySetHandle — Blind data type used to hold sets of properties
OfxPropertySuiteV1 — The OFX suite used to access properties on OFX objects.
OfxPropertySuiteV1::propSetPointer — Set a single value in a pointer property
OfxPropertySuiteV1::propSetString — Set a single value in a string property
OfxPropertySuiteV1::propSetDouble — Set a single value in a double property
OfxPropertySuiteV1::propSetInt — Set a single value in an int property
OfxPropertySuiteV1::propSetPointerN — Set multiple values of the pointer property
OfxPropertySuiteV1::propSetStringN — Set multiple values of a string property
OfxPropertySuiteV1::propSetDoubleN — Set multiple values of a double property
OfxPropertySuiteV1::propSetIntN — Set multiple values of an int property
OfxPropertySuiteV1::propGetPointer — Get a single value from a pointer property
OfxPropertySuiteV1::propGetString — Get a single value of a string property
OfxPropertySuiteV1::propGetDouble — Get a single value of a double property
OfxPropertySuiteV1::propGetInt — Get a single value of an int property
OfxPropertySuiteV1::propGetPointerN — Get multiple values of a pointer property
OfxPropertySuiteV1::propGetStringN — Get multiple values of a string property
OfxPropertySuiteV1::propGetDoubleN — Get multiple values of a double property
OfxPropertySuiteV1::propGetIntN — Get multiple values of an int property
OfxPropertySuiteV1::propReset — Resets all dimensions of a property to it's default value
OfxPropertySuiteV1::propGetDimension — Gets the dimension of the property
16. Image Effect Suite
OfxImageEffectSuiteV1 — The OFX suite for image effects
OfxImageEffectSuiteV1::getPropertySet — Retrieves the property set for the given image effect
OfxImageEffectSuiteV1::getParamSet — Retrieves the parameter set for the given image effect
OfxImageEffectSuiteV1::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 clip
OfxImageEffectSuiteV1::clipGetImage — Get a handle for an image in a clip at the indicated time and indicated region
OfxImageEffectSuiteV1::clipReleaseImage — Releases the image handle previously returned by clipGetImage
OfxImageEffectSuiteV1::clipGetRegionOfDefinition — Returns the spatial region of definition of the clip at the given time
OfxImageEffectSuiteV1::abort — Returns whether to abort processing or not.
OfxImageEffectSuiteV1::imageMemoryAlloc — Allocate memory from the host's image memory pool
OfxImageEffectSuiteV1::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 data
17. Progress Suite
OfxProgressSuiteV1 — A suite that provides progress feedback from a plugin to an application
OfxProgressSuiteV1::progressStart — Initiate a progress bar display.
OfxProgressSuiteV1::progressUpdate — Indicate how much of the processing task has been completed and reports on any abort status.
OfxProgressSuiteV1::progressEnd — Signal that we are finished with the progress meter.
18. Timeline Suite
OfxTimeLineSuiteV1 — Suite to control timelines
OfxTimeLineSuiteV1::getTime — Get the time value of the timeline that is controlling to the indicated effect.
OfxTimeLineSuiteV1::gotoTime — Move the timeline control to the indicated time.
OfxTimeLineSuiteV1::getTimeBounds — Get the current bounds on a timeline
19. Parameters Suite
OfxParameterSuiteV1 — The OFX suite used to define and manipulate user visible parameters
OfxParameterSuiteV1::paramDefine — Defines a new parameter of the given type in a describe action
OfxParameterSuiteV1::paramGetHandle — Retrieves the handle for a parameter in a given parameter set
OfxParameterSuiteV1::paramSetGetPropertySet — Retrieves the property set handle for the given parameter set
OfxParameterSuiteV1::paramGetPropertySet — Retrieves the property set handle for the given parameter
OfxParameterSuiteV1::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 parameter
OfxParameterSuiteV1::paramSetValueAtTime — Keyframes the value of a parameter at a specific time.
OfxParameterSuiteV1::paramGetNumKeys — Returns the number of keyframes in the parameter
OfxParameterSuiteV1::paramGetKeyTime — Returns the time of the nth key
OfxParameterSuiteV1::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 purposes
OfxParameterSuiteV1::paramEditEnd — Used to group any parameter changes for undo/redo purposes
OfxCustomParamInterpFuncV1 — Typedef for functions set as the ::kOfxParamPropCustomInterpCallbackV1 on custom params.
20. Memory Suite
OfxMemorySuiteV1 — The OFX suite that implements general purpose memory management.
OfxMemorySuiteV1::memoryAlloc — Allocate memory.
OfxMemorySuiteV1::memoryFree — Frees memory.
21. Multi Threading Suite
OfxThreadFunctionV1 — Typedef for functions passed to the multithreading suite
OfxMultiThreadSuiteV1 — OFX suite that provides simple SMP style multi-processing
OfxMultiThreadSuiteV1::multiThread — Function to spawn SMP threads
OfxMultiThreadSuiteV1::multiThreadNumCPUs — Function which indicates the number of CPUs available for SMP processing
OfxMultiThreadSuiteV1::multiThreadIndex — Function which indicates the index of the current thread
OfxMultiThreadSuiteV1::multiThreadIsSpawnedThread — Function to enquire if the calling thread was spawned by multiThread
OfxMultiThreadSuiteV1::mutexCreate — Create a mutex
OfxMultiThreadSuiteV1::mutexDestroy — Destroy a mutex
OfxMultiThreadSuiteV1::mutexLock — Blocking lock on the mutex
OfxMultiThreadSuiteV1::mutexUnLock — Unlock the mutex
OfxMultiThreadSuiteV1::mutexTryLock — Non blocking attempt to lock the mutex
22. Interact Suite
OfxInteractSuiteV1 — OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.
OfxInteractSuiteV1::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
23. Properties By Object
Properties on the Image Effect Host
Properties on an Effect Descriptor
Properties on an Effect Instance
Properties on a Clip Descriptor
Properties on a Clip Instance
Properties on an Image
Properties on Parameter Descriptors and Instances
Properties Common to All Parameters
Properties Common to All But Group and Page Parameters
Properties Common to All Parameters That Hold Values
Properties Common to All Numeric Parameters
Properties Common to All Double Parameters
Properties On 1D Double Parameters
Properties On 2D and 3D Double Parameters
Properties On 2D and 3D Integer Parameters
Properties On String Parameters
Properties On Choice Parameters
Properties On Custom Parameters
Properties On Page Parameters
Properties on Interact Descriptors
Properties on Interact Instances
24. Properties By Name
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 continously
kOfxImageClipPropFieldExtraction — 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 input
kOfxImageClipPropOptional — Indicates if a clip is optional.
kOfxImageClipPropUnmappedComponents — Indicates the current 'raw' component type on a clip before any mapping by clip preferences
kOfxImageClipPropUnmappedPixelDepth — Indicates the type of each component in a clip before any mapping by clip preferences
kOfxImageEffectFrameVarying — 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 effect
kOfxImageEffectInstancePropSequentialRender — Says whether an effect needs to be rendered sequentially or not
kOfxImageEffectPluginPropFieldRenderTwiceAlways — 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 threading
kOfxImageEffectPluginPropOverlayInteractV1 — Sets the entry for an effect's overlay interaction
kOfxImageEffectPluginPropSingleInstance — Indicates whether only one instance of a plugin can exist at the same time
kOfxImageEffectPluginRenderThreadSafety — Indicates how many simultaneous renders the plugin can deal with.
kOfxImageEffectPropClipPreferencesSlaveParam — Indicates the set of parameters on which a value change will trigger a change to clip preferences
kOfxImageEffectPropComponents — 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 renders
kOfxImageEffectPropInAnalysis — 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 image
kOfxImageEffectPropProjectExtent — 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 project
kOfxImageEffectPropProjectSize — The size of the current project in canonical coordinates.
kOfxImageEffectPropRegionOfDefinition — Used to indicate the region of definition of a plug-in
kOfxImageEffectPropRegionOfInterest — 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 host
kOfxImageEffectPropSupportsMultiResolution — 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 effect
kOfxImageEffectPropSupportsMultipleClipPARs — Indicates whether a host or plugin can support clips of differing pixel aspect ratios going into/out of an effect
kOfxImageEffectPropSupportsOverlays — Indicates whether a host support image effect ImageEffectOverlays.
kOfxImageEffectPropSupportsTiles — Indicates whether a clip, plugin or host supports tiled images
kOfxImageEffectPropTemporalClipAccess — 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 clip
kOfxImagePropBounds — The bounds of an image's pixels.
kOfxImagePropData — The pixel data pointer of an image.
kOfxImagePropField — Which fields are present in the image
kOfxImagePropPixelAspectRatio — 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 instance
kOfxInteractPropBitDepth — Indicates whether the dits per component in the interact's openGL frame buffer
kOfxInteractPropHasAlpha — Indicates whether the interact's frame buffer has an alpha component or not
kOfxInteractPropPenPosition — 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 viewport
kOfxParamHostPropMaxPages — Indicates the maximum number of parameter pages.
kOfxParamHostPropMaxParameters — Indicates the maximum numbers of parameters available on the host.
kOfxParamHostPropPageRowColumnCount — This indicates the number of parameter rows and coloumns on a page.
kOfxParamHostPropSupportsBooleanAnimation — Indicates if the host supports animation of boolean params
kOfxParamHostPropSupportsChoiceAnimation — 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 parameters
kOfxParamHostPropSupportsStringAnimation — Indicates if the host supports animation of string params
kOfxParamPropAnimates — Flags whether a parameter can animate.
kOfxParamPropCacheInvalidation — Specifies how modifying the value of a param will affect any output of an effect over time.
kOfxParamPropCanUndo — Flags whether changes to a parameter should be put on the undo/redo stack
kOfxParamPropChoiceOption — 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 preferred size of a parameter's custom interface.
kOfxParamPropInteractSize — The size of a parameter instance's custom interface in screen pixels.
kOfxParamPropInteractSizeAspect — The preferred aspect ratio of a parameter's custom interface.
kOfxParamPropInteractV1 — Overrides the parameter's standard user interface with the given interact.
kOfxParamPropInterpolationAmount — Property used by OfxCustomParamInterpFuncV1 to indicate the amount of interpolation to perform
kOfxParamPropInterpolationTime — 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 pass
kOfxParamPropScriptName — 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 pressed
kOfxPropLabel — 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 handle
25. Status Codes
OfxStatus — type returned to indicate success or failure of an operation.
kOfxStatOK — (0), indicates an operation completed sucessfully.
kOfxStatFailed — (1), indicates a failed operation.
kOfxStatErrFatal — (2), indicates a fatal operation.
kOfxStatErrUnknown — (3), status error code for an unknown object.
kOfxStatErrMissingHostFeature — (4) returned by a plug-in if a host is inadequate.
kOfxStatErrUnsupported — (5), error code for an unsupported feature/operation
kOfxStatErrExists — (6), something already exists.
kOfxStatErrFormat — (7), indicates an incorrect format.
kOfxStatErrMemory — (8), a memory shortage was encountered.
kOfxStatErrBadHandle — (9), indicates a bad handle
kOfxStatErrBadIndex — (10), a property index was invalid.
kOfxStatErrValue — (11), an illegal value was passed.
kOfxStatReplyYes — (12), returned to indicate a positive response.
kOfxStatReplyNo — (13), returned to indicate a positive response.
kOfxStatReplyDefault — (14), indicates the default should occur.