++ed by:
ZMUGHAL DELON EMAZEP ILUX

4 PAUSE users
2 non-PAUSE users.

Marc A. Lehmann

NAME

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

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 to see how functional is done right.

I'd loved to write a haskell interface instead, but it was sooo much easier in perl (at least for me..), so here's the Gimp <-> Perl interface, mostly a direct libgimp interface. Needless to say, it was (is) very instructive, too.

SYNOPSIS

  use Gimp;
  
  Other modules of interest:
  
  use Gimp::Util;
  use Gimp::OO;
  
  these have their own manpage.

IMPORT TAGS

If you don't give an interface= hint, we will guess a default which might be wrong in future versions of the Gimp, so watch out!

: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!

interface=lib

Use direct interface via libgimp.

interface=net

Use network interface using Net-Server and Gimp::Net.

GETTING STARTED

(ignore this section for now... ;) this will eventually contain some minimal plug-in examples)

use Gimp qw( :auto );

sub net { gimp_quit; }

exit gimp_main;

DESCRIPTION

Sorry, I didn't make a very useful documentation yet.. help appreciated!

Look at the sample plug-ins that come with this module. If you write other plug-ins, send them to me! If you have question on use, you might as well ask me (although I'm a busy man, so be patient, or wait for the next version ;)

It might also prove useful to know how a plug-in is written in C, so have a look at some existing plug-ins in C!

Anyway, feedback is appreciated, otherwise, I won't publish future version.

And have a look at the other modules, Gimp::Util and Gimp::OO, and maybe the interface modules Gimp::Lib and Gimp::Net.

Some highlites:

  • Networked plug-ins and plug-ins using the libgimp interfaces (i.e. to be started by The Gimp) are written alsmot the same way, 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)"

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).

  • The tile and region functions are not yet supported.

CALLBACKS

init (), query (), quit (), <installed_procedure>()

the standard libgimp callback functions. run() is missing, because this module will directly call the function you registered with gimp_install_procedure.

net ()

this is called when the plug-in is not started from within Gimp, but is using Net-Server (the perl network server extension you hopefully have installed and started ;)

FUNCTIONS

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. (not yet implemented for networked modules).

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(\$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 gimp_call_procedure invocation.

set_trace(*FILEHANDLE)

write trace to FILEHANDLE instead of STDERR.

gimp_main()

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

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

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.

Some functions that have a different calling convention than pdb functions but the same name are not visible in the perl module. (i.e. pdb functions have priority on name clashes)

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

array refs containing scalars of the same type, i.e. [1, 2, 3, 4]. (not yet supported).

COLOR

on input, either an array ref with 3 elements (i.e. [233,40,40]) or a X11-like string is accepted ("#rrggbb").

REGION

Not yet supported.

DISPLAY, IMAGE, LAYER, CHANNEL, DRAWABLE, SELECTION

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

BOUNDARY, PATH, STATUS

Not yet supported.

PLEASE

if you get this far while reading the manpage, please consider helping me with the documentation, or write scripts etc... ;) thanks!

AUTHOR

Marc Lehmann, pcg@goof.com

SEE ALSO

perl(1), gimp(1), Gimp::Util.