Language Binding API Deviations

The Flix Engine language bindings endeavor to remain as true as possible to the Flix Engine API. In certain cases, however, the C implementation does not transfer directly. This guide will provide an overview of the changes, both necessary and those done for the sake of convenience. Currently Flix Engine has support for Java, Perl, PHP and Python.

The main differences include:

A word on Java:
For better consistency with Java function call semantics, the Java bindings consist of three main wrapper classes, FlixEngine2, Codec and Filter. In addition to this, each enumeration becomes its own class. Javadoc documentation is provided to highlight these differences. If you chose to install the Java bindings, the Javadoc will be installed by default in:
/usr/local/src/flixmodules/flixjava/doc
Attention:
The language bindings need only be rebuilt should the CHANGELOG note changes to the interface, e.g., the addition of constants/functions. Without rebuilding, these new features will be unavailable and depending on the bindings being used will either generate a compile error or, in the case of constants, will return ON2_NOT_SUPP should they be used.

Flix Engine Handle Creation

When creating a handle to the Flix Engine one calls Flix2_Create() or Flix2_CreateEx() with a pointer to a FLIX2HANDLE, allowing the value of the handle to be stored back to this location. So for example:
   FLIX2HANDLE flix;
   Flix2_Create(&flix);
   /*...upon success flix holds the address of the handle...*/
When dealing with various interpreted languages there is no way to directly accomplish this. For this reason a helper function is introduced to first create a storage location for the handle. Note that though the following is in Perl, the helper functions carry over to all of the language bindings.
   $flixptr= new_flix2handlep();
We can now use this storage location to create a new handle to the engine:
   Flix2_Create($flixptr);
Before we use the new handle in the remaining API functions we have to retrieve its actual value. Another helper function is introduced for this purpose:
   $flix= flix2handlep_value($flixptr);
$flix is now the handle to use in the remaining API calls, for example:
   Flix2_SetInputFile($flix,"/path/to/input.video");
When you're finished with the handle you can clean up any resources allocated to it by calling:
   delete_flix2handlep($flixptr);

Codec Handle Creation

The Codec Manipulation functions use the same interface to create a handle as the Filters. See below for a detailed example.

Filter Handle Creation

The Filter Manipulation functions present an issue similar to creating a Flix Engine handle. The solution is the same, to introduce a few helper functions, as demonstrated by the following PHP code:
   ##create a storage location for the filter handle
   $filterptr= new_flix2plgnhandlep();
   Flix2_AddFilter($filterptr,$flix,FE2_FILTER_PNGEX);

   ##retrieve the value of the handle for use in the remaining filter functions
   $filter= flix2plgnhandlep_value($filterptr);
   Flix2_FilterSetParam($filter,FE2_PNGEX_AUTO_EXPORT_COUNT,10);

   ## ...encode...
   ##cleanup
   delete_flix2plgnhandlep($filterptr);
The above adds the PNG Image Export (Thumbnail) to the filter chain and sets it to auto export 10 images. You will notice that the string constants are referenced by name.

Note:
You may reuse $filterptr in subsequent calls to Flix2_AddFilter(). Note that you must retrieve the filter handle with flix2plgnhandlep_value() each time.

Constants

The string constants defined by the Filters, as well as any other defines and enumeration members can all be referenced by name in the language bindings. The method for referencing them varies from language to language:

Note:
Constants should ALWAYS be referenced by name as their values are subject to change.

Functions

In the same vein as the Flix Engine and Filter handle issue is the issue with functions that return values via a result parameter. In this case the value is returned in a list instead of creating a storage location or modifying a pointer.
Some examples will help clarify this point:

Attention:
Functions that return a string, e.g., Flix2_GetInputFile(), are NOT currently supported by the language bindings.
Note:
As the Java bindings have been modified to throw an exception instead of directly returning a status code, the return value is generally a single value or an array where appropriate. See the Javadoc for more information.

On2 Technologies, Inc Flix Engine Linux documentation, generated on Tue Nov 2 16:52:54 2010 by doxygen 1.5.5