LiViDO/OSC

##Technical Specification

###LiViDO/OSC Technical Specification for Veejay
(C) Niels Elburg 2010

Drafting LiViDO/OSC specification for Veejay

##Versions
LiViDO/OSC Nov 11th , 2010

  • added "identifier" to PORT_TYPE_PLUGIN_INFO

  • added "organization" to PORT_TYPE_PLUGIN_INFO

  • added "path" to PORT_TYPE_FILTER_INSTANCE

LiViDO/OSC April. 11th , 2010

  • added OSC extension

Livido 1.0 beta version 2005- 2010

(C) Gabriel "Salsaman" Finch, Niels Elburg, Dennis "Jaromil" Rojo, Daniel Fischer, Martin Bayer, Kentaro Fukuchi, Andraz Tori 2005.

###LIVIDO_API_VERSION
This is defined as 102 for this version of the specification.

###LIVIDO GENERAL DESIGN
Livido is an architecture to enable interchange of video processing plugins between video applications in a standardized and compatible way.

This document describes the LiViDO/OSC extension for Veejay

###LiViDO
Livido plugin is a shared object that application can load. Inside a plugin there can be implementations of many different filters, each filter implementation is called a filter class. Host gets to know a list of classes a plugin provides when calling livido_setup function. A class description includes descriptions of inputs and outputs filter can handle. Inputs and outputs can be channels and parameters. Descriptions of acceptable types of channels and parameters are called channel templates and parameter templates respectively. Host prepares for instantination of the filter by setting input and output channels and input parameters and then instantinates a filter. Host can use process_func() on that instance until it deinits an instance.
All passing of data between hosts and plugins is done trough ports, ports are the only C structures defined in Livido.

###OSC
OpenSound Control(OSC) is a content format for sharing (music) performance data (such as gestures, parameters and note sequenecs) between (musical) instruments.

Each LiViDO plugin exports its capability set to the outside world using a OSC namespace

Mandatory properties:

  • "instance" : LIVIDO_PORT_TYPE_FILTER_INSTANCE

  • "HOST_osc_cb" : Host OSC callback function

    typedef   void  (*generic_osc_cb_f)(void *userdata, void *port, void *value );  
  • "HOST_osc_data" : LIVIDO_PORT_TYPE_VOIDPTR: Host private data

  • "root" : LIVIDO_PORT_TYPE_VOIDPTR: Plugin's OSC namespace

OSC Namespace

Container

  • "name" : LIVIDO_ATOM_TYPE_STRING : Name

  • "description" : LIVIDO_ATOM_TYPE_STRING : Short descriptive information

  • "help" : LIVIDO_ATOM_TYPE_STRING : Help information

  • "format" : LIVIDO_ATOM_TYPE_STRING : OSC parameter format

  • "path" : LIVIDO_ATOM_TYPE_STRING : OSC path to identify this instance. For example /myorg/myname/myplugin/

  • "template" : LIVIDO_ATOM_TYPE_FILTERCLASS: Port reference to Plugins's Filter Class

Method

  • "name" : LIVIDO_ATOM_TYPE_STRING:

  • "format" : LIVIDO_ATOM_TYPE_STRING:

  • "description" : LIVIDO_ATOM_TYPE_DESCRIPTION:

  • "parent" : LIVIDO_ATOM_TYPE_VOIDPTR:

  • "path" : LIVIDO_ATOM_TYPE_STRING: OSC path

  • "instance" : LIVIDO_ATOM_TYPE_VOIDPTR:

Naming convention

  • All names are lowercase alphanumeric characters [a-z0-9] and the character '_'

  • The root of a plugin's namespace is '/' followed by the plugins name

  • The only reserved keywords are 'ID', 'bind' and 'unbind' to allow (de)coupling of Plugins

  • The '*' (asterix) denotes a numeric identifier to uniquely identify a plugin's instance

  • The '?' returns a plugins full namespace including all parameters and channels

/<Plugin Name>/<ID*>/<Parameter Name>/<Parameter Value>  
/<Plugin Name>/<ID*>/<Channel Name>/bind/<Plugin Name>/<ID*>/<Channel Name>  
/<Plugin Name>/<ID*>/<Channel Name>/unbind/<Plugin Name>/<ID*>/<Channel Name>  
/<Plugin Name>/<ID*>/<Parameter Name>/bind/<Plugin Name>/<ID*>/<Parameter Name>  
/<Plugin Name>/<ID*>/<Parameter Name>/unbind/<Plugin Name>/<ID*>/<Parameter Name>  

###PORTS
A port is a set of one or more properties:

Each port has a mandatory property called "type" (see below), depending upon "type" property port has other mandatory and optional properties.

"type" can be one of:

  • LIVIDO_PORT_TYPE_PLUGIN_INFO : Information about plugin and list of filter classes it includes

  • LIVIDO_PORT_TYPE_FILTER_CLASS : Descriptive information about single filter class

  • LIVIDO_PORT_TYPE_CHANNEL_TEMPLATE : Information about what kinds of channels filter accepts

  • LIVIDO_PORT_TYPE_PARAMETER_TEMPLATE : Information about what kinds of parameters filter has

  • LIVIDO_PORT_TYPE_FILTER_INSTANCE : All data about an instance

  • LIVIDO_PORT_TYPE_CHANNEL : Instantination of a channel

  • LIVIDO_PORT_TYPE_PARAMETER : Instantination of a parameter

"type" is a single valued property with atom_type LIVIDO_ATOM_TYPE_INT.

The "type" is passed as a parameter in the livido_port_new() function as:

livido_port_t *livido_port_new( int port_type );  

This returns a pointer to newly allocated port with the "type" property set to port_type.

Port types >=512 are available for custom use.

###PROPERTIES
As mentioned above, each port is a set of one or more properties.

A property has:

  • a key (which is a non-NULL string - (const char *) ASCII encoded)

  • a value (0 or more elements)

  • number of elements (>=0) contained in the value field.

  • an atom_type

  • a bitmap flags field

###PROPERTY RESTRICTIONS
Access to properties is restricted in certain cases, these are restriction flags used troughout this document:

  • HOSTSET - Read-only for the plugin

  • PLUGINSET - Read-only for the host

  • FINAL - Not allowed to change after it was set

  • MANDATORY - mandatory property that MUST exist at some point in time

  • OPTIONAL - property that COULD exist

Properties inherit restriction of the port where we do not specify otherwise.

###ATOM TYPES
LiViDO offers the following fundamental types (number <64):

  • LIVIDO_ATOM_TYPE_INT : signed int32_t

  • LIVIDO_ATOM_TYPE_DOUBLE : corresponds to C type "double"

  • LIVIDO_ATOM_TYPE_BOOLEAN : signed int32_t, constrained to take values 0 (FALSE) or 1 (TRUE)

  • LIVIDO_ATOM_TYPE_STRING : array of char

Note: STRINGS are all utf-8 encoded in Livido, except property Keys, which are ASCII encoded.

Pointer types (number>=64 and <512):

  • LIVIDO_ATOM_TYPE_VOIDPTR : corresponds to C void * type

  • LIVIDO_ATOM_TYPE_PORTPTR : livido_port_t : a void to a livido_property_t, currently used only for channel properties "same_as_size", "same_as_palette")

  • LIVIDO_ATOM_TYPE_INIT_F : pointer to a livido_init_f function

  • LIVIDO_ATOM_TYPE_PROCESS_F : pointer to a livido_process_f function

  • LIVIDO_ATOM_TYPE_DEINIT_F : pointer to a livido_deinit_f function

Types >=512 are available for custom use. Custom atom types must be pointer types, since livido cannot guess their byte size or type.

###PORT TYPE PLUGIN INFO
Port enables a plugin function livido_setup to tell the host what filter classes are available. Port is PLUGINSET and FINAL after livido_setup() finishes.

  • "type" == LIVIDO_PORT_TYPE_PLUGIN_INFO

Mandatory properties:

  • "filters" : LIVIDO_ATOM_TYPE_PORTPTR : atom or array of livido_filter_t,

  • "maintainer" : LIVIDO_ATOM_TYPE_STRING : maintainer of plugin package

  • "version" : LIVIDO_ATOM_TYPE_STRING : plugin package version

  • "api_version" : LIVIDO_ATOM_TYPE_INT : livido api version: MUST be set to the LIVIDO_API_VERSION as defined above in this spec

  • "identifier": LIVIDO_ATOM_TYPE_STRING: a unique identifier for this plugin. the field is mandatory. Use a DNS prefix. For example ( veejayhq.net.Negation )

Optional properties:

  • "url" : LIVIDO_ATOM_TYPE_STRING : URL of plugin package

###PORT TYPE FILTER CLASS
Port type filter class is used to describe all properties of a single filter class. Port is PLUGINSET and FINAL after livido_setup().

"type" == LIVIDO_PORT_TYPE_FILTER_CLASS

Mandatory properties:

  • "name" : LIVIDO_ATOM_TYPE_STRING : the filter name

  • "author" : LIVIDO_ATOM_TYPE_STRING : the filter author(s)

  • "organization": LIVIDO_ATOM_TYPE_STRING: name of organization providing the plugin

  • "description" : LIVIDO_ATOM_TYPE_STRING : filter description

  • "version" : LIVIDO_ATOM_TYPE_INT : filter version.

  • "license" : LIVIDO_ATOM_TYPE_STRING : license of filter

  • "flags" : LIVIDO_ATOM_TYPE_INT : bitmap of filter flags

  • "init_func" : LIVIDO_ATOM_TYPE_INIT_F : pointer to a init_func()

  • "process_func" : LIVIDO_ATOM_TYPE_PROCESS_F : pointer to a process_func()

  • "deinit_func" : LIVIDO_ATOM_TYPE_DEINIT_F : pointer to a deinit_func()

  • "in_channel_templates" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements: input ports of input channel templates, type of the referenced port MUST be LIVIDO_PORT_TYPE_CHANNEL_TEMPLATE

  • "out_channel_templates" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of output channel templates, type of the referenced port MUST be LIVIDO_PORT_TYPE_CHANNEL_TEMPLATE

  • "in_parameter_templates" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of input parameter templates, type of the referenced port MUST be LIVIDO_PORT_TYPE_PARAMETER_TEMPLATE

  • "out_parameter_templates" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of output parameter templates, type of the referenced port MUST be LIVIDO_PORT_TYPE_PARAMETER_TEMPLATE

Optional properties:

  • "url" : LIVIDO_ATOM_TYPE_STRING

###PORT TYPE FILTER INSTANCE
Port type filter instance is used to hold all data that are related to a single instance of the filter all properties of a single filter class. Port is HOSTSET after livido_setup.

"type" == LIVIDO_PORT_TYPE_FILTER_INSTANCE

Mandatory properties:

  • "filter_class" : LIVIDO_ATOM_TYPE_PORTPTR : Pointer to a filter class port this filter instance is based on

  • "in_channels" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of input channels, type of the referenced port MUST be LIVIDO_PORT_TYPE_CHANNEL

  • "out_channels" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of output channels , type of the referenced port MUST be LIVIDO_PORT_TYPE_CHANNEL

  • "in_parameters" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of input parameters, type of the referenced port MUST be LIVIDO_PORT_TYPE_PARAMETER

  • "out_parameters" : LIVIDO_ATOM_TYPE_PORTPTR, list of 0 or more elements : ports of output parameters, type of the referenced port MUST be LIVIDO_PORT_TYPE_PARAMETER

Optional properties:

  • Every filter instance can have its internal properties stored inside this port, and host MUST ignore them. Those internal properties MUST have keys prefixed with "PLUGIN_"

  • Every host can have its internal properties stored inside this port, and filter MUST ignore them. Those internal properties MUST have keys prefixed with "HOST_"

  • "path" : LIVIDO_ATOM_TYPE_STRING: relative or absolute path to plugin data directory. Field is set by host. Plugin can use it to load extra data during initialization.

###PORT TYPE CHANNEL TEMPLATE
Port type channel template is used as a description of a single channel (input or output) a filter can handle. Port is PLUGINSET and FINAL after livido_setup.

  • "type" == LIVIDO_PORT_TYPE_CHANNEL_TEMPLATE

Mandatory properties:

  • "name" : LIVIDO_ATOM_TYPE_STRING : name of the channel, MUST be unique across all channels in the filter class

  • "flags" : LIVIDO_ATOM_TYPE_INT : bitmap of channel_flags that plugin sets

  • "palette_list" : LIVIDO_ATOM_TYPE_INT : the plugin sets this to an array of allowed palettes for the channel. Its order is plugin's preference for a palette

Optional properties:

  • "description" : LIVIDO_ATOM_TYPE_STRING : description of this channel

  • "width" : LIVIDO_ATOM_TYPE_INT : If set, frame width in pixels that a plugin can handle. If it is set, host is forbidden to set the width in channel instance to anything else

  • "height" : LIVIDO_ATOM_TYPE_INT : If set, frame height in pixels that a plugin can handle. If it is set, host is forbidden to set the height in channel instance to anything else

  • "same_as_size" : LIVIDO_ATOM_TYPE_PORTPTR : plugin can set this to indicate that this channel must match "height" and "width" with another channel. The pointer points to another in/out channel template

  • "same_as_palette" : LIVIDO_ATOM_TYPE_PORTPTR : plugin can set this to indicate that this channel must match "current_palette" with another channel. The pointer points to another in/out channel template

  • "optional" : LIVIDO_ATOM_TYPE_BOOLEAN : the plugin may set this to TRUE for channels that can be left out at initialization time.

Restrictions to properties

Each channel template can only reference another through *_same_as or be referenced by another, not both.

There can be only backward references in the array. For example channel 2 can have *_same_as to channel 1, but not the other way around.

Output channels can, however, reference input channels at will

###PORT TYPE CHANNEL
Port type channel is used as a fixation of channel properties that the host sets and plugin reads to know what it is getting. Port is HOSTSET after init_func(). Channels should be a one-one match with channel templates (same order, same number).

  • "type" == LIVIDO_PORT_TYPE_CHANNEL

Mandatory properties:

  • "parent_template" : LIVIDO_ATOM_TYPE_PORT : Pointer to a channel template port this channel instance is based on. FINAL.

  • "timecode" : LIVIDO_ATOM_TYPE_DOUBLE : time in seconds for this channel, host can choose what exactly it represents

  • "width" : LIVIDO_ATOM_TYPE_INT : The chosen frame width in pixels

  • "height" : LIVIDO_ATOM_TYPE_INT : The chosen height in pixels

  • "current_palette" : LIVIDO_ATOM_TYPE_INT: The chosen palette, which must be one of the palettes contained in "palette_list" of a channel template

  • "pixel_data" : LIVIDO_ATOM_TYPE_VOIDPTR : array of size 4 of pointers to the image pixels data. depending on the value of "current_palette", only the first pointer is used for packed modes and in planar modes each plane has its own pointer.

  • "rowstrides" : LIVIDO_ATOM_TYPE_INT : array of size 4 carrying the row width of EACH PLANE in bytes (include padding)

Optional properties:

  • "fps" : LIVIDO_ATOM_TYPE_DOUBLE : fps of channel;

  • "pixel_aspect_ratio" : LIVIDO_ATOM_TYPE_DOUBLE : physical aspect ratio of the pixel of the image (pixel aspect ratio different than 1.0 means pixels are non-square)

  • "v_shift" : LIVIDO_ATOM_TYPE_INT : vertical shift in the pixels of the sampling of crominance planes for planar yuv palletes

  • "h_shift" : LIVIDO_ATOM_TYPE_INT : horizontal shift in the pixels of the sampling of crominance planes for planar yuv palletes

  • "YUV_sampling" : LIVIDO_ATOM_TYPE_INT : Sampling type for YUV palettes, enum defined below

  • "interlacing" : LIVIDO_ATOM_TYPE_INT : Interlacing type, defined below. if not present, the image must be NON INTERLACED

  • "disabled" : LIVIDO_ATOM_TYPE_BOOLEAN : the host MAY set this to TRUE before calling init_func() if the coresponding channel template has optional property set to true

###PORT TYPE PARAMETER TEMPLATE
Port type parameter template is used as a description of a single parameter (input or output) filter can handle. Port is PLUGINSET and FINAL after livido_setup.

Mandatory properties:

  • "name" : LIVIDO_ATOM_TYPE_STRING : name of the parameter, MUST be unique across the in_parameter_templates/out_parameter_templates

  • "default" : any of the fundamental atom type : sane default value of the parameter

  • "kind" : LIVIDO_ATOM_TYPE_STRING : Tells the host the minimal needed information to be able to present a parameter. Depending of the value of "kind", there are additional properties that are mandatory or optional. The rules for additional properties are spelled out below.

Optional properties:

  • "flags" : LIVIDO_ATOM_TYPE_INT : Plugin sets this to LIVIDO_PARAMETER_CHANGE_UNADVISED if a change in the "value" of instance of the parameter causes some kind of internal reinit of the plugin (realtime hosts can use this to be able to avoid slow behaviour of he plugins).

  • "description" : LIVIDO_ATOM_TYPE_STRING : parameter description, FINAL

PARAMETER CONSTRAINING

Parameter constraining in Livido is minimalistic, all GUI related stuff is to be defined in separate document. Parameter constraining is derived from additional properties defined for parameter template that depend on the value of the property "kind".

The kind is a mandatory property of every parameter, the defined values are:

  • "INDEX" (discrete)

  • "NUMBER" (continuous)

  • "TEXT" (utf-8)

  • "SWITCH" (boolean)

  • "COLOR_RGBA"

  • "COORDINATE"

Depending on the "kind" parameter atom type and mandatory additional properties MUST BE:

  • "INDEX"

Kind index means a discret number, which can be used for index choosing or passing integer values. It is constrained by min and max: min <= value <= max
The default property can only be of atom type LIVIDO_ATOM_TYPE_INT.
Additional properties that kind causes:

  • min : LIVIDO_ATOM_TYPE_INT : minimal value of the parameter, MANDATORY

  • max : LIVIDO_ATOM_TYPE_INT : maximal value of the parameter, MANDATORY

  • wrap : LIVIDO_ATOM_TYPE_BOOLEAN : indicates that the "value" should wrap when going below min or above max, OPTIONAL

  • "NUMBER"

Kind index means a continuous number, which can be used for index choosing or passing integer values. It is constrained by min and max: min <= value <= max
The default property can only be of atom type LIVIDO_ATOM_TYPE_DOUBLE.
Additional properties that kind causes:

  • min : LIVIDO_ATOM_TYPE_DOUBLE : minimal value of the parameter, MANDATORY for in parameters, OPTIONAL for out parameters.

  • max : LIVIDO_ATOM_TYPE_DOUBLE : maximal value of the parameter, MANDATORY for in parameters, OPTIONAL for out parameters.

  • wrap : LIVIDO_ATOM_TYPE_BOOLEAN : indicates that the "value" should wraped when going below min or above max, OPTIONAL

  • transition : LIVIDO_ATOM_TYPE_BOOLEAN : Indicates that this parameter is transition, OPTIONAL

  • "TEXT"

Kind text means a string, which can be used for passing strings.
The default property can only be of atom type LIVIDO_ATOM_TYPE_STRING.

  • "SWITCH"

Kind switch can be used for passing yes/no choices.
The default property can only be of atom type LIVIDO_ATOM_TYPE_BOOLEAN.

  • "COLOR_RGBA"

Kind color can be used for passing colors. Colors are represented as a list of 3 or 4 elements of type LIVIDO_ATOM_TYPE_DOUBLE. Depending on the default value, host knows if it has to pass 3 or 4 elements in the list to filter. Values of elements consecutively are red, green, blue and alpha, values are generally between 0.0 and 1.0.ccc
Additional properties that kind causes:

  • min : LIVIDO_ATOM_TYPE_DOUBLE array of N elements: minimal value of the parameter, MANDATORY

  • max : LIVIDO_ATOM_TYPE_DOUBLE array of N elements: maximal value of the parameter, MANDATORY

  • "COORDINATE"

Kind coordinate can be used for passing 2d normalized cartesian coordinats. Coordinates are represented as a list of 2 elements of type LIVIDO_ATOM_TYPE_DOUBLE. First value in a list presents an x coordinate and second one y in cartesian coordinates, coordinates inside the picture they relate to are considered to be between 0.0 and 1.0
The default property can only be of atom type LIVIDO_ATOM_TYPE_DOUBLE and an array of 2 elements.
Additional properties that kind causes:

  • min : LIVIDO_ATOM_TYPE_DOUBLE array of 2 elements: minimal value of the parameter, MANDATORY

  • max : LIVIDO_ATOM_TYPE_DOUBLE array of 2 elements: maximal value of the parameter, MANDATORY

###PORT TYPE PARAMETER
Port type parameter is used for passing a single (input or output) . Input parameters are HOSTSET and output parameters are PLUGINSET. Parameters should be a one-one match with channel templates (same order, same number).

Mandatory properties:

  • "parent_template" : LIVIDO_ATOM_TYPE_PORT : Pointer to a parameter template port this parameter instance is based on

  • "value" : type of the value MUST match the type of default property of the parent_template

###GETTING/SETTING PROPERTY VALUES
On livido_property_set(), the host/plugin programmer does not need to worry about allocating and freeing memory for the data to store. The model (or more precisely the Mediation layer) will take care of that for you. If you store an object the model will make a copy and store that. Later, when you set a new value in this property, the model will automatically livido_free() the old value and make a copy of the new value and store the copy.

The exception to this is any atom type of type PTR. If you allocate a chunk of data or a complex structure only the pointer value is stored (!). The model does not know anything about the content of the data your pointer refers to so it will not make a copy. Instead, you need to allocate and free the memory yourself in this case.

The plugin and host programmer can both retrieve and set values by Key.

On livido_property_get(), Livido will copy the data stored in the property, except for pointer types. For pointer types only the reference to the memory block is copied. The programmer should first allocate a memory area for livido_property_get() to copy to.

For setting pointer types, host/plugin must pass in a size_t array with the atom sizes.

###LIVIDO CORE FUNCTIONS
All host implementations must implement and offer the following core functions. The functions reside inside a host and plugin dynamically links to them upon loading.

  • livido_port_t *livido_port_new (int port_type)

  • void livido_port_free (livido_port_t *port) // only used by host

  • char *livido_list_properties (livido_port_t port) // returns NULL terminated char * array of properties

  • int livido_property_set (livido_port_t port, const char key, int atom_type, int num_elems, void *value) // returns a livido error

  • int livido_property_get (livido_port_t port, const char key, int idx, void *value) // returns a livido error

  • int livido_property_num_elements (livido_port_t port, const char key)

  • size_t livido_property_element_size (livido_port_t port, const char key, int idx)

  • int livido_property_atom_type(livido_port_t port, const char key)

  • void *livido_malloc_f (size_t size)

  • void livido_free_f (void *ptr)

  • void livido_memset_f (void s, int c, size_t n)

  • void livido_memcpy_f (void dest, const void *src, size_t n)

Notes:

livido_port_new() will set the "type" property to port_type, and will set it readonly.

livido_property_set() will create the property if the property does not exist.

livido_property_set() will return LIVIDO_ERROR_PROPERTY_READONLY if the property has the flag bit LIVIDO_PROPERTY_READONLY set.

livido_property_set() will return an error LIVIDO_ERROR_WRONG_ATOM_TYPE if you try to change the atom_type of a property.

For livido_property_set(), num_elems can be 0 and value can then be NULL. In this way, just the atom_type of the property can be set.

The sizes field of livido_property_set() is only used for pointer type values. It should be an array of size num_elems. For fundamental types, the sizes field should be set to NULL.

livido_property_get() will return LIVIDO_ERROR_NOSUCH_PROPERTY if a property does not exist. In this way the existence of a property can be determined. To assist with this, livido_property_get() can be called with a NULL void * value. The function will then not attempt to copy the value, but will return either LIVIDO_ERROR_NOSUCH_PROPERTY, or LIVIDO_NO_ERROR depending on whether the property exists or not.

The return values of livido_property_num_elements(), livido_property_element_size(), livido_property_atom_type(), and livido_property_get_readonly() are all undefined if the property does not exist.

The void for livido_property_set() and livido_property_get() is a (void ) typecast to/from an array of the appropriate type:
e.g. for LIVIDO_ATOM_TYPE_INT it is an int *. The number of elements in the array must match num_elems in livido_property_set().

Functions livido_malloc_f(), livido_free_f(), livido_memset_f(), livido_memcpy_f() have exactly the same semantics as malloc, free(), memset() and memcpy() from libc. Their purpose is to allow a host to provide a plugin with the application-specific memory managment. Plugins MUST NOT use malloc, free and memset, but have to use livido counterparts.

###PLUGIN FUNCTIONS
The only symbol plugin MUST export is livido_setup() function pointer, all other information is passed through respective ports (classes, functions, etc...)

livido_setup

livido_port_t *livido_setup(void);  

This function returns a PLUGIN INFO port that specifies what is the content of this plugin - which filter classes it has, who is the maintainer, etc.

Plugin implements livido_setup() in following way: the PLUGIN INFO port is first created by using livido_port_new().
The individual filters are then created and added to the property "filters" in the PLUGIN INFO port.
If no filters can be created (because of memory or other problems), the function should return NULL.

The returned port MUST have type LIVIDO_PORT_TYPE_PLUGIN_INFO.

init_func

int init_func(livido_port_t *)  

The port MUST have type LIVIDO_PORT_TYPE_FILTER_INSTANCE

The host calls this and passes in the desired filter.
The filter port instance passed to the init_func MUST have been correctly setup to match the filter class it relats to, this means that all the mandatory properties of input and output channels and of input parameters MUST be set.
The function returns a livido error code (see below).

The initfunc() function allows the plugin to create any internal memory structures it needs; plugin store internal data as properties that have keys prefixed with "PLUGIN" (see the definition of filter intance port)

process_func

int process_func(livido_port_t *, double timestamp)  

The port MUST have type LIVIDO_PORT_TYPE_FILTER_INSTANCE

host calls this for each processing cycle; the plugin can do its frame processing here. The function returns a livido error code (see below). Timestamp is the presentation time in seconds (can be e.g. time since playback start). The function returns a livido error code (see below).

deinit_func

int deinit_func(livido_port_t *)  

The port MUST have type LIVIDO_PORT_TYPE_FILTER_INSTANCE

host calls this to allow the plugin to free() any internal memory. Following this the host may free() the instance's port. The plugin does not need to free any ports or parameters, the host should take care of this.c

###OUTLINE LIVIDO PROCESS FLOW OVERVIEW

  • Host loads plugin (dlopen)

  • Host calls the livido_setup() function.

  • in livido_setup(), for each filter class, the plugin creates and initializes the port of a type LIVIDO_PORT_TYPE_FILTER_CLASS and adds it to the filter_list property of the returned port.

  • Host creates a FILTER_INSTANCE: Host examines the in_channel and out_channel ports, and sets the "disabled" flag for any optional channels it does not wish 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. All input parameters have to have values set at this point. This means host now has a port that it will instantiate.

  • Host calls init_func() from the filter info port, passing a pointer to a FILTER_INSTANCE it would like to instantiate.

  • Plugin now knows the channel sizes, palettes and which channels are in use. The plugin may now livido_malloc() internal data.

  • Host may now change parameter values (respecting "max" and "min" properties) and it after that it may call process_func() in the plugin, passing in the initialised FILTER_INSTANCE.

  • When the host has finished with the FILTER_INSTANCE, or if it needs to re-initialise it, the host must call deinit_func() in the plugin, passing in a pointer to the FILTER_INSTANCE. The plugin MUST now livido_free() any internally allocated data.

  • Host can now livido_port_free() the FILTER_INSTANCE, or it can adjust the non-final properties of the ports used and reuse the FILTER_INSTANCE by calling init_func() once more.

###LIVIDO FLAGS AND TYPES

Livido palette types

Palettes are all unsigned in LiViDO.

Some palettes have aliases; these are shown on the same line.

RGB Palettes
Palette numbers >0 and <512

LIVIDO_PALETTE_RGB888         LIVIDO_PALETTE_RGB24  
LIVIDO_PALETTE_BGR888         LIVIDO_PALETTE_BGR24  
LIVIDO_PALETTE_RGBA8888       LIVIDO_PALETTE_RGBA32  
LIVIDO_PALETTE_ARGB8888       LIVIDO_PALETTE_ARGB32  
LIVIDO_PALETTE_RGBFLOAT  
LIVIDO_PALETTE_RGBAFLOAT  
LIVIDO_PALETTE_RGB565  

YUV Palettes
Palette numbers >=512 and <1024

Ranges are 16-235 for Y, 16 - 240 for U and V.

LIVIDO_PALETTE_YUV422P           LIVIDO_PALETTE_YV16  
[Official name 'YV16', 8 bit Y plane followed by 8  
bit 2x1 subsampled V and U planes. Planar.]  

LIVIDO_PALETTE_YUV420P           LIVIDO_PALETTE_YV12  
[8 bit Y plane followed by 8 bit 2x2 subsampled V and U planes. Planar  
(Official name YV12)]  

LIVIDO_PALETTE_YVU420P           LIVIDO_PALETTE_I420  
[Same as YUV420P , but U and V are swapped. Planar.]  

LIVIDO_PALETTE_YUV444P  
[Unofficial , 8 bit Y plane followed by 8 bit U and V planes, no  
subsampling. Planar.]  

LIVIDO_PALETTE_YUVA4444P         LIVIDO_PALETTE_YUV4444P  
[Unofficial, like YUV444P but with Alpha. Planar.]  

LIVIDO_PALETTE_YUYV8888  
[Like YUV 4:2:2 but with different component ordering within the  
u_int32 macropixel. Packed.]  

LIVIDO_PALETTE_UYVY8888  
[YUV 4:2:2 (Y sample at every pixel, U and V sampled at every second  
pixel horizontally on each line). A macropixel contains 2 pixels in 1  
u_int32. Packed.]  

LIVIDO_PALETTE_YUV411  
[IEEE 1394 Digital Camera 1.04 spec. Is packed YUV format  
with a 6 pixel macroblock structure containing 4 pixels.  
Ordering is U2 Y0 Y1 V2 Y2 Y3. Uses same bandwith as YUV420P  
Only used for SMPTE DV NTSC.]  

Alpha Palettes
Palette numbers >=1024 and <2048

Alpha palettes have two uses: 1) for masks, 2) to split colour inputs into single colour channels, or to combine single colour channels into a combined channel. The order of colour channels is the same as the order in the combined channel. For example if an input in RGB24 palette is split into 3 non-mask alpha channels, then the alpha channels will be in the order: Red, Green, Blue. A single non-mask alpha channel would represent the luminance.

LIVIDO_PALETTE_A1  
LIVIDO_PALETTE_A8  
LIVIDO_PALETTE_AFLOAT  

Palette numbers >=2048 are available for custom palettes.

Filter flags

  • LIVIDO_FILTER_NON_REALTIME

non-realtime filter property: the filter is too slow to use in realtime processing.

  • LIVIDO_FILTER_CAN_DO_INPLACE

If this property is set, the filter can do inplace operations.
Hosts can select this mode by setting "pixel_data" for the first out_channel to NULL.
Plugin will then return the output in "pixel_data" of the first in_channel.
This can save a memcpy() in the host.

  • LIVIDO_FILTER_STATEFUL

plugin is stateful ; it has information about what occurred previously. I.e. it has internal state data.

  • LIVIDO_FILTER_IS_CONVERTER

This flag bit should be set if the plugin does not alter the image pixels except for resizing or palette conversion between in channel and out channel(s). It should only be set for the following types of plugins: plugins which only resize the in frame to out frame(s); plugins which only convert the palette from in frame to out frame(s), plugins which simply duplicate the in frame to out frame(s). It is used to assist with categorisation of the plugin type.

Flag bits >=30 are available for custom flags.

Channel flags

  • LIVIDO_CHANNEL_CHANGE_UNADVISED

plugin MAY use this flag to tell the host, that changing of channel size causes possibly unwanted behaviour of the filter. Unwanted behaviour can for example be reseting the accumulated values which causes the visual result of filter to change in unexpected way or maybe the next call to process function will take disproportional amount of time due to reinitialization. Host is safe to ignore the flag and plugin MUST still be useful, though functionality may suffer.

  • LIVIDO_CHANNEL_PALETTE_UNADVISED

plugin MAY use this flag to tell the host, that changing of channel palette causes possibly unwanted behaviour of the filter. Unwanted behaviour can for example be reseting the accumulated values which causes the visual result of filter to change in unexpected way or maybe the next call to process function will take disproportional amount of time due to reinitialization. Host is safe to ignore the flag and plugin MUST still be useful, though functionality may suffer.

Flag bits >=30 are available for custom flags.

Parameter flags

  • LIVIDO_PARAMETER_CHANGE_UNADIVSED

plugin MAY use this flag to tell the host, that changing of this parameter causes possibly unwanted behaviour of the filter. Unwanted behaviour can for example be reseting the accumulated values which causes the visual result of filter to change in unexpected way or maybe the next call to process function will take disproportional amount of time due to reinitialization. Host is safe to ignore the flag and plugin MUST still be useful, though functionality may suffer.

Flag bits >=30 are available for custom flags.

Property flags

  • LIVIDO_PROPERTY_READONLY

Flag bits >=30 are available for custom flags.

YUV sampling types

  • LIVIDO_YUV_SAMPLING_NONE : No subsampling (always YUV 4:4:4)

  • LIVIDO_YUV_SAMPLING_SMPTE : Chroma is sampled at half the horizontal frequency and is aligned horizontally with luma samples (YUV 4:2:2)

  • LIVIDO_YUV_SAMPLING_JPEG : Chroma is sampled at half the horizontal and half the vertical frequency. (YUV 4:2:0). Chroma samples are centered between luma samples.

  • LIVIDO_YUV_SAMPLING_MPEG2 : Same as JPEG, but Chroma samples are horizontally aligned and vertically centered between luma samples. There is notion of fields. (YUV 4:2:0)

  • LIVIDO_YUV_SAMPLING_DVPAL : Subsampling per field, Chroma samples are located above luma samples, but CB and CR samples are located on alternate lines (YUV 4:2:0)

  • LIVIDO_YUV_SAMPLING_DVNTSC : Chroma is sampled at 1/4 the horizontal frequency as luma but at full vertical frequency. The chroma samples are horizontally aligned with luma samples. (YUV 4:1:1)

Sampling types >=1024 are available for custom samplings.

Interlace types

  • LIVIDO_INTERLACE_NONE

  • LIVIDO_INTERLACE_TOPFIRST

  • LIVIDO_INTERLACE_BOTTOMFIRST

  • LIVIDO_INTERLACE_PROGRESSIVE

Interlace types >=1024 are available for custom interlacing.

###Livido errors

  • LIVIDO_NO_ERROR

return code means no problem

  • LIVIDO_ERROR_MEMORY_ALLOCATION

memory allocation by the filter has failed

  • LIVIDO_ERROR_PROPERTY_READONLY

plugin/host tried to set readonly property; returned from livido_property_set()

  • LIVIDO_ERROR_NOSUCH_ELEMENT

plugin/host tried to read value of an invalid element number in a property; returned from livido_property_get()

  • LIVIDO_ERROR_NOSUCH_PROPERTY

property does not exist for the specified port; returned from livido_property_get()

  • LIVIDO_ERROR_WRONG_ATOM_TYPE

once the atom_type of a property is set, you cannot change it. livido_property_set() will return this error if you attempt such a thing, and the value of the property will not be amended.

  • LIVIDO_ERROR_TOO_MANY_INSTANCES

can't create: plugin allows only limited number of filter instances, returned from init_func()

  • LIVIDO_ERROR_HARDWARE

there was an error initialising hardware for the filter; returned from init_func()

Error numbers >=1024 are available for custom errors.

###livido.h

/* LiViDO is free software; you can redistribute it and/or  
modify it under the terms of the GNU Lesser General Public  
License as published by the Free Software Foundation; either  
version 2.1 of the License, or (at your option) any later version.  

LiViDO is distributed in the hope that it will be useful,  
but WITHOUT ANY WARRANTY; without even the implied warranty of  
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  
Lesser General Public License for more details.  

You should have received a copy of the GNU Lesser General Public  
License along with this source code; if not, write to the Free Software  
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  

LiViDO is developed by:  

Niels Elburg - http://veejay.sf.net  

Gabriel "Salsaman" Finch - http://lives.sourceforge.net  

Denis "Jaromil" Rojo - http://freej.dyne.org  

Tom Schouten - http://zwizwa.fartit.com  

Andraz Tori - http://cvs.cinelerra.org  

reviewed with suggestions and contributions from:  

Silvano "Kysucix" Galliani - http://freej.dyne.org  

Kentaro Fukuchi - http://megaui.net/fukuchi  

Jun Iio - http://www.malib.net  

Carlo Prelz - http://www2.fluido.as:8080/  

*/  

/* (C) Gabriel "Salsaman" Finch, Niels Elburg, Dennis "Jaromil" Rojo, 2005 */  

* ifndef __LIVIDO_H__  
* define __LIVIDO_H__  

* ifdef __cplusplus  
extern "C"  
{  
* endif /* __cplusplus */  

* define LIVIDO_API_VERSION 1  

/* Palette types */  
/* RGB palettes */  
* define LIVIDO_PALETTE_RGB888 1  
* define LIVIDO_PALETTE_RGB24 1  
* define LIVIDO_PALETTE_BGR888 2  
* define LIVIDO_PALETTE_BGR24 2  
* define LIVIDO_PALETTE_RGB161616 3  
* define LIVIDO_PALETTE_RGB48 3  
* define LIVIDO_PALETTE_BGR161616 4  
* define LIVIDO_PALETTE_BGR48 4  
* define LIVIDO_PALETTE_RGBA8888 5  
* define LIVIDO_PALETTE_RGBA32 5  
* define LIVIDO_PALETTE_ABGR8888 6  
* define LIVIDO_PALETTE_ABGR32 6  
* define LIVIDO_PALETTE_RGBA161616 7  
* define LIVIDO_PALETTE_RGBA64 7  
* define LIVIDO_PALETTE_ABGR161616 8  
* define LIVIDO_PALETTE_ABGR64 8  
* define LIVIDO_PALETTE_ARGB8888 9  
* define LIVIDO_PALETTE_ARGB32 9  
* define LIVIDO_PALETTE_BGRA8888 10  
* define LIVIDO_PALETTE_BGRA32 10  
* define LIVIDO_PALETTE_ARGB161616 11  
* define LIVIDO_PALETTE_ARGB64 11  
* define LIVIDO_PALETTE_BGRA161616 12  
* define LIVIDO_PALETTE_BGRA64 12  
* define LIVIDO_PALETTE_RGBFLOAT 13  
* define LIVIDO_PALETTE_BGRFLOAT 14  
* define LIVIDO_PALETTE_RGBAFLOAT 15  
* define LIVIDO_PALETTE_ABGRFLOAT 16  
* define LIVIDO_PALETTE_ARGBFLOAT  17  
* define LIVIDO_PALETTE_BGRAFLOAT 18  
* define LIVIDO_PALETTE_RGB565 19  
* define LIVIDO_PALETTE_BGR565 20  

/* YUV palettes */  
* define LIVIDO_PALETTE_YUV422P 513  
* define LIVIDO_PALETTE_YV16 513  
* define LIVIDO_PALETTE_YUV420P 514  
* define LIVIDO_PALETTE_YV12 514  
* define LIVIDO_PALETTE_YVU420P 515  
* define LIVIDO_PALETTE_I420 515  
* define LIVIDO_PALETTE_YUV444P 516  
* define LIVIDO_PALETTE_YUVA4444P 517  
* define LIVIDO_PALETTE_YUV4444P 517  
* define LIVIDO_PALETTE_YUYV8888 518  
* define LIVIDO_PALETTE_UYVY8888 519  
* define LIVIDO_PALETTE_YUV411 520  

/* Alpha palettes */  
* define LIVIDO_PALETTE_A1 1025  
* define LIVIDO_PALETTE_A2 1026  
* define LIVIDO_PALETTE_A4 1027  
* define LIVIDO_PALETTE_A8 1028  
* define LIVIDO_PALETTE_A16 1029  
* define LIVIDO_PALETTE_AFLOAT 1030  

/* Filter flags */  
* define LIVIDO_FILTER_NON_REALTIME    (1<<0)  
* define LIVIDO_FILTER_CAN_DO_INPLACE  (1<<1)  
* define LIVIDO_FILTER_CAN_DO_SCALED   (1<<2)  
* define LIVIDO_FILTER_CAN_DO_VIEWPORT (1<<3)  
* define LIVIDO_FILTER_SELF_AUTOMATION (1<<4)  
* define LIVIDO_FILTER_FPS_NEEDED      (1<<5)  
* define LIVIDO_FILTER_STATELESS       (1<<6)  

/* Channel flags */  
* define LIVIDO_CHANNEL_MASK (1<<0)  
* define LIVIDO_CHANNEL_HOST_CAN_RESIZE (1<<1)  
* define LIVIDO_CHANNEL_HOST_CAN_CHANGE_PALETTE (1<<2)  

/* Parameter flags */  
* define LIVIDO_PARAMETER_NEEDS_REINIT (1<<0)  

/* Property flags */  
* define LIVIDO_PROPERTY_READONLY (1<<0)  

/* YUV sampling types */  
* define LIVIDO_YUV_SAMPLING_NONE 0  
* define LIVIDO_YUV_SAMPLING_SMPTE 1  
* define LIVIDO_YUV_SAMPLING_JPEG 2  
* define LIVIDO_YUV_SAMPLING_MPEG2 3  
* define LIVIDO_YUV_SAMPLING_DVPAL 4  
* define LIVIDO_YUV_SAMPLING_DVNTSC 5  

/* Interlace types */  
* define LIVIDO_INTERLACE_NONE            0  
* define LIVIDO_INTERLACE_TOPFIRST        1  
* define LIVIDO_INTERLACE_BOTTOMFIRST     2  
* define LIVIDO_INTERLACE_PROGRESSIVE     3  

/* Viewport types */  
* define LIVIDO_VIEWPORT_RECTANGLE 1  
* define LIVIDO_VIEWPOERT_POLYGON 2  
* define LIVIDO_VIEWPORT_CIRCLE 3  
* define LIVIDO_VIEWPORT_OVAL 4  
* define LIVIDO_VIEWPORT_TRIANGLE 5  

/* Colorkey colorspaces */  
* define LIVIDO_COLORKEY_RGB  0  
* define LIVIDO_COLORKEY_HSV  1  
* define LIVIDO_COLORKEY_HSL  2  
* define LIVIDO_COLORKEY_CMYK 3  

/* Livido errors */  
/* Core errors */  
* define LIVIDO_NO_ERROR 0  
* define LIVIDO_ERROR_MEMORY_ALLOCATION 1  
* define LIVIDO_ERROR_PROPERTY_READONLY 2  
* define LIVIDO_ERROR_NOSUCH_ELEMENT 3  
* define LIVIDO_ERROR_NOSUCH_PROPERTY 4  
* define LIVIDO_ERROR_WRONG_ATOM_TYPE 5  

/* Plugin errors */  
* define LIVIDO_ERROR_TOO_MANY_INSTANCES 6  
* define LIVIDO_ERROR_HARDWARE 7  

/* Atom types */  
/* Fundamental atoms */  
* define LIVIDO_ATOM_TYPE_INT 1  
* define LIVIDO_ATOM_TYPE_FLOAT 2  
* define LIVIDO_ATOM_TYPE_LONG 3  
* define LIVIDO_ATOM_TYPE_BOOLEAN 4  
* define LIVIDO_ATOM_TYPE_STRING 5  

/* Pointer atoms */  
* define LIVIDO_ATOM_TYPE_VOIDPTR 65  
* define LIVIDO_ATOM_TYPE_UINT8PTR 66  
* define LIVIDO_ATOM_TYPE_UINT16PTR 67  
* define LIVIDO_ATOM_TYPE_UINT32PTR 68  
* define LIVIDO_ATOM_TYPE_FLOATPTR 69  
* define LIVIDO_ATOM_TYPE_FILTERPTR 70  
* define LIVIDO_ATOM_TYPE_PORTPTR 71  

/* Port types */  
* define LIVIDO_PORT_TYPE_FILTER_LIST 1  
* define LIVIDO_PORT_TYPE_INFO 2  
* define LIVIDO_PORT_TYPE_CHANNEL 3  
* define LIVIDO_PORT_TYPE_PARAMETER 4  
* define LIVIDO_PORT_TYPE_KEYFRAME 5  
* define LIVIDO_PORT_TYPE_GUI 6  

/* Parameter port hints */  
* define NUMBER 1  
* define TEXT 2  
* define SWITCH 3  
* define LIST 4  
* define CHOICE 5  
* define COLORKEY 6  
* define COORDINATE 7  
* define TRANSITION 8  

extern void *livido_malloc_f (size_t size);  
extern void livido_free_f (void *ptr);  
extern void *livido_memset_f (void *s, int c, size_t n);  
extern void *livido_memcpy_f (void *dest, const void *src, size_t n);  

* ifndef HAVE_LIVIDO_PORT_T  
* define HAVE_LIVIDO_PORT_T  

typedef struct livido_property livido_property_t;  
typedef livido_property_t livido_port_t;  

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

typedef struct livido_storage {  
int num_elements;  
int atom_type;  
union {  
livido_atom_t *atom;  
livido_atom_t **array;  
};  
} livido_storage_t;  

struct livido_property {  
const char *key;  
livido_storage_t *data;  
int flags;  
livido_property_t *next;  
};  

* endif  

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;  

extern void livido_port_free (livido_port_t *prop);  
extern livido_port_t *livido_port_new(int port_type);  
extern char **livido_list_properties(livido_port_t *port);  
extern int livido_property_set(livido_port_t *port, const char *key, int atom_type, int num_elems, void *value, size_t *size);  
extern int livido_property_get(livido_port_t *port, const char *key, int idx, void *value);  
extern int livido_property_num_elements(livido_port_t *port, const char *key);  
extern int livido_property_element_size(livido_port_t *port, const char *key, int idx);  
extern int livido_property_atom_type(livido_port_t *port, const char *key);  
extern int livido_property_set_readonly(livido_port_t *port, const char *key);  
extern int livido_property_get_readonly(livido_port_t *port, const char *key);  

* ifdef __cplusplus  
}  
* endif /* __cplusplus */  

* endif // #ifndef __LIVIDO_H__  

###livido.c
This is a reference implementation of the livido core library. It will eventually be made into a library which can be linked in at compile time.

Code

/* LiViDO is free software; you can redistribute it and/or  
modify it under the terms of the GNU Lesser General Public  
License as published by the Free Software Foundation; either  
version 2.1 of the License, or (at your option) any later version.  

LiViDO is distributed in the hope that it will be useful,  
but WITHOUT ANY WARRANTY; without even the implied warranty of  
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  
Lesser General Public License for more details.  

You should have received a copy of the GNU Lesser General Public  
License along with this source code; if not, write to the Free Software  
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA  

LiViDO is developed by:  

Niels Elburg - http://veejay.sf.net  

Gabriel "Salsaman" Finch - http://lives.sourceforge.net  

Denis "Jaromil" Rojo - http://freej.dyne.org  

Tom Schouten - http://zwizwa.fartit.com  

Andraz Tori - http://cvs.cinelerra.org  

reviewed with suggestions and contributions from:  

Silvano "Kysucix" Galliani - http://freej.dyne.org  

Kentaro Fukuchi - http://megaui.net/fukuchi  

Jun Iio - http://www.malib.net  

Carlo Prelz - http://www2.fluido.as:8080/  

*/  

/* (C) Gabriel "Salsaman" Finch, Niels Elburg, Dennis "Jaromil" Rojo, 2005 */  

* include <string.h>  
* include <sys/types.h>  

static inline int livido_atom_type_is_ptr (int atom_type) {  
return (atom_type==LIVIDO_ATOM_TYPE_VOIDPTR||atom_type==LIVIDO_ATOM_TYPE_PORTPTR||\  
atom_type==LIVIDO_ATOM_TYPE_FILTERPTR)?1:0;  
}  

static inline size_t livido_atom_type_get_size (int atom_type, void *value) {  
return livido_atom_type_is_ptr (atom_type)?0:\  
(atom_type==LIVIDO_ATOM_TYPE_BOOLEAN||atom_type==LIVIDO_ATOM_TYPE_INT)?sizeof(int):\  
(atom_type==LIVIDO_ATOM_TYPE_FLOAT)?sizeof(float):\  
(atom_type==LIVIDO_ATOM_TYPE_LONG)?sizeof(long):\  
(atom_type==LIVIDO_ATOM_TYPE_STRING)?strlen((const char *)value):0;  
}  

static inline void livido_atom_free(livido_atom_t *atom, int atom_type) {  
if (!livido_atom_type_is_ptr(atom_type)) livido_free_f (atom->value);  
livido_free_f (atom);  
}  

static inline livido_atom_t *livido_atom_new(void *value, int atom_type, size_t size) {  
livido_atom_t *atom=(livido_atom_t *)livido_malloc_f(sizeof(livido_atom_t));  
if (atom==NULL) return NULL;  
if (livido_atom_type_is_ptr(atom_type)) {  
atom->size=size;  
livido_memcpy_f (&atom->value,value,sizeof(void *));  
}  
else {  
if (atom_type==LIVIDO_ATOM_TYPE_STRING) {  
char ** valuecharptrptr=(char **)value;  
atom->size=livido_atom_type_get_size(atom_type,*valuecharptrptr);  
}  
else atom->size=livido_atom_type_get_size(atom_type,value);  
atom->value=livido_malloc_f(atom->size);  
if (atom->value==NULL) {  
livido_free_f (atom);  
return NULL;  
}  
if (atom_type==LIVIDO_ATOM_TYPE_STRING) {  
char ** valuecharptrptr=(char **)value;  
livido_memcpy_f (atom->value,*valuecharptrptr,atom->size);  
}  
else livido_memcpy_f (atom->value,value,atom->size);  
}  
return atom;  
}  

static inline void livido_storage_free(livido_storage_t *store) {  
register int i;  
if (store->num_elements==1) livido_atom_free(store->atom,store->atom_type);  
else for (i=0;i<store->num_elements;i++) livido_atom_free(store->array[i],store->atom_type);  
}  

static inline livido_storage_t *livido_storage_new(int atom_type, int num_elems, void *value, size_t *sizes) {  
livido_storage_t *store=(livido_storage_t *)livido_malloc_f(sizeof(livido_storage_t));  
if (store==NULL) return NULL;  
store->num_elements=num_elems;  
store->atom_type=atom_type;  
if (num_elems==0) store->atom=NULL;  
else {  
if (num_elems==1) {  
if ((store->atom=livido_atom_new (value, atom_type, livido_atom_type_is_ptr(atom_type)?sizes[0]:0))==NULL) {  
livido_free_f (store);  
return NULL;  
}  
}  
else {  
register int i;  
void **valuevoidptrptr=(void **)value;  
if ((store->array=(livido_atom_t **)livido_malloc_f(num_elems*sizeof(livido_atom_t *)))==NULL) {  
livido_free_f (store);  
return NULL;  
}  
for (i=0;i<num_elems;i++) {  
if (livido_atom_type_is_ptr(atom_type)) store->array[i]=livido_atom_new(&valuevoidptrptr[i],atom_type,sizes[i]);  
else {  
if (atom_type==LIVIDO_ATOM_TYPE_STRING) store->array[i]=livido_atom_new(valuevoidptrptr[i],atom_type,0);  
else store->array[i]=livido_atom_new(&valuevoidptrptr[i],atom_type,0);  
}  
if (store->array[i]==NULL) { // memory error  
for (--i;i>=0;i--) livido_free_f (store->array[i]);  
livido_free_f (store);  
return NULL;  
}  
}  
}  
}  
return store;  
}  

static inline livido_property_t *livido_find_property(livido_port_t *prop, const char *key) {  
while (prop!=NULL) {  
if (!strcmp((char *)prop->key,(char *)key)) return prop;  
prop=prop->next;  
}  
return NULL;  
}  

static inline livido_storage_t *livido_get_storage_for(livido_port_t *port, const char *key) {  
livido_property_t *prop=livido_find_property (port,key);  
if (prop==NULL) return NULL;  
return prop->data;  
}  

static inline livido_atom_t *livido_get_atom_from_storage(livido_storage_t *store, int idx) {  
if (idx>store->num_elements||store->num_elements==0) return NULL;  
if (store->num_elements==1) return store->atom;  
return store->array[idx];  
}  

static inline void livido_property_free(livido_property_t *prop) {  
livido_storage_t *store=prop->data;  
if (store==NULL) return;  
livido_storage_free (store);  
livido_free_f ((char *)prop->key);  
}  

static inline livido_property_t *livido_property_new(const char *key) {  
size_t lstrlen;  
livido_property_t *prop=(livido_property_t *)livido_malloc_f(sizeof(livido_property_t));  
if (prop==NULL) return NULL;  
if ((prop->key=(char *)livido_malloc_f((lstrlen=(strlen(key)+1))))==NULL) {  
livido_free_f (prop);  
return NULL;  
}  
livido_memcpy_f ((char *)prop->key,key,lstrlen);  
prop->data=NULL;  
prop->next=NULL;  
prop->flags=0;  
return prop;  
}  

static inline void livido_property_append(livido_port_t *prop,livido_property_t *newprop) {  
livido_property_t *propnext;  
while (prop!=NULL) {  
propnext=prop->next;  
if (propnext==NULL) {  
prop->next=newprop;  
return;  
}  
prop=propnext;  
}  
}  

void livido_port_free(livido_port_t *prop) {  
livido_property_t *propnext;  
while (prop!=NULL) {  
propnext=prop->next;  
livido_property_free (prop);  
prop=propnext;  
}  
}  

livido_port_t *livido_port_new(int port_type) {  
livido_property_t *prop;  
size_t size=livido_atom_type_get_size(LIVIDO_ATOM_TYPE_INT,NULL);  
if ((prop=livido_property_new("type"))==NULL) return NULL;  
if ((prop->data=livido_storage_new (LIVIDO_ATOM_TYPE_INT,1,&port_type,&size))==NULL) {  
livido_free_f ((char *)prop->key);  
livido_free_f (prop);  
return NULL;  
}  
prop->next=NULL;  
livido_property_set_readonly (prop,"type");  
return prop;  
}  

char **livido_list_properties(livido_port_t *port) {  
livido_property_t *prop=port;  
char **proplist;  
register int i=1;  
size_t lstrlen;  
for (;prop!=NULL;i++) {  
prop=prop->next;  
}  
if ((proplist=(char **)livido_malloc_f(i*sizeof(char *)))==NULL) return NULL;  
i=0;  
for (prop=port;prop!=NULL;prop=prop->next) {  
if ((proplist[i]=(char *)livido_malloc_f((lstrlen=strlen(prop->key))+1))==NULL) {  
for (--i;i>=0;i--) livido_free_f (proplist[i]);  
livido_free_f (proplist);  
return NULL;  
}  
livido_memcpy_f (proplist[i],prop->key,lstrlen);  
livido_memset_f (proplist[i++]+lstrlen,0,1);  
}  
proplist[i]=NULL;  
return proplist;  
}  

int livido_property_set(livido_port_t *port, const char *key, int atom_type, int num_elems, void *value, size_t *size) {  
livido_storage_t *store;  
livido_property_t *prop=livido_find_property (port,key);  
if (prop==NULL) {  
if ((prop=livido_property_new (key))==NULL) return LIVIDO_ERROR_MEMORY_ALLOCATION;  
livido_property_append (port,prop);  
}  
else {  
if (prop->flags&LIVIDO_PROPERTY_READONLY) return LIVIDO_ERROR_PROPERTY_READONLY;  
if (atom_type!=prop->data->atom_type) return LIVIDO_ERROR_WRONG_ATOM_TYPE;  
livido_storage_free (prop->data);  
prop->data=NULL;  
}  
if ((store=livido_storage_new (atom_type,num_elems,value,size))==NULL) {  
return LIVIDO_ERROR_MEMORY_ALLOCATION;  
}  
prop->data=store;  
return LIVIDO_NO_ERROR;  
}  

int livido_property_get(livido_port_t *port, const char *key, int idx, void *value) {  
livido_atom_t *atom;  
livido_storage_t *store=livido_get_storage_for (port,key);  
if (store==NULL) return LIVIDO_ERROR_NOSUCH_PROPERTY;  
if ((atom=livido_get_atom_from_storage (store,idx))==NULL) return LIVIDO_ERROR_NOSUCH_ELEMENT;  
if (livido_atom_type_is_ptr (store->atom_type)) livido_memcpy_f (value,&atom->value,sizeof(void *));  
else {  
if (store->atom_type==LIVIDO_ATOM_TYPE_STRING) {  
char **valuecharptrptr=(char **)value;  
livido_memcpy_f(*valuecharptrptr,atom->value,atom->size);  
livido_memset_f(*valuecharptrptr+atom->size,0,1);  
}  
else livido_memcpy_f (value,atom->value,atom->size);  
}  
return LIVIDO_NO_ERROR;  
}  

int livido_property_num_elements(livido_port_t *port, const char *key) {  
livido_storage_t *store=livido_get_storage_for (port, key);  
if (store==NULL) return 0;  
return store->num_elements;  
}  

int livido_property_element_size(livido_port_t *port, const char *key, int idx) {  
livido_atom_t *atom;  
livido_storage_t *store=livido_get_storage_for (port, key);  
if (store==NULL) return 0;  
if ((atom=livido_get_atom_from_storage (store, idx))==NULL) return 0;  
return atom->size;  
}  

int livido_property_atom_type(livido_port_t *port, const char *key) {  
livido_storage_t *store=livido_get_storage_for (port, key);  
if (store==NULL) return 0;  
return store->atom_type;  
}  

int livido_property_set_readonly(livido_port_t *port, const char *key) {  
livido_property_t *prop=livido_find_property (port, key);  
if (prop==NULL) return LIVIDO_ERROR_NOSUCH_PROPERTY;  
prop->flags|=LIVIDO_PROPERTY_READONLY;  
return LIVIDO_NO_ERROR;  
}  

int livido_property_get_readonly(livido_port_t *port, const char *key) {  
livido_property_t *prop=livido_find_property (port, key);  
if (prop==NULL) return 0;  
return prop->flags&LIVIDO_PROPERTY_READONLY;  
}  

###Sample code

###Section 1: Examples using only the core functions

Example 1.1: Creating and freeing a port

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  
if (filter!=NULL) livido_port_free (filter);  
return 1;  
}  

Example 1.2: Creating a port, setting and reading an int, and freeing the port

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
int in_int=55;  
int out_int;  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&in_int);  
livido_property_get (filter,"test",0,&out_int);  

printf ("test is %d\n",out_int);  

livido_port_free (filter);  
return 1;  
}  

Example 1.3: Creating a port, setting and retrieving a UTF-8 string, and freeing the port

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
char *in_string="LiViDO Test";  
char *out_string;  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_property_set (filter,"name",LIVIDO_ATOM_TYPE_STRING,1,&in_string,NULL);  

/* don't forget to add one byte for the terminating NULL */  
out_string=(char *)malloc(livido_property_element_size(info,"name",0)+1);  
livido_property_get (filter,"name",0,&out_string);  
printf ("name is %s\n",out_string);  

free (out_string);  

livido_port_free (filter);  
return 1;  
}  

Example 1.4: Storing a reference to pointer type, retrieving and copying

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
void *source_blob=malloc(1024);  
void *blob_ptr,*dest_blob;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_property_set (filter,"internal",LIVIDO_ATOM_TYPE_VOIDPTR,1,&source_blob);  
livido_property_get (filter,"internal",0,&blob_ptr);  

if (blob_ptr==source_blob) printf ("pointer was stored correctly\n");  
printf ("stored a pointer to a memory block %p\n",blob_ptr);  

free (source_blob);  
free (dest_blob);  

livido_port_free (filter);  
return 1;  
}  

Example 1.5: Setting and reading a double array

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
double in_doubles[3]={25.31,19.76,7.65};  
double out_doubles;  
int num_elements,i;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  
livido_property_set (filter,"double array",LIVIDO_ATOM_TYPE_DOUBLE,3,&in_doubles);  

num_elements=livido_property_num_elements (filter,"double array");  
printf ("stored an array with %d elements\n",num_elements);  

for (i=0;i<num_elements;i++) {  
livido_property_get (filter,"double array",i,&out_doubles);  
printf ("element %d is %.2f\n",i,out_doubles);  
}  

livido_port_free (filter);  
return 1;  
}  

Example 1.6: Setting and reading a pointer array

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
void *in_array[3];  
void *out_blob;  
int num_elements,i;  
size_t sizes[3]={128,256,1024};  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

in_array[0]=malloc(sizes[0]);  
in_array[1]=malloc(sizes[1]);  
in_array[2]=malloc(sizes[2]);  

printf ("ptrs are: %p %p %p\n",in_array[0],in_array[1],in_array[2]);  

livido_property_set (filter,"void array",LIVIDO_ATOM_TYPE_VOIDPTR,3,&in_array,sizes);  

num_elements=livido_property_num_elements (filter,"void array");  
printf ("stored an array with %d elements\n",num_elements);  

for (i=0;i<num_elements;i++) {  
livido_property_get (filter,"void array",i,&out_blob);  
printf ("element %d is %p\n",i,out_blob);  
}  

free (in_array[0]);  
free (in_array[1]);  
free (in_array[2]);  
livido_port_free (filter);  
return 1;  
}  

Example 1.7: Setting the type of a property without setting its value

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
int type;  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

/* set just the property type, without setting a value */  
livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,0,NULL);  

type=livido_property_atom_type (filter,"test");  

if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is an int property\n");  

livido_port_free (filter);  
return 1;  
}  

Example 1.8: Setting the type of a property, then trying to change it

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
int inint=5;  
int outint;  
int type;  
double mydouble=7.6;  
int error;  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_INFO);  

/* make "test" an int property */  
livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);  
type=livido_property_atom_type (filter,"test");  
livido_property_get (filter,"test",0,&outint);  

if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is an int property, its value is %d\n",outint);  

/* now we try to set a double in it, we should get an error */  
error=livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_DOUBLE,1,&mydouble);  

printf ("error was %d\n",error);  
if (error==LIVIDO_ERROR_WRONG_ATOM_TYPE) printf ("The type could not be changed !\n");  

type=livido_property_atom_type (filter,"test");  
livido_property_get (filter,"test",0,&outint);  

if (type==LIVIDO_ATOM_TYPE_INT) printf ("\"test\" is still an int property, its value is %d\n",outint);  

livido_port_free (filter);  
return 1;  
}  

Example 1.9 setting a property readonly

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  

int inint=5;  
int outint;  
int error;  
int is_rdonly;  
livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

/* make "test" an int property */  
livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);  
livido_property_get (filter,"test",0,&outint);  
is_rdonly=livido_property_get_readonly (filter,"test");  

printf ("The value of \"test\" is %d, readonly state is %d\n",outint,is_rdonly);  

/* now we set it readonly */  
livido_property_set_readonly (filter, "test");  

inint=7;  

/* now we try to change the value, we should get an error */  
error=livido_property_set (filter,"test",LIVIDO_ATOM_TYPE_INT,1,&inint);  
if (error==LIVIDO_ERROR_PROPERTY_READONLY) printf ("The property is readonly !\n");  

livido_property_get (filter,"test",0,&outint);  
is_rdonly=livido_property_get_readonly (filter,"test");  
printf ("The value of \"test\" is %d, readonly state is %d\n",outint,is_rdonly);  

livido_port_free (filter);  
return 1;  
}  

Example 1.10: setting all mandatory properties for an "index" parameter template, then lisiting its properties

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
char *name="Parameter 1";  
char *kind="INDEX";  
int default=100;  
int min=0;  
int max=255;  
int i;  
char **prop_list;  
livido_port_t *param=livido_port_new (LIVIDO_PORT_TYPE_PARAMETER_TEMPLATE);  

/* set all of the mandatory properties */  
livido_property_set (param,"kind",LIVIDO_ATOM_TYPE_STRING,1,&kind);  
livido_property_set (param,"name",LIVIDO_ATOM_TYPE_STRING,1,&name);  
livido_property_set (param,"default",LIVIDO_ATOM_TYPE_INT,1,&default);  
livido_property_set (param,"min",LIVIDO_ATOM_TYPE_INT,1,&min);  
livido_property_set (param,"max",LIVIDO_ATOM_TYPE_INT,1,&max);  

/* now list the properties */  
prop_list=livido_list_properties (param);  

if (prop_list!=NULL) {  
for (i=0;prop_list[i]!=NULL;i++) {  
printf ("Property %d is called \"%s\"\n",i,prop_list[i]);  
free (prop_list[i]);  
}  
free (prop_list);  
}  

livido_port_free (param);  
return 1;  
}  

###Section 2: Examples using the livido-utility functions

Example 2.1: Creating and freeing a port, setting and reading an int property, checking if properties exist

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
int in_int=55;  
int out_int;  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_set_int_value (filter,"test",in_int);  
if (livido_has_property (filter,"test")) printf ("filter has property \"test\"\n");  

out_int=livido_get_int_value (filter,"test",&error);  

printf ("test is %d\n",out_int);  

if (!livido_has_property (filter,"test2")) printf ("filter does not have property \"test2\"\n");  

livido_port_free (filter);  
return 1;  
}  

Example 2.2: Creating and freeing a port, setting and reading a string property

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
char *in_string="LiViDO test";  
char *out_string;  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_set_string_value (filter,"test",in_string);  

out_string=livido_get_string_value (filter,"test",&error);  

printf ("\"test\" is \"%s\"\n",out_string);  

free (out_string);  

livido_port_free (filter);  
return 1;  
}  

Example 2.3: Creating and freeing a port, setting and reading a voidptr property

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
void *in_voidptr=malloc(1024);  
void *out_voidptr;  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_set_voidptr_value (filter,"test",in_voidptr);  
out_voidptr=livido_get_voidptr_value (filter,"test",&error);  

printf ("\"test\" is %p, in ptr was %p\n",out_voidptr,in_voidptr);  

free (in_voidptr);  

livido_port_free (info);  
return 1;  
}  

Example 2.4: Creating and freeing a port, setting and reading a double array

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
float in_doubles[]={48.1,42.9};  
float *out_doubles;  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

livido_set_double_array (filter,"test",2,in_doubles);  
out_doubles=livido_get_double_array (filter,"test",&error);  

printf ("\"test\" is %.2f and %.2f\n",out_doubles[0],out_doubles[1]);  

free (out_doubles);  

livido_port_free (filter);  
return 1;  
}  

Example 2.5: Creating and freeing a port, setting and reading a string array

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
char *in_strings[]={"test string 1","test string 2"};  
char **out_strings;  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_INFO);  

livido_set_string_array (filter,"test",2,in_strings);  

out_strings=livido_get_string_array (filter,"test",&error);  

printf ("\"test\" is %s and %s\n",out_strings[0],out_strings[1]);  

free (out_strings[0]);  
free (out_strings[1]);  
free (out_strings);  

livido_port_free (filter);  
return 1;  
}  

Example 2.6: Creating and freeing a port, setting and reading a voidptr array

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  

* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
void *in_voids[2];  
void **out_voids;  
size_t in_sizes[2]={1024,256};  
int error;  

livido_port_t *filter=livido_port_new (LIVIDO_PORT_TYPE_FILTER_CLASS);  

in_voids[0]=malloc(in_sizes[0]);  
in_voids[1]=malloc(in_sizes[1]);  

livido_set_voidptr_array (filter,"test",2,in_voids);  

/* warning, out_voids are reference only */  
out_voids=livido_get_voidptr_array (filter,"test",&error);  

printf ("\"test\" is %p and %p, original was %p and %p\n",out_voids[0],out_voids[1],in_voids[0],in_voids[1]);  

free (out_voids);  

livido_port_free (filter);  
return 1;  
}  

Example 2.7: Creating and freeing an INDEX parameter template, setting all the mandatory properties, setting readonly and listing them

#include <stdlib.h> // for malloc(), free()  
* include <string.h> // for memset(), memcpy()  
* include <stdio.h>  
* include "livido.h"  
* include "livido.c"  
* include "livido-utils.c"  

void *livido_malloc_f (size_t size) {return malloc(size);}  
void livido_free_f (void *ptr) {free(ptr);}  
void *livido_memset_f (void *s, int c, size_t n) {return memset(s,c,n);}  
void *livido_memcpy_f (void *dest, const void *src, size_t n) {return memcpy(dest,src,n);}  

int main (void) {  
int i;  
char **prop_list;  
livido_port_t *param=livido_port_new (LIVIDO_PORT_TYPE_PARAMETER);  

/* set all of the mandatory properties */  
livido_set_int_value (param,"kind","INDEX");  
livido_set_string_value (param,"name","Parameter1");  
livido_set_int_value (param,"default",100);  
livido_set_int_value (param,"min",0);  
livido_set_int_value (param,"max",255);  

/* now list the properties */  
prop_list=livido_list_properties (param);  

if (prop_list!=NULL) {  
for (i=0;prop_list[i]!=NULL;i++) {  
printf ("Property %d is called \"%s\"\n",i,prop_list[i]);  
livido_property_set_readonly (param,prop_list[i]);  
free (prop_list[i]);  
}  
free (prop_list);  
}  

livido_port_free (param);  
return 1;  
}

read more »


fx stuff

FX created with veejay.

##very old stuff


Image map









































































read more »


VIMS List

##Full list of veejay's events and FX

VIMS  Syntax: '<selector>:<arguments>;'  
Use arguments according to FORMAT  
FORMAT controls the arguments as in C printf. Interpreted sequences are:  
%d      integer  
%s      string  
VIMS selector 001     'Increment index of Effect List'  
FORMAT: '%d', where:  
Argument 0 is Step size  
VIMS selector 002     'Decrement index of Effect List'  
FORMAT: '%d', where:  
Argument 0 is Step size  
VIMS selector 003     'Put selected effect in Effect List to current sample and current entry'  
VIMS selector 004     'Print current settings'  
FORMAT: '%d', where:  
Argument 0 is Sample or Stream ID (depends on playmode, 0=current playing)  
VIMS selector 005     'GU Get a list of all tracks (unadvised!)'  
VIMS selector 006     'Camera/Projection calibration setup'  
VIMS selector 008     'Toggle grayscale preview on/off (default=off)'  
VIMS selector 010     'Play forward'  
VIMS selector 011     'Play backward'  
VIMS selector 012     'Play stop'  
VIMS selector 013     'Skip N frames forward'  
FORMAT: '%d', where:  
Argument 0 is Number of frames  
VIMS selector 014     'Skip N frames backward'  
FORMAT: '%d', where:  
Argument 0 is Number of frames  
VIMS selector 015     'Skip N seconds forward'  
FORMAT: '%d', where:  
Argument 0 is Number of seconds  
VIMS selector 016     'Skip N seconds backward'  
FORMAT: '%d', where:  
Argument 0 is Number of seconds  
VIMS selector 017     'Go to starting position'  
VIMS selector 018     'Go to ending position'  
VIMS selector 019     'Set current frame number'  
FORMAT: '%d', where:  
Argument 0 is Frame number  
VIMS selector 020     'Change trickplay speed'  
FORMAT: '%d', where:  
Argument 0 is Frame step  
VIMS selector 021     'Change frameduplication'  
FORMAT: '%d', where:  
Argument 0 is Frame repeat  
VIMS selector 022     'Start built-in UDP mcast server (YUV planar)'  
VIMS selector 023     'Stop built-in UDP mcast server'  
VIMS selector 020     'Change trickplay speed depending on play direction'  
FORMAT: '%d', where:  
Argument 0 is Frame step  
VIMS selector 033     'Macro keystroke recorder/playback'  
FORMAT: '%d %d', where:  
Argument 0 is Keep or reset (1=reset)  
Argument 1 is Macro status (0=disabled,1=record,2=playing)  
VIMS selector 034     'Select a bank to store macro keystrokes'  
FORMAT: '%d', where:  
Argument 0 is Bank ID  
VIMS selector 040     '(OUT) Write video output to (special) file in yuv4mpeg format'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 041     '(OUT) Stop writing video output to yuv4mpeg file'  
VIMS selector 042     'TCP: Send a frame to a connected veejay client'  
VIMS selector 045     'OUT: Start writing video output to a vloopback device'  
FORMAT: '%d', where:  
Argument 0 is Vloopback pipe number  
VIMS selector 046     'OUT: Stop writing to vloopback device'  
VIMS selector 047     'Push current playing sample or stream as viewport input'  
VIMS selector 048     'Set render depth, use 1 to render chain entries 0,1 and 2 of underlying sample, use 2 to toggle on/off'  
FORMAT: '%d', where:  
Argument 0 is Depth switch  
VIMS selector 050     'Paste frames from buffer at frame into edit descision list'  
FORMAT: '%d', where:  
Argument 0 is EDL position  
VIMS selector 051     'Copy frames from edit descision list to buffer'  
FORMAT: '%d %d', where:  
Argument 0 is EDL start position  
Argument 1 is EDL end position  
VIMS selector 052     'Delete frames from editlist (no undo!)'  
FORMAT: '%d %d', where:  
Argument 0 is EDL start position  
Argument 1 is EDL end position  
VIMS selector 053     'Crop frames from edit descision list to buffer'  
FORMAT: '%d %d', where:  
Argument 0 is EDL start position  
Argument 1 is EDL end position  
VIMS selector 054     'Cut frames from edit descision list to buffer'  
FORMAT: '%d %d', where:  
Argument 0 is EDL start position  
Argument 1 is EDL end position  
VIMS selector 055     'Add video file to edit descision list'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 056     'GU Append a file to the plain EDL and create a new sample (unadvised!)'  
FORMAT: '%d %s', where:  
Argument 0 is existing or new ID  

Argument 1 is Filename  
VIMS selector 058     'Save (selection of) edit descision list to new file'  
FORMAT: '%d %d %s', where:  
Argument 0 is EDL start position (0=start position)  
Argument 1 is EDL end position (0=end position)  
Argument 2 is Filename  
VIMS selector 059     'Load edit descision list from file'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 080     'Execute VIMS bundle'  
FORMAT: '%d', where:  
Argument 0 is Bundle ID  
VIMS selector 081     'Delete a VIMS bundle'  
FORMAT: '%d', where:  
Argument 0 is Bundle ID  
VIMS selector 082     'Add a new bundle to the event list'  
FORMAT: '%d %s', where:  
Argument 0 is Bundle ID (0=new, 1=overwrite existing)  
Argument 1 is VIMS text  
VIMS selector 083     'Attach/Detach a Key to VIMS Event'  
FORMAT: '%d %d %d %s', where:  
Argument 0 is VIMS ID  
Argument 1 is SDL Key symbol  
Argument 2 is SDL Key modifier (0=none,1=alt,2=ctrl,3=shift)  
Argument 3 is VIMS message  
VIMS selector 084     'Veejay load action file'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 085     'Veejay save action file'  
FORMAT: '%d %s', where:  
Argument 0 is Mode (0=only Bundles,1=save edl/sample list)  
Argument 1 is Filename  
VIMS selector 086     'Capture Effect Chain to a new Bundle'  
VIMS selector 100     'Create a new sample'  
FORMAT: '%d %d', where:  
Argument 0 is Starting position  
Argument 1 is Ending position  
VIMS selector 101     'Select and play sample'  
FORMAT: '%d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
VIMS selector 102     'Change looptype of sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Looptype (0=None,1=Normal,2=Pingpong)  
VIMS selector 103     'Change title of sample'  
FORMAT: '%d %s', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Title  
VIMS selector 104     'Change playback speed of sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Speed (0=pause, > 0  and < (end-start)  
VIMS selector 105     'Change start position of sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Frame number  
VIMS selector 106     'Change end position of sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Frame number  
VIMS selector 107     'Change frame repeat for this sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Frame repeat  
VIMS selector 108     'Set in point in sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Position  
VIMS selector 109     'Set out point in sample'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Position  
VIMS selector 110     'Set in and out points in sample'  
FORMAT: '%d %d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Starting position  
Argument 2 is Ending position  
VIMS selector 111     'Clear in and out points'  
FORMAT: '%d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
VIMS selector 112     'Enable effect chain of sample'  
FORMAT: '%d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
VIMS selector 113     'Disable effect chain of sample'  
FORMAT: '%d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
VIMS selector 120     'Delete sample'  
FORMAT: '%d', where:  
Argument 0 is Sample ID >= 1  
VIMS selector 121     'Delete all samples (caution!)'  
VIMS selector 125     'Load samples from file'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 126     'Save samples to file'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 127     'Copy sample to new'  
FORMAT: '%d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
VIMS selector 130     'Start recording from sample'  
FORMAT: '%d %d', where:  
Argument 0 is Number of frames (0=sample duration)  
Argument 1 is Auto Play (0=disable, 1=enable)  
VIMS selector 131     'Stop recording from this sample'  
VIMS selector 143     'Set sample's starting and ending position'  
FORMAT: '%d %d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Starting position  
Argument 2 is Ending position  
VIMS selector 144     'Switch between loop types'  
FORMAT: '%d %d', where:  
Argument 0 is Sample ID (0=current playing, -1=last created, > 0 = Sample ID)  
Argument 1 is Looptype (0=None, 1=Normal, 2=Pingpong)  
VIMS selector 145     'Change KF play status for entry X'  
FORMAT: '%d %d', where:  
Argument 0 is Entry ID  
Argument 1 is Status value  
VIMS selector 146     'Get keyframes for parameter Y on entry X'  
FORMAT: '%d %d', where:  
Argument 0 is Entry ID  
Argument 1 is Parameter ID  
VIMS selector 145     'Clear KF series on entry X'  
FORMAT: '%d', where:  
Argument 0 is Entry ID  
VIMS selector 150     'Store current frame as starting position of new sample'  
VIMS selector 151     'Store current frame as ending position of a new sample ( and commit )'  
VIMS selector 160     'Increase projection/camera point'  
FORMAT: '%d %d', where:  
Argument 0 is X increment  
Argument 1 is Y increment  
VIMS selector 161     'Decrease projection/camera point'  
FORMAT: '%d %d', where:  
Argument 0 is X increment  
Argument 1 is Y increment  
VIMS selector 162     'Set a viewport point using scale'  
FORMAT: '%d %d %d %d', where:  
Argument 0 is Point number  
Argument 1 is Scale factor  
Argument 2 is X  
Argument 3 is Y  
VIMS selector 163     'Get viewport points using scale'  
FORMAT: '%d', where:  
Argument 0 is Grid size  
VIMS selector 164     'Push viewport to secundary input'  
FORMAT: '%d %d', where:  
Argument 0 is On/Off  
Argument 1 is Color=0, Grayscale=1  
VIMS selector 201     'Select and play stream'  
FORMAT: '%d', where:  
Argument 0 is Stream ID >= 1  
VIMS selector 202     'Change RGB color of solid stream'  
FORMAT: '%d %d %d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Red  
Argument 2 is Green  
Argument 3 is Blue  
VIMS selector 203     'Change title of stream'  
FORMAT: '%d %s', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Title  
VIMS selector 207     'Set brightness value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 208     'Set constrast value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 207     'Set hue value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 210     'Set color value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 211     'Set white balance value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 212     'Set ficticious stream length'  
FORMAT: '%d', where:  
Argument 0 is Number of frames  
VIMS selector 213     'Disable effect chain of stream'  
FORMAT: '%d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
VIMS selector 211     'Set saturation value for Video4linux stream'  
FORMAT: '%d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Value 0-65535  
VIMS selector 220     'Delete stream'  
FORMAT: '%d', where:  
Argument 0 is Stream ID >= 1  
VIMS selector 228     'Start offline recording from stream'  
FORMAT: '%d %d %d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
Argument 1 is Number of frames  
Argument 2 is Auto Play (0=disable,1=enable)  
VIMS selector 229     'Stop offline recording from this stream'  
VIMS selector 230     'Start recording from stream'  
FORMAT: '%d %d', where:  
Argument 0 is Number of frames  
Argument 1 is Auto Play (0=disable,1=enable)  
VIMS selector 231     'Stop recording from this stream'  
FORMAT: '%d %d', where:  
VIMS selector 240     'Open video4linux device as new input stream'  
FORMAT: '%d %d', where:  
Argument 0 is Device Number (0=/dev/video0,1=/dev/video1, ... )  
Argument 1 is Channel Number (0=TV,1=composite,2=svideo)  
VIMS selector 241     'Open dv1394 device as new input stream'  
FORMAT: '%d', where:  
Argument 0 is Channel number  
VIMS selector 242     'Solid RGB color fill as new input stream'  
FORMAT: '%d %d %d', where:  
Argument 0 is Red  
Argument 1 is Green  
Argument 2 is Blue  
VIMS selector 243     'Open yuv4mpeg (special) file as new input stream'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 245     'Open TCP veejay connection (peer to peer, raw data) as new input stream'  
FORMAT: '%d %s', where:  
Argument 0 is Port number  
Argument 1 is Hostname or IP address  
VIMS selector 246     'Open UDP multicast as new input stream'  
FORMAT: '%d %s', where:  
Argument 0 is Port Number  
Argument 1 is Multicast Address  
VIMS selector 247     'Open image from file as new input stream'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 254     'Suspend Veejay (caution!)'  
VIMS selector 300     'Set audio volume'  
FORMAT: '%d', where:  
Argument 0 is Volume 0-100  
VIMS selector 301     'Enable / Disable Fullscreen video output'  
FORMAT: '%d', where:  
Argument 0 is On = 1, Off=0  
VIMS selector 302     'Set codec to use for recording (global setting)'  
FORMAT: '%s', where:  
Argument 0 is Codec name (use 'x' to see list)  
VIMS selector 303     'Change playback mode'  
FORMAT: '%d', where:  
Argument 0 is Playback (2=plain,1=stream,0=sample)  
VIMS selector 305     'Switch between sample and stream playback'  
VIMS selector 307     'Enable audio playback'  
VIMS selector 307     'Disable audio playback'  
VIMS selector 308     'Set current sample bank'  
FORMAT: '%d', where:  
Argument 0 is Bank number  
VIMS selector 309     'Play stream or sample slot (depends on current playmode)'  
FORMAT: '%d', where:  
Argument 0 is Slot number  
VIMS selector 315     'Start sample randomizer'  
FORMAT: '%d', where:  
Argument 0 is Mode (0=Random duration, 1=Sample duration)  
VIMS selector 316     'Stop sample randomizer'  
VIMS selector 320     'Start recording now and play when finished'  
VIMS selector 321     'Stop recording'  
VIMS selector 322     'Start recording'  
VIMS selector 323     'Change between box or triangle filter for sampling purposes'  
VIMS selector 324     'Bezerk mode toggle '  
VIMS selector 325     'More/Less verbosive console output'  
VIMS selector 326     '(OUT) Resize SDL video window'  
FORMAT: '%d %d %d %d', where:  
Argument 0 is Width  
Argument 1 is Height  
Argument 2 is X offset  
Argument 3 is Y offset  
VIMS selector 327     'Change playback mode'  
FORMAT: '%d', where:  
Argument 0 is Playback mode (0=sample,1=stream,2=plain)  
VIMS selector 328     'Play sample / stream'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Source type (0=sample,1=stream)  
VIMS selector 329     'Change YUV <-> RGB conversion (unadvised)'  
FORMAT: '%d', where:  
Argument 0 is Mode (0=GIMP,1=CCIR701,2=broken)  
VIMS selector 330     'Save output frame to file'  
FORMAT: '%d %d %s', where:  
Argument 0 is Width  
Argument 1 is Height  
Argument 2 is Filename  
VIMS selector 331     'Editlist cache mode toggle'  
VIMS selector 001     'GU Get preview image (raw RGB24)'  
FORMAT: '%d %d', where:  
Argument 0 is Width  
Argument 1 is Height  
VIMS selector 334     'Enable/Disable sync correction'  
FORMAT: '%d', where:  
Argument 0 is 0=off,1=on  
VIMS selector 335     'Change playback engine framerate'  
FORMAT: '%d', where:  
Argument 0 is Multiple by 100 (ie. for 25fps, use 2500)  
VIMS selector 339     'Take current frame as Mask for this Effect'  
VIMS selector 340     'Set sequence play on or off'  
FORMAT: '%d', where:  
Argument 0 is Status 0=off,1=on  
VIMS selector 341     'Add a sample to the sequence'  
FORMAT: '%d %d', where:  
Argument 0 is Seq ID  
Argument 1 is Sample ID  
VIMS selector 342     'Del sample from sequence slot'  
FORMAT: '%d', where:  
Argument 0 is Seq ID  
VIMS selector 350     'Increment current Channel ID on selected chain entry'  
FORMAT: '%d', where:  
Argument 0 is Increment vale  
VIMS selector 351     'Decrement current Channel ID on selected chain entry'  
FORMAT: '%d', where:  
Argument 0 is Decrement value  
VIMS selector 352     'Enable or disable Effect Chain for ALL samples or streams'  
FORMAT: '%d', where:  
Argument 0 is On = 1, Off= 0  
VIMS selector 353     'Enable Effect Chain'  
VIMS selector 354     'Disable Effect Chain'  
VIMS selector 355     'Reset Effect Chain'  
FORMAT: '%d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
VIMS selector 356     'Fade in effect chain'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Duration in frames  
VIMS selector 357     'Fade out effet chain'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Duration in frames  
VIMS selector 358     'GU Get effect chain'  
FORMAT: '%d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
VIMS selector 359     'Set Chain Index'  
FORMAT: '%d', where:  
Argument 0 is Index value  
VIMS selector 360     'Add effect to chain entry with default values'  
FORMAT: '%d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
Argument 2 is Effect ID  
VIMS selector 361     'Preset effect on chain entry'  
FORMAT: '%d %d %d %d %d %d %d %d %d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current  
Argument 2 is Effect ID  
Argument 3 is Parameter 0  
Argument 4 is Parameter 1  
Argument 5 is Parameter 2  
Argument 6 is Parameter 3  
Argument 7 is Parameter 4  
Argument 8 is Parameter 5  
Argument 9 is Parameter 6  
Argument 10 is Parameter 7  
VIMS selector 362     'Set a parameter value'  
FORMAT: '%d %d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
Argument 2 is Parameter number  
Argument 3 is Value  
VIMS selector 363     'Enable effect on chain index'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
VIMS selector 364     'Disable effect on chain index'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
VIMS selector 365     'Reset effect to default'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
VIMS selector 366     'Set mixing channel'  
FORMAT: '%d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
Argument 2 is Sample ID  
VIMS selector 367     'Set mixing source type'  
FORMAT: '%d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
Argument 2 is Source Type (0=sample,1=stream)  
VIMS selector 368     'Set mixing channel and source type'  
FORMAT: '%d %d %d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
Argument 2 is Source Type (0=sample,1=stream)  
Argument 3 is Sample or Stream ID  
VIMS selector 369     'Reset chain index'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index (-1=current)  
VIMS selector 370     'Set opacity of Effect Chain'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Opacity value [0-255]  
VIMS selector 371     'Decrement current FX chain entry'  
FORMAT: '%d', where:  
Argument 0 is Decrement value  
VIMS selector 372     'Increment current FX chain entry'  
FORMAT: '%d', where:  
Argument 0 is Increment value  
VIMS selector 373     'Change source type of a chain entry'  
FORMAT: '%d %d', where:  
Argument 0 is Chain entry  
Argument 1 is Source type (0=Sample, 1=Stream)  
VIMS selector 374     'Increment current value of a parameter'  
FORMAT: '%d %d', where:  
Argument 0 is Parameter number  
Argument 1 is Step size  
VIMS selector 375     'Decrement current value of a parameter'  
FORMAT: '%d %d', where:  
Argument 0 is Parameter number  
Argument 1 is Step size  
VIMS selector 376     'Enable / disable Effect Chain'  
VIMS selector 377     'Enable / disable effect on current entry'  
FORMAT: '%d %d', where:  
VIMS selector 388     'Print help in OSD (if available)'  
VIMS selector 399     'Print copyright'  
VIMS selector 390     'Set font position'  
FORMAT: '%d %d', where:  
Argument 0 is X position  
Argument 1 is Y position  
VIMS selector 391     'Set font color'  
FORMAT: '%d %d %d %d %d', where:  
Argument 0 is Red  
Argument 1 is Green  
Argument 2 is Blue  
Argument 3 is Alpha  
Argument 4 is 0=Transparent 1=BG 2=FG  
VIMS selector 392     'Set font type and font size'  
FORMAT: '%d %d', where:  
Argument 0 is Font type  
Argument 1 is Font size  
VIMS selector 393     'Add a subtitle sequence'  
FORMAT: '%d %d %d %d %d %s', where:  
Argument 0 is Subtitle sequence (0=new)  
Argument 1 is Start position  
Argument 2 is End position  
Argument 3 is X position  
Argument 4 is Y position  
Argument 5 is Text  
VIMS selector 394     'Delete a subtitle sequence'  
FORMAT: '%d', where:  
Argument 0 is Subtitle sequence  
VIMS selector 395     'Update a subtitle sequence'  
FORMAT: '%d %d %d %s', where:  
Argument 0 is Subtitle sequence  
Argument 1 is Start position  
Argument 2 is End position  
Argument 3 is Text  
VIMS selector 396     'Export subtitles to SRT'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 397     'Import subtitles from SRT'  
FORMAT: '%s', where:  
Argument 0 is Filename  
VIMS selector 398     'Select a subtitle sequence'  
FORMAT: '%d', where:  
Argument 0 is Subtitle sequence  
VIMS selector 399     'Toggle OSD status'  
VIMS selector 400     'GU Get video information details'  
VIMS selector 401     'GU Get all effects'  
VIMS selector 402     'GU Get EDL'  
VIMS selector 403     'GU Get all bundles'  
VIMS selector 405     'GU Get a list of all streams (unadvised!)'  
FORMAT: '%d', where:  
Argument 0 is stream offset  
VIMS selector 408     'GU Get a list of all samples (unadvised!)'  
FORMAT: '%d', where:  
Argument 0 is sample offset  
VIMS selector 409     'GU Get video4linux properties'  
FORMAT: '%d', where:  
Argument 0 is Stream ID (-1=last created, > 0 = Stream ID)  
VIMS selector 410     'GU Get effect chain index details'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Chain Index  
VIMS selector 411     'GU Get all VIMS events'  
VIMS selector 412     'GU Get console output'  
VIMS selector 413     'GU Get sample or stream information (unadivsed!)'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Source Type (0=sample,1=stream)  
VIMS selector 414     'GU Get sample options'  
FORMAT: '%d %d', where:  
Argument 0 is Sample or Stream ID (0=current playing, -1=last created, > 0 = ID)  
Argument 1 is Source Type (0=sample,1=stream)  
VIMS selector 415     'GU Get all devices and their locations'  
VIMS selector 416     'GU Get list of loaded fonts'  
VIMS selector 417     'GU Get list of loaded subtitle sequences'  
VIMS selector 418     'GU Get subtitle sequence'  
FORMAT: '%d', where:  
Argument 0 is Subtitle sequence  
VIMS selector 418     'GU Get list of sample sequences'  
VIMS selector 420     'GU Get all keys'  
VIMS selector 600     'Quit Veejay (caution!)'  
VIMS selector 600     'End sessions with veejay'  
Veejay OSC  
When using strings, set it *always* as the first argument  

----- The OSC address space -----  
/  
/video/  
/video/play: play foward  
/video/reverse: play reverse  
/video/pause: pause  
/video/speed: speed ( < 0 = reverse, > 0 = forward)  
/video/slow: slow  
/video/goto_start: goto start  
/video/goto_end: goto end  
/video/set_frame: set frame <pos>  
/video/prev_frame: set previous frame  
/video/next_frame: set next frame  
/video/next_second: set next second  
/video/prev_second: set previous second  
/video/mode: play plain video  
/video/set/  
/sample/  
/sample/new: create new sample <pos start> <pos end>  
/sample/copy: copy sample <num> as new sample  
/sample/del: delete sample <num>  
/sample/select: select and play sample <num>  
/sample/set/  
/sample/set/jitter: relative start/end position update <pos1> <pos2>  
/sample/set/start: set sample new starting position <pos>  
/sample/set/end: set sample new ending position <pos>  
/sample/set/looptype: sample set looptype <0 = none, 1 = normal, 2 = bounce>  
/sample/set/speed: sample set playback speed <num>  
/sample/set/marker: sample set marker <pos1> <pos2>  
/sample/set/slow: sample set frame duplicate <num>  
/sample/set/nomarker: sample delete marker  
/sample/rec/  
/sample/rec/start: sample start recording <0=entire sample, N=num frames> <0=dont play 1=play>  
/sample/rec/stop: sample stop recording  
/sample/rec/format: sample set recorder format (mjpeg,mpeg4,dv,divx,yv12,yv16)  
/stream/  
/stream/select: stream select and play <num>  
/stream/rec/  
/stream/rec/o_start: hidden record from stream <num frames> <autoplay bool>  
/stream/rec/o_stop: stop hidden recording   
/stream/rec/start: start stream recorder <num frames> <autoplay bool>  
/stream/rec/stop: stop stream recorder   
/stream/rec/format: set stream recorder format (mjpeg,divx,dv,yv12,yv16,mpeg4)  
/stream/new/  
/stream/new/v4l: new video4linux input stream <device num> <channel num>  
/stream/new/solid: new solid color stream <R> <G> <B>  
/stream/new/y4m: new yuv4mpeg input stream <filename>  
/stream/new/mcast: new multicast input stream <address> <port>  
/stream/new/net: new peer-to-peer input stream <hostname> <port>  
/record/  
/chain/  
/chain/reset: Effect chain clear  
/chain/fade_in: Fade in effect chain <num frames>  
/chain/fade_out: Fade out effect chain <num frames>  
/chain/enable: Effect chain enabled  
/chain/disable: Effect chain disabled  
/chain/opacity: Manual Fader (0=A 255=B  
/chain/global_fx: All Effect chains on/off (1/0)  
/out/  
/out/mcaststop: Stop mcast frame sender  
/out/mcaststart: Start mcast frame sender  
/cl/  
/cl/load: Samplelist load <filename>  
/cl/save: Samplelist save <filename>  
/el/  
/el/add_sample: Editlist add filename (as new sample)  
/el/paste_at: EditList paste frames from buf at frame <num>  
/el/copy: EditList copy frames <n1> to <n2> to buffer  
/el/del: EditList delete frames <n1> to <n2>  
/el/crop: EditList crop frames 0 - <n1>  <n2> - end  
/el/cut: EditList cut frames <n1> to <n2> into buffer  
/el/add: EditList add file <filename>  
/el/save: EditList save <filename>  
/el/load: EditList load <filename>  
/arg/  
/arg/set: Set argument <num> to value <num> for effect on entry <num>  
/entry/  
/entry/disable: Disable effect chain entry <num>  
/entry/enable: Enable effect chain entry <num>  
/entry/clear: Clear effect chain entry <num>  
/entry/select: Select effect chain entry <num>  
/entry/defaults: Set effect default values on chain entry <num>  
/entry/preset: Preset an effect on chain entry  
/entry/channel: Select channel <num> for mixing effect on entry <num>  
/entry/source: Select source (0=sample,1=stream) for mixing effect on entry <num>  
/output/  
/output/resize: Resize SDL video window <width> <height>  
/output/fullscreen: Toggle SDL video window fullscreen/windowed  
/config/  
/config/sampling: Configure sampling mode (linear=0 or triangle=1)  
/config/verbose: Toggle verbose output mode  
/config/bezerk: Toggle bezerk mode  
...end of OSC address space.  


Below follow all effects in Veejay,  
Effect numbers starting with 2xx are effects that use  
*two* sources (by default a copy of itself)  
Use the channel/source commands to select another sample/stream  
to mix with.  

[effect num] [effect name] [arg 0 , min/max ] [ arg 1, min/max ] ...  
0                       Dummy Frame               
Color                   0       0 - 7  
201                     Overlay Magic             
Mode                    0       1 - 32  
202                     Luma Magick               
Mode                    0       1 - 39  

Opacity A                       1       0 - 200  

Opacity B                       2       0 - 200  
203                     Map B to A (substract background mask)            
Threshold                       0       0 - 255  

Mode                    1       0 - 1  

Show mask/image                 2       0 - 2  

Thinning                        3       1 - 100  
204                     Normal Overlay            
Opacity                 0       0 - 255  
205                     Luma Key                  
Feather                 0       0 - 255  

Min Threshold                   1       0 - 255  

Max Threshold                   2       0 - 255  

Distance                        3       1 - 720  

Mode                    4       0 - 2  
206                     Chroma Key (RGB)                  
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Mode                    4       0 - 1  

Noise suppression                       5       1 - 6300  
207                     Chroma Magic              
Mode                    0       0 - 25  

Value                   1       0 - 255  
208                     Opacity by Threshold              
Mode                    0       0 - 2  

Threshold A                     1       0 - 255  

Threshold B                     2       0 - 255  

Opacity                 3       0 - 255  
209                     Splitted Screens                  
Mode                    0       0 - 13  

Switch                  1       0 - 1  
210                     Colored Border Translation                
Size                    0       1 - 288  

Color                   1       0 - 7  
211                     Frame Border Translation                  
Size                    0       1 - 288  
212                     AlphaLuma Overlay                 
213                     Transition Translate Opacity              
Opacity                 0       0 - 255  

Width                   1       0 - 720  

Height                  2       0 - 576  

Ay                      3       0 - 576  

Ax                      4       0 - 720  

By                      5       0 - 576  

Bx                      6       0 - 720  
214                     Transition Translate Carot                
Opacity                 0       0 - 255  

Mode                    1       0 - 1  

Point size                      2       1 - 720  

By start                        3       1 - 576  

By end                  4       1 - 576  

Row                     5       1 - 720  
215                     Transition Line           
Opacity                 0       0 - 255  

Line width                      1       1 - 720  

Distance                        2       2 - 720  

Mode                    3       0 - 1  
216                     Transition Translate Blend                
Mode                    0       0 - 30  

Width                   1       1 - 720  

Height                  2       1 - 576  

Ax offset                       3       1 - 720  

Ay offset                       4       1 - 576  

Bx offset                       5       1 - 720  

By offset                       6       1 - 576  
217                     Transition Fade to Color                  
Opacity                 0       1 - 255  

Color                   1       0 - 7  

Frame length                    2       1 - 3000  

Mode                    3       0 - 1  
218                     Transition Fade to Color by RGB           
Opacity                 0       1 - 255  

Red                     1       1 - 255  

Green                   2       1 - 255  

Blue                    3       0 - 255  

Mode                    4       0 - 1  

Frame length                    5       1 - 3000  
219                     Replace Pure White                
220                     Simple Mask (black and white)             
Threshold                       0       0 - 255  

Mode                    1       0 - 1  
221                     Threshold blur with overlay               
Opacity                 0       0 - 255  

Min Threshold                   1       0 - 255  

Max Threshold                   2       0 - 255  
222                     Overlay by Threshold Range                
Opacity                 0       0 - 255  

Min Threshold                   1       0 - 255  

Max Threshold                   2       0 - 255  
223                     Transparent Chroma Key (RGB)              
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Opacity                 4       0 - 255  

Noise level                     5       0 - 3500  
224                     Transition Wipe           
Opacity                 0       0 - 255  

Increment                       1       0 - 25  
225                     Tracer            
Opacity                 0       0 - 255  

Buffer length                   1       1 - 25  
226                     Magic Tracer              
Mode                    0       0 - 30  

Length                  1       1 - 25  
227                     Strong Luma Overlay               
Mode                    0       1 - 13  
228                     Blend by Color Key                
Angle                   0       5 - 900  

Red                     1       0 - 256  

Green                   2       0 - 256  

Blue                    3       0 - 256  

Blend mode                      4       0 - 7  

Noise suppression                       5       0 - 3500  
229                     Complex Threshold (fixme)                 
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Smoothen                        4       0 - 4  

Threshold                       5       0 - 255  
230                     Out of Sync -Replace selection-           
Vertical size                   0       1 - 575  

Mode                    1       0 - 1  

Framespeed                      2       1 - 250  
231                     Horizontal Sliding Bars           
Divider                 0       1 - 576  

Top Y                   1       0 - 576  

Bot Y                   2       0 - 576  

Top X                   3       0 - 576  

Bot X                   4       0 - 576  
232                     Vertical Sliding Bars             
Divider                 0       1 - 576  

Top Y                   1       0 - 576  

Bot Y                   2       0 - 576  

Top X                   3       0 - 576  

Bot X                   4       0 - 576  
233                     Displacement Map                  
X displacement                  0       1 - 720  

Y displcement                   1       1 - 576  

Mode                    2       0 - 1  
234                     Binary Overlays           
Mode                    0       0 - 10  
235                     Dissolve Overlay                  
Opacity                 0       0 - 255  
236                     Normal Overlay (per Channel)              
Opacity Y                       0       0 - 255  

Opacity Cb                      1       0 - 255  

Opacity Cr                      2       0 - 255  
237                     Videoplay (timestretched mosaic)                  
Photos                  0       2 - 10  

Waterfall                       1       1 - 250  

Mode                    2       0 - 3  
238                     VideoWall / Tile Placement                
Photos                  0       0 - 10  

X Displacement                  1       0 - 720  

Y displacement                  2       0 - 576  

Lock update                     3       0 - 1  
239                     Map B from threshold mask                 
Threshold                       0       0 - 255  

Reverse                 1       0 - 1  
240                     Map B to A (bitmask)              
Threshold                       0       0 - 255  

Reverse                 1       0 - 1  

Show                    2       0 - 1  
241                     Picture in picture                
Width                   0       8 - 720  

Height                  1       8 - 576  

X offset                        2       8 - 720  

Y offset                        3       8 - 576  
242                     Chameleon BlendTV                 
Mode (Appear,Dissapear)                 0       0 - 1  
243                     RadioActive EffecTV               
Mode                    0       0 - 6  

Zoom ratio                      1       50 - 100  

Strength                        2       0 - 255  

Difference Threshold                    3       0 - 255  
244                     Map B to A (sub bg, texture map))                 
Threshold                       0       0 - 255  

Reverse                 1       0 - 1  

Show mask                       2       0 - 4  

Thinning                        3       1 - 100  

Min blob weight                 4       1 - 5000  
245                     Water ripples             
Refresh Frequency                       0       1 - 3600  

Wavespeed                       1       1 - 16  

Decay                   2       1 - 31  

Mode                    3       0 - 6  

Threshold (motion)                      4       0 - 255  
100                     Dummy Frame               
Color                   0       0 - 7  
101                     Mirror            
H or V mode                     0       0 - 5  
102                     Multi Mirrors             
H or V                  0       0 - 3  

Number                  1       0 - 237  
103                     Width Mirror              
Widths                  0       2 - 720  
104                     Flip Frane                
H or V                  0       0 - 1  
105                     Posterize (Threshold Range)               
Posterize                       0       1 - 256  

Min Threshold                   1       0 - 256  

Max Threshold                   2       0 - 256  
106                     Negation                  
Value                   0       0 - 255  
107                     Solarize                  
Threshold                       0       1 - 255  
108                     Hue and Saturation                
Degrees                 0       0 - 360  

Intensity                       1       0 - 256  
109                     Gamma Correction                  
Gamma                   0       0 - 500  
110                     Soft Blur (1x3) and (3x3)                 
Kernel size                     0       0 - 1  
111                     RevTV (EffectTV)                  
Line spacing                    0       1 - 576  

Vertical scale                  1       1 - 720  

Luminance intensity                     2       0 - 255  

Color range                     3       0 - 7  
112                     Dices (EffectTV)                  
Mode                    0       0 - 5  
113                     SmuckTV (EffectTV)                
Mode                    0       0 - 14  
114                     Filter out chroma channels                
Mode                    0       0 - 2  
115                     Various Weird Effects             
Mode                    0       0 - 10  
116                     Matrix Dithering                  
Mode                    0       2 - 255  

Value                   1       0 - 1  
117                     Raw Data Manipulation             
Mode                    0       0 - 4  

Value                   1       1 - 255  
118                     Raw Chroma Pixel Replacement              
Old Cb                  0       0 - 255  

Old Cr                  1       0 - 255  

New Cb                  2       0 - 255  

New Cr                  3       0 - 255  
119                     Transform Cubics                  
Cubics                  0       1 - 36  
120                     Fibonacci Downscaler              
Mode                    0       0 - 1  

Fib                     1       1 - 8  
121                     Bump 2D           
Value 1                 0       1 - 256  

Value 2                 1       1 - 256  

Mode                    2       0 - 1  
122                     Rotozoom                  
Mode                    0       0 - 8  

Rotate                  1       0 - 255  

Zoom                    2       0 - 255  

Automatic                       3       0 - 3  
123                     Shift pixel values YCbCr                  
Mode                    0       0 - 9  

Value                   1       0 - 255  
124                     Overlay Scratcher                 
Opacity                 0       0 - 255  

Scratch buffer                  1       1 - 24  

PingPong                        2       0 - 1  
125                     Magic Overlay Scratcher           
Mode                    0       0 - 9  

Scratch frames                  1       1 - 24  

PingPong                        2       0 - 1  
126                     Matte Scratcher           
Mode                    0       0 - 25  

Value                   1       0 - 255  

Length                  2       0 - 25  

Pingpong                        3       0 - 1  
127                     Distortion                
Inc 1                   0       0 - 8  

Inc2                    1       0 - 8  
128                     Grayscale by Color Key            
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  
129                     Black and White by Threshold              
Min threshold                   0       0 - 255  

Max threshold                   1       0 - 255  
130                     Complex Invert            
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Noise suppression                       4       0 - 3500  
131                     Complex Saturation                
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Intensity                       4       0 - 360  

Degrees                 5       0 - 256  

Noise suppression                       6       0 - 3500  
132                     Isolate Color             
Angle                   0       5 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

White                   4       0 - 255  
133                     Sharpen           
Value                   0       0 - 2048  
134                     Amplify low noise                 
Mode                    0       0 - 2  

Amplification                   1       1 - 10000  
135                     Contrast                  
Mode                    0       0 - 2  

Intensity 1                     1       0 - 255  

Intensity 2                     2       0 - 255  
136                     Motion blur               
Frames                  0       0 - 1000  
137                     Sinoids           
Mode                    0       0 - 1  

Sinoids                 1       0 - 1000  
138                     Average           
Value                   0       1 - 100  
139                     Ripple            
Waves                   0       1 - 3600  

Amplitude                       1       1 - 80  

Attenuation                     2       1 - 360  
140                     Bathroom Window           
H or V                  0       0 - 1  

Value                   1       1 - 64  
141                     Slice Window              
Slices                  0       2 - 128  

Mode                    1       0 - 1  
142                     Zoom              
Width                   0       0 - 720  

Height                  1       0 - 576  

Factor                  2       10 - 100  

Mode                    3       0 - 1  
143                     Pencil Sketch (8)                 
Mode                    0       0 - 8  

Min Threshold                   1       0 - 255  

Max Treshold                    2       0 - 255  
144                     Deinterlace (yuvkineco)           
Value                   0       0 - 255  
145                     Pixel Raster              
Mode                    0       0 - 1  

Size                    1       1 - 40  
146                     Color Enhance             
Intensity Y                     0       0 - 255  

Intensity U                     1       0 - 255  

Intensity V                     2       0 - 255  
147                     Enhanced Magic Blend              
Mode                    0       0 - 7  

Min threshold                   1       1 - 255  

Max threshold                   2       1 - 255  
148                     Noise Pencil              
Mode                    0       0 - 3  

Amplification                   1       1 - 10000  

Min Threshold                   2       0 - 255  

Max Threshold                   3       0 - 255  
149                     RippleTV  (EffectTV)              
Refresh Frequency                       0       1 - 3600  

Wavespeed                       1       1 - 16  

Decay                   2       1 - 32  
150                     Pixelate                  
Pixels                  0       1 - 27  
151                     Magic Mirror Surface              
X                       0       0 - 360  

Y                       1       0 - 288  

X                       2       0 - 100  

Y                       3       0 - 100  
152                     Pixel Smear               
Mode                    0       0 - 3  

Value                   1       0 - 255  
153                     Grid              
Grid size                       0       4 - 144  
154                     Fish Eye                  
Value                   0       -1000 - 1000  
155                     Swirl             
Degrees                 0       1 - 360  
156                     Radial Blur               
Radius                  0       0 - 90  

Power                   1       0 - 100  

Direction                       2       0 - 2  
157                     Chromium                  
Mode                    0       0 - 3  
158                     Chrominance Palette (rgb key)             
Angle                   0       1 - 900  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Chroma Blue                     4       0 - 255  

Chroma Red                      5       0 - 255  
159                     U/V Correction            
Angle                   0       1 - 360  

U Rotate Center                 1       0 - 255  

V Rotate Center                 2       0 - 255  

Intensity U                     3       0 - 100  

Intensity V                     4       0 - 100  

Minimum UV                      5       0 - 255  

Maximum UV                      6       0 - 255  
160                     Radial cubics             
Radius                  0       2 - 72  

Value                   1       1 - 90  
161                     Cartoon           
Damp Y                  0       1 - 255  

Damp U                  1       0 - 255  

Damp V                  2       0 - 255  
162                     Nervous           
Buffer length                   0       0 - 25  
163                     Morphology (experimental)                 
Threshold                       0       0 - 255  

Operator                        1       0 - 8  

Repeat                  2       0 - 1  
164                     Video Blobs               
Radius                  0       1 - 360  

Blobs                   1       1 - 100  

Speed                   2       1 - 100  

Shape                   3       0 - 1  
165                     Video Boids               
Radius                  0       1 - 360  

Blobs                   1       2 - 256  

Shape                   2       0 - 1  

Cohesion                        3       0 - 100  

Seperation                      4       0 - 100  

Alignment                       5       0 - 100  

Speed                   6       1 - 100  

Home Radius                     7       1 - 360  
166                     Motion Ghost              
Opacity                 0       16 - 255  
167                     ZArtistic Filter (Oilpainting, acc. add )                 
Brush size                      0       2 - 16  

Smoothness                      1       1 - 255  

Mode (Luma/Chroma)                      2       0 - 1  
168                     ZArtistic Filter (Oilpaint, acc. avg)             
Brush size                      0       2 - 16  

Smoothness                      1       1 - 255  

Mode (Luma/Chroma)                      2       0 - 1  
169                     ZArtistic Filter (Horizontal strokes)             
Line size                       0       2 - 32  

Smoothness                      1       1 - 255  

Mode (Luma/Chroma)                      2       0 - 1  
170                     ZArtistic Filter (Round Brush)            
Radius                  0       2 - 32  

Distance from center                    1       1 - 200  

Smoothness                      2       1 - 255  

Mode (Luma/Chroma)                      3       0 - 1  
171                     ZArtistic Filter (Vertical strokes)               
Stroke size                     0       2 - 32  

Smoothness                      1       1 - 255  

Mode (Luma/Chroma)                      2       0 - 1  
172                     vvCutStop                 
Threshold                       0       0 - 255  

Frame freq                      1       0 - 255  

Cut mode                        2       0 - 1  

Hold front/back                 3       0 - 1  
173                     vvMaskStop                
Negate Mask                     0       0 - 1  

Swap Mask/Frame                 1       0 - 1  

Hold Frame Frequency                    2       0 - 255  

Hold Mask Frequency                     3       0 - 255  
174                     Photoplay (timestretched mosaic)                  
Photos                  0       2 - 10  

Waterfall                       1       1 - 250  

Mode                    2       0 - 3  
175                     Flare (Glow)              
Mode                    0       0 - 5  

Opacity                 1       0 - 255  

Radius                  2       0 - 100  
176                     Constant Luminance Blend                  
Mode                    0       0 - 31  

Threshold                       1       0 - 500  

Constant                        2       16 - 235  
177                     Color mapping             
Red                     0       0 - 255  

Green                   1       0 - 255  

Blue                    2       0 - 255  
178                     Goom              
Mode                    0       0 - 10  

Value                   1       100 - 5000  
179                     Colored Morphology                
Threshold                       0       0 - 255  

Operator mode                   1       0 - 8  

Repeat                  2       0 - 1  
180                     Color Flash               
Frametime                       0       0 - 50  

Red                     1       0 - 255  

Green                   2       0 - 255  

Blue                    3       0 - 255  

Delay                   4       1 - 10  
181                     RGB Channel               
Red                     0       0 - 1  

Green                   1       0 - 1  

Blue                    2       0 - 1  
182                     Automatic Histogram Equalizer             
Channel (Y,U,V,All)                     0       0 - 1  

Intensity                       1       0 - 255  

Strength                        2       0 - 255  
183                     Color Histogram           
Mode (R,G,B,All)                        0       0 - 3  

Draw                    1       0 - 1  

Intensity                       2       0 - 255  

Strength                        3       0 - 255  
184                     Motion Mapping            
Threshold                       0       0 - 255  

Reverse                 1       50 - 10000  

Draw                    2       0 - 1  

History                 3       2 - 200  

Capture length                  4       0 - 255  
185                     TimeDistortionTV (EffectTV)               
Mode                    0       5 - 100  
186                     ChameleonTV (EffectTV)            
Appearing/Dissapearing                  0       0 - 1  
187                     BaltanTV (EffecTV)                
Stride                  0       2 - 16  

Mode                    1       0 - 1  
188                     Contour extraction                
Threshold                       0       0 - 255  

Mode                    1       0 - 1  

Show image/contour                      2       0 - 2  

Thinning                        3       1 - 100  

Min weight                      4       1 - 5000  
189                     Lens correction           
Alpha X                 0       1 - 1000  

Alpha Y                 1       1 - 1000  

Direction                       2       0 - 1  
190                     Substract background (static, requires bg mask)           
Threshold                       0       0 - 255  

Mode                    1       0 - 1  

read more »


Dependencies

##List of dependencies

ffmpeg  
libxml2  
libsdl / SDL  
freetype2  

Optional:

libdv (http://libdv.sf.net)  
directfb (http://directfb.org)  
jack (http://jackaudio.org)  
unicap (http://www.unicap-imaging.org/)

read more »


Colorspaces

##Colorspaces

Veejay processes all video in YUV planar mostly for historical reasons - nowadays, VJ software is shifting to the domain of the GPU and OpenGL . However:

  • A lot of (older) capture hardware delivers in some YUV format
  • Your MJPEG and other videos usually decodes into some YUV format
  • YUV is a lot less bandwidth then RGB
  • Veejay is good at recording to disk from any source
  • Veejay runs on exotic systems and requires lower hardware requirements than most
    (commercial) VJ software.

On the downside, veejay sub- and supersamples YUV to 4:4:4 planar when special
FX require a U and V pixel for every Y pixel. Some USB Webcams only support the RGB colorspace , for which veejay provides a (very fast) colorspace conversion.

By default, veejay works in YUV 4:2:2 format which is the highest quality possible,
as such, it will try to open any video source in its native format.

YUV 4:2:2 planar Rec. 601 (Y'CbCr)

8 bit Y plane followed by 8 bit 2x1 subsampled V and U planes.

The Y plane is filled with 8 bit luminance samples ; Here the value 16 is used for black and 235 for white.

The U and V planes are filled with 8 bit chrominance samples, with the values 16 to 240.

This allows for overshoot and undershoot .

YUV 4:2:2 planar JPEG/JFIF (veejay's standard playback mode)

8 bit Y plane followed by 8 bit 2x1 subsampled V and U planes.

The sample values in the planes range from 0 - 255, Black is defined at 0, White at 255

Note that scaling this format to Rec. 601 is somewhat lossy.

Veejay has an enviroment variable you can set if you want to convert between the two formats

automatically.

read more »


What to use as a live video source?

The issue is raised every now and then:

"How do I plug in my (USB WebCam/Digital Camera/Exotic Hardware) to veejay?"

Currently, Veejay does not support decompressing digital video ( firewire) directly from the camera ( like on windows and mac). There is however, full functional support for avi's and quicktime movies in digital video.

The codec for DV video on linux, is unlike the commercial codecs for windows and macosx, rather slow. There's no way to expect near-realtime performance on average hardware.

( at least, not on my hardware wich is getting old).

Capturing live video is done trough UNICAP, so hopefully one day we can have digital video decompression on the fly.

As for the USB Webcams, please check out the compatibility list on http://www.exploits.org/v4l/

Basically, anything that goes with XawTV and others will propably work with Veejay too.

The veejay team has always relied on TV-input cards as a source of nice-quality realtime video source. The one's we used:

  • Anything that goes with BTTV
  • The AVER TV CARDBUS from AverMedia ( a PCMCIA card)
    We are in no way affiliated with AverMedia, or making advertisements, but it just happened to be the ONLY existing PCMCIA TV card at the time I was looking for one. there might be other alternatives right now, again, see http://www.exploits.org/v4l/

Using uncompressed video is very CPU friendly, wich leaves more juice for realtime effects. Even on commercial platforms there's a speed penalty when using compressed sources.

Comments on this issue are VERY welcome!

read more »


Video files and resolution.

1. Video formats and containers

A video file consists out of TWO seperate elements:

  • container
  • codec

The container holds the digitally encoded data and the codec is capable of decoding/encoding this digitally encoded data.

Veejay supports the AVI and the Quicktime container , with the following codecs:

Quicktime:

  • mpjeg,mjpa,jpeg,dmb1
  • dvsd, dv, dvcp, dvhd

AVI

  • mjpeg, mjpa,jpeg,jfif,dmb1
  • dvsd, dv, dvcp, dvhd
  • i420, i422, yv16, hfyu

Raw DV

  • PAL / NTSC dvsd

Veejay can only deal with video files that consists entirely out of whole images (only I-frames). The codecs below will only work if all frames are I-frames. Otherwise, veejay will abort with an error message.

AVI / Quicktime:

  • xvid, mp4v,divx,dxsd,mp4s,m4s2
  • div3,mp43,mp42,mpg4
  • avc1,h264,x264,davc,svq1,svq3,avc1

2. Wich codec to use

MotionJPEG ( mjpeg) is the veejay codec of choice for most applications, it gives you a good tradeof between compression, quality and compatibility. If you want speed, use AVI yv16 or i420 while recording to new samples.

Tools that support MJPEG:

2. Wich resolutions to use

Veejay can do:

  • pal: 720x576
  • ntsc: 720x480
  • 1/4 pal: 360x288
  • 1/4 ntsc: 360x240

and many more, but multiples of 16 ( jpeg squares) will look best!

If you load multiple video files on the commandline, make sure that all files have the same resolution and audio properties.

3. How to convert ( transcode)
Veejay can convert dv video to mjpeg for you, however, I prefer to use mplayer for this, wich has more flexibility.

From "anything" mplayer can play to mjpeg, use:

$ mencoder -ovc lavc -oac pcm -lavcopts vcodec=mjpeg -o

To scale on the fly, use:

$ mencoder -ovc lavc -oac pcm -lavcopts vcodec=mjpeg -vf scale=352:288 -o

consult mplayer documentation about other options, such as cropping and filtering out blocks in video.

a quick hint for bulk encoding a bunch of capture.dv files:

$ for i in `ls *dv`;do mencoder -ovc lavc -oac pcm -lavcopts vcodec=mjpeg -o `echo $i | sed s/.dv/.avi/` $i; done;

4. What is this dummy mode

Dummy mode opens up a 'color stream' to start veejay without a video file.

If you use a video file, veejay will take that file's properties as default settings for the whole session.

read more »