/ 
Gimp-2.3000_01
River stage zero No dependents
/ Gimp

NAME

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

This is a release of gimp-perl for gimp-2.8. It is not compatible with version 2.6 or below of GIMP.

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

SYNOPSIS

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

IMPORT TAGS

Place these in your use 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. The AUTOLOAD function that gets installed must only be used in OO mode - either as an object or a class method call - the only exception is when the first argument is a reference (including objects):

use Gimp qw(:auto);
Gimp->displays_flush; # fine
my $name = $layer->get_name; # also fine
gimp_quit(0); # will lose its parameter, due to Perl's OO implementation!
Gimp->quit(0); # works correctly
gimp_image_undo_disable($image); # as does this, by a coincidence
:param

Import constants for plugin parameter types (PDB_INT32, PDB_STRING etc.) only.

:consts

All constants found by querying GIMP (BG_IMAGE_FILL, RUN_NONINTERACTIVE, NORMAL_MODE, PDB_INT32 etc.).

:pollute

In previous version of gimp-perl, you could refer to GIMP classes as either e.g. Gimp::Image, OR Image. Now in order to not pollute the namespace, the second option will be available only when this option is specified.

spawn_options=options

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

:DEFAULT

The default set (see below).

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

GETTING STARTED

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

Using the Help/Procedure Browser is a good way to learn GIMP's Procedural Database(pdb). For referencing functions you already know of, the included script gimpdoc is useful.

DESCRIPTION

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, achieve a precision hard to get through manual use of GIMP, interface to a web server, or other tasks that involve Gimp.

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

Some highlights:

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

  • Use either a plain pdb (scheme-like but with perl OO class method) interface or a fully object-oriented syntax, i.e. Gimp->image_new(600,300,RGB) is the same as new Gimp::Image(600,300,RGB).

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

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

  • You can access the pixel-data functions using piddles (see Gimp::PixelRgn) 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.

ARCHITECTURE

There are two modes of operation: the perl is called by GIMP (as a plugin/filter) ("plugin mode"), or GIMP is called by perl (which uses the Gimp::Net functionality) - either connecting to an existing GIMP process ("net mode"), or starting its own one ("batch mode").

Plugin

The perl script is written as a plug-in using Gimp::Fu as described above. The architecture is simply that Gimp, on start-up, runs all its plug-ins at startup including all the perl scripts in its plugins directory. The perl scripts will register themselves as GIMP "procedures" in the PDB. When these procedures are called, typically from the menu system, the perl script will be run and supplied with the appropriate arguments.

From outside GIMP

The script will use Gimp as above, and use Gimp functions as it wishes. If you are using GIMP interactively, you need to run the Perl server (under "Filters/Perl" to allow your script to connect. Otherwise, the script will start its own GIMP, in "batch mode". Either way, your script, when it uses GIMP procedures (and Gimp-Perl functions), will actually be communicating with the perl server running under GIMP.

The architecture may be visualised like this:

perlscript <-> Gimp::Net <-> Perl-Server <-> Gimp::Lib <-> GIMP

This has certain consequences; native GIMP objects like images and layers obviously persist between Perl method calls, but libgimp entities such as GimpDrawable, with the perl interface Gimp::PixelRgn, require special handling. Currently they do not work when used over Gimp::Net.

OUTLINE OF A GIMP PLUG-IN

All plug-ins (running in "plugin mode") must finish with a call to Gimp::main.

The return code should be immediately handed out to exit:

exit Gimp::main;

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

In a Gimp::Fu-script, it will actually call Gimp::Fu::main instead of Gimp::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 exit with the result of main, 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 main to return at all, but still call exit immediately.

CALLBACKS

The Gimp module provides routines to be optionally filled in by a plug-in writer. This does not apply if using Gimp::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 from within Gimp.

Gimp::on_run

Run when anything calls it (network or lib).

Gimp::on_quit

Run when plugin terminates.

OUTLINE OF A GIMP EXTENSION

A GIMP extension is a special type of plugin. Once started, it stays running all the time. Typically during its run-initialisation (not on query) it will install temporary procedures.

If it has no parameters, then rather than being run when called, either from a menu or a scripting interface, it is run at GIMP startup.

An extension can receive and act on messages from GIMP, unlike a plugin, which can only initiate requests and get responses. This does mean the extension needs to fit in with GIMP's event loop (the Glib event loop in fact - use this by using Gtk2). This is easy. In its run hook, the extension simply needs to run Gimp->extension_ack after it has initialised itself (including installing any temporary procedures). Then, if it wants to just respond to GIMP events:

# to deal only with GIMP events:
Gimp->extension_ack;
Gimp->extension_process(0) while 1;

or also other event sources (including a GUI, or Glib::IO):

  # to deal with other events:
  Gimp::gtk_init;
  Gimp->extension_ack; # GIMP locks until this is done
  Gimp->extension_enable; # adds a Glib handler for GIMP messages
  my $tcp = IO::Socket::INET->new(
    Type => SOCK_STREAM, LocalPort => $port, Listen => 5, ReuseAddr => 1,
    ($host ? (LocalAddr => $host) : ()),
  ) or die __"unable to create listening tcp socket: $!\n";
  Glib::IO->add_watch(fileno($tcp), 'in', sub {
    warn "$$-setup_listen_tcp WATCHER(@_)" if $Gimp::verbose;
    my ($fd, $condition, $fh) = @_;
    my $h = $fh->accept or die __"unable to accept tcp connection: $!\n";
    my ($port,$host) = ($h->peerport, $h->peerhost);
    new_connection($h);
    slog __"accepted tcp connection from $host:$port";
    &Glib::SOURCE_CONTINUE;
  }, $tcp);
  Gtk2->main; # won't return if GIMP quits, but
	      # GIMP will call your quit callback

A working, albeit trivial, example is provided in examples/example-extension. A summarised example:

  use Gimp;
  Gimp::register_callback extension_gp_test => sub {
    # do some relevant initialisation here
    Gimp->install_temp_proc(
      "perl_fu_temp_demo", "help", "blurb", "id", "id", "2014-04-11",
      "<Toolbox>/Xtns/Perl/Test/Temp Proc demo", undef,
      &Gimp::TEMPORARY,
      [ [ &Gimp::PDB_INT32, 'run_mode', 'Run-mode', 0 ], ],
      [],
    );
    Gimp->extension_ack;
    Gimp->extension_process(0) while 1;
  };
  Gimp::register_callback perl_fu_temp_demo => sub {
    my ($run_mode) = @_;
    # here could bring up UI if $run_mode == RUN_INTERACTIVE
  };
  Gimp::on_query {
     Gimp->install_procedure(
	"extension_gp_test", "help", "blurb", "id", "id", "2014-04-11",
	undef, undef,
	&Gimp::EXTENSION,
	[], [],
     );
  };
  exit Gimp::main;

CALLING GIMP FUNCTIONS

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 GIMP's 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 :auto import tag - see the import :auto note for non-OO limitation; see below for another possibility!):

Gimp->palette_set_foreground([20,5,7]);
Gimp->palette_set_background("cornsilk");

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

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

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

SPECIAL FUNCTIONS

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 (Gimp::), not as Methods (Gimp->).

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 GIMP itself did it. This automatically parses gimp's gtkrc and sets a variety of default settings (visual, colormap, gamma, shared memory...).

use Gimp qw(net_init=...);

This is how to use Gimp-Perl in "net mode". Previous versions of this package required a call to Gimp::init. This is no longer necessary. The technical reason for this change is that when Gimp.pm loads, it must connect to GIMP to load its constants, like PDB_INT32.

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

These functions can be used to gain exclusive access to 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 perldoc -m Gimp::ColorDB, 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 has 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 (a GimpRGB), consisting of 3 or 4 numbers in the range between 0 and 1.0.

For example:

$color = canonicalize_colour ("#ff00bb"); # html format
$color = canonicalize_colour ([255,255,34]); # RGB
$color = canonicalize_colour ([255,255,34,255]); # RGBA
$color = canonicalize_colour ([1.0,1.0,0.32]); # actual GimpRGB
$color = canonicalize_colour ('red'); # uses the color database

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

SPECIAL METHODS

This chapter describes 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 (Gimp-> or $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::PixelRgn, to keep this manual page short.

gimp_call_procedure(procname, arguments...)

This function is actually used to implement the fancy stuff. It's 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 PDB_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 Gimp::PixelRgn->new and similar functions.

server_eval(string)

This evaluates the given string in array context and returns the results. It's similar to eval, 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).

OBJECT ORIENTED SYNTAX

In this manual, only the plain syntax (that lesser languages like C use) is described. See Gimp::OO for details on using the object oriented 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 Gimp::Image (width,height,type) $image = image_new Gimp::Display (width,height,type)

DEBUGGING AIDS

How to debug your scripts:

$Gimp::verbose

If set to true, will make Gimp say what it's doing on STDOUT. It will also stop Gimp::Net's normal behaviour of the server-side closing STDIN, STDOUT and STDERR. If you want it to be set during loading Gimp.pm, make sure to do so in a prior BEGIN block:

BEGIN { $Gimp::verbose = 1; }
use Gimp;
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.

set_trace returns the old tracemask.

Gimp::set_trace(\$tracevar)

write trace into $tracevar instead of printing it to STDERR. $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.

GLib debugging

GIMP makes use of GLib. Environment variables including G_DEBUG, and setting G_SLICE to always-malloc, control some behaviour. See https://developer.gnome.org/glib/unstable/glib-running.html for details. Additionally, the behaviour of malloc can be controlled with other environment variables as shown at http://man7.org/linux/man-pages/man3/mallopt.3.html, especially setting MALLOC_CHECK_ (note trailing underscore) to 3.

SUPPORTED GIMP DATA TYPES

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, COLORARRAY

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, VECTORS, ITEM

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.

STATUS

Not yet supported, except implicitly - this is how exceptions (from "die") get returned in "net mode".

AUTHOR

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

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

Ed J (with oversight and guidance from Kevin Cozens) (2.3+)

SEE ALSO

perl(1), gimp(1), Gimp::OO, Gimp::Data, Gimp::PixelRgn, Gimp::Util, Gimp::UI, Gimp::Config, Gimp::Net, and Gimp::Lib.