From 5c1676dfe6d2f3c837a5e074117b45613fd29a72 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:30:19 +0200 Subject: Adding upstream version 2.10.34. Signed-off-by: Daniel Baumann --- pdb/README | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 pdb/README (limited to 'pdb/README') diff --git a/pdb/README b/pdb/README new file mode 100644 index 0000000..221deec --- /dev/null +++ b/pdb/README @@ -0,0 +1,111 @@ +Some mostly unfinished docs are here. + +-Yosh + +This document describes the tool PDBGEN. + +If you added or modified .pdb files do not run this tool manually but +run make instead! It will call pdbgen.pl then to generate the files +into the right output directories. + +PDBGEN +------------------ + +What is this? +PDBGEN is a tool to automate much of the drudge work of making PDB interfaces +to GIMP internals. Right now, it generates PDB description records, +argument marshallers (with sanity checking) for the app side, as well +as libgimp wrappers for C plugins. It's written so that extending it +to provide support for CORBA and other languages suited to static +autogeneration. + +Invoking PDBGEN from the command line: +1. Change into the ./pdb directory. +2. $ ./pdbgen.pl DIRNAME +where DIRNAME is either "lib" or "app", depending on which set of files +you want to generate. The files are written into $destdir/app or $destdir/libgimp. +$destdir is the environment variable destdir. If it's not set, +then it's the ./pdb directory. Make sure the directories +$destdir/app and $destdir/libgimp already exist and you have write permissions. +Otherwise the code generator will fail and exit. +It's up to you to diff the file you changed. When you're happy with +the generated file, copy it into the actual ./app/ or ./libgimp/ directory +where it finally gets built. + +Anatomy of a PDB descriptor: +PDB descriptors are Perl code. You define a subroutine, which corresponds +to the PDB function you want to create. You then fill certain special +variables to fully describe all the information pdbgen needs to generate +code. Since it's perl, you can do practically whatever perl lets you +do to help you do this. However, at the simplest level, you don't need +to know perl at all to make PDB descriptors. + +Annotated description: +For example, we will look at gimp_display_new, specified in gdisplay.pdb. + +sub display_new { + +We start with the name of our PDB function (not including the "gimp_" prefix). + + $blurb = 'Create a new display for the specified image.'; + +This directly corresponds to the "blurb" field in the ProcRecord. + + $help = <<'HELP'; +Creates a new display for the specified image. If the image already has a +display, another is added. Multiple displays are handled transparently by the +GIMP. The newly created display is returned and can be subsequently destroyed +with a call to 'gimp-display-delete'. This procedure only makes sense for use +with the GIMP UI. +HELP + +This is the help field. Notice because it is a long string, we used HERE +document syntax to split it over multiple lines. Any extra whitespace +in $blurb or $help, including newlines, is automatically stripped, so you +don't have to worry about that. + + &std_pdb_misc; + +This is the "author", "copyright", and "date" fields. Since S&P are quite +common, they get a special shortcut which fills these in for you. Stuff +like this is defined in stddefs.pdb. + + @inargs = ( &std_image_arg ); + +You specify arguments in a list. Again, your basic image is very common, +so it gets a shortcut. + + @outargs = ( + { name => 'display', type => 'display', + desc => 'The new display', alias => 'gdisp', init => 1 } + ); + +This is a real argument. It has a name, type, description at a minimum. +"alias" lets you use the alias name in your invoker code, but the real +name is still shown in the ProcRecord. This is useful not only as a +shorthand, but for grabbing variables defined somewhere else (or constants), +in conjunction with the "no_declare" flag. "init" simply says initialize +this variable to a dummy value (in this case to placate gcc warnings) + + %invoke = ( + headers => [ qw("gdisplay.h") ], + +These are the headers needed for the functions you call. + + vars => [ 'guint scale = 0x101' ], + +Extra variables can be put here for your invoker. + + code => <<'CODE' +{ + if (gimage->layers == NULL) + success = FALSE; + else + success = ((gdisp = gdisplay_new (gimage, scale)) != NULL); +} +CODE + +The actual invoker code. Since it's a multiline block, we put curly braces +in the beginning. + + -- cgit v1.2.3