home *** CD-ROM | disk | FTP | other *** search
/ PC Pro 2002 April / pcpro0402.iso / essentials / graphics / Gimp / gimp-src-20001226.exe / src / gimp / plug-ins / perl / README < prev   
Encoding:
Text File  |  1999-11-21  |  9.9 KB  |  263 lines
  1. NAME
  2.  
  3.        Gimp - Perl extension for writing Gimp Extensions/Plug-ins/Load &
  4.        Save-Handlers
  5.  
  6. SYNOPSIS
  7.  
  8.        my $img = new Image (600, 300, RGB);
  9.        my $bg = $img->layer_new(600,300,RGB_IMAGE,"Background",100,NORMAL_MODE);
  10.        $img->add_layer($bg, 1);
  11.        $img->edit_fill($bg);
  12.        $img->display_new;
  13.        
  14.        A complete & documented example script can be found at the end of
  15.        this document (search for EXAMPLE).
  16.  
  17. DOCUMENTATION
  18.  
  19.        The Manpages in html format, the newest version, links and more
  20.        information can be found on the gimp-perl homepage, where you
  21.        should get an overview over the gimp-perl extension:
  22.  
  23.        http://gimp.pages.de/
  24.        -or-
  25.        http://www.goof.com/pcg/marc/gimp.html
  26.        
  27. PREREQUISITES
  28.  
  29.        To install/use this perl extension, you need to have the following
  30.        software packages installed (the given order is best):
  31.  
  32.        Perl5.004 (or higher):
  33.  
  34.           While this extension should run fine with older versions (it has
  35.           been tested with 5.004_04), I work with Perl5.005 or higher,
  36.           which has much more bugs fixed than the old 5.004.
  37.  
  38.           When in doubt, upgrade.
  39.  
  40.        GTK+, the X11 toolkit:
  41.        http://www.gtk.org/
  42.        ftp://ftp.gimp.org/pub/gtk/
  43.  
  44.           gtk+-1.2 or higher is recommended, but older versions mostly
  45.           work (some features not implemented in gtk+-1.0 do not work
  46.           properly, of course).
  47.  
  48.        Gtk, the perl extension for the above:
  49.        ftp://ftp.gimp.org/pub/gtk/perl/
  50.  
  51.           Gtk-0.6123 (or higher) is recommended. You might encounter some
  52.           problems compiling it for Perl5.004 (or any version), in that
  53.           case you might want to try the updated gnome-perl version on the
  54.           gnome-cvs-server. See the the gimp-perl pages for more info.
  55.  
  56.        The GNU Image Manipulation Program, i.e. The GIMP:
  57.        http://www.gimp.org/
  58.        ftp://ftp.gimp.org/pub/gimp/
  59.  
  60.           gimp-1.1 (or newer, e.g. CVS or CVS snapshots) is recommended
  61.           for full functionality, but any version since 1.0.2 should do,
  62.           some features not implemented in 1.0 don't work, though.
  63.  
  64.        PDL, the Perl Data Language
  65.        http://www.cpan.org/
  66.  
  67.           Optionally, you can install the PDL module to be able to
  68.           manipulate pixel data (or to be able to run the example plug-ins
  69.           that do pixel manipulation). PDL is available at any CPAN
  70.           mirror, version 1.9906 or higher is recommended. Without PDL,
  71.           some plug-ins do not work, and accessing raw image data is
  72.           impossible.
  73.  
  74. INSTALLATION
  75.  
  76.        On unix, you should be able to run "perl Makefile.PL" make, make
  77.        test && make install. To get a listing of configuration options,
  78.        enter
  79.  
  80.        perl ./Makefile.PL --help
  81.        
  82.        a straight "perl Makefile.PL" should do the job on most systems,
  83.        but watch out for warnings. If everything went fine, enter "make",
  84.        "make test", "make install".
  85.  
  86.        After installation, these perl plug-ins should be visible from
  87.        within the Gimp (and many, many more):
  88.  
  89.        <Toolbox>/Xtns/Perl Control Center
  90.        <Toolbox>/Xtns/Perl-Server
  91.        <Image>/Filters/Artistic/Windify
  92.        <Image>/Filters/Misc/Prepare for GIF
  93.        <Image>/Filters/Misc/Webify
  94.        
  95.        If you don't have unix, you can install linux instead
  96.        (http://www.linux.org/)
  97.  
  98. OVERWRITING INSTALL LOCATIONS (PREFIX)
  99.  
  100.        In the rare case that you want to install the Gimp-Perl modules
  101.        somewhere else than in the standard location then there is a
  102.        standard way to accomplish this.
  103.  
  104.        Usually, you can just use the PREFIX=/path option to the
  105.        Makefile.PL, or the other common solution of adding the INST* path
  106.        definitions onto the "make install" commandline.
  107.  
  108.        These options are described in the "perldoc ExtUtils::MakeMaker"
  109.        manpage.
  110.  
  111.        If you are configuring the gimp-pelr module that comes with the
  112.        Gimp sourcetree this won't work. In that case you can set the
  113.        environment variable:
  114.  
  115.        PERL_MM_OPT='whatever options you want to pass to MakeMaker'
  116.  
  117.        before running configure. The arguments that you put into that
  118.        variable will be passed to the Makefile.PL as if given on the
  119.        commandline.
  120.  
  121.        If you are building a slp/deb/rpm/whatever package you usually want
  122.        to use the normal prefix, while overwriting the prefix at "make
  123.        install" time. In that case, just build gimp-perl (or the whole
  124.        gimp) as usual, but instead of just calling "make install", use
  125.        something like the following command (this example is for debian):
  126.  
  127.           make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
  128.                install
  129.        
  130.        The lowercase prefix is used by the Gimp, the uppercase PREFIX is
  131.        used by perl.  Rarely you also want to specifiy manpage directories
  132.        etc.. you can also overwrite these (see "man ExtUtils::MakeMaker")
  133.        as well, e.g. for debian:
  134.  
  135.           make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
  136.                INSTALLMAN1DIR=`pwd`/debian/tmp/usr/man/man1 \
  137.                INSTALLMAN3DIR=`pwd`/debian/tmp/usr/man/man3 \
  138.                install
  139.  
  140.        PS: I'm not a debian developer/fan. If at all, I'd recommend
  141.        www.stampede.org (since they are using my compiler ;), but the
  142.        _best_ thing is DIY.
  143.  
  144. SUPPORT/MAILING LISTS/MORE INFO
  145.  
  146.        There is a mailinglist for general discussion about Gimp-Perl.  To
  147.        subscribe, send a mail with the single line
  148.  
  149.        subscribe
  150.        
  151.        to gimp-perl-request@lists.netcentral.net.
  152.  
  153.        If you want to get notified of new versions automatically, send a
  154.        mail with the single line:
  155.  
  156.        subscribe notify-gimp
  157.        
  158.        to majordomo@gcc.ml.org.
  159.        
  160.        You can also upload your scripts to the gimp registry at
  161.        http://registry.gimp.org/, part of it is dedicated to gimp-perl.
  162.  
  163. BLURB
  164.  
  165.        Scheme is the crappiest language ever. Have a look at Haskell
  166.        (http://www.haskell.org) to see how functional is done right.  I am
  167.        happy to receive opinions on both languages, don't hesitate to tell
  168.        me.
  169.  
  170. LICENSE
  171.  
  172.        The gimp-perl module is currently available under the GNU Public
  173.        License (see COPYING.GPL for details) and the Artistic License (see
  174.        COPYING.Artistic for details). Many of the scripts in the example
  175.        section follow these rules, but some of them have a different
  176.        licensing approach, please consult their source for more info.
  177.  
  178. THREATS
  179.  
  180.        Future versions of this package might be distributed under the
  181.        terms of the GPL only, to be consistent with the rest of the
  182.        Gimp. Andreas keeps me from doing this, though.
  183.  
  184.  
  185.        (c)1998,1999 Marc Lehmann <pcg@goof.com>
  186.  
  187. EXAMPLE PERL PLUG-IN
  188.  
  189.         To get even more look & feel, here is a complete plug-in source,
  190.         its the examples/example-fu.pl script from the distribution.
  191.  
  192. #!/usr/bin/perl
  193.  
  194. use Gimp;
  195. use Gimp::Fu;
  196.  
  197. register "gimp_fu_example_script",            # fill in a function name
  198.          "A non-working example of Gimp::Fu usage",    # and a short description,
  199.          "Just a starting point to derive new ".        # a (possibly multiline) help text
  200.             "scripts. Always remember to put a long".
  201.             "help message here!",
  202.          "Marc Lehmann",                # don't forget your name (author)
  203.          "(c) 1998, 1999 Marc Lehmann",            # and your copyright!
  204.          "19990316",                    # the date this script was written
  205.          "<Toolbox>/Xtns/Gimp::Fu Example",        # the menu path
  206.          "RGB*, GRAYA",                    # image types to accept (RGB, RGAB amnd GRAYA)
  207.          [
  208.          # argument type, switch name    , a short description        , default value, extra arguments
  209.           [PF_SLIDER    , "width"    , "The image width"        , 360, [300, 500]],
  210.           [PF_SPINNER    , "height"    , "The image height"        , 100, [100, 200]],
  211.           [PF_STRING    , "text"    , "The Message"            , "example text"],
  212.           [PF_INT    , "bordersize"    , "The bordersize"        , 10],
  213.           [PF_FLOAT    , "borderwidth"    , "The borderwidth"        , 1/5],
  214.           [PF_FONT    , "font"    , "The Font Family"        ],
  215.           [PF_COLOUR    , "text_colour"    , "The (foreground) text colour", [10,10,10]],
  216.           [PF_COLOUR    , "bg_colour"    , "The background colour"    , "#ff8000"],
  217.           [PF_TOGGLE    , "ignore_cols" , "Ignore colours"        , 0],
  218.           [PF_IMAGE    , "extra_image"    , "An additonal picture to ignore"],
  219.           [PF_DRAWABLE    , "extra_draw"    , "Somehting to ignroe as well"    ],
  220.           [PF_RADIO    , "type"    , "The effect type"        , 0, [small => 0, large => 1]],
  221.           [PF_BRUSH    , "a_brush"    , "An unused brush"        ],
  222.           [PF_PATTERN    , "a_pattern"    , "An unused pattern"        ],
  223.           [PF_GRADIENT    , "a_gradients"    , "An unused gradients"        ],
  224.          ],
  225.          sub {
  226.    
  227.    # now do sth. useful with the garbage we got ;)
  228.    my($width,$height,$text,$font,$fg,$bg,$ignore,$brush,$pattern,$gradient)=@_;
  229.    
  230.    # set tracing
  231.    Gimp::set_trace(TRACE_ALL);
  232.  
  233.    my $img=new Image($width,$height,RGB);
  234.    
  235.    # put an undo group around any modifications, so that
  236.    # they can be undone in one step. The eval shields against
  237.    # gimp-1.0, which does not have this function.
  238.    eval { $img->undo_push_group_start };
  239.    
  240.    my $l=new Layer($img,$width,$height,RGB,"Background",100,NORMAL_MODE);
  241.    $l->add_layer(0);
  242.  
  243.    # now a few syntax examples
  244.    
  245.    Palette->set_foreground($fg) unless $ignore;
  246.    Palette->set_background($bg) unless $ignore;
  247.    
  248.    fill $l BG_IMAGE_FILL;
  249.  
  250.    # the next function only works in gimp-1.1
  251.    $text_layer=$img->text_fontname(-1,10,10,$text,5,1,xlfd_size($font),$font);
  252.  
  253.    gimp_palette_set_foreground("green");
  254.    
  255.    # close the undo push group
  256.    eval { $img->undo_push_group_end };
  257.  
  258.    $img;    # return the image, or an empty list, i.e. ()
  259. };
  260.  
  261. exit main;
  262.  
  263.