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.

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);
save = 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.

gegl_node_set (node, "brightness", -0.2,
                     "contrast",   2.0,
                     NULL);

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

GeglNode      *gegl;
GeglRectangle  roi;
GeglNode      *png_save;
unsigned char *buffer;

gegl = gegl_parse_xml (xml_data);
roi      = gegl_node_get_bounding_box (gegl);
png_save = gegl_node_new_child (gegl,
                                "operation", "png-save",
                                "path",      "output.png",
                                NULL);

gegl_node_link (gegl, png_save);
gegl_node_process (png_save);

buffer = malloc (roi.w*roi.h*4);
gegl_node_blit (gegl,
                &roi,
                1.0,
                babl_format("R'G'B'A u8",
                roi.w*4,
                buffer,
                GEGL_BLIT_DEFAULT);

# iterative processing:

GeglProcessor *processor = gegl_node_new_processor (node, &roi);
double         progress;

while (gegl_processor_work (processor, &progress))
  g_warning ("%f%% complete", progress);
gegl_processor_destroy (processor);

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.

double level;
char  *path;

gegl_node_get (png_save, "path", &path, NULL);
gegl_node_get (threshold, "level", &level, NULL);

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 w;
   gint h;
 };

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.