Initial checkin of Pika from heckimp
This commit is contained in:
507
pdb/README_NEW_PDB_PROC
Normal file
507
pdb/README_NEW_PDB_PROC
Normal file
@ -0,0 +1,507 @@
|
||||
Creating new PDB procedures
|
||||
===========================
|
||||
Barak Itkin <lightningismyname@gmail.com>
|
||||
version 1.0, August 2010
|
||||
|
||||
////
|
||||
This document is an asciidoc document. It can be read as is, or you can
|
||||
print it as a formatted HTML page by running
|
||||
|
||||
asciidoc README_NEW_PDB_PROC
|
||||
|
||||
This will generate the file README_NEW_PDB_PROC.html.
|
||||
|
||||
Note that inline code parts are marked with + signs around them.
|
||||
////
|
||||
|
||||
This tutorial will show you the basics of creating a new procedure and
|
||||
adding it to PIKA's PDB.
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
What are PDB procedures?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A *PDB procedure* is a process which is registered in the Procedure
|
||||
Data-Base. Procedures registered in the database are available to all
|
||||
the PIKA plugins/scripts.
|
||||
|
||||
What should I want to add to the PDB?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Let's say a new feature was added to PIKA, and your plugin/script wants
|
||||
to use it. In order to do so, this function should be publicly available
|
||||
(most functions are only available to PIKA's core, and in order to
|
||||
expose them externally we have to add them to the PDB).
|
||||
|
||||
|
||||
Anything I should know before continuing this tutorial?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Yes. You should know
|
||||
https://en.wikipedia.org/wiki/C_%28programming_language%29[C Programming]
|
||||
(C is the language in which PIKA is coded), know a bit of
|
||||
https://library.gnome.org/devel/glib/stable/[Glib] (the library which
|
||||
PIKA uses for many of it's data-structures). In addition, you should
|
||||
know enough about the PIKA core for implementing your function (this is
|
||||
not a programming tutorial, this is only a technical tutorial) or at
|
||||
least have the intuition to understand enough from the code you see, to
|
||||
copy paste and modify the parts you need (In fact, this is how I made my
|
||||
first addition to the PDB :D However in most cases it's better to know
|
||||
what you are doing).
|
||||
|
||||
The basics of PDB procedures
|
||||
----------------------------
|
||||
|
||||
Since adding a function to the PDB can be tedious (you would need to
|
||||
modify 3 or more different source files), a scripting framework was
|
||||
developed to add functions to the PDB by writing them once. To see how
|
||||
function are implemented in the PDB, take a look in
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups[pdb/groups].
|
||||
|
||||
You can see many files with the .pdb suffix - these are special template
|
||||
files which include the actual source of the PDB functions. Let's take a
|
||||
quick look at one of these - text_layer_get_text in
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups/text_layer.pdb[pdb/groups/text_layer.pdb].
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
sub text_layer_get_text {
|
||||
$blurb = 'Get the text from a text layer as string.';
|
||||
|
||||
$help = <<'HELP';
|
||||
This procedure returns the text from a text layer as a string.
|
||||
HELP
|
||||
|
||||
&marcus_pdb_misc('2008', '2.6');
|
||||
|
||||
@inargs = (
|
||||
{ name => 'layer', type => 'layer',
|
||||
desc => 'The text layer' }
|
||||
);
|
||||
|
||||
@outargs = (
|
||||
{ name => 'text', type => 'string',
|
||||
desc => 'The text from the specified text layer.' }
|
||||
);
|
||||
|
||||
%invoke = (
|
||||
code => <<'CODE'
|
||||
{
|
||||
if (pika_pdb_layer_is_text_layer (layer, FALSE, error))
|
||||
{
|
||||
g_object_get (pika_text_layer_get_text (PIKA_TEXT_LAYER (layer)),
|
||||
"text", &text,
|
||||
NULL);
|
||||
}
|
||||
else
|
||||
{
|
||||
success = FALSE;
|
||||
}
|
||||
}
|
||||
CODE
|
||||
);
|
||||
}
|
||||
----
|
||||
|
||||
As you can see, all the function is wrapped inside the following wrapper:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
sub text_layer_get_text {
|
||||
...
|
||||
}
|
||||
----
|
||||
|
||||
That's the first line, declaring the name of the new PDB function (it
|
||||
will be renamed to +pika_text_layer_get_text+ automatically), and
|
||||
opening the braces for it's content.
|
||||
|
||||
Description of the procedure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
At the beginning of the PDB function, you'll find lines similar to these:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
$blurb = 'Get the text from a text layer as string.';
|
||||
|
||||
$help = <<'HELP';
|
||||
This procedure returns the text from a text layer as a string.
|
||||
HELP
|
||||
----
|
||||
|
||||
Every procedure has a blurb string and a help string. A blurb is a short
|
||||
string summarizing what the function does, and the help is a longer
|
||||
string in which you describe your function in more depth.
|
||||
|
||||
A one line string can be specified by simply putting it between braces
|
||||
(like the blurb string). A longer string, which can possibly spread over
|
||||
several lines, must be written in a special way:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
<<'HELP';
|
||||
This procedure returns the text from a text layer as a string.
|
||||
HELP
|
||||
----
|
||||
|
||||
The +<<'*HELP*'+ practically mean that the content of the string will be
|
||||
specified in the next lines and it will continue until reaching a line
|
||||
which has the content +HELP+ in it (without any spaces before/after it,
|
||||
and without anything else in that line).
|
||||
|
||||
Now, the next line is:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
&marcus_pdb_misc('2008', '2.6');
|
||||
----
|
||||
|
||||
If you contribute a function to the PIKA PDB, you credit yourself in the
|
||||
source code. The above line is for an author which contributed many
|
||||
functions and he now has a simple macro to credit him. For us regular
|
||||
users, if we want to specify the credit to ourself we should replace the
|
||||
above line with the following lines:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
$author = 'Elvis Presley <the_king@rock.com>';
|
||||
$copyright = 'Elvis Presley';
|
||||
$date = '2010';
|
||||
$since = '2.8';
|
||||
----
|
||||
|
||||
Replace the values of +$author+ and +$copyright+ with your own name and
|
||||
email, replace the value of +$date+ with the date in which you wrote the
|
||||
function (most functions only specify the year, so try to keep with this
|
||||
standard instead of adding a full date). And finally, replace the value
|
||||
of +$since+ with the version of PIKA which will be the first to include
|
||||
this function. For example, if PIKA 2.6 was released, and 2.8 wasn't
|
||||
released yet. then new functionality will be added in 2.8 (new
|
||||
functionality is only added inside new major version releases) and you
|
||||
should specify 2.8.
|
||||
|
||||
In and Out Arguments
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
After the header of the function which contains it's description, you'll
|
||||
find these lines:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@inargs = (
|
||||
{ name => 'layer', type => 'layer',
|
||||
desc => 'The text layer' }
|
||||
);
|
||||
|
||||
@outargs = (
|
||||
{ name => 'text', type => 'string',
|
||||
desc => 'The text from the specified text layer.' }
|
||||
);
|
||||
----
|
||||
|
||||
Here we specify the input arguments of this procedure, together with the
|
||||
returned arguments. As you can see, each argument has a name, a type and
|
||||
a description. The name will be used later in our code and it should be
|
||||
meaningful and be a valid name for a variable in C.
|
||||
|
||||
The type is one of the types listed in
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/pdb.pl[pdb/pdb.pl]
|
||||
inside the +%arg_types+ array. In
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/pdb.pl[pdb/pdb.pl]
|
||||
you can see the corresponding C type for each of the types we specify.
|
||||
For example, +layer+ type (inside the .pdb file) becomes a variable with
|
||||
the C type of +PikaLayer *+, and +string+ becomes +gchar *+.
|
||||
|
||||
If I want to add another input variable to the function, it'll look like this:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@inargs = (
|
||||
{ name => 'layer', type => 'layer',
|
||||
desc => 'The text layer' },
|
||||
{ name => 'temp', type => 'int32',
|
||||
desc => 'My silly number' }
|
||||
);
|
||||
|
||||
@outargs = (
|
||||
{ name => 'text', type => 'string',
|
||||
desc => 'The text from the specified text layer.' }
|
||||
);
|
||||
----
|
||||
|
||||
Don't forget to add comma between arguments!
|
||||
|
||||
The actual code
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
After specifying the arguments we will specify the actual code of the
|
||||
function inside the following wrapper:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
%invoke = (
|
||||
code => <<'CODE'
|
||||
|
||||
...
|
||||
|
||||
CODE
|
||||
);
|
||||
----
|
||||
|
||||
Now finally, let's take a look at the actual code:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
{
|
||||
if (pika_pdb_layer_is_text_layer (layer, FALSE, error))
|
||||
{
|
||||
g_object_get (pika_text_layer_get_text (PIKA_TEXT_LAYER (layer)),
|
||||
"text", &text,
|
||||
NULL);
|
||||
}
|
||||
else
|
||||
{
|
||||
success = FALSE;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
This is a simple code in C - nothing fancy. However, this code uses
|
||||
functions from inside PIKA's core (hacking on the PIKA core will be the
|
||||
content for a different guide). The variables +text+ and +layer+, inside
|
||||
the C code, correspond to the variables we specified in the input/output
|
||||
arguments (since they have exactly the same name):
|
||||
|
||||
[source,c]
|
||||
----
|
||||
@inargs = (
|
||||
{ name => 'layer', type => 'layer',
|
||||
desc => 'The text layer' }
|
||||
);
|
||||
|
||||
@outargs = (
|
||||
{ name => 'text', type => 'string',
|
||||
desc => 'The text from the specified text layer.' }
|
||||
);
|
||||
----
|
||||
|
||||
If for some reason, our function can fail (for example, in the code
|
||||
above the second line checks if the passed parameter is indeed a text
|
||||
layer and not just any layer) then we should add an indication that it
|
||||
failed by setting the variable +success+ to have the value +FALSE+.
|
||||
|
||||
Now, we need to do two more things to finish our function: add it to
|
||||
the function list, and configure the includes correctly.
|
||||
|
||||
Registering the function inside the PDB file
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
At the end of the PDB file, you should find the following segments:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@headers = qw("libpikabase/pikabase.h"
|
||||
"core/pikacontext.h"
|
||||
"text/pikatext.h"
|
||||
"text/pikatextlayer.h"
|
||||
"pikapdb-utils.h"
|
||||
"pikapdberror.h"
|
||||
"pika-intl.h");
|
||||
|
||||
@procs = qw(text_layer_new
|
||||
text_layer_get_text
|
||||
text_layer_set_text
|
||||
...
|
||||
);
|
||||
----
|
||||
|
||||
Inside the +@headers+ there is a list of various header files from the
|
||||
pika source. If your code requires a header which is not specified, add
|
||||
it there.
|
||||
|
||||
Inside the +@procs+ there is a list of the procedures which are exported
|
||||
by the file. *Make sure you add your procedure to the list!*
|
||||
|
||||
Advanced details
|
||||
----------------
|
||||
|
||||
enum arguments
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
In some cases you would like to have arguments which have a value from
|
||||
an enum (enumeration). Instead of just declaring these as integer values
|
||||
and telling in your description which value corresponds to which number,
|
||||
this can be done automatically for you if the desired enum is one of the
|
||||
enums which are already used by PIKA.
|
||||
|
||||
To make it clearer, let's take a look at +layer_get_mode+ in
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups/layer.pdb[pdb/groups/layer.pdb]:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@outargs = (
|
||||
{ name => 'mode', type => 'enum PikaLayerModeEffects',
|
||||
desc => 'The layer combination mode' }
|
||||
);
|
||||
----
|
||||
|
||||
If we take a look at the same procedure as it shows up in the procedure
|
||||
browser (+pika_layer_get_mode+), we will see the following return values:
|
||||
|
||||
[options="header",cols="1,1,11"]
|
||||
|=======================================================================
|
||||
|Name |Type |Description
|
||||
|mode |INT32 |
|
||||
The layer combination mode { NORMAL-MODE (0), DISSOLVE-MODE (1),
|
||||
BEHIND-MODE (2), MULTIPLY-MODE (3), SCREEN-MODE (4), OVERLAY-MODE (5),
|
||||
DIFFERENCE-MODE (6), ADDITION-MODE (7), SUBTRACT-MODE (8),
|
||||
DARKEN-ONLY-MODE (9), LIGHTEN-ONLY-MODE (10), HUE-MODE (11),
|
||||
SATURATION-MODE (12), COLOR-MODE (13), VALUE-MODE (14),
|
||||
DIVIDE-MODE (15), DODGE-MODE (16), BURN-MODE (17), HARDLIGHT-MODE (18),
|
||||
SOFTLIGHT-MODE (19), GRAIN-EXTRACT-MODE (20), GRAIN-MERGE-MODE (21),
|
||||
COLOR-ERASE-MODE (22), ERASE-MODE (23), REPLACE-MODE (24),
|
||||
ANTI-ERASE-MODE (25) }
|
||||
|=======================================================================
|
||||
|
||||
As you can see, all the values of the enum were listed (the source file
|
||||
containing this enum is
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/app/base/base-enums.h[app/base/base-enums.h])
|
||||
in it's description, and the type for this argument was declared as an
|
||||
integer value (reminder: enumeration values in C are actually mapped to
|
||||
numbers, unlike languages such as Java where enumeration values are
|
||||
indeed a new type in the language).
|
||||
|
||||
Limiting the range of numerical arguments
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In some cases you would like to limit the range of numerical values
|
||||
passed as parameters for your PDB function. For example, the width of
|
||||
newly created images should be limited to be at least 1 (since images
|
||||
with 0 width don't make sense...) and it also should be limited to some
|
||||
maximal width (so that it won't be bigger than the maximal size PIKA
|
||||
supports).
|
||||
|
||||
We can add this sort of range limitations inside the declaration of the
|
||||
function, and by that we can make sure it won't be called with values
|
||||
out of range (PIKA will make sure the values are inside the specified
|
||||
range before it calls our function). To see an example, let's take look
|
||||
at the procedure image_new from
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups/image.pdb[pdb/groups/image.pdb]:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@inargs = (
|
||||
{ name => 'width', type => '1 <= int32 <= PIKA_MAX_IMAGE_SIZE',
|
||||
desc => 'The width of the image' },
|
||||
{ name => 'height', type => '1 <= int32 <= PIKA_MAX_IMAGE_SIZE',
|
||||
desc => 'The height of the image' },
|
||||
{ name => 'type', type => 'enum PikaImageBaseType',
|
||||
desc => 'The type of image' }
|
||||
);
|
||||
----
|
||||
|
||||
As you can see, inside the +*type*+ field of the first two parameters,
|
||||
we added a limitation on the range of the parameter. The lower
|
||||
limitation is a simple number, and the upper limitation is a constant
|
||||
macro (+PIKA_MAX_IMAGE_SIZE+) defined in
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/libpikabase/pikalimits.h[libpikabase/pikalimits.h].
|
||||
In order to make sure this constand will indeed be defined when parsing
|
||||
this function, the file
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/libpikabase/pikabase.h[libpikabase/pikabase.h]
|
||||
(which includes
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/libpikabase/pikalimits.h[libpikabase/pikalimits.h])
|
||||
was added to the +@headers+ section of the pdb file.
|
||||
|
||||
Now, if you take a look at the code part of this function you won't see
|
||||
any check that the value is indeed inside the specified range. As we
|
||||
said, PIKA takes care of this automatically for us so we don't need to
|
||||
add the check ourselves. Inside the procedure browser, this procedure
|
||||
would show up like this:
|
||||
|
||||
[options="header",cols="1,1,11"]
|
||||
|=======================================================================
|
||||
|Name |Type |Description
|
||||
|width |INT32 |The width of the image (1 \<= width \<= 262144)
|
||||
|height |INT32 |The height of the image (1 \<= height \<= 262144)
|
||||
|type |INT32 |The type of image { RGB (0), GRAY (1), INDEXED (2) }
|
||||
|=======================================================================
|
||||
|
||||
Array arguments
|
||||
~~~~~~~~~~~~~~~
|
||||
In some cases you will want a function which returns an array or a
|
||||
function which receives an array. Array arguments are specified in a
|
||||
special way which is a bit different than the other arguments. To see
|
||||
how array arguments are specified, let's take a look at the +@outargs+
|
||||
of +vectors_stroke_get_points+ from
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups/vectors.pdb[pdb/groups/vectors.pdb]:
|
||||
|
||||
[source,perl]
|
||||
----
|
||||
@outargs = (
|
||||
{ name => 'type', type => 'enum PikaVectorsStrokeType',
|
||||
desc => 'type of the stroke (always PIKA_VECTORS_STROKE_TYPE_BEZIER for now).' },
|
||||
{ name => 'controlpoints', type => 'floatarray',
|
||||
desc => 'List of the control points for the stroke (x0, y0, x1, y1, ...).',
|
||||
array => { name => 'num_points',
|
||||
desc => 'The number of floats returned.' } },
|
||||
{ name => 'closed', type => 'boolean',
|
||||
desc => 'Whether the stroke is closed or not.' }
|
||||
);
|
||||
----
|
||||
|
||||
As you can see, the second argument which is of type +floatarray+ is
|
||||
specified in a different way than the other arguments; In addition to
|
||||
+name+, +type+ and +desc+, it also has an +*array*+ part. This part
|
||||
will declare another parameter for this function which will hold the
|
||||
length of the array (Reminder: in C you need the length of an array
|
||||
since unlike languages such as python, the length of an array isn't kept
|
||||
by default).
|
||||
|
||||
As a result of this declaration, two arguments will be created (in this
|
||||
order):
|
||||
|
||||
--
|
||||
. +*num_points*+ - a parameter of type +gint32+ which will hold the
|
||||
length of the array.
|
||||
. +*controlpoints*+ - a parameter of type +gdouble*+ which will point to
|
||||
the first element in the array.
|
||||
--
|
||||
|
||||
Like all the other arguments which are declared in the +@outargs+ and
|
||||
+@intargs+ parts, their name value will be the name of the variable in
|
||||
the code part. If you'll look at the code part of this function,
|
||||
you'll be able to find these lines:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
num_points = points_array->len;
|
||||
controlpoints = g_new (gdouble, num_points * 2);
|
||||
----
|
||||
As you can see from the code above, the +controlpoints+ argument starts
|
||||
just as a pointer to a double (array) - you have to do the allocation of
|
||||
the array yourself. However, if we would specify an array as an input
|
||||
argument, then the pointer will point to its beginning.
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
Hey! Now what - how do I see my function?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Compile PIKA again from the source, and pass the flag --with-pdbgen to
|
||||
the configure script (or to the autogen script if using the autogen
|
||||
script).
|
||||
|
||||
Conclusions
|
||||
~~~~~~~~~~~
|
||||
Now that you know how a PDB function looks like, you should be able to
|
||||
add new ones of your own if PIKA needs them (ask on the development list
|
||||
before working on a new function like this, since you need to see if the
|
||||
developers agree that it's needed!).
|
||||
|
||||
Don't forget to include the functions inside the right files! Under
|
||||
https://gitlab.gnome.org/GNOME/pika/tree/master/pdb/groups[pdb/groups]
|
||||
you can see many files (fonts.pdb, brush.pdb, layer.pdb, etc.) - *make
|
||||
sure you add your function in the place which logically suites it!*
|
||||
Reference in New Issue
Block a user
