Hacking:ScriptFu

From GIMP Developer Wiki
Revision as of 17:08, 5 January 2021 by Bootchk (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

ScriptFu refers to GIMP support for plugins written in the Scheme language.

The GIMP Scheme interpreter implements TinyScheme, a dialect of the Scheme language, a dialect of the Lisp language. The GIMP TinyScheme interpreter specializes it for image processing, adding a few more symbols to the TinyScheme language.

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

This describes GIMP 2 and GIMP 3 plugins. ScriptFu is mostly unchanged from GIMP 2 to GIMP 3, except to accomodate changes to GIMP itself.


Audience

This is mainly for authors of third party plugins. This page is a basic introduction with references to further reading. This is somewhat about programming language theory: ScriptFu as a language.

There are many Scheme plugins in the GIMP repository, providing important capabilities of GIMP. If you write a particularly useful Scheme plugin, it could find its way into the GIMP repository.

If you are interested in enhancing the Scheme interpreter of GIMP, it is written in C and its source is in the GIMP repository under /gimp/plug-ins/script-fu.


Overview

GIMP plug-ins let you program image manipulation algorithms. Scheme language GIMP plug-ins are interpreted. They can call 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". They are registered in the PDB with a name like "script-fu-...". They may appear in the GIMP user interface, in pull-down or pop-up menus.


Tutorials

A tutorial

Another tutorial from a paper book.

An out-of-date tutorial

Installation and debugging is covered in the tutorials.


Scheme plugins and the GIMP Procedural DataBase (PDB)

Scheme plugins are in the PDB and call the PDB

Calling procedures in the PDB

Scheme language plugins can call PDB procedures, as well as functions of the Scheme language. (They do not call functions from the libgimp library.) Example Scheme constructs for calling a PDB procedure:

(script-fu-clothify image drawable 1 2 3 4 5) calls the PDB procedure script-fu-clothify, which is another plugin
(gimp-image-get-drawables image ) calls an internal procedure, more or less the get-drawables method of the Image class of the Gimp module

PDB procedures called from a Scheme plugin return a list.

Scheme plugins in the PDB

Scheme language plugins are also in the PDB. Plug-ins register themselves in the PDB. The functions built into the interpreter for registering a plugin are:

  • script-fu-register
  • script-fu-menu-register

Registration means declaring:

  • the name and parameters of a plug-in (the signature)
  • other metadata such as help and author
  • declaring how and where a plug-in will appear in the GIMP menus, if at all.

ScriptFu plugins can return a value, when the script's run function's last line is a simple reference to a symbol. Unlike GIMP plugins in other languages, you do not register the types of return values.

All plugins understand a runtime "run mode". In NONINTERACTIVE (batch) mode, they do not provide a user interface. Most plugins take a run mode parameter. When a plugin calls a plugin, it usually passes a run mode. PDB procedures that are kind "Internal" do not usually accept a run mode parameter.


The language for defining ScriptFu plugin parameters

This is covered by many tutorials.

The only official documentation seems to be in the comments of the test-sphere.scm plugin in the GIMP repository.

Parameters are declared using a set of constants declared by the interpreter, the SF_... constants (an enumeration.)

Each parameter is declared by a triple of arguments to the script-fu-register function.

Each triple comprises:

  • a SF_... constant
  • a string name
  • a list that further specifies the parameter, the list contents depending on the SF_... constant

Most SF_... constants denote not only the type of the parameter, but how it appears in the dialog that ScriptFu can present in the GIMP GUI. (What kind of control widget will appear in the GUI.)


GIMP constants in ScriptFu

The ScriptFu interpreter also recognizes symbols for constants defined by GIMP. You use these symbols as arguments in calls to PDB procedures. They are generally of the form GIMP-... , that is, upper case with hyphens.


Examples and templates

Many examples can be found in the tutorials.

Many examples are in the GIMP repository at /gimp/plug-ins/script-fu/scripts.


A very brief and incomplete example, giving the basic structure of a plugin, is:

(define (script-fu-my-plugin 
...
)      )
(script-fu-register "script-fu-my-plugin"
...
)
(script-fu-menu-register "script-fu-my-plugin"
...
)

In the above example, you define the "run function" of your plugin, then call two functions to register it. After you install your script, your plugin will be in the PDB, and may appear in the GIMP GUI.



The Tiny Scheme language

Scheme is a dialect of Lisp. Lisp is a pure programmer's language with a very simple syntax.

GIMP provides a subset of the Scheme language called TinyScheme. The set of functions implemented by the TinyScheme interpreter of GIMP is smaller than the set implemented by the full Scheme language. But you can textually include third party Scheme functions inside your plug-in.

Revised5 Report on the Algorithmic Language Scheme

Early versions of GIMP used a different dialect of Lisp for ScriptFu plugins. You may occasionally find ancient scripts in that dialect.

A history and porting guide for GIMP TinyScheme plugins

Lisp is beautiful because it is can be interpreted by a small program (an interpreter for Lisp written in Lisp can be a few tens of lines.) ScriptFu (the plugin support offered by GIMP) is implemented by a small interpreter written in the C language, part of GIMP


Internationalization

You can declare intent to internationalize strings in ScriptFu plugins using "_" notation before strings, for example:

_"Clothify..."

You only need to internationalize strings that appear in the GUI.

Getting people to translate your strings is another matter.