home *** CD-ROM | disk | FTP | other *** search
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Chapter 12.  Scripting</title> <link rel="stylesheet" href="gimp-help-plain.css" type="text/css" /> <link rel="stylesheet" href="gimp-help-screen.css" type="text/css" /> <link rel="stylesheet" href="gimp-help-custom.css" type="text/css" /> <link rel="alternate stylesheet" href="gimp22.css" type="text/css" title="gimp22" /> <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> <link rel="start" href="index.html" title="GNU Image Manipulation Program" /> <link rel="up" href="pt02.html" title="Part II.  How do I Become a GIMP Wizard?" /> <link rel="prev" href="using-customize-splashscreen.html" title="7.  Customize Splash-Screen" /> <link rel="next" href="gimp-concepts-script-fu.html" title="2.  Using Script-Fu Scripts" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Chapter 12.  <span lang="en" xml:lang="en">Scripting</span> </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="using-customize-splashscreen.html"><img src="../images/prev.png" alt="Prev" /></a> </td> <th width="60%" align="center">Part II.  <span lang="en" xml:lang="en"> How do I Become a <acronym class="acronym">GIMP</acronym> Wizard? </span> </th> <td width="20%" align="right"> <a accesskey="n" href="gimp-concepts-script-fu.html"><img src="../images/next.png" alt="Next" /></a></td> </tr> </table> <hr /> </div> <div class="chapter" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title"><a id="gimp-scripting"></a>Chapter 12.  <span lang="en" xml:lang="en">Scripting</span> </h2> </div> </div> </div> <div class="toc"> <p> <b>Table of Contents</b> </p> <dl> <dt> <span class="sect1"> <a href="gimp-scripting.html#gimp-concepts-plugins">1. <span lang="en" xml:lang="en">Plugins</span> </a> </span> </dt> <dd> <dl> <dt> <span class="sect2"> <a href="gimp-scripting.html#id2614743">1.1. <span lang="en" xml:lang="en">Introduction</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-scripting.html#id2614929">1.2. <span lang="en" xml:lang="en">Using Plugins</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-scripting.html#gimp-plugins-install">1.3. <span lang="en" xml:lang="en">Installing New Plugins</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-scripting.html#plugins-write">1.4. <span lang="en" xml:lang="en">Writing Plugins</span> </a> </span> </dt> </dl> </dd> <dt> <span class="sect1"> <a href="gimp-concepts-script-fu.html">2. <span lang="en" xml:lang="en">Using Script-Fu Scripts</span> </a> </span> </dt> <dd> <dl> <dt> <span class="sect2"> <a href="gimp-concepts-script-fu.html#id2615470">2.1. <span lang="en" xml:lang="en">Script-Fu?</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="install-script-fu.html">2.2. <span lang="en" xml:lang="en">Installing Script-Fus</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="ch12s02s03.html">2.3. <span lang="en" xml:lang="en">Do's and Don'ts</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="ch12s02s04.html">2.4. <span lang="en" xml:lang="en">Different Kinds Of Script-Fus</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="standalone-script-fu.html">2.5. <span lang="en" xml:lang="en">Standalone Scripts</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="ch12s02s06.html">2.6. <span lang="en" xml:lang="en">Image-Dependent Scripts</span> </a> </span> </dt> </dl> </dd> <dt> <span class="sect1"> <a href="gimp-using-script-fu-tutorial.html">3. <span lang="en" xml:lang="en">A Script-Fu Tutorial</span> </a> </span> </dt> <dd> <dl> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial.html#gimp-using-script-fu-tutorial-scheme">3.1. <span lang="en" xml:lang="en">Getting Acquainted With Scheme</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-identifier.html">3.2. <span lang="en" xml:lang="en">Variables And Functions</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-lists.html">3.3. <span lang="en" xml:lang="en">Lists, Lists And More Lists</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-first-script.html">3.4. <span lang="en" xml:lang="en">Your First Script-Fu Script</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-script.html">3.5. <span lang="en" xml:lang="en">Giving Our Script Some Guts</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-extending-text-box.html">3.6. <span lang="en" xml:lang="en">Extending The Text Box Script</span> </a> </span> </dt> <dt> <span class="sect2"> <a href="gimp-using-script-fu-tutorial-result.html">3.7. <span lang="en" xml:lang="en">Your script and its working</span> </a> </span> </dt> </dl> </dd> </dl> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="gimp-concepts-plugins"></a>1.  <span lang="en" xml:lang="en">Plugins</span> </h2> </div> </div> </div> <a id="id2614730" class="indexterm"></a> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id2614743"></a>1.1.  <span lang="en" xml:lang="en">Introduction</span> </h3> </div> </div> </div> <p> One of the nicest things about <acronym class="acronym">GIMP</acronym> is how easily its functionality can be extended, by using plugins. <acronym class="acronym">GIMP</acronym> plugins are external programs that run under the control of the main <acronym class="acronym">GIMP</acronym> application and interact with it very closely. Plugins can manipulate images in almost any way that users can. Their advantage is that it is much easier to add a capability to <acronym class="acronym">GIMP</acronym> by writing a small plugin than by modifying the huge mass of complex code that makes up the <acronym class="acronym">GIMP</acronym> core. Many valuable plugins have C source code that only comes to 100-200 lines or so. </p> <p> Several dozen plugins are included in the main <acronym class="acronym">GIMP</acronym> distribution, and installed automatically along with <acronym class="acronym">GIMP</acronym>. Most of them can be accessed through the <span class="guimenu">Filters</span> menu (in fact, everything in that menu is a plugin), but a number are located in other menus. In many cases you can use one without ever realizing that it is a plugin: for example, the "Normalize" function for automatic color correction is actually a plugin, although there is nothing about the way it works that would tell you this. </p> <p> In addition to the plugins included with GIMP , many more are available on the net. A large number can be found at the GIMP Plugin Registry <a class="xref" href="bibliography.html#bibliography-online-gimp-plugin-registry" title="GIMP-Plugin Registry">[<abbr class="abbrev">GIMP-REGISTRY</abbr>]</a>, a web site whose purpose is to provide a central repository for plugins. Creators of plugins can upload them there; users in search of plugins for a specific purpose can search the site in a variety of ways. </p> <p> Anybody in the world can write a <acronym class="acronym">GIMP</acronym> plugin and make it available over the web, either via the Registry or a personal web site, and many very valuable plugins can be obtained in this way ­ some are described elsewhere in the User's Manual. With this freedom from constraint comes a certain degree of risk, though: the fact that anybody can do it means that there is no effective quality control. The plugins distributed with <acronym class="acronym">GIMP</acronym> have all been tested and tuned by the developers, but many that you can download were just hacked together in a few hours and then tossed to the winds. Some plugin creators just don't care about robustness, and even for those who do, their ability to test on a variety of systems in a variety of situations is often quite limited. Basically, when you download a plugin, you are getting something for free, and sometimes you get exactly what you pay for. This is not said in an attempt to discourage you, just to make sure you understand reality. </p> <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Warning"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Warning]" src="../images/warning.png" /> </td> <th align="left">Warning</th> </tr> <tr> <td align="left" valign="top"> <p> Plugins, being full-fledged executable programs, can do any of the things that any other program can do, including install back-doors on your system or otherwise compromise its security. Don't install a plugin unless it comes from a trusted source. </p> </td> </tr> </table> </div> <p> These caveats apply as much to the Plugin Registry as to any other source of plugins. The Registry is available to any plugin creator who wants to use it: there is no systematic oversight. Obviously if the maintainers became aware that something evil was there, they would remove it. (That hasn't happened yet.) There is, however, for <acronym class="acronym">GIMP</acronym> and its plugins the same warranty as for any other free software: namely, none. </p> <div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Caution"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Caution]" src="../images/caution.png" /> </td> <th align="left">Caution</th> </tr> <tr> <td align="left" valign="top"> <p> Plugins have been a feature of <acronym class="acronym">GIMP</acronym> for many versions. However, plugins written for one version of <acronym class="acronym">GIMP</acronym> can hardly ever be used successfully with other versions. They need to be ported: sometimes this is easy, sometimes not. Many plugins are already available in several versions. Bottom line: before trying to install a plugin, make sure that it is written for your version of <acronym class="acronym">GIMP</acronym>. </p> </td> </tr> </table> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="id2614929"></a>1.2.  <span lang="en" xml:lang="en">Using Plugins</span> </h3> </div> </div> </div> <p> For the most part you can use a plugin like any other <acronym class="acronym">GIMP</acronym> tool, without needing to be aware that it is a plugin. But there are a few things about plugins that are useful to understand. </p> <p> One is that plugins are generally not as robust as the <acronym class="acronym">GIMP</acronym> core. When <acronym class="acronym">GIMP</acronym> crashes, it is considered a very serious thing: it can cost the user a lot of trouble and headache. When a plugin crashes, the consequences are usually not so serious. In most cases you can just continuing working without worrying about it. </p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Note]" src="../images/note.png" /> </td> <th align="left">Note</th> </tr> <tr> <td align="left" valign="top"> <p> Because plugins are separate programs, they communicate with the <acronym class="acronym">GIMP</acronym> core in a special way: The <acronym class="acronym">GIMP</acronym> developers call it “<span class="quote">talking over a wire</span>”. When a plugin crashes, the communication breaks down, and you will see an error message about a “<span class="quote">wire read error</span>”. </p> </td> </tr> </table> </div> <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Tip"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Tip]" src="../images/tip.png" /> </td> <th align="left">Tip</th> </tr> <tr> <td align="left" valign="top"> <p> When a plugin crashes, <acronym class="acronym">GIMP</acronym> gives you a very ominous-looking message telling you that the plugin may have left <acronym class="acronym">GIMP</acronym> in a corrupted state, and you should consider saving your images and exiting. Strictly speaking, this is quite correct, because plugins have the power to alter almost anything in <acronym class="acronym">GIMP</acronym>, but for practical purposes, experience has shown that corruption is actually quite rare, and many users just continue working and don't worry about it. Our advice is that you simply think about how much trouble it would cause you if something went wrong, and weigh it against the odds. </p> </td> </tr> </table> </div> <p> Because of the way plugins communicate with <acronym class="acronym">GIMP</acronym>, they do not have any mechanism for being informed about changes you make to an image after the plugin has been started. If you start a plugin, and then alter the image using some other tool, the plugin will often crash, and when it doesn't will usually give a bogus result. You should avoid running more than one plugin at a time on an image, and avoid doing anything to the image until the plugin has finished working on it. If you ignore this advice, not only will you probably screw up the image, you will probably screw up the undo system as well, so that you won't even be able to recover from your foolishness. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="gimp-plugins-install"></a>1.3.  <span lang="en" xml:lang="en">Installing New Plugins</span> </h3> </div> </div> </div> <a id="id2615067" class="indexterm"></a> <p> The plugins that are distributed with <acronym class="acronym">GIMP</acronym> don't require any special installation. Plugins that you download yourself do. There are several scenarios, depending on what OS you are using and how the plugin is structured. In Linux it is usually pretty easy to install a new plugin; in Windows, it is either easy or very hard. In any case, the two are best considered separately. </p> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2615096"></a>1.3.1.  <span lang="en" xml:lang="en">Linux</span> </h4> </div> </div> </div> <p> Most plugins fall into two categories: small ones whose source code is distributed as a single .c file, and larger ones whose source code is distributed as a directory containing multiple files including a <code class="filename">Makefile</code>. </p> <p> For a simple one-file plugin, call it <code class="filename">borker.c</code>, installing it is just a matter of running the command <span class="command"><strong>gimptool-2.0 --install borker.c</strong></span>. This command compiles the plugin and installs it in your personal plugin directory, <code class="filename">~/gimp-2.4/plugins</code> unless you have changed it. This will cause it to be loaded automatically the next time you start <acronym class="acronym">GIMP</acronym>. You don't need to be root to do these things; in fact, you shouldn't be. If the plugin fails to compile, well, be creative. </p> <p> Once you have installed the plugin, how do you activate it? The menu path is determined by the plugin itself, so to answer this you need to either look at the documentation for the plugin (if there is any), or launch the Plugin Description dialog (from Xtns/Plugins Details) search the plug-in by its name and look of the <span class="guilabel">Tree view</span> tab. If you still don't find, finally explore the menus or look at the source code in the Register section -- whichever is easiest. </p> <p> For more complex plugins, organized as a directory with multiple files, there ought to be a file inside called either <code class="filename">INSTALL</code> or <code class="filename">README</code>, with instructions. If not, the best advice is to toss the plugin in the trash and spend your time on something else: any code written with so little concern for the user is likely to be frustrating in myriad ways. </p> <p> Some plugins (specifically those based on the <acronym class="acronym">GIMP</acronym> Plugin Template) are designed to be installed in the main system <acronym class="acronym">GIMP</acronym> directory, rather than your home directory. For these, you will need to be root to perform the final stage of installation (when issuing the <span class="command"><strong>make install</strong></span> command). </p> <p> If you install in your personal plugin directory a plugin that has the same name as one in the system plugin directory, only one can be loaded, and it will be the one in your home directory. You will receive messages telling you this each time you start <acronym class="acronym">GIMP</acronym>. This is probably a situation best avoided. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2615241"></a>1.3.2. Windows</h4> </div> </div> </div> <p> Windows is a much more problematic environment for building software than Linux. Every decent Linux distribution comes fully supplied with tools for compiling software, and they are all very similar in the way they work, but Windows does not come with such tools. It is possible to set up a good software-building environment in Windows, but it requires either a substantial amount of money or a substantial amount of effort and knowledge. </p> <p> What this means in relation to <acronym class="acronym">GIMP</acronym> plugins is the following: either you have an environment in which you can build software, or you don't. If you don't, then your best hope is to find a precompiled version of the plugin somewhere (or persuade somebody to compile it for you), in which case you simply need to put it into your personal plugin directory. If you do have an environment in which you can build software (which for present purposes means an environment in which you can build <acronym class="acronym">GIMP</acronym>), then you no doubt already know quite a bit about these things, and just need to follow the Linux instructions. </p> <p> If you would like to set up a build environment, and are ready for the heroism involved, you can find a reasonably recent description of how to go about it in the <acronym class="acronym">GIMP</acronym> Wiki, at HowToCompileGimp/MicrosoftWindows <a class="xref" href="bibliography.html#bibliography-online-gimp-wiki-compile-windows" title="GIMP-Wiki - How to compile for Windows">[<abbr class="abbrev">GIMP-WIKI01</abbr>]</a>. Since it is a Wiki, anybody is free to edit it, so please keep it up to date by adding advice based on your own experiences. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2615312"></a>1.3.3.  <span lang="en" xml:lang="en">Apple Mac OS X</span> </h4> </div> </div> </div> <p> How you install plugins on OS X mostly depends on how you installed GIMP itself. If you were one of the brave and installed GIMP through one of the package managers like fink <a class="xref" href="bibliography.html#bibliography-online-darwinports" title="Darwin Ports Package Manager for OS X">[<abbr class="abbrev">DARWINORTS</abbr>]</a> or darwinports, <a class="xref" href="bibliography.html#bibliography-online-fink" title="Fink Package Manager for OS X">[<abbr class="abbrev">FINK</abbr>]</a> the plugin installation works exactly the way it is described for the Linux platform already. The only difference is, that a couple of plugins might be even available in the repository of you package manager, so give it a try. </p> <p> If you on the other hand are one of the Users that preferred to grab a prebuild GIMP package like GIMP.app, you most probably want to stick to that prebuild stuff. So you can try to get a prebuild version of the plugin of you dreams from the author of the plugin, but I'd not want to bet on this. Building your own binaries unfortunately involves installing GIMP through one of the package managers mentioned above. </p> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="plugins-write"></a>1.4.  <span lang="en" xml:lang="en">Writing Plugins</span> </h3> </div> </div> </div> <a id="id2615381" class="indexterm"></a> <p> If you want to learn how to write a plugin, you can find plenty of help at the <acronym class="acronym">GIMP</acronym> Developers web site <a class="xref" href="bibliography.html#bibliography-online-gimp-dev-plugin" title="GIMP Plugin Development">[<abbr class="abbrev">GIMP-DEV-PLUGIN</abbr>]</a>. <acronym class="acronym">GIMP</acronym> is a complex program, but the development team has made strenuous efforts to flatten the learning curve for plugin writing: there are good instructions and examples, and the main library that plugins use to interface with <acronym class="acronym">GIMP</acronym> (called “<span class="quote">libgimp</span>”) has a well-documented <acronym class="acronym">API</acronym>. Good programmers, learning by modifying existing plugins, are often able to accomplish interesting things after just a couple of days of work. </p> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="using-customize-splashscreen.html"><img src="../images/prev.png" alt="Prev" /></a> </td> <td width="20%" align="center"> <a accesskey="u" href="pt02.html"> <img src="../images/up.png" alt="Up" /> </a> </td> <td width="40%" align="right"> <a accesskey="n" href="gimp-concepts-script-fu.html"><img src="../images/next.png" alt="Next" /></a></td> </tr> <tr> <td width="40%" align="left" valign="top"><a accesskey="p" href="using-customize-splashscreen.html">7.  <span lang="en" xml:lang="en">Customize Splash-Screen</span> </a> </td> <td width="20%" align="center"> <a accesskey="h" href="index.html"> <img src="../images/home.png" alt="Home" /> </a> </td> <td width="40%" align="right" valign="top"> <a accesskey="n" href="gimp-concepts-script-fu.html">2.  <span lang="en" xml:lang="en">Using Script-Fu Scripts</span> </a></td> </tr> </table> </div> </body> </html> 
