1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<title>PDP Developer Documentation</title>
8
<h1>PDP Developer Documentation</h1>
12
<p>There is not yet much developer information, partly because pdp is not that big and since the goals are
13
not completely clear yet, a lot will probably change on the inside in the future. I believe it is
14
not too hard to figure out how it works, once you get started somewhere. This document is a minimalistic
15
attempt to provide that starting point. For full prototypes see the header files. I suggest you have a look at the pdp_base base class, and some simple
16
modules: pdp_add, pdp_noise and pdp_gain for examples.
18
<h2> PDP architecture </h2>
19
<p> Architecture is a big word, but pdp is organized as modules. A packet pool module (a reuse pool memory manager),
20
a packet class, a processing queue module, a high level type conversion module, an image packet class, and some
21
low level modules for image type conversion, image resampling and all sorts of other image processing. Besides that
22
there are 2 extension libraries: pdp_scaf, a cellular automata extension and pdp_opengl, a 3d rendering extension.
23
These are separate because of portability issues. The different pdp_* externs in the main pdp library use the
24
core modules' functionality to minimize code duplication. I'm relatively happy with how it fits together,
25
but some things need to change for future plans. Most objects are written in the object oriented c style of pd.
26
To prevent namespace conflicts, (almost) all routines start with the pdp_ prefix. The second name is the name of the
27
object or module they belong to. The first argument is always a pointer to an object or an integer (for packets).
31
<p> PDP is written as an extension for PD. One of the goals of pdp is to evolve to a separate library that can
32
be reused in other software. The architecture will be split into two parts. A pd-independent part (the packet classes,
33
the packet pool, the type conversion system and the forth system) and a part with pd specific stuff (the process queue and interfaces to the
34
pd system like the base classes and the pd communication protocol). In order to do this the packet class will probably
35
evolve to a proper object model, supporting run time attribute binding (inspired by the python object model).
37
<p>There are some things that put a stamp on the current pdp design. Most importantly pd's processor object model and
38
communication protocol. (i.e. the fact that pd only supports unidirectional messaging creates the awkward concept
39
of a "passing packet" to eliminate excessive data copying.)
41
<p> In pd, the pdp messaging protocol is implemented as pd messages. The protocol is however 3 phase.
42
With a read only register phase, a read/write register phase and a process phase. This functionality
43
is part of the base class or the forth processor object. The dpd protocol is entirely different,
44
and is used in the opengl library. It is
45
not based on parallel dataflow but serial context passing.
48
<p> PDP introduces a new atom: the data packet. This can contain all kinds of data. Images (16bit/8bit), cellular
49
automata (1bit), matrices (real/complex float/double), opengl textures and 3d rendering contexts. Packets
50
are stored in a pool to ensure fast reuse, and to enable sharing. The paradigm is centered around a
51
combination of an object oriented approach and a dataflow approach.
52
<p>The methods operating on packets
53
(pdp_packet_*) are mainly for administrative purposes: memory management (construction, registering, copying)
54
and getting or setting info.
55
<p>All processing is done in the pd modules. Processors can be defined using
56
the forth scripting language, but this is still experimental. The forth system can be accessed
57
from the guile library.
58
<p> There is a central mechanism for packet type conversion. This is to facilitate the combination of different
59
media types. Whenever a packet class is constructed (i.e. in an extension library), a number of conversion
60
routines should be defined to convert the added type to one or some of the main pdp types.
67
<h2>PDP API Overview</h2>
69
The pdp public api contains only a single class: the packet. (The internal api has more classes, that can be used
70
too if necessary, but i won't document them.) A packet is a class in pdp. The table below lists the supported methods.
71
The first argument of a call is a packet id.
74
<TR><TH colspan = "2">pdp_packet_*
75
<TR><TD>new <TD>construct a raw packet (depreciated)
76
<TR><TD>new_* <TD>construct packet of specific type/subtype/...
77
<TR><TD>mark_unused <TD>release
78
<TR><TD>mark_passing <TD>conditional release (release on first copy ro/rw)
79
<TR><TD>copy_ro <TD>readonly (shared) copy
80
<TR><TD>copy_rw <TD>private copy
81
<TR><TD>clone_rw <TD>private copy (copies only meta data, not the content)
82
<TR><TD>header <TD>get the raw header (t_pdp *)
83
<TR><TD>data <TD>get the raw data (void *)
84
<TR><TD>pass_if_valid <TD>send a packet to pd outlet, if it is valid, and mark unused
85
<TR><TD>replace_if_valid <TD>delete packet and replace with new one, if new is valid
86
<TR><TD>copy_ro_or_drop <TD>copy readonly, or don't copy if dest slot is full + send drop notify
87
<TR><TD>copy_rw_or_drop <TD>same, but private copy
88
<TR><TD>get_description <TD>retrieve type info
89
<TR><TD>convert_ro <TD>same as copy_ro, but with an automatic conversion matching a type template
90
<TR><TD>convert_rw <TD>same as convert_ro, but producing a private copy
94
<p>The pool object methods. All the packets are stored in a central packet pool.
97
<TR><TH colspan = "2">pdp_pool_*
98
<TR><TD>collect_garbage <TD>manually free all unused resources in packet pool
101
<p>The process queue object methods. PDP supports a separate processing thread.
104
<TR><TH colspan = "2"> pdp_queue_*
105
<TR><TD>add <TD>add a process method + callback
106
<TR><TD>finish <TD>wait until a specific task is done
107
<TR><TD>wait <TD>wait until processing queue is done
110
<p>The control methods. General pdp control messages.
113
<TR><TH colspan = "2"> pdp_control_*
114
<TR><TD>notify_drop <TD>notify that a packet has been dropped
117
<p> The type mediator methods.
119
<TR><TH colspan = "2"> pdp_type_*
120
<TR><TD>description_match <TD>check if two type templates match
121
<TR><TD>register_conversion <TD>register a type conversion program
127
<p>NOTE: it is advised to derive your module from the pdp base class defined in pdp_base.h
128
instead of communicating directly with the pdp core
132
<h2>pdp_base class</h2>
133
If you want to write a pdp extern, you can derive it from the pdp_base class, instead of t_object.
134
This class abstracts a lot of the hassle of writing ordinary (inplace) packet processors. The base
135
allows you to register process callbacks. There are 3 kinds of callbacks: preproc, process and postproc.
136
The preproc method is called inside the pd thread. This can be used to setup some things that can only
137
be done inside the pd thread. The process method should do most of the work, and is called from the
138
pdp processing thread if it is enabled, after the preproc method is finished. You can't use most
139
of pd's calls in this method. The postproc method is called
140
from the pd thread after the process method is finished, and can be used to send data to pd outlets. Simple
141
packet processors only need the process method (packet input/output is handled by the pdp_base class).
143
<h2>pdp_imageproc_* modules</h2>
144
Most of the image processing code is organized as planar 16 bit signed processors.
145
This is crude and oversimplified, but it helps to keep the code size small and fast
146
at the same time (platform dependent assembly code is reduced to a bare minimum). These
147
routines can be used to build higher level image processing objects that are more (cache)
148
efficient than an abstraction using separate pdp modules. If you plan to write your own image
149
processing routines, you can use the pdp_imageproc_dispatch_ routine to support all 16bit image
150
types at once (greyscale, subsampled YCrCb, multichannel planar). This requires you write the
151
image processing routine as a planar (greyscale) processor using the pdp_imageproc_
152
interface. (see pdp_imageproc.h)
154
<h2>pdp_llconv call</h2>
155
Low level image conversion routines. (operating on raw data buffers). You probably won't need this,
156
since the high level type conversion (pdp_packet_convert_ro/rw) covers most of its functionality.
161
<address><a href="mailto:pdp@zzz.kotnet.org">Tom Schouten</a></address>
162
<!-- Created: Mon Apr 28 15:35:12 CEST 2003 -->
164
Last modified: Fri Sep 19 04:52:12 CEST 2003
added
removed
doc/misc/devdoc.html
