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.
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 (or will have)
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!
Import PARAM_* constants (PARAM_INT32, PARAM_STRING etc.)
The constants from gimpenums.h (BG_IMAGE_FILL, RUN_NONINTERACTIVE etc.)
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 hilites:
Networked plug-ins and plug-ins using the libgimp interfaces (i.e. to be started by The Gimp) are written almost the same way (if you use Gimp::Fu, there will be no differences at all), you can easily create hybrid (network & libgimp) scripts as well.
Use either a plain pdb (scheme-like) interface or nice object-oriented syntax, i.e. "gimp_layer_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 PDL)
noteworthy limitations (subject to be changed):
callback procedures do not return anything to The Gimp, not even a status argument, which seems to be mandatory by the gimp protocol (which is nowhere standardized, though).
All plug-ins (and extensions etc.) _must_ contain a call to gimp_main. The return code should be immediately handed out to exit:
gimp_main
exit gimp_main;
In a Gimp::Fu-script, you should call main instead:
main
exit main;
This is similar to Gtk, Tk or similar modules, where you have to call the main eventloop.
If you use the plain Gimp module (as opposed to Gimp::Fu), your program should only call one function: gimp_main. Everything else is being called from the Gimp. For this to work, you should define certain call-backs in the same module you called gimp_main:
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.
run
gimp_install_procedure
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 ;)
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 registers scripts with dashes, and everything else uses underscores).
libgimp functions can't be traced (and won't be traceable in the foreseeable future). Many libgimp functions are merely convinience functions for C programmers that just call equivalent PDB functions.
At the moment, Gimp favours libgimp functions where possible, i.e. the calling sequence is the same, or implementing an interface is too much work when there is an equivalent PDB function anyway. The libgimp functions are also slightly faster, but the real benefit is that users (YOU) will hit bugs in libgimp very effectively ;) Once libgimp is sufficiently debugged, I'll remove the libgimp functions that only shadow PDB functions (thus reducing object size as well).
To call pdb functions (or equivalent libgimp functions), just treat them as normal perl:
gimp_palette_set_foreground([20,5,7]); gimp_palette_ser_background("cornsilk");
"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_call_procedure
"plug-in-the-egg"->(RUN_INTERACTIVE,$image,$drawable);
Older perls need:
&{"plug-in-the-egg"}(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.
Should be called immediately when perl is initialized. Arguments are not yet supported. Initializations can later be done in the init function.
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\"].
Initializes a progress bar. In networked modules this is a no-op.
Updates the progress bar. No-op in networked modules.
With these functions you can access the raw pixel data of drawables. They are documented in Gimp::Pixel, to keep this manual page short.
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.
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 PARAM_INT32ARRAY's would be to return a reference to an array of integers, rather than blessed objects.
PARAM_INT32ARRAY
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.
perldoc -m Gimp
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.
No, I can't tell you how to cure immune deficiencies, but I can tell you how Gimp can help you debugging your scripts:
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. (not yet implemented for networked modules).
tracemask is any number of the following flags or'ed together.
nothing is printed.
all pdb calls (and only pdb calls!) are printed with arguments and return values.
the parameter types are printed additionally.
the parameter names are printed.
the parameter descriptions.
all of the above.
write trace into $tracevar instead of printing it to STDERR. $tracevar only contains the last command traces, i.e. it's cleared on every gimp_call_procedure invocation.
write trace to FILEHANDLE instead of STDERR.
Gimp supports different data types like colors, regions, strings. In perl, these are represented as:
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.
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).
These will be mapped to corresponding objects (IMAGE => Gimp::Image). In trace output you will see small integers (the image/layer/etc..-ID)
Not yet supported.
Marc Lehmann <pcg@goof.com>
perl(1), gimp(1), Gimp::OO, Gimp::Data and Gimp::Util.
2 POD Errors
The following errors were encountered while parsing the POD:
=cut found outside a pod block. Skipping to next block.
You forgot a '=back' before '=head1'
To install Gimp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Gimp
CPAN shell
perl -MCPAN -e shell install Gimp
For more information on module installation, please visit the detailed CPAN module installation guide.