About Plug-ins and Filters

Read this if you are new to GIMP and want to develop a filter or plugin.

This is an overview, short on details. It explains terminology.

Quickstart

This table is a summary that helps you choose a kind of plugin or filter to develop.

Read the rest of the document for explanations, exceptions, and other considerations.

Disambiguation

Filter versus plugin

In the context of image processing, the words “filter” and “plugin” are often used as synonyms.

The word “filter” has a generic meaning: alter an image, producing a visual effect. Plugins can be filters in that sense, but not all plugins are filters.

GEGL filters are plugins in the sense that they can be plugged into a GEGL installation. In many GIMP documents, the word “plugin” does not encompass GEGL filters. Most GEGL filters are also known more generally as “GEGL operations” or “layer effects”.

Plugin versus extension

In the context of software applications, the words “plugin” and “extension” are often used as synonyms. They are software, installed separately, that extend an application. For example, most browser applications let user’s install extensions.

GIMP terminology

In the context of GIMP documents:

• Filter: a GEGL filter extension, aka operation, usually non-destructive
• Plugin: other extensions, that are programs
• Resource: extensions that are data, such as brushes

You might classify like this:

Extension
  Resource / Data:  Brush, Font, Gradient, Palette, Pattern
  Programs:
    GEGL Filter
    Plugin

Uses or roles of plugins and filters

Many GEGL filters are primitive operations like image processing algorithms i.e. visual effects. But GEGL supports sequences, or more generally a graph, of operations (called a meta operation.)

Many plugins are just sequences of primitive filters or plugins like load/save i.e. exporting or importing image files in various formats. A plugin may abstract away the steps, and choices of parameters to the primitives. You can think of them as recipes.

Sometimes “scripting” means writing such a plugin that performs a simple sequence i.e. programming or automating workflow. Most such sequencing plugins are written in an interpreted language. But not all “scripts” do just simple sequencing (e.g. the introspected ones).

Programming Languages

GEGL filters, since they are technically shared libraries, are usually in C or a similar low-level programming language.

Plugins can be in C, or in a high-level language, often interpreted, like Python or Scheme.

Binding

On C programs, a linker links (and binds) them together into a binary. So:

• GEGL filter: links only to the GEGL library, libgegl. The filter and the library are both C libraries. No binding required.
• C plugin: links to the GIMP library, libgimp. No binding required.

Interpreted languages do not use a linker, but bind to a library at run-time. So, a “binding” lets a high-level language call a C library:

• Python plugin: loads the pygobject module and run-time binds to GIMP or GEGL or Gtk/GLib/Gio or other libraries using GObject Introspection.
• ScriptFu/Scheme plugin: uses a custom, run-time binding to the GIMP PDB (not to libgimp). ScriptFu as a language has:
  • functions that bind to internal PDB procedures (prefix “gimp-”)
  • functions that bind to plugin PDB procedures (prefix “plug-in-” or “script-fu-”)
  • special functions for registering plugins (prefix “script-fu-”)
  • since GIMP 3, special functions for GEGL filters (prefix “gimp-drawable-filter-” and others) These are not in the PDB, see ScriptFu documents.

Distribution of filters and plugins

We call “third-party” the filters or plug-ins developed not by GIMP project but by developers out there, like you. They are installed separately by users.

Some users are able to install third-party plugins written in interpreted languages. The source is text files that need only installation on GIMP config dir and not building.

Most users, however, are not prepared to build (compile) filters or plugins from source written in low-level languages. Building is too complicated. So, users may download a binary from a trusted source and install it themselves, or download an installer. See: Distributing plug-ins

Loading

We can distinguish two ways of loading:

• Filter: loaded by the GEGL library (so can be used by any app) and run in the GIMP app process.
• Plugin: loaded by the GIMP app (so can only be used by it) and run in a process separate from the GIMP app, which is the plug-in binary itself, or an interpreter (e.g. python, gimp-script-fu-interpreter).

The way the filter or plug-in is loaded and run have implications on eventual crashes and debugging them. See: Debugging plug-ins

Non-Destructive

Considering if a filter or plugin persists on an image, we can distinguish two kinds:

• non-destructive, sometimes called “effect” or “fx” for short: applied to an image but users can tweak parameters later.
• destructive: has all-or-nothing effect. A user can undo a destructive plugin, but then they need to start over, that is, apply the plugin again.

GEGL filters are non-destructive. They are inherently non-destructive; they don’t have a boolean property indicating their non-destructiveness.

After a user chooses a menu item for a GEGL filter, the filter dialog appears. When the user does not Cancel, the filter then becomes the active tool. (Some GEGL filters that don’t appear as separate GIMP menu items are listed in a pulldown menu after choosing GEGL Operation menu item).

When a user applies a filter non-destructively, the user can subsequently tweak the filter, revisiting its dialog. See: How to write a filter

Filters/Plugins and colorspace or color Model

Plugins and filters that are not ScriptFu plugins have the full capability in the GIMP (libgimp) and GEGL API’s, for dealing with colorspace and color model.

They also have the full capability of GEGL (and BABL) for dealing with BABL formats of colors.

GUI

All kinds of filters and plugins can have GUI, normally accessed by a menu.

Such menu items can appear almost anywhere in the GIMP menus. They can even appear in context menus, i.e. pulldown menus that appear when the user clicks the right mouse button on an item.

Instructions on how to create menus and/or GUI for plug-ins can be found on How to write a plug-in. Here, we will just list some core concepts and how they behave regarding filters or plug-ins.

Dialogs

Plugins declare their arguments.

GIMP’s filter/plugin system can generate and show a dialog for a user to enter arguments either by using GEGL or GimpProcedureDialog.

A plugin decides whether to show a GUI dialog based on the run-mode argument. A well-behaved plugin must respect the run-mode argument. See: Respect run-mode

Settings

Most filters and plugins have parameters. The set of parameters that a user actually chooses are kept for the next session (if proper GEGL/GIMP API is used), as “settings” sometimes called “preferences.”

The parameters usually have “factory” defaults. A user can reset the settings to their defaults.

Internationalization or i18n

Both plugins and filters can appear in the native language of the user thanks to “gettext” system.

A plugin that is internationalized requires additional build and installation steps. For instance:

• third-party plugins can declare a custom i18n domain and catalog.
• third-party GEGL filters cannot.

Custom GUI

Most plugins do not implement their own GUI. But plugins can implement their own GUI if needed, using for example Gtk.

The Programmers Database (PDB)

The PDB, as the name implies, is a database containing “procedures” for programmers. Plugins are in the PDB. On GIMP app, use Help > Procedure Browser to browse the PDB.

GEGL filters are not in the PDB. Use Help >GEGL Filter Browser to browse them.

Internal and plugin procedures

The PDB contains procedures of two main kind/type:

1. Internal: are defined in .pdb files in the GIMP source. Internal procedures have equivalents in libgimp so you can use libgimp functions instead.

   But not every function in libgimp is in the PDB. That is why we recommend not relying too much on the PDB. Prefer the functions of libgimp.

2. Plugin: are defined in plugin executables. A plugin “registers it’s procedures” in the PDB through the “plugin” protocol. This is likely the kind of procedure you are looking for, and it is taught in: Calling a plug-in from another (PDB)

Temporary and persistent procedures

A plugin can also register Temporary procedures in the PDB. A temporary procedure can come and go from the PDB since they are owned by the plugin that registers them. Most temporary procedures are the “old-style” plugins served by extension-script-fu. An example is script-fu-weave.

A plugin can also register Persistent procedures in the PDB. Persistent procedures/plugins run through the “extension” protocol in a process that usually persists for the life of a GIMP session. One notable example is extension-script-fu, which serves “old-style” Scheme plugins.

Well-behaved plugins

A well-behaved filter or plugin must fulfill a contract to:

• respect run-mode
• respect image mode
• respect active layers (the user’s selected layers)

The mechanisms behind plugins in GIMP do not necessarily enforce these contracts. It is the responsibility of the plugin developer so mechanisms in GIMP can enable/disable a plugin’s menu item (if any) based on the what image and layers a user has selected.

Respect run-mode

Every filter and plugin has a “run mode.” The run mode is an argument to the plugin or filter. It tells whether the user is present to control the plugin, i.e. whether the plugin should present a GUI dialog (so “interactive” run-mode) or not (aka “non-interactive”).

Respecting run-mode means that a plugin in non-interactive mode should not:

• show error dialogs
• show a dialog to enter arguments
• open displays i.e. windows in the GIMP app, for an image

In short, remember that a plugin can be called by other plugins. A plugin should not assume that it will always be called in interactive run-mode.

Respect image mode

A plugin declares the image modes it can process. A plugin also declares whether it can process images with transparency (alpha.)

When run in non-interactive mode, a plugin should return an error when called with images of modes that the plugin can’t handle.

A GEGL filter generally takes any image mode and performs conversions.

Respect multi-selected layers

A plugin declares whether it will act on set of layers a user has selected, or only on a single layer.

Some legacy plugins (written before the multi-select layers feature was added to GIMP 3.) don’t respect multi-selected layers.

Bonus: Need not respect the selection mask

Plugins need not respect the selection mask (the area the user has selected.) Some do and some don’t. The description of a plugin should say whether it requires, and acts on, a user’s selected area.

Many plugins act on the selected area, when the user has selected an area, otherwise act on an entire layer.