The Engine

The engine can be started from the console with the gephex-engine command. At the moment there are no command-line options. The only environment variable that is used is DISPLAY for the output under X11. All options are set in the configuration file ~/.gephex/gephex.conf. If no file exists a default configuration file is created.

common { media_path = [/home/tmp/seidel/gphx/share/gephex] } engine { module_path = [/home/tmp/seidel/gphx/lib/gephex/modules/] type_path = [/home/tmp/seidel/gphx/lib/gephex/types/] graph_path = [/home/cip/seidel/.gephex/graphs/] ipc_unix_node_prefix = [/tmp/gephex_socket_] ipc_type = [inet] ipc_port = [6666] renderer_interval = [40] net_interval = [40] } ...

media_path is used for both engine and gui. It is a semicolon separated list of directories, which contain media for GePhex (i.e. images, videos, fonts, ...). module_path is the absolute path to the directory with the effect plugins. The shared libraries for the types are stored in the type_path. The graph_path variable tells the engine the location of the user created graphs (semicolon separated list of directories). 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 because it has less overhead. The parameters ipc_unix_node_prefix and ipc_port must equal to the ones for the gui.

The GUI (graphical user interface)

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

common { media_path = [/home/tmp/seidel/gphx/share/gephex] } ... gui { ipc_type = [inet] ipc_inet_hostname = [localhost] ipc_port = [6666] ipc_unix_node_prefix = [/tmp/gephex_socket_] engine_binary = [/home/tmp/seidel/gphx/bin/gephex-engine] }

media_path is used for both engine and gui. It is a semicolon separated list of directories, which contain media for GePhex (i.e. images, videos, fonts, ...). 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 because it has less overhead. The parameters ipc_unix_node_prefix, ipc_namedpipe_servername, and ipc_port must equal to the ones in for the engine. engine_binary is the full path of the engine executable. It is used to spawn a engine process if necessary.

The gephex script

On unix platforms, a script called gephex is installed. It takes care of starting the engine and the gui.

The engine is started in an x-terminal-emulator, which defaults to x-terminal-emulator, and if that does not exists on your system xterm is used.

To override this behaviour, you can set the GEPHEX_XTERM environment variable. Make sure that your terminal emulator accepts the "-e" flag to execute a program. To add extra flags to your terminal emulator, use the GEPHEX_XTERM_FLAGS environment variable. Example:

> GEPHEX_XTERM=aterm GEPHEX_XTERM_FLAGS="-fg green -bg black" gephex

If you need even more control, look at the file ~/.gephex/run_in_terminal.sh. If you want to restore the default for some reason, it's ok to simply delete it, gephex will copy the default file if it does not find it there.

The gui uses the same mechanism to start the engine, so you can provide the GEPHEX_XTERM* variables for the gui, too.

Getting the latest version from the arch archive

I assume that you use the tla arch-client. To get the latest version you need to register the gephex archive. The name of the archive is gephex@gephex.org--2004 and the location is http://arch.gephex.org/gephex/2004.

bash@host:~$ tla register-archive http://arch.gephex.org/gephex/2004 Registering archive: gephex@gephex.org--2004 bash@host:~$

The full name of the revision is gephex--main--0.4:

bash@host:~$ tla get -A gephex@gephex.org--2004 gephex--main--0.4 GePhex * from archive cached: gephex@gephex.org--2004/gephex--main--0.4--patch-1727 * patching for revision: gephex@gephex.org--2004/gephex--main--0.4--patch-1728 * making pristine copy * tree version set gephex@gephex.org--2004/gephex--main--0.4 bash@host:~$

This command will fetch the latest version of gephex into the directory ./GePhex.

If you have questions regarding arch please have a look at the projects homepage.

Getting a Distribution-Tarball

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

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

Bootstrapping

This step is only necessary when you got the sources from the arch repository. The distributed tar balls 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. You should use rather new versions of automake and autoconf. For automake, 1.8 is known to work and 1.4 is known to *not* work with our build system. For autoconf, 2.59 is known to work.

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

• autoconf automake libtool

• python

• sgmltools-lite docbook-utils

GePhex uses autoconf and automake for the configuration and generation of 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 successfully 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 avifile alsa aalib

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: ...

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++ ...

Now we can start the build process. Depending 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

Users of the Debian GNU/Linux OS can create Debian binary packages from the source and install these as root with dpkg.

To build debian packages you need these debian packages installed:

• debhelper

• libqt3-mt-dev

• libsdl1.2-dev

• xlibmesa-dev

• libpng12-dev

• libavifile-0.7-dev

• libsdl-ttf2.0-dev

• libasound2-dev

• libmpeg3-dev

• libsdl-image1.2-dev

• automake1.8

• libtool

• autoconf

• python

• sgmltools-lite

• docbook-to-man

• docbook-utils

Not all necessary files for building the debian packages are included in the dist tarballs. You need to get a full copy of the gephex source tree from the arch repository. The necessary steps to do this are described above.

First bootstrap the clean source tree by calling the bootstrap.sh script in the root of the source tree. Then build the packages with the dpkg-buildpackage commando. After a successful build you can install the generated packages as superuser with dpkg.

bash@host:~/GePhex$ ./bootstrap bash@host:~/GePhex$ fakeroot dpkg-buildpackage bash@host:~/GePhex$ sudo dpkg -i ../gephex_0.4-1_i386.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://www.gephex.org/debian/ unstable main bash@host:~$ sudo apt-get install gephex

UN*X

You can start GePhex by executing gephex.

If you chose your own prefix for the install, make sure the gephex binariy is in the path.

WIN32

Just go into the bin directory of your GePhex directory and execute the gephex-engine and gephex-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 and for loading and saving effect-graphs,

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

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

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

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 with graphs, we have to tell it which graph we want to edit. Do this by clicking on the "Graphs" tab in the info-window. To create a new graph, right-click on the "Graphs" 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 "Effects" menu in the top-level menu-bar. Choose "Sources"->"Image Source". Then click into the graph window as shown in the next image.

Do the same for "Effects"->"Outputs"->"Image Output" and "Effects"->"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 the screen.

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

Configuring the Graph

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

Click on the button next to "Filename" and choose a nice image 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 "Graphs" 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.

ifsmodule

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

Video-playback (avifilemodule)

Video for Linux (capturemodule)

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 serialization 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)serialization 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 data type

The following chapter describes the necessary steps to implement a new data type 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 initialization it with the default value.

// initialize 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 initialize 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*);

Pluc the skeleton generator

The c-api design allows module developers to write their plugins in almost any programming language. This is achieved by a very low-level interface between host and plugin.

Pluc is distributed with GePhex in the modules subdirectory.

Many module functions are very simple and have just some lines of code. We want to implement a module that outputs the maximum of its number inputs. In c++ this would be a one-liner:

double output1,input1,input2;
output1 = std::max(input1,input2)

But the effort needed to export this piece of code via the c-api interface is huge. This is the reason why the pluc.py stub generator exists.

The idea of pluc is that many properties of a module are described in a spec file. Pluc can generate from this file:

• the build-system files (for automake and MS Visual Studio)

• a convenience layer to abstract from the c-api

• a minimum skeleton code for the module implementation that can be used as a basis for implementing the function.

Sample invocations of pluc:

pluc.py dsp testmodule.spec pluc.py am testmodule.spec pluc.py skel testmodule.spec

As can be seen, the first argument to pluc is a command. The second is the filename of the plugin specification.

---

Syntax and semantics of the spec file

A spec file consists of three parts. Each part is composed of an identifier followed by a block enclosed in curly braces. The first part contains global settings that determine the behavior of the whole module. The second part contains settings for all inputs of the module. The third part contains settings for all outputs of the module.

---

Global settings

The global settings begin with a unique name for the module, by convention prefixed with "mod_". To stick with the example from above we choose "mod_max".

Table 8-2. Mandatory global settings

name	STRING
deterministic	BOOL
group	STRING
xpm	FILENAME
author	STRING
version	STRING

name

the name that is visible to the user

deterministic

specifies if the module produces the same output whenever the input is the same. This is for example not true for a module that produces random numbers.

group

allows to group several effects

xpm

the name of a xpm file that is used as an icon for this module

The following settings are optional:

• enablePatching: BOOL

---

Input settings

The settings in the input block determine the type, default value and other attributes for every input.

The input block is composed of several blocks, one for each input.

Table 8-3. Mandatory input settings

name	STRING
type	STRING
const	BOOL
strong_dependency	BOOL

name

the name that is visible to the user

type

the type of the input (number, framebuffer, audio, color,...)

const

true iff the module does not change the value of the input

strong_dependency

true iff this input is needed every frame

These attributes are optional.

Table 8-4. Optional input settings

default	STRING
version	STRING

You can provide more optional settings. They are not checked by the engine and can be used to give more information to the gui.

Here is an input block with two number inputs.

inputs { lhs { name = x type = typ_NumberType const = true strong_dependency = true default = 0 widget_type = unboundednumber_selector } rhs { name = y type = typ_NumberType const = true strong_dependency = true widget_type = unboundednumber_selector default = 0 } }

---

Output settings

The settings in the output block determine the type and name for every output.

The output block is composed of several blocks, one for each output.

Table 8-5. Mandatory output settings

name	STRING
type	STRING

Example for an output block with one output:

outputs { r { name = Result type = typ_NumberType } }

An example for a new module

Putting all together, the complete spec for our max module looks like this:

mod_maxmodule { name = Maximator deterministic = true group = Number xpm = maxmodule.xpm author = Zardoz version = 1.0 } inputs { lhs { name = x type = typ_NumberType const = true strong_dependency = true default = 0 widget_type = unboundednumber_selector } rhs { name = y type = typ_NumberType const = true strong_dependency = true widget_type = unboundednumber_selector default = 0 } } outputs { r { name = Result type = typ_NumberType } }

Let's assume the spec file is called maxmodule.spec. The next step is to produce a Makefile.am and the skeleton code:

> pluc.py am maxmodule.spec > pluc.py skel maxmodule.spec

The skeleton code will be called maxmodule.c. After you have included the Makefile.am into your build system, the glue code will be automatically generated when you compile the maxmodule. So whats left to do is to edit the update method in maxmodule.c:

void update(void* instance) { InstancePtr inst = (InstancePtr) instance; inst->out_r->number = max(inst->in_lhs->number, inst->in_rhs->number); }

That's all!