<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>FreeFrame Open Video Plugin System Specification</title>
<style type="text/css">
a:link, a:visited, a:active {color:#0040A0;}
a:hover {TEXT-DECORATION:none; color:#0040A0;}
body, h1, h2, h3, h4, p, td, th {font-family:arial,sans-serif;font-size:10pt;}
h1 {font-size:20pt;}
h2 {font-size:16pt;}
h3 {font-size:12pt;}
h4 {font-size:10pt;}
</style>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head>
<body>
<center>
<h1>FreeFrame Open Video Plugin System Specification</h1>
<h2>Version 1.5 - 'FreeFrameGL'</h2>
</center>
<a href="#CHAPLibrary"><b>1. OS integration</b></a><br>
<a href="#CHAPConstants"><b>2. Basic types and constants</b></a><br>
<a href="#CHAPTypes"><b>3. Enumerated and derived types</b></a><br>
<a href="#CHAPStructures"><b>4. Structures</b></a><br>
<a href="#CHAPFunctions"><b>5. Functions</b></a><br>
<a href="#CHAPFunctionsGlobal"><b>5.1. Global functions</b></a><br>
<a href="#CHAPFunctionsInstance"><b>5.2. Instance specific functions</b></a><br>
<p> </p>
<p>
<b>Copyright (c) 2002-2007 <a href="http://www.freeframe.org" target="_blank">www.freeframe.org</a><br>
All rights reserved.</b>
</p>
<p>
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.
</p>
<p>
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
</p>
<ul type=disc>
<li>
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
</li>
<li>
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
</li>
<li>
Neither the name of FreeFrame nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
</li>
</ul>
<font face=courier>
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.
</font>
<p> </p>
<a name="CHAPLibrary"><hr><h2>1. OS integration</h2><hr>
</a>
<p>
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.
</p>
<p>
FreeFrame Plugins export a single function: <a href="#plugMain">plugMain</a>. 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.
<br>
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.
</p>
<hr>
<a name="plugMain">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>plugMain</h3></td>
<td valign=top>(unsigned integer functionCode, unsigned integer inputValue, unsigned integer instanceID)</td>
</tr></table>
</a>
<h4>Parameters:</h4>
<table border=0>
<tr>
<td><i>functionCode:</i></td>
<td>Tells the plugin which function is being called (see <a href="#functiontable">function table</a>)</td>
</tr>
<tr>
<td><i>inputValue:</i></td>
<td>
32-bit value or 32-bit pointer to some structure, depending on function
code.
</td>
</tr>
<tr>
<td><i>instanceID:</i></td>
<td>32-bit instance identifier. Only used for instance specific functions (see <a href="#functiontable">function table</a>)</td>
</tr>
</table>
<h4>Return value:</h4>
Depends on function code. See <a href="#functiontable">function table</a> for details.
<h4>Remarks:</h4>
<table border=0>
<tr>
<td>PLUGIN DEVELOPERS:</td>
<td>
You shouldn't need to change this function. This is the one and only function exposed by
the library containing the actual plugin.
</td>
</tr>
</table>
<p> </p>
<a name="CHAPConstants">
<hr><h2>2. Basic types and constants</h2><hr>
</a>
<p>
All numbers in this document are ordinary decimal numbers, expect if specified
otherwise.
</p>
<p>The following types are used:</p>
<p>
<table border=1>
<tr>
<td><b>Type</b></td>
<td><b>Range of type</b></td>
<td><b>Notes</b></td>
</tr>
<tr>
<td><b>32-bit unsigned integer</b></td>
<td>0 to 4294967295</td>
<td>-</td>
</tr>
<tr>
<td><b>32-bit pointer</b></td>
<td>0 to 4294967295</td>
<td>needs to be a valid memory location</td>
</tr>
<tr>
<td><b>32-bit IEEE float</b></td>
<td>1 sign bit, 8 bit exponent, 23 bit fraction</td>
<td>Smallest Non-Zero Values: + or - 1.4012985 × (10 ^ ?45)</td>
<td>Largest Non-Infinite Values: + or - 3.4028235 × (10 ^ 38)</td>
</tr>
<tr>
<a name="Float64"></a>
<td><b>64-bit IEEE float</b></td>
<td>1 sign bit, 11 bit exponent, 52 bit fraction</td>
<td>Smallest Non-Zero Values: + or - 5.0 × (10 ^ ?324)</td>
<td>Largest Non-Infinite Values: + or - 1.7976931348623157 × (10 ^ 308)</td>
</tr>
</table>
<p>The following constants are used as return values:
<a name="FF_FAIL"></a>
<a name="FF_SUCCESS"></a>
<a name="FF_TRUE"></a>
<a name="FF_FALSE"></a>
<a name="FF_SUPPORTED"></a>
<a name="FF_UNSUPPORTED"></a>
</p>
<table border=1>
<tr>
<td><b>FF_SUCCESS</b></td>
<td>0</td>
</tr>
<tr>
<td><b>FF_FAIL</b></td>
<td>(hex) FFFFFFFF</td>
</tr>
<tr>
<td><b>FF_TRUE</b></td>
<td>1</td>
</tr>
<tr>
<td><b>FF_FALSE</b></td>
<td>0</td>
</tr>
<tr>
<td><b>FF_SUPPORTED</b></td>
<td>1</td>
</tr>
<tr>
<td><b>FF_UNSUPPORTED</b></td>
<td>0</td>
</tr>
</table>
<h4>Remarks:</h4>
<ul type=disc>
<li>
In functions that return error codes any value other than 0 is assumed to be an
error code. These are to be defined in each function below. </li>
<li>
In functions that return a pointer, (hex) FFFFFFFF also represents a failure condition.</li>
</ul>
<p> </p>
<a name="CHAPTypes"><hr><h2>3. Enumerated and derived types</h2><hr>
</a>
<a name="InstanceIdentifier">
<table border=0 bgcolor="#E8E8E8">
<tr>
<td valign=top><h3>InstanceIdentifier</h3></td>
<td valign=top> (32-bit unsigned integer)</td>
</tr>
</table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>InstanceIdentifier:</i></td>
<td>
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.
</td>
</tr>
</table>
<hr>
<a name="NumParameters">
<table border=0 bgcolor="#E8E8E8">
<tr>
<td valign=top><h3>NumParameters</h3></td>
<td valign=top> (32-bit unsigned integer)
</td>
</tr>
</table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>NumParameters:</i></td>
<td>Specifies the number of parameters that the plugin implements.</td>
</tr>
</table>
<hr>
<a name="ParameterNumber"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterNumber</h3></td>
<td valign=top> (<a name="NumParameters">32-bit unsigned integer</a>)</td>
</tr></table>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterNumber:</i></td>
<td>Index of a parameter, starting at 0 for the first parameter.</td>
</tr>
</table>
<hr>
<a name="ParameterName">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterName</h3></td>
<td valign=top> (array of 16 1-byte ASCII characters, *not null terminated*)</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterName:</i></td>
<td>The name of the Parameter as it will be displayed by the host on the UI.</td>
</tr>
</table>
<hr>
<a name="ParameterValue">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterValue</h3></td>
<td valign=top> (32-bit float value OR 32-bit pointer)</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterValue:</i></td>
<td>Float value from 0-1 or pointer to null terminated string. (See remarks)</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
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.
<b>The Use of any values outside this range will result in hideous incompatibilities.</b>
The <a href="#ParameterDisplayValue"> ParameterDisplayValue</a> 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.
<br>
For text parameters, this 32-bit value represents a pointer to a null terminated
string.
</p>
<hr>
<a name="ParameterDefaultValue">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterDefaultValue</h3></td>
<td valign=top> (32-bit float value OR 32-bit pointer)</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterDefaultValue:</i></td>
<td>The initial default value for this parameter. 32-bit float value or 32-bit pointer to null terminated string. (See remarks)</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
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.
<br>
For text parameters, this 32-bit value represents a pointer to a null terminated
string.
</p>
<hr>
<a name="ParameterDisplayValue">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterDisplayValue</h3></td>
<td valign=top> (array of 16 1-byte ASCII characters, *not null
terminated*)</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterDisplayValue:</i></td>
<td>
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...
</td>
</tr>
</table>
<hr>
<a name="PluginCapsIndex"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>PluginCapsIndex</h3></td>
<td valign=top> (<a name="NumParameters">32-bit unsigned integer</a>)</td>
</tr></table>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>PluginCapsIndex:</i></td>
<td>
32-bit unsigned integer. Specifies certain capabilities of a plugin that the host may
want to enquire about.:<br>
0 = 16-bit 5-6-5 pixelformat support<br>
1 = 24-bit pixelformat support<br>
2 = 32-bit (or 24-bit 32-bit aligned) pixelformat support<br>
<br>
3 = Plugin supports <a href="#processFrameCopy">processFrameCopy</a> function<br>
<br>
4 = Plugin supports <a href="#processOpengl">processOpengl</a> function<br>
<br>
5 = Plugin supports <a href="#setTime">setTime</a> function<br>
<br>
Calls to these caps indexes are only meaningful if the plugin has reported
that it supports <a href="#processFrameCopy">processFrameCopy</a> or
<a href="#processOpengl">processOpengl</a>:<br>
10 = Minimum input frames<br>
11 = Maximum input frames<br>
<br>
Calls to this caps index are only meaningful if the plugin has reported
that it supports <a href="#processFrameCopy">processFrameCopy</a>:<br>
15 = Plugin optimized for copy or in-place processing
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
See <a href="#getPluginCaps">getPluginCaps</a> for more information about the usage
of this structure.
</p>
<p>
See <a href="#VideoInfoStruct">VideoInfoStruct</a> for more information about the
pixelformats.
</p>
<hr>
<a name="ParameterType"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ParameterType</h3></td>
<td valign=top> (<a name="NumParameters">32-bit unsigned integer</a>)</td>
</tr></table>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterType:</i></td>
<td>
32-bit unsigned integer. Tells the host what kind of data the
parameter is. Current meaningful values:<br>
<table border=0>
<tr>
<td><b>Value</b></td>
<td><b>Type</b></td>
<td><b>Description</b></td>
</tr>
<tr>
<td>0</td>
<td>boolean</td>
<td>0.0 defined as false and anything else defined as true - e.g. checkbox</td>
</tr>
<tr>
<td>1</td>
<td>event</td>
<td>
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. </td>
</tr>
<tr>
<td>2</td>
<td>red</td>
<td rowspan=3>
The 3 colors e.g. for a colorpicker </td>
</tr>
<tr>
<td>3</td>
<td>green</td>
</tr>
<tr>
<td>4</td>
<td>blue</td>
</tr>
<tr>
<td>5</td>
<td>xpos</td>
<td rowspan=2>
For x, y video interaction e.g. cursor - these define a position within the processed video frames.
</td>
</tr>
<tr>
<td>6</td>
<td>ypos</td>
</tr>
<tr>
<td>10</td>
<td>standard</td>
<td>A standard parameter representing an unspecified float value</td>
</tr>
<tr>
<td>11</td>
<td>alpha</td>
<td>Transparency value esp. for use in a 3 colour colourpicker + alpha </td>
</tr>
<tr>
<td>100</td>
<td>text</td>
<td>
A null terminated text input type - Note: only this type has a
different data type for the moment </td>
</tr>
</table>
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
The range of values permitted for all variables (except text) is strictly 0-1.<br><br>
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 <a href="#VideoInfoStruct">VideoInfoStruct</a>.
</p>
<hr>
<a name="InputChannel">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>InputChannel</h3></td>
<td valign=top> 32-bit unsigned integer</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>InputChannel:</i></td>
<td>
Input channel as relates to the use of multiple inputs in <a href="#processFrameCopy">processFrameCopy</a>
The first channel is 0.
</td>
</tr>
</table>
<hr>
<a name="InputStatus">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>InputStatus</h3></td>
<td valign=top> 32-bit unsigned integer</td>
</tr></table>
</a>
<h4>Definition:</h4>
<table border=0>
<tr>
<td valign=top><i>InputStatus:</i></td>
<td>
Status of input channels as relates to the use of multiple inputs in <a href="#processFrameCopy">processFrameCopy</a>.<br>
0 = Not in use<br>
1 = In Use
</td>
</tr>
</table>
<p> </p>
<a name="CHAPStructures">
<hr><h2>4. Structures</h2><hr>
</a>
<a name="PluginInfoStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>PluginInfoStruct</h3></td>
<td valign=top> (size = 32 bytes)</td>
</tr></table>
</a>
<pre>
PluginInfoStruct {
<b>APIMajorVersion:</b> 32-bit unsigned integer
<b>APIMinorVersion:</b> 32-bit unsigned integer
<b>PluginUniqueID:</b> 4 1-byte ASCII characters *not null terminated*
<b>PluginName:</b> 16 1-byte ASCII characters *not null terminated*
<b>PluginType:</b> 32-bit unsigned integer
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>APIMajorVersion:</i></td>
<td>Represents number before decimal point in version numbers</td>
</tr>
<tr>
<td valign=top><i>APIMinorVersion:</i></td>
<td>Represents number after decimal point in version numbers</td>
</tr>
<tr>
<td valign=top><i>PluginUniqueID:</i></td>
<td>Unique ID for plugin</td>
</tr>
<tr>
<td valign=top><i>PluginName:</i></td>
<td>Name of plugin</td>
</tr>
<tr>
<td valign=top><i>PluginType:</i></td>
<td>
Current meaningful values:<br>
0 = effect<br>
1 = source<br>
(see remarks)
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
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.
</p>
<p>
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.
<br>
Example: for version 0.511, APIMajorVersion=0 and APIMinorVersion=511.
</p>
<hr>
<a name="VideoInfoStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>VideoInfoStruct</h3></td>
<td valign=top> (size = 16 bytes)</td>
</tr></table>
</a>
<pre>
VideoInfoStruct {
<b>FrameWidth:</b> 32-bit unsigned integer
<b>FrameHeight:</b> 32-bit unsigned integer
<b>BitDepth:</b> 32-bit unsigned integer
<b>Orientation:</b> 32-bit unsigned integer
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>FrameWidth:</i></td>
<td>Width of video frame in pixels</td>
</tr>
<tr>
<td valign=top><i>FrameHeight:</i></td>
<td>Height of video frame in pixels</td>
</tr>
<tr>
<td valign=top><i>BitDepth:</i></td>
<td>Current meaningful values:<br>
0 = 16-bit, 5-6-5 packed<br>
1 = 24-bit, packed (see remarks)<br>
2 = 32-bit, also suitable for 32-bit unsigned integer aligned 24-bit (see remarks).<br>
(see remarks)
</td>
</tr>
<tr>
<td valign=top><i>Orientation:</i></td>
<td>Current meaningful values:<br>
1 = origin at top left<br>
2 = origin at bottom left<br>
(see remarks)
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
This structure is provided by the host when a CPU plugin is instantiated.
When a GPU plugin is instantiated, it is passed a <a href="#FFGLViewportStruct">FFGLViewportStruct</a>. The remarks below
are not relevant to GPU plugins.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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).
</p>
<p>
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.<br>
For all target platforms, the unsigned integer representation of a 32-bit color is the same, namely (in C syntax):
<pre>
unsigned int color = (A << 24) + (R << 16) + (G << 8) + (B << 0);
</pre>
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.
</p>
<hr>
<a name="SetParameterStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>SetParameterStruct</h3></td>
<td valign=top> (size = 8 bytes)</td>
</tr></table>
</a>
<pre>
SetParameterStruct {
<b>ParameterNumber:</b> <a href="#ParameterNumber">ParameterNumber</a>
<b>NewParameterValue:</b> <a href="#ParameterValue">ParameterValue</a>
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>ParameterNumber:</i></td>
<td>Index of the parameter to set.</td>
</tr>
<tr>
<td valign=top><i>NewParameterValue:</i></td>
<td>
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 <a href="#ParameterValue">ParameterValue</a>).
</td>
</tr>
</table>
<hr>
<a name="PluginExtendedInfoStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>PluginExtendedInfoStruct</h3></td>
<td valign=top> (size = 24 bytes)</td>
</tr></table>
</a>
<pre>
PluginExtendedInfoStruct{
<b>PluginMajorVersion:</b> 32-bit unsigned integer
<b>PluginMinorVersion:</b> 32-bit unsigned integer
<b>Description:</b> 32-bit pointer to null terminated string
<b>About:</b> 32-bit pointer to null terminated string
<b>FreeFrameExtendedDataSize:</b> 32-bit unsigned integer
<b>FreeFrameExtendedDataBlock:</b> 32-bit pointer
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>PluginMajorVersion:</i></td>
<td>
Represents number before decimal point in version numbers.
</td>
</tr>
<tr>
<td valign=top><i>PluginMinorVersion:</i></td>
<td>
Represents number after decimal point in version numbers.
</td>
</tr>
<tr>
<td valign=top><i>Description:</i></td>
<td>
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!
</td>
</tr>
<tr>
<td valign=top><i>About:</i></td>
<td>
Author and license information. Pointer value can be 0
if not provided by plugin!
</td>
</tr>
<tr>
<td valign=top><i>FreeFrameExtendedDataSize:</i></td>
<td>
Size in bytes of the FreeFrameExtendedDataBlock - or 0 if not provided by plugin.
</td>
</tr>
<tr>
<td valign=top><i>FreeFrameExtendedDataBlock:</i></td>
<td>
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.
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
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
</p>
<hr>
<a name="ProcessFrameCopyStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ProcessFrameCopyStruct</h3></td>
<td valign=top> (size = 12 bytes)</td>
</tr></table>
</a>
<pre>
ProcessFrameCopyStruct{
<b>numInputFrames:</b> 32-bit unsigned integer
<b>ppInputFrames:</b> 32-bit pointer to array of pointers
<b>pOutputFrame:</b> 32-bit pointer
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>numInputFrames:</i></td>
<td>Number of input frames contained in ppInputFrames.</td>
</tr>
<tr>
<td valign=top><i>ppInputFrames:</i></td>
<td>A pointer to an array of pointers to input frames.</td>
</tr>
<tr>
<td valign=top><i>pOutputFrame:</i></td>
<td>
Pointer to output frame.
</td>
</tr>
</table>
<hr>
<a name="FFGLTextureStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>FFGLTextureStruct</h3></td>
<td valign=top> (size = 20 bytes)</td>
</tr></table>
</a>
<pre>
FFGLTextureStruct {
<b>Width:</b> 32-bit unsigned integer
<b>Height:</b> 32-bit unsigned integer
<b>HardwareWidth:</b> 32-bit unsigned integer
<b>HardwareHeight:</b> 32-bit unsigned integer
<b>Handle:</b> 32-bit unsigned integer (GLuint)
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>Width:</i></td>
<td>Width (in pixels) of video frame</td>
</tr>
<tr>
<td valign=top><i>Height:</i></td>
<td>Height (in pixels) of video frame</td>
</tr>
<tr>
<td valign=top><i>HardwareWidth:</i></td>
<td>Width (in pixels) of GPU texture storing the video frame</td>
</tr>
<tr>
<td valign=top><i>HardwareHeight:</i></td>
<td>Height (in pixels) of GPU texture storing the video frame</td>
</tr>
<tr>
<td valign=top><i>Handle:</i></td>
<td>The OpenGL texture handle, from glGenTextures, use with glBindTexture</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>Hosts must provide textures of type GL_TEXTURE_2D. GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_3D, etc, are NOT supported.
</p>
<hr>
<a name="FFGLViewportStruct" id="FFGLViewportStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>FFGLViewportStruct</h3></td>
<td valign=top> (size = 16 bytes)</td>
</tr></table>
</a>
<pre>
FFGLViewportStruct {
<b>X:</b> 32-bit unsigned integer
<b>Y:</b> 32-bit unsigned integer
<b>Width:</b> 32-bit unsigned integer
<b>Height:</b> 32-bit unsigned integer
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>X:</i></td>
<td>X-coordinate of the viewport's bottom left corner</td>
</tr>
<tr>
<td valign=top><i>Y:</i></td>
<td>Y-coordinate of the viewport's bottom left corner</td>
</tr>
<tr>
<td valign=top><i>Width:</i></td>
<td>Width of viewport</td>
</tr>
<tr>
<td valign=top><i>Height:</i></td>
<td>Height of viewport</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
This structure is provided by the host when a GPU plugin is instantiated.
When a CPU plugin is instantiated, it is passed a <a href="#VideoInfoStruct">VideoInfoStruct</a>. The remarks below
are not relevant to CPU plugins.
</p>
<p>
GPU plugins draw their output into the host's OpenGL viewport during calls to <a href="#processOpengl">processOpenGL</a>. 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.
</p>
<hr>
<a name="ProcessOpenGLStruct">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>ProcessOpenGLStruct</h3></td>
<td valign=top> (size = 12 bytes)</td>
</tr></table>
</a>
<pre>
ProcessOpenGLStruct {
<b>numInputTextures:</b> 32-bit unsigned integer
<b>ppInputTextures:</b> 32-bit pointer to array of pointers to <a href="#FFGLTextureStruct">FFGLTextureStruct</a>
<b>HostFBO:</b> 32-bit unsigned integer (GLuint)
}
</pre>
<h4>Fields:</h4>
<table border=0>
<tr>
<td valign=top><i>numInputTextures:</i></td>
<td>Number of input textures contained in ppInputTextures</td>
</tr>
<tr>
<td valign=top><i>ppInputTextures:</i></td>
<td>A pointer to an array of pointers to input textures</td>
</tr>
<tr>
<td valign=top><i>HostFBO:</i></td>
<td>32-bit unsigned integer (GLuint) see Remarks below </td>
</tr>
</table>
<h4>Remarks:</h4>
<p>Hosts must provide textures of type GL_TEXTURE_2D. GL_TEXTURE_RECTANGLE_EXT, GL_TEXTURE_3D, etc, are NOT supported.
<p>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.
<p>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.
<p>When a host calls ProcessOpenGL with no FBO active, it must pass a value of 0 in the 'HostFBO' field.
<br><br>
<a name="CHAPFunctions">
<hr><h2>5. Functions</h2><hr>
</a>
<p>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.</p>
<a name="functiontable">
<h3>Function Code Table</h3>
</a>
<h4>Global functions:</h4>
<table border=1>
<tr>
<td><b>Code</b></td>
<td><b>Function</b></td>
<td><b>Input value type</b></td>
<td><b>Output value type</b></td>
</tr>
<tr>
<td>0</td>
<td><a href="#getInfo">getInfo</a></td>
<td>none</td>
<td>Pointer to a <a href="#PluginInfoStruct">PluginInfoStruct</a></td>
</tr>
<tr>
<td>1</td>
<td><a href="#initialise">initialise</a></td>
<td>none</td>
<td>Success/error code</td>
</tr>
<tr>
<td>2</td>
<td><a href="#deInitialise">deInitialise</a></td>
<td>none</td>
<td>Success/error code</td>
</tr>
<tr>
<td>4</td>
<td><a href="#getNumParameters">getNumParameters</a></td>
<td>none</td>
<td><a href="#NumParameters">NumParameters</a></td>
</tr>
<tr>
<td>5</td>
<td><a href="#getParameterName">getParameterName</a></td>
<td><a href="#ParameterNumber">ParameterNumber</a></td>
<td>Pointer to <a href="#ParameterName">ParameterName</a></td>
</tr>
<tr>
<td>6</td>
<td><a href="#getParameterDefault">getParameterDefault</a></td>
<td><a href="#ParameterNumber">ParameterNumber</a></td>
<td><a href="#ParameterDefaultValue">ParameterDefaultValue</a></td>
</tr>
<tr>
<td>10</td>
<td><a href="#getPluginCaps">getPluginCaps</a></td>
<td><a href="#PluginCapsIndex">PluginCapsIndex</a></td>
<td>Supported/unsupported/value</td>
</tr>
<tr>
<td>13</td>
<td><a href="#getExtendedInfo">getExtendedInfo</a></td>
<td>none</td>
<td>Pointer to <a href="#PluginExtendedInfoStruct">PluginExtendedInfoStruct</a></td>
</tr>
<tr>
<td>15</td>
<td><a href="#getParameterType">getParameterType</a></td>
<td><a href="#ParameterNumber">ParameterNumber</a></td>
<td><a href="#ParameterType">ParameterType</a></td>
</tr>
</table>
<h4>Instance specific functions:</h4>
<table border=1>
<tr>
<td><b>Code</b></td>
<td><b>Function</b></td>
<td><b>Input value type</b></td>
<td><b>Output value type</b></td>
</tr>
<tr>
<td>3</td>
<td><a href="#processFrame">processFrame</a></td>
<td>Pointer to a frame of video</td>
<td>Success/error code</td>
</tr>
<tr>
<td>7</td>
<td><a href="#getParameterDisplay">getParameterDisplay</a></td>
<td><a href="#ParameterNumber">ParameterNumber</a></td>
<td>Pointer to <a href="#ParameterDisplayValue">ParameterDisplayValue</a></td>
</tr>
<tr>
<td>8</td>
<td><a href="#setParameter">setParameter</a></td>
<td>Pointer to <a href="#SetParameterStruct">SetParameterStruct</a></td>
<td>Success/error code</td>
</tr>
<tr>
<td>9</td>
<td><a href="#getParameter">getParameter</a></td>
<td><a href="#ParameterNumber">ParameterNumber</a></td>
<td><a href="#ParameterValue">ParameterValue</a></td>
</tr>
<tr>
<td>11</td>
<td><a href="#instantiate">instantiate</a></td>
<td>Pointer to <a href="#VideoInfoStruct">VideoInfoStruct</a></td>
<td><a href="#InstanceIdentifier">InstanceIdentifier</a></td>
</tr>
<tr>
<td>12</td>
<td><a href="#deInstantiate">deInstantiate</a></td>
<td>none</td>
<td>Success/error code</td>
</tr>
<tr>
<td>14</td>
<td><a href="#processFrameCopy">processFrameCopy</a></td>
<td>Pointer to <a href="#ProcessFrameCopyStruct">ProcessFrameCopyStruct</a></td>
<td>Success/error code</td>
</tr>
<tr>
<td>16</td>
<td><a href="#getInputStatus">getInputStatus</a></td>
<td><a href="#InputChannel">InputChannel</a></td>
<td><a href="#InputStatus">InputStatus</a></td>
</tr>
<tr>
<td>17</td>
<td><a href="#processOpengl">processOpengl</a></td>
<td>pointer to <a href="#ProcessOpenGLStruct">ProcessOpenGLStruct</a></td>
<td>Success/error code </td>
</tr>
<tr>
<td>18</td>
<td><a href="#instantiateGL">instantiateGL</a></td>
<td>pointer to <a href="#FFGLViewportStruct">FFGLViewportStruct</a></td>
<td>InstanceIdentifier</td>
</tr>
<tr>
<td>19</td>
<td><a href="#deInstantiateGL">deInstantiateGL</a></td>
<td>none</td>
<td>Success/error code</td>
</tr>
<tr>
<td>20</td>
<td><a href="#setTime">setTime</a></td>
<td>Pointer to 64-bit float representing time in seconds</td>
<td>Success/error code</td>
</tr>
</table>
<p> </p>
<a name="CHAPFunctionsGlobal">
<hr><h2>5.1. Global functions</h2><hr>
</a>
<a name="getInfo">
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getInfo</h3></td>
<td valign=top> (function code = 0)</td>
</tr></table>
</a>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
32-bit pointer to <A href="#PluginInfoStruct">PluginInfoStruct</a> if successful,
<a href="#FF_FAIL">FF_FAIL</a> otherwise.
<h4>Remarks:</h4>
<p>
Gets information about the plugin - version, unique id, short name and type (see
<a href="#PluginInfoStruct">PluginInfoStruct</a>).
<br>
This function should be identical in all future versions of the FreeFrame API.
</p>
<table border=0>
<tr>
<td valign=top>HOST:</td>
<td>
Call this function first to get version information.
The version defines the other function codes that are supported.
</td>
</tr>
</table>
<hr>
<a name="initialise"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>initialise</h3></td>
<td valign=top> (function code = 1)</td>
</tr></table>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
<a href="#FF_SUCCESS">FF_SUCCESS</a> if successful, <a href="#FF_FAIL">FF_FAIL</a> or
other error-codes if failed. (32-bit unsigned integer)
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>PLUGIN:</td>
<td>
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
<a href="#instantiate">
instantiate</a>.
</td>
</tr>
<tr>
<td valign=top>HOST:</td>
<td>
This function *must* return before a call to <a href="#instantiate">instantiate</a>.
</td>
</tr>
</table>
<hr>
<a name="deInitialise"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>deInitialise</h3></td>
<td valign=top> (function code = 2)</td>
</tr></table>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
<a href="#FF_SUCCESS">FF_SUCCESS</a> if successful, <a href="#FF_FAIL">FF_FAIL</a> or
other error-codes if failed. (32-bit unsigned integer)
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>PLUGIN:</td>
<td>Tidy up, deallocate memory</td>
</tr>
<tr>
<td valign=top>HOST:</td>
<td>This *must* be the last function called on the plugin</td>
</tr>
</table>
<hr>
<a name="getNumParameters"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getNumParameters</h3></td>
<td valign=top> (function code = 4)</td>
</tr></table>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
<a href="#NumParameters">NumParameters</a> indicating the number of parameters in plugin
or <a href="#FF_FAIL">FF_FAIL</a> on error.
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>PLUGIN:</td>
<td>
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.
</td>
</tr>
<tr>
<td valign=top>HOST:</td>
<td>
Host developers should try to implement at least the first 4 parameters.
8 is the recommended number to expose.
</td>
</tr>
</table>
<hr>
<a name="getParameterName"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getParameterName</h3></td>
<td valign=top> (function code = 5)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>index:</i></td>
<td>
<a href="#ParameterNumber">ParameterNumber</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
32-bit pointer to <a href="#ParameterName">ParameterName</a> (16 byte char array) containing the name of parameter specified by
index.
Returns <a href="#FF_FAIL">FF_FAIL</a> on error.
<hr>
<a name="getParameterDefault"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getParameterDefault</h3></td>
<td valign=top> (function code = 6)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>index:</i></td>
<td>
<a href="#ParameterNumber">ParameterNumber</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
<a href="#ParameterDefaultValue">ParameterDefaultValue</a> 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.
<br>
Returns <a href="#FF_FAIL">FF_FAIL</a> on error.
<hr>
<a name="getPluginCaps"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getPluginCaps</h3></td>
<td valign=top> (function code = 10)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>capsIndex:</i></td>
<td>
<a href="#PluginCapsIndex">PluginCapsIndex</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
32-bit unsigned integer<br><Br>
Use the table below to determine what value to return for each capability (see <a href="#PluginCapsIndex">PluginCapsIndex</a>).
<br><br>
<table border=1>
<tr>
<td valign=top><b>capsIndex value</b></td>
<td valign=top><b>capsIndex meaning</b></td>
<td valign=top><b>return values</b></td>
</tr>
<tr>
<td valign=top>0 (FF_CAP_16BITVIDEO)</td>
<td valign=top>16 bit video</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports 16 bit video<br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support 16 bit video
</td>
</tr>
<tr>
<td valign=top>1 (FF_CAP_24BITVIDEO)</td>
<td valign=top>24 bit video</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports 24 bit video<br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support 24 bit video
</td>
</tr>
<tr>
<td valign=top>2 (FF_CAP_32BITVIDEO)</td>
<td valign=top>32 bit video</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports 32 bit video<br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support 32 bit video
</td>
</tr>
<tr>
<td valign=top>3 (FF_CAP_PROCESSFRAMECOPY)</td>
<td valign=top><a href="#processFrameCopy">processFrameCopy</a> support</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports <a href="#processFrameCopy">processFrameCopy</a><br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support <a href="#processFrameCopy">processFrameCopy</a>
</td>
</tr>
<tr>
<td valign=top>4 (FF_CAP_PROCESSOPENGL)</td>
<td valign=top><a href="#processOpengl">processOpengl</a> support</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports <a href="#processOpengl">processOpengl</a><br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support <a href="#processOpengl">processOpengl</a>
</td>
</tr>
<tr>
<td valign=top>5 (FF_CAP_SETTIME)</td>
<td valign=top><a href="#setTime">setTime</a> support</td>
<td valign=top>
<a href="#FF_SUPPORTED">FF_SUPPORTED</a>: plugin supports <a href="#setTime">setTime</a><br>
<a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a>: plugin doesn't support <a href="#setTime">setTime</a>
</td>
</tr>
<tr>
<td valign=top>10 (FF_CAP_MINIMUMINPUTFRAMES)</td>
<td>Minimum input frames</td>
<td>Returns minimum number of input frames plugin requires or <a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a> if capability not supported.</td>
</tr>
<tr>
<td valign=top>11 (FF_CAP_MAXIMUMINPUTFRAMES)</td>
<td valign=top>Maximum input frames</td>
<td valign=top>Returns maximum number of input frames plugin can process or <a href="#FF_UNSUPPORTED">FF_UNSUPPORTED</a> if capability not supported.</td>
</tr>
<tr>
<td valign=top>15 (FF_CAP_COPYORINPLACE)</td>
<td valign=top>Plugin optimization</td>
<td valign=top>
Return value indicates whether plugin is optimized for Copy or InPlace processing.<br>
0 (FF_UNSUPPORTED) = no preference<br>
1 (FF_CAP_PREFER_INPLACE) = InPlace processing is faster<br>
2 (FF_CAP_PREFER_COPY) = Copy processing is faster<br>
3 (FF_CAP_PREFER_BOTH) = Both are optimized<br>
</td>
</tr>
</table>
<h4>Remarks:</h4>
<p>
Plugins must support either CPU or GPU processing, but not both. CPU processing involves repeated calls to <a href="#processFrame">processFrame</a> and/or
<a href="#processFrameCopy">processFrameCopy</a>. GPU processing involves repeated calls to <a href="#processOpengl">processOpenGL</a>.
<br><Br>
CPU plugins should return FF_UNSUPPORTED (0) for FF_CAP_PROCESSOPENGL.
<br><br>
GPU plugins should return FF_SUPPORTED (1) for FF_CAP_PROCESSOPENGL.<br><br>
GPU plugins should return FF_UNSUPPORTED (0) for FF_CAP_16BITVIDEO,
FF_CAP_24BITVIDEO, FF_CAP_32BITVIDEO, FF_CAP_PROCESSFRAMECOPY, and FF_CAP_COPYORINPLACE.
<br><br>
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.
<br><br>
CPU PLUGIN/HOST BIT DEPTH<br>
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.
<hr>
<a name="getExtendedInfo"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getExtendedInfo</h3></td>
<td valign=top> (function code = 13)</td>
</tr></table>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
32-bit pointer to <a href="#PluginExtendedInfoStruct">PluginExtendedInfoStruct</a> or
<a href="#FF_FAIL">FF_FAIL</a> on error.
<hr>
<a name="getParameterType"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getParameterType</h3></td>
<td valign=top> (function code = 15)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>index:</i></td>
<td>
<a href="#ParameterNumber">ParameterNumber</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
<a href="#ParameterType">ParameterType</a> value which tells the host what kind of data the
parameter index is.<br>
Returns <a href="#FF_FAIL">FF_FAIL</a> on error.
<h4>Remarks:</h4>
<p>
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.
</p>
<p> </p>
<a name="CHAPFunctionsInstance">
<hr><h2>5.2. Instance specific functions</h2><hr>
</a>
<a name="processFrame"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>processFrame</h3></td>
<td valign=top> (function code = 3, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>pFrame:</i></td>
<td>
32-bit pointer to byte array containing frame of video.
</td>
</tr>
</table>
<h4>Return value:</h4>
<a href="#FF_SUCCESS">FF_SUCCESS</a> if successful, <a href="#FF_FAIL">FF_FAIL</a> if
failed. (32-bit unsigned integer)
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>Process a frame of video 'in place'. This is also the basic
frameport for source plugins.</td>
</tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>Do not implement this function, return FF_FAIL.</td>
</tr>
<tr>
<td valign=top>HOST:</td>
<td>pFrame needs to be a valid pointer throughout this call as the plugin processes
the frame 'in place'.
</td>
</tr>
</table>
<hr>
<a name="getParameterDisplay"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getParameterDisplay</h3></td>
<td valign=top> (function code = 7, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>index:</i></td>
<td>
<a href="#ParameterNumber">ParameterNumber</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
Pointer to <a href="#ParameterDisplayValue">ParameterDisplayValue</a> containing
a string to display as the value of parameter index.
<br>
Returns <a href="#FF_FAIL">FF_FAIL</a> if failed.
<hr>
<a name="setParameter"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>setParameter</h3></td>
<td valign=top> (function code = 8, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>setParam:</i></td>
<td>
Pointer to <a href="#SetParameterStruct">SetParameterStruct</a>.
</td>
</tr>
</table>
<h4>Return value:</h4>
Returns <a href="#FF_SUCCESS">FF_SUCCESS</a> if successful or <a href="#FF_FAIL">FF_FAIL</a> if failed
<h4>Remarks:</h4>
<p>
Sets the value of a parameter.
</p>
<table border=0>
<tr>
<td valign=top>PLUGIN:</td>
<td>
A plugin shouldn't change parameter values by itself. All
parameters are set by the plugin host through this function.
</td>
</tr>
</table>
<hr>
<a name="getParameter"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getParameter</h3></td>
<td valign=top> (function code = 9, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>index:</i></td>
<td>
<a href="#ParameterNumber">ParameterNumber</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
A <a href="#ParameterValue">ParameterValue</a> or <a href="#FF_FAIL">FF_FAIL</a> on error.
<h4>Remarks:</h4>
<p>
Returns value of a parameter. Note that the return value has different interpretations,
depending on the type of the parameter (see <a href="#ParameterValue">ParameterValue</a>).
</p>
<hr>
<a name="instantiate"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>instantiate</h3></td>
<td valign=top> (function code = 11, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>videoInfo:</i></td>
<td>
32-bit pointer to <a href="#VideoinfoStruct">VideoInfoStruct</a>.
</td>
</tr>
</table>
<h4>Return value:</h4>
An <a href="#InstanceIdentifier">InstanceIdentifier</a> for the newly instantiated
effect. Will be used as instanceID for future function calls.<br>
Returns <a href="#FF_FAIL">FF_FAIL</a> on error.
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>
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.
<br><br>
Make a local copy of the <a href="#VideoInfoStruct">VideoInfoStruct</a> 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.<br><br>
</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>
Do not implement this function, return FF_FAIL. GPU plugins have their own <a href="#instantiateGL">instantiateGL</a> function.<br><br><br>
</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>HOST:</td>
<td>
This function *must* return before a call to processFrame. The <a href="#InstanceIdentifier">InstanceIdentifier</a>
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.
<br><br>
Ensure that the pointer to <a href="#VideoInfoStruct">VideoInfoStruct</a> remains valid until the function returns.
</td>
</tr>
</table>
<hr>
<a name="deInstantiate"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>deInstantiate</h3></td>
<td valign=top> (function code = 12, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<i>none</i>
<h4>Return value:</h4>
Returns <a href="#FF_SUCCESS">FF_SUCCESS</a> if successful or <a href="#FF_FAIL">FF_FAIL</a> if failed.
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>
Tidy up, deallocate memory. All memory associated with the instance being deinstantiated must be freed
here.
</td>
</tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>
Do not implement this function, return FF_FAIL. GPU plugins have their own <a href="#deInstantiateGL">deInstantiateGL</a> function.
</td>
</tr>
<tr>
<td valign=top>HOST:</td>
<td>
This function must be called to close an instance of the plugin.
All instances should be closed before <a href="#deInitialise">deInitialising</a> the plugin!
</td>
</tr>
</table>
<hr>
<a name="processFrameCopy"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>processFrameCopy</h3></td>
<td valign=top> (function code = 14, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>copyStruct:</i></td>
<td>
32-bit pointer to <a href="#ProcessFrameCopyStruct">ProcessFrameCopyStruct</a>
</td>
</tr>
</table>
<h4>Return value:</h4>
Returns <a href="#FF_SUCCESS">FF_SUCCESS</a> if successful or <a href="#FF_FAIL">FF_FAIL</a> if failed.
<h4>Remarks:</h4>
<p>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>
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 <a href="#getPluginCaps">getPluginCaps</a>.
CPU source plugins should not support processFrameCopy as they do not require input frames.<br><br>
Plugins do not have to support processFrameCopy, but they must support the <a href="#processFrame">processFrame</a> (in-place) method of
processing. Support for processFrameCopy should be indicated in <a href="#getPluginCaps">getPluginCaps</a>.
<br><br>The plugin can also define (via <a href="#getPluginCaps">getPluginCaps</a>) which of processFrameCopy or <a href="#processFrame">processFrame</a> should be used for optimal performance.<br><br>
</td>
</tr>
<tr><td><br></td></tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>
Do not implement this function, return FF_FAIL;
</td>
</tr>
</table>
<hr>
<a name="getInputStatus"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>getInputStatus</h3></td>
<td valign=top> (function code = 16, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>channel:</i></td>
<td>
<a href="#InputChannel">InputChannel</a> value.
</td>
</tr>
</table>
<h4>Return value:</h4>
Returns an <a href="#InputStatus">InputStatus</a> value describing the status of
channel.
<h4>Remarks:</h4>
<p>
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.
</p>
<table border=0>
<tr>
<td valign=top>HOST:</td>
<td>
A host may only call this function for channels in this range:<br>
'Minimum input frames' <= channel < 'Maximum input frames' (see <a href="#getPluginCaps">getPluginCaps</a>).<br>
One should assume that all channels < 'Minimum input frames' are always in use.
</td>
</tr>
</table>
<hr>
<a name="processOpengl"></a>
<table border=0 bgcolor="#E8E8E8">
<tr>
<td valign=top><h3>processOpengl</h3></td>
<td valign=top> (function code = 17, needs valid instanceID!)</td>
</tr>
</table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>pProcessOpenGLStruct:</i></td>
<td> pointer to <a href="#ProcessOpenGLStruct">ProcessOpenGLStruct</a> structure. </td>
</tr>
</table>
<h4>Return value:</h4>
<a href="#FF_SUCCESS">FF_SUCCESS</a> if successful, <a href="#FF_FAIL">FF_FAIL</a> if
failed. (32-bit unsigned integer)
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>Do not implement this function, return FF_FAIL.<br><br><br></td>
</tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>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:
<ul>
<li>
If a plugin uses its own EXT_framebuffer_object ("FBO") for internal rendering, the plugin must restore the host's FBO binding using the HostFBO field from <a href="#ProcessOpenGLStruct">processOpenGLStruct</a> by calling glBindFramebufferEXT(GL_FRAMEBUFFER_EXT, HostFBO) .
<br><br>
</li>
<li>
If a plugin changes the OpenGL viewport state for any reason, it must restore the host's viewport (provided in the call to <a href="#instantiateGL">instantiateGL</a>).
<br><br>
</li>
<li>More exceptions may be added in the future as necessary<br><br></li>
<li>
Official documentation on "default" OpenGL states can be found here:<br>
<a href="http://www.opengl.org/documentation/specs" target="_blank">
http://www.opengl.org/documentation/specs</a> and <br>
<a href="http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/get.html" target="_blank">
http://www.opengl.org/documentation/specs/man_pages/hardcopy/GL/html/gl/get.html</a>
</li>
</ul></td>
</tr>
<tr>
<td valign=top>GPU HOST:</td>
<td>
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.
</td>
</tr>
</table>
<hr>
<a name="instantiateGL" id="instantiateGL"></a>
<table border=0 bgcolor="#E8E8E8">
<tr>
<td valign=top><h3>instantiateGL</h3></td>
<td valign=top> (function code = 18, needs valid instanceID!)</td>
</tr>
</table>
<p>#define FF_INSTANTIATEGL 18</p>
<p>DWORD instantiateGL(const FFGLViewportStruct *pHostGLViewport)</p>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>pFFGLViewportStruct:</i></td>
<td> pointer to FFGLViewportStruct structure that defines the host's OpenGL viewport. </td>
</tr>
</table>
<h4>Return value:</h4>
An <a href="#InstanceIdentifier">InstanceIdentifier</a> for the newly instantiated
effect. Will be used as instanceID for future function calls.<br>
Returns <a href="#FF_FAIL">FF_FAIL</a> on error.
<h4>Remarks:</h4>
<table border=0>
<tr><td>CPU PLUGINS:</td>
<td>Do not implement this function, return FF_FAIL. CPU plugins have their own <a href="#instantiate">instantiate</a> function.</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td> 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 <a href="#FFGLViewportStruct">FFGLViewportStruct</a> pointer will become invalid after instantiateGL returns, so (if necessary) plugins should store a copy of the <a href="#FFGLViewportStruct">FFGLViewportStruct</a> for later use during calls to <a href="#processOpengl">processOpenGL</a>.
<br><br>
When the plugin returns from this function it must be ready to process a frame.
</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>GPU HOST:</td>
<td>
Hosts must ensure that a valid OpenGL context is active during this call so that plugins can allocate GPU resources. <br><br>
This function must return before the host makes any calls to processOpengl. The <a href="#InstanceIdentifier">InstanceIdentifier</a> 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.<br><br>
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.
</td>
</tr>
</table>
<hr>
<a name="deInstantiateGL" id="deInstantiateGL"></a>
<table border=0 bgcolor="#E8E8E8">
<tr>
<td valign=top><h3>deInstantiateGL</h3></td>
<td valign=top> (function code = 19, needs valid instanceID!)</td>
</tr>
</table>
<p>#define FF_DEINSTANTIATEGL 19</p>
<p>DWORD deInstantiateGL(void *instanceID)</p>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>pProcessOpenGLStruct:</i></td>
<td> pointer to ProcessOpenGLStruct structure. </td>
</tr>
</table>
<h4>Return value:</h4>
Returns <a href="#FF_SUCCESS">FF_SUCCESS</a> if successful or <a href="#FF_FAIL">FF_FAIL</a> if failed.
<h4>Remarks:</h4>
<table border=0>
<tr>
<td valign=top>CPU PLUGINS:</td>
<td>Do not implement this function, return FF_FAIL. CPU plugins have their own <a href="#deInstantiate">deInstantiate</a> function.</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>GPU PLUGINS:</td>
<td>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.</td>
</tr>
<tr><td colspan=2><br></td></tr>
<tr>
<td valign=top>GPU HOST:</td>
<td>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 <a href="#deInitialise">deInitialising</a> the plugin!
</td>
</tr>
</table>
<hr>
<a name="setTime"></a>
<table border=0 bgcolor="#E8E8E8"><tr>
<td valign=top><h3>setTime</h3></td>
<td valign=top> (function code = 20, needs valid instanceID!)</td>
</tr></table>
<h4>Input value:</h4>
<table border=0>
<tr>
<td><i>Time:</i></td>
<td>
Pointer to <a href="#Float64">64-bit floating point value</a> representing time in seconds.
</td>
</tr>
</table>
<h4>Return value:</h4>
Returns <a href="#FF_SUCCESS">FF_SUCCESS</a> if successful or <a href="#FF_FAIL">FF_FAIL</a> if failed
<h4>Remarks:</h4>
<p>
Plugins that support the setTime function should return FF_TRUE when asked for the FF_CAP_SETTIME capability in <a href="#getPluginCaps">getPluginCaps</a>.
<br><br>
Hosts must not call SetTime while any of the plugin's process functions are still executing.
</p>
</body>
</html>