FreeFrame Open Video Plugin System Specification

Copyright (c) 2002, 2003 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:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• 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.
• 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.

FreeFrame plugins are distributed and used as compiled shared objects (.so) in Linux, as Frameworks 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.

Parameters:

Return value:

Remarks:

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	-lots to +lots	1 sign bit, 8 bit exponent, 24 bit mantissa

 

The following constants are used as return values:

Remarks:

• In functions that return error codes any value other than 0 is assumed to be an error code. These are be defined in each function below.
• In functions that return a pointer, (hex) FFFFFFFF also represents a failure condition

Definition:

Definition:

Definition:

Definition:

Definition:

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.

Definition:

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.

Definition:

Definition:

Remarks:

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

See VideoInfoStruct for more information about the pixelformats.

Definition:

Remarks:

The range of values permitted for all variables (except text) is strictly 0-1. This also holds for xpos/ypos variables (where, for example, xpos=0 corresponds to a screen x-coordinate of 0, and xpos=1 corresponds to an actual x-coordinate of FrameWidth-1. See VideoInfoStruct).

Definition:

Definition:

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:

Remarks:

Plugins of PluginType effect are passed frames of video, which they then modify. Source plugins are simply passed a pointer where they paint frames of video. One example of a source plugin would by a visual synthesizer which uses the parameters to synthesize video.

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 {
  FrameWidth: 32-bit unsigned integer
  FrameHeight: 32-bit unsigned integer
  BitDepth: 32-bit unsigned integer
  Orientation: 32-bit unsigned integer
}

Fields:

Remarks:

All video data in FreeFrame is pixel ordered, so the R, G, B 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);

SetParameterStruct {
  ParameterNumber: ParameterNumber
  NewParameterValue: ParameterValue
}

Fields:

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:

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{
  numInputFrames: 32-bit unsigned integer
  ppInputFrames: 32-bit pointer to array of pointers
  pOutputFrame: 32-bit pointer
}

Fields:

Global functions:

Instance specific functions:

Input value:

Return value:

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.

Input value:

Return value:

Remarks:

Input value:

Return value:

Remarks:

Input value:

Return value:

Remarks:

Input value:

Return value:

Input value:

Return value:

Input value:

Return value:

Remarks:

Bitdepth format of the video:
The host asks the plugin if it is capable of its favorite bit depth, and uses that if it is available. If not the host may decide not to use the plugin and deinitialise it, or it may enquire again to see if a second choice format is supported.

Input value:

Return value:

Input value:

Return value:

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.

Input value:

Return value:

Remarks:

Input value:

Return value:

Input value:

Return value:

Remarks:

Sets the value of a parameter.

Input value:

Return value:

Remarks:

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

Input value:

Return value:

Remarks:

Input value:

Return value:

Remarks:

Input value:

Return value:

Remarks:

The ProcessFrameCopy function performs a source->dest buffer frame process in effects plugins.
It is capable of processing multiple input frames - getPluginCaps should be used to see how many input frames the plugin would like.

Input value:

Return value:

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.