- NAME
- SYNOPSIS
- GETTING STARTED
- DESCRIPTION
- OUTLINE OF A GIMP PLUG-IN
- CALLING GIMP FUNCTIONS
- SPECIAL FUNCTIONS
- SPECIAL METHODS
- OBJECT ORIENTED SYNTAX
- DEBUGGING AIDS
- SUPPORTED GIMP DATA TYPES
- AUTHOR
- SEE ALSO
NAME
Gimp: a Perl extension for writing Gimp Extensions/Plug-ins/Load & Save-Handlers
This is a release of gimp-perl for gimp-2.0. It is not compatible with version 1.2.x or below of The Gimp.
This is mostly a reference manual. For a quick intro, look at Gimp::Fu.
SYNOPSIS
use Gimp; use Gimp::Fu; # easy scripting environment
IMPORT TAGS
Place these in your
use Gimp qw(...) command to have added features available to your plug-in.
- :auto
Import useful constants, like RGB, RUN_NONINTERACTIVE... as well as all libgimp and pdb functions automagically into the caller's namespace. This will overwrite your AUTOLOAD function, if you have one.
- :param
Import PARAM_* constants (PDB_INT32, PDB_STRING etc.) only.
- :consts
All constants from gimpenums.h (BG_IMAGE_FILL, RUN_NONINTERACTIVE, NORMAL_MODE, PDB_INT32 etc.).
- spawn_options=options
Set default spawn options to options, see Gimp::Net.
- :DEFAULT
The default set (see below).
The default (unless '' is specified) is
'main', ':consts', '__'. (
'__' is used for i18n purposes).
GETTING STARTED
Gimp::Fu is recommended for scripts not requiring custom interfaces or speciailized execution. Lots of examples are in the
examples/ directory of your gimp-perl source tree, or installed in your plug-ins directory if you are running from a package.
Using the
Xtns->DB Browser is a good way to learn The GIMP's Procedural Database(pdb). For referencing functions you already know of, the included script gimpdoc is useful.
DESCRIPTION
Gimp-Perl is a module for writing plug-ins, extensions, standalone scripts, and file-handlers for The GNU Image Manipulation Program (The GIMP). It can be used to automate repetitive tasks, acheive a precision hard to get through manual use of The GIMP, interface to a web server, or other tasks that involve Gimp.
It is developed on Linux, and should work with similar OSes.
Some hilights:
Access to The GIMP's Procedural Database (pdb) for manipulation of most objects.
Use either a plain pdb (scheme-like) interface or an object-oriented syntax, i.e.
gimp_image_new(600,300,RGB)is the same as
new Image(600,300,RGB)
Networked plug-ins look/behave the same as those running from within gimp.
Gimp::Fu will start The GIMP for you, if it cannot connect to an existing GIMP process.
You can access the pixel-data functions using piddles (see Gimp::PDL) giving the same level of control as a C plug-in, with a data language wrapper.
Over 50 example scripts to give you a good starting point, or use as is.
OUTLINE OF A GIMP PLUG-IN
All plug-ins (with the exception of those using
Gimp::init) 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..
- Gimp::on_query
Do any activities that must be performed at Gimp startup, when the procedure is queried. Should typically have at least one call to gimp_install_procedure.
- Gimp::on_net
Run when called from a network interface (from the Perl-Server or from running it standalone).
- Gimp::on_lib
Run only when called itneractively from within Gimp.
- Gimp::on_run
Run when anything calls it (network or lib). to change "-" (dashes) to "_"  and hopefully clearer to read.
SPECIAL FUNCTIONS
In this section, you can find descriptions of special functions, functions having different calling conventions/semantics than might be expected or otherwise 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 supported. Initializations can later be done in the init function.
- 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 ... };.
This function has not been well tested.
- Gimp::init([connection-argument]), Gimp::end(). This is used in the process of testing the module ('make test').
- do nothing when used via the Gimp::Lib interface.
-, 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/Gimp::canonicalize_color
Take in a color specifier in a variety of different formats, and return a valid gimp color specifier, consisting of 3 or 4 numbers in the range between 0 and 1.0.
For example:
$color = canonicalize_colour ("#ff00bb"); $color = canonicalize_colour ([255,255,34]); $color = canonicalize_colour ([255,255,34,255]); $color = canonicalize_colour ([1.0,1.0,0.32]); $color = canonicalize_colour ('red');
Note that bounds checking is excessively lax; this assumes relatively good input
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 from the C library.
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.
-).
OBJECT ORIENTED SYNTAX
In this manual, only the plain syntax (that lesser languages like C use) is described. See Gimp::OO for details on using the object oritented syntax. The 'gimpdoc' script will also return OO varients when functions are described. For example:
gimpdoc image_new
has a section:
SOME SYNTAX ALTERNATIVES image = Gimp->image_new (width,height,type) image = new Image (width,height,type) image = image_new Display (width,height,type)
DEBUGGING AIDS
How to debug your scripts:
- Gimp::set_trace (tracemask)
Tracking down bugs in gimp scripts is difficult, due to a lack of reasonable error messages. Often, if anything goes wrong, you only get an execution failure.
You can switch on tracing to see which parameters are used to call pdb functions, so you can at least see what was called to cause the error.
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 (default).
-.
AUTHOR
Marc Lehmann <pcg@goof.com> (pre-2.0)
Seth Burgess <sjburge@gimp.org> (2.0+)
SEE ALSO
perl(1), gimp(1), Gimp::OO, Gimp::Data, Gimp::Pixel, Gimp::PDL, Gimp::Util, Gimp::UI, Gimp::Feature, Gimp::Net, Gimp::Compat, Gimp::Config, Gimp::Lib, and Gimp::Module .
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 680:
=cut found outside a pod block. Skipping to next block.