GEGL-0.0.14

Contents

  • GEGL
  •   Features
  •   Gallery
  •   Dependencies
  •   Download
  •   Building
  •   Bugzilla
  •   Mailinglist
  •   Copyright
  •  
  • Documentation
  •   Glossary
  •   Operations
  •   API reference
  •   Hello World
  •   XML data model
  •   Environment
  •   gegl
  •  
  • Bindings
  •   rgegl
  •   pygegl
  •   gegl-sharp
  •  
  • Development
  •   Code Overview
  •  
  •  
  • changes
  • bugzilla
  • mailarchive
  • viewcvs

GEGL

GEGL (Generic Graphics Library) is a graph based image processing
framework.

GEGL's original design was made to scratch GIMP's itches for a new
compositing and processing core. This core is being designed to have
minimal dependencies. and a simple well defined API.

Features

  • Output in RGB, CIE Lab and Y'CbCr color models with 8bit, 16bit
    integer and 32bit floating point per component. Possible to extend
    to ICC managed output in babl.
  • Non destructive editing
  • C, C#, Python and Ruby interfaces.
  • Extendable through plug-ins.
  • XML serialization format (not-finalized)
  • Iterative processing.
  • Efficient subregion evaluation.
  • Per node caches.
  • Processing and display of image buffers larger than RAM
  • Internal sparse pyramidial render cache.
  • Bounding box based hit detection.
  • Rich core set of processing operations that internally computes
    with 32bit floating point, linear light RGB.
      □ PNG, JPEG, SVG, EXR, RAW, ffmpeg and other image sources.
      □ Pattern renderers
      □ Arithmetic operations
      □ porter duff compositing
      □ SVG filter modes and full set of compositing ops from SVG-1.2
        draft
      □ Gaussian blur, bilateral-filter, symmetric nearest neighbour,
        unsharp mask.
      □ Color correction.
      □ Text layout using pango

Gallery

For examples of what GEGLs rendering engine currently can do look at
the gallery.

Dependencies

GEGL is currently building on linux, the build enviroment probably
needs some fixes before all of it builds gracefully on many platforms.

  • Core
      □ glib (including gobject, and gmodule) 2.10 or newer, which
        provides inheritance, dynamic modules, common algorithms and
        data structures for C programming.
      □ babl 0.0.14 or newer (for pixel-format agnostisism).
      □ libpng (png load/export ops, and image magick fallback import)
  • GUI (sandbox for testing ops and the API)
      □ GTK+
  • Optional dependencies for operations.
      □ SDL (display op)
      □ libjpeg (jpg loader op)
      □ libopenexr (exr loader op)
      □ cairo, pango (text source op)
      □ librsvg

Download

The latest development snapshot, and eventually stable versions of GEGL
are available at ftp://ftp.gimp.org/pub/gegl/.

The current code under development can be browsed online and checked
out from GNOME Subversion using:

svn co http://svn.gnome.org/svn/gegl/trunk/ gegl

Building

To build GEGL type the following in the toplevel source directory:

$ ./configure  or: ./autogen.sh if building from svn
$ make
$ sudo make install

Bugzilla

The GEGL project uses GNOME Bugzilla, a bug-tracking system that allows
us to coordinate bug reports. Bugzilla is also used for enhancement
requests and the preferred way to submit patches for GEGL is to open a
bug report and attach the patch to it.

Below is a list of links to get you started with Bugzilla:

  • List of Open Bugs
  • List of Open Bugs (excluding enhancement requests)
  • List of Enhancement Proposals
  • Bugzilla Weekly Summary

Mailinglist

You can subscribe to gegl-developer and view the archives here. The
GEGL developer list is the appopriate place to ask development
questions, and get more information about GEGL development in general.
You can email this list at gegldev at gegl.org.

Copyright

GEGL 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 3 of the License, or (at your
option) any later version.

Contributors


Code:
  Calvin Williamson
  Caroline Dahloff
  Manish Singh
  Jay Cox
  Daniel Rogers
  Sven Neumann
  Michael Natterer
  Øyvind Kolås
  Philip Lafleur
  Dominik Ernst
  Richard Kralovic
  Kevin Cozens
  Victor Bogado
  Martin Nordholts
  Geert Jordaens
  Michael Schumacher
  John Marshall
  Étienne Bersac
  Mark Probst
  Håkon Hitland
  Tor Lillqvist

Documentation:
  Garry R. Osgood
  Øyvind Kolås
  Kevin Cozens
  Shlomi Fish

Artwork:
  Jakub Steiner

Documentation

GEGLs programmer/user interface is a Directed Acyclic Graph of nodes.
The DAG expresses a processing chain of operations. A DAG, or any node
in it, expresses a composited and processed image. It is possible to
request rectangular regions in a wide range of pixel formats from any
node. See the Glossary to decode this paragraph.

The GEGL API is available from both C as well as Ruby and Python. The
XML Data model provides a tree based interface that maps to the
internal DAG (Directed Acyclic Graph). Environment Variables can be set
to tune and instrument the behavior of GEGL. gegl is small commandline
tool acting as a wrapper around the XML capabilities that provides
output to PNG.

Glossary

connection
    A link/pipe routing image flow between operations within the graph
    goes from an output pad to an input pad, in graph glossary this
    might also be reffered to as an edge.
DAG
    Directed Acyclic Graph, see graph.
graph
    A composition of nodes, the graph is a DAG.
node
    The nodes are connected in the graph. A node has an associated
    operation or can be constructed graph.
operation
    The processing primitive of GEGL, is where the actual image
    processing takes place. Operations are plug-ins and provide the
    actual functionality of GEGL
pad
    The part of a node that exchanges image content. The place where
    image "pipes" are used to connect the various operations in the
    composition.

    input pad
        consumes image data, might also be seen as an image parameter
        to the operation.
    output pad
        a place where data can be requested, multiple input pads can
        reference the same output pad.

property
    Properties are what control the behavior of operations, through the
    use of GParamSpecs properties are self documenting through
    introspection.

Operations

The main source of documentation as GEGL grows is the Operations
reference. Plug-ins themselves register information about the
categories they belong to, what they do, and documentation of the
available parameters.

Hello world

This is a small sample GEGL application that animates a zoom on a
mandelbrot fractal


#include <gegl.h>

gint
main (gint    argc,
      gchar **argv)
{
  gegl_init (&argc, &argv);  /* initialize the GEGL library */

  {
    /* instantiate a graph */
    GeglNode *gegl = gegl_node_new ();

/*
This is the graph we're going to construct:

.-----------.
| display   |
`-----------'
   |
.-------.
| layer |
`-------'
   |   \
   |    \
   |     \
   |      |
   |   .------.
   |   | text |
   |   `------'
.-----------------.
| FractalExplorer |
`-----------------'

*/

    /*< The image nodes representing operations we want to perform */
    GeglNode *display    = gegl_node_create_child (gegl, "display");
    GeglNode *layer      = gegl_node_new_child (gegl,
                                 "operation", "layer",
                                 "x", 2.0,
                                 "y", 4.0,
                                 NULL);
    GeglNode *text       = gegl_node_new_child (gegl,
                                 "operation", "text",
                                 "size", 10.0,
                                 "color", gegl_color_new ("rgb(1.0,1.0,1.0)"),
                                 NULL);
    GeglNode *mandelbrot = gegl_node_new_child (gegl,
                                "operation", "FractalExplorer",
                                "width", 256,
                                "height", 256,
                                NULL);

    gegl_node_link_many (mandelbrot, layer, display, NULL);
    gegl_node_connect_to (text, "output",  layer, "aux");

    /* request that the save node is processed, all dependencies will
     * be processed as well
     */
    {
      gint frame;
      gint frames = 30;

      for (frame=0; frame<frames; frame++)
        {
          gchar string[512];
          gdouble t = frame * 1.0/frames;
          gdouble cx = -1.76;
          gdouble cy = 0.0;

#define INTERPOLATE(min,max) ((max)*(t)+(min)*(1.0-t))

          gdouble xmin = INTERPOLATE(  cx-0.02, cx-2.5);
          gdouble ymin = INTERPOLATE(  cy-0.02, cy-2.5);
          gdouble xmax = INTERPOLATE(  cx+0.02, cx+2.5);
          gdouble ymax = INTERPOLATE(  cy+0.02, cy+2.5);

          if (xmin<-3.0)
            xmin=-3.0;
          if (ymin<-3.0)
            ymin=-3.0;

          gegl_node_set (mandelbrot, "xmin", xmin,
                                     "ymin", ymin,
                                     "xmax", xmax,
                                     "ymax", ymax,
                                     NULL);
          g_sprintf (string, "%1.3f,%1.3f %1.3f×%1.3f",
            xmin, ymin, xmax-xmin, ymax-ymin);
          gegl_node_set (text, "string", string, NULL);
          gegl_node_process (display);
        }
    }

    /* free resources used by the graph and the nodes it owns */
    g_object_unref (gegl);
  }

  /* free resources globally used by GEGL */
  gegl_exit ();

  return 0;
}

Compiling

GEGL uses pkg-config for passing the needed compile time options,
download hello-world.c and typing what follows in a terminal after
succesfully installing GEGL should produce a working binary.

gcc hello-world.c `pkg-config --libs --cflags gegl` -o hello-world

XML data model

The tree allows clones, making it possible to express any acyclic graph
where the nodes are all of the types: source, filter and composer.

GEGL can write and reads its data model to and from XML. The XML is
chains of image processing commands, where some chains allow a child
chain (the 'over' operator to implement layers for instance).

The type of operation associated with a node can be specified either
with a class attribute or by using the operation name as the tag name
for the node.

For documentation on how this XML works, take a look at the sources in
the gallery. And browse the documentation for operations.

Environment

Some environment variables can be set to alter how GEGL runs, this list
might not be exhaustive but it should list the most useful ones.

BABL_STATS
    When set babl will write a html file (/tmp/babl-stats.html)
    containing a matrix of used conversions, as well as all existing
    conversions and which optimized paths are followed.
BABL_ERROR
    The amount of error that babl tolerates, set it to for instance 0.1
    to use some conversions that trade some quality for speed.
GEGL_DEBUG_BUFS
    Display tile/buffer leakage statistics.
GEGL_DEBUG_RECTS
    Show the results of have/need rect negotiations.
GEGL_DEBUG_TIME
    Print a performance instrumentation breakdown of GEGL and it's
    operations.
GEGL_SWAP
    The directory where temporary swap files are written, if not
    specified GEGL will not swap to disk. Be aware that swapping to
    disk is still experimental and GEGL is currently not removing the
    per process swap files.

gegl

GEGL provides a commandline tool called gegl, for working with the XML
data model from file, stdin or the commandline. It can display the
result of processing the layer tree or save it to file.

Some examples:

Render a composition to a PNG file:

gegl composition.xml -o composition.png

Invoke gegl like a viewer for gegl compositions:

gegl -ui -d 5 composition.xml

Using gegl with png's passing through stdin/stdout piping.

cat input.png | gegl -o - -x "<gegl>
<tree>
  <node class='invert'/>
  <node class='scale' x='0.5' y='0.5'/>
  <node class='png-load' path='-'/></tree></gegl>" > output.png

The latest development version is available in the gegl module in GNOME
Subversion.

gegl usage

The following is the usage information of the gegl binary, this
documentation might not be complete.


usage: gegl [options] <file | -- [op [op] ..]>

  Options:
     --help      this help information
     -h

     --file      read xml from named file
     -i

     --xml       use xml provided in next argument
     -x

     --dot       output a graphviz graph description
     --output    output generated image to named file
     -o          (file is saved in PNG format)

     -p          (increment frame counters of various elements when
                  processing is done.)

     -X          output the XML that was read in

     --verbose   print diagnostics while running
      -v

All parameters following -- are considered ops to be chained together
into a small composition instead of using an xml file, this allows for
easy testing of filters. Be aware that the default value will be used
for all properties.


Bindings

The bindings for use of GEGL in other programming languages than C are
co-hosted with GEGL in GNOME subversion but are not part of the regular
GEGL distribution. The following language bindings are currently
available:

rgegl
    for Ruby.
pygegl
    for Python.
gegl-sharp
    for C#/Mono.

Development

GEGL uses bugzilla to track feature requests and contributions. A
description of what the various directories in the GEGL checkout is in
the Code Overview. Most coders working with gegl would probably be
extending it through operations.

Code Overview

Directories in the GEGL distribution

gegl-dist-root
 │
 │
 ├──gegl               core source of GEGL, library init/deinit,
 │   │
 │   ├──buffer         contains the implementation of GeglBuffer
 │   │                  - sparse (tiled)
 │   │                  - recursivly subbuffer extendable
 │   │                  - clipping rectangle (defaults to bounds when making
 │   │                    subbuffers)
 │   │                  - storage in any babl supported pixel format
 │   │                  - read/write rectangular region as linear buffer for
 │   │                    any babl supported pixel format.
 │   ├──graph          graph storage and manipulation code.
 │   ├──module         The code to load plug-ins located in a colon seperated
 │   │                 list of paths from the environment variable GEGL_PATH
 │   ├──operation      The GeglOperation base class, and subclasses that act
 │   │                 as baseclasses for implementeting different types of
 │   │                 operation plug-ins.
 │   ├──process        The code controlling data processing.
 │   └──property-types specialized classes/paramspecs for GeglOperation
 │                     properties.
 │
 ├──operations        Runtime loaded plug-ins for image processing operations.
 │   │
 │   ├──core          Basic operations tightly coupled with GEGL.
 │   │
 │   ├──affine        transforming operations (rotate/scale/translate)
 │   ├──blur          Blurring operations.
 │   ├──color         Color adjustments.
 │   ├──generated     Operations generated from scripts (currently
 │   │                ruby scripts.) (arithmetic, compositors, ...)
 │   ├──io            sources and sinks (file loaders/savers etc.)
 │   ├──meta          Operations that themselves are made by gegl graphs.
 │   ├──render        Operations providing patters, graidents, fills, ...
 │   ├──svg           Non-compositors part of the SVG 1.2 specification.
 │   ├──transparency  opacity/mask control
 │   └──workshop      Works in progress, (not built/installed by default)
 │       └──generated generated operations that are in the workshop.
 │
 │
 ├──docs              A website for GEGL
 │   │
 │   └──gallery       A gallery of sample GEGL compositions, using the
 │       │            (not yet stabilized) XML format.
 │       │
 │       └──data      Image data used by the sample compositions.
 │
 ├──bin               gegl binary, for processing XML compositions to png files.
 │
 ├──bindings          bindings for using GEGL from other programming languages
 │                    not included in the tarball distribution but exist in
 │                    the subversion repository.
 │
 └──tools             some small utilities to help the build.

Directories in the babl distribution

babl-dist-root
 │
 ├──babl       the babl core
 │   └──base   reference implementations for RGB and Grayscale Color Models,
 │             8bit 16bit, and 32bit and 64bit floating point.
 ├──extensions CIE-Lab color model as well as a naive-CMYK color model.
 │             also contains a random cribbage of old conversion optimized
 │             code from gggl. Finding more exsisting conversions in third
 │             part libraries (hermes, lcms?, liboil?) could improve the
 │             speed of babl.
 ├──tests      tests used to keep babl sane during development.
 └──docs       Documentation/webpage for babl.

Extending

To create your own operations you should start by looking for one that
does approximatly what you already need. Copy it to a new .c source
file, and replace the occurences of the filename (operation name in the
source.)

Most of the operations do not use the verbose gobject syntax, but
preprocessor tricks turning the boilerplate in a short chant.

