Gimp man page on Mandriva

Man page or keyword search:  
man Server   17060 pages
apropos Keyword Search (all sections)
Output format
Mandriva logo
[printable version]

Gimp(3)		      User Contributed Perl Documentation	       Gimp(3)

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.

       In a "Gimp::Fu"-script, it will actually call "Gimp::Fu::main" instead
       of "Gimp::main":

	exit main;	       # Gimp::Fu::main is exported by default when using Gimp::Fu

       This is similar to Gtk, Tk or similar modules, where you have to call
       the main eventloop.

       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.

   CALLBACKS
       The Gimp module provides routines to be optionally filled in by a plug-
       in writer.  This does not apply if using "Gimp::Fu", as these are done
       automatically.

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

CALLING GIMP FUNCTIONS
       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 to change
	"-" (dashes) to	 "_" (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 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 ... };
	   Add a callback function that should be called when gtk is being
	   initialized (i.e. when Gimp::gtk_init is called, which should
	   therefore be done even in Gnome applications).

	   This is different to Gtk->init_add, which only gets called in
	   Gtk->main, which is too late for registering types.

	   This function has not been well tested.

       Gimp::init([connection-argument]), Gimp::end()
	   These is an alternative interface that replaces the call to
	   Gimp::main and the net callback. At the moment it only works for
	   the Net interface (Gimp::Net), 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 Gimp::Net. Calling "Gimp::end" is optional.
	   This is used in the process of testing the module ('make test').

       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 do nothing 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 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
	   (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 behaviour
	   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).

       Gimp::canonicalize_colour/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->").

       gimp_install_procedure(name, blurb, help, author, copyright, date,
       menu_path, image_types, type, [params], [return_vals])
	   Mostly same as gimp_install_procedure from the C library. 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 Gimp::Pixel, to keep this manual
	   page short.

       gimp_call_procedure(procname, arguments...)
	   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.

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

       server_eval(string)
	   This 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 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).

	   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 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 preceeding 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 or 4 elements (i.e.
	   [0.1,0.4,0.9] or [233,40,40]), a X11-like string ("#rrggbb") or a
	   colour 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.

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 .

POD ERRORS
       Hey! The above document had some coding errors, which are explained
       below:

       Around line 680:
	   =cut found outside a pod block.  Skipping to next block.

perl v5.10.1			  2005-09-15			       Gimp(3)
[top]

List of man pages available for Mandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net