1
pdp 0.13 design layers + components
2
-----------------------------------
4
from version 0.13 onwards, pdp is no longer just a pd plugin but a
5
standalone unix library (libpdp). this documents is an attempt to
6
describe the design layers.
11
on the top level, libpdp is interfaced to pd using a glue layer which
14
1. pdp/dpd protocols for pd
16
3. base classes for pdp/dpd
17
4. some small utility pd objects
18
5. pd specific interfaces to part of pdp core
20
7. pd object interface to packet forth (pdp object)
23
1. is the same as previous versions to ensure backwards compatibility in
24
pd with previous pdp modules and extensions that are written as pd
25
externs or external libs. this includes parts of pdp that are not yet
26
migrated to libpdp (some of them are very pd specific and will not be
27
moved to libpdp), and pidip. if you intend to write new modules, it is
28
encouraged to use the new forth based api, so your code can be part of
29
libpdp to use it in other image processing applications.
31
2. is considered a pd part. it implements multithreading of pdp inside
32
pd. multithreading is considered a host interface part, since it usually
33
requires special code.
35
3. the base classes (pd objects) for pdp image processing remain part of
36
the pd<->pdp layer. the reason is the same as 1. a lot of the original
37
pd style pdp is written as subclasses of the pdp_base, pdp_image_base,
38
dpd_base and pdp_3dp_base classes. if you need to write pd specific
39
code, it is still encouraged to use these apis, since they eliminate a
40
lot of red tape involving the pdp protocol. a disadvantage is that this
41
api is badly documented, and the basic api (1.) is a lot simpler to
42
learn and documented. 3dp is supposed to merge to the new forth api,
43
along with the image/video processing code.
45
4. is small enough to be ignored here
47
5. includes interfaces to thread system and type conversion system +
48
some pd specific stuff using 1. or 3.
50
6. the console interface to the pdp core, basicly a console for a
51
forth like language called packet forth which is pdp's main scripting
52
language. it's inteded for develloping and testing pdp but it can be
53
used to write controllers for pd/pdp/... too. this is based on 1.
55
7. is the main link between the new libpdp and pd. it is used to
56
instantiate pdp processors in pd which are written in the packet forth.
57
i.e. to create a mixer, you instantiate a [pdp mix] object, which would
58
be the same as the previous [pdp_mix] object. each [pdp] object creates
59
a forth environment, which is initialized by calling a forth init
60
method. [pdp mix] would call the forth word init_mix to create the local
61
environment for the mix object. wrappers will be included for backward
62
compatibility when the image processing code is moved to libpdp.
68
1. basic building blocks: symbol, list, memory manager
69
2. packet implementation (packet class and reuse queue)
70
3. packet type conversion system
71
4. os interface (X11, net, png, ...)
73
6. additional libraries
76
1. pdp makes intensive use of symbols and lists (trees, stacks, queues).
77
pdp's namespace is built on the symbol implementation. a lot of other
80
2. the pdp packet model is very simple. basicly nothing more than
81
constructors (new, copy, clone), destructors (mark_unused (for reuse
82
later), delete). there is no real object model for processors. this is a
83
conscious decision. processor objects are implemented as packet forth
84
processes with object state stored in process data space. this is enough
85
to interface the functionality present in packet forth code to any
86
arbitrary object oriented language or system.
88
3. each packet type can register conversion methods to other types. the
89
type conversion system does the casting. this is not completely finished
90
yet (no automatic multistage casting yet) but most of it is in place and
91
usable. no types without casts.
93
4. os specific modules for input/output. not much fun here..
95
5. All of pdp is glued together with a scripting language called packet
96
forth. This is a "high level" forth dialect that can operate on floats,
97
ints, symbols, lists, trees and packets. It is a "fool proof" forth,
98
which is polymorphic and relatively robust to user errors (read: it
99
should not crash or cause memory leaks when experimenting). It is
100
intended to serve as a packet level glue language, so it is not very
101
efficient for scalar code. This is usually not a problem, since packet
102
operations (esp. image processing) are much more expensive than a this
103
thin layer of glue connecting them.
105
All packet operations can be accessed in the forth. If you've ever
106
worked with HP's RPN calculators, you can use packet forth. The basic
107
idea is to write objects in packet forth that can be used in pd or in
108
other image processing applications. For more information on packet
109
forth, see the code (pdp_forth.h, pdp_forth.c and words.def)
111
6. opengl lib, based on dpd (3.) which will be moved to packet forth
112
words and the cellular automata lib, which will be moved to
113
vector/slice forth later.
119
All the packet processing code is (will be) exported as packet forth
120
words. This section is about how the code exported by those words is
123
C.1 IMAGE PROESSING: VECTOR FORTH
125
Eventually, image operations need to be implemented, and in order
126
to do this efficiently, both codewize (good modularity) as execution speed
127
wize, i've opted for another forth. DSP and forth seem to mix well, once
128
you get the risc pipeline issues out of the way. And, as a less rational
129
explanation, forth has this magic kind of feel, something like art..
132
As opposed to the packet forth, this is a "real" lowlevel forth
133
optimized for performance. Its reason of being is the solution of 3
134
problems: image processing code factoring, quasi optimal processor
135
pipeline & instruction usage, and locality of reference for maximum
136
cache performance. Expect crashes when you start experimenting with
137
this. It's really nothing more than a fancy macro assembler. It has no
138
safety belts. Chuck Moore doctrine..
140
The distinction between the two forths is at first sight not a good
141
example of minimizing glue layers. I.e. both systems (packet script
142
forth and low level slice forth) are forths in essence, requiring
143
(partial) design duplication. Both implementations are however
144
significantly different which justified this design duplication.
146
Apart from the implementation differences, the purpose of both languages
147
is not the same. This requires the designs of both languages to be
148
different in some respect. So, with the rule of "do everything right
149
once" in mind, this small remark tries to justify the fact that forth !=
152
The only place where apparent design correspondence (the language model)
153
is actually used is in the interface between the packet forth and the
156
The base forth is an ordinary minimal 32bit (or machine word
157
lenght) subroutine threaded forth, with a native code kernel for
158
i386/mmx, a portable c code kernel and room for more native code kernels
159
(i.e i386/sse/sse2/3dnow, altivec, dsp, ...) Besides support for native
160
machine words bit ints and pointers, no floats, since they clash with
161
mmx, are not needed for the fixed point image type, and can be
162
implemented using other vector instructions when needed), support for
163
slices and a separate "vector stack".
165
Vectors are the native machine vectors, i.e. 64bit for mmx/3dnow,
166
128bit for sse/sse2, or anything else. The architecture is supposed to
167
be open. (I've been thinking to add a block forth, operating on 256bit
168
blocks to eliminate pipeline issues). Blocks are just blocks of vectors
169
which are used as a basic loop unrolling data size grain for solving
170
pipeline operations in slice processing words.
172
Slices are just arrays of blocks. In the mmx forth kernel, they can
173
represent 4 scanlines or a 4 colour component scanline, depending on how
174
they are fed from packet data. Slices can be anything, but right now,
175
they're just scanlines. The forth kernel has a very simple and efficient
176
(branchless) reference count based memory allocator for slices. This
177
slice allocator is also stack based which ensures locality of reference:
178
a new allocated slice is the last deallocated slice.
180
The reason for this obsession with slices is that a lot of video
181
effects can be chained on the slice level (scanline or bunch of
182
scanlines), which improves speed through more locality of reference. In
183
concreto intermediates are not flushed to slower memory. The same
184
principles can be used to do audio dsp, but that's for later.
186
The mmx forth kernel is further factored down following another
187
virtual machine paradigm. After doing some profiling, i came to the
188
conclusion that the only, single paradigm way of writing efficient
189
vector code on today's machines is multiple accumulators to avoid
190
pipeline stalls. The nice thing about image processing is that it
191
parallellizes easily. Hence the slice/block thing. This leads to the
192
1-operand virtual machine concept for the mmx slice operations. The
193
basic data size is one 4x4 pixel block (16bit pixels), which is
194
implemented as asm macros in mmx-sliceops-macro.s and used in
195
mmx-sliceops-code.s to build slice operations. The slice operations are
196
built out of macro instructions for this 256bit or 512bit, 2 or 1
197
register virtual machine which has practically no pipeline delays
198
between its instructions.
200
Since the base of sliceforth is just another forth, it could be that
201
(part of) 3dp will be implemented in this lowlevel forth too, if
202
performance dictates it. It's probably simpler to do it in the lowlevel
203
forth than the packet forth anyway, in the form of cwords.
205
C.2: MATRIX PROCESSING: LIBGSL
207
All matrix processing packet forth words are (will be) basicly wrappers
208
around gsl library calls. Very straightforward.
212
The same goes for opengl. The difference here is that it uses the dpd
213
protocol in pdp, which is more like the Gem way of doing things. The
214
reason for this is that, although i've tried hard to avoid it, opengl
215
seems to dictate a drawing context based, instead of an object based way
216
of working. So processing is context (accumulator) based. Packet forth
217
will probably get some object oriented, or context oriented feel when
added
removed
doc/misc/layers.txt
