1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5
<TITLE>Pd Documentation 2</TITLE>
6
<meta http-equiv="Content-Type" content="text/html">
7
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen">
13
<H2>Pd Documentation chapter 2: theory of operation</H2>
16
<A href="index.htm#s2"> back to table of contents</A>
22
<P> The purpose of this chapter is to describe Pd's design and how it is
23
supposed to work. Practical details about how to obtain, install, and run Pd
24
are described in the next chapter. To learn digital audio processing basics
25
such as how to generate time-varying sounds that don't click or fold over, try
27
<A HREF="http://www.crca.ucsd.edu/~msp/techniques.htm"
28
<I> Theory and Techniques of Electronic Music </I></A>.
30
<H3> <A name=s1> 2.1 overview </A> </H3>
32
<P>Pd is a real-time graphical programming environment for audio and graphical
33
processing. It resembles the Max/MSP system but is much simpler and more
34
portable; also Pd has two features not (yet) showing up in Max/MSP: first,
35
via Mark Dank's GEM package, Pd can be used for simultaneous computer
36
animation and computer audio. Second, an experimental facility is provided
37
for defining and accessing data structures.
39
<H3> <A name=s1.1> 2.1.1. the main window, canvases, and printout </A> </H3>
41
<P>When Pd is running, you'll see a main "Pd" window, and possibly one or more
42
"canvases" or "patches". The main Pd window looks like this:
45
<IMG src="fig1.1.png" ALT="pd window">
48
<P> There are peak level and clip indicators for audio input and output; these
49
report peak levels over all input and all output channels. Note that DC
50
shows up as an input level; many cards have DC levels which show up in the
51
50s. To see an RMS audio level, select "test audio and MIDI" from the Media
52
menu. The main window display is intended only to help you avoid clipping
53
on input and output. You can turn the peak meters on and off using the
54
control at lower left.
56
<P> At lower right is a control to turn audio processing on and off
57
globally. Turning audio off stops the computation and relinquishes any audio
58
devices Pd is using. The "Media" menu is also provided, with accelerators
59
"Control-." to turn audio computation off and "Control-/" to turn it on. When
60
audio is on, Pd is computing audio samples in real time according to whatever
61
patches you have open (whether they are visible or not).
63
<P> The DIO (Digital I/O) error indicator flashes if there is a synchronization
64
error for audio input or output. (But note that on some platforms Pd doesn't
65
find out about them. If you never see red, you're probably not seeing the
67
Click the "DIO errors" button to see a list of recent errors.
68
This indicator should turn red whenever the
69
computation runs late (so that the DAC FIFOs fill and/or the ADC FIFOs empty)
70
or if audio input and output are not running at the same rate. See
71
<a href="x3.htm#s2"> audio and MIDI support </A>.
73
<P> The bottom part of the Pd window is an area for printout from objects in
74
patches, and/or for messages from Pd itself.
76
<P> Pd documents are called "patches" or "canvases."
77
Each open document has one main window and any number of
78
sub-windows. The sub-windows can be opened and closed but are always running
79
whether you can see them or not. Here is a simple Pd patch:
82
<IMG src="fig1.2.jpg" ALT="hello world patch">
85
<P>There are four <I> text boxes </I> in this patch: a number box (showing zero),
86
an object box showing "print," and two comments. The number box and the object
87
box are connected, the number box's output to the print box's input. Boxes may
88
have zero or more inputs and/or outputs, with the inputs on top and the outputs
92
Pd's printout appears on the main ``Pd" window,
93
unless you redirect it elsewhere.
95
<H3> <A name="s1.2"> 2.1.2. object boxes </A> </H3>
96
<P> Pd patches can have four types of boxes: <I> object, message, GUI, </I>
99
<P> You make <I> objects </I> by typing text into object boxes. The text is
100
divided into <I> atoms </I> separated by white space. The first atom specifies
101
what type of object Pd will make, and the other atoms, called <I> creation
102
arguments </I>, tell Pd how to initialize the object. If you type for example,
105
<IMG src="fig1.3.jpg" ALT="object">
108
<P>the "+" specifies the <I> class </I> of the object.
109
In this case the object will be the kind that carries out addition,
110
and the "13" initializes the amount to add.
112
<P> Atoms are either numbers or <I>
113
symbols </I> like "+". Anything that is not a valid number os considered a
114
symbol. Valid numbers may or may not have a decimal point (for instance, 12,
115
15.6, -.456), or may be
116
written in exponential notation (such as "4.5e6", which means "4.5 multiplied
117
by 10 six times, i.e., 4500000). Negative exponentials divide by 10 (so
118
that 1.23e-5 comes to 0.0000123).
120
<P> Non-valid numbers which are read as symbols
121
include things like "+5" and "0..6" as well as words and names such as "Zack"
122
or "cat". The symbols "gore", "Gore", and "GORE" are all distinct.
124
<P> The text you type into an object box determines how
125
many and what kinds of inlets and outlets the object will have. Some
126
classes (like "+" always have a fixed arrangement of inlets and outlets,
127
and in the case of other classes, the inlets and outlets will depend on the
130
<P>Here for example is a simple MIDI synthesizer:
133
<IMG src="fig1.4.png" ALT="simple MIDI synthesizer">
136
<P>This patch mixes <I> control </I> objects (notein, stripnote, and ftom) with
137
<I> tilde </I> objects osc~, *~, and dac~. The control objects carry out their
138
function sporadically, as a result of one or more type of <I> event </I>. In
139
this case, incoming MIDI note messages set off the control computation. The
140
result of the computation is, when the note happens to be a "note on" (and not
141
a "note off", to compute the frequency in cycles per second and pass it on to
142
the oscillator ("osc~").
144
<P> The second half of the patch, the osc~, *~, and dac~ objects, compute audio
145
samples, in the same way as an analog synthesizer works. The osc~ object is
146
acting as the interface between the two regimes, in that it takes control
147
messages to set its frequency but talks to "*~" using an audio signal. Audio
148
signals aren't sporadic; they are continuous streams of numbers. As a result
149
tilde objects act under very different rules from control objects. The audio
150
portion of the patch is always running, whether MIDI messages arrive or not. On
151
the other hand, the function of control computations is to insert calculations
152
between the audio computation which may change audio computation parameters
153
such as the frequency of an oscillator.
155
<P> The connections in the patch (the lines between the boxes) are also of two
156
types: control and signal. The type of connection depends on the outlet it
157
comes from. Signal connections are represented by thicker lines than control
158
connections; in the patch above, the two bottom conections are signal and the
159
others are control. In general, a control connection may be made to a signal
160
inlet; if numbers are sent over it they are automatially converted to
161
signals. Signal connections may not be made to control inlets; some sort
162
of explicit conversion must be specified.
164
<H3> <A name="s1.3"> 2.1.3. message and GUI boxes </A> </H3>
166
<P>The border of a box tells you how its text is interpreted and how the box
167
functions. Object boxes (as in the previous example) use the text to create
168
objects when you load a patch or type text onto a new one. If you retype the
169
text in an object box, the old one is discarded and a new one is created, using
170
the new creation arguments. The contents of an object box describe a message
171
which is sent to Pd to create the object.
173
<P> <I> Message </I> boxes interpret the text as a message to send whenever
174
the box is activated (by an incoming message or with the mouse.) The message
175
may be sent many times while the patch is running (as opposed to object boxes
176
whose message is used once to create the object). Instead of going straight
177
to Pd, the message box's message (or messages) go either to the box's outlet
178
or to other specified receiving objects. In the example
179
below, the message box, when clicked, sends the message "21" to an object
180
box which adds 13 to it.
183
<IMG src="fig1.5.jpg" ALT="[message( --> [object] -> [number]">
186
<P> The third box shown is a <I> GUI </I> ("graphical user interface") box. GUI
187
boxes come in many forms including number boxes (as in this example), toggles,
188
sliders, and so on. Whereas the appearance of an object or message box is
189
static when a patch is running, a number box's contents (the text) changes to
190
reflect the current value held by the box. You can also use a number box as a
191
control by clicking and dragging up and down, or by typing values in it.
192
(There are also shift- and alt-click actions; see <A href="x2.htm#s2.7">
193
getting help </A> to find out how to look this up).
195
<P> You can also create a "symbol" box which is like a number box but deals
196
in symbols like "cat." You can type your own strings in (followed by "enter")
197
or use it to display strings which arrive as messages to its inlet.
199
<H3> <A name="s1.4"> 2.1.4. patches and files </A> </H3>
201
<P>When you save a patch to a file, Pd doesn't save the entire state of all the
202
objects in the patch, but only what you see: the objects' creation arguments
203
and their interconnections. Certain data-storage objects have functions for
204
reading and writing other files to save and restore their internal state.
206
<P>Pd finds files using a <I> path </I> which can be specified as part of Pd's
207
startup arguments. The path specifies one or more directories, separated by
208
colons (semicolons if you're using windows.) Most objects which can read files
209
search for them along the search path, but when Pd writes files they go to
210
the directory where the patch was found.
212
<H3> <A name=s2> 2.2. editing Pd patches </A> </H3>
214
<H3> <A name=s2.1> 2.2.1. edit and run mode </A> </H3>
216
<P> A patch can be in edit or run mode; this really only affects how mouse
217
clicks affect the patch. In edit mode, clicking and dragging selects and
218
moves boxes or makes and cuts connections; in run mode clicking on boxes sends
219
them messages which they react to in different ways. In run mode, number and
220
message boxes can be used as controls. Normally, when you are in a performance
221
you will stay in run mode; to change the patch you go to edit mode.
223
<H3> <A name=s2.2> 2.2.2. creating boxes </A> </H3>
225
<P> You can create boxes (objects, messages, GUIs, and comments) using the
226
"put" menu. Note the handy accelerators. Object and message boxes are empty
227
at first; drag them where you want them and type in the text. The GUI
228
objects (which come in several flavors) require no typing; just create and
231
<P> You will often find it more convenient to select a box and "duplicate" it
232
(in the Edit menu) than to use the "Put" menu. If you select and duplicate
233
several items, any connections between them will be duplicated as well.
235
<H3> <A name=s2.3> 2.2.3. the selection </A> </H3>
237
<P>Boxes in a Pd window may be selected by clicking on them. To select more
238
than one object you may use shift-click or click on a blank portion of
239
the window and drag the cursor to select all objects within a rectangle.
241
<P>Clicking on an unselected object, message, or comment box makes the text
242
active, i.e., ready to be text edited. (If you select using the rectangle
243
method, the text isn't activated.) Once you've activated a text box, you
244
may type into it (replacing the selected text) or use the mouse to change the
247
<P> You may also select a single connection (patch cord) by clicking on it.
248
You can't have connections and boxes selected simultaneously.
250
<H3> <A name=s2.4> 2.2.4. deleting, cutting, and pasting </A> </H3>
252
<P>If you select a box, a connection, or several boxes, and if you haven't made
253
any text active, you can "delete" the selection by hitting the backspace or
254
delete key. You can also "cut" "copy" and "paste" using menu items. Notice
255
that pasting puts the new object(s) right down on top of the old ones.
257
<P>The "duplicate" menu item performs a copy and paste with a small offset so you
258
can see the new boxes. You can drag them together to a new place on the screen.
260
<P>You can cut and paste between windows within Pd but cut/paste isn't
261
integrated with the OS in any way. Cut/copy/paste for activated text in boxes
262
isn't implemented yet, although in Linux and Irix at least you can "X-paste"
263
into and out of "text" dialogs (created with the "edit text" menu item.)
265
<H3> <A name=s2.5> 2.2.5. changing the text </A> </H3>
267
<P> To change a text item, you can select it and then edit the text. If you
268
only click once, the entire text is selected and your typing will replace
269
everything. Click again and drag to select a portion of the text to retype.
272
more than a small amount of text (in a comment, for example) you might want to
273
select the text and choose "text editor" from the Edit menu, which opens a text
274
editing window with a copy of the text in it. Hitting "send" in that window is
275
exactly equivalent to retyping the text into Pd; you can send it to more than
276
one box in sequence if you want.
278
<P> If you click a box and move the mouse without releasing the button this
279
displaces the entire box. If you wish to displace a box which is already
280
selected, first de-select the box by clicking outside it; otherwise you will be
281
selecting text instead of moving the box.
283
<P> <I> The updated text only becomes part of the patch when you de-select the
284
object. </I> Changing the text in an "object" box deletes the old
285
object and creates a new one; the internal state of the old one is lost.
287
<H3> <A name=s2.6> 2.2.6. connecting and disconnecting boxes </A> </H3>
289
<P>To make a connection between two boxes, click on any outlet of the first
290
one, drag toward an inlet of the second one, and release. You can
291
release the mouse button anywhere within the target object and the connection
292
will be made to the nearest inlet.
294
<P>Connections are broken by selecting them and using "cut" or the backspace
297
<H3> <A name=s2.7> 2.2.7. popup menu for properties, open, and help </A> </H3>
299
<P> All the "clicking" mentioned above is done with the left mouse button.
300
The right button, instead, gives a popup menu offering "properties," "open,"
302
(For Macintosh users who may only have one button on their mouse,
303
double-clicking is mapped to right-click.)
305
<P> Selecting "help" on an object gets
306
a Pd patch that demonstrates how to use it. "Help" for the canvas as a whole
307
(right-clicking outside any object) gives a list of all built-in objects.
309
<P> The "open" menu item is only enabled if you right-click on a subpatch
310
(see below) and causes Pd to open it. Ordinary subpatches may also be opened
311
by clicking on them, but for "graph-on-parent" ones, this is the only way to
314
<P> The "properties" dialog allows you to change certain settings of GUI
315
objects, or of the patch itself (by clicking outside any box.)
317
<H3> <A name=s2.7> 2.2.8. miscellaneous </A> </H3>
319
<P> Control-q "quits" Pd, but asks you to comfirm the quit. To quit without
320
having to confirm, use command-shift-Q.
322
<H3> <A name="s3"> 2.3. messages </A> </H3>
324
<P> In Pd, objects intercommunicate by sending messages and/or audio signals.
325
Pd messages are sporadic, like MIDI messages or music N "Note cards."
327
<H3> <A name="s3.1"> 2.3.1. anatomy of a message </A> </H3>
329
<P>Messages contain a selector followed by
330
any number of arguments. The selector is a symbol, which appears in the patch
331
as a non-numeric string with no white space, semicolons, or commas. The
332
arguments may be symbols or numbers. Numbers in Pd are kept in 32-bit floating
333
point, so that they can represent integers exactly between -8388608 and
334
8388608. (In Max, there are separate data types for integers and floating
335
point numbers; Pd uses only float.)
337
<P> When a message is passed to something (which is often an inlet of a box
338
but could be anything that can receive a message), the selector of the message
339
is checked against the receiver. If the receiver recognizes messages of that
340
selector, it carries out some corresponding action. For instance, here is a
344
<IMG src="fig3.1.jpg" ALT="float object">
347
<P> The two rectangles at the top are usually both called "inlets" but
348
the one at the left directs incoming messages to the "float" object itself,
349
whereas the one at the right directs messages to an auxiliary "inlet"
350
object. The float object proper (represented by the left-hand inlet) accepts
351
messages with selector "float" and "bang". The right-hand inlet takes only
352
the message selector "float". These two selectors, along with "symbol" and
353
"list", are usually used to denote an object's main action, whatever it may be,
354
so that objects can be interconnected with maximum flexibility.
356
<P> It is possible to type messages which start with a number,
357
which cannot be used as a selector. A single number is always given the
358
"float" selector automatically, and a message with a number followed by other
359
arguments is given the selector "list".
361
<H3> <A name="s3.2"> 2.3.2. depth first message passing </A> </H3>
363
<P> In Pd whenever a message is initiated, the receiver may then send out
364
further messages in turn, and the receivers of those messages can send yet
365
others. So each message sets off a tree of consequent messages. This tree is
366
executed in depth first fashion. For instance in the patch below:
369
<IMG src="fig3.2.jpg" ALT="depth first message passing">
372
<P> the order of arrival of messages is either A-B-C-D or A-C-D-B. The "C"
373
message is not done until the "D" one is also, and the "A" is not done until
374
all four are. It is indeterminate which of "B" or "C" is done first; this
375
depends on what order you made the connections in (in Max, it's automatically
376
sorted right to left).
378
<P> Message-passing can give rise to infinite loops of the sort shown here:
381
<IMG src="fig3.3.jpg" ALT="infinite message passing loop">
384
<P> Here the left-hand "+" can't finish processing until the right-hand one has
385
been sent the result "2", which can't finish processing that until the
386
left-hand one has been sent "3", and so on. Pd will print an error message
387
reporting a "stack overflow" if this happens.
389
<P> However, it is legal to make a loop if there is a "delay" object somewhere
390
in it. When the "delay" receives a message it schedules a message for the
391
future (even if the time delay is 0) and is then "finished;" Pd's internal
392
scheduler will wake the delay back up later.
395
2.3.3. hot and cold inlets and right to left outlet order </A> </H3>
397
<P> With few exceptions (notably "timer"), objects treat their leftmost
398
inlet as "hot" in the sense that messages to left inlets can result in output
399
messages. So the following is a legal (and reasonable) loop construct:
402
<IMG src="fig3.4.jpg" ALT="hot and cold inlets">
405
<P>Here the "f" is an abbreviation for "float". Note that the "+ 1" output is
406
connected to the right-hand inlet of "f". This "cold" inlet merely stores the
407
value for the next time the "f" is sent the "bang" message.
409
<P>It is frequently desirable to send messages to two or more inlets of an object
410
to specify its action. For instance, you can use "+" to add two numbers; but
411
to do it correctly you must make sure the right hand inlet gets its value
412
first. Otherwise, when the left hand side value comes in, "+" will carry out
413
the addition (since the left hand inlet is the "hot" one) and will add this
414
value to whatever was previously sitting in the right hand inlet.
416
<P> Problems can arise when a single outlet is connected (either directly or
417
through arbitrarily long chains of message passing) to different inlets of a
418
single object. In this case it is indeterminate which order the two inlets will
419
receive their messages. Suppose for example you wish to use "+" to double a
420
number. The following is incorrect:
423
<IMG src="fig3.5.jpg" ALT="incorrect inlet connection">
426
<P> Here, I connected the left inlet before connecting the right hand one (although
427
this is not evident in the appearance of the patch.) The "+" thus adds the
428
new input (at left) to the previous input (at right).
430
<P> The "trigger" object, abbreviated "t", can be used to split out connections
431
from a single outlet in a determinate order. By convention, all objects in Pd,
432
when sending messages out more than one outlet, do so from right to left. If
433
you connect these to inlets of a second object without crossing wires, the
434
second object will get its leftmost inlet last, which is usually what you
435
want. Here is how to use "trigger" to disambiguate the previous example:
438
<IMG src="fig3.6.jpg" ALT="trigger to disambiguate">
441
<P> "Cold" (non-leftmost) inlets are almost universally used to store single
442
values (either numbers or symbols.) With the exception of "line" and "line~",
443
these values are "sticky," i.e., once you set the value it is good until the
444
next time you set it. (The "line" exception is for sanity's sake.)
446
<P> One more question sometimes comes up in execution order, which is
447
the order in which two messages are sent to a single "cold" inlet. In this
448
situation, since the messages are merged, the last value to be received is
449
the value that is used in the computation.
451
<H3> <A name="s3.4"> 2.3.4. message boxes </A> </H3>
453
Message boxes are text boxes in which you type a message. When the message
454
box is activated, either by clicking on it or sending something to its inlet,
455
the message or messages are sent, either to the message box's outlet or
456
elsewhere as specified.
459
<IMG src="fig3.7.jpg" ALT="message boxes">
462
<P>The first of the message boxes above contains the single number 1.5; this
463
message has an implicit selector of "float." The second is a list with three
464
numbers in it, and in the third, the selector is "my" and the two arguments are
465
the number 5 and the symbol "toes."
467
<P> Multiple messages may be separated by commas as shown:
470
<IMG src="fig3.8.jpg" ALT="multiple messages in one box">
473
<P>Here the three messages are the numbers 1, 2, and 3, and they are sent in
474
sequence (with no intervening time between them, as with the "trigger" object,
475
and having depth-first consequences so that whatever chain of actions depending
476
on "1" takes place before anything depending on "2" and so on.)
478
<P> Semicolons may also separate messages. A message following a semicolon must
479
specify a symbol giving a destination (in other words, semicolons are like
480
commas except that they clear the "current destination"
481
so that the next message specifies a new one). The "current destination" is
482
at first the message box's own outlet. In the example below, the leading
483
semicolon immediately redirects messages from the outlet to an object named
484
"fred" (which is here a receive object), and likewise the next message is sent
489
<IMG src="fig3.9.jpg" ALT="semicolons to send messages">
492
<P>Certain other objects (Pd windows, for example, and arrays) have Pd names and
493
can be sent messages this way. Also, the special object "pd" is defined to
494
which you may send messages to start and stop DSP.
496
<P> You can put variables in message boxes as shown below:
499
<IMG src="fig3.10.jpg" ALT="variables in message boxes">
502
<P>Here, "$1", etc., refer to the arguments of the arriving message (and aren't
503
defined if you send a "bang" message or if you click on the message box to
504
activate it.) Dollar sign variables are either numbers or symbols depending
505
on the incoming message; if symbols, you may even use them to specify variable
506
message selectors or destinations.
508
<H3> <A name="s4"> 2.4. audio signals </A> </H3>
511
Using Pd you can build audio patches which can synthesize musical sounds,
512
analyze incoming sounds, process incoming sounds to produce transformed
513
audio outputs, or integrate audio processing with other media. This section
514
describes how Pd treats audio signals.
516
<H3> <A name="s4.1"> 2.4.1. sample rate and format </A> </H3>
519
Pd's audio signals are internally kept as 32-bit floating point numbers, so
520
you have all the dynamic range you could want. However, depending on your
521
hardware, audio I/O is usually limited to 16 or 24 bits. Inputs all appear
522
between the values of -1 and 1; and output values will be clipped to that range.
523
Pd assumes a sample rate of 44100 unless you override this (
524
in Pd's command line or in the "audio setup" dialog).
527
Pd can read or write samples to files either in 16-bit or 24-bit fixed point
528
or in 32-bit floating point, in WAV, AIFF, or AU format, via the soundfiler,
529
readsf, and writesf objects.
531
<H3> <A name="s4.2"> 2.4.2. tilde objects and audio connections </A> </H3>
533
<P>Audio computations in Pd are carried out by "tilde objects" such as "osc~"
534
whose names conventionally end in a tilde character to warn you what they
535
are. Tilde objects can intercommunicate via audio connections. When audio
536
computation is turned on, or when you change the audio network while audio is
537
on, Pd sorts all the tilde objects into a linear order for running; then this
538
linear list is run down in blocks of 64 samples each; at 44100 Hz. this means
539
the audio network runs every 1.45 milliseconds.
541
<P> Inlets or outlets are configured in Pd either for messages or audio; it's
542
an error to connect an audio outlet to a non-audio inlet or vice versa; usually
543
these errors are detected at "sort time" when audio is started or the network
544
changed with audio running. An object's leftmost inlet may accept both audio
545
and messages; any other inlet is either one or the other.
548
The audio network, that is, the tilde objects and their interconnections,
549
must be acyclic. If there are loops, you will see the error message at "sort
550
time." When errors are reported at sort time there is no easy way to
551
find the source of the error. You can build algorithms with feedback using
552
nonlocal signal connections.
555
Your subpatches can have audio inlets and outlets via the inlet~ and outlet~
558
<H3> <A name=s4.3> 2.4.3. converting audio to and from messages </A> </H3>
560
<P> If you want to use a control value as a signal, you can use the sig~ object
561
to convert it. The +~, -~, *~, /~, osc~, and phasor~ objects can be configured
562
to take control or signal inputs.
564
<P> The other direction, signal to control, requires that you specify at what
565
moments you want the signal sampled. This is handled by the snapshot~ object,
566
but you can also sample a signal with tabwrite~ and then get access it via
567
tabread or tabread4 (note the missing tildes!). There are also analysis
568
objects, the simplest of which is "env~", the envelope follower.
570
<H3> <A name=s4.4> 2.4.4. switching and blocking </A> </H3>
572
<P>You can use the switch~ or block~ objects to turn portions of your audio
573
computation on and off and to control the block size of computation. There
574
may be only one switch~ or block~ object in any window; it acts on the entire
575
window and all of its subwindows, which may still have their own nested
576
switch~/block~ objects. Switch~ and block~ take a block size and an overlap
577
factor as arguments; so for instance, "block~ 1024 4" specifies 1024 sample
578
blocks, overlapped by a factor of 4 relative to the parent window. Switch~
579
carries a small computational overhead in addition to whatever overhead is
580
associated with changing the block size.
582
<P> Larger block sizes than 64 should result in small increases in run-time
583
efficiency. Also, the fft~ and related objects operate on blocks so that
584
setting the block size also sets the number of FFT channels. You may wish
585
to use block sizes smaller than 64 to gain finer resolutions of message/audio
586
interaction, or to reduce "block delay" in feedback algorithms. At the
587
(untested) extreme, setting the block size to one allows you to write your
588
own recursive filters.
590
<P> You can use switch~ to budget your DSP computations; for instance you might
591
want to be able to switch between two synthesis algorithms. To do this, put
592
each algorithm in its own subpatch (which can have sub-sub patches in turn, for
593
a voice bank for instance), and switch each one off as you switch the other one
594
on. Beware of clicks; if you have a line~ controlling output level, give it
595
time to ramp to zero before you switch it off or it will be stuck at a nonzero
596
value for the next time it comes back on.
598
<P> When a subpatch is switched off its audio outputs generate zeros; this
599
costs a fairly small overhead; a cheaper way to get outputs is to use throw~
600
inside the switched module and catch~ outside it.
602
<H3> <A name=s4.5> 2.4.5. nonlocal signal connections </A> </H3>
604
<P>You may wish to pass signals non-locally, either to get from one window to another, or
605
to feed a signal back to your algorithm's input. This can be done using
606
throw~/catch~, send~/receive~, or delwrite~/delread~ pairs. Throw~ and catch~
607
implement a summing bus; throw~ adds into the bus and catch~ reads out the
608
accumulated signal and zeros the bus for the next time around. There can be
609
many throw~ objects associated with a single catch~, but a throw~ can't talk to
610
more than one catch~. You can reset the destination of a throw~ if you want to.
612
<P> Send~ just saves a signal which may then be receive~d any number of times; but
613
a receive~ can only pick up one send~ at a time (but you can switch between
616
<P> Don't try to throw~ and catch~ or send~ and receive~ between windows with
617
different block sizes. The only re-blocking mechanisms which are well tested
618
are inlet~ and outlet~.
620
<P> When you send a signal to a point that is earlier in the sorted list of tilde
621
objects, the signal doesn't get there until the next cycle of DSP computation,
622
one block later; so your signal will be delayed by one block (1.45 msec by
623
default.) Delread~ and delwrite~ have this same restriction, but here the 1.45
624
msec figure gives the minimum attainable delay. For nonrecursive algorithms, a
625
simple flanger for example, you might wish to ensure that your delread~ is
626
sorted after your delwrite~. The only way to ensure this is to create the
627
delread~ after you created the delwrite~; if things get out of whack, just
628
delete and re-create the delread~.
630
<H3> <A name=s5> 2.5. scheduling </A> </H3>
632
<P>Pd uses 64-bit floating point numbers to represent time, providing sample
633
accuracy and essentially never overflowing. Time appears to the user
636
<H3> <A name=s5.1> 2.5.1. audio and messages </A> </H3>
638
<P>Audio and message processing are interleaved in Pd. Audio processing is
639
scheduled every 64 samples at Pd's sample rate; at 44100 Hz. this gives a
640
period of 1.45 milliseconds. You may turn DSP computation on and off by
641
sending the "pd" object the messages "dsp 1" and "dsp 0."
643
<P> In the intervals between, delays might time out or external conditions
644
might arise (incoming MIDI, mouse clicks, or whatnot). These may cause a
645
cascade of depth-first message passing; each such message cascade is completely
646
run out before the next message or DSP tick is computed. Messages are never
647
passed to objects during a DSP tick; the ticks are atomic and parameter changes
648
sent to different objects in any given message cascade take effect
651
<P> In the middle of a message cascade you may schedule another one at a delay
652
of zero. This delayed cascade happens after the present cascade has finished,
653
but at the same logical time.
655
<H3> <A name=s5.2> 2.5.2. computation load </A> </H3>
657
<P> The Pd scheduler maintains a (user-specified) lead on its computations;
658
that is, it tries to keep ahead of real time by a small amount in order to be
659
able to absorb unpredictable, momentary increases in computation time. This
660
is specified using the "audiobuffer" or "frags" command line flags (see <a
661
href="x3.htm" name=s3>getting Pd to run </A>).
663
<P> If Pd gets late with respect to real time, gaps (either occasional or
664
frequent) will appear in both the input and output audio streams. On the
665
other hand, disk streaming objects will work correctly, so that you may use
666
Pd as a batch program with soundfile input and/or output. The "-nogui"
667
and "-send" startup flags are provided to aid in doing this.
669
<P> Pd's "realtime" computations compete for CPU time with its own GUI, which
670
runs as a separate process. A flow control mechanism will be provided someday
671
to prevent this from causing trouble, but it is in any case wise to avoid
672
having too much drawing going on while Pd is trying to make sound. If a
673
sub-window is closed, Pd suspends sending the GUI update messages for it;
674
but not so for miniaturized windows as of version 0.32. You should really
675
close them when you aren't using them.
677
<H3> <A name=s5.3> 2.5.3. determinism </A> </H3>
679
<P>All message cascades that are scheduled (via "delay" and
680
its relatives) to happen before a given audio tick will happen as scheduled
681
regardless of whether Pd as a whole is running on time; in other words,
682
calculation is never reordered for any real-time considerations. This is done
683
in order to make Pd's operation deterministic.
685
<P> If a message cascade is started by an external event, a time tag is given
686
it. These time tags are guaranteed to be consistent with the times at which
687
timeouts are scheduled and DSP ticks are computed; i.e., time never decreases.
688
(However, either Pd or a hardware driver may lie about the physical time an
689
input arrives; this depends on the operating system.) "Timer" objects which
690
measure time intervals measure them in terms of the logical time stamps of the
691
message cascades, so that timing a "delay" object always gives exactly the
692
theoretical value. (There is, however, a "realtime" object that measures real
693
time, with nondeterministic results.)
695
<P> If two message cascades are scheduled for the same logical time, they are
696
carried out in the order they were scheduled.
698
<H3> <A name=s6> 2.6. semantics </A> </H3>
700
This section describes how objects in Pd are created, how they store data and
701
how object and other boxes pass messages among themselves.
703
<H3> <A name=s6.1> 2.6.1. creation of objects </A> </H3>
705
The text in a box has a different function depending on whether it is a message,
706
atom (number/symbol), or object box. In message boxes the text specifies the
707
message or messages it will send as output. In atom boxes the text changes
708
at run time to show the state of the box, which is either a number or a symbol.
710
<P> In an object box, as in a message box, the text specifies a message; but
711
here the message is to be passed to Pd itself, once, and the
712
message's effect is to create the object in question. When you open a file,
713
all the objects created are created using their text as "creation messages."
714
If you type a new message into an object box (or change it), the old object is
715
destroyed and the message is used to create the new one.
717
<P> The selector of the message (the first word in the message) is a selector
718
which Pd interprets to mean which type of object to create. Any message
719
arguments (called "creation arguments") are used to parameterize the object
720
being created. Thus in "makenote 64 250" the selector "makenote" determines
721
the class of object to create and the creation arguments 64 and 250 become the
722
initial velocity and duration.
724
<H3> <A name=s6.2> 2.6.2. persistence of data </A> </H3>
726
Among the design principles of Pd is that patches should be printable, in the
727
sense that the appearance of a patch should fully determine its functionality.
728
For this reason, if messages received by an object change its action, since the
729
changes aren't reflected in the object's appearance, they are not saved as part
730
of the file which specifies the patch and will be forgotten when the patch is
731
reloaded. In the same way, if you delete and then recreate an object the
732
original object's state is not retained but is instead reinitialized (possibly
733
as specified by creation arguments.)
735
<P> An exception is made for subpatches whose "state" is the configuration of
736
the subpatch; as a special case, this configuration is restored when the
737
patch is read from a file. Also, if you rename the subpatch, for instance
738
typing "pd jane" instead of "pd spot," the contents of the patch are preserved
739
and only the text in the object box and the window title of the subpatch are
742
<P> It is probably bad style to specify creation arguments ala "makenote 64 250"
743
if you are going to override them later; this is confusing to anyone who tries
744
to understand the patch.
746
<H3> <A name=s6.3> 2.6.3. message passing </A> </H3>
748
Messages in Pd consist of a selector (a symbol) and zero or more arguments
749
(which may be symbols or numbers). To pass a message to an object, Pd first
750
checks the selector against the class of the object. Message boxes all are
751
of one class and they all take the same incoming messages and dispense them
752
according to their state, that is, the text typed into the box. The same
753
holds for atom boxes (number or symbol) except that their state may change
754
(it consists of the number or symbol showing).
756
<P> Object boxes may have many different classes. The class is usually
757
determined by the selector of the creation message, i.e., the first atom of the
758
creation message which is usually a symbol.
760
<P> Each class comes with a fixed collection of messages it may be sent. For
761
example, the "float" or "f" object takes "bang" and "float." These messages
762
are sent to "float" objects (objects whose class is float) via the leftmost,
763
hot inlet. (The right inlet is a separate, auxiliary object.) Objects of
764
class "float" respond to the message "bang" by outputting their current value,
765
that is, by sending a "float" message to their outlet. They respond to "float"
766
messages by setting their value and then outputting it.
768
<P> Each other class (like "float") in Pd has its own protocol for responding
769
to messages it is sent, and may take "float" and "bang" messages, or others
770
in addition or instead of them.
772
<H3> <A name=s6.4> 2.6.4. inlets and lists </A> </H3>
774
The leftmost connection point at the top of most objects represents the object
775
itself. Any other dark rectangle is a separate object called an "inlet"
776
although in Pd there are 4 individual inlet classes. The class of the inlet
777
determines which messages it will take: symbol, float, or other; and the inlet
778
forwards the message either to the object proper or to some proxy, usually
779
one that the object creates for the occasion.
781
<P> Unless they arrange otherwise by defining a "list" method, objects respond
782
to the "list" message by distributing the arguments of the message to their
783
inlets, except for the first argument which is passed as a "float" or
784
"symbol" message to the object proper.
786
<H3> <A name=s6.5> 2.6.5. dollar signs </A> </H3>
788
In message or object boxes, message arguments starting with a dollar sign
789
and a number (like "$1" or "$3-bazoo") are variables which are substituted
790
with values supplied as part of the environment the message is passed in.
791
In the case of message boxes, the environment consists of the arguments of
792
the "list" message (possibly extrapolated from "bang," "float,"
793
or other) that the message box is responding to. Thus, if a message box gets
794
"23 skidoo" and if it contains the text, "$2 until $1," out comes the message,
797
<P> Object boxes contain text which forms a message to be sent to Pd to create
798
and initialize the object. Here, $1, etc., are taken from the context in which
799
the patch was loaded. When the patch is a new document or opened from a file
800
the "$" variables are undefined. But if the patch is an abstraction (see the
801
next section) they are
802
taken from the abstractions' creation arguments.
804
<P> Constructions such as "$1-x" are expanded by string concatenation. This
805
is the mechanism for making local variables. In particular, $0 in an abstraction
806
is a counter which is guaranteed to be unique to that abstraction, so sends and
807
receives with names like "$0-bear" can be used as local send/receive pairs.
809
<P> Note that the expansion of variables such as $0 and $1 only works at the
810
beginning of the symbol; so, for instance, "rats-$1" will not be expanded.
811
Occasionally you may want to have double or triple substitutions; this can
812
be done one stage at a time by nesting abstractions (with each subpatch
813
adding its own $-variable to the beginning of a symbol and passing that on
814
as argument to a further abstraction.)
816
<P> For example, if you want to get dog-food, dog-ears, and cat-food, for
817
example, have an abstraction "a1" that invokes an abstraction "a2" twice, as
818
"a2 $1-food" and "a2 $1-ears", and then in a third patch call a1 twice, as
819
"a1 cat" and "a1 dog". Inside the four "a2" copioes, $1 will evaluate to
820
"dog-food", "cat-food", "dog-ears", and "cat-ears".
822
<H3> <A name="s7"> 2.7. subpatches </A> </H3>
824
Pd offers two mechanisms for making subpatches, called "one-off subpatches"
825
and "abstractions." In either case the subpatch appears as an object box
826
in a patch. If you type "pd" or "pd my-name" into an object box, this creates
827
a one-off subpatch. For instance, in this fragment:
829
<CENTER><P> <IMG src="fig7.1.jpg" ALT="subpatch"> </P></CENTER>
831
the box in the middle, if clicked on, opens the sub-patch shown here:
833
<CENTER><P> <IMG src="fig7.2.jpg" ALT="open subpatch window"> </P></CENTER>
835
<P> The contents of the subpatch are saved as part of the parent patch, in
836
one file. If you make several copies of a subpatch you may change them
839
<P> The objects, "inlet,", "inlet~," "outlet," and "outlet~,", when put in a
840
subpatch, create inlets and outlets for the object box containing the subpatch.
841
This works equally for one-off subpatches and abstractions. The inlet~ and
842
outlet~ versions create inlets and outlets for audio signals. You can't mix
843
messages and audio in a subpatch inlet or outlet; they must be one or the other
844
exclusively. Inlets and outlets appear on the invoking box in the same left-to-right
845
order as they appear in the subpatch.
847
<H3> <A name="s7.1"> 2.7.1. abstractions </A> </H3>
849
<P> To make an abstraction, save a patch with a name such as "abstraction1.pd"
850
and then invoke it as "abstraction1" in an object box:
852
<CENTER><P> <IMG src="fig7.3.jpg" ALT="abstraction"> </P></CENTER>
854
<P> Here we're invoking a separate file, "abstraction1.pd", which holds the
855
patch shown here (the border is the same as for the subpatch above):
857
<CENTER><P> <IMG src="fig7.4.jpg" ALT="abstraction example"> </P></CENTER>
859
You may create many instances of "abstraction1" or invoke it from several
860
different patches; and changing the contents of "abstraction1" will affect all
861
invocations of it as they are created. An analogy from the "c" programming
862
language is that one-off subpatches are like bracketed blocks of code and
863
abstractions are like subroutines.
865
<P> Abstractions are instantiated by typing the name of a patch (minus the ".pd"
866
extension) into an object box. You may also type arguments; for instance if
867
you have a file "my-abstraction.pd" you may type "my-abstraction 5" to set the
868
variable $1 to 5. This is defined only for object boxes (not for messages) in
869
the abstraction. (For message boxes, "$1", etc, have a different meaning as
870
described above.) If you want to send a message with a $1 in the sense of a
871
creation argument of an abstraction, you must generate it with an object box
872
such as "float $1", "symbol $1", or perhaps "pack $1 $2", which may then be
873
sent to a message box.
875
<P> The corresponding feature in Max (both Opcode and Ircam) was the "#1"
876
construct. In a Max abstraction, "#1", etc., are replaced by the creation
877
argument. This has the disadvantage that you can't edit the abstraction as
878
instantiated in the patch since the "#" variables are substituted. In Pd the
879
"$" variables in object boxes are spelled literally as "$" variables so that
880
it's meaningful to edit them from within their calling patch. On the Pd side,
881
however, there is the disadvantage that it's confusing to have "$" expanded at
882
a different time in an object box than in a message box. In an object box, the
883
"$" argument is expanded at creation time, and in a message box, at message
886
<H3> <A name="s7.2"> 2.7.2. Graph-on-parent subpatches </A> </H3>
888
If you open the "properties" dialog for a subpatch or an abstraction, you can
889
check the "graph on parent" box to have the controls of the subpatch/abstraction
890
appear on the parent. For instance, here is an invocation of "abstraction2":
892
<CENTER><P> <IMG src="fig7.5.jpg" ALT="graph-on-parent abstraction"> </P></CENTER>
894
where the patch "abstraction2.pd" contains:
896
<CENTER><P> <IMG src="fig7.6.jpg" ALT="inside graph-on-parent abstraction"> </P></CENTER>
898
Here, the number box in the abstraction shows up on the box that invoked
899
the abstraction. The "graph on parent" flag is set in the abstraction
900
(and is saved as part of the abstraction); to set it, open the "properties"
901
dialog for the "abstraction2" canvas by right-clicking on any white space
904
<P> To open the subpatch, right click on the object and select "open". (On
905
Macintoshes without a 2-button mouse, you can double-click in edit mode
906
instead.) It doesn't work just to click on the object in run mode since clicks
907
are sent to visible controls and/or arrays.
909
<P> When the sub-patch is closed, all controls in it appear on the object
910
instead; so the number box in the sub-patch in the example above is the same
911
one as you see in the box. Only controls are made visible in this way
913
<H3> <A name=s8> 2.8. numeric arrays </A> </H3>
915
Linear arrays of numbers recur throughout the computer musician's bag of tricks,
916
beginning with the wavetable oscillator. The wavetable oscillator later was
917
reinvented as the looping sampler. Also, table lookup is used for nonlinear
918
distortion of audio signals. In the domain of control, arrays of numbers
919
can specify control mappings, probability densities, voicing data, and much
922
<P> Arrays in Pd should be allocated (and possible read in from a file) before
923
beginning to make sound, since memory allocation and disk operations may take
924
long enough to cause audio buffer overruns or underruns. Pd provides two ways
925
to define new arrays, as "graphs" and "tables". In either case the array
926
has a pre-defined name and size (i.e., number of points). Elements of the
927
array are stored as floating-point numbers, 4 bytes apiece
929
<P> If you use an array to store a one-second sound at 44.1 kHz you will need
930
176 kilobytes, or a one-minute sound, 10.6 megabytes. To store a sound with
931
two or more channels, use a separate array for each channel.
933
<P> Arrays are also useful as transfer functions, for example for nonlinear
934
distortion of an audio signal, or to map a control onto a synthesis parameter.
935
In situations like this one typically uses much shorter arrays, of no more
936
than a few hundred elements. They are also useful for storing measured
937
spectra derived from the fft~ objects, and probably for many other uses.
939
<P> Arrays usually appear within subpatches created to house them, whether
940
in "graph on parent" form (so that you see them within a rectangle drawn on
941
the containing patch), or as a regular subpatch (which you see as a text box.)
942
In the "graph on parent" form, an array appears as shown:
944
<CENTER><P> <IMG src="fig8.1.jpg" ALT="array"> </P></CENTER>
946
<P> Arrays are indexed from 0 to N-1 where N is the number of points in the
947
array. You can read an array value using the tabread object:
949
<CENTER><P> <IMG src="fig8.2.jpg" ALT="array indexing"> </P></CENTER>
951
Here we see that the third point of the array (index 2) has the value 0.4.
952
To write into the array you can use the tabwrite object:
954
<CENTER><P> <IMG src="fig8.3.jpg" ALT="setting an value in an array"> </P></CENTER>
956
In this example, sending the message sets the third element to 0.5. (You
957
may also send the two numbers to the two inlets separately.)
959
<P> The two previous examples showed control operations to read and write from
960
and to arrays. These may also be done using audio signals. For example,
961
the patch below creates a 440 Hz. tone with "array1" as a waveform:
963
<CENTER><P> <IMG src="fig8.4.jpg" ALT="setting an array with a waveform"> </P></CENTER>
965
Here phasor~'s outputs a sawtooth wave, repeating 440 times per second, whose
966
output range is from 0 to 1. The multiplier and adder adjust the range from
967
1 to 11, and then the values are used as indices for tabread4~, which is a
968
4-point interpolating table lookup module. (Much more detail is available in
969
the audio example patches in the "pure documentation" series.)
971
<P> To create a new array, select "array" from the "put" menu. Up will come
972
a dialog window to set initial properties of the array. By default, a
973
new graph is created to hold the array, but it may also be housed in the
974
most recently created graph instead. Other properties may be specified there
975
and/or changed later using the "properties" dialog.
977
<P> If you select "properties" on an array in a graph, you two dialogs, one
978
for the array and one for the graph. The array dialog looks like this:
980
<CENTER><P> <IMG src="fig8.5.jpg" ALT="array properties window"> </P></CENTER>
982
You may use this to change the name and size, in addition to another property,
983
"save contents". If "save contents" is selected, the array's values are stored
984
in the containing patch; otherwise they're initialized to zero each time the
985
patch is reloaded. If you intend to use arrays to store sounds, you will
986
probably not wish to store them in the patch but as separate soundfiles. This
987
will be more efficient, and you may also then use a sound editor to modify them
990
<P> If you check "delete me" and then "OK", the array will be deleted. This is
991
an odd interface for deleting an object, and is only provided because Pd
992
lacks a mechanism for selecting arrays (so that "cut" could serve).
994
<P> The graph dialog (which also pops up) is shown here:
996
<CENTER><P> <IMG src="fig8.6.jpg" ALT="graph properties"> </P></CENTER>
998
<P> The X bounds initially range from 0 to the number of points in the table
999
minus one (this is a good choice for arrays, although graphs holding other
1000
kinds of objects might require other X bounds.) The Y bounds should be
1001
chosen to reflect the natural range of the table, so that stored sounds
1002
would naturally range from -1 to 1, but a sequence of frequency values might
1003
range from 0 to 20,000. Finally, you choose the screen size of the graph,
1004
width and height, in screen pixels.
1006
<P> Many other operations are defined for arrays; see the related patches
1007
in the tutorial (starting at 2.control/15.array.pd) for more possibilities.
1009
<H3> <A name=s9> 2.9. Data structures </A> </H3>
1010
(Note: this section is adapted from an article submitted to ICMC 2002.)
1012
<P> The original idea in developing Pd was to make a real-time computer music
1013
performance environment like Max, but somehow to include also a facility for
1014
making computer music scores with user-specifiable graphical representations.
1015
This idea has important precedents in Eric Lindemann's Animal and Bill Buxton's
1016
SSSP. An even earlier class of precedents lies in the rich variety of paper
1017
scores for electronic music before it became practical to offer a
1018
computer-based score editor. In this context, scores by Stockhausen (<I>
1019
Kontakte</I> and <I> Studie II</I>) and Yuasa (<I>Toward the Midnight Sun</I>)
1020
come most prominently to mind, but also Xenakis's <I>Mycenae-alpha</I>, which,
1021
although it was realized using a computer, was scored on paper and only
1022
afterward laboriously transcribed into the computer.
1024
<P> Pd is designed to to offer an extremely unstructured environment for
1025
describing data structures and their graphical appearance. The underlying
1026
idea is to allow the user to display any kind of data he or she wants to,
1027
associating it in any way with the display. To accomplish this Pd introduces
1028
a graphical data structure, somewhat like a data structure out of the C
1029
programming language, but with a facility for attaching shapes and colors to
1030
the data, so that the user can visualize and/or edit it. The data itself can
1031
be edited from scratch or can be imported from files, generated
1032
algorithmically, or derived from analyses of incoming sounds or other data
1036
example of a very short musical sketch realized using Pd:
1038
<CENTER><P> <IMG src="fig9.1.jpg" ALT="graphical score"> </P></CENTER>
1040
The example, which only lasts a few seconds, is a polyphonic collection of
1041
time-varying noise bands. The graphical ``score" consists of six objects, each
1042
having a small grab point at left, a black shape to show dynamic, and a colored
1043
shape to show changing frequency and bandwidth. The horizontal axis represents
1044
time and the vertical axis, frequency (although, as explained later, this
1045
behavior isn't built into pd). The dynamic and frequency shapes aren't
1046
constrained to be connected or even to be proximate, but since they pertain to
1047
the same sound their horizontal positions line up. In this example the last
1048
(furthest-right) object is percussive (as seen by the black shape) and has a
1049
fixed frequency and bandwidth, whereas the large, articulated shape in the
1050
center has a complicated trajectory in both frequency and dynamic. The color
1051
of the frequency trace determines the voice number used to realize it.
1053
<P> Each object is thus composed of a combination of scalar values (color;
1054
aggregate position in X and Y coordinates) and array values (time/value
1055
pairs for the black traces and time/frequency/bandwidth triples for the
1056
colored ones.) This is all specified by the user using Pd's ``template"
1059
<P> Here is the template associated with the graphical objects
1062
<CENTER><P> <IMG src="fig9.2.jpg" ALT="template for graphical score"> </P></CENTER>
1064
Templates consist of a data structure definition (the "struct" object) and
1065
zero or more drawing instructions ("filledpolygon" and "plot"). The "struct"
1066
object gives the template the name, "template-toplevel." The data structure
1067
is defined to contain three floating point numbers named "x", "y", and
1068
"voiceno," and two arrays, one named "pitch" whose elements belong to another
1069
template named "template-pitch," and similarly for the array "amp."
1071
<P> In general, data structures are built from four data types: scalar floats
1072
and symbols, arrays (whose elements share another, specified template) and
1073
lists (whose elements may have a variety of templates). The contents of a Pd
1074
window themselves form a list. Pd's correlate of Max's "table" object is
1075
implemented as a top-level array whose elements are scalars containing a single
1076
floating-point number.
1078
<P> Data structures in Pd may nest arbitrarily deeply using the array and list
1079
types. For example, a collection of sinusoidal tracks from an analysis engine
1080
could be implemented as an array of arrays of (pitch, amplitude)
1081
pairs; this appears as example 12 in Pd's FFT object online tutorial.
1083
<P> After the "struct" object in the template shown above, the remaining
1084
three objects are <I> drawing instructions </I> , first for a rectangle
1085
("filledpolygon"), and then for two arrays. The various graphical
1086
attributes that are specified for drawing instructions may be numerical
1087
constants or data structure field names; in the latter case the value varies
1088
depending on the data. For instance, the second creation argument to
1089
"plot" is the color. The first "plot" plots the "amp" field and the
1090
color is given as 0, or black. The second one plots "pitch" using the color
1091
"voiceno". In this way the color of the second trace is attached to the
1092
"voiceno" slot in the data structure, so that color will vary according to its
1095
<H3> <A name="s9.1"> 2.9.1. Traversal </A> </H3>
1097
<P> Pd objects are provided to traverse lists and arrays, and to address
1098
elements of data structures for getting and setting. Here is a patch showing
1099
how these facilities could be used, for example, to sequence the graphical
1102
<CENTER><P> <IMG src="fig9.3.jpg" ALT="traversal example patch"> </P></CENTER>
1104
<P> Pd has no built-in sequencer, nor even any notion that "x" values should be
1105
used as a time axis. (However, a "sort" function is provided, which reorders
1106
a list from left to right, on the assumption that users might often want to use Pd
1107
data collections as x-ordered sequences.) Recording sequences of events into
1108
lists, and/or playing the lists back as sequences, are functionalities that the
1109
user is expected to supply on top of Pd's offerings, which, it is hoped, would
1110
allow those functionalities within a much larger range of possibilities, to
1111
include random re-orderings of events, score following, self-modifying scores,
1112
reactive improvisation, and perhaps much more.
1114
<P> Traversal of data is made possible by adding a new type of atom, "pointer",
1115
to the two previously defined types that make up messages, to wit, numbers and
1116
symbols. Unlike numbers and symbols, pointers have no printed form and thus
1117
can't be uttered in message boxes. Traversal objects such as "pointer" and
1118
"get" (among several others) can generate or use pointers. The pointer data
1119
type is also integrated into pipe-fitting objects such as "pack",
1123
<P> In the patch shown above, the topmost "pointer" object holds a pointer to
1124
the next object to "play" (by sending it to one of the "voice"
1125
abstractions at bottom.) The pointer object takes a "traverse" message to
1126
set it to the head of the list (named "pd-data"), and "next" messages to
1127
move to (and output) the next datum in the list (i.e., the next in the list of
1128
six objects in the score). Another "pointer" object is also used, further
1129
down, as a storage cell for pointers just as "float" is for numbers.
1131
<P> The center of any sequencer is always the "delay" object, which must be
1132
fed the time difference between each event (including the non-event of hitting
1133
"start") and the next. As we extract each of the six objects in the score, we
1134
must wait the delay for playing that object, and then send its pointer to one
1135
of the "voice" abstractions to play it. However, we have to inspect the
1136
object itself to know the delay before playing it. So, in the loop, we peel off
1137
the first remaining object to play and inspect the time difference between it
1138
and the previous one, using this value to set the delay, but also storing the
1139
pointer in the lower "pointer" and "pack" objects.
1141
<P> The time difference needed to set the delay object is obtained using the
1142
"get template-toplevel x" object. (This is converted to incremental time
1143
("-"), corrected for tempo, and fed to the delay.) Pd provides
1145
objects for reading and writing values from data structures.
1146
The two "get" objects shown here obtain the "x" and "voiceno" fields
1147
of the current object. The template name (template-toplevel) is supplied
1148
to the "get" objects so that they can look up the offset of the necessary
1149
field(s) in advance, for greater run-time efficiency.
1151
<P> Once the delay has expired, the object's pointer is recalled (the lower
1152
"pointer" object), and the voice number is recalled. This is packed with
1153
the pointer itself and routed, so that the pointer goes to the appropriate
1154
voice. The voice number is shown as the color of the frequency trace in
1155
"999" units (first digit red, second green, third blue) and the "route" is
1156
arbitrarily set up to select among the six primary and secondary colors plus
1159
<P> The details of extracting the pitch and dynamic breakpoints from the arrays
1160
defined in the template are managed in the "voice" abstraction.
1162
abstraction receives a
1163
pointer to a given object and manages the sequencing of the arrays; so it
1164
contains two sequencers itself. The nesting of the overall structure of
1165
the sequencer patch mirrors the nesting of the original data structures.
1166
Finally, the voice abstraction puts its audio output on a summing bus.
1168
<P> More general patches can easily be constructed which access heterogeneous lists
1169
of objects (having different templates). In this way, an arbitrarily rich
1170
personal "score language" can be developed and sequenced.
1172
<H3> <A name=s9.2> 2.9.2. Accessing and changing data </A> </H3>
1174
<P> In general, accessing or changing data is done via "pointers" to
1175
"scalars". Numbers and symbols within scalars are accessed using the
1176
"get" object and changed, in the same way, using "set". Since lists
1177
and arrays are composed of scalars, every actual number or symbol in a data
1178
heap will be a number or symbol element of some scalar. To access them, it
1179
suffices to have objects to chase down elements of lists and arrays (given
1180
either a global name or a pointer to the containing scalar).
1182
<P> Lists are traversed in the way shown above; to get to a sublist of a scalar,
1183
the "get" object will provide a pointer, in the same way as it provides
1184
"float" or "symbol" elements of scalars. For arrays, an
1185
"element" object is provided which, given a scalar, a field name and
1186
a number, chases down the numbered, scalar, element of the named array field.
1188
<P> To alter "float" or "symbol" elements of scalars is straightforward
1189
using the "set" object, but arrays and lists can't be set by assignment;
1190
there is no suitable data type available within messages. Lists could
1191
possibly be "settable" by passing pointers to other lists, but permitting this
1192
would have required either automatically doing deep copies of data structures
1193
to carry out the assignments, or else implementing a garbage collecting memory
1194
management system, either of which would be difficult to realize within
1195
real-time computation time constraints. Instead, all the data hanging from a
1196
scalar is considered as belonging to that scalar, and is left in memory until
1197
the scalar is deleted; the data may be changed atom by atom, but primitives
1198
are not provided which would imply unpredictable execution times.
1200
<P> The "getsize" and "setsize" objects are provided to access or change
1201
the number of elements in the array. For lists, an "append" object
1202
appends a new scalar for a given template to a list, after the element pointed
1203
to. (To insert a scalar at the beginning of a list, the pointer can be set to
1204
the "head" of the list, a formal location before the first list item.)
1205
Deletion is less flexible; the only operation is to delete an entire list.
1206
(There's no reason not to provide finer-grain deletion mechanisms except that
1207
it's not clear how to protect against stale pointers efficiently, except by
1208
voiding the entire collection of pointers into a list.)
1210
<H3> <A name=s9.3> 2.9.3. Editing </A> </H3>
1212
<P> The graphical score shown above can be edited by dragging breakpoints, or
1213
by adding and deleting them, using mouse clicks. Also, entire objects or
1214
collections of them may be copied, pasted, and dragged around the screen.
1215
Alternatively, there is an editable (or computer generate-able or parse-able)
1216
text representation for the data, which may be seen or changed in a dialog
1217
window or read and written to external text files.
1219
<P> Since the graphical presentation of data objects is determined by drawing
1220
instructions, the drawing instructions are interpreted backwards to alter data
1221
as a result of mouse operations. If a given graphical dimension is controlled
1222
by a variable, that variable is then controlled by dragging along that
1223
dimension; if the dimension is constant, it can't be altered by dragging.
1225
<P> Tricky situations can arise when the user changes the contents of templates.
1226
A change in drawing instructions can be accommodated by simply tracking
1227
down and redrawing all data objects using the template. However, changing
1228
the "struct" object itself make for less straightforward situations. The
1229
user might wish to reorder fields, delete them, add new ones, or rename them.
1230
When a "struct" object changes, Pd automatically conforms the data from the old
1231
structure to the new one. Fields with the same name as previously are maintained
1232
(reordering them as necessary); and if a field disappears but another of the
1233
same type appears, the new one(s) are taken to be renamings of the old one(s)
1234
in order of appearance. New fields which cannot be matched in this way with
1235
previously existing ones are assumed to be new and are initialized.
1237
<P> It can happen that two "struct" objects compete to define the same data
1238
structure, or that the user reads in data from a file which expects a different
1239
version of the structure, or alternatively, that the "struct" object for
1240
existing data objects disappears. For this reason, Pd maintains a private
1241
representation of the last active version of a "struct" until all
1242
similarly named "structs," as well as all data using that "struct", have
1243
disappeared. If the user introduces a new version of the "struct" and only
1244
later deletes the "current" one, the data is only conformed to the new version
1245
once the old one is deleted. In this way we avoid getting into situations
1246
where data is left hanging without its structure definition, or where data ends
1247
up belonging to two or more structures of the same name. The worst that can
1248
happen is that data may lose their drawing instructions, in which case Pd
1249
supplies a simple default shape.
1251
<H3> <A name=s9.4> 2.9.4. Limitations </A> </H3>
1253
<P> When examples get more complicated and/or dense than the one shown here, it
1254
becomes difficult to see and select specific features of a data collection;
1255
more work is needed to facilitate this.
1256
There should be some facility for turning drawing instructions on and off, or
1257
perhaps for switching between versions of a template, depending on the user's
1258
desired view. There should also be a callback facility in the template for
1259
when an object is edited with the mouse, so that the user can bind actions to
1262
<P> More generally, the collection of traversal objects that Pd provides is
1263
adequate to support a variety of modes of data collection and use, such as
1264
analysis and sequencing. But the patches required to traverse the data
1265
collections are not always simple. It would be desirable to find a more
1266
straightforward mechanism than that provided by the "pointer", "get"
1269
<P> The "data" facility, although part of the original plan for Pd, has only
1270
recently been implemented in its current form, and as (hopefully) the user base
1271
grows there will surely be occasions for many further extensions of the data
1272
handling primitives and the graphical presentation and editing functions.
added
removed
doc/1.manual/x2.htm
