The Engine

The engine can be started on the console with the gephex-engine command. At the moment there are no command-line options and environment variables that influence the behaviour. All options are set in the configuration file ~/.gephex/engine.conf. If no file exists a default configuration file is created.

conf { module_dirs=[/usr/lib/gephex/modules/] type_dirs=[/usr/lib/gephex/types/] graph_dir=[/home/martin/.gephex/graphs/] sequence_dir=[/home/martin/.gephex/sequences/] playlist_dir=[/home/martin/.gephex/playlists/] ipc_type=[inet] ipc_unix_node_prefix=[/tmp/gephex_socket_] ipc_port=[6666] }

module_dirs is the absolute path to the directory with the effect plugins. The shared libraries for the types are stored in the type_dirs. In future versions there should be the possibility for multiple paths for both directories. The triple graph_dir, sequence_dir and playlist_dir tells the engine the location, where to store the user created data objects. The user interface must connect to the engine with a ipc mechanism ipc_type. You can select between inet for a internet-protocol based communication, on Unix platforms unix for Unix domain sockets and namedpipe for named pipes on win32 systems. If engine and GUI run on the same host the usage of non ip based communication is preferred cause of the low latency behaviour. The parameters ipc_unix_node_prefix and ipc_port must equal to the ones in the ~/.gephex/gui.conf file.

Getting the latest CVS Snapshot

To get the developer version from the cvs you need to connect to the server. When prompted for the password of the anonymous user, leave that empty and press the enter key.

bash@host:~$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gephex login Logging in to :pserver:anonymous@cvs.sourceforge.net:2401/cvsroot/gephex CVS password: bash@host:~$

The sources are stored in the GePhex module. To get a clean copy use the checkout command. This creates the GePhex subdirectory with the source tree.

bash@host:~$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gephex co GePhex cvs server: Updating GePhex U GePhex/AUTHORS U GePhex/BUGS U GePhex/ChangeLog U GePhex/INSTALL ...

Getting a Distribution-Tarball

Visit our download page and get a release. Let's assume the tarball is called gephex-0.0.4.tar.gz. Just unpack the file.

bash@host:~$ tar xvzf gephex-0.0.4.tar.gz gephex-0.0.4/AUTHORS gephex-0.0.4/BUGS gephex-0.0.4/ChangeLog gephex-0.0.4/INSTALL ...

Bootstrapping

This step is only necessary when you got the sources from CVS. The distributed tarballs are already "bootstrapped".

To do the bootstrapping, you need some additional software. This includes autoconf and automake and some additional packages to build the documentation etc.

When installing from a tarball, this software is *not* needed!

• autoconf automake libtool

• python

• sgmltools-lite docbook-utils

GePhex uses autoconf and automake for the configuration and generation of the Makefiles. Use the script bootstrap.sh to create the build-system without further intervention.

bash@host:~$ cd GePhex bash@host:~/GePhex$./bootstrap.sh running aclocal ... running libtoolize --force ... running autoheader ... running automake --add-missing --copy ... running autoconf ... ./configure has been succesfully built! See './configure --help' for available options

Configure and Build

This step configures the build system for your system. You need the following libraries to get all the features of GePhex:

• libqt xlib

• libsdl libpng mesa

At the very least you should have libqt and xlib installed. If not the GUI will not be built.

At this point you can choose the location where the software should be installed. Some special options to include/exclude features can also be activated here. E.g. if you have a recent x86 processor you could enable the faster MMX implementation for some modules.

To see the available options you can use the configure script:

bash@host:~/GePhex$./configure --help `configure' configures this package to adapt to many kinds of systems. ... Installation directories: --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local] ... Optional Features: ... --enable-mmx Turn on MMX support. Still runs on x86 that don't have MMX! --enable-serialize-framebuffer Serialize the framebuffer type (for previews in the gui). Optional Packages: ... --with-effectv=dir Compile with effectv. Needs effectv source files. You must provide the effectv src dir. Example: --with-effectv=/home/georg/effectv-0.38 ...

So let's do the actual configuration:

bash@host:~/GePhex$ ./configure --enable-mmx --with-v4l --prefix=/usr checking for a BSD-compatible install... /usr/bin/install -c checking whether build environment is sane... yes checking for gawk... gawk checking whether make sets $(MAKE)... yes checking for g++... g++ ...

Lets now start the actual build process. Dependent on you system this could take a long time.

bash@host:~/GePhex$ make make all-recursive make[1]: Entering directory `/home/martin/code/gephex/GePhex' Making all in base make[2]: Entering directory `/home/martin/code/gephex/GePhex/base' Making all in src make[3]: Entering directory `/home/martin/code/gephex/GePhex/base/src' ...

Installation

The following command installs the software on your system. The two binaries for the user interface gephex-gui and the rendering engine gephex-engine will be installed in the PREFIX/bin directory and the location of the plugins is in PREFIX/lib/gephex.

bash@host:~/GePhex# make install

You might need to be root to install (depending on the installation prefix you chose).

Create your own Debian Packages

TODO: Does this work in the sources from a dist tar.gz, too?

Users of the Debian GNU/Linux OS can create Debian binary packages from the source and install these with dpkg. Just change in the root to the Source tree and invoke the dpkg-buildpackages. After a successful build you can install the generated packages.

bash@host:~/GePhex$ fakeroot dpkg-buildpackages bash@host:~/GePhex$ sudo dpkg -i ../gephex*.deb

Using our APT Repository

The Debian binary package format is the common way to install software on a Debian GNU/Linux system. Using the dpkg, a medium-level tool to install, build, remove and manage Debian GNU/Linux packages, the system stays in a consistent state after changes to the software installation or configuration. The proper deinstallation and upgrade to a other version of the application package is guaranteed.

Add the GePhex apt repository lines to your /etc/apt/sources.list and install GePhex with apt-get:

bash@host:~$ sudo cat >> /etc/apt/sources.list deb http://gephex.sourceforge.net/debian/ stable main bash@host:~$ sudo apt-get install gephex

If your Debian GNU/Linux distribution is testing or unstable you have to replace the stable in the apt line with your distribution name.

UN*X

You can start GePhex by executing gephex-engine and gephex-gui in a shell (in that order).

If you chose your own prefix for the install, make sure the binaries are in the path.

WIN32

Just go into the bin directory of your GePhex directory and execute the engine and the GUI (in that order).

Structure of the GUI

As you can see in the image, the GUI (Graphical User Interface) is divided into four major areas. The areas are marked with a red pen.

• 1: Info-window. Used for properties of effects, loading and saving effect-graphs, sequences, and playlists.

• 2: Graph-window. Used to edit effect-graphs.

• 3: Control-window. Used to control running effect-graphs.

• 4: Message- and sequence-window. Used to display error and warning messages and to edit sequences.

The First Graph

The most important concept for using GePhex is that of an effect-graph. An effect-graph is a number of simple basic effects, combined to perform a more complex effect.

Since GePhex works on graphs, we have to tell it which graph we want to edit. Do this by clicking on the "Graphen" tab in the info-window. To create a new graph, right-click on the "Graphen" item inside the tab (see next image).

When the context-menu opens up, just select "New Graph". Enter "first" in the dialog.

Now you see another item called "first" in the tree-view below "default". This is our new graph. To activate it, click on the arrow (or plus symbol) left to "first". Click on the appearing child item "default".

This child item is a "snapshot" of the graph. For now you just need to know, that you need one active graph with one active snapshot in order to create an effect.

The letters "r" and "e" tell you that graph "first" is active (with current snapshot "default").

Adding Effects to the Graph

Now we have created a new graph. But it is not very useful yet, because it is empty. So let's create some effects.

To do so, open the "Effekte" menu in the top-level menu-bar. Choose "Quellen"->"Bitmap Loader". Then click into the graph window as shown in the next image.

Do the same for "Effekte"->"Outputs"->"X11 Output" (or "GDI Output" on win32) and "Effekte"->"Filter"->"FlashFader". Arrange them as in the next image (You can simply move them around with the mouse).

The red boxes on the left side of the basic effects are inputs, the blue buttons on the right are outputs.

Connect the effects as shown in the next picture:

The graph we have created so far is still very simple. In fact, you would not call such a graph an effect at all. What it does is simply loading a bitmap, eventually flashing it and displaying it to screen.

You can think of this graph in terms of data flow: data comes from a source (the bitmap loader), flows through the flash-fader filter and is displayed in the sink (the output).

Configuring the Graph

This is simple. We just choose a bitmap. Right-click on the "Bitmap-loader"-effect and choose "Properties" in the context menu. Now the info-window displays the properties of the bitmap effect:

Click on the button next to "Dateiname" and choose a nice bmp file.

Running and controlling the Graph

Simple again. Just click on the little red fellow on the bottom right. You should see the output window opening and displaying the bmp file you chose. To inform you that it is running, GePhex turns the red fellow to a green fellow.

To control the flash-fader effect we must add a control at the upper input of the flash-fader. The following picture explains how you can add a control to an input:

Just try it!

GePhex must be running for the control changes to take effect!.

Saving the Graph

Click on the "Graphen" tab in the info-window. Right-click on "first" and choose "Save Graph". Done. The graph will be already there when you start next time.

Win32

All following paths are relative to your GePhex distribution dir (for example c:\programs\GePhex-0.0.4alpha\). Just copy the files in examples\graphs into graphs and restart GePhex if it is running.

Un*x

Copy the files in [your gephex source dir]/examples/graphs to ~/.gephex/graphs. The ~/.gephex directory is created the first time you start GePhex.

ifsmodule

Linear iterated function systems are a fractal type. The module renders these kind of ifs parameter sets to a image.

libmpeg3module

This module has only one input. This is the name of a video file. The module opens and decodes this. The frames are exported to the output. The resolution is the original of the video stream.

Supported file formats are mpeg1 and mpeg2 ...

v4lmodule

Video4linux is the original video capture/overlay API of the linux kernel. It is based on the API introduced by the bttv driver. It seems that v4l will be replaced in the next stable linux kernel by its successor Video for Linux Two but at the moment no distribution has support for that API in its precompiled kernels. Support for this API is planned.

The first input is the filename of the video device. This is normally /dev/videoX where X is the number of the device. It is possible to switch the device during rendering. An invalid device results in a black output screen. The device is opened the first time the output of the module is used and closed with quit of the gephex-engine. A manual unloading of the module can also free the device handles. The other two inputs force the size of the grabbed image. If the device doesn't support that resolution a black frame is generated. A resolution 0,0 forces the module to choose any capable resolution. The output is either the grabbed frame from the v4l device or in case of an error a black, fully transparent 1x1 image.

The current version of this module is tested with the 2.4.20 kernel drivers of the the usb webcam PCVC740K "ToUCam Pro" from Phillips and the pci bttv848 frame-grabber card win-TV radio.

known bugs:

• A error in the yuv2rgb conversion function creates sometimes a broken bottom line.

• The capturing process is not while one update of the module. it is between two updates. If update isn't called every frame e.g. cause the branch isn't needed the module delivers one old frame with the first update. One solution is the check system time and check for dropped frames

• the memory of the output frame is allocated in the module and not the resize code of the framebuffertype is called

Further informations about video4linux driver- and user-space programming can be found in the kernel documentation (kernel-source-2.4.20/Documentation/video4linux/API.html and kernel-source-2.4.20/Documentation/DocBook/videobook.tmpl) and in the video4linux mailing list.

The c-API

A GePhex data type plugin is a shared library. There is exact one data type in each library file. The file suffix is .so on the Unix platforms and .dll on ms windows system. Each library exports a set of function symbols as defined in the following section.

The GePhex type API consists of a required and an additional part. Every type plugin must implement the required part. The loader of a type plugin must ignore plugins that don't export these symbols. By implementing functions of the additional part the serialisation and automatic subtype conversion functionality can be enabled. But not for all effects these features are necessary.

The first group of function are independent of type instances. The functions init and shutdown handle the (un)loading of the plugin. getInfo and getSpec allow the host application to query information about the type from the plugin.

The second group is instance based. There are functions to create and destroy type objects like newInstance and deleteInstance. Others assign and convertType instances. The created instances are identified by objects of the type TypeInstanceID this is a unique id with the size of a pointer. It is up to the user of the type plugin to ensure not to mix type object identifier and functions of different types.

There are two optional features a type can provide: (de)serialisation and type attributes.

Type attributes describe different representations of values and allow to convert between them. A color is can be in the RGB, YUV or HSV color-space. The color doesn't change if the convert between them. It is just the representation that changes. A color type can have a attribute color-space and some functions to convert transparent from one space to another. Types that have attributes must implement convertType and attributesEqual.

To store type instances or to transfer them via network it isn't enough to store/transfer the TypeInstanceID we must store the real value not the identifier. The functions serialize and deSerialize convert type instances to a byte-stream and back.

typedef void* TypeInstanceID;

typedef void* TypeInstanceID;

typedef void* TypeInstanceID;

typedef void* TypeInstanceID;

typedef void* TypeInstanceID;

typedef void* TypeInstanceID;
typedef void* TypeAttributesInstanceID;

typedef void* TypeInstanceID;
typedef void* TypeAttributesInstanceID;

An example for a new datatype

The following chapter describes the necessary steps to implement a new datatype plugin. The new type will be a color palette. Mathematically this is is a mapping from an interval to the color-space. Since the standard color-space in the GePhex is the red-green-blue color-model with 256 discrete steps from each color-channel and a source space with 256 elements the palette can easily implemented as a array with 256 RGBA entries.

The implementation of the new type is split up in two files: palettetype.h and palettetype.c. The .c file includes the header and will be compiled to the shared library. In the .c files are the exported functions defined. The memory layout of the type and all helper methods resists in the header-file, cause all modules that use the type include the header and do not link with the shared library.

We define the memory layout of the new type in the header in a straight forward way:

typedef struct PaletteType_ { uint_32 pal[256]; } PaletteType;

uint_32 is a typedef for an unsigned integer with 32 bit size. It is defined in the header basic_types.h. The 32 bits of the integer are composed by the 4 color components red, green, blue and alpha.

The next step is to define the functions of the shared library. To keep it simple we'll implement only the necessary core methods: getInfo,getSpec,deleteInstance,newInstance and assign

The implementation of getInfo and getSpec are similarly for all types their propose is to deliver type-specific info strings to the caller. For the new type we set these two strings to:

"typ_spec { name=typ_PaletteType; }" and "info { name=Palette }".

const char* getSpec(void) { // return the specification string return "typ_spec { name=typ_PaletteType; }"; } int getInfo (char* buf,int bufLen) { static const char* INFO = "info { name=Palette }"; int reqLen = strlen(INFO) + 1; // check if the buffer is big enough if (buf != 0 && reqLen <= bufLen) { // the string fits in, copy it memcpy(buf,INFO,reqLen); } return reqLen;

The other three mandatory functions are the constructor, the destructor and assignment method. In the .c file we place simple wrappers to the real methods in the header. This ensures that modules and the engine use the same implementation since the modules include the type-headers and the engine loads the shared libraries.

void* newInstance(void) { return palette_newInstance(); } void assign(void* dst,const void* src) { palette_assign((PaletteType*)dst,(const PaletteType*)src); } void deleteInstance(void* pal) { palette_deleteInstance((PaletteType*) pal); }

The actual implementation of the functions palette_newInstance, palette_assign and palette_deleteInstance is in the header.

The creation of a new type object is split into two functions: one for memory allocation and the other for initialisation it with the default value.

// initialise a palette with the default value static __inline void number_initInstance(PaletteType* newType) { int i; for(i=0;i!=256;++i) { newType->palette[i] = 0x00000000; } } // allocate memory for a new palette type-object and initialise it static __inline PaletteType* palette_newInstance(void) { PaletteType* newType = (PaletteType*) malloc(sizeof(PaletteType)); palette_initInstance(newType); return newType; }

The assign method just copies the entries of the source array to the destination.

// assign the value of the source palette to the destination palette static __inline void palette_assign(PaletteType* dst,const PaletteType* src) { dst->palette = src->palette; int i; for(i=0;i!=256;++i) { dst->palette[i] = src->palette[i]; } }

The type allocates memory the destructor must free this resource for reuse.

/* frees the allocated memory for a palette type object */ static __inline void palette_deleteInstance(PaletteType* pal) { free(pal); }

The C-API

A module is a shared library that exports some c functions. In the following section the necessary and the optional methods and their semantics are described.

typedef void (*logT) (int, const char*);