Helper Tools for Developers

Table of Contents

GEGL operations development is clearly more involved than plug-in development. Furthermore bugs are not as forgiving, especially as a crash in your code will also crash GIMP, unlike for plug-ins.

Here are a few tricks to help with development.

Compile with Debug Data

If your operation is build with debugging data, this will give you line number and variables information in the stack trace generated by GIMP during a crash. This can be a very valuable debugging tool.

The option for compiling with debugging is -g in gcc.

Add a Build System

Rather than always compiling manually, you may be interested to write a build script so that you can easily recompile your operation, without having to remember compiler options and typing long command lines.

These days, we mostly suggest to use the meson build system.

For instance, this very basic meson.build file installed in the same directoy as the 2 C sources we just created will compile both operations appropriately:

project('gimp-tutorial-point-filter-op', 'c', version : '0.1')

gegl = dependency('gegl-0.4', required : true)

op1 = shared_library('gimp-tutorial-meta-op',
                     'gimp-tutorial-meta-op.c',
                     dependencies : [gegl],
                     name_prefix : '')

op2 = shared_library('gimp-tutorial-point-filter-op',
                     'gimp-tutorial-point-filter-op.c',
                     dependencies : [gegl],
                     name_prefix : '')

Now how you have to do is for instance to create a _build/ directory and compile inside:

mkdir _build
cd _build
meson setup ..
ninja

Once compiled, you will find the 2 following files in your _build/ directory:

  • gimp-tutorial-meta-op.so
  • gimp-tutorial-point-filter-op.so

Note: meson will build the proper format depending on your target platform. For instance, on Windows, it will be .dll files and on macOS .dylib files instead of .so files obviously.

What you can do during development is (if you are on a Unix-like OS) to make symbolic links to your compiled operations:

ln -s `pwd`/gimp-tutorial-meta-op.so ~/.local/share/gegl-0.4/plug-ins/
ln -s `pwd`/gimp-tutorial-point-filter-op.so ~/.local/share/gegl-0.4/plug-ins/

You may be interested in the output of meson configure since meson will propose you a lot of features by default. For instance the -Dbuildtype option will allow you to compile with debug data during development, which should be the default.

Other features enables you to optimize, set up the warning level or use code sanitizers, among many others.

To know more, we suggest to read meson documentation.

GEGL Graph

GIMP contains a very powerful tool called the “GEGL Graph”. As the name indicates, it allows to construct GEGL graphs directly from within the graphical interface.

You may find this tool in the menu Filters > Generic > GEGL Graph… or by searching it in the Action Search.

Once opened, you may test any existing filters on your opened image, with the following syntax:

op-name property1=value1 property2=value2

For a more concrete example, let’s say I want to run a Gaussian Blur with Size X and Y at 5.0. I would write this line in the GEGL Graph:

gegl:gaussian-blur std-dev-x=5.0 std-dev-y=5.0

Of course, you may set several filters one after the other. Just write one filter per line. For instance, add a Cartoon effect after your blur, with Mask radius at 3.0:

gegl:gaussian-blur std-dev-x=5.0 std-dev-y=5.0
gegl:cartoon mask-radius=3.0

You may even make more complicated graphs with auxiliary buffers. The default GEGL Graph text field actually contains a bunch of commented examples for you to take inspiration from.

This is a great helper tool, especially when you construct Meta Operations, which you can first test directly on canvas without writing a single line of code.

⚠️ Warning: the GEGL graph is a developer tool and similarly to the fact that wrongly used GEGL operations may crash GIMP, it is possible to crash GIMP with some combinations of filters, especially if you use experimental ones (which are not accessible from the graphical interface).

GEGL command line

Getting info on existing operations

GEGL comes with a command line utility simply called gegl. The simplest thing you may do with it is simply getting a list of all the operations seen by GEGL. This is actually a good way to verify that your operation is loaded correctly by GEGL, much more faster than running GIMP every time:

gegl --list-all

Once you had found an operation you want to get information about, you may get more info with the --info option:

$ gegl --info gegl:text
reference-hash       aeef4d46ce63f8d2a0bd6692acd608f2
name                 gegl:text
title                Render Text
categories           render
operation-class
reference-composition <?xml version='1.0' encoding='UTF-8'?><gegl><node operation='gegl:crop'
                     width='200' height='200'/><node operation='gegl:text'> <params> <param
                     name='size'>20</param> <param name='wrap'>200</param> <param
                     name='color'>green</param> <param name='string'>loves or pursues or desires to
                     obtain pain of itself, because it is pain, but occasionally circumstances occur
                     in which toil and pain can procure him some great pleasure. To take a trivial
                     example, which of us ever undertakes laborious physical exercise, except to
                     obtain some advantage from it? But who has any right to find fault with a man who
                     chooses to enjoy a pleasure that has no annoying consequences, or one who avoids
                     a pain that produces no</param> </params></node></gegl>
description          Display a string of text using pango and cairo.

Properties:
string               [gchararray] String to display (utf8) (default: "Hello")
font                 [gchararray] Font family (utf8) (default: "Sans")
size                 [gdouble] Font size in pixels. (default: 10.000000)
color                [GeglColor] Color for the text (defaults to 'black')
wrap                 [gint] Sets the width in pixels at which long lines will wrap. Use -1 for no
                     wrapping. (default: -1)
vertical-wrap        [gint] Sets the height in pixels according to which the text is vertically
                     justified. Use -1 for no vertical justification. (default: -1)
alignment            [gint] Alignment for multi-line text (0=Left, 1=Center, 2=Right) (default: 0)
vertical-alignment   [gint] Vertical text alignment (0=Top, 1=Middle, 2=Bottom) (default: 0)
width                [gint] Rendered width in pixels. (read only) (default: 0)
height               [gint] Rendered height in pixels. (read only) (default: 0)

You can see all the properties, with their name, their type, default values and more. This is a very powerful tool while developing.

Testing Operations on Command Line

Finally some very quick way to test your filters is to call them through the command line. The gegl tool can read a graph written in XML though for simpler graphs as one-time tests, you may prefer the gegl-chain format which is the same syntax as in the GEGL Graph.

As a good example, say I want to test our meta operation with a custom text and font size. I may just call:

gegl input.png -o output.png -- zemarmot:hello-world-meta text="Hello Universe" font-size=100.0 compute-size=0

Conclusion

We now have explored the bases of GEGL Operation creation. Obviously there is much more to it, but our tutorial won’t go into such depth yet.

We hope it was enough to make you want experiment with making your own filters!