Difference between revisions of "Hacking:Plugins"

From GIMP Developer Wiki
Jump to: navigation, search
(Integrate information from developer.gimp.org; improve text)
(integrate How to write a GIMP plug-in from developer.gimp.org)
Line 66: Line 66:
== References for Programming GIMP Plug-ins ==
== References for Programming GIMP Plug-ins ==
[http://developer.gimp.org/plug-ins.html A tutorial on programming GIMP plug-ins in the C language.]
[[Hacking:How to write a GIMP plug-in | A tutorial on programming GIMP plug-ins in the C language]].
[http://www.gimp.org/docs/scheme_plugin/ A tutorial on programming GIMP plug-ins in the Scheme language.]
[http://www.gimp.org/docs/scheme_plugin/ A tutorial on programming GIMP plug-ins in the Scheme language.]

Revision as of 19:43, 26 January 2014

GIMP supports plug-ins.

Some plug-ins are distributed with GIMP and some are distributed by third parties.

Getting Started

A good way to get started is to read plug-ins distributed with GIMP.

You can test snippets of Scheme and Python plug-ins on the consoles available in GIMP at the menu items: Filters>Script-Fu>Console and Filters>Python-Fu>Console. A console is a terminal window that lets you enter and execute statements in the programming language.

The documentation for the PDB is available in GIMP at the menu item: Help>Procedure Browser.

Plug-ins and the GIMP Procedural DataBase (PDB)

Plug-ins must register themselves in the PDB. Other GIMP functions, called internal procedures, are also in the PDB. An internal procedure often provides a function also found in the GIMP menus.

Registration means declaring the name and parameters of a plug-in, as well as declaring where a plug-in will appear in the GIMP menus, if at all.

A plug-in commonly calls other plug-ins in the PDB.

(Note that the procedures in the PDB are often similar to procedures in the GIMP library, but have different signatures. Do not confuse the two.)

Programming Languages for GIMP Plug-ins

GIMP plug-ins are written in the C, Scheme, Python, or Perl programming languages.

C language GIMP plug-ins are compiled and linked with Gimp libraries. They can access functions in those libraries or functions in the PDB. They are distributed as executable files with suffix ".exe".

Scheme language GIMP plug-ins are interpreted. They can access procedures in the GIMP Procedural Database (PDB) as well as the functions built into the Scheme language. They are distributed as text files called scripts with suffix ".scm".

Python language GIMP plug-ins are interpreted. They can access procedures in the GIMP Procedural Database (PDB) as well as functions provided by the PyGimp set of Python modules (chiefly, the module named "gimpfu") and functions provided by the Python modules in a standard Python distribution. They are distributed as text files with suffix ".py".

Choosing a Language for a GIMP Plug-in

Plug-ins are usually usually written in the C language if they implement fundamental algorithms at the pixel level. Such plug-ins might need the speed of a compiled language and full access to the GIMP libraries. However, such plug-ins need to be separately compiled for each platform.

Plug-ins written in Scheme or Python usually implement less compute intensive algorithms. Often they implement recipes: step-by-step sequences of actions a user could do manually using the GIMP. They are limited to GIMP functions found in the PDB (they can't directly access the Gimp C libraries. For Python plug-ins the gimpfu module wraps many GIMP C library functions.) They are very portable (assuming the separate Python interpreter is installed for Python plug-ins.)

Plug-ins in C can provide any user interface using, for example, the GTK toolkit. Plug-ins written in Scheme or Python can easily provide a dialog for plug-in settings using a standard set of widgets provided (by the Scheme interpreter and the PyGimp modules) for the parameters of the plug-in. Plug-ins written in Python can provide fuller user interfaces by using, for example the PyGTK toolkit, which is in a standard Python distribution.

C is an older language, the traditional programming language for systems level programming with full access to the underlying hardware and operating system. It is powerful but unforgiving.

Scheme is a Lisp-like language with a very simple syntax. Some people find it hard to learn and difficult to read. The set of functions distributed with the Scheme interpreter built into Gimp is what the language provides, so you might need to include third party Scheme functions inside your plug-in.

Python is a more recent, interpreted language. It is open source from Python.org and supported on most platforms. It supports programming concepts such as object orientation and exceptions. Since it is interpreted, it supports agile programming or rapid prototyping. Most Python programs are written idiomatically, using common phrases. Some people find Python abstractions and idioms difficult to learn. The set of modules in a standard Python distribution provides a rich set of components.

Debugging GIMP Plug-ins

Generally, debugging Scheme and Python plug-ins is easier. Python provides a trace when a plug-in throws an exception. Python also has a convenient logging module.

You can use the technique of embedding print statements or logging statements in your plug-in. Start GIMP from a console (a terminal window) to see the output of your debugging statements to stdout or stderr (the standard output streams for a program.)

You can also debug plug-ins using a run-time debugger, such as the GNU debugger, gdb, or a memory debugger, such as valgrind or purify. Since a plug-in is started from within GIMP and runs as a separate process from GIMP, you generally "attach" a running plug-in to a debugger. Or, for example, instead of you starting the debugger, GIMP starts the debugger when you start a plug-in from within GIMP. See [1] for more information. Generally a debugger is more useful for C-language programs. Using a debugger you might find yourself reading GIMP code instead of your plug-in code.

Community of GIMP Plug-in Authors

Many authors of GIMP Scheme and Python plug-ins lurk at:

Gimp Plugin Registry


Generally, there are fewer authors of C-language GIMP plug-ins. The community of GIMP developers are mostly C programmers but they don't often write plug-ins. Questions to GIMP developers concerning C-language plug-ins are discouraged for all but difficult questions. Bugs in third-party plug-ins (those not distributed with GIMP) should NOT be reported as GIMP bugs, only reported to the author or maintainers of the third-party plug-ins.

References for Programming GIMP Plug-ins

A tutorial on programming GIMP plug-ins in the C language.

A tutorial on programming GIMP plug-ins in the Scheme language.

GIMP Python Documentation.

A tutorial on programming GIMP plug-ins in Python.

The GIMP 2.0 API Reference This documents the GIMP C library, not the GIMP Procedural Database! The PDB is best examined from within GIMP using Help>Procedure Browser

A few questions about plug-in development are answered in GIMP Developer Frequently Asked Questions.

Templates for GIMP Plug-ins

A template is a canonical, minimal shell of, or a fill-in-the-blanks version, or an empty prototype for, a plug-in.

A template for a C-language plug-in can be downloaded from GIMP's FTP server. A more current version is in the GIMP plug-in template project's repository. The template includes all necessary features of a well-behaved plug-in and includes build files for compiling the template. You don't have to care for autoconf, automake, internationalisation etc.

There is also a template for a Scheme language plug-in.

A template for a Python language plug-in is near the start of the GIMP Python Documentation.

A template demonstrating how GIMP Python displays GUI widgets (for each parameter type) in the settings dialog of a Python plug-in is in the plug-in registry.

GIMP Plug-in Architecture

Plug-ins are invoked by GIMP (whether interactive GIMP or batch-mode GIMP.) Plug-ins run as separate, independent processes from GIMP. That is, they have a separate execution environment. When a plug-in crashes, it does not usually affect the separate GIMP process. The GIMP and plug-in processes communicate using shared memory inter-process communication, but that does not concern most plug-in developers. The inter-process communication is hidden and established automatically by the canonical framework for a plug-in.

A GIMP user can continue to use GIMP while a plug-in executes. However, usually a user waits and a plug-in returns quickly.

A plug-in can open dialog windows with the user. The plug-in framework provides an initial "settings" dialog, for the parameters of a plug-in, before a plug-in begins its substantive work. A C-language plug-in should return a result code to GIMP and let GIMP display an error dialog if any. A Scheme or Python language plug-in should call the PDB procedure gimp_message() to display an error dialog. Or a Python plug-in can raise an exception, which results in the GIMP process displaying an error dialog.

A plug-in that operates on an existing drawable (image, layer, or channel) should finally flush the display to show results to a user.

A plug-in can also open separate displays (windows, for example on images.) A plug-in creates a display, then flushes it to show or refresh it to a user.

A plug-in is invoked with a "run mode":

  • interactive: shows a settings dialog for the user to modify parameters and can show GUI dialogs and windows to the user
  • non-interactive: runs with the passed parameters and should not interact with a user
  • run with last values: runs with previously used values for parameters (does not display a settings dialog) but can otherwise interact with the user

It is the responsibility of a well-behaved plug-in to adhere to these rules. For example, a plug-in that is invoked with run mode non-interactive should not attempt to open a display.

Installation of GIMP Plug-ins

Scheme and Python plug-ins are readable text files. C-language and Python plug-in files must have permissions set to allow execution.

When GIMP starts, it examines the standard installation directories for plug-ins, and registers the plug-ins it finds. The plug-ins registered in the PDB are not persistent: if you delete a plug-in file, it disappears from the PDB. If you install a plug-in file, it will not appear in the PDB until you restart GIMP (except for Scheme plug-ins, which can be refreshed while GIMP is running using the menu item Filters>Script-Fu>Refresh Scripts.) (Also, as long as you don't change the registration signature of a C-language or Python plug-in, you can modify the plug-in file and rerun it without restarting GIMP.)

Plug-ins distributed with GIMP are installed in standard subdirectories of the GIMP installation: all users on a multi-user computer can use them. A user can install third-party plug-ins in the same place, although it is not recommended. A user should install third-party plug-ins in a standard subdirectory of the user's home directory, so that on a multi-user computer, each user has their own plug-ins, and so that after a re-installation or update of GIMP, the user's third-party plug-ins in their home directory are not affected.

You can determine the path to the two standard installation directories (all users, and user local) for plug-ins on any platform by installing GIMP and examining the Folders/Plug-Ins item of the Edit>Preferences dialog.

Typically, third-party Scheme plug-ins are installed in ~/.gimp-2.x/scripts and C-language and Python language plug-ins are installed in ~/.gimp-2.x/plug-ins directories. Here, ~ means the user's home directory, the "." means the directory is a hidden file, and "x" is the minor version of GIMP, for example "7" for GIMP version 2.7.

Internationalization of GIMP Plug-ins

GIMP is used around the world. Well-behaved plug-ins should be internationalized (translated into other languages, I18N.) The plug-in templates demonstrate internationalization.

The GIMP project maintains the translation files for the plug-ins distributed with GIMP.

For now, there does not seem to be any organization maintaining translation files for most third-party plug-ins.