NAME
gimp-perl is a plug-in used for writing GIMP extensions/plug-ins/load &
save handlers in Perl.
WARNING
This version of the module is for use with GIMP 2.8.0 or later.
Current limitations:
Please report all problems
SYNOPSIS
my $img = new Image (600, 300, RGB);
my $bg = $img->layer_new(600,300,RGB_IMAGE,"Background",100,NORMAL_MODE);
$img->add_layer($bg, 1);
$img->edit_fill($bg);
$img->display_new;
A complete & documented example script can be found at the end of
this document (search for EXAMPLE).
DOCUMENTATION
Online documentation is largely outdated. Much of the documentation at
http://www.goof.com/pcg/marc/gimp.html still applies. The POD
information embedded in the modules is the latest available, though
it isn't very updated either.
PREREQUISITES
To install/use this perl extension, you need to have the following
software packages installed (the given order is best):
Perl 5.6 (or higher):
While this extension might run with perl 5.6, it is being developed
using Perl 5.14, and later. If you encounter problems when trying to
use a version of Perl older than 5.14, update to a newer version of
Perl and try again. The developers of this module can neither support
nor encourage the use of older versions of Perl.
The GNU Image Manipulation Program, aka. GIMP
http://www.gimp.org/
ftp://ftp.gimp.org/pub/gimp/
gimp-2.8 (or newer, e.g. git master) is required. For
older versions of GIMP, use version 1.2* of the gimp-perl
module.
Gtk, the perl extension for gtk+2
http://gtk2-perl.sourceforge.net
The "gtk2-perl-xs" variant is required, the "inline"
version is *NOT* supported. Releases (as on CPAN) may work.
PDL, the Perl Data Language
http://www.cpan.org/
Optionally, you can install the PDL module to be able to
manipulate pixel data (or to be able to run the example plug-ins
that do pixel manipulation). PDL is available at any CPAN
mirror, version 2.4 or higher is recommended. Without PDL,
some plug-ins do not work (they will not be installed),
and accessing raw image data is impossible.
INSTALLATION
On Unix/Linux, you should be able to run "perl Makefile.PL", make, make
test && make install. To get a listing of configuration options, enter:
perl ./Makefile.PL --help
Simply using "perl Makefile.PL" should do the job on most systems,
but watch out for warnings. If everything went fine, enter "make",
"make test, (su to appropriate level if you are installing system-wide),
"make install".
After installation, these perl plug-ins should be visible from
within the Gimp (and many, many more):
<Toolbox>/Xtns/Perl-Server
<Image>/Filters/Artistic/Windify
<Image>/Filters/Misc/Prepare for GIF
<Image>/Filters/Misc/Webify
OVERWRITING INSTALL LOCATIONS (PREFIX)
In the rare case that you want to install the gimp-perl modules
somewhere else than in the standard location then there is a
standard way to accomplish this.
Usually, you can just use the PREFIX=/path option to the
Makefile.PL, or the other common solution of adding the INST* path
definitions onto the "make install" commandline.
These options are described in the "perldoc ExtUtils::MakeMaker"
manpage.
If you are building a slp/deb/rpm/whatever package you usually want
to use the normal prefix, while overwriting the prefix at "make
install" time. In that case, just build gimp-perl (or the whole
GIMP) as usual, but instead of just calling "make install", use
something like the following command (this example is for debian):
make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
install
The lowercase prefix is used by the Gimp, the uppercase PREFIX is
used by perl. Rarely you also want to specifiy manpage directories
etc.. you can also overwrite these (see "man ExtUtils::MakeMaker")
as well, e.g. for debian:
make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
INSTALLMAN1DIR=`pwd`/debian/tmp/usr/man/man1 \
INSTALLMAN3DIR=`pwd`/debian/tmp/usr/man/man3 \
install
SUPPORT/MAILING LISTS/MORE INFO
The gimp-user and gimp-developer lists (see
http://www.gimp.org/mail_lists.html) are currently the suggested
mailing lists.
New releases will be announced to gimp-announce.
You can also upload your scripts to the gimp registry at
http://registry.gimp.org/.
If you think your script is of general intrest, please let
<sjburges@gimp.org> know and it will be considered for
inclusion in future Gimp module releases. If you just want
a link to your gimp-perl project, please mail <sjburges@gimp.org>
also.
BLURB
gimp-perl is an effort to make a usable, debuggable, and flexible
interface to GIMP through use of Perl.
LICENSE
The gimp-perl module is available under the GNU Public License
(see COPYING.GPL for details) and the Artistic License (see
COPYING.Artistic for details). Many of the scripts in the example
section follow these rules, but some of them have a different
licensing approach. Each should have a licensing statement; please
consult individual plugin sources/POD for more info.
(c)1998,1999 Marc Lehmann <pcg@goof.com>
(c)2003,2004 Seth Burgess <sjburges@gimp.org>
EXAMPLE PERL PLUG-IN
To get even more look & feel, here is a complete plug-in source,
its the examples/example-fu script from the distribution.
#!/opt/bin/perl
use Gimp;
use Gimp::Fu;
# expand your terminal to 121 across to read easily...
register "gimp_fu_example_script", # fill in a function name
"A non-working example of Gimp::Fu usage", # and a short description,
"Just a starting point to derive new ". # a (possibly multiline) help text
"scripts. Always remember to put a long".
"help message here!",
"Marc Lehmann <pcg\@goof.com>", # don't forget your name (author)
"(c)1998,1999,2000 Marc Lehmann", # and your copyright!
"20000321", # the date this script was written (YYYYMMDD)
N_"<Toolbox>/Xtns/Gimp::Fu Example...", # the menu path - the 'N_' is for internationalization
"RGB*, GRAYA", # image types to accept (RGB, RGAB amnd GRAYA)
[ # one of each type of parameter here
# argument type, switch name , a short description , default value, extra arguments
[PF_SLIDER , "width" , "The image width" , 360, [300, 500]],
[PF_SPINNER , "height" , "The image height" , 100, [100, 200]],
[PF_STRING , "text" , "The Message" , "example text"],
[PF_INT , "bordersize" , "The bordersize" , 10],
[PF_FLOAT , "borderwidth" , "The borderwidth" , 1/5],
[PF_FONT , "font" , "The Font Family" ],
[PF_COLOUR , "text_colour" , "The (foreground) text colour", [10,10,10]],
[PF_COLOUR , "bg_colour" , "The background colour" , [0xff,0x80,0]],
[PF_TOGGLE , "ignore_cols" , "Ignore colours" , 0],
[PF_IMAGE , "extra_image" , "An additonal picture to ignore"],
[PF_DRAWABLE , "extra_draw" , "Somehting to ignroe as well" ],
[PF_RADIO , "type" , "The effect type" , 0, [small => 0, large => 1]],
[PF_BRUSH , "a_brush" , "An unused brush" ],
[PF_PATTERN , "a_pattern" , "An unused pattern" ],
[PF_GRADIENT , "a_gradients" , "An unused gradients" ],
],
sub {
# now do sth. useful with the garbage we got ;)
my($width,$height,$text,$brd1,$brd2,$font,$fg,$bg,$ignore,$xtraimg,
$xtradrw,$effecttype,$brush,$pattern,$gradient)=@_;
# set tracing, disable this to get rid of the debugging output
Gimp::set_trace(TRACE_CALL);
my $img = new Image ($width, $height, RGB);
# put an undo group around any modifications, so that
# they can be undone in one step.
$img->undo_group_start;
# the __ before the string in the next line indicates text that must be translated
my $l = new Layer ($img, $width, $height, RGB, __"Background", 100, NORMAL_MODE);
$l->add_layer(0);
# now a few syntax examples
Context->set_foreground($fg) unless $ignore;
Context->set_background($bg) unless $ignore;
fill $l BACKGROUND_FILL;
$text_layer = $img->text_fontname(-1, 10, 10, $text, 5, 1, 10, PIXELS, $font);
Palette->set_foreground("green");
# close the undo push group
$img->undo_group_end;
$img; # return the image, or an empty list, i.e. ()
};
exit main; # call the "main" funciton to start the script working