Gimp - Perl extension for writing Gimp Extensions/Plug-ins/Load & Save-Handlers
This is mostly a reference manual. For a quick intro, look at
Gimp::Fu. For more information, including tutorials, look at the
Gimp-Perl pages at http://gimp.pages.de.
RATIONALE
Well, scheme (which is used by script-fu), is IMnsHO the crappiest language
ever (well, the crappiest language that one actually can use, so it's not
_that_ bad). Scheme has the worst of all languages, no data types, but still
using variables. Look at haskell (http://www.haskell.org) to see how
functional is done right.
Since I was unable to write a haskell interface (and perl is the traditional
scripting language), I wrote a Perl interface instead. Not too bad a
decision I believe...
SYNOPSIS
use Gimp;
Other modules of interest:
use Gimp::Fu; # easy scripting environment
use Gimp::PDL; # interface to the Perl Data Language
these have their own manpage.
IMPORT TAGS
If you don't specify any import tags, Gimp assumes "qw/:consts main xlfd_size/"
which is usually what you want.
:auto
Import useful constants, like RGB, RUN_NONINTERACTIVE... as well as all
libgimp and pdb functions automagically into the caller's namespace. BEWARE!
This will overwrite your AUTOLOAD function, if you have one!
I think you already know what this is about: writing Gimp
plug-ins/extensions/scripts/file-handlers/standalone-scripts, just about
everything you can imagine in perl. If you are missing functionality (look
into TODO first), please feel free contact the author...
Some hilights:
* Networked plug-ins and plug-ins using the libgimp interfaces (i.e. to be started from within The Gimp) look almost the same (if you use the Gimp::Fu interface, there will be no visible differences at all), you can easily create hybrid (networked & libgimp) scripts as well.
* Use either a plain pdb (scheme-like) interface or nice object-oriented syntax, i.e. gimp_image_new(600,300,RGB) is the same as new Image(600,300,RGB)
* Gimp::Fu will start The Gimp for you, if it cannot connect to an existing gimp process.
* You can optionally overwrite the pixel-data functions by versions using piddles (see Gimp::PDL)
noteworthy limitations (subject to be changed):
* callback procedures do not poass return values to The Gimp.
OUTLINE OF A GIMP PLUG-IN
All plug-ins (and extensions etc.) _must_ contain a call to "Gimp::main".
The return code should be immediately handed out to exit:
exit main; # Gimp::main is exported by default.
Before the call to "Gimp::main", no other PDB function must be called.
In a "Gimp::Fu"-script, you should call "Gimp::Fu::main" instead:
exit main; # Gimp::Fu::main is exported by default as well.
This is similar to Gtk, Tk or similar modules, where you have to call the
main eventloop. Attention: 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.
If you need to do cleanups before exiting you should use the "quit"
callback (which is not yet available if you use Gimp::Fu).
CALLBACKS
THIS SECTION IS OUTDATED AND WILL BE REWORKED SOON. USE Gimp::Fu or READ
THE SOURCE :(
If you use the plain Gimp module (as opposed to Gimp::Fu), your program
should only call one function: "main". Everything else is going to be
called from The Gimp at a later stage. For this to work, you should
define certain call-backs in the same module you called "Gimp::main":
init (), query (), quit ()
the standard libgimp callback functions. "run"() is missing, because this
module will directly call the function you registered with
"gimp_install_procedure". Some only make sense for extensions, some
only for normal plug-ins.
<installed_procedure>()
The callback for a registered function ("gimp_install_procedure" and
friends). The arguments from The Gimp are passed as normal arguments
(with the exception of arrays being passed without a preceding count).
The return values from <installed_procedure>() are checked against the
specification, with the exception that a single "undef" is treated like no
arguments. you can return less, but not more results than specified.
If you "die" within the callback, the error will be reported to The Gimp
(as soon as The Gimp implements such a functionality) as an execution error.
net ()
this is called when the plug-in is not started directly from within the
Gimp, but instead from the Net-Server (the perl network server extension you
hopefully have installed and started ;)
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 the Gimp-Xtns menu (but remember that
DB Browser is buggy and displays ``_'' (underscores) as ``-'' (dashes), so
you can't see the difference between gimp_quit and gimp-quit. As a rule
of thumb, Script-Fu in gimp versions before 1.2 registers scripts with
dashes, and everything else uses 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, but see below
for another possibility!):
As you can see, you can also drop part of the name prefixes with this
syntax, so its actually shorter to write.
``But how do I call functions containing dashes?''. Well, get your favourite
perl book and learn perl! Anyway, newer perls understand a nice syntax (see
also the description for "gimp_call_procedure"):
(unfortunately. the plug-in in this example is actually called
``plug_in_the_egg'' *sigh*)
SPECIAL FUNCTIONS
In this section, you can find descriptions of special functions, functions
having different calling conventions/semantics than I would expect (I
cannot speak for you), or just plain interesting functions. All of these
functions must either be imported explicitly or called using a namespace
override ("Gimp::"), not as Methods ("Gimp->").
main(), Gimp::main()
Should be called immediately when perl is initialized. Arguments are not yet
supported. Initializations can later be done in the init function.
xlfd_size(fontname)
This auxillary functions parses the XLFD (usually obtained from a "PF_FONT"
parameter) and returns its size and unit (e.g. "(20,POINTS)"). This can
conviniently used in the gimp_text_..._fontname functions, which ignore the
size (no joke ;). Example:
$drawable->text_fontname (50, 50, "The quick", 5, 1, xlfd_size $font, $font;
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.
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 "Gimp::end" is optional.
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 are nops 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", 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 clal gimp functions. This is
usually only the case after gimp_main or gimp_init have been called.
Using this fucntion 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).
SPECIAL METHODS
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 ("Gimp->"
or "$object->").
Mostly same as gimp_install_procedure. 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.:
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
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. Actually, the recommended way to write gimp scripts is to use the
fancy OO-like syntax you are used to in perl (version 5 at least ;). As a
fact, OO-syntax saves soooo much typing as well. See Gimp::OO for
details.
DEBUGGING AIDS
No, I can't tell you how to cure immune deficiencies (which might well be
uncurable, as AIDS virii might be able to survive in brain cells, among
other unreachable (for medication) parts of your body), but I can tell
you how Gimp can help you debugging your scripts:
Gimp::set_trace (tracemask)
Tracking down bugs in gimp scripts is difficult: no sensible error messages.
If anything goes wrong, you only get an execution failure. Switch on
tracing to see which parameters are used to call pdb functions.
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.
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.
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.
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 elements (i.e. [233,40,40]), a X11-like
string (``#rrggbb'') or a colour name (``papayawhip'') (see set_rgb_db).