Auto-generated Reference Index

API

Complete Reference Index

struct OfxBytes

#include <ofxParam.h>

Provides information for a parameter of type kOfxParamTypeBytes.

Public Members

const unsigned char *data: a pointer to the data buffer

size_t length: the length of the data buffer, in bytes

struct OfxDialogSuiteV1

#include <ofxDialog.h>

Public Members

OfxStatus (*RequestDialog)(void *user_data)

Request the host to send a kOfxActionDialog to the plugin from its UI thread.

Pre:

user_data: A pointer to any user data

Post:

Return:

kOfxStatOK - The host has queued the request and will send an ‘OfxActionDialog’
kOfxStatFailed - The host has no provisio for this or can not deal with it currently.

OfxStatus (*NotifyRedrawPending)(void)

Inform the host of redraw event so it can redraw itself If the host runs fullscreen in OpenGL, it would otherwise not receive redraw event when a dialog in front would catch all events.

Pre:

Post:

Return:

kOfxStatReplyDefault

struct OfxDrawSuiteV1

#include <ofxDrawSuite.h>

OFX suite that allows an effect to draw to a host-defined display context. To use this, the plugin must use kOfxImageEffectPluginPropOverlayInteractV2.

Public Members

OfxStatus (*getColour)(OfxDrawContextHandle context, OfxStandardColour std_colour, OfxRGBAColourF *colour)

Retrieves the host’s desired draw colour for.

context draw context
std_colour desired colour type
colour returned RGBA colour

Return:

kOfxStatOK - the colour was returned
kOfxStatErrValue - std_colour was invalid
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

OfxStatus (*setColour)(OfxDrawContextHandle context, const OfxRGBAColourF *colour)

Sets the colour for future drawing operations (lines, filled shapes and text)

context draw context
colour RGBA colour

The host should use “over” compositing when using a non-opaque colour.

Return:

kOfxStatOK - the colour was changed
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

OfxStatus (*setLineWidth)(OfxDrawContextHandle context, float width)

Sets the line width for future line drawing operations.

context draw context
width line width

Use width 0 for a single pixel line or non-zero for a smooth line of the desired width

The host should adjust for screen density.

Return:

kOfxStatOK - the width was changed
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

OfxStatus (*setLineStipple)(OfxDrawContextHandle context, OfxDrawLineStipplePattern pattern)

Sets the stipple pattern for future line drawing operations.

context draw context
pattern desired stipple pattern

Return:

kOfxStatOK - the pattern was changed
kOfxStatErrValue - pattern was not valid
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

OfxStatus (*draw)(OfxDrawContextHandle context, OfxDrawPrimitive primitive, const OfxPointD *points, int point_count)

Draws a primitive of the desired type.

context draw context
primitive desired primitive
points array of points in the primitive
point_count number of points in the array

kOfxDrawPrimitiveLines - like GL_LINES, n points draws n/2 separated lines kOfxDrawPrimitiveLineStrip - like GL_LINE_STRIP, n points draws n-1 connected lines kOfxDrawPrimitiveLineLoop - like GL_LINE_LOOP, n points draws n connected lines kOfxDrawPrimitiveRectangle - draws an axis-aligned filled rectangle defined by 2 opposite corner points kOfxDrawPrimitivePolygon - like GL_POLYGON, draws a filled n-sided polygon kOfxDrawPrimitiveEllipse - draws a axis-aligned elliptical line (not filled) within the rectangle defined by 2 opposite corner points

Return:

kOfxStatOK - the draw was completed
kOfxStatErrValue - invalid primitive, or point_count not valid for primitive
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

OfxStatus (*drawText)(OfxDrawContextHandle context, const char *text, const OfxPointD *pos, int alignment)

Draws text at the specified position.

context draw context
text text to draw (UTF-8 encoded)
pos position at which to align the text
alignment text alignment flags (see kOfxDrawTextAlignment*)

The text font face and size are determined by the host.

Return:

kOfxStatOK - the text was drawn
kOfxStatErrValue - text or pos were not defined
kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw

struct OfxHost

#include <ofxCore.h>

Generic host structure passed to OfxPlugin::setHost function.

This structure contains what is needed by a plug-in to bootstrap its connection to the host.

Public Members

OfxPropertySetHandle host: Global handle to the host. Extract relevant host properties from this. This pointer will be valid while the binary containing the plug-in is loaded.

const void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion)

The function which the plug-in uses to fetch suites from the host.

host the host the suite is being fetched from this must be the host member of the OfxHost struct containing fetchSuite.
suiteName ASCII string labelling the host supplied API
suiteVersion version of that suite to fetch

Any API fetched will be valid while the binary containing the plug-in is loaded.

Repeated calls to fetchSuite with the same parameters will return the same pointer.

It is recommended that hosts should return the same host and suite pointers to all plugins in the same shared lib or bundle.

returns

NULL if the API is unknown (either the api or the version requested),
pointer to the relevant API if it was found

struct OfxImageEffectOpenGLRenderSuiteV1

#include <ofxGPURender.h>

OFX suite that provides image to texture conversion for OpenGL processing.

Public Members

OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip, OfxTime time, const char *format, const OfxRectD *region, OfxPropertySetHandle *textureHandle)

loads an image from an OFX clip as a texture into OpenGL

clip clip to load the image from
time effect time to load the image from
format requested texture format (As in none,byte,word,half,float, etc..) When set to NULL, the host decides the format based on the plug-in’s kOfxOpenGLPropPixelDepth setting.
region region of the image to load (optional, set to NULL to get a ‘default’ region) this is in the CanonicalCoordinates.
textureHandle property set containing information about the texture

An image is fetched from a clip at the indicated time for the given region and loaded into an OpenGL texture. When a specific format is requested, the host ensures it gives the requested format. When the clip specified is the “Output” clip, the format is ignored and the host must bind the resulting texture as the current color buffer (render target). This may also be done prior to calling the kOfxImageEffectActionRender action. If the region parameter is set to non-NULL, then it will be clipped to the clip’s Region of Definition for the given time. The returned image will be at least as big as this region. If the region parameter is not set or is NULL, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped to the clip’s Region of Definition. Information about the texture, including the texture index, is returned in the textureHandle argument. The properties on this handle will be…

With the exception of the OpenGL specifics, these properties are the same as the properties in an image handle returned by clipGetImage in the image effect suite.

Note

this is the OpenGL equivalent of clipGetImage from OfxImageEffectSuiteV1

Pre:

clip was returned by clipGetHandle
Format property in the texture handle

Post:

texture handle to be disposed of by clipFreeTexture before the action returns
when the clip specified is the “Output” clip, the format is ignored and the host must bind the resulting texture as the current color buffer (render target). This may also be done prior to calling the render action.

Return:

kOfxStatOK - the image was successfully fetched and returned in the handle,
kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plug-in should continue operation, but assume the image was black and transparent.
kOfxStatErrBadHandle - the clip handle was invalid,
kOfxStatErrMemory - not enough OpenGL memory was available for the effect to load the texture. The plug-in should abort the GL render and return kOfxStatErrMemory, after which the host can decide to retry the operation with CPU based processing.

OfxStatus (*clipFreeTexture)(OfxPropertySetHandle textureHandle)

Releases the texture handle previously returned by clipLoadTexture.

For input clips, this also deletes the texture from OpenGL. This should also be called on the output clip; for the Output clip, it just releases the handle but does not delete the texture (since the host will need to read it).

Pre:

textureHandle was returned by clipGetImage

Post:

all operations on textureHandle will be invalid, and the OpenGL texture it referred to has been deleted (for source clips)

Return:

kOfxStatOK - the image was successfully fetched and returned in the handle,
kOfxStatFailed - general failure for some reason,
kOfxStatErrBadHandle - the image handle was invalid,

OfxStatus (*flushResources)()

Request the host to minimize its GPU resource load.

When a plug-in fails to allocate GPU resources, it can call this function to request the host to flush its GPU resources if it holds any. After the function the plug-in can try again to allocate resources which then might succeed if the host actually has released anything.

Pre:

Post:

No changes to the plug-in GL state should have been made.

Return:

kOfxStatOK - the host has actually released some resources,
kOfxStatReplyDefault - nothing the host could do..

struct OfxImageEffectSuiteV1

#include <ofxImageEffect.h>

The OFX suite for image effects.

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

Public Members

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

Retrieves the property set for the given image effect.

imageEffect image effect to get the property set for
propHandle pointer to a the property set pointer, value is returned here

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

Return:

kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

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

Retrieves the parameter set for the given image effect.

imageEffect image effect to get the property set for
paramSet pointer to a the parameter set, value is returned here

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

Return:

kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

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

Define a clip to the effect.

pluginHandle handle passed into ‘describeInContext’ action
name unique name of the clip to define
propertySet property handle for the clip descriptor will be returned here

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

Pre:

we are inside the describe in context action.

Return:

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

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

imageEffect an instance handle to the plugin
name name of the clip, previously used in a clip define call
clip where to return the clip
propertySet if not NULL, the descriptor handle for a parameter’s property set will be placed here.

The propertySet will have the same value as would be returned by OfxImageEffectSuiteV1::clipGetPropertySet

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

Not a valid call in any of the describe actions.

Pre:

create instance action called,
name passed to clipDefine for this context,
not inside describe or describe in context actions.

Post:

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

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

Retrieves the property set for a given clip.

clip clip effect to get the property set for
propHandle pointer to a the property set handle, value is returedn her

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

Return:

kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

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

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

clip clip to extract the image from
time time to fetch the image at
region region to fetch the image from (optional, set to NULL to get a ‘default’ region) this is in the CanonicalCoordinates.
imageHandle property set containing the image’s data

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

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

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

Pre:

clip was returned by clipGetHandle

Post:

image handle is only valid for the duration of the action clipGetImage is called in
image handle to be disposed of by clipReleaseImage before the action returns

Return:

kOfxStatOK - the image was successfully fetched and returned in the handle,
kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plugin should continue operation, but assume the image was black and transparent.
kOfxStatErrBadHandle - the clip handle was invalid,
kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

OfxStatus (*clipReleaseImage)(OfxPropertySetHandle imageHandle)

Releases the image handle previously returned by clipGetImage.

Pre:

imageHandle was returned by clipGetImage

Post:

all operations on imageHandle will be invalid

Return:

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

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

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

clipHandle return this clip’s region of definition
time time to use when determining clip’s region of definition
bounds (out) bounds are returned here — in CanonicalCoordinates

Pre:

clipHandle was returned by clipGetHandle

Post:

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

Return:

kOfxStatOK - the region was successfully found and returned in the handle,
kOfxStatFailed - the region could not be determined,
kOfxStatErrBadHandle - the clip handle was invalid,
kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing.

int (*abort)(OfxImageEffectHandle imageEffect)

Returns whether to abort processing or not.

imageEffect instance of the image effect

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

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

Return:

0 if the effect should continue whatever processing it is doing
1 if the effect should abort whatever processing it is doing

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

Allocate memory from the host’s image memory pool.

instanceHandle effect instance to associate with this memory allocation, may be NULL.
nBytes number of bytes to allocate
memoryHandle pointer to the memory handle where a return value is placed

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

See ImageEffectsMemoryAllocation.

Return:

kOfxStatOK if all went well, a valid memory handle is placed in memoryHandle
kOfxStatErrBadHandle if instanceHandle is not valid, memoryHandle is set to NULL
kOfxStatErrMemory if there was not enough memory to satisfy the call, memoryHandle is set to NULL

OfxStatus (*imageMemoryFree)(OfxImageMemoryHandle memoryHandle)

Frees a memory handle and associated memory.

memoryHandle memory handle returned by imageMemoryAlloc

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

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

See ImageEffectsMemoryAllocation.

Return:

kOfxStatOK if the memory was cleanly deleted
kOfxStatErrBadHandle if the value of memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc

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

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

memoryHandle memory handle returned by imageMemoryAlloc
returnedPtr where to the pointer to the locked memory

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

Note that memory locks and unlocks nest.

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

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

See also OfxImageEffectSuiteV1::imageMemoryUnlock and ImageEffectsMemoryAllocation.

Return:

kOfxStatOK if the memory was locked, a pointer is placed in returnedPtr
kOfxStatErrBadHandle if the value of memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc, null is placed in *returnedPtr
kOfxStatErrMemory if there was not enough memory to satisfy the call, *returnedPtr is set to NULL

OfxStatus (*imageMemoryUnlock)(OfxImageMemoryHandle memoryHandle)

Unlock allocated image data.

allocatedData pointer to memory previously returned by OfxImageEffectSuiteV1::imageAlloc

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

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

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

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

See also OfxImageEffectSuiteV1::imageMemoryLock and ImageEffectsMemoryAllocation.

Return:

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

struct OfxInteractSuiteV1

#include <ofxInteract.h>

OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.

Public Members

OfxStatus (*interactSwapBuffers)(OfxInteractHandle interactInstance): Requests an openGL buffer swap on the interact instance.

OfxStatus (*interactRedraw)(OfxInteractHandle interactInstance): Requests a redraw of the interact instance.

OfxStatus (*interactGetPropertySet)(OfxInteractHandle interactInstance, OfxPropertySetHandle *property): Gets the property set handle for this interact handle.

struct OfxMemorySuiteV1

#include <ofxMemory.h>

The OFX suite that implements general purpose memory management.

Use this suite for ordinary memory management functions, where you would normally use malloc/free or new/delete on ordinary objects.

For images, you should use the memory allocation functions in the image effect suite, as many hosts have specific image memory pools.

Note

C++ plugin developers will need to redefine new and delete as skins on top of this suite.

Public Members

OfxStatus (*memoryAlloc)(void *handle, size_t nBytes, void **allocatedData)

Allocate memory.

handle - effect instance to associate with this memory allocation, or NULL.
nBytes number of bytes to allocate
allocatedData pointer to the return value. Allocated memory will be aligned for any use.

This function has the host allocate memory using its own memory resources and returns that to the plugin.

Return:

kOfxStatOK the memory was successfully allocated
kOfxStatErrMemory the request could not be met and no memory was allocated

OfxStatus (*memoryFree)(void *allocatedData)

Frees memory.

allocatedData pointer to memory previously returned by OfxMemorySuiteV1::memoryAlloc

This function frees any memory that was previously allocated via OfxMemorySuiteV1::memoryAlloc.

Return:

kOfxStatOK the memory was successfully freed
kOfxStatErrBadHandle allocatedData was not a valid pointer returned by OfxMemorySuiteV1::memoryAlloc

struct OfxMessageSuiteV1

#include <ofxMessage.h>

The OFX suite that allows a plug-in to pass messages back to a user. The V2 suite extends on this in a backwards compatible manner.

Public Members

OfxStatus (*message)(void *handle, const char *messageType, const char *messageId, const char *format, ...)

Post a message on the host, using printf style varargs.

handle effect handle (descriptor or instance) the message should be associated with, may be NULL
messageType string describing the kind of message to post, one of the kOfxMessageType* constants
messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or “”, in which case no override will occur,
format printf style format string
… printf style varargs list to print

Return:

kOfxStatOK - if the message was successfully posted
kOfxStatReplyYes - if the message was of type kOfxMessageQuestion and the user reply yes
kOfxStatReplyNo - if the message was of type kOfxMessageQuestion and the user reply no
kOfxStatFailed - if the message could not be posted for some reason

struct OfxMessageSuiteV2

#include <ofxMessage.h>

The OFX suite that allows a plug-in to pass messages back to a user.

This extends OfxMessageSuiteV1, and should be considered a replacement to version 1.

Note that this suite has been extended in backwards compatible manner, so that a host can return this struct for both V1 and V2.

Public Members

OfxStatus (*message)(void *handle, const char *messageType, const char *messageId, const char *format, ...)

Post a transient message on the host, using printf style varargs. Same as the V1 message suite call.

handle effect handle (descriptor or instance) the message should be associated with, may be null
messageType string describing the kind of message to post, one of the kOfxMessageType* constants
messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or “”, in which case no override will occur,
format printf style format string
… printf style varargs list to print

Return:

kOfxStatOK - if the message was successfully posted
kOfxStatReplyYes - if the message was of type kOfxMessageQuestion and the user reply yes
kOfxStatReplyNo - if the message was of type kOfxMessageQuestion and the user reply no
kOfxStatFailed - if the message could not be posted for some reason

OfxStatus (*setPersistentMessage)(void *handle, const char *messageType, const char *messageId, const char *format, ...)

Post a persistent message on an effect, using printf style varargs, and set error states. New for V2 message suite.

handle effect instance handle the message should be associated with, may NOT be null,
messageType string describing the kind of message to post, should be one of…
- kOfxMessageError
- kOfxMessageWarning
- kOfxMessageMessage
messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or “”, in which case no override will occur,
format printf style format string
… printf style varargs list to print

Persistent messages are associated with an effect handle until explicitly cleared by an effect. So if an error message is posted the error state, and associated message will persist and be displayed on the effect appropriately. (eg: draw a node in red on a node based compostor and display the message when clicked on).

If messageType is error or warning, associated error states should be flagged on host applications. Posting an error message implies that the host cannot proceed, a warning allows the host to proceed, whilst a simple message should have no stop anything.

Return:

kOfxStatOK - if the message was successfully posted
kOfxStatErrBadHandle - the handle was rubbish
kOfxStatFailed - if the message could not be posted for some reason

OfxStatus (*clearPersistentMessage)(void *handle)

Clears any persistent message on an effect handle that was set by OfxMessageSuiteV2::setPersistentMessage. New for V2 message suite.

handle effect instance handle messages should be cleared from.
handle effect handle (descriptor or instance)

Clearing a message will clear any associated error state.

Return:

kOfxStatOK - if the message was successfully cleared
kOfxStatErrBadHandle - the handle was rubbish
kOfxStatFailed - if the message could not be cleared for some reason

struct OfxMultiThreadSuiteV1

#include <ofxMultiThread.h>

OFX suite that provides simple SMP style multi-processing.

Public Members

OfxStatus (*multiThread)(OfxThreadFunctionV1 func, unsigned int nThreads, void *customArg)

Function to spawn SMP threads.

func function to call in each thread.
nThreads number of threads to launch
customArg parameter to pass to customArg of func in each thread.

This function will spawn nThreads separate threads of computation (typically one per CPU) to allow something to perform symmetric multi processing. Each thread will call ‘func’ passing in the index of the thread and the number of threads actually launched.

multiThread will not return until all the spawned threads have returned. It is up to the host how it waits for all the threads to return (busy wait, blocking, whatever).

nThreads can be more than the value returned by multiThreadNumCPUs, however the threads will be limited to the number of CPUs returned by multiThreadNumCPUs.

This function cannot be called recursively.

Return:

kOfxStatOK, the function func has executed and returned successfully
kOfxStatFailed, the threading function failed to launch
kOfxStatErrExists, failed in an attempt to call multiThread recursively,

OfxStatus (*multiThreadNumCPUs)(unsigned int *nCPUs)

Function which indicates the number of CPUs available for SMP processing.

nCPUs pointer to an integer where the result is returned

This value may be less than the actual number of CPUs on a machine, as the host may reserve other CPUs for itself.

Return:

kOfxStatOK, all was OK and the maximum number of threads is in nThreads.
kOfxStatFailed, the function failed to get the number of CPUs

OfxStatus (*multiThreadIndex)(unsigned int *threadIndex)

Function which indicates the index of the current thread.

threadIndex pointer to an integer where the result is returned

This function returns the thread index, which is the same as the threadIndex argument passed to the OfxThreadFunctionV1.

If there are no threads currently spawned, then this function will set threadIndex to 0

Return:

kOfxStatOK, all was OK and the maximum number of threads is in nThreads.
kOfxStatFailed, the function failed to return an index

int (*multiThreadIsSpawnedThread)(void)

Function to enquire if the calling thread was spawned by multiThread.

Return:

0 if the thread is not one spawned by multiThread
1 if the thread was spawned by multiThread

OfxStatus (*mutexCreate)(OfxMutexHandle *mutex, int lockCount)

Create a mutex.

mutex where the new handle is returned
count initial lock count on the mutex. This can be negative.

Creates a new mutex with lockCount locks on the mutex initially set.

Return:

kOfxStatOK - mutex is now valid and ready to go

OfxStatus (*mutexDestroy)(const OfxMutexHandle mutex)

Destroy a mutex.

Destroys a mutex initially created by mutexCreate.

Return:

kOfxStatOK - if it destroyed the mutex
kOfxStatErrBadHandle - if the handle was bad

OfxStatus (*mutexLock)(const OfxMutexHandle mutex)

Blocking lock on the mutex.

This tries to lock a mutex and blocks the thread it is in until the lock succeeds.

A successful lock causes the mutex’s lock count to be increased by one and to block any other calls to lock the mutex until it is unlocked.

Return:

kOfxStatOK - if it got the lock
kOfxStatErrBadHandle - if the handle was bad

OfxStatus (*mutexUnLock)(const OfxMutexHandle mutex)

Unlock the mutex.

This unlocks a mutex. Unlocking a mutex decreases its lock count by one.

Return:

kOfxStatOK if it released the lock
kOfxStatErrBadHandle if the handle was bad

OfxStatus (*mutexTryLock)(const OfxMutexHandle mutex)

Non blocking attempt to lock the mutex.

This attempts to lock a mutex, if it cannot, it returns and says so, rather than blocking.

A successful lock causes the mutex’s lock count to be increased by one, if the lock did not succeed, the call returns immediately and the lock count remains unchanged.

Return:

kOfxStatOK - if it got the lock
kOfxStatFailed - if it did not get the lock
kOfxStatErrBadHandle - if the handle was bad

struct OfxOpenCLProgramSuiteV1

#include <ofxGPURender.h>

OFX suite that allows a plug-in to get OpenCL programs compiled.

This is an optional suite the host can provide for building OpenCL programs for the plug-in, as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also cache program binaries for performance (however, if the source of the program or the OpenCL environment changes, the host must recompile so some mechanism such as hashing must be used).

Public Members

OfxStatus (*compileProgram)(const char *pszProgramSource, int fOptional, void *pResult): Compiles the OpenCL program.

struct OfxParameterSuiteV1

#include <ofxParam.h>

The OFX suite used to define and manipulate user visible parameters.

Keyframe Handling

These functions allow the plug-in to delete and get information about keyframes.

To set keyframes, use paramSetValueAtTime().

paramGetKeyTime and paramGetKeyIndex use indices to refer to keyframes. Keyframes are stored by the host in increasing time order, so time(kf[i]) < time(kf[i+1]). Keyframe indices will change whenever keyframes are added, deleted, or moved in time, whether by the host or by the plug-in. They may vary between actions if the user changes a keyframe. The keyframe indices will not change within a single action.

OfxStatus (*paramGetNumKeys)(OfxParamHandle paramHandle, unsigned int *numberOfKeys)

Returns the number of keyframes in the parameter.

paramHandle parameter handle to interrogate
numberOfKeys pointer to integer where the return value is placed

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Returns the number of keyframes in the parameter.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramGetKeyTime)(OfxParamHandle paramHandle, unsigned int nthKey, OfxTime *time)

Returns the time of the nth key.

paramHandle parameter handle to interrogate
nthKey which key to ask about (0 to paramGetNumKeys -1), ordered by time
time pointer to OfxTime where the return value is placed

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - the nthKey does not exist

OfxStatus (*paramGetKeyIndex)(OfxParamHandle paramHandle, OfxTime time, int direction, int *index)

Finds the index of a keyframe at/before/after a specified time.

paramHandle parameter handle to search
time what time to search from
direction
- == 0 indicates search for a key at the indicated time (some small delta)
- > 0 indicates search for the next key after the indicated time
- < 0 indicates search for the previous key before the indicated time
index pointer to an integer which in which the index is returned set to -1 if no key was found

Return:

kOfxStatOK - all was OK
kOfxStatFailed - if the search failed to find a key
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramDeleteKey)(OfxParamHandle paramHandle, OfxTime time)

Deletes a keyframe if one exists at the given time.

paramHandle parameter handle to delete the key from
time time at which a keyframe is

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - no key at the given time

OfxStatus (*paramDeleteAllKeys)(OfxParamHandle paramHandle)

Deletes all keyframes from a parameter.

paramHandle parameter handle to delete the keys from
name parameter to delete the keyframes from is

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

Public Members

OfxStatus (*paramDefine)(OfxParamSetHandle paramSet, const char *paramType, const char *name, OfxPropertySetHandle *propertySet)

Defines a new parameter of the given type in a describe action.

paramSet handle to the parameter set descriptor that will hold this parameter
paramType type of the parameter to create, one of the kOfxParamType* #defines
name unique name of the parameter
propertySet if not null, a pointer to the parameter descriptor’s property set will be placed here.

This function defines a parameter in a parameter set and returns a property set which is used to describe that parameter.

This function does not actually create a parameter, it only says that one should exist in any subsequent instances. To fetch an parameter instance paramGetHandle must be called on an instance.

This function can always be called in one of a plug-in’s “describe” functions which defines the parameter sets common to all instances of a plugin.

Return:

kOfxStatOK - the parameter was created correctly
kOfxStatErrBadHandle - if the plugin handle was invalid
kOfxStatErrExists - if a parameter of that name exists already in this plugin
kOfxStatErrUnknown - if the type is unknown
kOfxStatErrUnsupported - if the type is known but unsupported

OfxStatus (*paramGetHandle)(OfxParamSetHandle paramSet, const char *name, OfxParamHandle *param, OfxPropertySetHandle *propertySet)

Retrieves the handle for a parameter in a given parameter set.

paramSet instance of the plug-in to fetch the property handle from
name parameter to ask about
param pointer to a param handle, the value is returned here
propertySet if not null, a pointer to the parameter’s property set will be placed here.

Parameter handles retrieved from an instance are always distinct in each instance. The parameter handle is valid for the life-time of the instance. Parameter handles in instances are distinct from parameter handles in plugins. You cannot call this in a plugin’s describe function, as it needs an instance to work on.

Return:

kOfxStatOK - the parameter was found and returned
kOfxStatErrBadHandle - if the plugin handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*paramSetGetPropertySet)(OfxParamSetHandle paramSet, OfxPropertySetHandle *propHandle)

Retrieves the property set handle for the given parameter set.

paramSet parameter set to get the property set for
propHandle pointer to a the property set handle, value is returedn her

Note

The property handle belonging to a parameter set is the same as the property handle belonging to the plugin instance.

Return:

kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*paramGetPropertySet)(OfxParamHandle param, OfxPropertySetHandle *propHandle)

Retrieves the property set handle for the given parameter.

param parameter to get the property set for
propHandle pointer to a the property set handle, value is returedn her

The property handle is valid for the lifetime of the parameter, which is the lifetime of the instance that owns the parameter

Return:

kOfxStatOK - the property set was found and returned
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*paramGetValue)(OfxParamHandle paramHandle, ...)

Gets the current value of a parameter,.

paramHandle parameter handle to fetch value from
… one or more pointers to variables of the relevant type to hold the parameter’s value

This gets the current value of a parameter. The varargs … argument needs to be pointer to C variables of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example…

  OfxParamHandle myDoubleParam, *myColourParam;
  ofxHost->paramGetHandle(instance, "myDoubleParam", &myDoubleParam);
  double myDoubleValue;
  ofxHost->paramGetValue(myDoubleParam, &myDoubleValue);
  ofxHost->paramGetHandle(instance, "myColourParam", &myColourParam);
  double myR, myG, myB;
  ofxHost->paramGetValue(myColourParam, &myR, &myG, &myB);

Note

paramGetValue should only be called from within a kOfxActionInstanceChanged or interact action and never from the render actions (which should always use paramGetValueAtTime).

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramGetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)

Gets the value of a parameter at a specific time.

paramHandle parameter handle to fetch value from
time at what point in time to look up the parameter
… one or more pointers to variables of the relevant type to hold the parameter’s value

This gets the current value of a parameter. The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramGetDerivative)(OfxParamHandle paramHandle, OfxTime time, ...)

Gets the derivative of a parameter at a specific time.

paramHandle parameter handle to fetch value from
time at what point in time to look up the parameter
… one or more pointers to variables of the relevant type to hold the parameter’s derivative

This gets the derivative of the parameter at the indicated time.

The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list.

Only double and colour params can have their derivatives found.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramGetIntegral)(OfxParamHandle paramHandle, OfxTime time1, OfxTime time2, ...)

Gets the integral of a parameter over a specific time range,.

paramHandle parameter handle to fetch integral from
time1 where to start evaluating the integral
time2 where to stop evaluating the integral
… one or more pointers to variables of the relevant type to hold the parameter’s integral

This gets the integral of the parameter over the specified time range.

The varargs needs to be pointer to C variables of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on the varags list.

Only double and colour params can be integrated.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramSetValue)(OfxParamHandle paramHandle, ...)

Sets the current value of a parameter.

paramHandle parameter handle to set value in
… one or more variables of the relevant type to hold the parameter’s value

This sets the current value of a parameter. The varargs … argument needs to be values of the relevant type for this parameter. Note that params with multiple values (eg Colour) take multiple args here. For example…

  ofxHost->paramSetValue(instance, "myDoubleParam", double(10));
  ofxHost->paramSetValue(instance, "myColourParam", double(pix.r), double(pix.g), double(pix.b));

Note

paramSetValue should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramSetValueAtTime)(OfxParamHandle paramHandle, OfxTime time, ...)

Keyframes the value of a parameter at a specific time.

paramHandle parameter handle to set value in
time at what point in time to set the keyframe
… one or more variables of the relevant type to hold the parameter’s value

This sets a keyframe in the parameter at the indicated time to have the indicated value. The varargs … argument needs to be values of the relevant type for this parameter. See the note on OfxParameterSuiteV1::paramSetValue for more detail

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Note

paramSetValueAtTime should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramCopy)(OfxParamHandle paramTo, OfxParamHandle paramFrom, OfxTime dstOffset, const OfxRangeD *frameRange)

Copies one parameter to another, including any animation etc…

paramTo parameter to set
paramFrom parameter to copy from
dstOffset temporal offset to apply to keys when writing to the paramTo
frameRange if paramFrom has animation, and frameRange is not null, only this range of keys will be copied

This copies the value of paramFrom to paramTo, including any animation it may have. All the previous values in paramTo will be lost.

To choose all animation in paramFrom set frameRange to [0, 0]

V1.3: This function can be called the kOfxActionInstanceChanged action and during image effect analysis render passes. V1.4: This function can be called the kOfxActionInstanceChanged action

Pre:

Both parameters must be of the same type.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the parameter handle was invalid

OfxStatus (*paramEditBegin)(OfxParamSetHandle paramSet, const char *name)

Used to group any parameter changes for undo/redo purposes.

paramSet the parameter set in which this is happening
name label to attach to any undo/redo string UTF8

If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the start of a set of a parameter changes that should be considered part of a single undo/redo block.

Note

paramEditBegin should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the instance handle was invalid

OfxStatus (*paramEditEnd)(OfxParamSetHandle paramSet)

Used to group any parameter changes for undo/redo purposes.

paramSet parameter set in which this is happening

If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction or some analysis of imagery etc.. this is used to indicate the end of a set of parameter changes that should be considerred part of a single undo/redo block

Note

paramEditEnd should only be called from within a kOfxActionInstanceChanged or interact action.

Return:

kOfxStatOK - all was OK
kOfxStatErrBadHandle - if the instance handle was invalid

struct OfxParametricParameterSuiteV1

#include <ofxParametricParam.h>

The OFX suite used to define and manipulate ‘parametric’ parameters.

This is an optional suite.

Parametric parameters are in effect ‘functions’ a plug-in can ask a host to arbitrarily evaluate for some value ‘x’. A classic use case would be for constructing look-up tables, a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that to fill an array.

A host would probably represent this to a user as a cubic curve in a standard curve editor interface, or possibly through scripting. The user would then use this to define the ‘shape’ of the parameter.

The evaluation of such params is not the same as animation, they are returning values based on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass a parametric position and time.

Often, you would want such a parametric parameter to be multi-dimensional, for example, a colour look-up table might want three values, one for red, green and blue. Rather than declare three separate parametric parameters, it would be better to have one such parameter with multiple values in it.

The major complication with these parameters is how to allow a plug-in to set values, and defaults. The default default value of a parametric curve is to be an identity lookup. If a plugin wishes to set a different default value for a curve, it can use the suite to set key/value pairs on the descriptor of the param. When a new instance is made, it will have these curve values as a default.

Public Members

OfxStatus (*parametricParamGetValue)(OfxParamHandle param, int curveIndex, OfxTime time, double parametricPosition, double *returnValue)

Evaluates a parametric parameter.

param handle to the parametric parameter
curveIndex which dimension to evaluate
time the time to evaluate to the parametric param at
parametricPosition the position to evaluate the parametric param at
returnValue pointer to a double where a value is returned

Return:

kOfxStatOK - all was fine
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - the curve index was invalid

OfxStatus (*parametricParamGetNControlPoints)(OfxParamHandle param, int curveIndex, double time, int *returnValue)

Returns the number of control points in the parametric param.

param handle to the parametric parameter
curveIndex which dimension to check
time the time to check
returnValue pointer to an integer where the value is returned.

Return:

kOfxStatOK - all was fine
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrBadIndex - the curve index was invalid

OfxStatus (*parametricParamGetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double *key, double *value)

Returns the key/value pair of the nth control point.

param handle to the parametric parameter
curveIndex which dimension to check
time the time to check
nthCtl the nth control point to get the value of
key pointer to a double where the key will be returned
value pointer to a double where the value will be returned

Return:

kOfxStatOK - all was fine
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*parametricParamSetNthControlPoint)(OfxParamHandle param, int curveIndex, double time, int nthCtl, double key, double value, bool addAnimationKey)

Modifies an existing control point on a curve.

param handle to the parametric parameter
curveIndex which dimension to set
time the time to set the value at
nthCtl the control point to modify
key key of the control point
value value of the control point
addAnimationKey if the param is an animatable, setting this to true will force an animation keyframe to be set as well as a curve key, otherwise if false, a key will only be added if the curve is already animating.

This modifies an existing control point. Note that by changing key, the order of the control point may be modified (as you may move it before or after anther point). So be careful when iterating over a curves control points and you change a key.

Return:

kOfxStatOK - all was fine
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*parametricParamAddControlPoint)(OfxParamHandle param, int curveIndex, double time, double key, double value, bool addAnimationKey)

Adds a control point to the curve.

param handle to the parametric parameter
curveIndex which dimension to set
time the time to set the value at
key key of the control point
value value of the control point
addAnimationKey if the param is an animatable, setting this to true will force an animation keyframe to be set as well as a curve key, otherwise if false, a key will only be added if the curve is already animating.

This will add a new control point to the given dimension of a parametric parameter. If a key exists sufficiently close to ‘key’, then it will be set to the indicated control point.

Return:

kOfxStatOK - all was fine
kOfxStatErrBadHandle - if the parameter handle was invalid
kOfxStatErrUnknown - if the type is unknown

OfxStatus (*parametricParamDeleteControlPoint)(OfxParamHandle param, int curveIndex, int nthCtl)

Deletes the nth control point from a parametric param.

param handle to the parametric parameter
curveIndex which dimension to delete
nthCtl the control point to delete

OfxStatus (*parametricParamDeleteAllControlPoints)(OfxParamHandle param, int curveIndex)

Delete all curve control points on the given param.

param handle to the parametric parameter
curveIndex which dimension to clear

struct OfxPlugin

#include <ofxCore.h>

The structure that defines a plug-in to a host.

This structure is the first element in any plug-in structure using the OFX plug-in architecture. By examining its members a host can determine the API that the plug-in implements, the version of that API, its name and version.

For details see Architecture.

Public Members

const char *pluginApi: Defines the type of the plug-in, this will tell the host what the plug-in does. e.g.: an image effects plug-in would be a “OfxImageEffectPlugin”

int apiVersion: Defines the version of the pluginApi that this plug-in implements

const char *pluginIdentifier: String that uniquely labels the plug-in among all plug-ins that implement an API. It need not necessarily be human sensible, however the preference is to use reverse internet domain name of the developer, followed by a ‘.’ then by a name that represents the plug-in.. It must be a legal ASCII string and have no whitespace in the name and no non printing chars. For example “uk.co.somesoftwarehouse.myPlugin”

unsigned int pluginVersionMajor: Major version of this plug-in, this gets incremented when backwards compatibility is broken.

unsigned int pluginVersionMinor: Major version of this plug-in, this gets incremented when software is changed, but does not break backwards compatibility.

void (*setHost)(OfxHost *host)

Function the host uses to connect the plug-in to the host’s api fetcher.

fetchApi pointer to host’s API fetcher

Mandatory function.

The very first function called in a plug-in. The plug-in must not call any OFX functions within this, it must only set its local copy of the host pointer.

It is recommended that hosts should return the same host and suite pointers to all plugins in the same shared lib or bundle.

Pre:

nothing else has been called

Post:

the pointer suite is valid until the plug-in is unloaded

OfxPluginEntryPoint *mainEntry

Main entry point for plug-ins.

Mandatory function.

The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins can perform several actions. For the list of actions consult OFX Actions.

Preconditions

setHost has been called

struct OfxPointD

#include <ofxCore.h>

Defines two dimensional double point.

Public Members

double x

double y

struct OfxPointI

#include <ofxCore.h>

Defines two dimensional integer point.

Public Members

int x

int y

struct OfxProgressSuiteV1

#include <ofxProgress.h>

A suite that provides progress feedback from a plugin to an application.

A plugin instance can initiate, update and close a progress indicator with this suite.

This is an optional suite in the Image Effect API.

API V1.4: Amends the documentation of progress suite V1 so that it is expected that it can be raised in a modal manner and have a “cancel” button when invoked in instanceChanged. Plugins that perform analysis post an appropriate message, raise the progress monitor in a modal manner and should poll to see if processing has been aborted. Any cancellation should be handled gracefully by the plugin (eg: reset analysis parameters to default values), clear allocated memory…

Many hosts already operate as described above. kOfxStatReplyNo should be returned to the plugin during progressUpdate when the user presses cancel.

Suite V2: Adds an ID that can be looked up for internationalisation and so on. When a new version is introduced, because plug-ins need to support old versions, and plug-in’s new releases are not necessary in synch with hosts (or users don’t immediately update), best practice is to support the 2 suite versions. That is, the plugin should check if V2 exists; if not then check if V1 exists. This way a graceful transition is guaranteed. So plugin should fetchSuite passing 2, (OfxProgressSuiteV2*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); and if no success pass (OfxProgressSuiteV1*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,1);

Public Members

OfxStatus (*progressStart)(void *effectInstance, const char *label)

Initiate a progress bar display.

Call this to initiate the display of a progress bar.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.
label a text label to display in any message portion of the progress object’s user interface. A UTF8 string.

Pre:

- There is no currently ongoing progress display for this instance.

Return:

kOfxStatOK - the handle is now valid for use
kOfxStatFailed - the progress object failed for some reason
kOfxStatErrBadHandle - effectInstance was invalid

OfxStatus (*progressUpdate)(void *effectInstance, double progress)

Indicate how much of the processing task has been completed and reports on any abort status.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.
progress a number between 0.0 and 1.0 indicating what proportion of the current task has been processed.

Return:

kOfxStatOK - the progress object was successfully updated and the task should continue
kOfxStatReplyNo - the progress object was successfully updated and the task should abort
kOfxStatErrBadHandle - the progress handle was invalid,

OfxStatus (*progressEnd)(void *effectInstance)

Signal that we are finished with the progress meter.

Call this when you are done with the progress meter and no longer need it displayed.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.

Post:

- you can no longer call progressUpdate on the instance

Return:

kOfxStatOK - the progress object was successfully closed
kOfxStatErrBadHandle - the progress handle was invalid,

struct OfxProgressSuiteV2

#include <ofxProgress.h>

Public Members

OfxStatus (*progressStart)(void *effectInstance, const char *message, const char *messageid)

Initiate a progress bar display.

Call this to initiate the display of a progress bar.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.
message a text label to display in any message portion of the progress object’s user interface. A UTF8 string.
messageId plugin-specified id to associate with this message. If overriding the message in an XML resource, the message is identified with this, this may be NULL, or “”, in which case no override will occur. New in V2 of this suite.

Pre:

- There is no currently ongoing progress display for this instance.

Return:

kOfxStatOK - the handle is now valid for use
kOfxStatFailed - the progress object failed for some reason
kOfxStatErrBadHandle - effectInstance was invalid

OfxStatus (*progressUpdate)(void *effectInstance, double progress)

Indicate how much of the processing task has been completed and reports on any abort status.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.
progress a number between 0.0 and 1.0 indicating what proportion of the current task has been processed.

Return:

kOfxStatOK - the progress object was successfully updated and the task should continue
kOfxStatReplyNo - the progress object was successfully updated and the task should abort
kOfxStatErrBadHandle - the progress handle was invalid,

OfxStatus (*progressEnd)(void *effectInstance)

Signal that we are finished with the progress meter.

Call this when you are done with the progress meter and no longer need it displayed.

effectInstance the instance of the plugin this progress bar is associated with. It cannot be NULL.

Post:

- you can no longer call progressUpdate on the instance

Return:

kOfxStatOK - the progress object was successfully closed
kOfxStatErrBadHandle - the progress handle was invalid,

struct OfxPropertySuiteV1

#include <ofxProperty.h>

The OFX suite used to access properties on OFX objects.

Public Members

OfxStatus (*propSetPointer)(OfxPropertySetHandle properties, const char *property, int index, void *value)

Set a single value in a pointer property.

properties handle of the thing holding the property
property string labelling the property
index for multidimenstional properties and is dimension of the one we are setting
value value of the property we are setting

Return:

OfxStatus (*propSetString)(OfxPropertySetHandle properties, const char *property, int index, const char *value)

Set a single value in a string property.

properties handle of the thing holding the property
property string labelling the property
index for multidimenstional properties and is dimension of the one we are setting
value value of the property we are setting

Return:

OfxStatus (*propSetDouble)(OfxPropertySetHandle properties, const char *property, int index, double value)

Set a single value in a double property.

properties handle of the thing holding the property
property string labelling the property
index for multidimenstional properties and is dimension of the one we are setting
value value of the property we are setting

Return:

OfxStatus (*propSetInt)(OfxPropertySetHandle properties, const char *property, int index, int value)

Set a single value in an int property.

properties handle of the thing holding the property
property string labelling the property
index for multidimenstional properties and is dimension of the one we are setting
value value of the property we are setting

Return:

OfxStatus (*propSetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void *const *value)

Set multiple values of the pointer property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are setting in that property (ie: indices 0..count-1)
value pointer to an array of property values

Return:

OfxStatus (*propSetStringN)(OfxPropertySetHandle properties, const char *property, int count, const char *const *value)

Set multiple values of a string property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are setting in that property (ie: indices 0..count-1)
value pointer to an array of property values

Return:

OfxStatus (*propSetDoubleN)(OfxPropertySetHandle properties, const char *property, int count, const double *value)

Set multiple values of a double property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are setting in that property (ie: indices 0..count-1)
value pointer to an array of property values

Return:

OfxStatus (*propSetIntN)(OfxPropertySetHandle properties, const char *property, int count, const int *value)

Set multiple values of an int property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are setting in that property (ie: indices 0..count-1)
value pointer to an array of property values

Return:

OfxStatus (*propGetPointer)(OfxPropertySetHandle properties, const char *property, int index, void **value)

Get a single value from a pointer property.

properties handle of the thing holding the property
property string labelling the property
index refers to the index of a multi-dimensional property
value pointer the return location

Return:

OfxStatus (*propGetString)(OfxPropertySetHandle properties, const char *property, int index, char **value)

Get a single value of a string property.

properties handle of the thing holding the property
property string labelling the property
index refers to the index of a multi-dimensional property
value pointer the return location

Return:

OfxStatus (*propGetDouble)(OfxPropertySetHandle properties, const char *property, int index, double *value)

Get a single value of a double property.

properties handle of the thing holding the property
property string labelling the property
index refers to the index of a multi-dimensional property
value pointer the return location

See the note ArchitectureStrings for how to deal with strings.

Return:

OfxStatus (*propGetInt)(OfxPropertySetHandle properties, const char *property, int index, int *value)

Get a single value of an int property.

properties handle of the thing holding the property
property string labelling the property
index refers to the index of a multi-dimensional property
value pointer the return location

Return:

OfxStatus (*propGetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void **value)

Get multiple values of a pointer property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are getting of that property (ie: indices 0..count-1)
value pointer to an array of where we will return the property values

Return:

OfxStatus (*propGetStringN)(OfxPropertySetHandle properties, const char *property, int count, char **value)

Get multiple values of a string property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are getting of that property (ie: indices 0..count-1)
value pointer to an array of where we will return the property values

See the note ArchitectureStrings for how to deal with strings.

Return:

OfxStatus (*propGetDoubleN)(OfxPropertySetHandle properties, const char *property, int count, double *value)

Get multiple values of a double property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are getting of that property (ie: indices 0..count-1)
value pointer to an array of where we will return the property values

Return:

OfxStatus (*propGetIntN)(OfxPropertySetHandle properties, const char *property, int count, int *value)

Get multiple values of an int property.

properties handle of the thing holding the property
property string labelling the property
count number of values we are getting of that property (ie: indices 0..count-1)
value pointer to an array of where we will return the property values

Return:

OfxStatus (*propReset)(OfxPropertySetHandle properties, const char *property)

Resets all dimensions of a property to its default value.

properties handle of the thing holding the property
property string labelling the property we are resetting

Return:

OfxStatus (*propGetDimension)(OfxPropertySetHandle properties, const char *property, int *count)

Gets the dimension of the property.

properties handle of the thing holding the property
property string labelling the property we are resetting
count pointer to an integer where the value is returned

Return:

struct OfxRangeD

#include <ofxCore.h>

Defines one dimensional double bounds.

Public Members

double min

double max

struct OfxRangeI

#include <ofxCore.h>

Defines one dimensional integer bounds.

Public Members

int min

int max

struct OfxRectD

#include <ofxCore.h>

Defines two dimensional double region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Public Members

double x1

double y1

double x2

double y2

struct OfxRectI

#include <ofxCore.h>

Defines two dimensional integer region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Public Members

int x1

int y1

int x2

int y2

struct OfxRGBAColourB

#include <ofxPixels.h>

Defines an 8 bit per component RGBA pixel.

Public Members

unsigned char r

unsigned char g

unsigned char b

unsigned char a

struct OfxRGBAColourD

#include <ofxPixels.h>

Defines a double precision floating point component RGBA pixel.

Public Members

double r

double g

double b

double a

struct OfxRGBAColourF

#include <ofxPixels.h>

Defines a floating point component RGBA pixel.

Public Members

float r

float g

float b

float a

struct OfxRGBAColourS

#include <ofxPixels.h>

Defines a 16 bit per component RGBA pixel.

Public Members

unsigned short r

unsigned short g

unsigned short b

unsigned short a

struct OfxRGBColourB

#include <ofxPixels.h>

Defines an 8 bit per component RGB pixel.

Public Members

unsigned char r

unsigned char g

unsigned char b

struct OfxRGBColourD

#include <ofxPixels.h>

Defines a double precision floating point component RGB pixel.

Public Members

double r

double g

double b

struct OfxRGBColourF

#include <ofxPixels.h>

Defines a floating point component RGB pixel.

Public Members

float r

float g

float b

struct OfxRGBColourS

#include <ofxPixels.h>

Defines a 16 bit per component RGB pixel.

Public Members

unsigned short r

unsigned short g

unsigned short b

struct OfxTimeLineSuiteV1

#include <ofxTimeLine.h>

Suite to control timelines.

This suite is used to enquire and control a timeline associated with a plug-in instance.

This is an optional suite in the Image Effect API.

Public Members

OfxStatus (*getTime)(void *instance, double *time)

Get the time value of the timeline that is controlling to the indicated effect.

instance is the instance of the effect changing the timeline, cast to a void *
time pointer through which the timeline value should be returned

This function returns the current time value of the timeline associated with the effect instance.

Return:

kOfxStatOK - the time enquiry was successful
kOfxStatFailed - the enquiry failed for some host specific reason
kOfxStatErrBadHandle - the effect handle was invalid

OfxStatus (*gotoTime)(void *instance, double time)

Move the timeline control to the indicated time.

instance is the instance of the effect changing the timeline, cast to a void *
time is the time to change the timeline to. This is in the temporal coordinate system of the effect.

This function moves the timeline to the indicated frame and returns. Any side effects of the timeline change are also triggered and completed before this returns (for example instance changed actions and renders if the output of the effect is being viewed).

Return:

kOfxStatOK - the time was changed successfully, will all side effects if the change completed
kOfxStatFailed - the change failed for some host specific reason
kOfxStatErrBadHandle - the effect handle was invalid
kOfxStatErrValue - the time was an illegal value

OfxStatus (*getTimeBounds)(void *instance, double *firstTime, double *lastTime)

Get the current bounds on a timeline.

instance is the instance of the effect changing the timeline, cast to a void *
firstTime is the first time on the timeline. This is in the temporal coordinate system of the effect.
lastTime is last time on the timeline. This is in the temporal coordinate system of the effect.

This function

Return:

kOfxStatOK - the time enquiry was successful
kOfxStatFailed - the enquiry failed for some host specific reason
kOfxStatErrBadHandle - the effect handle was invalid

struct OfxYUVAColourB

#include <ofxOld.h>

Defines an 8 bit per component YUVA pixel — ofxPixels.h Deprecated in 1.3, removed in 1.4.

Public Members

unsigned char y

unsigned char u

unsigned char v

unsigned char a

struct OfxYUVAColourF

#include <ofxOld.h>

Defines an floating point component YUVA pixel — ofxPixels.h.

Deprecated:

Deprecated in 1.3, removed in 1.4

Public Members

float y

float u

float v

float a

struct OfxYUVAColourS

#include <ofxOld.h>

Defines an 16 bit per component YUVA pixel — ofxPixels.h.

Deprecated:

Deprecated in 1.3, removed in 1.4

Public Members

unsigned short y

unsigned short u

unsigned short v

unsigned short a

file ofx-native-v1.5_aces-v1.3_ocio-v2.3.h

Contains the list of supported colourspaces. This file was auto-generated by scripts/genColour from ofx-native-v1.5_aces-v1.3_ocio-v2.3.

Defines

kOfxConfigIdentifier

kOfxColourspaceOfxDisplayHdr: ofx_display_hdr Any display-referred HDR video such as Rec. 2100 HLG or PQ.

kOfxColourspaceOfxDisplayHdrLabel

kOfxColourspaceOfxDisplayHdrEncoding

kOfxColourspaceOfxDisplayHdrIsData

kOfxColourspaceOfxDisplayHdrIsBasic

kOfxColourspaceOfxDisplayHdrIsCore

kOfxColourspaceOfxDisplayHdrIsDisplay

kOfxColourspaceOfxDisplaySdr: ofx_display_sdr Any display-referred SDR video such as Rec. 709.

kOfxColourspaceOfxDisplaySdrLabel

kOfxColourspaceOfxDisplaySdrEncoding

kOfxColourspaceOfxDisplaySdrIsData

kOfxColourspaceOfxDisplaySdrIsBasic

kOfxColourspaceOfxDisplaySdrIsCore

kOfxColourspaceOfxDisplaySdrIsDisplay

kOfxColourspaceOfxRaw: ofx_raw Image values should not be treated as colour, e.g. motion vectors or masks.

kOfxColourspaceOfxRawLabel

kOfxColourspaceOfxRawEncoding

kOfxColourspaceOfxRawIsData

kOfxColourspaceOfxRawIsBasic

kOfxColourspaceOfxRawIsCore

kOfxColourspaceOfxRawIsDisplay

kOfxColourspaceOfxSceneLinear: ofx_scene_linear Any scene-referred linear colourspace.

kOfxColourspaceOfxSceneLinearLabel

kOfxColourspaceOfxSceneLinearEncoding

kOfxColourspaceOfxSceneLinearIsData

kOfxColourspaceOfxSceneLinearIsBasic

kOfxColourspaceOfxSceneLinearIsCore

kOfxColourspaceOfxSceneLinearIsDisplay

kOfxColourspaceOfxSceneLog: ofx_scene_log Any scene-referred colourspace with a log transfer function.

kOfxColourspaceOfxSceneLogLabel

kOfxColourspaceOfxSceneLogEncoding

kOfxColourspaceOfxSceneLogIsData

kOfxColourspaceOfxSceneLogIsBasic

kOfxColourspaceOfxSceneLogIsCore

kOfxColourspaceOfxSceneLogIsDisplay

kOfxColourspaceSrgbDisplay

kOfxColourspaceSrgbDisplayLabel

kOfxColourspaceSrgbDisplayEncoding

kOfxColourspaceSrgbDisplayIsData

kOfxColourspaceSrgbDisplayIsBasic

kOfxColourspaceSrgbDisplayIsCore

kOfxColourspaceSrgbDisplayIsDisplay

kOfxColourspaceDisplayp3Display

kOfxColourspaceDisplayp3DisplayLabel

kOfxColourspaceDisplayp3DisplayEncoding

kOfxColourspaceDisplayp3DisplayIsData

kOfxColourspaceDisplayp3DisplayIsBasic

kOfxColourspaceDisplayp3DisplayIsCore

kOfxColourspaceDisplayp3DisplayIsDisplay

kOfxColourspaceRec1886Rec709Display

kOfxColourspaceRec1886Rec709DisplayLabel

kOfxColourspaceRec1886Rec709DisplayEncoding

kOfxColourspaceRec1886Rec709DisplayIsData

kOfxColourspaceRec1886Rec709DisplayIsBasic

kOfxColourspaceRec1886Rec709DisplayIsCore

kOfxColourspaceRec1886Rec709DisplayIsDisplay

kOfxColourspaceRec1886Rec2020Display

kOfxColourspaceRec1886Rec2020DisplayLabel

kOfxColourspaceRec1886Rec2020DisplayEncoding

kOfxColourspaceRec1886Rec2020DisplayIsData

kOfxColourspaceRec1886Rec2020DisplayIsBasic

kOfxColourspaceRec1886Rec2020DisplayIsCore

kOfxColourspaceRec1886Rec2020DisplayIsDisplay

kOfxColourspaceRec2100HlgDisplay

kOfxColourspaceRec2100HlgDisplayLabel

kOfxColourspaceRec2100HlgDisplayEncoding

kOfxColourspaceRec2100HlgDisplayIsData

kOfxColourspaceRec2100HlgDisplayIsBasic

kOfxColourspaceRec2100HlgDisplayIsCore

kOfxColourspaceRec2100HlgDisplayIsDisplay

kOfxColourspaceRec2100PqDisplay

kOfxColourspaceRec2100PqDisplayLabel

kOfxColourspaceRec2100PqDisplayEncoding

kOfxColourspaceRec2100PqDisplayIsData

kOfxColourspaceRec2100PqDisplayIsBasic

kOfxColourspaceRec2100PqDisplayIsCore

kOfxColourspaceRec2100PqDisplayIsDisplay

kOfxColourspaceSt2084P3d65Display

kOfxColourspaceSt2084P3d65DisplayLabel

kOfxColourspaceSt2084P3d65DisplayEncoding

kOfxColourspaceSt2084P3d65DisplayIsData

kOfxColourspaceSt2084P3d65DisplayIsBasic

kOfxColourspaceSt2084P3d65DisplayIsCore

kOfxColourspaceSt2084P3d65DisplayIsDisplay

kOfxColourspaceP3d65Display

kOfxColourspaceP3d65DisplayLabel

kOfxColourspaceP3d65DisplayEncoding

kOfxColourspaceP3d65DisplayIsData

kOfxColourspaceP3d65DisplayIsBasic

kOfxColourspaceP3d65DisplayIsCore

kOfxColourspaceP3d65DisplayIsDisplay

kOfxColourspaceACES20651

kOfxColourspaceACES20651Label

kOfxColourspaceACES20651Encoding

kOfxColourspaceACES20651IsData

kOfxColourspaceACES20651IsBasic

kOfxColourspaceACES20651IsCore

kOfxColourspaceACES20651IsDisplay

kOfxColourspaceACEScc

kOfxColourspaceACESccLabel

kOfxColourspaceACESccEncoding

kOfxColourspaceACESccIsData

kOfxColourspaceACESccIsBasic

kOfxColourspaceACESccIsCore

kOfxColourspaceACESccIsDisplay

kOfxColourspaceACEScct

kOfxColourspaceACEScctLabel

kOfxColourspaceACEScctEncoding

kOfxColourspaceACEScctIsData

kOfxColourspaceACEScctIsBasic

kOfxColourspaceACEScctIsCore

kOfxColourspaceACEScctIsDisplay

kOfxColourspaceACEScg

kOfxColourspaceACEScgLabel

kOfxColourspaceACEScgEncoding

kOfxColourspaceACEScgIsData

kOfxColourspaceACEScgIsBasic

kOfxColourspaceACEScgIsCore

kOfxColourspaceACEScgIsDisplay

kOfxColourspaceLinP3d65

kOfxColourspaceLinP3d65Label

kOfxColourspaceLinP3d65Encoding

kOfxColourspaceLinP3d65IsData

kOfxColourspaceLinP3d65IsBasic

kOfxColourspaceLinP3d65IsCore

kOfxColourspaceLinP3d65IsDisplay

kOfxColourspaceLinRec2020

kOfxColourspaceLinRec2020Label

kOfxColourspaceLinRec2020Encoding

kOfxColourspaceLinRec2020IsData

kOfxColourspaceLinRec2020IsBasic

kOfxColourspaceLinRec2020IsCore

kOfxColourspaceLinRec2020IsDisplay

kOfxColourspaceLinRec709Srgb

kOfxColourspaceLinRec709SrgbLabel

kOfxColourspaceLinRec709SrgbEncoding

kOfxColourspaceLinRec709SrgbIsData

kOfxColourspaceLinRec709SrgbIsBasic

kOfxColourspaceLinRec709SrgbIsCore

kOfxColourspaceLinRec709SrgbIsDisplay

kOfxColourspaceG18Rec709Tx

kOfxColourspaceG18Rec709TxLabel

kOfxColourspaceG18Rec709TxEncoding

kOfxColourspaceG18Rec709TxIsData

kOfxColourspaceG18Rec709TxIsBasic

kOfxColourspaceG18Rec709TxIsCore

kOfxColourspaceG18Rec709TxIsDisplay

kOfxColourspaceG22Ap1Tx

kOfxColourspaceG22Ap1TxLabel

kOfxColourspaceG22Ap1TxEncoding

kOfxColourspaceG22Ap1TxIsData

kOfxColourspaceG22Ap1TxIsBasic

kOfxColourspaceG22Ap1TxIsCore

kOfxColourspaceG22Ap1TxIsDisplay

kOfxColourspaceG22Rec709Tx

kOfxColourspaceG22Rec709TxLabel

kOfxColourspaceG22Rec709TxEncoding

kOfxColourspaceG22Rec709TxIsData

kOfxColourspaceG22Rec709TxIsBasic

kOfxColourspaceG22Rec709TxIsCore

kOfxColourspaceG22Rec709TxIsDisplay

kOfxColourspaceG24Rec709Tx

kOfxColourspaceG24Rec709TxLabel

kOfxColourspaceG24Rec709TxEncoding

kOfxColourspaceG24Rec709TxIsData

kOfxColourspaceG24Rec709TxIsBasic

kOfxColourspaceG24Rec709TxIsCore

kOfxColourspaceG24Rec709TxIsDisplay

kOfxColourspaceSrgbEncodedAp1Tx

kOfxColourspaceSrgbEncodedAp1TxLabel

kOfxColourspaceSrgbEncodedAp1TxEncoding

kOfxColourspaceSrgbEncodedAp1TxIsData

kOfxColourspaceSrgbEncodedAp1TxIsBasic

kOfxColourspaceSrgbEncodedAp1TxIsCore

kOfxColourspaceSrgbEncodedAp1TxIsDisplay

kOfxColourspaceSrgbEncodedP3d65Tx

kOfxColourspaceSrgbEncodedP3d65TxLabel

kOfxColourspaceSrgbEncodedP3d65TxEncoding

kOfxColourspaceSrgbEncodedP3d65TxIsData

kOfxColourspaceSrgbEncodedP3d65TxIsBasic

kOfxColourspaceSrgbEncodedP3d65TxIsCore

kOfxColourspaceSrgbEncodedP3d65TxIsDisplay

kOfxColourspaceSrgbTx

kOfxColourspaceSrgbTxLabel

kOfxColourspaceSrgbTxEncoding

kOfxColourspaceSrgbTxIsData

kOfxColourspaceSrgbTxIsBasic

kOfxColourspaceSrgbTxIsCore

kOfxColourspaceSrgbTxIsDisplay

kOfxColourspaceRaw

kOfxColourspaceRawLabel

kOfxColourspaceRawEncoding

kOfxColourspaceRawIsData

kOfxColourspaceRawIsBasic

kOfxColourspaceRawIsCore

kOfxColourspaceRawIsDisplay

kOfxColourspaceCIEXYZD65

kOfxColourspaceCIEXYZD65Label

kOfxColourspaceCIEXYZD65Encoding

kOfxColourspaceCIEXYZD65IsData

kOfxColourspaceCIEXYZD65IsBasic

kOfxColourspaceCIEXYZD65IsCore

kOfxColourspaceCIEXYZD65IsDisplay

kOfxColourspaceP3d60Display

kOfxColourspaceP3d60DisplayLabel

kOfxColourspaceP3d60DisplayEncoding

kOfxColourspaceP3d60DisplayIsData

kOfxColourspaceP3d60DisplayIsBasic

kOfxColourspaceP3d60DisplayIsCore

kOfxColourspaceP3d60DisplayIsDisplay

kOfxColourspaceP3DciDisplay

kOfxColourspaceP3DciDisplayLabel

kOfxColourspaceP3DciDisplayEncoding

kOfxColourspaceP3DciDisplayIsData

kOfxColourspaceP3DciDisplayIsBasic

kOfxColourspaceP3DciDisplayIsCore

kOfxColourspaceP3DciDisplayIsDisplay

kOfxColourspaceADX10

kOfxColourspaceADX10Label

kOfxColourspaceADX10Encoding

kOfxColourspaceADX10IsData

kOfxColourspaceADX10IsBasic

kOfxColourspaceADX10IsCore

kOfxColourspaceADX10IsDisplay

kOfxColourspaceADX16

kOfxColourspaceADX16Label

kOfxColourspaceADX16Encoding

kOfxColourspaceADX16IsData

kOfxColourspaceADX16IsBasic

kOfxColourspaceADX16IsCore

kOfxColourspaceADX16IsDisplay

kOfxColourspaceLinArriWideGamut3

kOfxColourspaceLinArriWideGamut3Label

kOfxColourspaceLinArriWideGamut3Encoding

kOfxColourspaceLinArriWideGamut3IsData

kOfxColourspaceLinArriWideGamut3IsBasic

kOfxColourspaceLinArriWideGamut3IsCore

kOfxColourspaceLinArriWideGamut3IsDisplay

kOfxColourspaceArriLogc3Ei800

kOfxColourspaceArriLogc3Ei800Label

kOfxColourspaceArriLogc3Ei800Encoding

kOfxColourspaceArriLogc3Ei800IsData

kOfxColourspaceArriLogc3Ei800IsBasic

kOfxColourspaceArriLogc3Ei800IsCore

kOfxColourspaceArriLogc3Ei800IsDisplay

kOfxColourspaceLinArriWideGamut4

kOfxColourspaceLinArriWideGamut4Label

kOfxColourspaceLinArriWideGamut4Encoding

kOfxColourspaceLinArriWideGamut4IsData

kOfxColourspaceLinArriWideGamut4IsBasic

kOfxColourspaceLinArriWideGamut4IsCore

kOfxColourspaceLinArriWideGamut4IsDisplay

kOfxColourspaceArriLogc4

kOfxColourspaceArriLogc4Label

kOfxColourspaceArriLogc4Encoding

kOfxColourspaceArriLogc4IsData

kOfxColourspaceArriLogc4IsBasic

kOfxColourspaceArriLogc4IsCore

kOfxColourspaceArriLogc4IsDisplay

kOfxColourspaceBmdfilmWidegamutGen5

kOfxColourspaceBmdfilmWidegamutGen5Label

kOfxColourspaceBmdfilmWidegamutGen5Encoding

kOfxColourspaceBmdfilmWidegamutGen5IsData

kOfxColourspaceBmdfilmWidegamutGen5IsBasic

kOfxColourspaceBmdfilmWidegamutGen5IsCore

kOfxColourspaceBmdfilmWidegamutGen5IsDisplay

kOfxColourspaceDavinciIntermediateWidegamut

kOfxColourspaceDavinciIntermediateWidegamutLabel

kOfxColourspaceDavinciIntermediateWidegamutEncoding

kOfxColourspaceDavinciIntermediateWidegamutIsData

kOfxColourspaceDavinciIntermediateWidegamutIsBasic

kOfxColourspaceDavinciIntermediateWidegamutIsCore

kOfxColourspaceDavinciIntermediateWidegamutIsDisplay

kOfxColourspaceLinBmdWidegamutGen5

kOfxColourspaceLinBmdWidegamutGen5Label

kOfxColourspaceLinBmdWidegamutGen5Encoding

kOfxColourspaceLinBmdWidegamutGen5IsData

kOfxColourspaceLinBmdWidegamutGen5IsBasic

kOfxColourspaceLinBmdWidegamutGen5IsCore

kOfxColourspaceLinBmdWidegamutGen5IsDisplay

kOfxColourspaceLinDavinciWidegamut

kOfxColourspaceLinDavinciWidegamutLabel

kOfxColourspaceLinDavinciWidegamutEncoding

kOfxColourspaceLinDavinciWidegamutIsData

kOfxColourspaceLinDavinciWidegamutIsBasic

kOfxColourspaceLinDavinciWidegamutIsCore

kOfxColourspaceLinDavinciWidegamutIsDisplay

kOfxColourspaceCanonlog2CinemagamutD55

kOfxColourspaceCanonlog2CinemagamutD55Label

kOfxColourspaceCanonlog2CinemagamutD55Encoding

kOfxColourspaceCanonlog2CinemagamutD55IsData

kOfxColourspaceCanonlog2CinemagamutD55IsBasic

kOfxColourspaceCanonlog2CinemagamutD55IsCore

kOfxColourspaceCanonlog2CinemagamutD55IsDisplay

kOfxColourspaceCanonlog3CinemagamutD55

kOfxColourspaceCanonlog3CinemagamutD55Label

kOfxColourspaceCanonlog3CinemagamutD55Encoding

kOfxColourspaceCanonlog3CinemagamutD55IsData

kOfxColourspaceCanonlog3CinemagamutD55IsBasic

kOfxColourspaceCanonlog3CinemagamutD55IsCore

kOfxColourspaceCanonlog3CinemagamutD55IsDisplay

kOfxColourspaceLinCinemagamutD55

kOfxColourspaceLinCinemagamutD55Label

kOfxColourspaceLinCinemagamutD55Encoding

kOfxColourspaceLinCinemagamutD55IsData

kOfxColourspaceLinCinemagamutD55IsBasic

kOfxColourspaceLinCinemagamutD55IsCore

kOfxColourspaceLinCinemagamutD55IsDisplay

kOfxColourspaceLinVgamut

kOfxColourspaceLinVgamutLabel

kOfxColourspaceLinVgamutEncoding

kOfxColourspaceLinVgamutIsData

kOfxColourspaceLinVgamutIsBasic

kOfxColourspaceLinVgamutIsCore

kOfxColourspaceLinVgamutIsDisplay

kOfxColourspaceVlogVgamut

kOfxColourspaceVlogVgamutLabel

kOfxColourspaceVlogVgamutEncoding

kOfxColourspaceVlogVgamutIsData

kOfxColourspaceVlogVgamutIsBasic

kOfxColourspaceVlogVgamutIsCore

kOfxColourspaceVlogVgamutIsDisplay

kOfxColourspaceLinRedwidegamutrgb

kOfxColourspaceLinRedwidegamutrgbLabel

kOfxColourspaceLinRedwidegamutrgbEncoding

kOfxColourspaceLinRedwidegamutrgbIsData

kOfxColourspaceLinRedwidegamutrgbIsBasic

kOfxColourspaceLinRedwidegamutrgbIsCore

kOfxColourspaceLinRedwidegamutrgbIsDisplay

kOfxColourspaceLog3g10Redwidegamutrgb

kOfxColourspaceLog3g10RedwidegamutrgbLabel

kOfxColourspaceLog3g10RedwidegamutrgbEncoding

kOfxColourspaceLog3g10RedwidegamutrgbIsData

kOfxColourspaceLog3g10RedwidegamutrgbIsBasic

kOfxColourspaceLog3g10RedwidegamutrgbIsCore

kOfxColourspaceLog3g10RedwidegamutrgbIsDisplay

kOfxColourspaceLinSgamut3

kOfxColourspaceLinSgamut3Label

kOfxColourspaceLinSgamut3Encoding

kOfxColourspaceLinSgamut3IsData

kOfxColourspaceLinSgamut3IsBasic

kOfxColourspaceLinSgamut3IsCore

kOfxColourspaceLinSgamut3IsDisplay

kOfxColourspaceLinSgamut3cine

kOfxColourspaceLinSgamut3cineLabel

kOfxColourspaceLinSgamut3cineEncoding

kOfxColourspaceLinSgamut3cineIsData

kOfxColourspaceLinSgamut3cineIsBasic

kOfxColourspaceLinSgamut3cineIsCore

kOfxColourspaceLinSgamut3cineIsDisplay

kOfxColourspaceLinVeniceSgamut3

kOfxColourspaceLinVeniceSgamut3Label

kOfxColourspaceLinVeniceSgamut3Encoding

kOfxColourspaceLinVeniceSgamut3IsData

kOfxColourspaceLinVeniceSgamut3IsBasic

kOfxColourspaceLinVeniceSgamut3IsCore

kOfxColourspaceLinVeniceSgamut3IsDisplay

kOfxColourspaceLinVeniceSgamut3cine

kOfxColourspaceLinVeniceSgamut3cineLabel

kOfxColourspaceLinVeniceSgamut3cineEncoding

kOfxColourspaceLinVeniceSgamut3cineIsData

kOfxColourspaceLinVeniceSgamut3cineIsBasic

kOfxColourspaceLinVeniceSgamut3cineIsCore

kOfxColourspaceLinVeniceSgamut3cineIsDisplay

kOfxColourspaceSlog3Sgamut3

kOfxColourspaceSlog3Sgamut3Label

kOfxColourspaceSlog3Sgamut3Encoding

kOfxColourspaceSlog3Sgamut3IsData

kOfxColourspaceSlog3Sgamut3IsBasic

kOfxColourspaceSlog3Sgamut3IsCore

kOfxColourspaceSlog3Sgamut3IsDisplay

kOfxColourspaceSlog3Sgamut3cine

kOfxColourspaceSlog3Sgamut3cineLabel

kOfxColourspaceSlog3Sgamut3cineEncoding

kOfxColourspaceSlog3Sgamut3cineIsData

kOfxColourspaceSlog3Sgamut3cineIsBasic

kOfxColourspaceSlog3Sgamut3cineIsCore

kOfxColourspaceSlog3Sgamut3cineIsDisplay

kOfxColourspaceSlog3VeniceSgamut3

kOfxColourspaceSlog3VeniceSgamut3Label

kOfxColourspaceSlog3VeniceSgamut3Encoding

kOfxColourspaceSlog3VeniceSgamut3IsData

kOfxColourspaceSlog3VeniceSgamut3IsBasic

kOfxColourspaceSlog3VeniceSgamut3IsCore

kOfxColourspaceSlog3VeniceSgamut3IsDisplay

kOfxColourspaceSlog3VeniceSgamut3cine

kOfxColourspaceSlog3VeniceSgamut3cineLabel

kOfxColourspaceSlog3VeniceSgamut3cineEncoding

kOfxColourspaceSlog3VeniceSgamut3cineIsData

kOfxColourspaceSlog3VeniceSgamut3cineIsBasic

kOfxColourspaceSlog3VeniceSgamut3cineIsCore

kOfxColourspaceSlog3VeniceSgamut3cineIsDisplay

kOfxColourspaceCameraRec709

kOfxColourspaceCameraRec709Label

kOfxColourspaceCameraRec709Encoding

kOfxColourspaceCameraRec709IsData

kOfxColourspaceCameraRec709IsBasic

kOfxColourspaceCameraRec709IsCore

kOfxColourspaceCameraRec709IsDisplay

kOfxColourspaceRoleAcesInterchange

Roles - standard names used for compatibility with common OCIO configs.

aces_interchange Guaranteed to be ACES2065-1.

kOfxColourspaceRoleAcesInterchangeIsBasic

kOfxColourspaceRoleAcesInterchangeIsCore

kOfxColourspaceRoleCieXyzD65Interchange: cie_xyz_d65_interchange CIE XYZ colorimetry with the neutral axis at D65.

kOfxColourspaceRoleCieXyzD65InterchangeIsBasic

kOfxColourspaceRoleCieXyzD65InterchangeIsCore

kOfxColourspaceRoleColorPicking: color_picking The colourspace to use for colour pickers, typically a display colourspace.

kOfxColourspaceRoleColorPickingIsBasic

kOfxColourspaceRoleColorPickingIsCore

kOfxColourspaceRoleColorTiming: color_timing A colourspace suitable for colour grading, typically a log colourspace.

kOfxColourspaceRoleColorTimingIsBasic

kOfxColourspaceRoleColorTimingIsCore

kOfxColourspaceRoleCompositingLog: compositing_log Any scene-referred colourspace with a log transfer function.

kOfxColourspaceRoleCompositingLogIsBasic

kOfxColourspaceRoleCompositingLogIsCore

kOfxColourspaceRoleData: data Image values should not be treated as colour, e.g. motion vectors or masks. Mapped to the raw colourspace.

kOfxColourspaceRoleDataIsBasic

kOfxColourspaceRoleDataIsCore

kOfxColourspaceRoleMattePaint: matte_paint A colourspace suitable for matte painting.

kOfxColourspaceRoleMattePaintIsBasic

kOfxColourspaceRoleMattePaintIsCore

kOfxColourspaceRoleSceneLinear: scene_linear Any scene-referred linear colourspace.

kOfxColourspaceRoleSceneLinearIsBasic

kOfxColourspaceRoleSceneLinearIsCore

kOfxColourspaceRoleTexturePaint: texture_paint A colourspace suitable for texture painting, typically sRGB.

kOfxColourspaceRoleTexturePaintIsBasic

kOfxColourspaceRoleTexturePaintIsCore

file ofxColour.h

#include “ofx-native-v1.5_aces-v1.3_ocio-v2.3.h”

Contains the API for colourspace data exchange.

Defines

kOfxImageEffectPropColourManagementStyle

What style of colour management does the host or plug-in offer?

Define OFX_NO_DEFAULT_COLORSPACE_HEADER if you want to manage the colourspace headers yourself. If this is not defined, the latest ofx-native config will be included.

Hosts should set this property if they will provide colourspace information to plug-ins. Plug-ins should set this property if they can use host-provided colourspace information. Collectively, the full, core and basic styles are referred to as native colour management. OCIO is used as the reference for the colour management API, but is not required to implement the native styles.

The colourspace strings used in the native styles are from an OFX-specific OCIO config which is currently based on the OCIO ACES Studio built-in config, studio-config-v2.1.0_aces-v1.3_ocio-v2.3, and stored for OFX purposes in ofx-native-v1.5_aces-v1.3_ocio-v2.3.h (referred to as the config header). Additionally, there is a scheme for cross-referencing between clips, and a set of “basic colourspaces”, which are designed to be generic names for a family of colourspaces. When a basic colourspace is used, this means the host is free to choose any colourspace with the same encoding and reference space (scene vs display).

The assumption is that OCIO > Full > Core > Basic, so the highest style supported by both host and plug-in should usually be chosen by the host. The chosen style must be set by the host using this property on an image effect instance.

Valid Values - This must be one of
- kOfxImageEffectColourManagementNone - no colour management
- kOfxImageEffectColourManagementBasic - only basic colourspaces from the config header may be used
- kOfxImageEffectColourManagementCore - only core colourspaces from the config header may be used
- kOfxImageEffectColourManagementFull - any colourspace from the config header may be used
- kOfxImageEffectColourManagementOCIO - any OCIO config may be used (implies use of the OCIO library)

kOfxImageEffectColourManagementNone

kOfxImageEffectColourManagementBasic

kOfxImageEffectColourManagementCore

kOfxImageEffectColourManagementFull

kOfxImageEffectColourManagementOCIO

kOfxImageEffectPropColourManagementAvailableConfigs

What native mode configs are supported?

While the API for colour management is expected to be stable, the set of colourspaces will evolve over time. This property must be set by both plug-ins and hosts specifying the list of native mode configs that are available on each side.

Valid Values - A list of config identifiers. The only currently supported value is ofx-native-v1.5_aces-v1.3_ocio-v2.3.

kOfxImageEffectPropColourManagementConfig

The native colour management config to be used for this instance.

The host must set this property to indicate the native colour management config the plug-in should be used to look up colourspace strings. It is important to set this even in OCIO mode, to define the basic colourspaces.

Valid Values - any string provided by the plug-in in kOfxImageEffectPropColourManagementAvailableConfigs

kOfxImageEffectPropOCIOConfig

The path to the OCIO config used for this instance.

A host must set this property on any effect instances where it has negotiated OCIO colour management (kOfxImageEffectColourManagementOCIO). Use of URIs for built-in configs, such as ocio://default is permitted.

Valid Values - Filesystem path to the config or URI starting ocio://

kOfxImageClipPropColourspace

The colourspace used for this clip.

Hosts should set this property to the colourspace of the input clip. Typically it will be set to the working colourspace of the host but could be any valid colourspace.

Both host and plug-in should use the value of kOfxImageClipPropPreferredColourspace where reasonable.

In OCIO mode, a basic colourspace may have been requested via kOfxImageClipPropPreferredColourspaces, but the actual colourspace used should be reported in this property. If an OCIO host has added the basic colourspaces to its config as roles or aliases, they would be permitted here.

Cross-referencing between clips is possible by setting this property to “OfxColourspace_<clip>”. For example a plug-in may set this property during kOfxImageEffectActionGetOutputColourspace to “OfxColourspace_Source”, telling he host that the colourspace of the output matches the “Source” input clip. In the basic style, plug-ins are recommended to use cross-referencing for their output clip unless kOfxColourspaceRaw is required.

If a clip sets OfxImageClipPropIsMask or it only supports OfxImageComponentAlpha, colour management is disabled and this property must be unset.

Valid Values - colourspace that is permitted under the style in use. For OCIO, any string acceptable to Config::getColorSpace()

kOfxImageClipPropPreferredColourspaces

The preferred colourspace for this clip.

Plug-ins may set this property during kOfxImageEffectActionGetClipPreferences to request images in a colourspace which is convenient for them. The property is an ordered set of colourspace identifiers, which may be any of the names or aliases supported by the colour management style in use. If plug-ins prefer more esoteric colourspaces, they are encouraged to also include basic colourspacesas a fallback. For example a colour grading plug-in which supports a specific camera and expects a log colourspace might list:

“arri_logc4”, “arri_logc3_ei800”, “ACEScct”, “ofx_scene_log”

The host is free to choose any colourspace from this list, but should favour the first mutually agreeable colourspace, and set kOfxImageClipPropColourspace to tell the plug-in which colourspace has been selected. A host does not need to convert into the first choice just because it can, as this might be inefficient, and should avoid scene-to-display or display-to-scene conversions where possible.

In the event that the host cannot supply images in a requested colourspace, it may supply images in any valid colourspace. Plug-ins must check kOfxImageClipPropColourspace to see if their request was satisfied.

In both native and OCIO modes, it is recommended to include basic colourspaces in this list, because this gives the host more flexibility to avoid unnecessary colourspace conversions.

Hosts can invoke kOfxImageEffectActionGetOutputColourspace to set this on an output clip, which could be helpful in a generator context, and plug-ins should follow the same logic as hosts when deciding which colourspace to use.

It might be much less costly for a host to perform a conversion than a plug-in, so in the example of a plug-in which performs all internal processing in scene linear, it is sensible for the plug-in to universally assert that preference by preferring kOfxColourspaceOfxSceneLinear, and for the host to honour it if possible. However, if a plug-in is capable of adapting to any input colourspace, it should not set this preference.

Cross-referencing between clips is possible by setting this property to “OfxColourspace_<clip>”. For example, a plug-in in a transition context may set this property on its “SourceTo” clip to “OfxColourspace_SourceFrom”, telling the host it would like both input clips to be in the same colourspace.

If a plug-in has inputs which expect motion vectors, depth values or other non-colour channels, it should set the preferred colourspace to kOfxColourspaceRaw. Similarly, if a host requests outputs in a typical scene colourspace, but the plug-in is producing motion vectors, it should ignore the request and set kOfxImageClipPropColourspace to kOfxColourspaceRaw.

Valid Values - colourspace that is permitted under the style in use. For Basic, any colourspace from the config header where IsBasic is true. For Core, any colourspace from the config header where IsCore is true. For Full, any colourspace from the config header. For OCIO, any string acceptable to Config::getColorSpace(), or a basic colourspace.

kOfxImageEffectPropDisplayColourspace

The display colourspace used in the plug-in’s viewport.

Used with native colour management styles, this property is relevant for plug-ins which have their own viewport in a custom window. Plug-ins should not expect this to be available during a render event. Hosts should set this property to a display colourspace which matches that used in its own viewport. For a multi-display system, choose the colourspace for the display device where a native window would appear by default. A host which supports OCIO should use the OCIO-specific display and view properties instead.

Valid Values - any colourspace from the config header

kOfxImageEffectPropOCIODisplay

The OCIO display to be used in the plug-in’s viewport.

This OCIO-specific property allows the host to specify which OCIO display should be used. If not defined, the default rules for choosing a display will be followed.

Valid Values - OCIO display that is present in the config

kOfxImageEffectPropOCIOView

The OCIO view to be used in the plug-in’s viewport.

This OCIO-specific property allows the host to specify which OCIO view should be used. If not defined, the default rules for choosing a view will be followed.

Valid Values - OCIO view for the display specified by kOfxImageEffectPropOCIODisplay

kOfxImageEffectActionGetOutputColourspace

This action allows a host to ask an effect, given a list of preferred colourspaces, what colourspace will be used for its output clip. This should be called after first gathering the plug-in’s preferred input colourspaces via OfxImageEffectActionGetClipPreferences.

Cross-references to input clip colourspaces are permitted, for example in a filter context, the host might request “OfxColourspace_Source”.

If a host wants to rely on the output clip colourspace, it must call this action whenever the effect instance is changed. Do not assume that the output colourspace will be the same across all instances of an effect, or even for the lifetime of an effect instance, because a plug-in may change its output colourspace based on a user changing a parameter. Assume that the plug-in will check kOfxImageClipPropColourspace on its input clips during this action in order to decide the output clip colourspace, so the action must be called again if the host changes any of the other colour properties.

On a successful return from this action, the host must set kOfxImageClipPropColourspace on the instance’s output clip to the value from outArgs.

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – a property set containing the property
- kOfxImageClipPropPreferredColourspaces the host’s list of preferred colourspaces
outArgs – a property set containing the property
- kOfxImageClipPropColourspace the colourspace selected by the plug-in, which may be a cross-reference to an input clip.

Returns:

kOfxStatOK, the action was trapped and the colourspace was set in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the colourspace of the first input clip
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

file ofxCore.h

#include “stddef.h”

#include <limits.h>

Contains the core OFX architectural struct and function definitions. For more details on the basic OFX architecture, see Architecture.

Defines

OfxExport

Platform independent export macro.

This macro is to be used before any symbol that is to be exported from a plug-in. This is OS/compiler dependent.

kOfxActionLoad

This action 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 handle, inArgs and outArgs arguments to the mainEntry are redundant and should be set to NULL.

Pre:

The plugin’s OfxPlugin::setHost function has been called

Post:

This action will not be called again while the binary containing the plug-in remains loaded.

Returns:

kOfxStatOK, the action was trapped and all was well,
kOfxStatReplyDefault, the action was ignored,
kOfxStatFailed
, the load action failed, no further actions will be passed to the plug-in. Interpret if possible kOfxStatFailed as plug-in indicating it does not want to load Do not create an entry in the host’s UI for plug-in then.

Plug-in also has the option to return 0 for OfxGetNumberOfPlugins or kOfxStatFailed if host supports OfxSetHost in which case kOfxActionLoad will never be called.
kOfxStatErrFatal, fatal error in the plug-in.

kOfxActionDescribe

The kOfxActionDescribe is the second action passed to a plug-in. It is where a plugin defines how it behaves and the resources it needs to function.

Note that the handle passed in acts as a descriptor for, rather than an instance of the plugin. The handle is global and unique. The plug-in is at liberty to cache the handle away for future reference until the plug-in is unloaded.

Most importantly, the effect must set what image effect contexts it is capable of working in.

This action must be trapped, it is not optional.

Parameters:

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

Pre:

kOfxActionLoad has been called

Post:

kOfxActionDescribe will not be called again, unless it fails and returns one of the error codes where the host is allowed to attempt the action again
the handle argument, being the global plug-in description handle, is a valid handle from the end of a successful describe action until the end of the kOfxActionUnload action (ie: the plug-in can cache it away without worrying about it changing between actions).
kOfxImageEffectActionDescribeInContext will be called once for each context that the host and plug-in mutually support. If a plug-in does not report to support any context supported by host, host should not enable the plug-in.

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatErrMissingHostFeature, in which the plugin will be unloaded and ignored, plugin may post message
kOfxStatErrMemory, in which case describe may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxActionUnload

This action 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.

Pre:

the kOfxActionLoad action has been called
all instances of a plugin have been destroyed

Post:

No other actions will be called.

Returns:

kOfxStatOK, the action was trapped all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal, in which case we the program will be forced to quit

kOfxActionPurgeCaches

This action is an action that may be passed to a plug-in instance from time to time in low memory situations. Instances receiving 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.

Parameters:

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

Pre:

kOfxActionCreateInstance has been called on the instance handle,

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxActionSyncPrivateData

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.

Parameters:

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

Pre:

kOfxActionCreateInstance has been called on the instance handle,

Post:

Any private state data can be reconstructed from the parameter set,

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxActionCreateInstance

This action 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.

Parameters:

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

Pre:

kOfxActionDescribe has been called
the instance is fully constructed, with all objects requested in the describe actions (eg, parameters and clips) have been constructed and have had their initial values set. This means that if the values are being loaded from an old setup, that load should have taken place before the create instance action is called.

Post:

the instance pointer will be valid until the kOfxActionDestroyInstance action is passed to the plug-in with the same instance handle

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored, but all was well anyway
kOfxStatErrFatal
kOfxStatErrMemory, in which case this may be called again after a memory purge
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message if possible and the host should destroy the instanace handle and not attempt to proceed further

kOfxActionDestroyInstance

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.

kOfxStatOK, the action was trapped and all was well,
kOfxStatReplyDefault, the action was ignored as the effect had nothing to do,
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message.

Parameters:

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

Pre:

kOfxActionCreateInstance has been called on the handle,
the instance has not had any of its members destroyed yet,

Post:

the instance pointer is no longer valid and any operation on it will be undefined

Returns:

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.

kOfxActionInstanceChanged

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.

Parameters:

handle – handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropType The type of the thing that changed which will be one of..
- kOfxTypeParameter Indicating a parameter’s value has changed in some way
- kOfxTypeClip A clip to an image effect has changed in some way (for Image Effect Plugins only)
- kOfxPropName the name of the thing that was changed in the instance
- kOfxPropChangeReason what triggered the change, which will be one of…
- kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,
- kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action
- kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time
- kOfxPropTime
- the effect time at which the chang occurred (for Image Effect Plugins only)
- kOfxImageEffectPropRenderScale
- the render scale currently being applied to any image fetched from a clip (for Image Effect Plugins only)
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
kOfxActionBeginInstanceChanged has been called on the instance handle.

Post:

kOfxActionEndInstanceChanged will be called on the instance handle.

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxActionBeginInstanceChanged

The kOfxActionBeginInstanceChanged and kOfxActionEndInstanceChanged actions 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.

Parameters:

handle – handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropChangeReason what triggered the change, which will be one of…
- kOfxChangeUserEdited - the user or host changed the instance somehow and caused a change to something, this includes undo/redos, resets and loading values from files or presets,
- kOfxChangePluginEdited - the plugin itself has changed the value of the instance in some action
- kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time
outArgs – is redundant and is set to NULL

Post:

For kOfxActionBeginInstanceChanged , kOfxActionCreateInstance has been called on the instance handle.
For kOfxActionEndInstanceChanged , kOfxActionBeginInstanceChanged has been called on the instance handle.
kOfxActionCreateInstance has been called on the instance handle.

Post:

For kOfxActionBeginInstanceChanged, kOfxActionInstanceChanged will be called at least once on the instance handle.
kOfxActionEndInstanceChanged will be called on the instance handle.

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxActionEndInstanceChanged: Action called after the end of a set of kOfxActionEndInstanceChanged actions, used with kOfxActionBeginInstanceChanged to bracket a grouped set of changes, see kOfxActionBeginInstanceChanged.

kOfxActionBeginInstanceEdit

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.

Parameters:

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

Pre:

kOfxActionCreateInstance has been called on the instance handle,

Post:

kOfxActionEndInstanceEdit will be called when the last editor is closed on the instance

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxActionEndInstanceEdit

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.

Parameters:

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

Pre:

kOfxActionBeginInstanceEdit has been called on the instance handle,

Post:

no user interface is open on the instance

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored
kOfxStatErrFatal,
kOfxStatFailed, something went wrong, but no error code appropriate, the plugin should to post a message

kOfxPropAPIVersion

Property on the host descriptor, saying what API version of the API is being implemented.

This is a version string that will specify which version of the API is being implemented by a host. It can have multiple values. For example “1.0”, “1.2.4” etc…..

If this is not present, it is safe to assume that the version of the API is “1.0”.

kOfxPropTime: General property used to get/set the time of something.

kOfxPropIsInteractive

Indicates if a host is actively editing the effect with some GUI.

If false, the effect currently has no interface. This may be because the effect is loaded in a background render host, or it may be loaded on an interactive host that has not yet opened an editor for the effect.

The output of an effect should only ever depend on the state of its parameters, not on the interactive flag. The interactive flag is more a courtesy flag to let a plugin know that it has an interface. If a plugin wants to have its behaviour depend on the interactive flag, it should make a secret parameter which shadows the state of the flag.

kOfxPluginPropFilePath

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’

kOfxPropInstanceData

A private data pointer that the plug-in can store its own data behind.

This data pointer is unique to each plug-in instance, so two instances of the same plug-in do not share the same data pointer. Use it to hang any needed private data structures.

kOfxPropType

General property, used to identify the kind of an object behind a handle.

Valid Values - currently this can be…

kOfxPropName

Unique name of an object.

This property is used to label objects uniquely among objects of that type. It is typically set when a plugin creates a new object with a function that takes a name.

kOfxPropVersion

Identifies a specific version of a host or plugin.

This is a multi dimensional integer property that represents the version of a host (host descriptor), or plugin (plugin descriptor). These represent a version number of the form ‘1.2.3.4’, with each dimension adding another ‘dot’ on the right.

A version is considered to be more recent than another if its ordered set of values is lexicographically greater than another, reading left to right. (ie: 1.2.4 is smaller than 1.2.6). Also, if the number of dimensions is different, then the values of the missing dimensions are considered to be zero (so 1.2.4 is greater than 1.2).

- Valid Values - positive integers

kOfxPropVersionLabel

Unique user readable version string of a plugin or host.

This is purely for user feedback, a plugin or host should use kOfxPropVersion if they need to check for specific versions.

- Valid Values - ASCII string

kOfxPropPluginDescription

Description of the plug-in to a user.

This is a string giving a potentially verbose description of the effect.

- Valid Values - UTF8 string

kOfxPropLabel

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.

kOfxPropIcon

If set this tells the host to use an icon instead of a label for some object in the interface.

The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon.

The first dimension, if set, will the name of and SVG file, the second a PNG file.

- Valid Values - ASCII string

kOfxPropShortLabel

Short user visible name of an object.

This is a shorter version of the label, typically 13 character glyphs or less. Hosts should use this if they have limited display space for their object labels.

kOfxPropLongLabel

Long user visible name of an object.

This is a longer version of the label, typically 32 character glyphs or so. Hosts should use this if they have mucg display space for their object labels.

kOfxPropChangeReason

Indicates why a plug-in changed.

Argument property for the kOfxActionInstanceChanged action.

- Valid Values - this can be...
   - ::kOfxChangeUserEdited - the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resets
   - ::kOfxChangePluginEdited - the plug-in itself has changed the value of the object in some action
   - ::kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time

kOfxPropEffectInstance

A pointer to an effect instance.

This property is used to link an object to the effect. For example if the plug-in supplies an openGL overlay for an image effect, the interact instance will have one of these so that the plug-in can connect back to the effect the GUI links to.

kOfxPropHostOSHandle

A pointer to an operating system specific application handle.

Some plug-in vendor want raw OS specific handles back from the host so they can do interesting things with host OS APIs. Typically this is to control windowing properly on Microsoft Windows. This property returns the appropriate ‘root’ window handle on the current operating system. So on Windows this would be the hWnd of the application main window.

kOfxChangeUserEdited: String used as a value to kOfxPropChangeReason to indicate a user has changed something.

kOfxChangePluginEdited: String used as a value to kOfxPropChangeReason to indicate the plug-in itself has changed something.

kOfxChangeTime: String used as a value to kOfxPropChangeReason to a time varying object has changed due to a time change.

kOfxFlagInfiniteMax

Used to flag infinite rects. Set minimums to this to indicate infinite.

This is effectively INT_MAX.

kOfxFlagInfiniteMin

Used to flag infinite rects. Set minimums to this to indicate infinite.

This is effectively INT_MIN

kOfxBitDepthNone: String used to label unset bitdepths.

kOfxBitDepthByte: String used to label unsigned 8 bit integer samples.

kOfxBitDepthShort: String used to label unsigned 16 bit integer samples.

kOfxBitDepthHalf

String used to label half-float (16 bit floating point) samples.

Version: Added in Version 1.4. Was in ofxOpenGLRender.h before.

kOfxBitDepthFloat: String used to label signed 32 bit floating point samples.

kOfxStatOK: Status code indicating all was fine.

kOfxStatFailed: Status error code for a failed operation.

kOfxStatErrFatal

Status error code for a fatal error.

Only returned in the case where the plug-in or host cannot continue to function and needs to be restarted.

kOfxStatErrUnknown: Status error code for an operation on or request for an unknown object.

kOfxStatErrMissingHostFeature

Status error code returned by plug-ins when they are missing host functionality, either an API or some optional functionality (eg: custom params).

Plug-Ins returning this should post an appropriate error message stating what they are missing.

kOfxStatErrUnsupported: Status error code for an unsupported feature/operation.

kOfxStatErrExists: Status error code for an operation attempting to create something that exists.

kOfxStatErrFormat: Status error code for an incorrect format.

kOfxStatErrMemory: Status error code indicating that something failed due to memory shortage.

kOfxStatErrBadHandle: Status error code for an operation on a bad handle.

kOfxStatErrBadIndex: Status error code indicating that a given index was invalid or unavailable.

kOfxStatErrValue: Status error code indicating that something failed due an illegal value.

kOfxStatReplyYes: OfxStatus returned indicating a ‘yes’.

kOfxStatReplyNo: OfxStatus returned indicating a ‘no’.

kOfxStatReplyDefault: OfxStatus returned indicating that a default action should be performed.

Typedefs

typedef struct OfxPropertySetStruct *OfxPropertySetHandle: Blind data structure to manipulate sets of properties through.

typedef int OfxStatus: OFX status return type.

typedef struct OfxHost OfxHost

Generic host structure passed to OfxPlugin::setHost function.

This structure contains what is needed by a plug-in to bootstrap its connection to the host.

OfxStatus() OfxPluginEntryPoint (const char *action, const void *handle, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs)

Entry point for plug-ins.

action ASCII c string indicating which action to take
instance object to which action should be applied, this will need to be cast to the appropriate blind data type depending on the action
inData handle that contains action specific properties
outData handle where the plug-in should set various action specific properties

This is how the host generally communicates with a plug-in. Entry points are used to pass messages to various objects used within OFX. The main use is within the OfxPlugin struct.

The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins can perform several actions. For the list of actions consult OFX Actions.

typedef struct OfxPlugin OfxPlugin

The structure that defines a plug-in to a host.

This structure is the first element in any plug-in structure using the OFX plug-in architecture. By examining its members a host can determine the API that the plug-in implements, the version of that API, its name and version.

For details see Architecture.

typedef double OfxTime: How time is specified within the OFX API.

typedef struct OfxRangeI OfxRangeI: Defines one dimensional integer bounds.

typedef struct OfxRangeD OfxRangeD: Defines one dimensional double bounds.

typedef struct OfxPointI OfxPointI: Defines two dimensional integer point.

typedef struct OfxPointD OfxPointD: Defines two dimensional double point.

typedef struct OfxRectI OfxRectI

Defines two dimensional integer region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

typedef struct OfxRectD OfxRectD

Defines two dimensional double region.

Regions are x1 <= x < x2

Infinite regions are flagged by setting

Functions

OfxPlugin *OfxGetPlugin(int nth)

Returns the ‘nth’ plug-in implemented inside a binary.

Returns a pointer to the ‘nth’ plug-in implemented in the binary. A function of this type must be implemented in and exported from each plug-in binary.

int OfxGetNumberOfPlugins(void)

Defines the number of plug-ins implemented inside a binary.

A host calls this to determine how many plug-ins there are inside a binary it has loaded. A function of this type must be implemented in and exported from each plug-in binary.

OfxStatus OfxSetHost(const OfxHost *host)

First thing host should call.

This host call, added in 2020, is not specified in earlier implementation of the API. Therefore host must check if the plugin implemented it and not assume symbol exists. The order of calls is then: 1) OfxSetHost, 2) OfxGetNumberOfPlugins, 3) OfxGetPlugin The host pointer is only assumed valid until OfxGetPlugin where it might get reset. Plug-in can return kOfxStatFailed to indicate it has nothing to do here, it’s not for this Host and it should be skipped silently.

file ofxDialog.h

#include “ofxCore.h”

#include “ofxProperty.h”

This file contains an optional suite which should be used to popup a native OS dialog from a host parameter changed action.

When a host uses a fullscreen window and is running the OFX plugins in another thread it can lead to a lot of conflicts if that plugin will try to open its own window.

This suite will provide the functionality for a plugin to request running its dialog in the UI thread, and informing the host it will do this so it can take the appropriate actions needed. (Like lowering its priority etc..)

Defines

kOfxDialogSuite: The name of the Dialog suite, used to fetch from a host via OfxHost::fetchSuite.

kOfxActionDialog

Action called after a dialog has requested a ‘Dialog’ The arguments to the action are:

user_data Pointer which was provided when the plugin requested the Dialog

When the plugin receives this action it is safe to popup a dialog. It runs in the host’s UI thread, which may differ from the main OFX processing thread. Plugin should return from this action when all Dialog interactions are done. At that point the host will continue again. The host will not send any other messages asynchronous to this one.

Typedefs

typedef struct OfxDialogSuiteV1 OfxDialogSuiteV1

file ofxDrawSuite.h

#include “ofxCore.h”

#include “ofxPixels.h”

API for host- and GPU API-independent drawing.

Version: Added in OpenFX 1.5

Defines

kOfxDrawSuite: the string that names the DrawSuite, passed to OfxHost::fetchSuite

kOfxInteractPropDrawContext: The Draw Context handle.

Typedefs

typedef struct OfxDrawContext *OfxDrawContextHandle: Blind declaration of an OFX drawing context.

typedef enum OfxStandardColour OfxStandardColour: Defines valid values for OfxDrawSuiteV1::getColour.

typedef enum OfxDrawLineStipplePattern OfxDrawLineStipplePattern: Defines valid values for OfxDrawSuiteV1::setLineStipple.

typedef enum OfxDrawPrimitive OfxDrawPrimitive: Defines valid values for OfxDrawSuiteV1::draw.

typedef enum OfxDrawTextAlignment OfxDrawTextAlignment: Defines text alignment values for OfxDrawSuiteV1::drawText.

typedef struct OfxDrawSuiteV1 OfxDrawSuiteV1: OFX suite that allows an effect to draw to a host-defined display context. To use this, the plugin must use kOfxImageEffectPluginPropOverlayInteractV2.

Enums

enum OfxStandardColour

Defines valid values for OfxDrawSuiteV1::getColour.

Values:

enumerator kOfxStandardColourOverlayBackground

enumerator kOfxStandardColourOverlayActive

enumerator kOfxStandardColourOverlaySelected

enumerator kOfxStandardColourOverlayDeselected

enumerator kOfxStandardColourOverlayMarqueeFG

enumerator kOfxStandardColourOverlayMarqueeBG

enumerator kOfxStandardColourOverlayText

enum OfxDrawLineStipplePattern

Defines valid values for OfxDrawSuiteV1::setLineStipple.

Values:

enumerator kOfxDrawLineStipplePatternSolid

enumerator kOfxDrawLineStipplePatternDot

enumerator kOfxDrawLineStipplePatternDash

enumerator kOfxDrawLineStipplePatternAltDash

enumerator kOfxDrawLineStipplePatternDotDash

enum OfxDrawPrimitive

Defines valid values for OfxDrawSuiteV1::draw.

Values:

enumerator kOfxDrawPrimitiveLines

enumerator kOfxDrawPrimitiveLineStrip

enumerator kOfxDrawPrimitiveLineLoop

enumerator kOfxDrawPrimitiveRectangle

enumerator kOfxDrawPrimitivePolygon

enumerator kOfxDrawPrimitiveEllipse

enum OfxDrawTextAlignment

Defines text alignment values for OfxDrawSuiteV1::drawText.

Values:

enumerator kOfxDrawTextAlignmentLeft

enumerator kOfxDrawTextAlignmentRight

enumerator kOfxDrawTextAlignmentTop

enumerator kOfxDrawTextAlignmentBottom

enumerator kOfxDrawTextAlignmentBaseline

enumerator kOfxDrawTextAlignmentCenterH

enumerator kOfxDrawTextAlignmentCenterV

file ofxGPURender.h

#include “ofxImageEffect.h”

This file contains an optional suite for performing GPU-accelerated
rendering of OpenFX Image Effect Plug-ins.  For details see
\ref ofxGPURender.

It allows hosts and plug-ins to support OpenGL, OpenCL, CUDA, and Metal.
Additional GPU APIs, such a Vulkan, could use similar techniques.

StatusReturnValues

OfxStatus returns indicating that a OpenGL render error has occurred:

If a plug-in returns kOfxStatGLRenderFailed, the host should retry the render with OpenGL rendering disabled.
If a plug-in returns kOfxStatGLOutOfMemory, the host may choose to free resources on the GPU and retry the OpenGL render, rather than immediately falling back to CPU rendering.

kOfxStatGPUOutOfMemory: GPU render ran out of memory.

kOfxStatGLOutOfMemory: OpenGL render ran out of memory (same as kOfxStatGPUOutOfMemory)

kOfxStatGPURenderFailed: GPU render failed in a non-memory-related way.

kOfxStatGLRenderFailed: OpenGL render failed in a non-memory-related way (same as kOfxStatGPURenderFailed)

Defines

__OFXGPURENDER_H__

kOfxOpenGLRenderSuite: The name of the OpenGL render suite, used to fetch from a host via OfxHost::fetchSuite.

kOfxImageEffectPropOpenGLRenderSupported

Indicates whether a host or plug-in can support OpenGL accelerated rendering.

Valid Values -
- “false” - in which case the host or plug-in does not support OpenGL accelerated rendering
- ”true” - which means a host or plug-in can support OpenGL accelerated rendering, in the case of plug-ins this also means that it is capable of CPU based rendering in the absence of a GPU
- ”needed” - only for plug-ins, this means that an plug-in has to have OpenGL support, without which it cannot work.

V1.4: It is now expected from host reporting v1.4 that the plug-in can during instance change switch from true to false and false to true.

kOfxOpenGLPropPixelDepth

Indicates the bit depths supported by a plug-in during OpenGL renders.

This is analogous to kOfxImageEffectPropSupportedPixelDepths. When a plug-in sets this property, the host will try to provide buffers/textures in one of the supported formats. Additionally, the target buffers where the plug-in renders to will be set to one of the supported formats.

Unlike kOfxImageEffectPropSupportedPixelDepths, this property is optional. Shader-based effects might not really care about any format specifics when using OpenGL textures, so they can leave this unset and allow the host the decide the format.

Valid Values -
- kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)
- kOfxBitDepthByte
- kOfxBitDepthShort
- kOfxBitDepthHalf
- kOfxBitDepthFloat

kOfxImageEffectPropOpenGLEnabled

Indicates that a plug-in SHOULD use OpenGL acceleration in the current action.

When a plug-in and host have established they can both use OpenGL renders then when this property has been set the host expects the plug-in to render its result into the buffer it has setup before calling the render. The plug-in can then also safely use the ‘OfxImageEffectOpenGLRenderSuite’

Valid Values
- 0 indicates that the plug-in cannot use the OpenGL suite
- 1 indicates that the plug-in should render into the texture, and may use the OpenGL suite functions.

v1.4: kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture

Note

Once this property is set, the host and plug-in have agreed to use OpenGL, so the effect SHOULD access all its images through the OpenGL suite.

kOfxImageEffectPropOpenGLTextureIndex

Indicates the texture index of an image turned into an OpenGL texture by the host.

This value should be cast to a GLuint and used as the texture index when performing OpenGL texture operations.

The property set of the following actions should contain this property:

kOfxImageEffectPropOpenGLTextureTarget

Indicates the texture target enumerator of an image turned into an OpenGL texture by the host.

This value should be cast to a GLenum and used as the texture target when performing OpenGL texture operations.

The property set of the following actions should contain this property:

kOfxImageEffectPropCPURenderSupported

Indicates whether a host or plug-in can (or more importantly cannot) support CPU rendering.

Valid Values -
- “false” - in which case the host or plug-in does not support CPU rendering
- ”true” - which means a host or plug-in can support CPU rendering

Version: added in version 1.5.1.

kOfxActionOpenGLContextAttached

Action called when an effect has just been attached to an OpenGL context.

The purpose of this action is to allow a plug-in to set up any data it may need to do OpenGL rendering in an instance. For example…

allocate a lookup table on a GPU,
create an OpenCL or CUDA context that is bound to the host’s OpenGL context so it can share buffers.

The plug-in will be responsible for deallocating any such shared resource in the kOfxActionOpenGLContextDetached action.

A host cannot call kOfxActionOpenGLContextAttached on the same instance without an intervening kOfxActionOpenGLContextDetached. A host can have a plug-in swap OpenGL contexts by issuing a attach/detach for the first context then another attach for the next context.

The arguments to the action are…

handle handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs is redundant and set to NULL
outArgs is redundant and set to NULL

A plug-in can return…

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored, but all was well anyway
kOfxStatErrMemory, in which case this may be called again after a memory purge
kOfxStatFailed, something went wrong, but no error code appropriate, the plug-in should to post a message if possible and the host should not attempt to run the plug-in in OpenGL render mode.

kOfxActionOpenGLContextDetached

Action called when an effect is about to be detached from an OpenGL context.

The purpose of this action is to allow a plug-in to deallocate any resource allocated in kOfxActionOpenGLContextAttached just before the host decouples a plug-in from an OpenGL context. The host must call this with the same OpenGL context active as it called with the corresponding kOfxActionOpenGLContextAttached.

The arguments to the action are…

handle handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs is redundant and set to NULL
outArgs is redundant and set to NULL

A plug-in can return…

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored, but all was well anyway
kOfxStatErrMemory, in which case this may be called again after a memory purge
kOfxStatFailed, something went wrong, but no error code appropriate, the plug-in should to post a message if possible and the host should not attempt to run the plug-in in OpenGL render mode.

kOfxImageEffectPropCudaRenderSupported

Indicates whether a host or plug-in can support CUDA render.

Valid Values -
- “false” - the host or plug-in does not support CUDA render
- ”true” - the host or plug-in can support CUDA render

kOfxImageEffectPropCudaEnabled

Indicates that a plug-in SHOULD use CUDA render in the current action.

If a plug-in and host have both set kOfxImageEffectPropCudaRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as CUDA memory pointers.

Valid Values
- 0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
- 1 indicates that the kOfxImagePropData of each image of each clip is a CUDA memory pointer.

kOfxImageEffectPropCudaStreamSupported

Indicates whether a host or plug-in can support CUDA streams.

Valid Values -
- “false” - in which case the host or plug-in does not support CUDA streams
- ”true” - which means a host or plug-in can support CUDA streams

kOfxImageEffectPropCudaStream

The CUDA stream to be used for rendering.

This property will only be set if the host and plug-in both support CUDA streams.

If set:

this property contains a pointer to the stream of CUDA render (cudaStream_t). In order to use it, reinterpret_cast<cudaStream_t>(pointer) is needed.
the plug-in SHOULD ensure that its render action enqueues any asynchronous CUDA operations onto the supplied queue.
the plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action, and SHOULD NOT call cudaDeviceSynchronize() at any time.

If not set:

the plug-in SHOULD ensure that any asynchronous operations it enqueues have completed before returning from the render action.

kOfxImageEffectPropMetalRenderSupported

Indicates whether a host or plug-in can support Metal render.

Valid Values -
- “false” - the host or plug-in does not support Metal render
- ”true” - the host or plug-in can support Metal render

kOfxImageEffectPropMetalEnabled

Indicates that a plug-in SHOULD use Metal render in the current action.

If a plug-in and host have both set kOfxImageEffectPropMetalRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as Metal buffers.

Valid Values
- 0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
- 1 indicates that the kOfxImagePropData of each image of each clip is a Metal id<MTLBuffer>.

kOfxImageEffectPropMetalCommandQueue

The command queue of Metal render.

This property contains a pointer to the command queue to be used for Metal rendering (id<MTLCommandQueue>). In order to use it, reinterpret_cast<id<MTLCommandQueue>>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous Metal operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

kOfxImageEffectPropOpenCLRenderSupported

Indicates whether a host or plug-in can support OpenCL Buffers render.

Valid Values -
- “false” - the host or plug-in does not support OpenCL Buffers render
- ”true” - the host or plug-in can support OpenCL Buffers render

kOfxImageEffectPropOpenCLSupported

Indicates whether a host or plug-in can support OpenCL Images render.

Valid Values -
- “false” - in which case the host or plug-in does not support OpenCL Images render
- ”true” - which means a host or plug-in can support OpenCL Images render

kOfxImageEffectPropOpenCLEnabled

Indicates that a plug-in SHOULD use OpenCL render in the current action.

If a plug-in and host have both set kOfxImageEffectPropOpenCLRenderSupported=”true” or have both set kOfxImageEffectPropOpenCLSupported=”true” then the host MAY set this property to indicate that it is passing images as OpenCL Buffers or Images.

When rendering using OpenCL Buffers, the cl_mem of the buffers are retrieved using kOfxImagePropData. When rendering using OpenCL Images, the cl_mem of the images are retrieved using kOfxImageEffectPropOpenCLImage. If both kOfxImageEffectPropOpenCLSupported (Buffers) and kOfxImageEffectPropOpenCLRenderSupported (Images) are enabled by the plug-in, it should use kOfxImageEffectPropOpenCLImage to determine which is being used by the host.

Valid Values
- 0 indicates that a plug-in SHOULD use OpenCL render in the render action
- 1 indicates that a plug-in SHOULD NOT use OpenCL render in the render action

kOfxImageEffectPropOpenCLCommandQueue

Indicates the OpenCL command queue that should be used for rendering.

This property contains a pointer to the command queue to be used for OpenCL rendering (cl_command_queue). In order to use it, reinterpret_cast<cl_command_queue>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous OpenCL operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

kOfxImageEffectPropOpenCLImage

Indicates the image handle of an image supplied as an OpenCL Image by the host.

This value should be cast to a cl_mem and used as the image handle when performing OpenCL Images operations. The property should be used (not kOfxImagePropData) when rendering with OpenCL Images (kOfxImageEffectPropOpenCLSupported), and should be used to determine whether Images or Buffers should be used if a plug-in supports both kOfxImageEffectPropOpenCLSupported and kOfxImageEffectPropOpenCLRenderSupported. Note: the kOfxImagePropRowBytes property is not required to be set by the host, since OpenCL Images do not have the concept of row bytes.

kOfxOpenCLProgramSuite

Typedefs

typedef struct OfxImageEffectOpenGLRenderSuiteV1 OfxImageEffectOpenGLRenderSuiteV1: OFX suite that provides image to texture conversion for OpenGL processing.

typedef struct OfxOpenCLProgramSuiteV1 OfxOpenCLProgramSuiteV1

OFX suite that allows a plug-in to get OpenCL programs compiled.

This is an optional suite the host can provide for building OpenCL programs for the plug-in, as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also cache program binaries for performance (however, if the source of the program or the OpenCL environment changes, the host must recompile so some mechanism such as hashing must be used).

file ofxImageEffect.h

#include “ofxCore.h”

#include “ofxParam.h”

#include “ofxInteract.h”

#include “ofxMessage.h”

#include “ofxMemory.h”

#include “ofxMultiThread.h”

Defines

_ofxImageEffect_h_

kOfxImageEffectPluginApi

String used to label OFX Image Effect Plug-ins.

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

kOfxImageEffectPluginApiVersion: The current version of the Image Effect API.

kOfxImageComponentNone: String to label something with unset components.

kOfxImageComponentRGBA: String to label images with RGBA components.

kOfxImageComponentRGB: String to label images with RGB components.

kOfxImageComponentAlpha: String to label images with only Alpha components.

kOfxImageEffectContextGenerator: Use to define the generator image effect context. See kOfxImageEffectPropContext.

kOfxImageEffectContextFilter: Use to define the filter effect image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextTransition: Use to define the transition image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextPaint: Use to define the paint image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextGeneral: Use to define the general image effect context See kOfxImageEffectPropContext.

kOfxImageEffectContextRetimer: Use to define the retimer effect context See kOfxImageEffectPropContext.

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

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

kOfxTypeImageEffectInstance: Used as a value for kOfxPropType on image effect instance handles

kOfxTypeClip: Used as a value for kOfxPropType on image effect clips.

kOfxTypeImage: Used as a value for kOfxPropType on image effect images.

kOfxImageEffectActionGetRegionOfDefinition

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

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

If the effect does not handle this action, the host should use the default RoD instead, which depends on the context. This is…

generator context - defaults to the project window,
filter and paint contexts - defaults to the RoD of the ‘Source’ input clip at the given time,
transition context - defaults to the union of the RoDs of the ‘SourceFrom’ and ‘SourceTo’ input clips at the given time,
general context - defaults to the union of the RoDs of all the non optional input clips and the ‘Source’ input clip (if it exists and it is connected) at the given time, if none exist, then it is the project window
retimer context - defaults to the union of the RoD of the ‘Source’ input clip at the frame directly preceding the value of the ‘SourceTime’ double parameter and the frame directly after it

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropTime the effect time for which a region of definition is being requested
- kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this action
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – has the following property which the plug-in may set:
- kOfxImageEffectPropRegionOfDefinition the calculated region of definition, initially set by the host to the default RoD (see below), in Canonical Coordinates.

Returns:

kOfxStatOK the action was trapped and the RoD was set in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the default values
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionGetRegionsOfInterest

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

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropTime the effect time for which a region of definition is being requested
- kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this action
- kOfxImageEffectPropRegionOfInterest the region to be rendered in the output image, in Canonical Coordinates.
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
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 postpended, for example OfxImageClipPropRoI_Source. These are initialised to the default RoI.

Returns:

kOfxStatOK, the action was trapped and at least one RoI was set in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the default values
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionGetTimeDomain

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

The default is:

the union of all the frame ranges of the non optional input clips,
infinite if there are no non optional input clips.

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – is redundant and is null
outArgs – has the following property
- kOfxImageEffectPropFrameRange the frame range an effect can produce images for

Pre:

kOfxActionCreateInstance has been called on the instance
the effect instance has been created in the general effect context

Returns:

kOfxStatOK, the action was trapped and the kOfxImageEffectPropFrameRange was set in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the default value
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionGetFramesNeeded

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

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

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

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

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

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

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

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following property
- kOfxPropTime the effect time for which we need to calculate the frames needed on input
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – has a set of properties, one for each input clip, named OfxImageClipPropFrameRange_ with the name of the clip post-pended. For example OfxImageClipPropFrameRange_Source. All these properties are multi-dimensional doubles, with the dimension is a multiple of two. Each pair of values indicates a continuous range of frames that is needed on the given input. They are all initialised to the default value.

Returns:

kOfxStatOK, the action was trapped and at least one frame range in the outArgs property set
kOfxStatReplyDefault, the action was not trapped and the host should use the default values
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionGetClipPreferences

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

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – is redundant and is set to NULL
outArgs – has the following properties which the plugin can set
- a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropComponents_ post pended with the clip’s name. This must be set to one of the component types which the host supports and the effect stated it can accept on that input
- a set of char * X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropDepth_ post pended with the clip’s name. This must be set to one of the pixel depths both the host and plugin supports
- a set of char * X 1 properties, one for each of the input clips currently attached, labelled with OfxImageClipPropPreferredColourspaces_ post pended with the clip’s name. This must be set according to the requirements of the colour management style in use.
- a set of double X 1 properties, one for each of the input clips currently attached and the output clip, labelled with OfxImageClipPropPAR_ post pended with the clip’s name. This is the pixel aspect ratio of the input and output clips. This must be set to a positive non zero double value,
- kOfxImageEffectPropFrameRate the frame rate of the output clip, this must be set to a positive non zero double value
- kOfxImageClipPropFieldOrder the fielding of the output clip
- kOfxImageEffectPropPreMultiplication the premultiplication of the output clip
- kOfxImageClipPropContinuousSamples whether the output clip can produce different images at non-frame intervals, defaults to false,
- kOfxImageEffectFrameVarying whether the output clip can produces different images at different times, even if all parameters and inputs are constant, defaults to false.

Returns:

kOfxStatOK, the action was trapped and at least one of the properties in the outArgs was changed from its default value
kOfxStatReplyDefault, the action was not trapped and the host should use the default values
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionIsIdentity

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

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

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropTime the time at which to test for identity
- kOfxImageEffectPropFieldToRender the field to test for identity
- kOfxImageEffectPropRenderWindow the window (in \ref PixelCoordinates) to test for identity under
- kOfxImageEffectPropRenderScale the scale factor being applied to the images being rendered
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – has the following properties which the plugin can set
- kOfxPropName this to the name of the clip that should be used if the effect is an identity transform, defaults to the empty string
- kOfxPropTime the time to use from the indicated source clip as an identity image (allowing time slips to happen), defaults to the value in kOfxPropTime in inArgs

Returns:

kOfxStatOK, the action was trapped and the effect should not have its render action called, the values in outArgs indicate what frame from which clip to use instead
kOfxStatReplyDefault, the action was not trapped and the host should call the render action
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionRender

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

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxPropTime the time at which to render
- kOfxImageEffectPropFieldToRender the field to render
- kOfxImageEffectPropRenderWindow the window (in \ref PixelCoordinates) to render
- kOfxImageEffectPropRenderScale the scale factor being applied to the images being rendered
- kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance
- kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session
- kOfxImageEffectPropRenderQualityDraft if the render should be done in draft mode (e.g. for faster scrubbing)
- kOfxImageEffectPropNoSpatialAwareness if the plugin must render without spatial awareness (e.g. for LUT generation)
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – is redundant and should be set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance
kOfxImageEffectActionBeginSequenceRender has been called on the instance

Post:

kOfxImageEffectActionEndSequenceRender action will be called on the instance

Returns:

kOfxStatOK, the effect rendered happily
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectActionBeginSequenceRender

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be rendered
- kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders)
- kOfxPropIsInteractive is this a single frame render due to user interaction in a GUI, or a proper full sequence render.
- kOfxImageEffectPropRenderScale the scale factor to apply to images for this call
- kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance
- kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session
- kOfxImageEffectPropThumbnailRender (optional) if the host considers this render a “thumbnail”
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance

Post:

kOfxImageEffectActionRender action will be called at least once on the instance
kOfxImageEffectActionEndSequenceRender action will be called on the instance

Returns:

kOfxStatOK, the action was trapped and handled cleanly by the effect,
kOfxStatReplyDefault, the action was not trapped, but all is well anyway,
kOfxStatErrMemory, in which case the action may be called again after a memory purge,
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message,
kOfxStatErrFatal

kOfxImageEffectActionEndSequenceRender

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

Parameters:

handle – handle to the instance, cast to an OfxImageEffectHandle
inArgs – has the following properties
- kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be rendered
- kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders),
- kOfxPropIsInteractive is this a single frame render due to user interaction in a GUI, or a proper full sequence render.
- kOfxImageEffectPropRenderScale the scale factor to apply to images for this call
- kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance
- kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance
kOfxImageEffectActionEndSequenceRender action was called on the instance
kOfxImageEffectActionRender action was called at least once on the instance

Returns:

kOfxStatOK, the action was trapped and handled cleanly by the effect,
kOfxStatReplyDefault, the action was not trapped, but all is well anyway,
kOfxStatErrMemory, in which case the action may be called again after a memory purge,
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message,
kOfxStatErrFatal

kOfxImageEffectActionDescribeInContext

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

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

This action must be trapped, it is not optional.

Parameters:

handle – handle to the context descriptor, cast to an OfxImageEffectHandle this may or may not be the same as passed to kOfxActionDescribe
inArgs – has the following property:
- kOfxImageEffectPropContext the context being described
outArgs – is redundant and is set to NULL

Pre:

kOfxActionDescribe has been called on the descriptor handle,
kOfxActionCreateInstance has not been called

Returns:

kOfxStatOK, the action was trapped and all was well
kOfxStatErrMissingHostFeature, in which the context will be ignored by the host, the plugin may post a message
kOfxStatErrMemory, in which case the action may be called again after a memory purge
kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
kOfxStatErrFatal

kOfxImageEffectPropSupportedContexts

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

Valid Values - This must be one of

kOfxImageEffectPropPluginHandle

The plugin handle passed to the initial ‘describe’ action.

This value will be the same for all instances of a plugin.

kOfxImageEffectHostPropIsBackground

Indicates if a host is a background render.

Valid Values - This must be one of
- 0 if the host is a foreground host, it may open the effect in an interactive session (or not)
- 1 if the host is a background ‘processing only’ host, and the effect will never be opened in an interactive session.

kOfxImageEffectPluginPropSingleInstance

Indicates whether only one instance of a plugin can exist at the same time.

Some plugins, for whatever reason, may only be able to have a single instance in existence at any one time. This plugin property is used to indicate that.

Valid Values - This must be one of
- 0 - which means multiple instances can exist simultaneously,
- 1 - which means only one instance can exist at any one time.

kOfxImageEffectPluginRenderThreadSafety

Indicates how many simultaneous renders the plugin can deal with.

Valid Values - This must be one of
- kOfxImageEffectRenderUnsafe - indicating that only a single ‘render’ call can be made at any time among all instances,
- kOfxImageEffectRenderInstanceSafe - indicating that any instance can have a single ‘render’ call at any one time,
- kOfxImageEffectRenderFullySafe - indicating that any instance of a plugin can have multiple renders running simultaneously

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

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

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

kOfxImageEffectPluginPropHostFrameThreading

Indicates whether a plugin lets the host perform per frame SMP threading.

Valid Values - This must be one of
- 0 - which means that the plugin will perform any per frame SMP threading
- 1 - which means the host can call an instance’s render function simultaneously at the same frame, but with different windows to render.

kOfxImageEffectPropSupportsMultipleClipDepths

Indicates whether a host or plugin can support clips of differing component depths going into/out of an effect.

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.

Valid Values - This must be one of
- 0 - in which case the host or plugin does not support clips of multiple pixel depths,
- 1 - which means a host or plugin is able to to deal with clips of multiple pixel depths,

kOfxImageEffectPropSupportsMultipleClipPARs

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.

Valid Values - This must be one of
- 0 - in which case the host or plugin does not support clips of multiple pixel aspect ratios
- 1 - which means a host or plugin is able to to deal with clips of multiple pixel aspect ratios

kOfxImageEffectPropClipPreferencesSlaveParam

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

Valid Values - the name of any described parameter

kOfxImageEffectPropSetableFrameRate

Indicates whether the host will let a plugin set the frame rate of the output clip.

See ImageEffectClipPreferences.

If a clip can be continuously sampled, the frame rate will be set to 0.

Valid Values - This must be one of
- 0 - in which case the plugin may not change the frame rate of the output clip,
- 1 - which means a plugin is able to change the output clip’s frame rate in the kOfxImageEffectActionGetClipPreferences action.

kOfxImageEffectPropSetableFielding

Indicates whether the host will let a plugin set the fielding of the output clip.

See ImageEffectClipPreferences.

Valid Values - This must be one of
- 0 - in which case the plugin may not change the fielding of the output clip,
- 1 - which means a plugin is able to change the output clip’s fielding in the kOfxImageEffectActionGetClipPreferences action.

kOfxImageEffectInstancePropSequentialRender

Indicates whether a plugin needs sequential rendering, and a host support it.

Some effects have temporal dependencies, some information from from the rendering of frame N-1 is needed to render frame N correctly. This property is set by an effect to indicate such a situation. Also, some effects are more efficient if they run sequentially, but can still render correct images even if they do not, eg: a complex particle system.

During an interactive session a host may attempt to render a frame out of sequence (for example when the user scrubs the current time), and the effect needs to deal with such a situation as best it can to provide feedback to the user.

However if a host caches output, any frame frame generated in random temporal order needs to be considered invalid and needs to be re-rendered when the host finally performs a first to last render of the output sequence.

In all cases, a host will set the kOfxImageEffectPropSequentialRenderStatus flag to indicate its sequential render status.

Valid Values -
- 0 - for a plugin, indicates that a plugin does not need to be sequentially rendered to be correct, for a host, indicates that it cannot ever guarantee sequential rendering,
- 1 - for a plugin, indicates that it needs to be sequentially rendered to be correct, for a host, indicates that it can always support sequential rendering of plugins that are sequentially rendered,
- 2 - for a plugin, indicates that it is best to render sequentially, but will still produce correct results if not, for a host, indicates that it can sometimes render sequentially, and will have set kOfxImageEffectPropSequentialRenderStatus on the relevant actions

kOfxImageEffectPropSequentialRenderStatus

Property on all the render action that indicate the current sequential render status of a host.

This property is set to indicate whether the effect is currently being rendered in frame order on a single effect instance. See kOfxImageEffectInstancePropSequentialRender for more details on sequential rendering.

Valid Values -
- 0 - the host is not currently sequentially rendering,
- 1 - the host is currentely rendering in a way so that it guarantees sequential rendering.

kOfxHostNativeOriginBottomLeft

kOfxHostNativeOriginTopLeft

kOfxHostNativeOriginCenter

kOfxImageEffectHostPropNativeOrigin

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

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

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

kOfxImageEffectPropInteractiveRenderStatus

Property that indicates if a plugin is being rendered in response to user interaction.

This property is set to 1 on all render calls that have been triggered because a user is actively modifying an effect (or up stream effect) in an interactive session. This typically means that the effect is not being rendered as a part of a sequence, but as a single frame.

Valid Values -
- 0 - the host is rendering the instance due to some reason other than an interactive tweak on a UI,
- 1 - the instance is being rendered because a user is modifying parameters in an interactive session.

kOfxImageEffectPluginPropGrouping

Indicates the effect group for this plugin.

This is purely a user interface hint for the host so it can group related effects on any menus it may have.

kOfxImageEffectPluginPropObsolete

Indicates whether the plugin should be hidden in the host’s OFX browser UI.

If set to 1, this indicates the plugin has been made obsolete by a different version of the same plugin contained in the same bundle (i.e. same pluginIdentifier but different pluginVersionMajor and/or pluginVersionMinor). At least one version of the plugin in the bundle (typically the newest) must have this property omitted or set to 0.

Valid Values -
- 0 - the host will show the plugin in its OFX browser UI,
- 1 - the host will not show the plugin in its OFX browser UI.

kOfxImageEffectPropSupportsOverlays

Indicates whether a host support image effect ImageEffectOverlays.

Valid Values - This must be one of
- 0 - the host won’t allow a plugin to draw a GUI over the output image,
- 1 - the host will allow a plugin to draw a GUI over the output image.

kOfxImageEffectPluginPropOverlayInteractV1

Sets the entry for an effect’s overlay interaction.

The entry point pointed to must be one that handles custom interaction actions.

Valid Values - must point to an OfxPluginEntryPoint

kOfxImageEffectPluginPropOverlayInteractV2

Sets the entry for an effect’s overlay interaction. Unlike kOfxImageEffectPluginPropOverlayInteractV1, the overlay interact in the plug-in is expected to implement the kOfxInteractActionDraw using the OfxDrawSuiteV1.

The entry point pointed to must be one that handles custom interaction actions.

Valid Values - must point to an OfxPluginEntryPoint

kOfxImageEffectPropSupportsMultiResolution

Indicates whether a plugin or host support multiple resolution images.

Multiple resolution images mean…

input and output images can be of any size
input and output images can be offset from the origin

Valid Values - This must be one of

0 - the plugin or host does not support multiple resolutions
1 - the plugin or host does support multiple resolutions

kOfxImageEffectPropSupportsTiles

Indicates whether a clip, plugin or host supports tiled images.

Tiled images mean that input or output images can contain pixel data that is only a subset of their full RoD.

If a clip or plugin does not support tiled images, then the host should supply full RoD images to the effect whenever it fetches one.

V1.4: It is now possible (defined) to change OfxImageEffectPropSupportsTiles in Instance Changed

kOfxImageEffectPropTemporalClipAccess

Indicates support for random temporal access to images in a clip.

On a host, it indicates whether the host supports temporal access to images.

On a plugin, indicates if the plugin needs temporal access to images.

On a clip, it indicates that the clip needs temporal access to images.

kOfxImageEffectPropContext

Indicates the context a plugin instance has been created for.

Valid Values - This must be one of

kOfxImageEffectPropPixelDepth

Indicates the type of each component in a clip or image (after any mapping)

Note that for a clip, this is the value set by the clip preferences action, not the raw ‘actual’ value of the clip.

Valid Values - This must be one of
- kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)
- kOfxBitDepthByte
- kOfxBitDepthShort
- kOfxBitDepthHalf
- kOfxBitDepthFloat

kOfxImageEffectPropComponents

Indicates the current component type in a clip or image (after any mapping)

Note that for a clip, this is the value set by the clip preferences action, not the raw ‘actual’ value of the clip.

Valid Values - This must be one of
- kOfxImageComponentNone (implying a clip is unconnected, not valid for an image)
- kOfxImageComponentRGBA
- kOfxImageComponentRGB
- kOfxImageComponentAlpha

kOfxImagePropUniqueIdentifier

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.

kOfxImageClipPropContinuousSamples

Clip and action argument property which indicates that the clip can be sampled continuously.

If this is set to true, then the frame rate of a clip is effectively infinite, so to stop arithmetic errors the frame rate should then be set to 0.

Valid Values - This must be one of…
- 0 if the images can only be sampled at discrete times (eg: the clip is a sequence of frames),
- 1 if the images can only be sampled continuously (eg: the clip is in fact an animating roto spline and can be rendered at any time).

kOfxImageClipPropUnmappedPixelDepth

Indicates the type of each component in a clip before any mapping by clip preferences.

This is the actual value of the component depth, before any mapping by clip preferences.

Valid Values - This must be one of
- kOfxBitDepthNone (implying a clip is unconnected image)
- kOfxBitDepthByte
- kOfxBitDepthShort
- kOfxBitDepthHalf
- kOfxBitDepthFloat

kOfxImageClipPropUnmappedComponents

Indicates the current ‘raw’ component type on a clip before any mapping by clip preferences.

Valid Values - This must be one of
- kOfxImageComponentNone (implying a clip is unconnected)
- kOfxImageComponentRGBA
- kOfxImageComponentRGB
- kOfxImageComponentAlpha

kOfxImageEffectPropPreMultiplication

Indicates the premultiplication state of a clip or image.

See the documentation on clip preferences for more details on how this is used with the kOfxImageEffectActionGetClipPreferences action.

Valid Values - This must be one of
- kOfxImageOpaque - the image is opaque and so has no premultiplication state
- kOfxImagePreMultiplied - the image is premultiplied by its alpha
- kOfxImageUnPreMultiplied - the image is unpremultiplied

kOfxImageOpaque: Used to flag the alpha of an image as opaque

kOfxImagePreMultiplied: Used to flag an image as premultiplied

kOfxImageUnPreMultiplied: Used to flag an image as unpremultiplied

kOfxImageEffectPropSupportedPixelDepths

Indicates the bit depths support by a plug-in or host.

The default for a plugin is to have none set, the plugin must define at least one in its describe action.

Valid Values - This must be one of
- kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)
- kOfxBitDepthByte
- kOfxBitDepthShort
- kOfxBitDepthHalf
- kOfxBitDepthFloat

kOfxImageEffectPropSupportedComponents

Indicates the components supported by a clip or host,.

This list of strings indicate what component types are supported by a host or are expected as input to a clip.

The default for a clip descriptor is to have none set, the plugin must define at least one in its define function

Valid Values - This must be one of
- kOfxImageComponentNone (implying a clip is unconnected)
- kOfxImageComponentRGBA
- kOfxImageComponentRGB
- kOfxImageComponentAlpha

kOfxImageClipPropOptional: Indicates if a clip is optional.

kOfxImageClipPropIsMask

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.

kOfxImagePropPixelAspectRatio: The pixel aspect ratio of a clip or image.

kOfxImageEffectPropFrameRate

The frame rate of a clip or instance’s project.

For an input clip this is the frame rate of the clip.

For an output clip, the frame rate mapped via pixel preferences.

For an instance, this is the frame rate of the project the effect is in.

For the outargs property in the kOfxImageEffectActionGetClipPreferences action, it is used to change the frame rate of the output clip.

kOfxImageEffectPropUnmappedFrameRate

Indicates the original unmapped frame rate (frames/second) of a clip.

If a plugin changes the output frame rate in the pixel preferences action, this property allows a plugin to get to the original value.

kOfxImageEffectPropFrameStep

The frame step used for a sequence of renders.

Valid Values - can be any positive value, but typically
- 1 for frame based material
- 0.5 for field based material

kOfxImageEffectPropFrameRange

The frame range over which a clip has images.

Dimension 0 is the first frame for which the clip can produce valid data.

Dimension 1 is the last frame for which the clip can produce valid data.

kOfxImageEffectPropUnmappedFrameRange

The unmaped frame range over which an output clip has images.

Dimension 0 is the first frame for which the clip can produce valid data.

Dimension 1 is the last frame for which the clip can produce valid data.

If a plugin changes the output frame rate in the pixel preferences action, it will affect the frame range of the output clip, this property allows a plugin to get to the original value.

kOfxImageClipPropConnected

Says whether the clip is actually connected at the moment.

An instance may have a clip may not be connected to an object that can produce image data. Use this to find out.

Any clip that is not optional will always be connected during a render action. However, during interface actions, even non optional clips may be unconnected.

kOfxImageEffectFrameVarying

Indicates whether an effect will generate different images from frame to frame.

This property indicates whether a plugin will generate a different image from frame to frame, even if no parameters or input image changes. For example a generator that creates random noise pixel at each frame.

kOfxImageEffectPropRenderScale

The proxy render scale currently being applied.

This should be applied to any spatial parameters to position them correctly. Not that the ‘x’ value does not include any pixel aspect ratios.

kOfxImageEffectPropRenderQualityDraft

Indicates whether an effect can take quality shortcuts to improve speed.

This property indicates that the host provides the plug-in the option to render in Draft/Preview mode. This is useful for applications that must support fast scrubbing. These allow a plug-in to take short-cuts for improved performance when the situation allows and it makes sense, for example to generate thumbnails with effects applied. For example switch to a cheaper interpolation type or rendering mode. A plugin should expect frames rendered in this manner that will not be stuck in host cache unless the cache is only used in the same draft situations. If an host does not support that property a value of 0 is assumed. Also note that some hosts do implement kOfxImageEffectPropRenderScale - these two properties can be used independently.

kOfxImageEffectPropNoSpatialAwareness

Indicates that the plugin can render without spatial awareness, either inherently or by disabling certain parameters at render time.

If the plugin descriptor has this property set to “true”, the plugin is expected to disable spatial effects when the host sets this property to “true” in the arguments passed to kOfxImageEffectActionBeginSequenceRender and kOfxImageEffectActionRender.

Valid Values - This must be one of
- ”false” - the plugin cannot render without spatial awareness and the host should bypass it for renders that require no spatial awareness.
- ”true” - the plugin can render without spatial awareness. The host will indicate this type of render by setting kOfxImageEffectPropNoSpatialAwareness to “true” in the arguments passed to kOfxImageEffectActionBeginSequenceRender and kOfxImageEffectActionRender.

Version: added in version 1.5.1.

kOfxImageEffectPropThumbnailRender

Indicates whether the render is what the host considers a “thumbnail” render.

This property indicates that the host considers the render to be a “thumbnail”, defined as a low-resolution image for use in the host’s user interface. A plugin could react to this property by

rendering a badge rather than a detailed effect unlikely to be visible in a thumbnail
turning itself off in kOfxImageEffectActionIsIdentity
disabling temporal inputs in kOfxImageEffectActionGetFramesNeeded
Version
added in version 1.5.1.
- Valid Values - This must be one of
  - ”false” - the host does not consider this render a thumbnail
  - ”true” - the host considers this render a thumbnail

kOfxImageEffectPropProjectExtent

The extent of the current project in canonical coordinates.

The extent is the size of the ‘output’ for the current project. See NormalisedCoordinateSystem for more information on the project extent.

The extent is in canonical coordinates and only returns the top right position, as the extent is always rooted at 0,0.

For example a PAL SD project would have an extent of 768, 576.

kOfxImageEffectPropProjectSize

The size of the current project in canonical coordinates.

The size of a project is a sub set of the kOfxImageEffectPropProjectExtent. For example a project may be a PAL SD project, but only be a letter-box within that. The project size is the size of this sub window.

The project size is in canonical coordinates.

See NormalisedCoordinateSystem for more information on the project extent.

kOfxImageEffectPropProjectOffset

The offset of the current project in canonical coordinates.

The offset is related to the kOfxImageEffectPropProjectSize and is the offset from the origin of the project ‘subwindow’.

For example for a PAL SD project that is in letterbox form, the project offset is the offset to the bottom left hand corner of the letter box.

The project offset is in canonical coordinates.

See NormalisedCoordinateSystem for more information on the project extent.

kOfxImageEffectPropProjectPixelAspectRatio: The pixel aspect ratio of the current project.

kOfxImageEffectInstancePropEffectDuration

The duration of the effect.

This contains the duration of the plug-in effect, in frames.

kOfxImageClipPropFieldOrder

Which spatial field occurs temporally first in a frame.

Valid Values - This must be one of
- kOfxImageFieldNone - the material is unfielded
- kOfxImageFieldLower - the material is fielded, with image rows 0,2,4…. occurring first in a frame
- kOfxImageFieldUpper - the material is fielded, with image rows line 1,3,5…. occurring first in a frame

kOfxImagePropData

The pixel data pointer of an image.

This property contains one of:

a pointer to memory that is the lower left hand corner of an image
a pointer to CUDA memory, if the Render action arguments includes kOfxImageEffectPropCudaEnabled=1
an id<MTLBuffer>, if the Render action arguments includes kOfxImageEffectPropMetalEnabled=1
a cl_mem, if the Render action arguments includes kOfxImageEffectPropOpenCLEnabled=1

See kOfxImageEffectPropCudaEnabled, kOfxImageEffectPropMetalEnabled and kOfxImageEffectPropOpenCLEnabled

kOfxImagePropBounds

The bounds of an image’s pixels.

The bounds, in PixelCoordinates, are of the addressable pixels in an image’s data pointer.

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

X values are x1 <= X < x2 Y values are y1 <= Y < y2

For less than full frame images, the pixel bounds will be contained by the kOfxImagePropRegionOfDefinition bounds.

kOfxImagePropRegionOfDefinition

The full region of definition of an image.

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 actual addressable pixels in an image, which may be less than its full region of definition.

kOfxImagePropRowBytes

The number of bytes in a row of an image.

For various alignment reasons, a row of pixels may need to be padded at the end with several bytes before the next row starts in memory.

This property indicates the number of bytes in a row of pixels. This will be at least sizeof(PIXEL) * (bounds.x2-bounds.x1). Where bounds is fetched from the kOfxImagePropBounds property.

Note that (for CPU images only, not CUDA/Metal/OpenCL Buffers, nor OpenGL textures accessed via the OpenGL Render Suite) row bytes can be negative, which allows hosts with a native top down row order to pass image into OFX without having to repack pixels. Row bytes is not supported for OpenCL Images.

kOfxImagePropField

Which fields are present in the image.

Valid Values - This must be one of
- kOfxImageFieldNone - the image is an unfielded frame
- kOfxImageFieldBoth - the image is fielded and contains both interlaced fields
- kOfxImageFieldLower - the image is fielded and contains a single field, being the lower field (rows 0,2,4…)
- kOfxImageFieldUpper - the image is fielded and contains a single field, being the upper field (rows 1,3,5…)

kOfxImageEffectPluginPropFieldRenderTwiceAlways

Controls how a plugin renders fielded footage.

Valid Values - This must be one of
- 0 - the plugin is to have its render function called twice, only if there is animation in any of its parameters
- 1 - the plugin is to have its render function called twice always

kOfxImageClipPropFieldExtraction

Controls how a plugin fetched fielded imagery from a clip.

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.

- Valid Values - This must be one of
   - kOfxImageFieldBoth    - fetch a full frame interlaced image
   - kOfxImageFieldSingle  - fetch a single field, making a half height image
   - kOfxImageFieldDoubled - fetch a single field, but doubling each line and so making a full height image

kOfxImageEffectPropFieldToRender

Indicates which field is being rendered.

Valid Values - this must be one of
- kOfxImageFieldNone - there are no fields to deal with, all images are full frame
- kOfxImageFieldBoth - the imagery is fielded and both scan lines should be rendered
- kOfxImageFieldLower - the lower field is being rendered (lines 0,2,4…)
- kOfxImageFieldUpper - the upper field is being rendered (lines 1,3,5…)

kOfxImageEffectPropRegionOfDefinition

Used to indicate the region of definition of a plug-in.

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

This will be in CanonicalCoordinates

kOfxImageEffectPropRegionOfInterest

The value of a region of interest.

A host passes this value into the region of interest action to specify the region it is interested in rendering.

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

This will be in CanonicalCoordinates.

kOfxImageEffectPropRenderWindow

The region to be rendered.

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

This will be in PixelCoordinates

kOfxImageFieldNone: String used to label imagery as having no fields

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

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

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

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

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

kOfxImageEffectOutputClipName: String that is the name of the standard OFX output clip.

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

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

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

kOfxImageEffectTransitionParamName: the name of the mandated ‘Transition’ param for the transition context

kOfxImageEffectRetimerParamName: the name of the mandated ‘SourceTime’ param for the retime context

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

kOfxStatErrImageFormat: Error code for incorrect image formats.

Typedefs

typedef struct OfxImageEffectStruct *OfxImageEffectHandle: Blind declaration of an OFX image effect.

typedef struct OfxImageClipStruct *OfxImageClipHandle: Blind declaration of an OFX image effect.

typedef struct OfxImageMemoryStruct *OfxImageMemoryHandle: Blind declaration for an handle to image memory returned by the image memory management routines.

typedef struct OfxImageEffectSuiteV1 OfxImageEffectSuiteV1

The OFX suite for image effects.

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

file ofxInteract.h

#include “ofxCore.h”

Contains the API for ofx plugin defined GUIs and interaction.

Defines

kOfxInteractSuite

kOfxInteractPropSlaveToParam

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

Valid Values - the name of any parameter associated with this interact.

kOfxInteractPropPixelScale: The size of a real screen pixel under the interact’s canonical projection.

kOfxInteractPropBackgroundColour

The background colour of the application behind an interact instance.

The components are in the order red, green then blue.

- Valid Values - from 0 to 1

kOfxInteractPropSuggestedColour

The suggested colour to draw a widget in an interact, typically for overlays.

Some applications allow the user to specify colours of any overlay via a colour picker, this property represents the value of that colour. Plugins are at liberty to use this or not when they draw an overlay.

If a host does not support such a colour, it should return kOfxStatReplyDefault

- Valid Values - greater than or equal to 0.0

kOfxInteractPropPenPosition

The position of the pen in an interact.

This value passes the position of the pen into an interact. This is in the interact’s canonical coordinates.

kOfxInteractPropPenViewportPosition

The position of the pen in an interact in viewport coordinates.

This value passes the position of the pen into an interact. This is in the interact’s openGL viewport coordinates, with 0,0 being at the bottom left.

kOfxInteractPropPenPressure

The pressure of the pen in an interact.

This is used to indicate the status of the ‘pen’ in an interact. If a pen has only two states (eg: a mouse button), these should map to 0.0 and 1.0.

Valid Values - from 0 (no pressure) to 1 (maximum pressure)

kOfxInteractPropBitDepth: Indicates the bits per component in the interact’s openGL frame buffer.

kOfxInteractPropHasAlpha

Indicates whether the interact’s frame buffer has an alpha component or not.

Valid Values - This must be one of
- 0 indicates no alpha component
- 1 indicates an alpha component

kOfxActionDescribeInteract

This action is the first action passed to an interact. It is where an interact defines how it behaves and the resources it needs to function. If not trapped, the default action is for the host to carry on as normal Note that the handle passed in acts as a descriptor for, rather than an instance of the interact.

Parameters:

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

Pre:

The plugin has been loaded and the effect described.

Returns:

kOfxStatOK the action was trapped and all was well
kOfxStatErrMemory in which case describe may be called again after a memory purge
kOfxStatFailed something was wrong, the host should ignore the interact
kOfxStatErrFatal

kOfxActionCreateInstanceInteract

This action 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.

Parameters:

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

Pre:

kOfxActionDescribe has been called on this interact

Post:

the instance pointer will be valid until the kOfxActionDestroyInstance action is passed to the plug-in with the same instance handle

Returns:

kOfxStatOK the action was trapped and all was well
kOfxStatReplyDefault the action was ignored, but all was well anyway
kOfxStatErrFatal
kOfxStatErrMemory in which case this may be called again after a memory purge
kOfxStatFailed in which case the host should ignore this interact

kOfxActionDestroyInstanceInteract

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.

Parameters:

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

Pre:

kOfxActionCreateInstance has been called on the handle,
the instance has not had any of its members destroyed yet

Post:

the instance pointer is no longer valid and any operation on it will be undefined

Returns:

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

kOfxStatOK the action was trapped and all was well
kOfxStatReplyDefault the action was ignored as the effect had nothing to do
kOfxStatErrFatal
kOfxStatFailed something went wrong, but no error code appropriate.

kOfxInteractActionDraw

This action is issued to an interact whenever the host needs the plugin to redraw the given interact.

The interact should either issue OpenGL calls (if the plugin is using OverlayInteractV1) to draw itself, or use DrawSuite calls (if using OverlayInteractV2).

If this is called via kOfxImageEffectPluginPropOverlayInteractV2, drawing MUST use DrawSuite.

If this is called via kOfxImageEffectPluginPropOverlayInteractV1, drawing SHOULD use OpenGL. Some existing plugins may use DrawSuite via kOfxImageEffectPluginPropOverlayInteractV1 if it’s supported by the host, but this is discouraged.

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.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
- kOfxPropEffectInstance a handle to the effect for which the interact has been,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle
the openGL context for this interact has been set
the projection matrix will correspond to the interact’s canonical view

Returns:

kOfxStatOK the action was trapped and all was well
kOfxStatReplyDefault the action was ignored
kOfxStatErrFatal
kOfxStatFailed something went wrong, the host should ignore this interact in future

kOfxInteractActionPenMotion

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.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
- kOfxPropEffectInstance a handle to the effect for which the interact has been,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
- kOfxInteractPropPenPosition position of the pen in,
- kOfxInteractPropPenViewportPosition position of the pen in,
- kOfxInteractPropPenPressure the pressure of the pen,
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK the host should not pass the pen motion to any other interactive object it may own that shares the same view.

Returns:

kOfxStatOK the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault the action was not trapped and the host can deal with it if it wants

kOfxInteractActionPenDown

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.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin,
- kOfxPropEffectInstance a handle to the effect for which the interact has been,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
- kOfxInteractPropPenPosition position of the pen in
- kOfxInteractPropPenViewportPosition position of the pen in
- kOfxInteractPropPenPressure the pressure of the pen
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.

Returns:

kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants

kOfxInteractActionPenUp

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.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin,
- kOfxPropEffectInstance a handle to the effect for which the interact has been,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
- kOfxInteractPropPenPosition position of the pen in
- kOfxInteractPropPenViewportPosition position of the pen in
- kOfxInteractPropPenPressure the pressure of the pen
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same view.

Returns:

kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants

kOfxInteractActionKeyDown

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.

Parameters:

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 occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.

Returns:

kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants

kOfxInteractActionKeyUp

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.

Parameters:

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 occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.

Returns:

kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants

kOfxInteractActionKeyRepeat

This action is issued when a key on the keyboard is repeated. No openGL calls should be issued by the plug-in during this action.

Parameters:

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 occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,
the current instance handle has had kOfxInteractActionGainFocus called on it

Post:

if the instance returns kOfxStatOK, the host should not pass the pen motion to any other interactive object it may own that shares the same focus.

Returns:

kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own
kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants

kOfxInteractActionGainFocus

This action is issued when an interact gains input focus. No openGL calls should be issued by the plug-in during this action.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
- kOfxPropEffectInstance a handle to the effect for which the interact is being used on,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels,
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,

Returns:

kOfxStatOK the action was trapped
kOfxStatReplyDefault the action was not trapped

kOfxInteractActionLoseFocus

This action is issued when an interact loses input focus. No openGL calls should be issued by the plug-in during this action.

Parameters:

handle – handle to an interact instance, cast to an OfxInteractHandle
inArgs – has the following properties on an image effect plugin
- kOfxPropEffectInstance a handle to the effect for which the interact is being used on,
- kOfxInteractPropPixelScale the scale factor to convert canonical pixels to screen pixels,
- kOfxInteractPropBackgroundColour the background colour of the application behind the current view
- kOfxPropTime the effect time at which changed occurred
- kOfxImageEffectPropRenderScale the render scale applied to any image fetched
outArgs – is redundant and is set to NULL

Pre:

kOfxActionCreateInstance has been called on the instance handle,

Returns:

kOfxStatOK the action was trapped
kOfxStatReplyDefault the action was not trapped

Typedefs

typedef struct OfxInteract *OfxInteractHandle: Blind declaration of an OFX interactive gui.

typedef struct OfxInteractSuiteV1 OfxInteractSuiteV1: OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces.

file ofxKeySyms.h

Defines

kOfxPropKeySym

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 equivalent.

Some keys, especially on non-english language systems, may have a UTF8 value, but 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.

Valid Values - one of any specified by #defines in the file ofxKeySyms.h.

kOfxPropKeyString

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 equivalent, in which case this is set to the empty string “”, and the associate kOfxPropKeySym is set to the equivalent raw key press.

Some keys, especially on non-english language systems, may have a UTF8 value, but 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.

Valid Values - a UTF8 string representing a single character, or the empty string.

kOfxKey_Unknown

kOfxKey_BackSpace

kOfxKey_Tab

kOfxKey_Linefeed

kOfxKey_Clear

kOfxKey_Return

kOfxKey_Pause

kOfxKey_Scroll_Lock

kOfxKey_Sys_Req

kOfxKey_Escape

kOfxKey_Delete

kOfxKey_Multi_key

kOfxKey_SingleCandidate

kOfxKey_MultipleCandidate

kOfxKey_PreviousCandidate

kOfxKey_Kanji

kOfxKey_Muhenkan

kOfxKey_Henkan_Mode

kOfxKey_Henkan

kOfxKey_Romaji

kOfxKey_Hiragana

kOfxKey_Katakana

kOfxKey_Hiragana_Katakana

kOfxKey_Zenkaku

kOfxKey_Hankaku

kOfxKey_Zenkaku_Hankaku

kOfxKey_Touroku

kOfxKey_Massyo

kOfxKey_Kana_Lock

kOfxKey_Kana_Shift

kOfxKey_Eisu_Shift

kOfxKey_Eisu_toggle

kOfxKey_Zen_Koho

kOfxKey_Mae_Koho

kOfxKey_Home

kOfxKey_Left

kOfxKey_Up

kOfxKey_Right

kOfxKey_Down

kOfxKey_Prior

kOfxKey_Page_Up

kOfxKey_Next

kOfxKey_Page_Down

kOfxKey_End

kOfxKey_Begin

kOfxKey_Select

kOfxKey_Print

kOfxKey_Execute

kOfxKey_Insert

kOfxKey_Undo

kOfxKey_Redo

kOfxKey_Menu

kOfxKey_Find

kOfxKey_Cancel

kOfxKey_Help

kOfxKey_Break

kOfxKey_Mode_switch

kOfxKey_script_switch

kOfxKey_Num_Lock

kOfxKey_KP_Space

kOfxKey_KP_Tab

kOfxKey_KP_Enter

kOfxKey_KP_F1

kOfxKey_KP_F2

kOfxKey_KP_F3

kOfxKey_KP_F4

kOfxKey_KP_Home

kOfxKey_KP_Left

kOfxKey_KP_Up

kOfxKey_KP_Right

kOfxKey_KP_Down

kOfxKey_KP_Prior

kOfxKey_KP_Page_Up

kOfxKey_KP_Next

kOfxKey_KP_Page_Down

kOfxKey_KP_End

kOfxKey_KP_Begin

kOfxKey_KP_Insert

kOfxKey_KP_Delete

kOfxKey_KP_Equal

kOfxKey_KP_Multiply

kOfxKey_KP_Add

kOfxKey_KP_Separator

kOfxKey_KP_Subtract

kOfxKey_KP_Decimal

kOfxKey_KP_Divide

kOfxKey_KP_0

kOfxKey_KP_1

kOfxKey_KP_2

kOfxKey_KP_3

kOfxKey_KP_4

kOfxKey_KP_5

kOfxKey_KP_6

kOfxKey_KP_7

kOfxKey_KP_8

kOfxKey_KP_9

kOfxKey_F1

kOfxKey_F2

kOfxKey_F3

kOfxKey_F4

kOfxKey_F5

kOfxKey_F6

kOfxKey_F7

kOfxKey_F8

kOfxKey_F9

kOfxKey_F10

kOfxKey_F11

kOfxKey_L1

kOfxKey_F12

kOfxKey_L2

kOfxKey_F13

kOfxKey_L3

kOfxKey_F14

kOfxKey_L4

kOfxKey_F15

kOfxKey_L5

kOfxKey_F16

kOfxKey_L6

kOfxKey_F17

kOfxKey_L7

kOfxKey_F18

kOfxKey_L8

kOfxKey_F19

kOfxKey_L9

kOfxKey_F20

kOfxKey_L10

kOfxKey_F21

kOfxKey_R1

kOfxKey_F22

kOfxKey_R2

kOfxKey_F23

kOfxKey_R3

kOfxKey_F24

kOfxKey_R4

kOfxKey_F25

kOfxKey_R5

kOfxKey_F26

kOfxKey_R6

kOfxKey_F27

kOfxKey_R7

kOfxKey_F28

kOfxKey_R8

kOfxKey_F29

kOfxKey_R9

kOfxKey_F30

kOfxKey_R10

kOfxKey_F31

kOfxKey_R11

kOfxKey_F32

kOfxKey_R12

kOfxKey_F33

kOfxKey_R13

kOfxKey_F34

kOfxKey_R14

kOfxKey_F35

kOfxKey_R15

kOfxKey_Shift_L

kOfxKey_Shift_R

kOfxKey_Control_L

kOfxKey_Control_R

kOfxKey_Caps_Lock

kOfxKey_Shift_Lock

kOfxKey_Meta_L

kOfxKey_Meta_R

kOfxKey_Alt_L

kOfxKey_Alt_R

kOfxKey_Super_L

kOfxKey_Super_R

kOfxKey_Hyper_L

kOfxKey_Hyper_R

kOfxKey_space

kOfxKey_exclam

kOfxKey_quotedbl

kOfxKey_numbersign

kOfxKey_dollar

kOfxKey_percent

kOfxKey_ampersand

kOfxKey_apostrophe

kOfxKey_quoteright

kOfxKey_parenleft

kOfxKey_parenright

kOfxKey_asterisk

kOfxKey_plus

kOfxKey_comma

kOfxKey_minus

kOfxKey_period

kOfxKey_slash

kOfxKey_0

kOfxKey_1

kOfxKey_2

kOfxKey_3

kOfxKey_4

kOfxKey_5

kOfxKey_6

kOfxKey_7

kOfxKey_8

kOfxKey_9

kOfxKey_colon

kOfxKey_semicolon

kOfxKey_less

kOfxKey_equal

kOfxKey_greater

kOfxKey_question

kOfxKey_at

kOfxKey_A

kOfxKey_B

kOfxKey_C

kOfxKey_D

kOfxKey_E

kOfxKey_F

kOfxKey_G

kOfxKey_H

kOfxKey_I

kOfxKey_J

kOfxKey_K

kOfxKey_L

kOfxKey_M

kOfxKey_N

kOfxKey_O

kOfxKey_P

kOfxKey_Q

kOfxKey_R

kOfxKey_S

kOfxKey_T

kOfxKey_U

kOfxKey_V

kOfxKey_W

kOfxKey_X

kOfxKey_Y

kOfxKey_Z

kOfxKey_bracketleft

kOfxKey_backslash

kOfxKey_bracketright

kOfxKey_asciicircum

kOfxKey_underscore

kOfxKey_grave

kOfxKey_quoteleft

kOfxKey_a

kOfxKey_b

kOfxKey_c

kOfxKey_d

kOfxKey_e

kOfxKey_f

kOfxKey_g

kOfxKey_h

kOfxKey_i

kOfxKey_j

kOfxKey_k

kOfxKey_l

kOfxKey_m

kOfxKey_n

kOfxKey_o

kOfxKey_p

kOfxKey_q

kOfxKey_r

kOfxKey_s

kOfxKey_t

kOfxKey_u

kOfxKey_v

kOfxKey_w

kOfxKey_x

kOfxKey_y

kOfxKey_z

kOfxKey_braceleft

kOfxKey_bar

kOfxKey_braceright

kOfxKey_asciitilde

kOfxKey_nobreakspace

kOfxKey_exclamdown

kOfxKey_cent

kOfxKey_sterling

kOfxKey_currency

kOfxKey_yen

kOfxKey_brokenbar

kOfxKey_section

kOfxKey_diaeresis

kOfxKey_copyright

kOfxKey_ordfeminine

kOfxKey_guillemotleft

kOfxKey_notsign

kOfxKey_hyphen

kOfxKey_registered

kOfxKey_macron

kOfxKey_degree

kOfxKey_plusminus

kOfxKey_twosuperior

kOfxKey_threesuperior

kOfxKey_acute

kOfxKey_mu

kOfxKey_paragraph

kOfxKey_periodcentered

kOfxKey_cedilla

kOfxKey_onesuperior

kOfxKey_masculine

kOfxKey_guillemotright

kOfxKey_onequarter

kOfxKey_onehalf

kOfxKey_threequarters

kOfxKey_questiondown

kOfxKey_Agrave

kOfxKey_Aacute

kOfxKey_Acircumflex

kOfxKey_Atilde

kOfxKey_Adiaeresis

kOfxKey_Aring

kOfxKey_AE

kOfxKey_Ccedilla

kOfxKey_Egrave

kOfxKey_Eacute

kOfxKey_Ecircumflex

kOfxKey_Ediaeresis

kOfxKey_Igrave

kOfxKey_Iacute

kOfxKey_Icircumflex

kOfxKey_Idiaeresis

kOfxKey_ETH

kOfxKey_Eth

kOfxKey_Ntilde

kOfxKey_Ograve

kOfxKey_Oacute

kOfxKey_Ocircumflex

kOfxKey_Otilde

kOfxKey_Odiaeresis

kOfxKey_multiply

kOfxKey_Ooblique

kOfxKey_Ugrave

kOfxKey_Uacute

kOfxKey_Ucircumflex

kOfxKey_Udiaeresis

kOfxKey_Yacute

kOfxKey_THORN

kOfxKey_ssharp

kOfxKey_agrave

kOfxKey_aacute

kOfxKey_acircumflex

kOfxKey_atilde

kOfxKey_adiaeresis

kOfxKey_aring

kOfxKey_ae

kOfxKey_ccedilla

kOfxKey_egrave

kOfxKey_eacute

kOfxKey_ecircumflex

kOfxKey_ediaeresis

kOfxKey_igrave

kOfxKey_iacute

kOfxKey_icircumflex

kOfxKey_idiaeresis

kOfxKey_eth

kOfxKey_ntilde

kOfxKey_ograve

kOfxKey_oacute

kOfxKey_ocircumflex

kOfxKey_otilde

kOfxKey_odiaeresis

kOfxKey_division

kOfxKey_oslash

kOfxKey_ugrave

kOfxKey_uacute

kOfxKey_ucircumflex

kOfxKey_udiaeresis

kOfxKey_yacute

kOfxKey_thorn

kOfxKey_ydiaeresis

file ofxMemory.h

This file contains the API for general purpose memory allocation from a host.

Defines

kOfxMemorySuite

Typedefs

typedef struct OfxMemorySuiteV1 OfxMemorySuiteV1

The OFX suite that implements general purpose memory management.

Use this suite for ordinary memory management functions, where you would normally use malloc/free or new/delete on ordinary objects.

For images, you should use the memory allocation functions in the image effect suite, as many hosts have specific image memory pools.

Note

C++ plugin developers will need to redefine new and delete as skins on top of this suite.

file ofxMessage.h

#include “ofxCore.h”

This file contains the Host API for end user message communication.

Defines

kOfxMessageSuite

kOfxMessageFatal

String used to type fatal error messages.

Fatal error messages should only be posted by a plugin when it can no longer continue operation.

kOfxMessageError

String used to type error messages.

Ordinary error messages should be posted when there is an error in operation that is recoverable by user intervention.

kOfxMessageWarning

String used to type warning messages.

Warnings indicate states that allow for operations to proceed, but are not necessarily optimal.

kOfxMessageMessage

String used to type simple ordinary messages.

Ordinary messages simply convey information from the plugin directly to the user.

kOfxMessageLog

String used to type log messages.

Log messages are written out to a log and not to the end user.

kOfxMessageQuestion

String used to type yes/no messages.

The host is to enter a modal state which waits for the user to respond yes or no. The OfxMessageSuiteV1::message function which posted the message will only return after the user responds. When asking a question, the OfxStatus code returned by the message function will be,

kOfxStatReplyYes - if the user replied ‘yes’ to the question
kOfxStatReplyNo - if the user replied ‘no’ to the question
some error code if an error was encounterred

It is an error to post a question message if the plugin is not in an interactive session.

Typedefs

typedef struct OfxMessageSuiteV1 OfxMessageSuiteV1: The OFX suite that allows a plug-in to pass messages back to a user. The V2 suite extends on this in a backwards compatible manner.

typedef struct OfxMessageSuiteV2 OfxMessageSuiteV2

The OFX suite that allows a plug-in to pass messages back to a user.

This extends OfxMessageSuiteV1, and should be considered a replacement to version 1.

Note that this suite has been extended in backwards compatible manner, so that a host can return this struct for both V1 and V2.

file ofxMultiThread.h

#include “ofxCore.h”

This file contains the Host Suite for threading

Defines

kOfxMultiThreadSuite

Typedefs

typedef struct OfxMutex *OfxMutexHandle: Mutex blind data handle.

void() OfxThreadFunctionV1 (unsigned int threadIndex, unsigned int threadMax, void *customArg)

The function type to passed to the multi threading routines.

threadIndex unique index of this thread, will be between 0 and threadMax
threadMax to total number of threads executing this function
customArg the argument passed into multiThread

A function of this type is passed to OfxMultiThreadSuiteV1::multiThread to be launched in multiple threads.

typedef struct OfxMultiThreadSuiteV1 OfxMultiThreadSuiteV1: OFX suite that provides simple SMP style multi-processing.

file ofxOld.h

Defines

kOfxImageComponentYUVA

String to label images with YUVA components —ofxImageEffects.h.

Deprecated:

removed in v1.4. Note, this has been deprecated in v1.3

kOfxImageEffectPropInAnalysis

Indicates whether an effect is performing an analysis pass. —ofxImageEffects.h.

Deprecated:

This feature has been deprecated - officially commented out v1.4.

kOfxInteractPropViewportSize

The size of an interact’s openGL viewport — ofxInteract.h.

Deprecated:

V1.3: This property is the redundant and its use will be deprecated in future releases. V1.4: Removed

kOfxParamDoubleTypeNormalisedX

value for the kOfxParamPropDoubleType property, indicating a size normalised to the X dimension. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of ::OfxParamDoubleTypeX V1.4: Removed

kOfxParamDoubleTypeNormalisedY

value for the kOfxParamPropDoubleType property, indicating a size normalised to the Y dimension. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of ::OfxParamDoubleTypeY V1.4: Removed

kOfxParamDoubleTypeNormalisedXAbsolute

value for the kOfxParamPropDoubleType property, indicating an absolute position normalised to the X dimension. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of ::OfxParamDoubleTypeXAbsolute V1.4: Removed

kOfxParamDoubleTypeNormalisedYAbsolute

value for the kOfxParamPropDoubleType property, indicating an absolute position normalised to the Y dimension. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of ::OfxParamDoubleTypeYAbsolute V1.4: Removed

kOfxParamDoubleTypeNormalisedXY

value for the kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for 2D params. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of ::OfxParamDoubleTypeXY V1.4: Removed

kOfxParamDoubleTypeNormalisedXYAbsolute

value for the kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for a 2D param that can be interpreted as an absolute spatial position. See kOfxParamPropDoubleType. — ofxParam.h

Deprecated:

V1.3: Deprecated in favour of kOfxParamDoubleTypeXYAbsolute V1.4: Removed

Typedefs

typedef struct OfxYUVAColourB OfxYUVAColourB: Defines an 8 bit per component YUVA pixel — ofxPixels.h Deprecated in 1.3, removed in 1.4.

typedef struct OfxYUVAColourS OfxYUVAColourS

Defines an 16 bit per component YUVA pixel — ofxPixels.h.

Deprecated:

Deprecated in 1.3, removed in 1.4

typedef struct OfxYUVAColourF OfxYUVAColourF

Defines an floating point component YUVA pixel — ofxPixels.h.

Deprecated:

Deprecated in 1.3, removed in 1.4

file ofxOpenGLRender.h

Defines

_ofxOpenGLRender_h_

file ofxParam.h

#include “ofxCore.h”

#include “ofxProperty.h”

This header contains the suite definition to manipulate host side parameters.

For more details go see ParametersPage

Defines

kOfxParameterSuite: string value to the kOfxPropType property for all parameters

kOfxTypeParameter: string value on the kOfxPropType property for all parameter definitions (ie: the handle returned in describe)

kOfxTypeParameterInstance: string value on the kOfxPropType property for all parameter instances

kOfxParamTypeInteger: String to identify a param as a single valued integer.

kOfxParamTypeDouble: String to identify a param as a Single valued floating point parameter

kOfxParamTypeBoolean: String to identify a param as a Single valued boolean parameter.

kOfxParamTypeChoice: String to identify a param as a Single valued, ‘one-of-many’ parameter.

kOfxParamTypeStrChoice

String to identify a param as a string-valued ‘one-of-many’ parameter.

Since: Version 1.5

kOfxParamTypeRGBA: String to identify a param as a Red, Green, Blue and Alpha colour parameter.

kOfxParamTypeRGB: String to identify a param as a Red, Green and Blue colour parameter.

kOfxParamTypeDouble2D: String to identify a param as a Two dimensional floating point parameter.

kOfxParamTypeInteger2D: String to identify a param as a Two dimensional integer point parameter.

kOfxParamTypeDouble3D: String to identify a param as a Three dimensional floating point parameter.

kOfxParamTypeInteger3D: String to identify a param as a Three dimensional integer parameter.

kOfxParamTypeString: String to identify a param as a String (UTF8) parameter.

kOfxParamTypeCustom: String to identify a param as a Plug-in defined parameter.

kOfxParamTypeBytes: String to identify a param as a Plug-in defined opaque data parameter.

kOfxParamTypeGroup: String to identify a param as a Grouping parameter.

kOfxParamTypePage: String to identify a param as a page parameter.

kOfxParamTypePushButton: String to identify a param as a PushButton parameter.

kOfxParamHostPropSupportsCustomAnimation: Indicates if the host supports animation of custom parameters.

kOfxParamHostPropSupportsStringAnimation: Indicates if the host supports animation of string params.

kOfxParamHostPropSupportsBooleanAnimation: Indicates if the host supports animation of boolean params.

kOfxParamHostPropSupportsChoiceAnimation: Indicates if the host supports animation of choice params.

kOfxParamHostPropSupportsCustomInteract

Indicates if the host supports custom interacts for parameters.

Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.

kOfxParamHostPropMaxParameters

Indicates the maximum numbers of parameters available on the host.

If set to -1 it implies unlimited number of parameters.

kOfxParamHostPropMaxPages

Indicates the maximum number of parameter pages.

If there is no limit to the number of pages on a host, set this to -1.

Hosts that do not support paged parameter layout should set this to zero.

kOfxParamHostPropPageRowColumnCount

This indicates the number of parameter rows and columns on a page.

If the host has supports paged parameter layout, used dimension 0 as the number of columns per page and dimension 1 as the number of rows per page.

kOfxParamPageSkipRow

Pseudo parameter name used to skip a row in a page layout.

Passed as a value to the kOfxParamPropPageChild property.

See ParametersInterfacesPagedLayouts for more details.

kOfxParamPageSkipColumn

Pseudo parameter name used to skip a row in a page layout.

Passed as a value to the kOfxParamPropPageChild property.

See ParametersInterfacesPagedLayouts for more details.

kOfxParamPropInteractV1

Overrides the parameter’s standard user interface with the given interact.

If set, the parameter’s normal interface is replaced completely by the interact gui.

Currently custom interacts for parameters can only be drawn using OpenGL. APIs will be added later to support using the new Draw Suite.

- Valid Values -  must point to a OfxPluginEntryPoint

kOfxParamPropInteractSize

The size of a parameter instance’s custom interface in screen pixels.

This is set by a host to indicate the current size of a custom interface if the plug-in has one. If not this is set to (0,0).

kOfxParamPropInteractSizeAspect

The preferred aspect ratio of a parameter’s custom interface.

If set to anything other than 0.0, the custom interface for this parameter will be of a size with this aspect ratio (x size/y size).

- Valid Values - greater than or equal to 0.0

kOfxParamPropInteractMinimumSize

The minimum size of a parameter’s custom interface, in screen pixels.

Any custom interface will not be less than this size.

- Valid Values - greater than (0, 0)

kOfxParamPropInteractPreferedSize

The preferred size of a parameter’s custom interface.

A host should attempt to set a parameter’s custom interface on a parameter to be this size if possible, otherwise it will be of kOfxParamPropInteractSizeAspect aspect but larger than kOfxParamPropInteractMinimumSize.

Valid Values - greater than (0, 0)

kOfxParamPropType

The type of a parameter.

This string will be set to the type that the parameter was create with.

kOfxParamPropAnimates

Flags whether a parameter can animate.

A plug-in uses this property to indicate if a parameter is able to animate.

kOfxParamPropCanUndo: Flags whether changes to a parameter should be put on the undo/redo stack.

kOfxPropParamSetNeedsSyncing

States whether the plugin needs to resync its private data.

The plugin should set this flag to true whenever any internal state has not been flushed to the set of params.

The host will examine this property each time it does a copy or save operation on the instance. If it is set to 1, the host will call SyncPrivateData and then set it to zero before doing the copy/save. If it is set to 0, the host will assume that the param data correctly represents the private state, and will not call SyncPrivateData before copying/saving. If this property is not set, the host will always call SyncPrivateData before copying or saving the effect (as if the property were set to 1 — but the host will not create or modify the property).

Valid Values -
- 0 - no need to sync
- 1 - paramset is not synced

kOfxParamPropIsAnimating

Flags whether a parameter is currently animating.

Set by a host on a parameter instance to indicate if the parameter has a non-constant value set on it. This can be as a consequence of animation or of scripting modifying the value, or of a parameter being connected to an expression in the host.

kOfxParamPropPluginMayWrite

Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis pass.

This is used to tell the host whether the plug-in is going to attempt to set the value of the parameter.

Deprecated:

v1.4: deprecated - to be removed in 1.5

kOfxParamPropPersistant

Flags whether the value of a parameter should persist.

This is used to tell the host whether the value of the parameter is important and should be save in any description of the plug-in.

kOfxParamPropEvaluateOnChange

Flags whether changing a parameter’s value forces an evaluation (ie: render),.

This is used to indicate if the value of a parameter has any affect on an effect’s output, eg: the parameter may be purely for GUI purposes, and so changing its value should not trigger a re-render.

kOfxParamPropSecret

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.

kOfxParamPropScriptName

The value to be used as the id of the parameter in a host scripting language.

Many hosts have a scripting language that they use to set values of parameters and more. If so, this is the name of a parameter in such scripts.

- Valid Values - ASCII string unique to all parameters in the plug-in.

kOfxParamPropCacheInvalidation

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. -If the parameter represents something like an absolute position, the cache will only need to be invalidated for the range of frames that keyframe affects.

If the parameter represents something like a speed which is integrated, the cache will be invalidated from the keyframe until the end of the clip.
There are potentially other situations where the entire cache will need to be invalidated (though I can’t think of one off the top of my head).
- Valid Values - This must be one of

kOfxParamInvalidateValueChange: Used as a value for the kOfxParamPropCacheInvalidation property.

kOfxParamInvalidateValueChangeToEnd: Used as a value for the kOfxParamPropCacheInvalidation property.

kOfxParamInvalidateAll: Used as a value for the kOfxParamPropCacheInvalidation property.

kOfxParamPropHint: A hint to the user as to how the parameter is to be used.

kOfxParamPropDefault

The default value of a parameter.

The exact type and dimension is dependent on the type of the parameter. These are….

kOfxParamTypeInteger - integer property of one dimension
kOfxParamTypeDouble - double property of one dimension
kOfxParamTypeBoolean - integer property of one dimension
kOfxParamTypeChoice - integer property of one dimension
kOfxParamTypeStrChoice - string property of one dimension
kOfxParamTypeRGBA - double property of four dimensions
kOfxParamTypeRGB - double property of three dimensions
kOfxParamTypeDouble2D - double property of two dimensions
kOfxParamTypeInteger2D - integer property of two dimensions
kOfxParamTypeDouble3D - double property of three dimensions
kOfxParamTypeInteger3D - integer property of three dimensions
kOfxParamTypeString - string property of one dimension
kOfxParamTypeCustom - string property of one dimension
kOfxParamTypeBytes - pointer to OfxBytes struct of one dimension, or nullptr
kOfxParamTypeGroup - does not have this property
kOfxParamTypePage - does not have this property
kOfxParamTypePushButton - does not have this property

kOfxParamPropDoubleType

Describes how the double parameter should be interpreted by a host.

Valid Values -This must be one of
- kOfxParamDoubleTypePlain - parameter has no special interpretation,
- kOfxParamDoubleTypeAngle - parameter is to be interpreted as an angle,
- kOfxParamDoubleTypeScale - parameter is to be interpreted as a scale factor,
- kOfxParamDoubleTypeTime - parameter represents a time value (1D only),
- kOfxParamDoubleTypeAbsoluteTime - parameter represents an absolute time value (1D only),
- kOfxParamDoubleTypeX - size wrt to the project’s X dimension (1D only), in canonical coordinates,
- kOfxParamDoubleTypeXAbsolute - absolute position on the X axis (1D only), in canonical coordinates,
- kOfxParamDoubleTypeY - size wrt to the project’s Y dimension(1D only), in canonical coordinates,
- kOfxParamDoubleTypeYAbsolute - absolute position on the Y axis (1D only), in canonical coordinates,
- kOfxParamDoubleTypeXY - size in 2D (2D only), in canonical coordinates,
- kOfxParamDoubleTypeXYAbsolute - an absolute position on the image plane, in canonical coordinates.

Double parameters can be interpreted in several different ways, this property tells the host how to do so and thus gives hints as to the interface of the parameter.

kOfxParamDoubleTypePlain: value for the kOfxParamPropDoubleType property, indicating the parameter has no special interpretation and should be interpreted as a raw numeric value.

kOfxParamDoubleTypeScale: value for the kOfxParamPropDoubleType property, indicating the parameter is to be interpreted as a scale factor. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeAngle: value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an angle. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeTime: value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as a time. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeAbsoluteTime: value for the kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an absolute time from the start of the effect. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeX: value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the X dimension. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeY: value for the kOfxParamPropDoubleType property, indicating a size in canonical coords in the Y dimension. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeXAbsolute: value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the X dimension. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeYAbsolute: value for the kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the Y dimension. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeXY: value for the kOfxParamPropDoubleType property, indicating a 2D size in canonical coords. See kOfxParamPropDoubleType.

kOfxParamDoubleTypeXYAbsolute: value for the kOfxParamPropDoubleType property, indicating a 2D position in canonical coords. See kOfxParamPropDoubleType.

kOfxParamPropDefaultCoordinateSystem

Describes in which coordinate system a spatial double parameter’s default value is specified.

This allows a spatial param to specify what its default is, so by saying normalised and “0.5” it would be in the ‘middle’, by saying canonical and 100 it would be at value 100 independent of the size of the image being applied to.

Valid Values - This must be one of
- kOfxParamCoordinatesCanonical - the default is in canonical coords
- kOfxParamCoordinatesNormalised - the default is in normalised coordinates

kOfxParamCoordinatesCanonical: Define the canonical coordinate system.

kOfxParamCoordinatesNormalised: Define the normalised coordinate system.

kOfxParamPropHasHostOverlayHandle

A flag to indicate if there is a host overlay UI handle for the given parameter.

If set to 1, then the host is flagging that there is some sort of native user overlay interface handle available for the given parameter.

kOfxParamPropUseHostOverlayHandle

A flag to indicate that the host should use a native UI overlay handle for the given parameter.

If set to 1, then a plugin is flaging to the host that the host should use a native UI overlay handle for the given parameter. A plugin can use this to keep a native look and feel for parameter handles. A plugin can use kOfxParamPropHasHostOverlayHandle to see if handles are available on the given parameter.

kOfxParamInterpTypeConstantStep: value for the kOfxParamInterpType property, indicating a constant/hold/step interpolation type. See kOfxParamInterpType.

kOfxParamInterpTypeLinear: value for the kOfxParamInterpType property, indicating a linear interpolation type. See kOfxParamInterpType.

kOfxParamInterpTypeSmooth: value for the kOfxParamInterpType property, indicating some kind of smooth interpolation type. See kOfxParamInterpType.

kOfxParamInterpType

Sets the default interpolation type of a Integer or Double parameter.

Type - C string X 1
Default - kOfxParamInterpTypeLinear
Property Set - 1D integer and double plugin parameter descriptor (read/write) and instance (read only)
Valid Values - This must be one of
- kOfxParamInterpTypeConstantStep - constant/hold/step interpolation,
- kOfxParamInterpTypeLinear - linear interpolation,
- kOfxParamInterpTypeSmooth - some kind of smooth (bezier, hermite, cardinal, etc) interpolation

This allows a plugin to indicate how a number-type parameter should be interpolated by default. This is useful if a parameter is used to encode a keyed set of interesting frame numbers to be used as markers or retime points without the host animating them.

kOfxParamPropShowTimeMarker

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.

kOfxPluginPropParamPageOrder

Sets the parameter pages and order of pages.

This property sets the preferred order of parameter pages on a host. If this is never set, the preferred order is the order the parameters were declared in.

- Valid Values - the names of any page param in the plugin

kOfxParamPropPageChild

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.

- Valid Values - the names of any parameter that is not a group or page, as well as ::kOfxParamPageSkipRow and ::kOfxParamPageSkipColumn

kOfxParamPropParent

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.

- Valid Values - the name of a parameter with type of ::kOfxParamTypeGroup

kOfxParamPropGroupOpen

Whether the initial state of a group is open or closed in a hierarchical layout.

This is a property on parameters of type kOfxParamTypeGroup, and tells the group whether it should be open or closed by default.

kOfxParamPropEnabled

Used to enable a parameter in the user interface.

When set to 0 a user should not be able to modify the value of the parameter. Note that the plug-in itself can still change the value of a disabled parameter.

kOfxParamPropDataPtr

A private data pointer that the plug-in can store its own data behind.

This data pointer is unique to each parameter instance, so two instances of the same parameter do not share the same data pointer. Use it to hang any needed private data structures.

kOfxParamPropChoiceOption

Set options of a choice parameter.

This property contains the set of options that will be presented to a user from a choice parameter. See ParametersChoice for more details.

kOfxParamPropChoiceOrder

Set values the host should store for a choice parameter.

(read/write), OfxParamPropChoiceOption

This property specifies the order in which the options are presented. See “Choice Parameters” for more details. This property is optional; if not set, the host will present the options in their natural order.

This property is useful when changing order of choice param options, or adding new options in the middle, in a new version of the plugin.

  Plugin v1:
  Option = {"OptA", "OptB", "OptC"}
  Order = {1, 2, 3}

  Plugin v2:
  // will be shown as OptA / OptB / NewOpt / OptC
  Option = {"OptA", "OptB", "OptC", NewOpt"}
  Order = {1, 2, 4, 3}

Note that this only affects the host UI’s display order; the project still stores the index of the selected option as always. Plugins should never reorder existing options if they desire backward compatibility.

Values may be arbitrary 32-bit integers. Behavior is undefined if the same value occurs twice in the list; plugins should not do that.

Since: Version 1.5

kOfxParamPropChoiceEnum

Set a enumeration string in a StrChoice (string-valued choice) parameter.

(read/write), This property contains the set of enumeration strings stored by the host in the project corresponding to the options that will be presented to a user from a StrChoice parameter. See ParametersChoice for more details.

Since: Version 1.5

kOfxParamHostPropSupportsStrChoiceAnimation

Indicates if the host supports animation of string choice params.

Since: Version 1.5

kOfxParamHostPropSupportsStrChoice

Indicates if the host supports the StrChoice param type.

Since: Version 1.5

kOfxParamPropMin

The minimum value for a numeric parameter.

Setting this will also reset kOfxParamPropDisplayMin.

kOfxParamPropMax

The maximum value for a numeric parameter.

Setting this will also reset kOfxParamPropDisplayMax.

kOfxParamPropDisplayMin

The minimum value for a numeric parameter on any user interface.

If a user interface represents a parameter with a slider or similar, this should be the minimum bound on that slider.

kOfxParamPropDisplayMax

The maximum value for a numeric parameter on any user interface.

If a user interface represents a parameter with a slider or similar, this should be the maximum bound on that slider.

kOfxParamPropIncrement

The granularity of a slider used to represent a numeric parameter.

This value is always in canonical coordinates for double parameters that are normalised.

- Valid Values - any greater than 0.

kOfxParamPropDigits

How many digits after a decimal point to display for a double param in a GUI.

This applies to double params of any dimension.

- Valid Values - any greater than 0.

kOfxParamPropDimensionLabel

Label for individual dimensions on a multidimensional numeric parameter.

Use this on 2D and 3D double and integer parameters to change the label on an individual dimension in any GUI for that parameter.

- Valid Values - any

kOfxParamPropIsAutoKeying

Will a value change on the parameter add automatic keyframes.

This is set by the host simply to indicate the state of the property.

kOfxParamPropCustomInterpCallbackV1

A pointer to a custom parameter’s interpolation function.

It is an error not to set this property in a custom parameter during a plugin’s define call if the custom parameter declares itself to be an animating parameter.

- Valid Values - must point to a ::OfxCustomParamInterpFuncV1

kOfxParamPropStringMode

Used to indicate the type of a string parameter.

Valid Values - This must be one of the following

kOfxParamPropStringFilePathExists

Indicates string parameters of file or directory type need that file to exist already.

If set to 0, it implies the user can specify a new file name, not just a pre-existing one.

kOfxParamStringIsSingleLine: Used to set a string parameter to be single line, value to be passed to a kOfxParamPropStringMode property.

kOfxParamStringIsMultiLine: Used to set a string parameter to be multiple line, value to be passed to a kOfxParamPropStringMode property.

kOfxParamStringIsFilePath: Used to set a string parameter to be a file path, value to be passed to a kOfxParamPropStringMode property.

kOfxParamStringIsDirectoryPath: Used to set a string parameter to be a directory path, value to be passed to a kOfxParamPropStringMode property.

kOfxParamStringIsLabel: Use to set a string parameter to be a simple label, value to be passed to a kOfxParamPropStringMode property

kOfxParamStringIsRichTextFormat: String value on the kOfxParamPropStringMode property of a string parameter (added in 1.3)

kOfxParamPropCustomValue: 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.

kOfxParamPropInterpolationTime

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.

kOfxParamPropInterpolationAmount

Property used by OfxCustomParamInterpFuncV1 to indicate the amount of interpolation to perform.

This property indicates how far between the two kOfxParamPropCustomValue keys to interpolate.

Valid Values - from 0 to 1

Typedefs

typedef struct OfxParamStruct *OfxParamHandle: Blind declaration of an OFX param.

typedef struct OfxParamSetStruct *OfxParamSetHandle: Blind declaration of an OFX parameter set.

typedef struct OfxBytes OfxBytes: Provides information for a parameter of type kOfxParamTypeBytes.

OfxStatus() OfxCustomParamInterpFuncV1 (OfxParamSetHandle instance, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs)

Function prototype for custom parameter interpolation callback functions.

instance the plugin instance that this parameter occurs in
inArgs handle holding the following properties…
- kOfxPropName - the name of the custom parameter to interpolate
- kOfxPropTime - absolute time the interpolation is occurring at
- kOfxParamPropCustomValue - string property that gives the value of the two keyframes to interpolate, in this case 2D
- kOfxParamPropInterpolationTime - 2D double property that gives the time of the two keyframes we are interpolating
- kOfxParamPropInterpolationAmount - 1D double property indicating how much to interpolate between the two keyframes

outArgs handle holding the following properties to be set
- kOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D

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.

typedef struct OfxParameterSuiteV1 OfxParameterSuiteV1: The OFX suite used to define and manipulate user visible parameters.

file ofxParametricParam.h

#include “ofxParam.h”

This header file defines the optional OFX extension to define and manipulate parametric parameters.

Defines

kOfxParametricParameterSuite: string value to the kOfxPropType property for all parameters

kOfxParamTypeParametric: String to identify a param as a single valued integer.

kOfxParamPropParametricDimension

The dimension of a parametric param.

This indicates the dimension of the parametric param.

kOfxParamPropParametricUIColour

The colour of parametric param curve interface in any UI.

being interpreted as R, G and B of the colour for each curve drawn in the UI.

This sets the colour of a parametric param curve drawn a host user interface. A colour triple is needed for each dimension of the oparametric param.

If not set, the host should generally draw these in white.

kOfxParamPropParametricInteractBackground

Interact entry point to draw the background of a parametric parameter.

Defines a pointer to an interact which will be used to draw the background of a parametric parameter’s user interface. None of the pen or keyboard actions can ever be called on the interact.

The openGL transform will be set so that it is an orthographic transform that maps directly to the ‘parametric’ space, so that ‘x’ represents the parametric position and ‘y’ represents the evaluated value.

kOfxParamHostPropSupportsParametricAnimation

Property on the host to indicate support for parametric parameter animation.

Valid Values
- 0 indicating the host does not support animation of parmetric params,
- 1 indicating the host does support animation of parmetric params,

kOfxParamPropParametricRange

Property to indicate the min and max range of the parametric input value.

This controls the min and max values that the parameter will be evaluated at.

- Valid Values - any pair of numbers so that  the first is less than the second.

Typedefs

typedef struct OfxParametricParameterSuiteV1 OfxParametricParameterSuiteV1

The OFX suite used to define and manipulate ‘parametric’ parameters.

This is an optional suite.

Parametric parameters are in effect ‘functions’ a plug-in can ask a host to arbitrarily evaluate for some value ‘x’. A classic use case would be for constructing look-up tables, a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that to fill an array.

A host would probably represent this to a user as a cubic curve in a standard curve editor interface, or possibly through scripting. The user would then use this to define the ‘shape’ of the parameter.

The evaluation of such params is not the same as animation, they are returning values based on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass a parametric position and time.

Often, you would want such a parametric parameter to be multi-dimensional, for example, a colour look-up table might want three values, one for red, green and blue. Rather than declare three separate parametric parameters, it would be better to have one such parameter with multiple values in it.

The major complication with these parameters is how to allow a plug-in to set values, and defaults. The default default value of a parametric curve is to be an identity lookup. If a plugin wishes to set a different default value for a curve, it can use the suite to set key/value pairs on the descriptor of the param. When a new instance is made, it will have these curve values as a default.

file ofxPixels.h

Contains pixel struct definitions

Typedefs

typedef struct OfxRGBAColourB OfxRGBAColourB: Defines an 8 bit per component RGBA pixel.

typedef struct OfxRGBAColourS OfxRGBAColourS: Defines a 16 bit per component RGBA pixel.

typedef struct OfxRGBAColourF OfxRGBAColourF: Defines a floating point component RGBA pixel.

typedef struct OfxRGBAColourD OfxRGBAColourD: Defines a double precision floating point component RGBA pixel.

typedef struct OfxRGBColourB OfxRGBColourB: Defines an 8 bit per component RGB pixel.

typedef struct OfxRGBColourS OfxRGBColourS: Defines a 16 bit per component RGB pixel.

typedef struct OfxRGBColourF OfxRGBColourF: Defines a floating point component RGB pixel.

typedef struct OfxRGBColourD OfxRGBColourD: Defines a double precision floating point component RGB pixel.

file ofxProgress.h

Defines

kOfxProgressSuite: suite for displaying a progress bar

Typedefs

typedef struct OfxProgressSuiteV1 OfxProgressSuiteV1

A suite that provides progress feedback from a plugin to an application.

A plugin instance can initiate, update and close a progress indicator with this suite.

This is an optional suite in the Image Effect API.

API V1.4: Amends the documentation of progress suite V1 so that it is expected that it can be raised in a modal manner and have a “cancel” button when invoked in instanceChanged. Plugins that perform analysis post an appropriate message, raise the progress monitor in a modal manner and should poll to see if processing has been aborted. Any cancellation should be handled gracefully by the plugin (eg: reset analysis parameters to default values), clear allocated memory…

Many hosts already operate as described above. kOfxStatReplyNo should be returned to the plugin during progressUpdate when the user presses cancel.

Suite V2: Adds an ID that can be looked up for internationalisation and so on. When a new version is introduced, because plug-ins need to support old versions, and plug-in’s new releases are not necessary in synch with hosts (or users don’t immediately update), best practice is to support the 2 suite versions. That is, the plugin should check if V2 exists; if not then check if V1 exists. This way a graceful transition is guaranteed. So plugin should fetchSuite passing 2, (OfxProgressSuiteV2*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); and if no success pass (OfxProgressSuiteV1*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,1);

typedef struct OfxProgressSuiteV2 OfxProgressSuiteV2

file ofxProperty.h

#include “ofxCore.h”

Contains the API for manipulating generic properties. For more details see PropertiesPage.

Defines

kOfxPropertySuite

Typedefs

typedef struct OfxPropertySuiteV1 OfxPropertySuiteV1: The OFX suite used to access properties on OFX objects.

file ofxTimeLine.h

Defines

kOfxTimeLineSuite: Name of the time line suite.

Typedefs

typedef struct OfxTimeLineSuiteV1 OfxTimeLineSuiteV1

Suite to control timelines.

This suite is used to enquire and control a timeline associated with a plug-in instance.

This is an optional suite in the Image Effect API.

group ActionsAll: These are the actions passed to a plug-in’s ‘main’ function

group PropertiesAll: These strings are used to identify properties within OFX, they are broken up by the host suite or API they relate to.

group PropertiesGeneral: These properties are general properties and apply to may objects across OFX

group StatusCodes: These strings are used to identify error states within ofx, they are returned by various host suite functions, as well as plug-in functions. The valid return codes for each function are documented with that function.

group StatusCodesGeneral: General status codes start at 1 and continue until 999

group OpenGLRenderSuite

StatusReturnValues

OfxStatus returns indicating that a OpenGL render error has occurred:

If a plug-in returns kOfxStatGLRenderFailed, the host should retry the render with OpenGL rendering disabled.
If a plug-in returns kOfxStatGLOutOfMemory, the host may choose to free resources on the GPU and retry the OpenGL render, rather than immediately falling back to CPU rendering.

kOfxStatGPUOutOfMemory: GPU render ran out of memory.

kOfxStatGLOutOfMemory: OpenGL render ran out of memory (same as kOfxStatGPUOutOfMemory)

kOfxStatGPURenderFailed: GPU render failed in a non-memory-related way.

kOfxStatGLRenderFailed: OpenGL render failed in a non-memory-related way (same as kOfxStatGPURenderFailed)

Defines

kOfxOpenGLRenderSuite: The name of the OpenGL render suite, used to fetch from a host via OfxHost::fetchSuite.

kOfxImageEffectPropOpenGLRenderSupported

Indicates whether a host or plug-in can support OpenGL accelerated rendering.

Valid Values -
- “false” - in which case the host or plug-in does not support OpenGL accelerated rendering
- ”true” - which means a host or plug-in can support OpenGL accelerated rendering, in the case of plug-ins this also means that it is capable of CPU based rendering in the absence of a GPU
- ”needed” - only for plug-ins, this means that an plug-in has to have OpenGL support, without which it cannot work.

V1.4: It is now expected from host reporting v1.4 that the plug-in can during instance change switch from true to false and false to true.

kOfxOpenGLPropPixelDepth

Indicates the bit depths supported by a plug-in during OpenGL renders.

This is analogous to kOfxImageEffectPropSupportedPixelDepths. When a plug-in sets this property, the host will try to provide buffers/textures in one of the supported formats. Additionally, the target buffers where the plug-in renders to will be set to one of the supported formats.

Unlike kOfxImageEffectPropSupportedPixelDepths, this property is optional. Shader-based effects might not really care about any format specifics when using OpenGL textures, so they can leave this unset and allow the host the decide the format.

Valid Values -
- kOfxBitDepthNone (implying a clip is unconnected, not valid for an image)
- kOfxBitDepthByte
- kOfxBitDepthShort
- kOfxBitDepthHalf
- kOfxBitDepthFloat

kOfxImageEffectPropOpenGLEnabled

Indicates that a plug-in SHOULD use OpenGL acceleration in the current action.

When a plug-in and host have established they can both use OpenGL renders then when this property has been set the host expects the plug-in to render its result into the buffer it has setup before calling the render. The plug-in can then also safely use the ‘OfxImageEffectOpenGLRenderSuite’

Valid Values
- 0 indicates that the plug-in cannot use the OpenGL suite
- 1 indicates that the plug-in should render into the texture, and may use the OpenGL suite functions.

v1.4: kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture

Note

Once this property is set, the host and plug-in have agreed to use OpenGL, so the effect SHOULD access all its images through the OpenGL suite.

kOfxImageEffectPropOpenGLTextureIndex

Indicates the texture index of an image turned into an OpenGL texture by the host.

This value should be cast to a GLuint and used as the texture index when performing OpenGL texture operations.

The property set of the following actions should contain this property:

kOfxImageEffectPropOpenGLTextureTarget

Indicates the texture target enumerator of an image turned into an OpenGL texture by the host.

This value should be cast to a GLenum and used as the texture target when performing OpenGL texture operations.

The property set of the following actions should contain this property:

kOfxImageEffectPropCPURenderSupported

Indicates whether a host or plug-in can (or more importantly cannot) support CPU rendering.

Valid Values -
- “false” - in which case the host or plug-in does not support CPU rendering
- ”true” - which means a host or plug-in can support CPU rendering

Version: added in version 1.5.1.

kOfxActionOpenGLContextAttached

Action called when an effect has just been attached to an OpenGL context.

The purpose of this action is to allow a plug-in to set up any data it may need to do OpenGL rendering in an instance. For example…

allocate a lookup table on a GPU,
create an OpenCL or CUDA context that is bound to the host’s OpenGL context so it can share buffers.

The plug-in will be responsible for deallocating any such shared resource in the kOfxActionOpenGLContextDetached action.

A host cannot call kOfxActionOpenGLContextAttached on the same instance without an intervening kOfxActionOpenGLContextDetached. A host can have a plug-in swap OpenGL contexts by issuing a attach/detach for the first context then another attach for the next context.

The arguments to the action are…

handle handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs is redundant and set to NULL
outArgs is redundant and set to NULL

A plug-in can return…

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored, but all was well anyway
kOfxStatErrMemory, in which case this may be called again after a memory purge
kOfxStatFailed, something went wrong, but no error code appropriate, the plug-in should to post a message if possible and the host should not attempt to run the plug-in in OpenGL render mode.

kOfxActionOpenGLContextDetached

Action called when an effect is about to be detached from an OpenGL context.

The purpose of this action is to allow a plug-in to deallocate any resource allocated in kOfxActionOpenGLContextAttached just before the host decouples a plug-in from an OpenGL context. The host must call this with the same OpenGL context active as it called with the corresponding kOfxActionOpenGLContextAttached.

The arguments to the action are…

handle handle to the plug-in instance, cast to an OfxImageEffectHandle
inArgs is redundant and set to NULL
outArgs is redundant and set to NULL

A plug-in can return…

kOfxStatOK, the action was trapped and all was well
kOfxStatReplyDefault, the action was ignored, but all was well anyway
kOfxStatErrMemory, in which case this may be called again after a memory purge
kOfxStatFailed, something went wrong, but no error code appropriate, the plug-in should to post a message if possible and the host should not attempt to run the plug-in in OpenGL render mode.

Typedefs

typedef struct OfxImageEffectOpenGLRenderSuiteV1 OfxImageEffectOpenGLRenderSuiteV1: OFX suite that provides image to texture conversion for OpenGL processing.

group CudaRender

Version: CUDA rendering was added in version 1.5.

Defines

kOfxImageEffectPropCudaRenderSupported

Indicates whether a host or plug-in can support CUDA render.

Valid Values -
- “false” - the host or plug-in does not support CUDA render
- ”true” - the host or plug-in can support CUDA render

kOfxImageEffectPropCudaEnabled

Indicates that a plug-in SHOULD use CUDA render in the current action.

If a plug-in and host have both set kOfxImageEffectPropCudaRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as CUDA memory pointers.

Valid Values
- 0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
- 1 indicates that the kOfxImagePropData of each image of each clip is a CUDA memory pointer.

kOfxImageEffectPropCudaStreamSupported

Indicates whether a host or plug-in can support CUDA streams.

Valid Values -
- “false” - in which case the host or plug-in does not support CUDA streams
- ”true” - which means a host or plug-in can support CUDA streams

kOfxImageEffectPropCudaStream

The CUDA stream to be used for rendering.

This property will only be set if the host and plug-in both support CUDA streams.

If set:

this property contains a pointer to the stream of CUDA render (cudaStream_t). In order to use it, reinterpret_cast<cudaStream_t>(pointer) is needed.
the plug-in SHOULD ensure that its render action enqueues any asynchronous CUDA operations onto the supplied queue.
the plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action, and SHOULD NOT call cudaDeviceSynchronize() at any time.

If not set:

the plug-in SHOULD ensure that any asynchronous operations it enqueues have completed before returning from the render action.

group MetalRender

Version: Metal rendering was added in version 1.5.

Defines

kOfxImageEffectPropMetalRenderSupported

Indicates whether a host or plug-in can support Metal render.

Valid Values -
- “false” - the host or plug-in does not support Metal render
- ”true” - the host or plug-in can support Metal render

kOfxImageEffectPropMetalEnabled

Indicates that a plug-in SHOULD use Metal render in the current action.

If a plug-in and host have both set kOfxImageEffectPropMetalRenderSupported=”true” then the host MAY set this property to indicate that it is passing images as Metal buffers.

Valid Values
- 0 indicates that the kOfxImagePropData of each image of each clip is a CPU memory pointer.
- 1 indicates that the kOfxImagePropData of each image of each clip is a Metal id<MTLBuffer>.

kOfxImageEffectPropMetalCommandQueue

The command queue of Metal render.

This property contains a pointer to the command queue to be used for Metal rendering (id<MTLCommandQueue>). In order to use it, reinterpret_cast<id<MTLCommandQueue>>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous Metal operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

group OpenClRender

Version: OpenCL rendering was added in version 1.5.

Defines

kOfxImageEffectPropOpenCLRenderSupported

Indicates whether a host or plug-in can support OpenCL Buffers render.

Valid Values -
- “false” - the host or plug-in does not support OpenCL Buffers render
- ”true” - the host or plug-in can support OpenCL Buffers render

kOfxImageEffectPropOpenCLSupported

Indicates whether a host or plug-in can support OpenCL Images render.

Valid Values -
- “false” - in which case the host or plug-in does not support OpenCL Images render
- ”true” - which means a host or plug-in can support OpenCL Images render

kOfxImageEffectPropOpenCLEnabled

Indicates that a plug-in SHOULD use OpenCL render in the current action.

If a plug-in and host have both set kOfxImageEffectPropOpenCLRenderSupported=”true” or have both set kOfxImageEffectPropOpenCLSupported=”true” then the host MAY set this property to indicate that it is passing images as OpenCL Buffers or Images.

When rendering using OpenCL Buffers, the cl_mem of the buffers are retrieved using kOfxImagePropData. When rendering using OpenCL Images, the cl_mem of the images are retrieved using kOfxImageEffectPropOpenCLImage. If both kOfxImageEffectPropOpenCLSupported (Buffers) and kOfxImageEffectPropOpenCLRenderSupported (Images) are enabled by the plug-in, it should use kOfxImageEffectPropOpenCLImage to determine which is being used by the host.

Valid Values
- 0 indicates that a plug-in SHOULD use OpenCL render in the render action
- 1 indicates that a plug-in SHOULD NOT use OpenCL render in the render action

kOfxImageEffectPropOpenCLCommandQueue

Indicates the OpenCL command queue that should be used for rendering.

This property contains a pointer to the command queue to be used for OpenCL rendering (cl_command_queue). In order to use it, reinterpret_cast<cl_command_queue>(pointer) is needed.

The plug-in SHOULD ensure that its render action enqueues any asynchronous OpenCL operations onto the supplied queue.

The plug-in SHOULD NOT wait for final asynchronous operations to complete before returning from the render action.

kOfxImageEffectPropOpenCLImage

Indicates the image handle of an image supplied as an OpenCL Image by the host.

This value should be cast to a cl_mem and used as the image handle when performing OpenCL Images operations. The property should be used (not kOfxImagePropData) when rendering with OpenCL Images (kOfxImageEffectPropOpenCLSupported), and should be used to determine whether Images or Buffers should be used if a plug-in supports both kOfxImageEffectPropOpenCLSupported and kOfxImageEffectPropOpenCLRenderSupported. Note: the kOfxImagePropRowBytes property is not required to be set by the host, since OpenCL Images do not have the concept of row bytes.

kOfxOpenCLProgramSuite

Typedefs

typedef struct OfxOpenCLProgramSuiteV1 OfxOpenCLProgramSuiteV1

OFX suite that allows a plug-in to get OpenCL programs compiled.

This is an optional suite the host can provide for building OpenCL programs for the plug-in, as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also cache program binaries for performance (however, if the source of the program or the OpenCL environment changes, the host must recompile so some mechanism such as hashing must be used).

group ImageEffectActions: These are the list of actions passed to an image effect plugin’s main function. For more details on how to deal with actions, see Image Effect Actions.

group ImageEffectPropDefines: These are the list of properties used by the Image Effects API.

group StatusCodesImageEffect

These are status codes returned by functions in the OfxImageEffectSuite and Image Effect plugin functions.

They range from 1000 until 1999

group PropertiesInteract: These are the list of properties used by the Interact API documented in CustomInteractionPage.

group InteractActions: These are the list of actions passed to an interact’s entry point function. For more details on how to deal with actions, see Interact Actions.

group KeySyms

These keysymbols are used as values by the kOfxPropKeySym property to indicate the value of a key that has been pressed. A corresponding kOfxPropKeyString property is also set to contain the unicode value of the key (if it has one).

The special keysym kOfxKey_Unknown is used to set the kOfxPropKeySym property in cases where the key has a UTF8 value which is not supported by the symbols below.

group ParamTypeDefines: These strings are used to identify the type of the parameter when it is defined, they are also on the kOfxParamPropType in any parameter instance.

group ParamPropDefines: These are the list of properties used by the parameters suite.

group ErrorCodes

page ofxOpenGLRender

Introduction

The OfxOpenGLRenderSuite allows image effects to use OpenGL commands (hopefully backed by a GPU) to accelerate rendering of their outputs. The basic scheme is simple….

An effect indicates it wants to use OpenGL acceleration by setting the kOfxImageEffectPropOpenGLRenderSupported flag on its descriptor
A host indicates it supports OpenGL acceleration by setting kOfxImageEffectPropOpenGLRenderSupported on its descriptor
In an effect’s kOfxImageEffectActionGetClipPreferences action, an effect indicates what clips it will be loading images from onto the GPU’s memory during an effect’s kOfxImageEffectActionRender action.

OpenGL House Keeping

If a host supports OpenGL rendering then it flags this with the string property kOfxImageEffectPropOpenGLRenderSupported on its descriptor property set. Effects that cannot run without OpenGL support should examine this in kOfxActionDescribe action and return a kOfxStatErrMissingHostFeature status flag if it is not set to “true”.

Effects flag to a host that they support OpenGL rendering by setting the string property kOfxImageEffectPropOpenGLRenderSupported on their effect descriptor during the kOfxActionDescribe action. Effects can work in three ways….

purely on CPUs without any OpenGL support at all, in which case they should set kOfxImageEffectPropOpenGLRenderSupported to be “false” (the default),
on CPUs but with optional OpenGL support, in which case they should set kOfxImageEffectPropOpenGLRenderSupported to be “true”,
only with OpenGL support, in which case they should set kOfxImageEffectPropOpenGLRenderSupported to be “needed”.

Hosts can examine this flag and respond to it appropriately.

Effects can use OpenGL accelerated rendering during the following action…

kOfxImageEffectActionRender

If an effect has indicated that it optionally supports OpenGL acceleration, it should check the property kOfxImageEffectPropOpenGLEnabled passed as an in argument to the following actions,

If this property is set to 0, then it should not attempt to use any calls to the OpenGL suite or OpenGL calls whilst rendering.

Getting Images as Textures

An effect could fetch an image into memory from a host via the standard Image Effect suite “clipGetImage” call, then create an OpenGL texture from that. However as several buffer copies and various other bits of house keeping may need to happen to do this, it is more efficient for a host to create the texture directly.

The OfxOpenGLRenderSuiteV1::clipLoadTexture function does this. The arguments and semantics are similar to the OfxImageEffectSuiteV2::clipGetImage function, with a few minor changes.

The effect is passed back a property handle describing the texture. Once the texture is finished with, this should be disposed of via the OfxOpenGLRenderSuiteV1::clipFreeTexture function, which will also delete the associated OpenGL texture (for source clips).

The returned handle has a set of properties on it, analogous to the properties returned on the image handle by OfxImageEffectSuiteV2::clipGetImage. These are:

The main difference between this and an image handle is that the kOfxImagePropData property is replaced by the kOfxImageEffectPropOpenGLTextureIndex property. This integer property should be cast to a GLuint and is the index to use for the OpenGL texture. Next to texture handle the texture target enumerator is given in kOfxImageEffectPropOpenGLTextureTarget

Note, because the image is being directly loaded into a texture by the host it need not obey the Clip Preferences action to remap the image to the pixel depth the effect requested.

Render Output Directly with OpenGL

Effects can use the graphics context as they see fit. They may be doing several render passes with fetch back from the card to main memory via ‘render to texture’ mechanisms interleaved with passes performed on the CPU. The effect must leave output on the graphics card in the provided output image texture buffer.

The host will create a default OpenGL viewport that is the size of the render window passed to the render action. The following code snippet shows how the viewport should be rooted at the bottom left of the output texture.

  // set up the OpenGL context for the render to texture
  ...

  // figure the size of the render window
  int dx = renderWindow.x2 - renderWindow.x1;
  int dy = renderWindow.y2 - renderWindow.y2;

  // setup the output viewport
  glViewport(0, 0, dx, dy);

Prior to calling the render action the host may also choose to bind the output texture as the current color buffer (render target), or they may defer doing this until clipLoadTexture is called for the output clip.

After this, it is completely up to the effect to choose what OpenGL operations to render with, including projections and so on.

OpenGL Current Context

The host is only required to make the OpenGL context current (e.g., using wglMakeCurrent, for Windows) during the following actions:

For the first 3 actions, Render through EndSequenceRender, the host is only required to set the OpenGL context if kOfxImageEffectPropOpenGLEnabled is set. In other words, a plug-in should not expect the OpenGL context to be current for other OFX calls, such as kOfxImageEffectActionDescribeInContext.

page ofxOpenCLRender

Introduction

The OpenCL extension enables plug-ins to use OpenCL commands (typically backed by a GPU) to accelerate rendering of their outputs. The basic scheme is simple….

an plug-in indicates it wants to use OpenCL acceleration by setting the kOfxImageEffectPropOpenCLSupported (Images) and/or kOfxImageEffectPropOpenCLRenderSupported (Buffers) flags on it’s descriptor.
a host indicates it supports OpenCL acceleration by setting kOfxImageEffectPropOpenCLSupported (Images) and/or kOfxImageEffectPropOpenCLRenderSupported (Buffers) on it’s descriptor.
the host decides when to use OpenCL, and sets the kOfxImageEffectPropOpenCLEnabled property on the BeginRender/Render/EndRender calls to indicate this.
when OpenCL Images are being used (kOfxImageEffectPropOpenCLSupported) the clip image property kOfxImageEffectPropOpenCLImage will be set and non-null.
when OpenCL Buffers are being used (kOfxImageEffectPropOpenCLRenderSupported) the clip image property kOfxImagePropData will be set and non-null.

Discovery and Enabling

If a host supports OpenCL rendering then it flags with the string property kOfxImageEffectPropOpenCLSupported (Images) and/or kOfxImageEffectPropOpenCLRenderSupported (Buffers) on its descriptor property set. Effects that cannot run without OpenCL support should examine this in kOfxActionDescribe action and return a kOfxStatErrMissingHostFeature status flag if it is not set to “true”.

Effects flag to a host that they support OpenCL rendering by setting the string property kOfxImageEffectPropOpenCLSupported (Images) and/or kOfxImageEffectPropOpenCLRenderSupported (Buffers) on their effect descriptor during the kOfxActionDescribe action. Effects can work in two ways….

purely on CPUs without any OpenCL support at all, in which case they should set kOfxImageEffectPropOpenCLSupported (Images) and kOfxImageEffectPropOpenCLRenderSupported (Buffers) to be “false” (the default),
on CPUs but with optional OpenCL support, in which case they should set kOfxImageEffectPropOpenCLSupported (Images) and/or kOfxImageEffectPropOpenCLRenderSupported (Buffers) to be “true”

Host may support just OpenCL Images, just OpenCL Buffers, or both, as indicated by which of these two properties they set “true”. Likewise plug-ins may support just OpenCL Images, just OpenCL Buffers, or both, as indicated by which of these two properties they set “true”. If both host and plug-in support both, it is up to the host which it uses. Typically, it will be based on what it uses natively (to avoid an extra copy operation). If a plug-in supports both, it must use kOfxImageEffectPropOpenCLImage to determine if Images or Buffers are being used for a given render action.

Effects can use OpenCL render only during the following action:

kOfxImageEffectActionRender

If a plug-in has indicated that it optionally supports OpenCL acceleration, it should check the property kOfxImageEffectPropOpenCLEnabled passed as an in argument to the following actions,

If this property is set to 0, then it must not attempt to use OpenCL while rendering. If this property is set to 1, then it must use OpenCL buffers or images while rendering.

If a call using OpenCL rendering fails, the host may re-attempt using CPU buffers instead, but this is not required, and might not be efficient.

OpenCL platform and device versions and feature support

Assume an in-order command queue. Do not assume a profiling command queue.

Effects should target OpenCL 1.1 API and OpenCL C kernel language support. Only minimum required features required in OpenCL 1.1 should be used (for example, see “5.3.2.1 Minimum List of Supported Image Formats” for the list of image types which can be expected to be supported across all devices). If you have specific requirements for features beyond these minimums, you will need to check the device (e.g., using clGetDeviceInfo with CL_DEVICE_EXTENSIONS) to see if your feature is available, and have a fallback if it’s not.

Temporary buffers and images should not be kept past the render action. A separate extension for host managed caching is in the works.

Do not retain OpenCL objects without a matching release within the render action.

Multiple OpenCL Devices

This is very important: The host may support multiple OpenCL devices. Therefore the plug-in should keep a separate set of kernels per OpenCL content (e.g., using a map). The OpenCL context can be found from the command queue using clGetCommandQueueInfo with CL_QUEUE_CONTEXT. Failure to do this will cause crashes or incorrect results when the host switches to another OpenCL device.

page deprecated

Member kOfxImageComponentYUVA: - removed in v1.4. Note, this has been deprecated in v1.3

Member kOfxImageEffectPropInAnalysis: - This feature has been deprecated - officially commented out v1.4.

Member kOfxInteractPropViewportSize: - V1.3: This property is the redundant and its use will be deprecated in future releases. V1.4: Removed

Member kOfxParamDoubleTypeNormalisedX: - V1.3: Deprecated in favour of ::OfxParamDoubleTypeX V1.4: Removed

Member kOfxParamDoubleTypeNormalisedXAbsolute: - V1.3: Deprecated in favour of ::OfxParamDoubleTypeXAbsolute V1.4: Removed

Member kOfxParamDoubleTypeNormalisedXY: - V1.3: Deprecated in favour of ::OfxParamDoubleTypeXY V1.4: Removed

Member kOfxParamDoubleTypeNormalisedXYAbsolute: - V1.3: Deprecated in favour of kOfxParamDoubleTypeXYAbsolute V1.4: Removed

Member kOfxParamDoubleTypeNormalisedY: - V1.3: Deprecated in favour of ::OfxParamDoubleTypeY V1.4: Removed

Member kOfxParamDoubleTypeNormalisedYAbsolute: - V1.3: Deprecated in favour of ::OfxParamDoubleTypeYAbsolute V1.4: Removed

Member kOfxParamPropPluginMayWrite: - v1.4: deprecated - to be removed in 1.5

Member OfxYUVAColourF: - Deprecated in 1.3, removed in 1.4

Member OfxYUVAColourS: - Deprecated in 1.3, removed in 1.4

page index: This page represents the automatically extracted HTML documentation of the source headers for the OFX Image Effect API. The documentation was extracted by doxygen (http://www.doxygen.org). A more complete reference manual is https://openfx.readthedocs.io .