"Fossies" - the Fresh Open Source Software Archive

Member "gimp-2.10.28/pdb/README" (14 Sep 2021, 4083 Bytes) of package /linux/misc/gimp-2.10.28.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Some mostly unfinished docs are here.
    2 
    3 -Yosh
    4 
    5 This document describes the tool PDBGEN.
    6 
    7 If you added or modified .pdb files do not run this tool manually but
    8 run make instead! It will call pdbgen.pl then to generate the files
    9 into the right output directories.
   10 
   11 PDBGEN
   12 ------------------
   13 
   14 What is this?
   15 PDBGEN is a tool to automate much of the drudge work of making PDB interfaces
   16 to GIMP internals. Right now, it generates PDB description records,
   17 argument marshallers (with sanity checking) for the app side, as well
   18 as libgimp wrappers for C plugins. It's written so that extending it
   19 to provide support for CORBA and other languages suited to static
   20 autogeneration.
   21 
   22 Invoking PDBGEN from the command line:
   23 1. Change into the ./pdb directory.
   24 2. $ ./pdbgen.pl DIRNAME
   25 where DIRNAME is either "lib" or "app", depending on which set of files
   26 you want to generate. The files are written into $destdir/app or $destdir/libgimp.
   27 $destdir is the environment variable destdir. If it's not set,
   28 then it's the ./pdb directory. Make sure the directories
   29 $destdir/app and $destdir/libgimp already exist and you have write permissions.
   30 Otherwise the code generator will fail and exit.
   31 It's up to you to diff the file you changed. When you're happy with
   32 the generated file, copy it into the actual ./app/ or ./libgimp/ directory
   33 where it finally gets built.
   34 
   35 Anatomy of a PDB descriptor:
   36 PDB descriptors are Perl code. You define a subroutine, which corresponds
   37 to the PDB function you want to create. You then fill certain special
   38 variables to fully describe all the information pdbgen needs to generate
   39 code. Since it's perl, you can do practically whatever perl lets you
   40 do to help you do this. However, at the simplest level, you don't need
   41 to know perl at all to make PDB descriptors.
   42 
   43 Annotated description:
   44 For example, we will look at gimp_display_new, specified in gdisplay.pdb.
   45 
   46 sub display_new { 
   47 
   48 We start with the name of our PDB function (not including the "gimp_" prefix).
   49 
   50     $blurb = 'Create a new display for the specified image.';
   51 
   52 This directly corresponds to the "blurb" field in the ProcRecord.
   53 
   54     $help = <<'HELP';
   55 Creates a new display for the specified image. If the image already has a
   56 display, another is added. Multiple displays are handled transparently by the
   57 GIMP. The newly created display is returned and can be subsequently destroyed
   58 with a call to 'gimp-display-delete'. This procedure only makes sense for use
   59 with the GIMP UI.
   60 HELP
   61 
   62 This is the help field. Notice because it is a long string, we used HERE
   63 document syntax to split it over multiple lines. Any extra whitespace
   64 in $blurb or $help, including newlines, is automatically stripped, so you
   65 don't have to worry about that.
   66 
   67     &std_pdb_misc;
   68 
   69 This is the "author", "copyright", and "date" fields. Since S&P are quite
   70 common, they get a special shortcut which fills these in for you. Stuff
   71 like this is defined in stddefs.pdb.
   72 
   73     @inargs = ( &std_image_arg );
   74 
   75 You specify arguments in a list. Again, your basic image is very common,
   76 so it gets a shortcut.
   77 
   78     @outargs = (
   79         { name => 'display', type => 'display',
   80           desc => 'The new display', alias => 'gdisp', init => 1 }
   81     );
   82 
   83 This is a real argument. It has a name, type, description at a minimum.
   84 "alias" lets you use the alias name in your invoker code, but the real
   85 name is still shown in the ProcRecord. This is useful not only as a
   86 shorthand, but for grabbing variables defined somewhere else (or constants),
   87 in conjunction with the "no_declare" flag. "init" simply says initialize
   88 this variable to a dummy value (in this case to placate gcc warnings)
   89 
   90     %invoke = (
   91         headers => [ qw("gdisplay.h") ],
   92 
   93 These are the headers needed for the functions you call.
   94 
   95         vars => [ 'guint scale = 0x101' ],
   96 
   97 Extra variables can be put here for your invoker.
   98 
   99         code => <<'CODE'
  100 {
  101   if (gimage->layers == NULL)
  102     success = FALSE;
  103   else
  104     success = ((gdisp = gdisplay_new (gimage, scale)) != NULL);
  105 }
  106 CODE
  107 
  108 The actual invoker code. Since it's a multiline block, we put curly braces
  109 in the beginning.
  110 
  111