This document is both a tutorial and the reference for the C API of GEGL. The concepts covered in the tutotrial should be applicable using other languages as well.

The core API of GEGL isn't frozen yet and feedback regarding it's use as well as the clarity of this documentation is most welcome.

Algorithms created with GEGL are expressed as graphs of nodes. The nodes have associated image processing operations. A node has output and input pads which can be connected. By connecting these nodes in chains a set of image operation filters and combinators can be applied to the image data.

To make GEGL process data you request a rectangular region of an node's output pad to be rendered into a provided linear buffer, of any (supported by babl) pixel format. GEGL is using information about the rectangular bounding-boxes for regions that are needed to compute the requested result. For many forms of processing it should thus be efficient to ask for only a subregion to be recomputed. This fits well with being able to back an api that requests rectangular regions to be repainted.

Before GEGL can be used the engine should be initialized by either calling gegl_init or through the use of gegl_get_option_group. To shut down the GEGL engine call gegl_exit.

#include <gegl.h>

int main(int argc, char **argv)
{
  gegl_init (&argc, &argv);
      # other GEGL code
  gegl_exit ();
}

The Node is the image processing primitive connected to create compositions in GEGL. The toplevel GeglNode which contains a graph of GeglNodes is created with gegl_node_new. Using this toplevel node we can create children of this node which are individual processing elements using gegl_node_new_child

A node either has an associated operation or is a parent for other nodes, that are connected to their parent through proxies created with gegl_node_get_input_proxy and gegl_node_get_output_proxy.

The properties available on a node depends on which operation is specified.

GeglNode *gegl, *load, *bcontrast;

gegl = gegl_node_new ();
load = gegl_node_new_child (gegl,
                            "operation", "load",
                            "path",      "input.png",
                            NULL);
bcontrast = gegl_node_new_child (gegl,
                                 "operation", "brightness-contrast",
                                 "brightness", 0.2,
                                 "contrast",   1.5,
                                 NULL);

Nodes in GEGL are connected to each other. The resulting graph of nodes represents the image processing pipeline to be processed.

gegl_node_link_many (background, over, png_save, NULL);
gegl_node_connect_to (translate, "output", over, "aux");
gegl_node_link_many (text, blur, translate);

Properties can be set either when creating the node with gegl_node_new_child as well as later when changing the initial value with gegl_node_set.

To see what operations are available for a given operation look in the Operations reference or use gegl_node_get_properties.

There are two different ways to do processing with GEGL, either you query any node providing output for a rectangular region to be rendered using gegl_node_blit, or you use gegl_node_process on a sink node (A display node, an image file writer or similar). To do iterative processing you need to use a GeglProcessor see gegl_processor_work for a code sample.

This section lists functions that retrieve information, mostly needed for interacting with a graph in a GUI, not creating one from scratch.

You can figure out what the bounding box of a node is with gegl_node_get_bounding_box, retrieve the values of named properties using gegl_node_get.

The XML format used by GEGL is not stable and should not be relied on for anything but testing purposes yet.

GeglRectangles are used in gegl_node_get_bounding_box and gegl_node_blit for specifying rectangles.

struct GeglRectangle
 {
   gint x;
   gint y;
   gint width;
   gint height;
 };

GeglColor is used for properties that use a gegl color, use gegl_color_new with a NULL string to create a new blank one, gegl_colors are destroyed with g_object_unref when they no longer are needed.

The colors used by gegls are described in a format similar to CSS. The textstring "rgb(1.0,1.0,1.0)" signifies opaque white and "rgba(1.0,0.0,0.0,0.75)" is a 75% opaque red. Hexadecimal forms like RRGGBB and RRGGBBAA are also supported.

The following functions are mostly included to make it easier to create language bindings. The varargs versions most often lead to more readable C code.