Gimp Man Page

---

Name

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

This is mostly a reference manual. For a quick introduction, look at the Gimp::Fu man page. For more information, including tutorials, look at the Gimp-Perl pages at http://gimp.pages.de.

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 man page.

Import Tags

If you don't specify 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!

:param

Import PARAM_* constants (PARAM_INT32, PARAM_STRING, etc.) only.

:consts

All constants from gimpenums.h:

BG_IMAGE_FILL, RUN_NONINTERACTIVE, NORMAL_MODE,
PARAM_INT32, etc.

spawn_options=options

Set default spawn options to options; see the Gimp::Net man page.

default

The default (unless '' is specified) is main xlfd_size :consts.

Getting Started

You should first read the Gimp::Fu man page and then come back. This man page 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.

Description

I think you already know what this is about: writing Gimp plug-ins/extensions/scripts/file-handlers/stand-alone scripts, just about everything you can imagine in Perl. If you are missing functionality (look into TODO first), please feel free to contact the author.

Some highlights:

· Networked plug-ins and plug-ins using the libgimpinterfaces (i.e., to be started from within 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 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 the Gimp::PDL man page).

Noteworthy Limitation (Subject To Change):

· Callback procedures do not pass return values to Gimp.

Outline Of A Gimp Plug-in

All plug-ins (and extensions) 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

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 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 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 Gimp (as soon as Gimp implements such a functionality) as an execution error.

net ()

This is called when the plug-in is not started directly from within 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 flavors 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 GimpXtns 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).

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 favorite Perl book and learn Perl! Anyway, newer Perls understand a nice syntax (see also the description for gimp_call_procedure):

"plug-in-the-egg"->(RUN_INTERACTIVE,$image,$drawable);

Very old Perls may need:

&{"plug-in-the-egg"}(RUN_INTERACTIVE,$image,$drawable);

(Unfortunately, the plug-in in this example is actually called "plug_in_the_egg" *sigh*. Formatters note: take a look in the plug-in source code, and you will be 100% sure about the name.)

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 auxiliary functions parse the XLFD (usually obtained from a PF_FONT parameter) and return its size and unit (e.g., (20,POINTS)). This can conveniently be 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::init_gtk()

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::init([connection-argument]), Gimp::end()

This is an alternative and experimental interface that replaces the call to Gimp::main and the net callback. At the moment it only works for the Net interface (the Gimp::Net man page), 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 the Gimp::Net man page. 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 Consortium's 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 call gimp functions. This is usually only the case after gimp_main or gimp_init have been called.

Gimp::register_callback (gimp_function_name,perl_function)

Using this function you can overwrite the standard Gimp behavior 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 section 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. 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 the Gimp::Pixel man page, 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 PARAM_INT32ARRAY's would be to return a reference to an array of integers, rather than blessed objects.

server_eval(string)

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 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 matter of fact, OO-syntax saves soooo much typing as well. See the Gimp::OO man page for details.

Debugging Aids

No, I can't tell you how to cure immune deficiencies (which might well be incurable, as AIDS 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.

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.

INT32ARRAY, INT16ARRAY, INT8ARRAY, FLOATARRAY, STRINGARRAY

Array refs containing scalars of the same type, i.e., [1, 2, 3, 4]. Gimp implicitly swallows or generates a proceeding 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 color name ("papayawhip") (see set_rgb_db).

DISPLAY, IMAGE, LAYER, CHANNEL, DRAWABLE, SELECTION

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.

REGION, BOUNDARY, PATH, STATUS

Not yet supported (and might never be).

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), gimp(1), the Gimp::OO man page, the Gimp::Data man page, the Gimp::Pixel man page, the Gimp::PDL man page, the Gimp::Util man page, the Gimp::UI man page, the Gimp::Feature man page, the Gimp::Net man page, the Gimp::Compat man page, the Gimp::Config man page, the Gimp::Lib man page, the Gimp::Module man page, the scm2perl man page and the scm2scm man page.

Gimp::Fu Man Page

---

Name

Gimp::Fu - "easy to use" framework for Gimp scripts

Synopsis

use Gimp;
use Gimp::Fu;

(this module uses Gtk, so make sure it's correctly installed)

Description

Currently, there are only three functions in this module. This fully suffices to provide a professional interface and the ability to run this script from within Gimp and standalone from the commandline.

Dov Grobgeld has written an excellent tutorial for Perl-Fu, see "A Tutorial For Perl Gimp Users" starting on page 735. While not finished, it's definitely worth a look! You can find it at http://imagic.weizmann.ac.il/~dov/gimp/perl-tut.html.

Introduction

In general, a Gimp::Fu script looks like this:

#!/path/to/your/perl

use Gimp;
use Gimp::Fu;

register <many arguments>, sub {
your code;
}

exit main;

(This distribution comes with example scripts. One is examples/example-fu.pl, which is a small Gimp::Fu-script you can take as a starting point for your experiments).

Attention: At the moment it's necessary to always import the Gimp::Fu module after the Gimp module.

The Register Function

register

"function_name",

"blurb", "help",

"author", "copyright",

"date",

"menu path",

"image types",

[

[PF_TYPE,name,desc,optional-default,optional-extra-args],

[PF_TYPE,name,desc,optional-default,optional-extra-args],

# etc...

],

[

# like above, but for return values (optional)

],

[`feature1', `feature2'...], # optionally check for features

sub { code };

function name

The pdb name of the function, i.e. the name under which it will be registered in the Gimp database. If it doesn't start with "perl_fu_", "plug_in_" or "extension_", it will be prepended. If you don't want this, prefix your function name with a single "+". The idea here is that every Gimp::Fu plug-in will be found under the common perl_fu_-prefix.

blurb

A small description of this script/plug-in.

help

A help text describing this script. Should be longer and more verbose than blurb.

copyright

The copyright designation for this script. Important! Save your intellectual rights!

date

The "last modified" time of this script. There is no strict syntax here, but I recommend ISO format (yyyymmdd or yyyy-mm-dd).

menu path

The menu entry Gimp should create. It should start either with <Image>, if you want an entry in the image menu (the one that opens when clicking into an image), <Xtns>, for the Xtns menu or <None> for none.

image types

The types of images your script will accept. Examples are "RGB", "RGB*", "GRAY, RGB" etc... Most scripts will want to use "*", meaning "any type."

The Parameter Array

An array ref containing parameter definitions. These are similar to the parameter definitions used for gimp_install_procedure, but include an additional default value used when the caller doesn't supply one, and optional extra arguments describing some types like PF_SLIDER.

Each array element has the form [type, name, description, default_value, extra_args].

<Image>-type plug-ins get two additional parameters, image (PF_IMAGE) and drawable (PF_DRAWABLE). Do not specify these yourself. Also, the run_mode argument is never given to the script, but its value can be accessed in the package-global $run_mode. The name is used in the dialog box as a hint, the description will be used as a tooltip.

See the section Parameter Types for the supported types.

The Return Values

This is just like the parameter array, just that it describes the return values. Of course, default values don't make much sense here. (Even if they did, it's not implemented anyway.) This argument is optional.

The Features Requirements

See the Gimp::Features man page for a description of which features can be checked for. This argument is optional (but remember to specify an empty return value array, [], if you want to specify it).

The Code

This is either an anonymous sub declaration (sub { your code here; }, or a coderef, which is called when the script is run. Arguments (including the image and drawable for <Image> plug-ins) are supplied automatically.

It is good practice to return an image, if the script creates one, or undef, since the return value is interpreted by Gimp::Fu (like displaying the image or writing it to disk). If your script creates multiple pictures, return an array.

PARAMETER TYPES

PF_INT8, PF_INT16, PF_INT32, PF_INT, PF_FLOAT, PF_STRING, PF_VALUE

Are all mapped to a string entry, since Perl doesn't really distinguish between all these datatypes. The reason they exist is to help other scripts (possibly written in other languages! really!). It's nice to be able to specify a float as 13.45 instead of "13.45" in C! PF_VALUE is synonymous to PF_STRING, and <PF_INT> is synonymous to <PF_INT32>.

PF_COLOR, PF_COLOUR

Will accept a color argument. In dialogs, a color preview will be created which will open a color selection box when clicked.

PF_IMAGE

A Gimp image.

PF_DRAWABLE

A Gimp drawable (image, channel or layer).

PF_TOGGLE, PF_BOOL

A boolean value (anything Perl would accept as true or false). The description will be used for the togglebutton label!

PF_SLIDER

Uses a horizontal scale. To set the range and stepsize, append an array ref (see Gtk::Adjustment for an explanation) [range_min, range_max, step_size, page_increment, page_size] as "extra argument" to the description array. Default values will be substitued for missing entries, like in:

[PF_SLIDER, "alpha value", "the alpha value", 100, [0, 255, 1] ]

PF_SPINNER

The same as PF_SLIDER, except that it uses a spinbutton instead of a scale.

PF_RADIO

In addition to a default value, an extra argument describing the various options must be provided. That extra argument must be a reference to an array filled with Option-Name = Option-Value> pairs. Gimp::Fu will then generate a horizontal frame with radio buttons, one for each alternative. For example:

[PF_RADIO, "direction", "the direction to move to", 5,\
[Left => 5, Right => 7]]]

draws two buttons, when the first (the default, "Left") is activated, 5 will be returned. If the second is activated, 7 is returned.

PF_FONT

Lets the user select a font and returns an X Logical Font Descriptor (XLFD). The default argument, if specified, must be a full XLFD specification, or a warning will be printed. Please note that the Gimp text functions using these fontnames (gimp_text_..._fontname) ignore the size. You can extract the size and dimension by using the xlfd_size function.

In older Gimp-Versions a user-supplied string is returned.

PF_BRUSH, PF_PATTERN, PF_GRADIENT

Lets the user select a brush/pattern/gradient whose name is returned as a string. The default brush/pattern/gradient-name can be preset.

PF_CUSTOM

PF_CUSTOM is for those of you requiring some nonstandard-widget. You have to supply a code reference returning three values as the extra argument:

(widget, settor, gettor)

widget is Gtk widget that should be used.

settor is a function that takes a single argument, the new value for the widget (the widget should be updated accordingly).

gettor is a function that should return the current value of the widget.

While the values can be of any type (as long as it fits into a scalar), be prepared to get a string when the script is started from the commandline or the PDB.

PF_FILE

This represents a file system object. It usually is a file, but can be anything (directory, link). It might not even exist at all.

Miscellaneous Functions

save_image(img,options_and_path)

This is the internal function used to save images. As it does more than just gimp_file_save, I thought it would be handy in other circumstances as well.

The img is the image you want to save (which might get changed during the operation!), options_and_path denotes the filename and optinal options. If there are no options, save_image tries to deduce the filetype from the extension. The syntax for options is

[IMAGETYPE[OPTIONS...]:]filespec

IMAGETYPE is one of GIF, JPG, JPEG, PNM or PNG options include

options valid for all images

+F flatten the image (default depends on the image)

-F do not flatten the image

options for GIF and PNG images

+I do save as interlaced (GIF only)

-I do not save as interlaced (default)

options for PNG images

-Cn use compression level n

options for JPEG images

-Qn use quality "n" to save file (JPEG only)

-S do not smooth (default)

+S smooth before saving

some examples:

test.jpg save the image as a simple jpeg

JPG:test.jpg same

JPG-Q70:test.jpg the same but force a quality of 70 "

GIF-I-F:test.jpg save a gif image(!) named test.jpg non- inerlaced and without flattening

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), the Gimp manpage.

Gimp::OO Man Page

---

Name

Gimp::OO -- Pseudo-OO for Gimp functions.

Synopsis

use Gimp; # Gimp::OO is now part of Gimp.

Description

As you might have noticed, you can sort most Gimp functions into three groups, depending on the nameprefix: gimp_, plug_in_, extension_ etc.

What's more, there are functions groups like gimp_image_ or gimp_selection_, operating on a common object, Images and Selection in this case.

If you only had the plain syntax, your scripts would quickly acquire the "vertical Gimp syndrome":

gimp_palette_set_foreground(...)
gimp_layer_new(...)
gimp_palette_set_background(...)
gimp_image_add_layer(...)

Of course, your fingers will suffer from severe injuries as well.

A solution to this situation is to use OO-syntax. Gimp plays some (very) dirty tricks and provides a number of classes, like Gimp::Image and Gimp::Palette that allow shorter identifiers to be used (all these appear with the Gimp:: prefix as well as without, i.e., Gimp::Palette is the same class as Palette).

If you call a method, Gimp tries to find a Gimp function by prepending a number of prefixes until it finds a valid function:

$image = Gimp->image_new(...);
# calls gimp_image_new(...)

$image = Image->new(...);
# calls gimp_image_new as well

$image = new Image(...);
# the same in green

Palette->set_foreground(...)
#calls
#gimp_palette_set_foreground(..)

Return values from functions are automatically blessed (through The Magic Autobless feature ;) to their corresponding classes, i.e.:

$image = new Image(...);
# $image is now blessed to
# Gimp::Image

$image->height;
# calls gimp_image_height($image)

$image->flatten;
# likewise gimp_flatten($image)

$image->histogram(...);
# calls gimp_histogram($image,...),
# since gimp_image_histogram
# does not exist

The class argument ($image in the above examples) is prepended to the argument list.

Another shortcut: Many functions want a (redundant) image argument, like:

$image->shear ($layer, ...)

Because all you want is to shear the $layer, not the $image, this is confusing as well. In cases like this, Gimp allows you to write:

$layer->shear (...)

and automatically infers the additional IMAGE-type argument.

As the (currently) last goodie, if the first argument is of type INT32, its name is "run_mode" and there are no other ambiguties, you can omit it, i.e. these three calls are equivalent:

plug_in_gauss_rle (RUN_NONINTERACTIVE, $image, $layer, 8, 1, 1);

plug_in_gauss_rle ($image, $layer, 8, 1, 1);

plug_in_gauss_rle ($layer, 8, 1, 1);

You can call all sorts of sensible and not-so-sensible functions, so this feature can be abused:

patterns_list Image; # will call gimp_patterns_list

quit Plugin; # will quit the Gimp, not an Plugin.

There is no image involved here whatsoever.

Available Classes

The following classes (with and without Gimp::) are available. The prefixes that are checked are shown as well (the null prefix "" is implicit).

Gimp (there is no Gimp::Gimp, only Gimp::)

gimp_

Layer

gimp_layer_
gimp_drawable_
gimp_floating_sel_
gimp_image_
gimp_
plug_in_

Image

gimp_image_
gimp_drawable_
gimp_
plug_in_

Drawable

gimp_drawable_
gimp_layer_
gimp_image_
gimp_
plug_in_

Selection

gimp_selection_

Channel

gimp_channel_
gimp_drawable_
gimp_selection_
gimp_image_
gimp_
plug_in_

Display

gimp_display_
gimp_

Palette

gimp_palette_

Plugin

plug_in_

Gradients

gimp_gradients_

Edit

gimp_edit_

Progress

gimp_progress_

Region

(none except the implicit null prefix)

Tile

gimp_tile_

PixelRgn

gimp_pixel_rgn_

GDrawable

gimp_gdrawable_

Brushes

gimp_brushes_

Parasite

parasite_
gimp_

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), the Gimp manpage.

Gimp::Data Man Page

---

Name

Gimp::Data -- Set and get state data.

Synopsis

use Gimp::Data;

$Gimp::Data{'value1'} = "Hello";
print $Gimp::Data{'value1'},", World!!\n";

Description

With this module, you can access plug-in-specific (or global) data in Gimp, i.e., you can store and retrieve values that are stored in the main Gimp application.

An example would be to save parameter values in Gimp, so that on subsequent invocations of your plug-in, the user does not have to set all parameter values again (the Gimp::Fu man page does this already).

%Gimp::Data

You can store and retrieve anything you like in this hash. Its contents will automatically be stored in Gimp, and can be accessed in later invocations of your plug-in. Be aware that other plug-ins store data in the same "hash", so better prefix your key with something unique, like your plug-in's name. As an example, the Gimp::Fu module uses "function_name/_fu_data" to store its data.

This module might use a persistent implementation, i.e., your data might survive a restart of the Gimp application, but you cannot count on this.

Limitations

You cannot store references, and you cannot (yet) iterate through the keys (with keys, values or each).

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), the Gimp manpage.

Gimp::Util Man Page

---

Name

Gimp::Util -- some handy routines for Gimp-Perl users

Synopsis

use Gimp;
use Gimp::Util;

Description

Gimp-Perl is nice, but when you have to write 10 lines every time just to get some simple functions done, it very quickly becomes tedious :-/

This module tries to define some functions that aim to automate frequently used tasks, i.e. it's a sort of catchall-bag for (possibly) useful macro functions. If you want to add a function just mail the author of the GimpPerl extension (see below).

In Gimp-Perl (but not in Gimp as seen by the end user) it is possible to have layers that are NOT attached to an image. This is, IMHO a bad idea, you end up with them and the user cannot see them or delete them. So we always attach our created layers to an image here, to avoid memory leaks and debugging times.

These functions try to preserve the current settings like colors, but not all do.

Also: These functions are handled in exactly the same way as PDB-Functions, i.e., the (hypothetical) function gimp_image_xyzzy can be called as $image->xyzzy, if the module is available.

The need to explicitly use Gimp::Util will go away in the future.

Functions

get_state (), set_state state

get_state returns a scalar representing most of Gimp's global state (at the moment foreground color, background color, active gradient, pattern and brush). The state can later be restored by a call to set_state. This is ideal for library functions such as the ones used here, at least when it includes more state in the future.

layer_create image, name, color, pos

Creates a colored layer, insert into image and return layer.

text_draw imag, layer, text, font, size, fgcolor

Creates a colored text, draw over a background, add to img, ret img.

image_create_text text, font, size, fgcolor, bgcolor

Creates an image, add colored text layer on a background layer, return img.

layer_add_layer_as_mask image, layer, layermask

Takes a layer and add it as a mask to another layer, return mask.

gimp_text_wh $text, $fontname

Returns the width and height of the "$text" of the given font (XLFD format)

gimp_drawable_mask $drawable

Returns an array (x,y,w,h) containing the upper-left corner and the size of the current mask, just as needed by pixelrgn and similar functions.

gimp_image_layertype $alpha

Returns the corresponding layer type for an image, alpha controls whether the layer type is with alpha or not. Example: imagetype: RGB -> RGB_IMAGE (or RGBA_IMAGE).

gimp_image_add_new_layer $image, $index, $fill_type, $alpha

Creates a new layer and adds it at position $index (default 0) to the image, after filling it with gimp_drawable_fill $fill_type (default BG_IMAGE_FILL). If $alpha is non-zero (default 1), the new layer has alpha.

gimp_image_set_visible $image, @layers,

gimp_image_set_invisible $image,@layers mark the given layers visible (invisible) and all others invisible (visible).

gimp_layer_get_position $layer

Returns the position the layer has in the image layer stack.

gimp_layer_set_position $layer, $new_index

Moves the layer to a new position in the layer stack.

Author

Various, version 1.000 written mainly by Tels (http://bloodgate.com/). The author of the Gimp-Perl extension (contact him to include new functions) is Marc Lehmann <pcg@goof.com>

Gimp::Pixel Man Page

---

Name

Gimp::Pixel -- how to operate on raw pixels

Synopsis

use Gimp;

use Gimp::PDL; # you need Gimp::PDL for pixel access

use PDL; # to make sensible things with the pixels

# Gimp::GDrawable - The GDrawable structure

# Gimp::Tile - The Tile family of functions.

# Gimp::PixelRgn - The PixelRgn family of functions.

Description

You can access the pixels in a drawable through tiles or pixel regions. This man page explains how this is done in Perl. All classes (Gimp::GDrawable, Gimp::Tile, Gimp::PixelRgn) are available with and without the Gimp:: prefix.

Gdrawables

Well, you know drawables (also known as PARAM_DRAWABLE or Gimp::Drawable)? In Gimp, drawables are things you can draw on: layers, channels or whole images. While most functions named gimp_drawable_something operate on drawable_IDs, some functions (notably the ones operating on raw pixel data!) need a GDrawable instead. Every drawable has a corresponding GDrawable; you can get it with the gimp_drawable_get function:

my $gdrawable = $drawable->get;

When the $gdrawable is destroyed, it is automatically flushed and detached, so you don't need to do this yourself.

Tiles

Tiles are the basic building blocks of all drawables. Each drawable consists of a "grid" of tiles, each tile having the same size. The size of a tile is always the same (it's hardcoded in your Gimp program).

The gimp_tile_width and gimp_tile_height functions return the current width/height of a tile (at the moment, this is 64x64).

How do I get a tile? First, you have to grab a GDrawable structure. You can get one from any drawable, by calling the get function:

my $gdrawable = $drawable->get;

In a sense, <$gdrawable> contains all tiles. Changes you make to them might not be reflected in the image until you destroy this variable. (Thats the reason I used "my" in the above example. Once $gdrawable gets out of scope, the drawable in the Gimp automatically gets updated).

To get access to a tile, you have to call get_tile or get_tile2. get_tile expects row/column numbers of the tile, while get_tile2 expects pixel coordinates and will return the tile that pixel is in:

my $tile = $gdrawable->get_tile2(1,75,60);

The data method returns and sets the raw pixel data.

$piddle = $tile->data; # get the tile data as a piddle

$piddle *= 0.5; # do sth. with the pixels

$tile->data($piddle); # and modify the tile

PixelRegions

PixelRegions are rectangular parts of a drawable. You can access single pixels, rows, columns and rectangles within these regions. Don't expect me to explain everything now, I don't understand the mechanism too well myself.

How do I create a pixel region? First, you have to grab a GDrawable structure. You can get one from any drawable, by calling the get function:

my $gdrawable = $drawable->get;

Now, you can create as many PixelRgn structures as you want from the GDrawable:

my $region = new PixelRgn($gdrawable,0,0,50,30,1,0); # with "new"

my $region = $gdrawable->pixel_rgn(0,0,50,30,1,0); #or from a \
#drawable

Which method you choose is purely a question of style...

The following functions return packed pixel data (see the Gimp::PDL man page for an easier way to manipulate on image data):

$piddle = $region->get_pixel(45,60);
#return the pixel at (45|60)

$piddle = $region->get_row(45,60,10);
#return ten horizontal pixels

$piddle = $region->get_col(45,60,10);
#same but vertically

$piddle = $region->get_rect(45,60,10,12);
#a 10x12 rectangle

To modify pixels, the dirty bit of the region must be set (I believe, but I don't see what the dirty bit in a region is for, so I might be wrong), and you can write pixel data to the region with the following functions, each one corresponding to a get-function:

$region->set_pixel($piddle,45,60);
# set pixel at (45|60)

$region->set_row($piddle,45,60);
# set a row "

$region->set_col($piddle,45,60);
# set a column

$region->set_rect($piddle,45,60);
# set a whole rectangle

Please note that (unlike the C functions they call), the size arguments (width and/or height) are missing; they can be calculated from the piddle.

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), Gimp(1).

Gimp::Compat Man Page

---

Name

Gimp::Compat -- compatibility functions for older versions of Gimp.

Synopsis

<loaded automatically on demand>

Description

Older versions of Gimp (version 1.0 at the time of this writing) lack some very important or useful functions.

This module is providing the most needed replacement functions. If you happen to miss a function, then please create a replacement function and send it to me ;)

These functions are handled in exactly the same way as PDB-Functions, i.e., the (hypothetical) function gimp_image_xyzzy can be called as $image->xyzzy, if the module is available.

Functions

gimp_text_fontname, gimp_get_extents_fontname

These are emulated in 1.0.

gimp_paintbrush

The last two arguments only available in 1.1 are simply dropped.

Author

Various, Dov Grobgeld <dov@imagic.weizmann.ac.il>. The author of the Gimp-Perl extension (contact him to include new functions) is Marc Lehmann <pcg@goof.com>

Gimp::Feature Man Page

---

Name

Gimp::Features -- check for specific features to be present before registering the script.

Synopsis

use Gimp::Features;

or

use Gimp::Features qw(feature1 feature2 ...);

Description

This module can be used to check for specific features to be present. This can be used to deny running the script when neccessary features are not present. While some features can be checked for at any time, the Gimp::Fu module offers a nicer way to check for them.

gtk

Checks for the presence of the gtk interface module.

gtk-1.1, gtk-1.2

Checks for the presence of gtk-1.1 (1.2) or higher.

perl-5.005

Checks for Perl version 5.005 or higher.

pdl

Checks for the presence of a suitable version of PDL (>=1.9906).

gnome

Checks for the presence of the Gnome-Perl module.

gtkxmhtl

Checks for the presence of the Gtk::XmHTML module.

unix

Checks whether the script runs on a unix-like operating system. At the moment, this is every system except windows, macos, os2 and vms.

gimp-1.1, gimp-1.2

Checks for the presense of Gimp in at least version 1.1 (1.2).

This feature can only be checked after Gimpmain> has been called (usually found in the form exit main). See the Gimp::Fu man page on how to check for these.

Functions

present(feature)

Checks for the presense of the single feature given as the argument. Returns true if the feature is present, false otherwise.

need(feature,[function-name])

Requires a specific feature. If the required feature is not present, the program will exit gracefully, logging an appropriate message. You can optionally supply a function name to further specify the place where this feature was missing.

This is the function used when importing symbols from the module.

missing(feature-description,[function-name])

Indicates that a generic feature (described by the first argument) is missing. A function name can further be specified. This function will log the given message and exit gracefully.

describe(feature)

Returns a string describing the given feature in more detail, or undef if there is no description for this feature.

list()

Returns a list of features that can be checked for. This list might not be complete.

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), Gimp(1).

Gimp::Config Man Page

---

Name

Gimp::Config -- config options found during configure time.

Description

The Gimp::Config module creates a tied hash %Gimp::Config which contains all the definitions the configure script and Perl deduced from the system configuration at configure time. You can access these values just like you access any other values, i.e., $Gimp::Config{KEY}. Some important keys are:

IN_GIMP => true when Gimp-Perl was part of the Gimp distribution.

GIMP => the path of the Gimp executable

prefix => the installation prefix

libdir => the Gimp system-wide libdir

bindir => paths where Gimp binaries are installed

gimpplugindir => the Gimp plug-in directory (without the /plug-ins-suffix)

See Also

The Gimp man page.

Gimp::Pod Man Page

---

Name

Gimp::Pod -- Evaluate pod documentation embedded in scripts.

Synopsis

use Gimp::Pod;

$pod = new Gimp::Pod;

$text = $pod->format ();

$html = $pod->format ('html');

$synopsis = $pod->section ('SYNOPSIS');

$author = $pod->author;

@sections = $pod->sections;

Description

Gimp::Pod can be used to find and parse embedded pod documentation in Gimp-Perl scripts. At the moment, only the formatted text can be fetched; future versions might have more interesting features.

Methods

new

Returns a new Gimp::Pod object representing the current script or undef, if an error occurred.

format([$format])

Returns the embedded pod documentation in the given format, or undef if no documentation can be found. Format can be one of `text', `html', `man' or `latex'. If none is specified, 'text' is assumed.

section($header)

Tries to retrieve the section with the header $header. There is no trailing newline on the returned string, which may be undef in case the section can't be found.

copyright

Tries to retrieve fields suitable for calls to the register function.

sections

Returns a list of paragraphs found in the pod.

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), Gimp(1),

Gimp::Net Man Page

---

Name

Gimp::Net -- Communication module for the Gimp-Perl server.

Synopsis

use Gimp;

Description

For Gimp::Net (and thus commandline and remote scripts) to work, you first have to install the "Perl-Server" extension somewhere where Gimp can find it (e.g.,, in your .gimp/plug-ins/ directory). Usually, this is done automatically while installing the Gimp extension. If you have a menu entry C<<Xtns>/Perl-Server> then it is probably installed.

The Perl Server can either be started from the C<<Xtns>> menu in Gimp, or automatically when a Perl script can't find a running Perl Server.

When started from within Gimp, the Perl-Server will create a unix domain socket to which local clients can connect. If an authorization password is given to the Perl Server (by defining the environment variable GIMP_HOST before starting Gimp), it will also listen on a tcp port (default 10009). Since the password is transmitted in cleartext, using the Perl-Server over tcp effectively lowers the security of your network to the level of telnet. Even worse: The current Gimp::Netprotocol can be used for denial of service attacks, i.e., crashing the Perl Server. There also *might* be buffer overflows.

Environment

The environment variable GIMP_HOST specifies the default server to contact and/or the password to use. The syntax is [auth@][tcp/]hostname[:port] for tcp, [auth@]unix/local/socket/path for unix and spawn/ for a private gimp instance. Examples are:

www.yahoo.com # just kidding ;)"

yahoo.com:11100 # non-standard port "

tcp/yahoo.com # make sure it uses tcp

authorize@tcp/yahoo.com:123 # full-fledged specification "

unix/tmp/unx # use unix domain socket "

password@unix/tmp/test # additionally use a password "

authorize@ # specify authorization only "

spawn/ # use a private gimp instance "

spawn/nodata # pass --no-data switch "

spawn/gui # don't pass -n switch

Callbacks

net()

Is called after you have succesfully connected to the server. Do your dirty work in this function, or see the Gimp::Fu man page for a better solution.

Functions

server_quit()

Sends the Perl Server a quit command.

get_connection()

Return a connection id which uniquely identifies the current connection.

set_connection(conn_id)

Set the connection to use on subsequent commands. conn_id is the connection id as returned by get_connection( ).

Bugs

(Ver 0.04) This module is much faster than it was thought to be... Silly that I wondered whether I should implement it in Perl or C, since Perl is so fast.

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), the Gimp manpage.

21/May/99 Perl 5.004, patch 04 1

Gimp::Lib Man Page

---

Name

Gimp::Lib -- Interface to libgimp (as opposed to Gimp::Net)

Synopsis

use Gimp; # internal use only

Description

This is the package that interfaces to Gimp via the libgimp interface, i.e., the normal interface to use with Gimp. You don't normally use this module directly, look at the documentation for the package "Gimp".

Author

Marc Lehmann <pcg@goof.com>

See Also

perl(1), the Gimp man page.

Gimp::PDL Man Page

---

Name

Gimp::PDL -- Overwrite Tile/Region functions to work with piddles. This module is obsolete, please remove any references to it.

Synopsis

use Gimp;
use Gimp::PDL;
use PDL;

Description

This module overwrites some methods of Gimp::Tile and Gimp::PixelRgn. The new functions return and accept piddles. The last argument (height) of gimp_pixel_rgn_set_rect is calculated from the piddle. There is no other way to access the raw pixeldata in Gimp.

Some examples:

$region = $drawable->get->pixel_rgn (0,0, 100,100, 1,0);

$pixel = $region->get_pixel (5,7);
# fetches the pixel from (5|7)

print $pixel; " "
# outputs something like

# [255, 127, 0], i.e. in

# RGB format ;)

$region->set_pixel ($pixel * 0.5, 5, 7);
# darken the pixel

$rect = $region->get_rect (3,3,70,20);
# get a horizontal stripe "

$rect = $rect->hclip(255/5)*5;
# clip and multiply by 5

$region->set_rect($rect); " "
# and draw it! "

undef $region; " "
# and update it!

Author

Marc Lehmann <pcg@goof.com>

See Also

The Gimp::Pixel man page, perl(1), Gimp(1).

This module is obsolete, please remove any references to it.

Gimp::UI Man Page

---

Name

Gimp::UI -- "simulation of libgimpui", and more!

Synopsis

use Gimp::UI;

Description

Due to the brain-damaged (read: "unusable") libgimpui API, I had to reimplement all of it in Perl.

$option_menu = new Gimp::UI::ImageMenu

$option_menu = new Gimp::UI::LayerMenu

$option_menu = new Gimp::UI::ChannelMenu

$option_menu = new Gimp::UI::DrawableMenu \
(constraint_func, active_element, \var);

$button = new Gimp::UI::PatternSelect;

$button = new Gimp::UI::BrushSelect;

$button = new Gimp::UI::GradientSelect;

$button = new Gimp::UI::ColorSelectButton;

Author

Marc Lehmann <pcg@goof.com>. The ColorSelectButton code is written by Dov Grobgeld <dov@imagic.weizmann.ac.il>, with modifications by Kenneth Albanowski <kjahds@kjahds.com>.

See Also

perl(1), the Gimp man page.