= Technical Specification =

== livido_setup ==
Each plugin must implement the function:

{{{
    livido_filter_t *livido_setup(void);
}}}

This function returns a linked list of livido_filter_t *.[[BR]]
The filters are created by the plugin using livido_port_new() (or a utility wrapper to this).


== livido_filter ==

A livido_filter has 5 port sets:

 * 1 info port
 * 1 in_channels port array
 * 1 out_channels port array
 * 1 in_parameters port array
 * 1 out_parameters port array

{{{
typedef struct livido_filter { 
     livido_port_t *info;
     livido_port_t **in_channels;
     livido_port_t **out_channels;
     livido_port_t **in_parameters;
     livido_port_t **out_parameters;
} livido_filter_t;
}}}


== Port ==

A port has a linked list of properties:

{{{
    typedef livido_property_t * livido_port_t;
}}}

Some properties are mandatory, some are optional.[[BR]]
For each port type/port hint, there is a mandatory set of properties and
an optional set of properties.[[BR]]


== Port Type ==

Each port has a mandatory property "type". "type" can be one of:

  * LIVIDO_PORT_TYPE_INFO
  * LIVIDO_PORT_TYPE_CHANNEL
  * LIVIDO_PORT_TYPE_PARAMETER
  * LIVIDO_PORT_TYPE_KEYFRAME
  * LIVIDO_PORT_TYPE_GUI

It is a single valued property with atom_type LIVIDO_ATOM_TYPE_INT.

The port_type is passed as a parameter in the init_port function as
{{{
 livido_port_t *livido_init_port( int port_type );
}}} 

After intialization the "type" property must be set read-only/immutable.



== Port Hint ==

Ports of type parameter also have an optional property, "hint". This is a single valued property with atom_type LIVIDO_ATOM_TYPE_INT.
The "hint" is used to further subdivide ports.[[BR]]

"hint" may be one of:[[BR]]

 * NUMBER
 * TEXT
 * SWITCH
 * LIST
 * CHOICE
 * COLORKEY
 * COORDINATE[[BR]]

If the "hint" is not set by the plugin, the "hint" is assumed to correspond to a single valued parameter of whatever type corresponds to the atom_type of the "value" property.[[BR]]

 * If the "value" property has atom_type LIVIDO_ATOM_TYPE_INT and "hint" is not set then the hint is assumed to be NUMBER.
 * If the "value" property has atom_type LIVIDO_ATOM_TYPE_FLOAT and "hint" is not set then the hint is assumed to be NUMBER.
 * If the "value" property has atom_type LIVIDO_ATOM_TYPE_CHARPTR and "hint" is not set then the hint is assumed to be TEXT.
 * If the "value" property has atom_type LIVIDO_ATOM_TYPE_BOOLEAN and "hint" is not set then the hint is assumed to be SWITCH.[[BR]]

Sometimes hosts may add these last four port hints if the plugin omits them. Once the "hint" is set, it should be set read-only/immutable.[[BR]]

The other mandatory and optional properties for each type/hint are shown below.


== Properties ==

Each port is a linked list of properties
A property has:
 * a key (which is a non-NULL string - (const char *))
 * a value (which is a livido_storage)
 * a next_pointer to the next property in the list (or a NULL for the last property)

The next_pointer is not visible to plugins or hosts.

{{{
typedef struct livido_property {
  const char *key; ///< unique type: min,max,value,step_size,page_size,decimals
  livido_storage_t *data; ///< either 1 atom or N atoms
  livido_property_t *next;
} livido_property_t;
}}}







Some type/hint/property combinations can take only one type of atom. Others allow an initial choice for atom types.[[BR]]

For LIVIDO_PORT_TYPE_PARAMETER, LIVIDO_PORT_HINT_COLORKEY, "value" property, atom type can be LIVIDO_ATOM_TYPE_INT, LIVIDO_ATOM_TYPE_FLOAT or LIVIDO_ATOM_TYPE_STRING.[[BR]]

Once this is set it should be kept constant for that port. For other properties which take a choice of atom types in that port, their atom type must match the atom type of the "value" property.[[BR]]

For example if the "value" property of a parameter port with LIVIDO_PORT_HINT_COLORKEY is set to take an atom_type of LIVIDO_ATOM_TYPE_INT, then the "min" and "max" properties of that port must also take a LIVIDO_ATOM_TYPE_INT atom_type.[[BR]]
For LIVIDO_PORT_TYPE_CHANNEL, the "pixel_data" property has a variable number of elements depending on the value of the "current_palette" property.[[BR]]


== Atom types ==

LiViDO implements the following atom types:[[BR]]

 * LIVIDO_ATOM_TYPE_INT
 * LIVIDO_ATOM_TYPE_FLOAT
 * LIVIDO_ATOM_TYPE_LONG
 * LIVIDO_ATOM_TYPE_BOOLEAN
 * LIVIDO_ATOM_TYPE_CHARPTR
 * LIVIDO_ATOM_TYPE_VOIDPTR
 * LIVIDO_ATOM_TYPE_UINT8PTR
 * LIVIDO_ATOM_TYPE_INT8PTR
 * LIVIDO_ATOM_TYPE_UINT16PTR
 * LIVIDO_ATOM_TYPE_INT16PTR
 * LIVIDO_ATOM_TYPE_UINT32PTR
 * LIVIDO_ATOM_TYPE_INT32PTR
 * LIVIDO_ATOM_TYPE_FLOATPTR
[[BR]]
As well as atom_type, each property has a number of elements, sometimes this is fixed, sometimes it is variable.


== livido_storage ==
This is the data which is stored in a property. A livido_storage has:[[BR]]

 * a (fixed) int num_elements
 * a (fixed) int atom_type
 * a flags field
 * data

{{{
struct livido_storage {
  int num_elements; ///< if its 1 or 0, it's an ATOM, otherwise its an ARRAY
  int atom_type;
  union {
    livido_atom_t *atom; // NULL if num_elements==0
    livido_atom_t **array;
  } data;
  int flags;
};
}}}


- the union "data" contains an atom * if number of elements == 1 otherwise it containts a atom **[[BR]]
  Number_of_elements can be set to 0, in which case this will hold a NULL pointer. This is useful for plugins which want to set the atom_type of a property without setting its value explicitly.

- "flags" is a bit field. One bit represents "read-only", and it can be set/cleared at any time. Another bit represents "immutable". Once the "immutable" bit has been set, the "flags" field cannot be changed any more.[[BR]]
The livido library functions to set properties will check the state of the "read-only" bit, and if it is set then the function will return an error code and not change the parameter value.[[BR]]
By convention, once the atom_type of a property is set, the atom_type of that property is constant for the life of that port.[[BR]]

== livido_atom ==
This is the lowest level of data in livido, and one or more of these are used in a livido_storage. A livido_atom has:
 * a type id int
 * a size of type size_t
 * a void * value

{{{
typedef struct livido_atom {
  int type;
  size_t size;
  void *value;
} livido_atom_t;
}}}





== Getting/setting values ==

Get/set is done by key and value.

Property values are copied on a get/set, except for pointer type atoms which are copied by reference.

Atoms of type charptr are also copied by value on get/set.

On get_value Livido will return a copy of the value in the property.

On set_value, the (previously) allocated property will be destroyed and a new one is allocated and set;
host should care of discarding all references to the old value.


== Functions ==

There are different levels of function: basic functions which are provided in livido.c, and higher level api functions which are provided in the livido utilities library.

 * livido_atom_t *livido_atom_new () - only used internally by livido
 * void livido_atom_free () - only used internally by livido
 * livido_storage_t *livido_storage_new()
 * void livido_storage_free() - only used internally by livido
 * livido_property_t *livido_property_new (livido_port_t *port, const char *key, int atom_type); // creates a new property of type atom_t. Livido_set_value will also call this to create the property if it does not exist.
 * void livido_property_free (livido_property_t *property);
 * livido_port_t *livido_port_new (int port_type)
 * void livido_port_free (livido_port_t *port)
 * int livido_set_value (livido_port_t *port, const char *key, int atom_type, int num_elems, void *value, size_t *sizes) // num_elems is >= 0, returns a livido_error
 * int livido_get_value (livido_port_t *port, const char *key, int idx, void *value) // idx starts at 0; returns LIVIDO_ERROR_NOSUCH_PROPERTY if property does not exist, thus it can be used to test if a property exists; always returns a livido_error
 * int livido_get_num_elements (livido_port_t *port, const char *key) // can return 0 for NULL storages
 * size_t livido_get_atom_size(livido_port_t *port, const char *key, int idx) // idx starts at 0, can return 0 for a NULL storage
 * int livido_get_atom_type(livido_port_t *port, const char *key)
 * char **livido_list_properties (livido_port_t *port) // returns a NULL terminated string array
 * int livido_set_readonly (livido_property_t *property)
 * int livido_get_readonly (livido_property_t *property)  // returns 0 (read/write) or 1 (read_only)


== Disabled ==
This is an optional property for all port types except LIVIDO_PORT_TYPE_INFO. It takes a single atom of type LIVIDO_ATOM_TYPE_BOOLEAN. The plugin may set this property to TRUE for channels in the livido_setup() function.

The host may set this to FALSE for channels before calling init() in the plugin. In this way, optional channels can be implemented.



== Other plugin functions ==

{{{
    int init(livido_filter_t *)
}}}
The host calls this and passes back the port set, with some values changed.
Prior to this, the host can change the "value" property of parameters. It returns an int livido error code.

The init function allows the plugin to create any internal memory structures it needs; these can be referred to in the info port, property "internal" which takes a void * atom_type.

The host must also attend to "disabled" in the channel ports, and set the "current_palette" property in the channel ports.

{{{
    int process(livido_filter_t *)
}}}
host calls this for each processing cycle; the plugin can do its frame processing here.

{{{
    int deinit(livido_filter_t *)
}}}
host calls this allow the plugin to free any internal memory held in the info port "internal" property. Following this the host may free the livido_filter. The plugin does not need to free any ports or paramters, the host should take care of this. 


== Flow of operation ==
 * Host loads plugin
 * Host creates (mallocs) a livido_filter **
 * Host passes this to plugin in the livido_setup() function.
 * For each filter in the plugin, the plugin creates the livido_filter, initialises an info port, an array of in_channel ports, an array of out_channel ports, an array of in_parameter ports and an array of out_parameter ports. These filters are added as array elements to the filter array passed by the host. The plugin returns an error code (or LIVIDO_NO_ERROR).
 * Host examines the in_channel and out_channel ports, and clears the "disabled" flag for any optional channels it wishes to use. It also checks "palette_list", selects a palette it would like to start using on that channel and sets the chosen value in the "current_palette" property. It also sets the sizes ("width" and "height" properties) if the plugin left them as zero.
 * Host can change "value" for any non-disabled in_parameter, thus overriding the plugin's default.
 * Host calls setup in the plugin, passing in a filter it would like to use.
 * Plugin now knows the channel sizes, palettes and which are in use, and can check if the plugin has changed any parameter "value" properties. The plugin may now malloc internal data if it wishes and set a pointer to this in the info port property "internal"
 * Host may now change parameter values (respecting "max" and "min" properties) and it may call process() in the plugin whenever it likes, passing in the initialised filter. 
 * When the host has finished with the filter, or if it needs to re-initialise it, the host must call deinit() in the plugin, passing in the filter. The plugin can now free any internal data which it allocated.
* Host can now either free the filter, or re-initialise it by calling init() in the plugin again. The host may wish to keep a copy of the original filter returned from livido_setup(), in this way the "values" and channel statuses will be reset to their defaults.








== Conversion functions ==

We provide functions for converting between atom types for some port/property pairs (i.e. those pairs which have a choice of atom types)

TODO


== Mnemonics ==

Since the "label" property of a parameter type port is often used by hosts as the label text for a parameter, an underscore in a "label" property is rendered as a mnemonic in most hosts. This can be an important consideration for plugin accessibility.

== Ports and properties ==
Here we specify the port/property pairs, whether they are mandatory or optional, and their types.

== Info port ==

"type" == LIVIDO_PORT_TYPE_INFO

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR : the filter name

"author" : LIVIDO_ATOM_TYPE_CHARPTR : the filter author name

"version" : LIVIDO_ATOM_TYPE_INT : filter verison

"api_version" : LIVIDO_ATOM_TYPE_INT : livido api verison

"flags" : LIVIDO_ATOM_TYPE_INT : bitmap of instance_flags

"init_func" : LIVIDO_ATOM_TYPE_VOIDPTR : pointer to a livido_init_f

"process_func" : LIVIDO_ATOM_TYPE_VOIDPTR : pointer to a livido_process_f

"deinit_func" : LIVIDO_ATOM_TYPE_VOIDPTR : pointer to a livido_deinit_f

"num_in_channels" : LIVIDO_ATOM_TYPE_INT : total number in array

"num_out_channels" : LIVIDO_ATOM_TYPE_INT : total number in array

"num_in_parameters" : LIVIDO_ATOM_TYPE_INT : total number in array

"num_out_parameters" : LIVIDO_ATOM_TYPE_INT : total number in array

==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR : filter description

"license" : LIVIDO_ATOM_TYPE_CHARPTR

"url" : LIVIDO_ATOM_TYPE_CHARPTR

"scale_x" : LIVIDO_ATOM_TYPE_FLOAT : 

"scale_y" : LIVIDO_ATOM_TYPE_FLOAT  :

"num_threads" : LIVIDO_ATOM_TYPE_INT : (==1 if not present)

"view" : LIVIDO_ATOM_TYPE_VOIDPTR : this is used by plugins which have trigger functions. See the section entitled "View/Trigger_func"

"fps" : LIVIDO_ATOM_TYPE_FLOAT : plugin can set this in the setup function if it requires fixed FPS.

"internal" : LIVIDO_ATOM_TYPE_VOIDPTR  : the plugin can set this in its init() function to store internal data. The plugin should free() it in its deinit() function.





== Channel port ==

"type" == LIVIDO_PORT_TYPE_CHANNEL


==== Mandatory properties ====


"name" : LIVIDO_ATOM_TYPE_CHARPTR  : name of the channel

"flags" : LIVIDO_ATOM_TYPE_INT : bitmap of channel_flags

"timecode" : LIVIDO_ATOM_TYPE_LONG : timecode since 'play start' (RT) or start of the timeline (NLE) in microseconds


==== Mandatory properties for video channels ====

"width" : LIVIDO_ATOM_TYPE_INT : frame width in pixels, plugin can set this in setup() to a non-zero value (zero means any)

"height" : LIVIDO_ATOM_TYPE_INT : frame height in pixels, plugin can set this in setup() to a non-zero value (zero means any)

"palette_list" : LIVIDO_ATOM_TYPE_INT : the plugin sets this to an array of allowed palettes for the channel, terminating the array with a LIVIDO_PALETTE_END

"current_palette" : LIVIDO_ATOM_TYPE_INT : the host sets this to the chosen palette, which must be one of the palettes contained in "palette_list".

"pixel_data" : LIVIDO_ATOM_TYPE_*PTR : number of elements varies depending on "current_palette"

"rowstrides" : LIVIDO_ATOM_TYPE_INT : length of one row in bytes (include padding) : same number of elements as "pixel_data"


==== Mandatory properties for audio channels ====

"audio_data" : Audio channels will be specified in the LiViDO Audio Extension : TODO


==== Optional properties ====

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"window" : array of INT or FLOAT

"v_shift" : LIVIDO_ATOM_TYPE_INT : used for YUV type palettes

"h_shift" : LIVIDO_ATOM_TYPE_INT : used for YUV type palettes

"interlacing" : LIVIDO_ATOM_TYPE_INT : Progressive,None (default) ,Topfirst,Bot.first - if not present, then no interlacing is assumed. TODO

"fps" (DOUBLE) : default is same as instance "fps"

"same_as" : LIVIDO_ATOM_TYPE_VOIDPTR : plugin can set this to indicate that this channel must match with another channel. The pointer points to another in/out channel. The flags field indicates whether frame size (height/width) or palette must match (or both).

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing either the "height", "width" or "current_palette" properties of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *channel, const char *property)

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN : the plugin may set this to TRUE in setup(), host may set its value to FALSE before calling init().



== Keyframe parameter port ==

"type" == LIVIDO_PORT_TYPE_KEYFRAME


==== Mandatory properties ====

"timecode" : LIVIDO_ATOM_TYPE_LONG : timecode of this keyframe event

"value" : LIVIDO_ATOM_TYPE_* : value at timecode




== Number parameter port ==

"type" == LIVIDO_PORT_TYPE_PARAMETER

"hint" == NUMBER

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"min" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"max" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"decimals" : LIVIDO_ATOM_TYPE_INT : this property is mandatory if the atom_type of "value" is LIVIDO_ATOM_TYPE_FLOAT

==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"step_size" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"page_size" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"wrap" : LIVIDO_ATOM_TYPE_BOOLEAN : indicates whether values wrap-around min->max/max->min

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int update_view_func(livido_filter_t *filter, livido_port_t *port, const char *property)

"interpolate_func" : LIVIDO_ATOM_TYPE_VOIDPTR : int keyframe_func(livido_port_t *in_keyframes, livido_port_t *out_keyframe)





== Text parameter port ==

"type" == LIVIDO_PORT_TYPE_PARAMETER

"hint" == TEXT

==== Mandatory properties ====


"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_CHARPTR

==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"min_length" : LIVIDO_ATOM_TYPE_INT

"max_length" : LIVIDO_ATOM_TYPE_INT

"padding_character" : LIVIDO_ATOM_TYPE_CHARPTR : character (utf-8) to be used by host to pad to "min_length", if not present, space should be used

"padding_method" : LIVIDO_ATOM_TYPE_INT : if present, can be one of LIVIDO_TEXT_PAD_LEFT (the default), LIVIDO_TEXT_PAD_RIGHT, LIVIDO_TEXT_PAD_CENTER : the host is expected to do the padding.

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int update_view_func(livido_filter_t *filter, livido_port_t *port, const char *property)

== Colorkey parameter port ==

"type" == LIVIDO_PORT_TYPE_PARAMETER

"hint" == COLORKEY


==== Mandatory properties ====


"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT : multivalued

"min" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"max" : LIVIDO_ATOM_TYPE_INT or LIVIDO_ATOM_TYPE_FLOAT

"decimals" : LIVIDO_ATOM_TYPE_INT : this property is mandatory if the atom_type of "value" is LIVIDO_ATOM_TYPE_FLOAT


==== Optional properties ====

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"colorspace" : LIVIDO_ATOM_TYPE_INT : if not present, RGB(A) is assumed

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *port, const char *property)

"interpolate_func" : LIVIDO_ATOM_TYPE_VOIDPTR : int keyframe_func(livido_port_t *in_keyframes, livido_port_t *out_keyframe)



== Choice parameter port ==


"type" == LIVIDO_PORT_PARAMETER

"hint" == CHOICE

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_INT : index of current value in "list_values" (0 based)

"list_values" : array of any (non pointer) atom type


==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *port, const char *property)





== List parameter port ==

"type" == LIVIDO_PORT_PARAMETER

"hint" == LIST

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR

"number_of_elements" : LIVIDO_ATOM_TYPE_INT : number of elements in array

"value" : LIVIDO_ATOM_TYPE_* : array of n values, may take any non-pointer atom_type.

==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *port, const char *property)










== Switch parameter port ==

"type" == LIVIDO_PORT_PARAMETER

"hint" == SWITCH

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_BOOLEAN

==== Optional properties ====

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"description" : LIVIDO_ATOM_TYPE_CHARPTR

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *port, const char *property)



== Coordinate parameter port ==

"type" == LIVIDO_PORT_PARAMETER

"hint" == COORDINATE

==== Mandatory properties ====

"name" : LIVIDO_ATOM_TYPE_CHARPTR

"value" : LIVIDO_ATOM_TYPE_FLOAT or LIVIDO_ATOM_TYPE_INT

"min" : LIVIDO_ATOM_TYPE_FLOAT or LIVIDO_ATOM_TYPE_INT

"max" : LIVIDO_ATOM_TYPE_FLOAT or LIVIDO_ATOM_TYPE_INT

==== Optional properties ====

"label" : LIVIDO_ATOM_TYPE_CHARPTR : label for display

"disabled" : LIVIDO_ATOM_TYPE_BOOLEAN

"geometry" : LIVIDO_ATOM_TYPE_CHARPTR (e.g. "cartesian", "logarithm", "polar") : "cartesian" assumed if not set

"update_view_func" : LIVIDO_ATOM_TYPE_VOIDPTR : if the plugin sets this to non-NULL, then the host should call this after changing the "value" parameter of the port
The function template is: int trigger_func(livido_filter_t *filter, livido_port_t *port, const char *property)

"interpolate_func" : LIVIDO_ATOM_TYPE_VOIDPTR : int keyframe_func(livido_port_t *in_keyframes, livido_port_t *out_keyframe)

"description" : LIVIDO_ATOM_TYPE_CHARPTR

== Livido Palettes ==
 *  LIVIDO_PALETTE_RGB24
 *  LIVIDO_PALETTE_RGB888
 *  LIVIDO_PALETTE_RGB32
 *  LIVIDO_PALETTE_RGBA8888
 *  LIVIDO_PALETTE_RGB161616
 *  LIVIDO_PALETTE_RGBA16161616
 *  LIVIDO_PALETTE_YUV888
 *  LIVIDO_PALETTE_YUVA8888
 *  LIVIDO_PALETTE_YUV161616
 *  LIVIDO_PALETTE_YUVA16161616
 *  LIVIDO_PALETTE_YUV422P
 *  LIVIDO_PALETTE_YUV420P
 *  LIVIDO_PALETTE_YUV444P
 *  LIVIDO_PALETTE_A8
 *  LIVIDO_PALETTE_A16
 *  LIVIDO_PALETTE_RGBFLOAT
 *  LIVIDO_PALETTE_RGBAFLOAT
 *  LIVIDO_PALETTE_AFLOAT
 *  LIVIDO_PALETTE_BGR888
 *  LIVIDO_PALETTE_YUYV8888
 *  LIVIDO_PALETTE_UYVY8888
 *  LIVIDO_PALETTE_RGB565
 *  LIVIDO_PALETTE_RGBX8888
 *  LIVIDO_PALETTE_A4
 *  LIVIDO_PALETTE_A2
 *  LIVIDO_PALETTE_A1

 *   LIVIDO_PALETTE_FIRST_CUSTOM 2048

== Livido flags and types ==

==== Filter flags ====
 *  LIVIDO_FILTER_NON_REALTIME[[BR]]
    non-realtime filter property

 *  LIVIDO_FILTER_CAN_DO_INPLACE[[BR]]
   If this property is set, the filter can do inplace operations then
   host can use plugin process() function and have the first output come out of the
   first input channel.
   If plugin advertizes this capability, it HAS to have first
   output channel connected to the first input channel (same_palette and same_size);
   the host can indicate it would like the first input channel to be used as the first output channel
   by setting the first output frame "pixel_data" to NULL in process()


 *  LIVIDO_FILTER_CAN_DO_SCALED[[BR]]
    The plugin knows how to scale the parameters when drawing
    previews/thumbnails host can use scale_x and scale_y in this case

 *  LIVIDO_FILTER_CAN_DO_WINDOWED[[BR]]
   The plugin knows how to operate on window of frame (adjusting
   parameters accordingly) window is denoted as window_x1, window_y1
   for upper left corner of the window and full_x and full_y give the
   total size of the frame as it was before cropping lower right
   corner can be caluclated by adding window_x1 to channel
   width... and the same for height.[[BR]]

   The host must set the following fields in the filter in order
   to tell the plugin the geometry of the desired window:
   - livido_instance::window_x
   - livido_instance::window_y
   - livido_instance::window_w
   - livido_instance::window_h */

 *  LIVIDO_FILTER_SELF_AUTOMATION[[BR]]
    plugin can self-animate - it may change parameter "value"s during
    process(); all other plugins may only change "value"s during init()


 *  LIVIDO_FILTER_FPS_NEEDED[[BR]]
   The plugin absolutely needs frames_per_second information, don't
   try to use it without


 *  LIVIDO_FILTER_STATELESS[[BR]]
    plugin does not use internal buffers/static data




==== Channel flags ====

 *  LIVIDO_CHANNEL_MASK[[BR]]
    tell host that channel is a mask

 *  LIVIDO_CHANNEL_SAME_AS_SIZE[[BR]]
    tell host that same_as refers to palettes

 *  LIVIDO_CHANNEL_SAME_AS_PALETTE[[BR]]
    tell host that same_as refers to palettes

 *  LIVIDO_CHANNEL_HOST_CAN_RESIZE[[BR]]
    tell host that channels can be resized without calling deinit/init, SAME_AS rules must still be followed

 *  LIVIDO_CHANNEL_HOST_CAN_CHANGE_PALETTE[[BR]]
    tell host that current_palette can be changed without calling deinit/init, SAME_AS rules must still be followed


==== Parameter flags ====

 * LIVIDO_PARAMETER_NEEDS_REINIT[[BR]]
   set by plugin: host needs to re-init parameter value change

==== Property flags ====

 * LIVIDO_PROPERTY_READONLY

==== Interlace types ====

 * LIVIDO_INTERLACE_NONE
 * LIVIDO_INTERLACE_TOPFIRST
 * LIVIDO_INTERLACE_BOTTOMFIRST
 * LIVIDO_INTERLACE_PROGRESSIVE

==== Padding types ====

 * LIVIDO_TEXT_PAD_LEFT
 * LIVIDO_TEXT_PAD_RIGHT
 * LIVIDO_TEXT_PAD_CENTER

==== Colorkey colorspaces ====

 * LIVIDO_COLORKEY_RGB
 * LIVIDO_COLORKEY_YUV
 * LIVIDO_COLORKEY_HSV

== Livido errors ==

 *  LIVIDO_NO_ERROR[[BR]]
    return code means no problem

 *  LIVIDO_ERROR_TOO_MANY_INSTANCES[[BR]]
    can't create: plugin allows only limited number of filter instances

 *  LIVIDO_ERROR_MEMORY_ALLOCATION[[BR]]
    memory allocation by the filter has failed (not enough memory?)

 *  LIVIDO_ERROR_NULL_FILTER[[BR]]
    a NULL was passed as a function parameter instead of a valid livido_filter_t *

 *  LIVIDO_ERROR_NULL_PORT[[BR]]
    a NULL was passed as a function parameter instead of a valid livido_port_t *

 *  LIVIDO_ERROR_NULL_KEY[[BR]]
    a NULL was passed as a function parameter instead of a valid const char *

 *  LIVIDO_ERROR_PROPERTY_READONLY[[BR]]
    plugin/host tried to set readonly property

 *  LIVIDO_ERROR_WRONG_ELEMENTS[[BR]]
    plugin/host tried to read an invalid element number in a storage

 *  LIVIDO_ERROR_NOSUCH_PROPERTY[[BR]]
    property does not exist for the specified port

 * LIVIDO_ERROR_HINT_MORE_KEYFRAMES[[BR]]
   plugin may return this from interpolate_func; more accurate value can be given if more keyframes are provided