The GePhex Book

The engine can be started from the console with the gephex-engine command. The only environment variable that is used is DISPLAY for the output under X11. All options are set in the configuration file ~/.gephex/0.4/gephex.conf. If this file does not exist, 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/]
    frei0r_path          = [/home/cip/seidel/.frei0r-1/lib/]
    graph_path           = [/home/cip/seidel/.gephex/0.4/graphs/]
    ipc_unix_node_prefix = [/tmp/gephex_socket_]
    ipc_type             = [inet]
    ipc_port             = [6666]
    renderer_interval    = [40]
    net_interval         = [40]
}
...

In the following, a path is a semicolon separated list of directories, which are searched by the engine in the given order.

All options that can be set in the config file can be overridden from the command line. For example

  > gephex-engine --ipc_port=1234

overrides the value of the option ipc_port.

The --help option shows a list of available parameters with a short help text.

    > gephex-engine --help
                  welcome to...
       ---             _           ---
    ----              | |            ----
  ----   __ _ ___ _ __| |  ___ _  __  ----
 -----  / _' | - \ '_ \ |_/ - \ \/ /  -----
------ | (_| | --/ |_) |  \ --/>  <   ------
 -----  \__. | \_| .__/ |' |\_/ /\ \  -----
  ----   ._' |\__/ |  |_||_|__//  \_| ----
   ----  |__/    |_|                 ----
      ---                          ---

[version:    "0.4.3"]
[build time: "Mar  5 2005 - 00:13:18"]
Usage: /Users/georg/gphx//bin/gephex-engine-real [options]
The allowed options are:
  --media_path  List of directories that contain videos, images and fonts (separated by ';')
...
  

The gui can be started on the console with the gephex-gui command. There are two environment variablse that influence the guis behaviour, see the note at the end of the section. All options are set in the configuration file ~/.gephex/0.4/gephex.conf. If this file does not exist 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, ...).

All options that can be set in the config file can be overridden from the command line. For example

  > gephex-gui --media_path=/mnt/data/footage/

overrides the value of the option media_path.

The --help option shows a list of available parameters with a short help text.

    > gephex-gui --help
Usage: /Users/georg/gphx//bin/gephex-gui-real [options]
The allowed options are:
  --media_path  List of directories that contain videos, images and fonts (separated by ';')
...
  

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 behavior, 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.

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.

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

On windows you can use, for example, WinRAR to unpack the file.

Building on Mac OS X is very similar to building on other UNIX systems.

Note that the tools described here are only one choice of several alternatives. If you find a better way to build gephex on Mac OS X let us know.

Here comes a list with tools that can be used to build gephex.

After that everything should work as described in the section called “Building on Unix Platforms”.

If you manage to compile and link gephex against the native qt version for Mac OS X please let us know!

We are looking for people to improve gephex on Mac OS X. Important areas that need work:

If you are interested let us know!

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

Just get the windows binary .rar or .zip file and unpack it. GePhex can be started from the bin directory.

You can start GePhex by executing gephex.

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

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

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.

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

Creating a graph

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

Choosing the name of the graph

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

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

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

Adding an basic effect

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:

Connecting effects

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

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:

Properties

Click on the button next to "Filename" and choose a nice image file.

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:

Creating a control

Just try it!

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.

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

This IFS fractal is rendered in gray scale mode.

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.

    "info { name=Palette }"
  

  "typ_spec { name=typ_IntType; }" 
 

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;

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);
}

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

mod_spec 
   { 
     name = mod_STRING; 
     number_of_inputs = UINT; 
     number_of_outputs = UINT; 
     deterministic = BOOL 
   }

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:

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.

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
    }
}

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!