Gimp - Perl extension for writing Gimp Extensions/Plug-ins/Load & Save-Handlers
This is mostly a reference manual. For a quick intro, look at the Gimp::Fu manpage. For more information, including tutorials, look at the Gimp-Perl pages at http://gimp.pages.de.
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...
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.
If you don't specify any import tags, Gimp assumes qw/:consts main xlfd_size/
which is usually what you want.
The default (unless '' is specified) is 'main', 'xlfd_size', ':consts', '__'.
('__' is used for i18n purposes).
You should first read the Gimp::Fu manpage and then come back. This manpage is mainly intended for reference purposes.
Also, Dov Grobgeld has written an excellent tutorial for Gimp-Perl. You can find it at http://imagic.weizmann.ac.il/~dov/gimp/perl-tut.html
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:
noteworthy limitations (subject to be changed):
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).
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:
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.
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.
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!):
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->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.
``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):
"Gimp::plug-in-the-egg"->(RUN_INTERACTIVE,$image,$drawable);
You can drop the Gimp:: when using the :auto-import-tag. Very
(very!) old perls may need:
&{"Gimp::plug-in-the-egg"}("Gimp",RUN_INTERACTIVE,$image,$drawable);
(unfortunately. the plug-in in this example is actually called ``plug_in_the_egg'' *sigh*)
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->).
xlfd_size(fontname)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;
This is different to Gtk->init_add, which only gets called in Gtk->main, which is too late for registering types.
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 the Gimp::Net manpage. Calling Gimp::end is optional.
Currently, these functions only lock the current Perl-Server instance against exclusive access, they are nops when used via the Gimp::Lib interface.
perldoc -m Gimp, at the end of the file (the default database is
similar, but not identical to the X11 default rgb.txt)
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).
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->).
gimp_progress_init(message,[])gimp_progress_update(percentage)gimp_image_new(args...);
is replaced by
gimp_call_procedure "gimp_image_new",args...;
at runtime.
PARAM_INT32ARRAY's would be to return a reference to an array of
integers, rather than blessed objects.
server_eval(string)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).
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 the Gimp::OO manpage for details.
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:
This function is never exported, so you have to qualify it when calling.
tracemask is any number of the following flags or'ed together.
set_trace returns the old tracemask.
Gimp supports different data types like colors, regions, strings. In perl, these are represented as:
Marc Lehmann <pcg@goof.com>
perl(1), gimp(1), the Gimp::OO manpage, the Gimp::Data manpage, the Gimp::Pixel manpage, the Gimp::PDL manpage, the Gimp::Util manpage, the Gimp::UI manpage, the Gimp::Feature manpage, the Gimp::Net manpage, the Gimp::Compat manpage, the Gimp::Config manpage, the Gimp::Lib manpage, the Gimp::Module manpage, scm2perl and scm2scm.