GIMP Developer - About Plug-ins and Filters (original) (raw)

Table of Contents

About

This is a general discussion of aspects of plugins.

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 helps you choose a kind of plugin or filter to develop.

This table is a brief summary and gives simplified answers. Read the rest of the document for explanations, details, exceptions, and other considerations.

Aspect GEGL filter GIMP C plugin Plugin that introspects ScriptFu plugin
Usual use/role Visual effects Any, export/import Any Scripting
Language C/C++ C Python, any language having GI module ScriptFu/Scheme
Platform portable packaging No, binary No, binary Yes, text Yes, text
Portable to GIMP 2 Yes Maybe No No
Uses GObject Introspection No No Yes No
Binds to GEGL GIMP, GEGL Any PDB
Previews Yes No No No
Non-destructive (NDE) Yes Can add to layers Can add to layers Can add to layers
Generated GUI/dialog Yes Yes Yes Yes
Persistent settings Yes Yes Yes Yes
Custom GUI/dialog No Yes Yes No
Internationalization Yes Yes Yes Yes
Color space/model API Yes Yes Yes No

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. GEGL filters are also known more generally as “GEGL operations” or “layer effects”. Not all GEGL operations are filters that produce visual 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:

You might classify like this:

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

Uses or roles of plugins and filters

Most load/save plugins are written in C. But the plugin for the OpenRaster format is in Python.

Most scripting plugins are in an interpreted language such as Python or Scheme, but see “Sequencing.”

Processes

GEGL filters run in the GIMP app process.

Plugins run in a process separate from the GIMP app.

Old-style ScriptFu plugins are served by the extension-script-fu process. That process is a separate plugin and process but it serves all the old-style plugins (installed to the /scripts directory.) Old-style ScriptFu plugins run in the extension-script-fu process.

The Programmers Database (PDB)

Use the PDB Browser to browse the PDB.

GEGL filters are not in the PDB. Plugins are in the PDB.

Kinds of procedures in the PDB

The PDB contains procedures of kind/type:

  1. Internal
  2. Plugin
  3. Temporary
  4. Persistent (Extension)

Internal procedures

Internal procedures have equivalents in libgimp. But not every function in libgimp is in the PDB.

Internal procedures are not defined in a plugin file. They are defined in .pdb files in the GIMP source.

Plugin procedures

Plugin procedures are in the PDB. A plugin “registers it’s procedures” in the PDB.

Plugin procedures are defined in plugin files.

Temporary procedures

A plugin can also register Temporary procedures in the PDB. But they are owned by the plugin that registers them. Temporary procedures can also be defined in a separate plugin file, and loosely said to be plugins themselves. Most temporary procedures are the “old-style” plugins served by extension-script-fu. An example is script-fu-weave.

A temporary procedure can come and go from the PDB, but most are in the PDB as long as the GIMP app is running. Some are removed from the PDB when their owning plugin is removed.

Persistent procedures

A plugin can also register Persistent procedures in the PDB. The old name for a persistent procedure is “Extension.” Persistent procedures/plugins usually run in a process that persists for the life of a GIMP session.

Persistent procedures are rare. One notable example is extension-script-fu, which serves “old-style” Scheme plugins.

Persistent procedures use the extension protocol to the GIMP process, whereas plugin procedures use the plugin protocol.

Plugins/procedures can call other plugins/procedures, but only the GIMP app itself calls persistent plugins.

ScriptFu plugins bind to the PDB

Since ScriptFu binds to the PDB, a ScriptFu plugin is more limited than plugins that bind to libgimp. For example, the PDB API does not have all the methods for color space and color model that libgimp has.

ScriptFu as a language has:

Both filters and plugins declare:

Plugins, but not GEGL filters also declare:

GEGL filters

This section discusses aspects of GEGL filters, noting differences from plugins.

Using GEGL filters

A user applies a GEGL filter to a single layer. The layer is the active layer. A user cannot apply a GEGL filter when the user has selected more than one layer.

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

In the GIMP app, a user can choose to apply a filter non-destructively. The GIMP app effectively adds a boolean property_is-applied-destructively_ to an application of a GEGL filter.

When a user applies a filter non-destructively, the user can subsequently tweak the filter, revisiting its dialog.

A user can stack many layer effects on a layer. The most recently applied filter is to the top of the stack. A user can stack the same GEGL filter on the same layer many times.

GEGL filters have tool behavior

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. When the user subsequently clicks in an image, the filter dialog appears again to add another filter instance to the image.

Browsing and acquiring GEGL filters

Most GEGL filters are part of a GEGL distribution. They are loaded by the GEGL library and thus by GIMP.

You can browse the set of such filters on the GEGL web site.

A few GEGL filters are not in a GEGL distribution, but distributed with GIMP. Their name starts with “gimp:”

Third parties can also distribute GEGL filters, to be installed in GIMP.

Many GEGL filters distributed with GEGL appear in the menus of GIMP. A user can’t tell beforehand, but when a user chooses a menu item, they might see a distinctive dialog, having the GEGL icon.

Some GEGL filters that don’t appear as separate GIMP menu items are listed in a pulldown menu of the GEGL Operation dialog when a user chooses the Tools>GEGL Operation menu item.

Some filters distributed with GEGL are blacklisted by the GIMP app. That is, GIMP prevents a user from directly using such GEGL filters. A plugin can call blacklisted filters.

The blacklisted filters are blacklisted for security reasons, and for other reasons, for example duplication.

A GEGL Filter Browser, a plugin within GIMP, is work in progress.

Sequencing

Many plugins and filters are just sequences of primitive filters or plugins. A plugin may abstract away the steps, and choices of parameters to the primitives. You can think of them as recipes.

You might find a tutorial describing a sequence of steps. A plugin can automate the sequence of steps.

Sometimes “scripting” means writing such a plugin that performs a simple sequence. Not all “scripts” do just simple sequencing.

Most such sequencing plugins are written in an interpreted language.

Many GEGL filters are primitive operations. But GEGL supports sequences, or more generally a graph, of operations (called a meta operation.)

Loading

Every GIMP plugin can only be used with the GIMP app.

A GEGL filter can be used with other applications that use the GEGL library.

GEGL filters and plugins are installed with GIMP and can appear as menu items in the GIMP app.

Non-Destructive

GEGL filters are non-destructive. Most plugins are destructive, or it does not pertain.

Non-destructive filters are sometimes called “effects” or “fx” for short.

A user can undo a destructive plugin, but then they need to start over, that is, apply the plugin again.

Run Mode, Interactive versus Non-Interactive

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. Also know as “interactive versus non-interactive.”

When a user is processing images in batches, they want filters to run in non-interactive mode. You can run the GIMP app from the command line, invoking plugins and filters, to process images non-interactively.

Some filters and plugins never ask a user to control. The plugin still gets the run mode argument.

A well-behaved plugin should respect the given run mode argument. See “Well-behaved plugins.”

GUI

All kinds of filters and plugins can have GUI.

Plugins and filters can declare their appearance in the GIMP menus.

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.

A user need not be aware a menu item is implemented by a plugin.

Dialogs

Plugins declare their arguments.

GIMP’s filter/plugin system can generate and show a dialog for a user to enter arguments.

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.

Sensitivity/Enabling

Mechanisms in GIMP enable/disable a plugin’s menu item (if any) based on the what image and layers a user has selected.

A user can only click on menu items that are sensitive aka enabled.

The menu items of many filters and plugins might be disabled when:

Image mode

A plugin declares the image modes it can process.

A pluign also declares whether it can process images with transparency (alpha.)

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

Capability re multi-selected layers

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

Settings

Most filters and plugins have parameters. The set of parameters that a user actually chooses are kept for the next session, as “settings” sometimes called “preferences.”

The settings are kept for the next session of the plugin, and for the next session of the GIMP app.

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

Internationalization or i18n

Plugins and filters can appear in the native language of the user.

GIMP uses the “gettext” system for i18n.

Support is built into the GIMP library. Support is also build into the ScriptFu system.

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

First-party GEGL filters and plugins find their translation data in a standard place.

Third-party plugins can declare a custom i18n domain and catalog. Third-partyGEGL filters cannot.

Custom GUI

Plugins can implement their own GUI, using for example Gtk.

Most plugins do not implement their own GUI.

When plugins do implement their own GUI:

Programming Languages

GEGL filters are usually written in C for performance.

When your favorite language has a module for GObject Introspection, you can use the language to program a plugin for GIMP. A problem is that often such modules, e.g. for the Lua and Javascript languages, are not portable across platforms.

Support for Lua and Javascript is experimental

Long ago, you could write plugins in the Perl language.

Binding

This describes how a programming language binds or links filters and plugins to GIMP and GEGL libraries. A binding lets a high-level language call a C library. A linker links (and binds) C programs together into an executable. Interpreted languages do not use a linker, but bind to a library at run-time.

Plugins and filters:

Filters/Plugins and colorspace or color Model

Many filters and plugins are agnostic of colorspace and model. They don’t care, and work regardless. They may perform suitable conversions.

Other filters and plugins may want to inquire of and change colors, color space, and color model.

Non-Scheme plugins and filters and colors

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.

ScriptFu Scheme plugins and colors

Most ScriptFu Scheme plugins are agnostic of colorspace and color model.

Since ScriptFu Scheme plugins bind to the PDB, and the PDB has limited procedures for dealing with colorspace and color model, such plugins can’t effectively deal with colorspace and color model.

Colors in ScriptFu are represented simply, as 8-bit triplets or quads in the sRGB colorspace. Thus such plugins cannot effectively represent and set colors with high precision, or in different BABL formats. They may lose precision.

Distribution of filters and plugins

This is about packaging and distributing filters and plugins.

Parties who distribute plugins

Some third-party plugins are kept in public repositories. For example, the G’Mic plugin. Such third-parties may also distribute packaged plugins.

Packaging

The usual form is:

Most users are not prepared to build (compile) plugins from source written in low-level languages. Building is too complicated.

Some users are able to install plugins written in interpreted languages, The source is text files that need only installation and not building.

Acquisition and installation

A typical problem for users is to also install any packages a plugin depends on. For example, a plugin written in Python may require a particular version of the Python interpreter, or a particular Python module.

Another problem for users is that they expect to install with one click, without needing adminstrative permissions and skills.

Modern apps let users install extensions from within the app, across the net. For example, there might be an “Extensions” button in the app. The GIMP app does not yet support that.

Some third-party GIMP plugins are packaged as flatpaks. Users can use the flatpak app to install such plugins from the trusted FlatHub site.

The best way to insure your plugin is widely distributed is first, to make it useful to a large audience, and then to make it of such high quality that you can persuade the GIMP project to adopt and maintain it.

Security during installation

Some platforms are more locked down than others.

Some platforms require software in binary form to be signed before installation. Alternatively, the platform may allow exceptions to that rule. Many users may not know how to allow an exception (how to give permission.)

The GIMP project signs the packages it distributes as required. Third parties may want to sign their packages for widespread distribution.

Signing on an Apple platform requires a developer to have an Apple Developer Account.

Well-behaved plugins

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

The mechanisms behind plugins in GIMP do not necessarily enforce these contracts. It is the responsibility of the plugin developer.

Respect multi-selected layers

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

Respect image mode

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

Respect run-mode

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

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.

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.

History

In GIMP version 2, plugins written in Python used the PyGimp module. That was a custom binding from Python to libgimp. It used Python 2, which is no longer supported.

In GIMP version 2, many filters that are now GEGL filters were just plugins in C. During the development of GIMP version 3, they were moved to the GEGL project.

Formerly, there were web sites that let you download filters and plugins. For example GIMP RegistryNow that is rare, because of increased security concerns and lack of resources i.e. time and money.

In GIMP version 2, much of the behavior of plugins was scattered in many implementations. Since GIMP version 3, the behaviors are implemented in fewer places, for example the Plugin class of the GIMP library. Example of behaviors that were scattered are the look-and-feel of dialogs, and the implementation of settings. Formerly they were implemented separately in PyGimp and ScriptFu, and in many individual plugins.