Gimp: a Perl extension for writing Gimp Extensions/Plug-ins/Load & Save-Handlers

This is a release of gimp-perl for gimp-2.0. It is not compatible with version 1.2.x or below of The Gimp.

This is mostly a reference manual. For a quick intro, look at Gimp::Fu.

  use Gimp;
  use Gimp::Fu;         # easy scripting environment

Place these in your CWuse Gimp qw(...) command to have added features available to your plug-in.

:auto

Import useful constants, like RGB, RUN_NONINTERACTIVE... as well as all libgimp and pdb functions automagically into the caller's namespace. This will overwrite your AUTOLOAD function, if you have one.

:param

Import PARAM_* constants (PDB_INT32, PDB_STRING etc.) only.

:consts

All constants from gimpenums.h (BG_IMAGE_FILL, RUN_NONINTERACTIVE, NORMAL_MODE, PDB_INT32 etc.).

spawn_options=options

Set default spawn options to options, see Gimp::Net.

:DEFAULT

The default set (see below).

The default (unless '' is specified) is CW'main', ':consts', '__'. (CW'__' is used for i18n purposes).

Gimp::Fu is recommended for scripts not requiring custom interfaces or speciailized execution. Lots of examples are in the CWexamples/ directory of your gimp-perl source tree, or installed in your plug-ins directory if you are running from a package.

Using the CWXtns->DB Browser is a good way to learn The GIMP's Procedural Database(pdb). For referencing functions you already know of, the included script gimpdoc is useful.

Gimp-Perl is a module for writing plug-ins, extensions, standalone scripts, and file-handlers for The GNU Image Manipulation Program (The GIMP). It can be used to automate repetitive tasks, acheive a precision hard to get through manual use of The GIMP, interface to a web server, or other tasks that involve Gimp.

It is developed on Linux, and should work with similar OSes.

Some hilights:

* Access to The GIMP's Procedural Database (pdb) for manipulation of most objects.

* Networked plug-ins look/behave the same as those running from within gimp.

* Gimp::Fu will start The GIMP for you, if it cannot connect to an existing GIMP process.

* You can access the pixel-data functions using piddles (see Gimp::PDL) giving the same level of control as a C plug-in, with a data language wrapper.

* Over 50 example scripts to give you a good starting point, or use as is.

All plug-ins (with the exception of those using CWGimp::init) must contain a call to CWGimp::main.

The return code should be immediately handed out to exit:

 exit main;             # Gimp::main is exported by default.

Before the call to CWGimp::main, no other PDB function must be called.

In a CWGimp::Fu-script, it will actually call CWGimp::Fu::main instead of CWGimp::main:

 exit main;             # Gimp::Fu::main is exported by default when using Gimp::Fu

This is similar to Gtk, Tk or similar modules, where you have to call the main eventloop.

Although you call CWexit with the result of CWmain, the main function might not actually return. This depends on both the version of Gimp and the version of the Gimp-Perl module that is in use. Do not depend on CWmain to return at all, but still call CWexit immediately.

The Gimp module provides routines to be optionally filled in by a plug-in writer. This does not apply if using CWGimp::Fu, as these are done automatically.

Gimp::on_query

Do any activities that must be performed at Gimp startup, when the procedure is queried. Should typically have at least one call to gimp_install_procedure.

Gimp::on_net

Run when called from a network interface (from the Perl-Server or from running it standalone).

Gimp::on_lib

Run only when called itneractively from within Gimp.

Gimp::on_run

Run when anything calls it (network or lib).

There are two different flavours of gimp-functions. Functions from the PDB (the Procedural DataBase), and functions from libgimp (the C-language interface library).

You can get a listing and description of every PDB function by starting the DB Browser extension in the GIMP Xtns menu (but remember to change - (dashes) to _ (underscores)).

libgimp functions can't be traced (and won't be traceable in the foreseeable future).

To call pdb functions (or equivalent libgimp functions), just treat them like normal perl (this requires the use of the CW:auto import tag, but see below for another possibility!):

 gimp_palette_set_foreground([20,5,7]);
 gimp_palette_set_background("cornsilk");

If you don't use the CW:auto import tag, you can call all Gimp functions using OO-Syntax:

 Gimp->gimp_palette_set_foreground([20,5,7]);
 Gimp->palette_set_background("cornsilk");
 Palette->set_foreground('#1230f0');

As you can see, you can also drop part of the name prefixes with this syntax, so its actually shorter to write and hopefully clearer to read.

In this section, you can find descriptions of special functions, functions having different calling conventions/semantics than might be expected or otherwise interesting functions. All of these functions must either be imported explicitly or called using a namespace override (CWGimp::), not as Methods (CWGimp->).

main(), Gimp::main()

Should be called immediately when perl is initialized. Arguments are not supported. Initializations can later be done in the init function.

Gimp::gtk_init()

Initialize Gtk in a similar way the Gimp itself did it. This automatically parses gimp's gtkrc and sets a variety of default settings (visual, colormap, gamma, shared memory...).

Gimp::gtk_init_add { init statements ... };

Add a callback function that should be called when gtk is being initialized (i.e. when Gimp::gtk_init is called, which should therefore be done even in Gnome applications). This is different to Gtk->init_add, which only gets called in Gtk->main, which is too late for registering types. This function has not been well tested.

Gimp::init([connection-argument]), Gimp::end()

These is an alternative interface that replaces the call to Gimp::main and the net callback. At the moment it only works for the Net interface (Gimp::Net), and not as a native plug-in. Here's an example:

 use Gimp;

 Gimp::init;
 <do something with the gimp>

The optional argument to init has the same format as the GIMP_HOST variable described in Gimp::Net. Calling CWGimp::end is optional. This is used in the process of testing the module ('make test').

Gimp::lock(), Gimp::unlock()

These functions can be used to gain exclusive access to the Gimp. After calling lock, all accesses by other clients will be blocked and executed after the call to unlock. Calls to lock and unlock can be nested. Currently, these functions only lock the current Perl-Server instance against exclusive access, they do nothing when used via the Gimp::Lib interface.

Gimp::set_rgb_db(filespec)

Use the given rgb database instead of the default one. The format is the same as the one used by the X11 Consortiums rgb database (you might have a copy in /usr/lib/X11/rgb.txt). You can view the default database with CWperldoc -m Gimp, at the end of the file (the default database is similar, but not identical to the X11 default rgb.txt)

Gimp::initialized()

this function returns true whenever it is safe to call gimp functions. This is usually only the case after gimp_main or gimp_init have been called.

Gimp::register_callback(gimp_function_name, perl_function)

Using this function you can overwrite the standard Gimp behaviour of calling a perl subroutine of the same name as the gimp function. The first argument is the name of a registered gimp function that you want to overwrite ('perl_fu_make_something'), and the second argument can be either a name of the corresponding perl sub ('Elsewhere::make_something') or a code reference (\&my_make).

Gimp::canonicalize_colour/Gimp::canonicalize_color

Take in a color specifier in a variety of different formats, and return a valid gimp color specifier, consisting of 3 or 4 numbers in the range between 0 and 1.0. For example:

 $color = canonicalize_colour ("#ff00bb");
 $color = canonicalize_colour ([255,255,34]);
 $color = canonicalize_colour ([255,255,34,255]);
 $color = canonicalize_colour ([1.0,1.0,0.32]);
 $color = canonicalize_colour ('red');

Note that bounds checking is excessively lax; this assumes relatively good input

This chapter descibes methods that behave differently than you might expect, or methods uniquely implemented in perl (that is, not in the PDB). All of these must be invoked using the method syntax (CWGimp-> or CW$object->).

gimp_install_procedure(name, blurb, help, author, copyright, date, menu_path, image_types, type, [params], [return_vals])

Mostly same as gimp_install_procedure from the C library. The parameters and return values for the functions are specified as an array ref containing either integers or array-refs with three elements, [PARAM_TYPE, \NAME\, \DESCRIPTION\].

gimp_progress_init(message,[])

Initializes a progress bar. In networked modules this is a no-op.

gimp_progress_update(percentage)

Updates the progress bar. No-op in networked modules.

gimp_tile_*, gimp_pixel_rgn_*, gimp_drawable_get

With these functions you can access the raw pixel data of drawables. They are documented in Gimp::Pixel, to keep this manual page short.

gimp_call_procedure(procname, arguments...)

This function is actually used to implement the fancy stuff. Its your basic interface to the PDB. Every function call is eventually done through his function, i.e.:

 gimp_image_new(args...);

is replaced by

 gimp_call_procedure "gimp_image_new",args...;

at runtime.

gimp_list_images, gimp_image_get_layers, gimp_image_get_channels

These functions return what you would expect: an array of images, layers or channels. The reason why this is documented is that the usual way to return CWPDB_INT32ARRAY's would be to return a reference to an array of integers, rather than blessed objects.

gimp_drawable_bounds drawable/gdrawable

Returns an array (x,y,w,h) containing the upper left corner and the size of currently selected parts of the drawable, just as needed by PixelRgn->new and similar functions.

server_eval(string)

This evaluates the given string in array context and returns the results. It's similar to CWeval, but with two important differences: the evaluating always takes place on the server side/server machine (which might be the same as the local one) and compilation/runtime errors are reported as runtime errors (i.e. throwing an exception).

In this manual, only the plain syntax (that lesser languages like C use) is described. See Gimp::OO for details on using the object oritented syntax. The 'gimpdoc' script will also return OO varients when functions are described. For example:

gimpdoc image_new

has a section:

SOME SYNTAX ALTERNATIVES image = Gimp->image_new (width,height,type) image = new Image (width,height,type) image = image_new Display (width,height,type)

How to debug your scripts:

Gimp::set_trace (tracemask)

Tracking down bugs in gimp scripts is difficult, due to a lack of reasonable error messages. Often, if anything goes wrong, you only get an execution failure. You can switch on tracing to see which parameters are used to call pdb functions, so you can at least see what was called to cause the error. This function is never exported, so you have to qualify it when calling. tracemask is any number of the following flags or'ed together.

TRACE_NONE

nothing is printed (default).

TRACE_CALL

all pdb calls (and only pdb calls!) are printed with arguments and return values.

TRACE_TYPE

the parameter types are printed additionally.

TRACE_NAME

the parameter names are printed.

TRACE_DESC

the parameter descriptions.

TRACE_ALL

all of the above. CWset_trace returns the old tracemask.

Gimp::set_trace(\$tracevar)

write trace into CW$tracevar instead of printing it to STDERR. CW$tracevar only contains the last command traces, i.e. it's cleared on every PDB invocation invocation.

Gimp::set_trace(*FILEHANDLE)

write trace to FILEHANDLE instead of STDERR.

Gimp supports different data types like colors, regions, strings. In perl, these are represented as:

INT32, INT16, INT8, FLOAT, STRING

normal perl scalars. Anything except STRING will be mapped to a perl-double.

INT32ARRAY, INT16ARRAY, INT8ARRAY, FLOATARRAY, STRINGARRAY

array refs containing scalars of the same type, i.e. [1, 2, 3, 4]. Gimp implicitly swallows or generates a preceeding integer argument because the preceding argument usually (this is a de-facto standard) contains the number of elements.

COLOR

on input, either an array ref with 3 or 4 elements (i.e. [0.1,0.4,0.9] or [233,40,40]), a X11-like string (#rrggbb) or a colour name (papayawhip) (see set_rgb_db).

DISPLAY, IMAGE, LAYER, CHANNEL, DRAWABLE, SELECTION

these will be mapped to corresponding objects (IMAGE => Gimp::Image). In trace output you will see small integers (the image/layer/etc..-ID)

PARASITE

represented as an array ref [name, flags, data], where name and data should be perl strings and flags is the numerical flag value.

REGION, BOUNDARY, PATH, STATUS

Not yet supported.

Marc Lehmann <pcg@goof.com> (pre-2.0)

Seth Burgess <sjburge@gimp.org> (2.0+)

perl(1), gimp(1), Gimp::OO, Gimp::Data, Gimp::Pixel, Gimp::PDL, Gimp::Util, Gimp::UI, Gimp::Feature, Gimp::Net, Gimp::Compat, Gimp::Config, Gimp::Lib, and Gimp::Module .