FreeFrame Open Video Plugin System Specification

Version 1.5 - 'FreeFrameGL'

1. OS integration
2. Basic types and constants
3. Enumerated and derived types
4. Structures
5. Functions
    5.1. Global functions
    5.2. Instance specific functions

 

Copyright (c) 2002-2007 www.freeframe.org
All rights reserved.

This document is a functional specification for the FreeFrame application programmers interface (API). It is intended to be subject to the same license as the code supplied as examples of use of the FreeFrame API.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 


1. OS integration


FreeFrame plugins are distributed and used as compiled shared objects (.so) in Linux, as Bundles in Mac OS X and as Dynamic Link Libraries (.dll) in Windows.

FreeFrame Plugins export a single function: plugMain. This is passed 3 values: a 32-bit function code, a 32-bit input value and a 32-bit instance identifier. It returns a 32-bit output value.
The input values and output values have different types according to the function code. This may be implemented differently on different platforms in different languages, but the format of the values must be consistent.


plugMain

(unsigned integer functionCode, unsigned integer inputValue, unsigned integer instanceID)

Parameters:

functionCode: Tells the plugin which function is being called (see function table)
inputValue: 32-bit value or 32-bit pointer to some structure, depending on function code.
instanceID: 32-bit instance identifier. Only used for instance specific functions (see function table)

Return value:

Depends on function code. See function table for details.

Remarks:

PLUGIN DEVELOPERS: You shouldn't need to change this function. This is the one and only function exposed by the library containing the actual plugin.

 


2. Basic types and constants


All numbers in this document are ordinary decimal numbers, expect if specified otherwise.

The following types are used:

Type Range of type Notes
32-bit unsigned integer 0 to 4294967295 -
32-bit pointer 0 to 4294967295 needs to be a valid memory location
32-bit IEEE float 1 sign bit, 8 bit exponent, 23 bit fraction Smallest Non-Zero Values: + or - 1.4012985 × (10 ^ ?45) Largest Non-Infinite Values: + or - 3.4028235 × (10 ^ 38)
64-bit IEEE float 1 sign bit, 11 bit exponent, 52 bit fraction Smallest Non-Zero Values: + or - 5.0 × (10 ^ ?324) Largest Non-Infinite Values: + or - 1.7976931348623157 × (10 ^ 308)
 

The following constants are used as return values:

FF_SUCCESS 0
FF_FAIL (hex) FFFFFFFF
FF_TRUE 1
FF_FALSE 0
FF_SUPPORTED 1
FF_UNSUPPORTED 0

Remarks:

 


3. Enumerated and derived types


InstanceIdentifier

 (32-bit unsigned integer)

Definition:

InstanceIdentifier: Unique identifier for the instance of a plugin. For some plugins, this value might represent a pointer to a plugin-specific data structure containing the instance's current state. Or it could be an index to a table of all active instances of a plugin, or any other value that uniquely identifies an instance.

NumParameters

 (32-bit unsigned integer)

Definition:

NumParameters: Specifies the number of parameters that the plugin implements.

ParameterNumber

 (32-bit unsigned integer)

Definition:

ParameterNumber: Index of a parameter, starting at 0 for the first parameter.

ParameterName

 (array of 16 1-byte ASCII characters, *not null terminated*)

Definition:

ParameterName: The name of the Parameter as it will be displayed by the host on the UI.

ParameterValue

 (32-bit float value OR 32-bit pointer)

Definition:

ParameterValue: Float value from 0-1 or pointer to null terminated string. (See remarks)

Remarks:

Apart from text parameters, FreeFrame parameter values are always 32-bit floats, and the range of values permitted is STRICTLY 0-1 (0 <= ParameterValue <= 1). This allows faster processing and a good range of values over a standard range, so the host can run up sliders or similar for the plugin. The Use of any values outside this range will result in hideous incompatibilities. The ParameterDisplayValue can be used to display whatever actual values the plugin likes e.g. 0-255, 0-767, 1-256 or whatever. The plugin should translate the standard 0-1 float range into the values it needs for its processing.
For text parameters, this 32-bit value represents a pointer to a null terminated string.


ParameterDefaultValue

 (32-bit float value OR 32-bit pointer)

Definition:

ParameterDefaultValue: The initial default value for this parameter. 32-bit float value or 32-bit pointer to null terminated string. (See remarks)

Remarks:

Plugins should always specify default values. Sometimes a host may not implement all parameters on a plugin, so the plugin must use default values until told to do otherwise by the host. Apart from text parameters, FreeFrame parameter values are always 32-bit floats, and the range of values permitted is STRICTLY 0-1.
For text parameters, this 32-bit value represents a pointer to a null terminated string.


ParameterDisplayValue

 (array of 16 1-byte ASCII characters, *not null terminated*)

Definition:

ParameterDisplayValue: String representing the current display value of this parameter. The plugin can display whatever it likes here e.g. just the float, a rounded 0-100 '%' representation for the user, words representing states like 'on' / 'off', different effects that the one plugin can do etc...

PluginCapsIndex

 (32-bit unsigned integer)

Definition:

PluginCapsIndex: 32-bit unsigned integer. Specifies certain capabilities of a plugin that the host may want to enquire about.:
0 = 16-bit 5-6-5 pixelformat support
1 = 24-bit pixelformat support
2 = 32-bit (or 24-bit 32-bit aligned) pixelformat support
 
3 = Plugin supports processFrameCopy function
 
4 = Plugin supports processOpengl function
 
5 = Plugin supports setTime function
 
Calls to these caps indexes are only meaningful if the plugin has reported that it supports processFrameCopy or processOpengl:
10 = Minimum input frames
11 = Maximum input frames

Calls to this caps index are only meaningful if the plugin has reported that it supports processFrameCopy:
15 = Plugin optimized for copy or in-place processing

Remarks:

See getPluginCaps for more information about the usage of this structure.

See VideoInfoStruct for more information about the pixelformats.


ParameterType

 (32-bit unsigned integer)

Definition:

ParameterType: 32-bit unsigned integer. Tells the host what kind of data the parameter is. Current meaningful values:
Value Type Description
0 boolean 0.0 defined as false and anything else defined as true - e.g. checkbox
1 event Similar to boolean but for a momentary push button style trigger. 1.0 is set momentarily to denote a simple event - e.g. pushbutton / keystroke.
2 red The 3 colors e.g. for a colorpicker
3 green
4 blue
5 xpos For x, y video interaction e.g. cursor - these define a position within the processed video frames.
6 ypos
10 standard A standard parameter representing an unspecified float value
11 alpha Transparency value esp. for use in a 3 colour colourpicker + alpha
100 text A null terminated text input type - Note: only this type has a different data type for the moment

Remarks:

The range of values permitted for all variables (except text) is strictly 0-1.

For the xpos and ypos parameter types, GPU plugin coordinates (0,0) refer to the bottom left corner of the processed frame, and coordinates (1,1) refer to the upper right corner. CPU plugin coordinates (0,0) may be at the bottom left or top left, and (1,1) at the top right or bottom right, depending on the orientation defined in the VideoInfoStruct.


InputChannel

 32-bit unsigned integer

Definition:

InputChannel: Input channel as relates to the use of multiple inputs in processFrameCopy The first channel is 0.

InputStatus

 32-bit unsigned integer

Definition:

InputStatus: Status of input channels as relates to the use of multiple inputs in processFrameCopy.
0 = Not in use
1 = In Use

 


4. Structures


PluginInfoStruct

 (size = 32 bytes)
PluginInfoStruct {
  APIMajorVersion: 32-bit unsigned integer
  APIMinorVersion: 32-bit unsigned integer
  PluginUniqueID: 4 1-byte ASCII characters *not null terminated*
  PluginName: 16 1-byte ASCII characters *not null terminated*
  PluginType: 32-bit unsigned integer
}

Fields:

APIMajorVersion: Represents number before decimal point in version numbers
APIMinorVersion: Represents number after decimal point in version numbers
PluginUniqueID: Unique ID for plugin
PluginName: Name of plugin
PluginType: Current meaningful values:
0 = effect
1 = source
(see remarks)

Remarks:

Plugins of PluginType effect process one or more input frames to create an output frame. Source plugins create an output based only on the plugin parameters, and do not expect or use any input frames.

FreeFrame APIMinorVersion numbers should always have 3 digits - so divide the minor version number by 1000 and add the major version number to get the full version number.
Example: for version 0.511, APIMajorVersion=0 and APIMinorVersion=511.


VideoInfoStruct

 (size = 16 bytes)
VideoInfoStruct {
  FrameWidth: 32-bit unsigned integer
  FrameHeight: 32-bit unsigned integer
  BitDepth: 32-bit unsigned integer
  Orientation: 32-bit unsigned integer
}

Fields:

FrameWidth: Width of video frame in pixels
FrameHeight: Height of video frame in pixels
BitDepth: Current meaningful values:
0 = 16-bit, 5-6-5 packed
1 = 24-bit, packed (see remarks)
2 = 32-bit, also suitable for 32-bit unsigned integer aligned 24-bit (see remarks).
(see remarks)
Orientation: Current meaningful values:
1 = origin at top left
2 = origin at bottom left
(see remarks)

Remarks:

This structure is provided by the host when a CPU plugin is instantiated. When a GPU plugin is instantiated, it is passed a FFGLViewportStruct. The remarks below are not relevant to GPU plugins.

Video frames are provided to CPU plugins as large buffers of pixels. The Red, Green, Blue, and sometimes Alpha values of a single pixel are located at consecutive memory locations. A video buffer consists of FrameWidth x FrameHeight pixels.

Plugins using 32-bit as byte aligned 24-bit video should be careful not to overwrite the alpha (4th) byte of each pixel (e.g. by using it as a processing space) as this may be used soon by hosts with 32-bit video processing becoming more accessible.

If Orientation == 1 the first pixel at the pointer to the frame is the top left pixel. If Orientation == 2, it is the bottom left pixel. This is particularly important for text and live input (to avoid mirroring of the image).

The byte order of color values depends on the target platform (i.e. big-endian versus little-endian). For little-endian platforms (e.g. Intel PC), the byte order is BGRA for 32-bit and BGR for 24-bit colors. For big-endian machines (e.g. MAC), the byte order for 32-bit is ARGB and RGB for 24-bit.
For all target platforms, the unsigned integer representation of a 32-bit color is the same, namely (in C syntax):

unsigned int color = (A << 24) + (R << 16) + (G << 8) + (B << 0);
where A, R, G, B are the 8-bit color components. Plugin developers who aim for platform-independence should be aware of these differences and program their plugins accordingly.


SetParameterStruct

 (size = 8 bytes)
SetParameterStruct {
  ParameterNumber: ParameterNumber
  NewParameterValue: ParameterValue
}

Fields:

ParameterNumber: Index of the parameter to set.
NewParameterValue: New value for this parameter. For float parameters, this is a float from 0-1. For text parameters, this is a pointer to a null terminated string (see ParameterValue).

PluginExtendedInfoStruct

 (size = 24 bytes)
PluginExtendedInfoStruct{
  PluginMajorVersion: 32-bit unsigned integer
  PluginMinorVersion: 32-bit unsigned integer
  Description: 32-bit pointer to null terminated string
  About: 32-bit pointer to null terminated string
  FreeFrameExtendedDataSize: 32-bit unsigned integer
  FreeFrameExtendedDataBlock: 32-bit pointer
}

Fields:

PluginMajorVersion: Represents number before decimal point in version numbers.
PluginMinorVersion: Represents number after decimal point in version numbers.
Description: A description of the plugin - intended to be made available to the user in hosts supporting this function via the UI. Pointer value can be 0 if not provided by plugin!
About: Author and license information. Pointer value can be 0 if not provided by plugin!
FreeFrameExtendedDataSize: Size in bytes of the FreeFrameExtendedDataBlock - or 0 if not provided by plugin.
FreeFrameExtendedDataBlock: 32-bit pointer to a FreeFrame ExtendedDataBlock - this interface is not yet in use, but provided to allow the FreeFrame project to establish an extended data block format in the future. Please do not use until a data format has been agreed.

Remarks:

FreeFrame PluginMinorVersion numbers should always have 3 digits - so divide the minor version number by 1000 and add the major version number to get the full version number. Example: 0.751 APIMajorVersion=0, APIMinorVersion=751


ProcessFrameCopyStruct

 (size = 12 bytes)
ProcessFrameCopyStruct{
  numInputFrames: 32-bit unsigned integer
  ppInputFrames: 32-bit pointer to array of pointers
  pOutputFrame: 32-bit pointer
}

Fields:

numInputFrames: Number of input frames contained in ppInputFrames.
ppInputFrames: A pointer to an array of pointers to input frames.
pOutputFrame: Pointer to output frame.

FFGLTextureStruct

 (size = 20 bytes)
FFGLTextureStruct {
  Width: 32-bit unsigned integer
  Height: 32-bit unsigned integer
  HardwareWidth: 32-bit unsigned integer
  HardwareHeight: 32-bit unsigned integer
  Handle: 32-bit unsigned integer (GLuint)
}

Fields:

Width: Width (in pixels) of video frame
Height: Height (in pixels) of video frame
HardwareWidth: Width (in pixels) of GPU texture storing the video frame
HardwareHeight: Height (in pixels) of GPU texture storing the video frame
Handle: The OpenGL texture handle, from glGenTextures, use with glBindTexture

Remarks:

Hosts must provide textures of type GL_TEXTURE_2D. GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_3D, etc, are NOT supported.


FFGLViewportStruct

 (size = 16 bytes)
FFGLViewportStruct {
   X: 32-bit unsigned integer
   Y: 32-bit unsigned integer
   Width: 32-bit unsigned integer
   Height: 32-bit unsigned integer
}

Fields:

X: X-coordinate of the viewport's bottom left corner
Y: Y-coordinate of the viewport's bottom left corner
Width: Width of viewport
Height: Height of viewport

Remarks:

This structure is provided by the host when a GPU plugin is instantiated. When a CPU plugin is instantiated, it is passed a VideoInfoStruct. The remarks below are not relevant to CPU plugins.

GPU plugins draw their output into the host's OpenGL viewport during calls to processOpenGL. Plugins can expect that this viewport will not change during the lifetime of the plugin. If the host's viewport changes (perhaps because the user changed their output window size or output resolution), any loaded plugins must be deinstantiated and reinstantiated and provided with the new viewport information.


ProcessOpenGLStruct

 (size = 12 bytes)
ProcessOpenGLStruct {
   numInputTextures: 32-bit unsigned integer
   ppInputTextures: 32-bit pointer to array of pointers to FFGLTextureStruct
   HostFBO: 32-bit unsigned integer (GLuint)
}

Fields:

numInputTextures: Number of input textures contained in ppInputTextures
ppInputTextures: A pointer to an array of pointers to input textures
HostFBO: 32-bit unsigned integer (GLuint) see Remarks below

Remarks:

Hosts must provide textures of type GL_TEXTURE_2D. GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_3D, etc, are NOT supported.

Hosts will often wish to capture the output of a GPU plugin to an offscreen texture. Hosts and plugins *must* use the the EXT_framebuffer_object ("FBO") extension to do this. Use of any other methods (such as 'PBuffers') is not supported.

When a host calls ProcessOpenGL with an FBO active, the host must provide the handle to the FBO in the 'HostFBO' field. Plugins that use their own FBOs internally must restore the host's FBO with a call to glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, HostFBO) so that the host can successfully capture the output of the plugin.

When a host calls ProcessOpenGL with no FBO active, it must pass a value of 0 in the 'HostFBO' field.


5. Functions


Some functions are specific to an instance of a plugin, and thus require a valid InstanceID in the InstanceID field, others concern global parameters that are the same for all instances, and so do not require a valid InstanceID.

Function Code Table

Global functions:

Code Function Input value type Output value type
0 getInfo none Pointer to a PluginInfoStruct
1 initialise none Success/error code
2 deInitialise none Success/error code
4 getNumParameters none NumParameters
5 getParameterName ParameterNumber Pointer to ParameterName
6 getParameterDefault ParameterNumber ParameterDefaultValue
10 getPluginCaps PluginCapsIndex Supported/unsupported/value
13 getExtendedInfo none Pointer to PluginExtendedInfoStruct
15 getParameterType ParameterNumber ParameterType

Instance specific functions:

Code Function Input value type Output value type
3 processFrame Pointer to a frame of video Success/error code
7 getParameterDisplay ParameterNumber Pointer to ParameterDisplayValue
8 setParameter Pointer to SetParameterStruct Success/error code
9 getParameter ParameterNumber ParameterValue
11 instantiate Pointer to VideoInfoStruct InstanceIdentifier
12 deInstantiate none Success/error code
14 processFrameCopy Pointer to ProcessFrameCopyStruct Success/error code
16 getInputStatus InputChannel InputStatus
17 processOpengl pointer to ProcessOpenGLStruct Success/error code
18 instantiateGL pointer to FFGLViewportStruct InstanceIdentifier
19 deInstantiateGL none Success/error code
20 setTime Pointer to 64-bit float representing time in seconds Success/error code

 


5.1. Global functions


getInfo

 (function code = 0)

Input value:

none

Return value:

32-bit pointer to PluginInfoStruct if successful, FF_FAIL otherwise.

Remarks:

Gets information about the plugin - version, unique id, short name and type (see PluginInfoStruct).
This function should be identical in all future versions of the FreeFrame API.

HOST: Call this function first to get version information. The version defines the other function codes that are supported.

initialise

 (function code = 1)

Input value:

none

Return value:

FF_SUCCESS if successful, FF_FAIL or other error-codes if failed. (32-bit unsigned integer)

Remarks:

PLUGIN: Prepare the plug-in for processing. Set default values, allocate memory. When the plug-in returns from this function it must be ready to accept calls to instantiate.
HOST: This function *must* return before a call to instantiate.

deInitialise

 (function code = 2)

Input value:

none

Return value:

FF_SUCCESS if successful, FF_FAIL or other error-codes if failed. (32-bit unsigned integer)

Remarks:

PLUGIN: Tidy up, deallocate memory
HOST: This *must* be the last function called on the plugin

getNumParameters

 (function code = 4)

Input value:

none

Return value:

NumParameters indicating the number of parameters in plugin or FF_FAIL on error.

Remarks:

PLUGIN: Plugin developers should normally expect hosts to expose up to 8 parameters Some hosts may only expose 1 or 4 parameters, some may expose larger numbers. All parameters should have sensible defaults incase the user is unable to control them from the host.
HOST: Host developers should try to implement at least the first 4 parameters. 8 is the recommended number to expose.

getParameterName

 (function code = 5)

Input value:

index: ParameterNumber

Return value:

32-bit pointer to ParameterName (16 byte char array) containing the name of parameter specified by index. Returns FF_FAIL on error.

getParameterDefault

 (function code = 6)

Input value:

index: ParameterNumber

Return value:

ParameterDefaultValue indicating the default value of parameter specified by index. For float parameters, the return value is a 32-bit float (0<=value<=1). Return value for text parameters is a 32-bit pointer to a null terminated string.
Returns FF_FAIL on error.

getPluginCaps

 (function code = 10)

Input value:

capsIndex: PluginCapsIndex

Return value:

32-bit unsigned integer

Use the table below to determine what value to return for each capability (see PluginCapsIndex).

capsIndex value capsIndex meaning return values
0 (FF_CAP_16BITVIDEO) 16 bit video FF_SUPPORTED: plugin supports 16 bit video
FF_UNSUPPORTED: plugin doesn't support 16 bit video
1 (FF_CAP_24BITVIDEO) 24 bit video FF_SUPPORTED: plugin supports 24 bit video
FF_UNSUPPORTED: plugin doesn't support 24 bit video
2 (FF_CAP_32BITVIDEO) 32 bit video FF_SUPPORTED: plugin supports 32 bit video
FF_UNSUPPORTED: plugin doesn't support 32 bit video
3 (FF_CAP_PROCESSFRAMECOPY) processFrameCopy support FF_SUPPORTED: plugin supports processFrameCopy
FF_UNSUPPORTED: plugin doesn't support processFrameCopy
4 (FF_CAP_PROCESSOPENGL) processOpengl support FF_SUPPORTED: plugin supports processOpengl
FF_UNSUPPORTED: plugin doesn't support processOpengl
5 (FF_CAP_SETTIME) setTime support FF_SUPPORTED: plugin supports setTime
FF_UNSUPPORTED: plugin doesn't support setTime
10 (FF_CAP_MINIMUMINPUTFRAMES) Minimum input frames Returns minimum number of input frames plugin requires or FF_UNSUPPORTED if capability not supported.
11 (FF_CAP_MAXIMUMINPUTFRAMES) Maximum input frames Returns maximum number of input frames plugin can process or FF_UNSUPPORTED if capability not supported.
15 (FF_CAP_COPYORINPLACE) Plugin optimization Return value indicates whether plugin is optimized for Copy or InPlace processing.
0 (FF_UNSUPPORTED) = no preference
1 (FF_CAP_PREFER_INPLACE) = InPlace processing is faster
2 (FF_CAP_PREFER_COPY) = Copy processing is faster
3 (FF_CAP_PREFER_BOTH) = Both are optimized

Remarks:

Plugins must support either CPU or GPU processing, but not both. CPU processing involves repeated calls to processFrame and/or processFrameCopy. GPU processing involves repeated calls to processOpenGL.

CPU plugins should return FF_UNSUPPORTED (0) for FF_CAP_PROCESSOPENGL.

GPU plugins should return FF_SUPPORTED (1) for FF_CAP_PROCESSOPENGL.

GPU plugins should return FF_UNSUPPORTED (0) for FF_CAP_16BITVIDEO, FF_CAP_24BITVIDEO, FF_CAP_32BITVIDEO, FF_CAP_PROCESSFRAMECOPY, and FF_CAP_COPYORINPLACE.

FF_CAP_MINIMUMINPUTFRAMES, FF_CAP_MAXIMUMINPUTFRAMES, and FF_CAP_SETTIME apply to both CPU and GPU plugins, so all plugins should return appropriate values for these queries.

CPU PLUGIN/HOST BIT DEPTH
Typically a host program has a preferred bit depth that it uses to perform its operations, and it will ask the plugin if it supports that bit depth. If the plugin does not support it, the host may decide not to use the plugin and deinitialize it. If the host supports a 2nd or 3rd format, it may check with the plugin to see if those are supported, and use one of them instead.


getExtendedInfo

 (function code = 13)

Input value:

none

Return value:

32-bit pointer to PluginExtendedInfoStruct or FF_FAIL on error.

getParameterType

 (function code = 15)

Input value:

index: ParameterNumber

Return value:

ParameterType value which tells the host what kind of data the parameter index is.
Returns FF_FAIL on error.

Remarks:

Hosts may decide to present an appropriate visual interface depending on the parameter type. All FreeFrame data for the moment is passed as 32-bit floats from 0-1, except text data.

 


5.2. Instance specific functions


processFrame

 (function code = 3, needs valid instanceID!)

Input value:

pFrame: 32-bit pointer to byte array containing frame of video.

Return value:

FF_SUCCESS if successful, FF_FAIL if failed. (32-bit unsigned integer)

Remarks:

CPU PLUGINS: Process a frame of video 'in place'. This is also the basic frameport for source plugins.
GPU PLUGINS: Do not implement this function, return FF_FAIL.
HOST: pFrame needs to be a valid pointer throughout this call as the plugin processes the frame 'in place'.

getParameterDisplay

 (function code = 7, needs valid instanceID!)

Input value:

index: ParameterNumber

Return value:

Pointer to ParameterDisplayValue containing a string to display as the value of parameter index.
Returns FF_FAIL if failed.

setParameter

 (function code = 8, needs valid instanceID!)

Input value:

setParam: Pointer to SetParameterStruct.

Return value:

Returns FF_SUCCESS if successful or FF_FAIL if failed

Remarks:

Sets the value of a parameter.

PLUGIN: A plugin shouldn't change parameter values by itself. All parameters are set by the plugin host through this function.

getParameter

 (function code = 9, needs valid instanceID!)

Input value:

index: ParameterNumber

Return value:

A ParameterValue or FF_FAIL on error.

Remarks:

Returns value of a parameter. Note that the return value has different interpretations, depending on the type of the parameter (see ParameterValue).


instantiate

 (function code = 11, needs valid instanceID!)

Input value:

videoInfo: 32-bit pointer to VideoInfoStruct.

Return value:

An InstanceIdentifier for the newly instantiated effect. Will be used as instanceID for future function calls.
Returns FF_FAIL on error.

Remarks:

CPU PLUGINS: Prepare an instance of the plugin for processing. Set default values, allocate memory. When the plugin returns from this function it must be ready to process a frame.

Make a local copy of the VideoInfoStruct if necessary, the pointer may not be valid after the function returns. The instance identifier you provide to the host must be the unique identifier of this instance until a call to deinitialise.


GPU PLUGINS: Do not implement this function, return FF_FAIL. GPU plugins have their own instantiateGL function.



HOST: This function *must* return before a call to processFrame. The InstanceIdentifier provided by the plugin is your handle to this instance of the plugin. The host must keep this instance identifier, and provide it in all calls to the plugin regarding that instance.

Ensure that the pointer to VideoInfoStruct remains valid until the function returns.

deInstantiate

 (function code = 12, needs valid instanceID!)

Input value:

none

Return value:

Returns FF_SUCCESS if successful or FF_FAIL if failed.

Remarks:

CPU PLUGINS: Tidy up, deallocate memory. All memory associated with the instance being deinstantiated must be freed here.
GPU PLUGINS: Do not implement this function, return FF_FAIL. GPU plugins have their own deInstantiateGL function.
HOST: This function must be called to close an instance of the plugin. All instances should be closed before deInitialising the plugin!

processFrameCopy

 (function code = 14, needs valid instanceID!)

Input value:

copyStruct: 32-bit pointer to ProcessFrameCopyStruct

Return value:

Returns FF_SUCCESS if successful or FF_FAIL if failed.

Remarks:

CPU PLUGINS: The processFrameCopy function performs a source->dest buffer frame process in CPU effect plugins. Multiple input frames can be processed by processFrameCopy, so plugins should indicate the number of input frames they prefer with getPluginCaps. CPU source plugins should not support processFrameCopy as they do not require input frames.

Plugins do not have to support processFrameCopy, but they must support the processFrame (in-place) method of processing. Support for processFrameCopy should be indicated in getPluginCaps.

The plugin can also define (via getPluginCaps) which of processFrameCopy or processFrame should be used for optimal performance.


GPU PLUGINS: Do not implement this function, return FF_FAIL;


getInputStatus

 (function code = 16, needs valid instanceID!)

Input value:

channel: InputChannel value.

Return value:

Returns an InputStatus value describing the status of channel.

Remarks:

This function is provided to allow hosts to optimize the rendering of input frames. Due to user input a plugin may only plan to render certain input channels - this function allows hosts to ask the plugin which input channels it plans to render.

HOST: A host may only call this function for channels in this range:
'Minimum input frames' <= channel < 'Maximum input frames' (see getPluginCaps).
One should assume that all channels < 'Minimum input frames' are always in use.

processOpengl

 (function code = 17, needs valid instanceID!)

Input value:

pProcessOpenGLStruct: pointer to ProcessOpenGLStruct structure.

Return value:

FF_SUCCESS if successful, FF_FAIL if failed. (32-bit unsigned integer)

Remarks:

CPU PLUGINS: Do not implement this function, return FF_FAIL.


GPU PLUGINS: Before returning from ProcessOpenGL, plugins MUST RESTORE ANY CHANGED OPENGL STATES BACK TO THE DEFAULT OPENGL STATE as defined by the OpenGL spec - WITH THE FOLLOWING EXCEPTIONS:
GPU HOST: Hosts must provide textures of type GL_TEXTURE_2D. GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_3D, etc, are NOT supported. Hosts must ensure that OpenGL is in its default state when ProcessOpenGL is called - with the exceptions listed above.

instantiateGL

 (function code = 18, needs valid instanceID!)

#define FF_INSTANTIATEGL 18

DWORD instantiateGL(const FFGLViewportStruct *pHostGLViewport)

Input value:

pFFGLViewportStruct: pointer to FFGLViewportStruct structure that defines the host's OpenGL viewport.

Return value:

An InstanceIdentifier for the newly instantiated effect. Will be used as instanceID for future function calls.
Returns FF_FAIL on error.

Remarks:

CPU PLUGINS: Do not implement this function, return FF_FAIL. CPU plugins have their own instantiate function.

GPU PLUGINS: Prepare an instance of the plugin for processing. Set default values, allocate memory, GPU resources, textures, shader programs, etc. Plugins should expect the host's OpenGL viewport to remain valid for the lifetime of the plugin. The FFGLViewportStruct pointer will become invalid after instantiateGL returns, so (if necessary) plugins should store a copy of the FFGLViewportStruct for later use during calls to processOpenGL.

When the plugin returns from this function it must be ready to process a frame.

GPU HOST: Hosts must ensure that a valid OpenGL context is active during this call so that plugins can allocate GPU resources.

This function must return before the host makes any calls to processOpengl. The InstanceIdentifier provided by the plugin is your handle to this instance of the plugin. The host must keep this instance identifier, and provide it in all calls to the plugin regarding that instance.

If the host's viewport changes (perhaps because the user changed their output window size or output resolution), any loaded plugins affected by the change must be deinstantiated and reinstantiated and provided with the new viewport information.

deInstantiateGL

 (function code = 19, needs valid instanceID!)

#define FF_DEINSTANTIATEGL 19

DWORD deInstantiateGL(void *instanceID)

Input value:

pProcessOpenGLStruct: pointer to ProcessOpenGLStruct structure.

Return value:

Returns FF_SUCCESS if successful or FF_FAIL if failed.

Remarks:

CPU PLUGINS: Do not implement this function, return FF_FAIL. CPU plugins have their own deInstantiate function.

GPU PLUGINS: Tidy up, deallocate memory, deallocate GPU resources specific to this GL instance: textures, shader programs, etc. All memory associated with the instance being deinstantiated must be freed here. Plugins should release all GPU resources they've created for this instance.

GPU HOST: This function is called to close an instance of the plugin. Hosts must ensure a valid OpenGL context is active during this call so that plugins can free GPU resources. All instances should be closed before deInitialising the plugin!

setTime

 (function code = 20, needs valid instanceID!)

Input value:

Time: Pointer to 64-bit floating point value representing time in seconds.

Return value:

Returns FF_SUCCESS if successful or FF_FAIL if failed

Remarks:

Plugins that support the setTime function should return FF_TRUE when asked for the FF_CAP_SETTIME capability in getPluginCaps.

Hosts must not call SetTime while any of the plugin's process functions are still executing.