Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for gimp (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

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

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

       This is mostly a reference manual. For a quick intro, look at Gimp::Fu. For more informa-
       tion, including tutorials, look at the Gimp-Perl pages at http://gimp.pages.de.

       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
       (http://www.haskell.org) to see how functional is done right.

       Since I was unable to write a haskell interface (and perl is the traditional scripting
       language), I wrote a Perl interface instead. Not too bad a decision I believe...

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


       If you don't specify any import tags, Gimp assumes "qw/:consts main xlfd_size/" which is
       usually what you want.

	   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!

	   Import PARAM_* constants (PDB_INT32, PDB_STRING etc.) only.

	   All constants from gimpenums.h (BG_IMAGE_FILL, RUN_NONINTERACTIVE, NORMAL_MODE,
	   PDB_INT32 etc.).

	   Set default spawn options to options, see Gimp::Net.

	   The default set (see below).

       The default (unless '' is specified) is 'main', 'xlfd_size', ':consts', '__'.  ('__' is
       used for i18n purposes).

       You should first read the Gimp::Fu manpage and then come back. This manpage is mainly
       intended for reference purposes.

       Also, Dov Grobgeld has written an excellent tutorial for Gimp-Perl. You can find it at

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

       Some hilights:

       o Networked plug-ins and plug-ins using the libgimp interfaces (i.e. to be started from
       within The 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
       o 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)"
       o Gimp::Fu will start The Gimp for you, if it cannot connect to an existing gimp process.
       o You can optionally overwrite the pixel-data functions by versions using piddles (see

       noteworthy limitations (subject to be changed):

       o callback procedures do not poass return values to The Gimp.

       All plug-ins (and extensions etc.) _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"

       If you need to do cleanups before exiting you should use the "quit" callback (which is not
       yet available if you use Gimp::Fu).


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

	   The callback for a registered function ("gimp_install_procedure" and friends). The
	   arguments from The 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 The Gimp (as soon as
	   The Gimp implements such a functionality) as an execution error.

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

       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 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 in gimp versions before 1.2 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!):


       If you don't use the ":auto" import tag, you can call all Gimp functions using OO-Syntax:


       As you can see, you can also drop part of the name prefixes with this syntax, so its actu-
       ally shorter to write.

       "But how do I call functions containing dashes?". Well, get your favourite perl book and
       learn perl! Anyway, newer perls understand a nice syntax (see also the description for


       You can drop the "Gimp::" when using the ":auto"-import-tag. Very (very!) old perls may


       (unfortunately. the plug-in in this example is actually called "plug_in_the_egg" *sigh*)

       In this section, you can find descriptions of special functions, functions having differ-
       ent 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 sup-
	   ported. Initializations can later be done in the init function.

	   This auxillary functions parses the XLFD (usually obtained from a "PF_FONT" parameter)
	   and returns its size and unit (e.g. "(20,POINTS)"). This can conviniently 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;

	   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

       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.

       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;

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

       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 exclu-
	   sive access, they are nops when used via the Gimp::Lib interface.

	   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)

	   this function returns true whenever it is safe to clal gimp functions. This is usually
	   only the case after gimp_main or gimp_init have been called.

	   Using this fucntion 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 over-
	   write ('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).

       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. The parameters and return values for the func-
	   tions are specified as an array ref containing either integers or array-refs with
	   three elements, [PARAM_TYPE, \"NAME\", \"DESCRIPTION\"].

	   Initializes a progress bar. In networked modules this is a no-op.

	   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 docu-
	   mented 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.:


	   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.

	   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 compila-
	   tion/runtime errors are reported as runtime errors (i.e. throwing an exception).

       In this manual, only the plain syntax (that lesser 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 fact, OO-syntax saves soooo much typing
       as well. See Gimp::OO for details.

       No, I can't tell you how to cure immune deficiencies (which might well be uncurable, as
       AIDS virii might be able to survive in brain cells, among other unreachable (for medica-
       tion) parts of your body), but I can tell you how Gimp can help you debugging your

       Gimp::set_trace (tracemask)
	   Tracking down bugs in gimp scripts is difficult: no sensible error messages.  If any-
	   thing 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.

		   nothing is printed.

		   all pdb calls (and only pdb calls!) are printed with arguments and return val-

		   the parameter types are printed additionally.

		   the parameter names are printed.

		   the parameter descriptions.

		   all of the above.

	   "set_trace" returns the old tracemask.

	   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.

	   write trace to FILEHANDLE instead of STDERR.

       Gimp supports different data types like colors, regions, strings. In perl, these are rep-
       resented as:

       INT32, INT16, INT8, FLOAT, STRING
	   normal perl scalars. Anything except STRING will be mapped to a perl-double.

	   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.

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

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

	   represented as an array ref [name, flags, data], where name and data should be perl
	   strings and flags is the numerical flag value.

	   Not yet supported (and might never be).

       Marc Lehmann <pcg@goof.com>

       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, Gimp::Module, scm2perl
       and scm2scm.

perl v5.8.0				    2001-12-06					  Gimp(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 05:55 PM.