Debian Codegraph @

doc/1.manual/2.theory.of.operation.htm

raw
1 <!DOCTYPE html>
2 <HTML lang="en">
3 <HEAD>
4 <meta name="viewport" content="width=device-width, initial-scale=1.0">
5 <TITLE>Pd Manual - Chapter 2: Theory of operation</TITLE>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
7 <link rel="stylesheet" type="text/css" href="resources/pdmanual.css" media="screen">
8 <link rel="icon" href="resources/favicon.ico">
9 </HEAD>
10 <BODY>
11
12 <div class="nav nav-top">
13 <div class="nav-back"><A href="1.introduction.htm">&lt; Chapter 1: Introduction</A></div>
14 <div class="nav-home"><A href="index.htm#s2">Table of contents</A></div>
15 <div class="nav-forward"><A href="3.installing.configuring.htm">Chapter 3: Installing and configuring Pd &gt;</A></div>
16 </div>
17 <div id="corpus">
18
19 <IMG id="logo" src="resources/icon.png" ALT="pd icon">
20
21 <H2>Chapter 2: Theory of operation</H2>
22
23 <P>The purpose of this chapter is to describe Pd's design and how it is
24 supposed to work. Practical details about how to obtain, install, and run Pd
25 are described in the <A href="3.installing.configuring.htm">next chapter</A>. Links to more extensive
26 guides (and to more theoretical information about computer music) are provided
27 in the <A href="1.introduction.htm">previous chapter</A>.</P>
28
29 <H3> <A href="#s2.1" id="s2.1">2.1. Overview</A> </H3>
30
31 <P>Pd (Pure Data) is a real-time graphical programming environment designed for audio
32 processing, that can be extended for multimedia purposes and more. Pd resembles the
33 MAX system, but is much simpler and more portable. For example, with Peter Brinkmann's
34 libpd, you can use Pd as an embeddable audio synthesis library. Additionally, Pd was
35 originally designed to offer a unique experimental feature not found in MAX,
36 allowing users to define and access data structures in innovative ways, with the ability
37 to attach shapes and colors to data in order to visualize it and/or edit it graphically
38 (see section <A href="2.theory.of.operation.htm#s2.10">2.10 Data Structures</A> for details).</P>
39
40 <P>Despite its lightweight and portable nature, Pd offers a wide range of external
41 packages that enhance its capabilities, primarily focusing on audio and control
42 processing, but also for graphical processing and whatnot. For examples and details
43 on installing and managing packages, refer to <A href="4.externals.htm"> Chapter 4: Externals</A>.</P>
44
45 <H4> <A href="#s2.1.1" id="s2.1.1"> 2.1.1. The main window, canvases, and printout</A> </H4>
46
47 <P>Pd starts with the main "Pd" window. When you open a Pd document file you'll see a
48 separate window, known in Pd as a <i>canvas</i> and also referred to as <i>patch</i>.
49 The main Pd window looks like this:</P>
50
51 <figure>
52 <IMG src="resources/2.1.1.png" ALT="pd window">
53 <figcaption><u>Fig. 2.1.1</u> The main Pd window (aka "Console window") on Windows</figcaption>
54 </figure>
55
56 <P>At the top, you'll see the menu entries: <b>File</b>, <b>Edit</b>, <b>Put</b>,
57 <b>Find</b>, <b>Media</b>, <b>Window</b>, <b>Tools</b> and <b>Help</b> (on Macs, this is shown
58 at a top bar on the screen, and there is an additional first <b>Pd</b> menu entry similarly
59 to other apps on macOS and as seen below). You can create and open patches via the
60 <b>File menu</b>, where you can also close and save them (note the handy shortcuts).</P>
61
62 <figure>
63 <IMG src="resources/2.1.2.png" ALT="file menu">
64 <figcaption><u>Fig. 2.1.2</u> The File menu on macOS</figcaption>
65 </figure>
66
67 <P>Creating a new file creates a blank window.</P>
68
69 <figure>
70 <IMG src="resources/2.1.3.png" ALT="patch canvas">
71 <figcaption><u>Fig. 2.1.3</u> A new and blank patch canvas</figcaption>
72 </figure>
73
74
75 <P>The lower part of the Pd window is a console area for printout from outputs of
76 boxes in patches and for messages from Pd itself. Here is a simple Pd patch:</P>
77
78 <figure>
79 <IMG src="resources/2.1.4.png" ALT="simple patch">
80 <figcaption><u>Fig. 2.1.4</u> A simple patch</figcaption>
81 </figure>
82
83 <P>This patch contains four <i>text boxes</i>: a <i>number box</i> (displaying "<code>0</code>"),
84 an <i>object box</i> labeled "print", plus two <i>comments</i> (which are simply texts
85 that don't affect the patch and can't be connected to anything). The number
86 box is connected to the object box, with the output of the number box feeding into
87 the input of the <b>[print]</b> object box. Boxes may have zero or more inputs
88 and/or outputs, called <i>inlets</i> and <i>outlets</i>. Inlets are visible at the top of objects
89 and outlets at their bottom. When clicking and dragging on the number box in run mode, the values
90 are printed in the main "Pd" window.</P>
91
92 <P>On the upper right of the main Pd window, there is a <b>DSP</b> toggle, which stands
93 for "Digital Signal Processing" and turns audio processing on and off globally. DSP
94 is off by default when Pd is opened. When you turn it on, Pd starts computing
95 audio samples in realtime for all open patches (whether they are visible or not).</P>
96
97 <figure>
98 <IMG src="resources/2.1.5.png" ALT="DSP on">
99 <figcaption><u>Fig. 2.1.5</u> Activated DSP toggle in the Pd window on a mac</figcaption>
100 </figure>
101
102 <P>Turning off <b>DSP</b> halts the computation and releases any audio devices
103 that Pure Data is utilizing. You can configure audio devices as described in
104 <A href="3.installing.configuring.htm#s3.3.1">3.3.1. Audio settings</A>.</P>
105
106 <P>The <b>Media menu</b> offers shortcuts to toggle DSP on and off. Use <kbd>Ctrl</kbd>+<kbd>/</kbd>
107 ("Control" key on PCs or "Command" key on Apple computers plus the <kbd>/</kbd> key)
108 to turn audio processing on, and <kbd>Ctrl</kbd>+<kbd>.</kbd> to turn it off. You can check the input
109 audio level if you select "Test Audio and MIDI..." and make other Audio and MIDI tests (read more
110 about this in <A href="3.installing.configuring.htm#s3.3">3.3. Testing and configuring Audio and MIDI</A>).</P>
111
112 <figure>
113 <IMG src="resources/2.1.6.png" ALT="media menu">
114 <figcaption><u>Fig. 2.1.6</u> The Media menu</figcaption>
115 </figure>
116
117 <P> Besides printing the messages from objects, the Pd window logs several messages from Pd.
118 You can set different log levels to filter the output. The default level is 2 (normal).
119 You can increase it to get more detailed information or decrease it to only see fatal errors.</P>
120
121 <figure>
122 <IMG src="resources/2.1.7.png" ALT="log levels">
123 <figcaption><u>Fig. 2.1.7</u> The log level popup menu</figcaption>
124 </figure>
125
126 <P id="sfinderror">Errors are mostly printed by objects and displayed in the Pd window in red color.
127 You can find error sources for the corresponding line with <kbd>Ctrl</kbd>+<kbd>click</kbd>
128 or through the context menu on right click as shown below. Alternatively, you can use the
129 "Find Last Error" entry in the <b>Find menu</b> for this.</P>
130
131 <p>Note that you can also find objects printing regular log outputs via right click or
132 <kbd>Ctrl</kbd>+<kbd>click</kbd> in many cases (a cursor change will signalize this option
133 when hovering the log lines).</p>
134
135 <p>In cases of objects that couldn't be created, the context menu also contains a
136 "Find externals" option that will open <b>deken</b> with a prefilled search field.</p>
137
138 <figure>
139 <IMG src="resources/2.1.8.png" ALT="find error">
140 <figcaption><u>Fig. 2.1.8</u>Find error source via right click</figcaption>
141 </figure>
142
143 <P>If the Pd window is focused, the font size for menus and printout can be changed
144 using the "Font" dialog entry in the <b>Edit menu</b>.</P>
145
146 <figure>
147 <IMG src="resources/2.1.9.png" ALT="edit menu">
148 <figcaption><u>Fig. 2.1.9</u> The Edit menu</figcaption>
149 </figure>
150
151 <P> Make your adjustments in the Font dialog window and increase the size if you are
152 having trouble reading on HiDPI screens. You can ignore the "Stretch" parameter here, since
153 that only works for Pd documents.</P>
154
155 <figure>
156 <IMG src="resources/2.1.10.png" ALT="font settings">
157 <figcaption><u>Fig. 2.1.10</u> The Font settings dialog</figcaption>
158 </figure>
159
160 <P>Pd documents (called "patches" or "canvases") have their own main window and any number of
161 sub-windows. The sub-windows can be opened and closed, but they are always running,
162 whether you see them or not. When opened, sub-windows show up as a separate canvases.
163 When you have a patch window focused, you can use the "Font" dialog entry in the
164 <b>Edit menu</b> to set the patch's font size, which also applies to its subwindows.
165 Note that the patch's font size gets saved with the file.</P>
166
167 <P>For patch canvases, you can also use the "Stretch" feature, which stretches
168 or compresses text elements (boxes) of your patch. This can be used to realign objects
169 accordingly to font size changes which don't affect the layout.</P>
170
171 <P>In the <b>Edit menu</b> you can also <b>Zoom In</b> and <b>Zoom Out</b> a patch window.
172 Note that the Zoom setting is not saved in the patch though.</P>
173
174 <figure>
175 <IMG src="resources/2.1.11.png" ALT="zoomed in and out">
176 <figcaption><u>Fig. 2.1.11</u> A patch in standard and zoomed state</figcaption>
177 </figure>
178
179 <P>In the <b>Edit menu</b>, you can also clear all messages printed in the Pd window with
180 the "Clear Console" entry (shortcut <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>L</kbd>). On the
181 <b>Window menu</b>, you find the "Pd Window" entry (shortcut <kbd>Ctrl</kbd>+<kbd>R</kbd>),
182 which brings the Pd window to the front or sends it behind the last focused patch.</P>
183
184 <P>On PCs, this menu shows the <kbd>Ctrl</kbd>+<kbd>Q</kbd> entry to quit Pd, which prompts
185 you to confirm the action (on Macs, this is listed in the <b>Pd menu</b>). To quit
186 without confirmation, you can use <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Q</kbd>.</P>
187
188 <H4> <A href="#s2.1.2" id="s2.1.2"> 2.1.2. Object boxes</A> </H4>
189
190 <P>The object box loads an instance of a class in your patch. You can create an
191 object box from the <b>Put menu</b>. When you insert a new object box, it is empty
192 and presented with a dashed border before creation.</P>
193
194 <figure>
195 <IMG src="resources/2.1.12.png" ALT="dashed box">
196 <figcaption><u>Fig. 2.1.12</u> An uncreated object box</figcaption>
197 </figure>
198
199 <P>You only create a particular <i>object</i> after you entered text into the
200 object box and click outside it to instantiate it. The text consists of <i>atoms</i>,
201 which are separated by spaces. The first atom (which needs to be a symbol) determines
202 the type of object Pd will create, while the subsequent atoms, known as <i>creation
203 arguments</i>, instruct Pd how to initialize the object. For instance, you can type
204 "+ 13".</P>
205
206 <figure>
207 <IMG src="resources/2.1.13.png" ALT="object box">
208 <figcaption><u>Fig. 2.1.13</u> A created object box</figcaption>
209 </figure>
210
211 <P>Here, the "+" specifies the <I>class</I> of the object. In this case the
212 object will carry out additions, and the "13" initializes the value to add.</P>
213
214 <P>Atoms are either <I>numbers</I> or <I>symbols</I> - they can also be <I>pointers</I>,
215 but those are only used when dealing with data structures, hence, most of times, we're
216 dealing with either floats or symbols, but how do they differentiate? In Pd, anything
217 that is not a valid number is considered a symbol! Valid numbers may or may not have a
218 decimal point, such as "12", "15.6", "-0.456". Numbers in Pd may also be written in
219 exponential notation and have limited display and internal precision. Check more details
220 in <A href="2.theory.of.operation.htm#s2.4.1">subsection 2.4.1.</A>.</P>
221
222 <P>A number that starts with a "+" is not considered a valid number and is considered a
223 symbol instead, so is "0..6" as well as words and names such as "Zack" or "cat". The
224 symbols "gore", "Gore", and "GORE" are all distinct, reflecting case sensitivity.</P>
225
226 <P>The text you type into an object box determines how many and what kinds of
227 <i>inlets</i> and <i>outlets</i> the object will have. Certain classes, such as
228 <b>[+]</b>, consistently maintain a fixed configuration of inlets and outlets.
229 However, for other classes, the number and arrangement of inlets and outlets
230 can vary based on the creation arguments.</P>
231
232 <P>Here is an example of a simple synthesizer that takes a MIDI input and
233 synthesizes a pure tone:</P>
234
235 <figure>
236 <IMG src="resources/2.1.14.png" ALT="simple MIDI synthesizer">
237 <figcaption><u>Fig. 2.1.14</u> A simple MIDI synthesizer</figcaption>
238 </figure>
239
240 <P>This patch mixes <I>control</I> objects (<b>[notein]</b>, <b>[stripnote]</b>,
241 and <b>[ftom]</b>) with <I>tilde</I> objects (<b>[osc~]</b>, <b>[*~]</b>, and
242 <b>[dac~]</b>). These are the two types of objects that exist in Pd: control
243 objects and signal objects.</P>
244
245 <P>The control objects on the upper half carry out their function sporadically, as a
246 result of one or more types of <I>events</I>. In this case, incoming MIDI note
247 messages set off the control computation. When a note event happens (more
248 specifically a "note on" event, since "note off" events are filtered by <b>[stripnote]</b>),
249 the control computation is triggered and it computes the frequency in
250 cycles per second with <b>[mtof]</b> and passes it on to the oscillator
251 (<b>[osc~]</b>).</P>
252
253 <P>The objects in the lower half of the patch (<b>[osc~]</b>,
254 <b>[*~]</b>, and <b>[dac~]</b>) compute
255 audio samples. The <b>[osc~]</b> object serves as the interface
256 between the two regimes; it takes control messages to set its frequency but outputs
257 an audio sine wave to a gain level adjustment in <b>[*~]</b>,
258 which then goes to the output via <b>[dac~]</b>.</P>
259
260
261 <P>The connections in the patch (the lines between the boxes) are also of the types
262 "control" or "signal". Note that they are visually distinct, where signal connections
263 are thicker than control connections. The connection type depends on the outlet
264 it comes from.</P>
265
266 <P>It's possible to make control connections to a signal inlet; if numbers
267 get sent through it, they are usually automatically converted to signals. Signal
268 connections can't be made to control inlets though; some sort of explicit conversion
269 from audio signal to control data is necessary in this case.</P>
270
271 <P>Audio signals form continuous streams of numbers, not intermittent bursts.
272 Therefore, tilde objects operate under rules distinct from those of control objects.
273 When DSP is activated, the audio segment of the patch runs continuously, regardless
274 of whether MIDI messages are received. In contrast, control computations are
275 interspersed within the audio processing, allowing for the adjustment of parameters
276 such as the frequency of an oscillator in this example.</P>
277
278 <H4> <A href="#s2.1.3" id="s2.1.3"> 2.1.3. Message and GUI boxes</A> </H4>
279
280 <P>The shape of a box tells you how its text is interpreted and how the box
281 functions. Object boxes (as in the previous example) are rectangular and use
282 the text to create objects when you load a patch or type text onto a new one.
283 That is, the contents of an object box describe a message which is sent to Pd
284 to create the object. If you retype the text in an object box, the old one is
285 discarded and a new one is created, using the new creation arguments.</P>
286
287 <P><I>Message</I> boxes have a different shape and interpret the text as a
288 message to send whenever the box is activated (through an incoming message or via
289 a mouse click). The message may be sent many times while the patch is running
290 (as opposed to object boxes whose message is used once to create the object).
291 Instead of going straight to Pd, the message box's messages go either
292 to its outlet or to other receiving objects specified in the message itself.
293 In the example below, a click on the message box sends the message "21" to the
294 connected object box, which adds 13 to it.</P>
295
296 <figure>
297 <IMG src="resources/2.1.15.png" ALT="Different box shapes">
298 <figcaption><u>Fig. 2.1.15</u> Different box shapes</figcaption>
299 </figure>
300
301 <P>The third box here is a <I>GUI</I> ("graphical user interface") box. Pd has
302 3 basic GUI boxes. In addition to <i>number boxes</i> (as in this example), there are
303 <i>symbol boxes</i> to display and edit symbols and <i>list boxes</i> for arbitrary
304 lists of atoms.</P>
305
306 <P>Pd also comes with another set of GUIs that include <i>bang</i>, <i>toggle</i>,
307 <i>sliders</i>, <i>radio buttons</i>, etc.</P>
308
309 <P>You can interact with GUIs in many ways and they are visually dynamic. For instance,
310 while the appearance of an object or message box remains unchanged when a patch is
311 running, a number box's content changes to reflect the current value held by the box.
312 You can also use a number box as a control by clicking and dragging up and down, or
313 by typing values in it and hitting enter (more details on how this and any other GUIs
314 work is available in the objects' help files; see <A href="2.theory.of.operation.htm#s2.2.7">2.2.7. Popup
315 menu for "Properties", "Open" and "Help"</A>.</P>
316
317 <H4> <A href="#s2.1.4" id="s2.1.4"> 2.1.4. Patches and files</A> </H4>
318
319 <P>As mentioned before, you can create or open Pd files from the <b>File menu</b>,
320 as well as close and save them.</P>
321
322 <P>When you save a patch to a file, Pd doesn't save the entire state of all the
323 objects in the patch, but only what you see: the objects' creation arguments
324 and their interconnections. Nonetheless, the <b>[savestate]</b>
325 object offers a mechanism to save the state of abstractions (see
326 <A href="2.theory.of.operation.htm#s2.8">2.8. Subpatches</A>). Also, certain data-storage objects have
327 functions for reading and writing files to save and restore their internal
328 state (one example is the <b>[text]</b> object). When loading
329 a patch, the <b>[loadbang]</b> object can be used to initialize
330 the parameters of your patch, so you can load text files and make other preparations.</P>
331
332 <P>Pd searches for files using specified paths. Most objects capable of reading files
333 search along these paths, but when Pd writes files, they are saved to the directory
334 where the patch itself is located by default. Check <A href="3.installing.configuring.htm#s3.4">3.4. Path and
335 startup</A> for more details.</P>
336
337 <H3> <A href="#s2.2" id="s2.2">2.2. Editing Pd patches</A> </H3>
338
339 <P>Normally, you'll use Pd in run mode, which is also referred to as "performance
340 mode". In order to edit a patch, you need to go into edit mode.</P>
341
342 <H4> <A href="#s2.2.1" id="s2.2.1"> 2.2.1. Edit and run mode</A> </H4>
343
344 <P>When you open a Pd file, it is in run mode. In run mode, the cursor is an arrow that
345 points up and is slightly tilted to the left, but it points straight up when you are
346 able to click on a box. In run mode, you mostly click and interact with GUIs (like the
347 number box) and message boxes (which are used as controls to send messages).</P>
348
349 <figure>
350 <IMG src="resources/2.2.1.png" ALT="run mode arrow">
351 <figcaption><u>Fig. 2.2.1</u> The arrow cursors in run mode</figcaption>
352 </figure>
353
354 <P> In order to go into edit mode, you need to select the "Edit Mode" entry from the
355 <b>Edit menu</b> to activate and check it on.</P>
356
357 <figure>
358 <IMG src="resources/2.2.2.png" ALT="edit mode">
359 <figcaption><u>Fig. 2.2.2</u> Selecting edit mode from the Edit menu</figcaption>
360 </figure>
361
362 <P>When you are in edit mode, the patch actually runs in the same way as in run mode,
363 processing control data and sound (if DSP is on), but you're able to edit the patch
364 while it runs. The only real change is how mouse clicks affect the patch. In run mode,
365 mouse clicks will interact with the patch and change parameters of the performance, while
366 in edit mode the purpose of mouse clicks is to edit and change the patch. Note that in
367 edit mode, the mouse cursor becomes a pointing hand instead of an arrow. Unchecking the
368 "Edit Mode" entry returns the patch to run mode and changes the cursor back to an
369 arrow. You can use the <kbd>Ctrl</kbd>+<kbd>E</kbd> shortcut to switch between these modes.</P>
370
371 <figure>
372 <IMG src="resources/2.2.3.png" ALT="edit mode hand pointer">
373 <figcaption><u>Fig. 2.2.3</u> The hand cursor in edit mode</figcaption>
374 </figure>
375
376 <P>In edit mode, you can move boxes around by clicking on them and dragging.
377 You can also edit text, create or delete boxes and make or cut connections (more
378 details on this will follow below) and you can resize some boxes in your patch,
379 namely object boxes, number/symbol/list boxes, comments, messages. Note you can
380 also resize <A href="2.theory.of.operation.htm#s2.8.2">Graph-on-parent subpatches</A> and
381 <A href="2.theory.of.operation.htm#s2.9">Arrays</A>.</P>
382
383 <figure>
384 <IMG src="resources/2.2.4.png" ALT="resizing boxes">
385 <figcaption><u>Fig. 2.2.4</u> The double arrow cursor for resizing boxes when in edit mode</figcaption>
386 </figure>
387
388 <p>You need to move the cursor to the right edge of the object and you'll see the cursor
389 becoming a double-sided horizontal arrow. You can then click and drag horizontally to
390 resize these box. The exception to this rule are the IEMguis objects (toggles, sliders,
391 radio buttons, etc). These used to be an external library package but were incorporated
392 natively into Pd in version 0.34 (they can still be created from object boxes though -
393 see their help patches for the corresponding symbols). At the time of this writing,
394 they can't be resized in edit mode with the mouse cursor.</p>
395
396 <P>If you are predominantly editing a patch, but would like to quickly switch to
397 run mode just to click on something like a message, you can press and hold
398 <kbd>Ctrl</kbd> to temporarily switch to run mode until you release it.</P>
399
400 <P>In the <b>Edit menu</b> you also find "Undo" and "Redo" operations, which revert
401 and recreate changes you've done in your patch while in edit mode. Note that you can
402 also "Undo" and "Redo" while in run mode.</P>
403
404 <P>You can resize patch windows like any other windows in your OS. Note that the mouse
405 becomes a double sided arrows in the horizontal and vertical edges or corner bounds.
406 This is possible regardless if you are in edit or run mode. If boxes are outside
407 the visible area, you'll see that scrollbars appear. In both edit or run mode you can
408 navigate through the hidden area. Besides dragging the scrollbars, you can pan the patch
409 vertically by turning the mousewheel and horizontally when pressing and holding
410 <kbd>Shift</kbd> while doing so. On trackpads, you can use 2-finger scrub gestures to
411 pan in all directions. Resizing the patch window to fit all objects in removes the
412 scrollbars.</P>
413
414 <figure>
415 <IMG src="resources/2.2.5.png" ALT="scrollbars">
416 <figcaption><u>Fig. 2.2.5</u> A patch window with scrollbars</figcaption>
417 </figure>
418
419 <H4> <A href="#s2.2.2" id="s2.2.2"> 2.2.2. Creating boxes</A> </H4>
420
421 <P>Pd patches can have four types of boxes: <I>object</I>, <I>message</I>, <I>GUI</I> and
422 <I>comment</I> (which counts as a "box type" even though it's not a "box" visually).
423 You can create these boxes using the <b>Put menu</b>. Also note the handy shortcuts
424 to create each item specifically.</P>
425
426 <figure>
427 <IMG src="resources/2.2.6.png" ALT="put menu">
428 <figcaption><u>Fig. 2.2.6</u> The Put menu</figcaption>
429 </figure>
430
431 <P> Note that most of these are individual GUI (graphical user interface) boxes.
432 Besides the three basic GUI boxes (number, symbol and list), there's another group
433 of GUIs that has more options (toggles, sliders, radio buttons, etc). These are
434 also known as "IEMguis". There are also entries for "array" and "graph" that will
435 be explained later.</P>
436
437 <P>If you are in run mode and click on an entry in the <b>Put menu</b> or use
438 a shortcut, Pd automatically switches to edit mode. When you add boxes
439 this way, they are automatically selected and follow the mouse cursor;
440 drag them around as desired until you click to position them where you want.
441 The box will still be selected and you can input text.</P>
442
443 <P>Message and object boxes are empty when added. Typing into them will also
444 force position the boxes if they haven't been positioned yet by a click.
445 To actually create the object, deselect it by clicking on an empty spot
446 of the patch or using the <kbd>Esc</kbd> key.</P>
447
448 <P>When you add a comment box, it shows a "comment" placeholder text. When you
449 position it, the text is selected and you can start typing a new commentary.
450 Similar to an object box, the comment is only created after deselecting it.
451 Same is true for a message box as the message is only part of the patch after
452 deselecting it. Saving a patch without properly created objects, comments or
453 message boxes will save them as empty boxes.</P>
454
455 <P>You may find it more convenient to select a box and "duplicate" it than to use
456 the <b>Put menu</b>. If you duplicate a selection of several items, connections
457 between them will be duplicated as well. To deselect more than one box, you
458 can also either click on an empty area of your patch or press <kbd>Esc</kbd>.</P>
459
460 <H4> <A href="#s2.2.3" id="s2.2.3"> 2.2.3. Selecting items and moving them or "tidying them up"</A> </H4>
461
462 <P>In Edit mode you can select or deselect one or more boxes. Note that the outline
463 of all boxes and containing text turn light blue (instead of the usual black) to
464 indicate they are selected. Boxes in a Pd window may be individually selected by
465 clicking on them. If you don't release the mouse button you can select a box and drag
466 it around right away.</P>
467
468 <P>To select more than one box, you may use <kbd>Shift</kbd>+<kbd>Click</kbd> on each item.
469 You can then click again on one of the selected boxes to move the group around.
470 Alternatively, you click on a blank portion of the window and drag the cursor to
471 select all boxes within a rectangular area (then click again on one of the selected
472 boxes to move them as well). If you press <kbd>Shift</kbd>, you can repeat the click
473 and drag operation to select another group of boxes as well. If you do
474 <kbd>Shift</kbd>+<kbd>Click</kbd> on a selected box, you deselect it. The "Select All"
475 entry on the <b>Edit menu</b> (<kbd>Ctrl</kbd>+<kbd>A</kbd>) selects all items in a
476 patch window.</P>
477
478 <P>When you have one or more boxes selected, you can also move them by using the
479 <kbd>Arrow keys</kbd>, which moves items one pixel in the direction of the arrows.
480 You can also use <kbd>Shift</kbd>+<kbd>Arrow keys</kbd> to move items 10 pixels in the
481 desired direction. By the way, if you select boxes that are connected, the
482 connections (patch cords) are also moved around.</P>
483
484 <P>The "Tidy Up" entry in the <b>Edit menu</b> allows you to align
485 selected boxes that are not perfectly aligned. You can select boxes arranged in a
486 horizontal row and use the shortcut <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>R</kbd>
487 to try and align them perfectly horizontally. Similarly, this can be applied to
488 vertically align a column of boxes. Bidimensional rectangular selections of boxes
489 are also possible, but aligning horizontally and vertically separately tends to yield
490 better results. When boxes are misaligned drastically, this action won't do anything.</P>
491
492 <figure>
493 <IMG src="resources/2.2.7.png" ALT="tidy up">
494 <figcaption><u>Fig. 2.2.7</u> Tidying up (aligning) vertically</figcaption>
495 </figure>
496
497 <H4> <A href="#s2.2.4" id="s2.2.4">2.2.4. Delete, cut, copy and paste boxes</A> </H4>
498
499 <P>If you select any item you can press <kbd>Backspace</kbd> or <kbd>Delete</kbd>
500 key to delete it. Connections of a deleted box are also deleted. A multiple selection
501 of items (and their connections) can also be deleted.</P>
502
503 <P>For one or more selected items and their connections you can also "Cut", "Copy",
504 "Paste" and "Duplicate" from the <b>Edit menu</b> or shortcuts. Note that you can
505 "Cut" or "Copy" and then "Paste" the selection in a different patch window. When
506 pasted, the items stay selected, so you can click on one of them and move the
507 whole selection around by dragging (or move them using the arrow keys).</P>
508
509 <P>You'll see that pasting inserts the selection at the same position it was copied
510 from, unless the place is already taken; in that case, there is a small offset. The
511 "Duplicate" menu entry performs a copy and paste with a similar offset (since the
512 original selection remains in the original position).</P>
513
514 <P>Note that the cut/copy/paste functionality for patch elements is not integrated with
515 the operating system's clipboard. This limitation prevents you from pasting between
516 different versions or flavors of Pure Data. Furthermore, it is not possible to copy
517 from a patch and paste into a Pd subprocess that was instantiated through a
518 <b>[pd~]</b> object.</P>
519
520
521 <H4> <A href="#s2.2.5" id="s2.2.5">2.2.5. Changing the text of objects, messages and comments</A> </H4>
522
523 <P>Clicking on an unselected object, message or comment box and releasing the
524 click makes the text active, i.e., ready to be text edited (if you select using
525 a rectangular area selection or <kbd>Shift</kbd>+<kbd>Click</kbd>, the text isn't activated).</P>
526
527 <P>If you only click once, the entire text is selected and your typing will replace
528 the whole selections. Use <kbd>Arrow keys</kbd> to navigate the cursor through the
529 text or use the mouse to click and drag to change the text selection and edit it.</P>
530
531 <P>If you wish to displace a box whose text is activated you need to first deselect
532 it (by clicking outside it or using <kbd>Esc</kbd>), otherwise you will be selecting
533 text instead of moving the box.</P>
534
535 <P>The updated text only becomes part of the patch when you deselect the
536 object. As already mentioned, changing the text in an object box deletes
537 the old object and creates a new one; so the internal state of the old one
538 is completely lost.</P>
539
540 <figure>
541 <IMG src="resources/2.2.8.png" ALT="changing text">
542 <figcaption><u>Fig. 2.2.8</u> Editing text in an object box</figcaption>
543 </figure>
544
545 <P>You can also use the copy, cut, and paste commands for the selected text. The
546 text selection functionality for cut/copy/paste is integrated with the operating
547 system, enabling you to copy and paste text between Pd and other software
548 applications.</P>
549
550 <H4> <A href="#s2.2.6" id="s2.2.6">2.2.6. Connecting and disconnecting boxes</A> </H4>
551
552 <P>This subsection only describes the simplest way to connect two boxes. For
553 more advanced and convenient techniques and shortcuts, refer to the next section.</P>
554
555 <P>To create a connection in edit mode, move your mouse into the the area of
556 an outlet. Note that the cursor becomes a circle (a patch point), indicating
557 that you can click and drag to create a connection. Drag the cord into an inlet
558 area, where you'll see again the circle shaped cursor, signaling that you can
559 release the mouse button to create a connection. You can release the mouse button
560 anywhere within the target box and the connection will be made to the nearest
561 inlet.</P>
562
563 <figure>
564 <IMG src="resources/2.2.9.png" ALT="connecting boxes">
565 <figcaption><u>Fig. 2.2.9</u> Connecting boxes via click and drag</figcaption>
566 </figure>
567
568 <P>If you move the mouse cursor over a patch cord, you'll see it takes the shape
569 of an "chapter" to denote you can select it and delete it. Click on the connection
570 to select it and press <kbd>Backspace</kbd> or <kbd>Delete</kbd> key to delete
571 it. You can't just select patch cords with click and drag for a rectangular
572 area and you can only select a single connection by clicking on it.</P>
573
574 <figure>
575 <IMG src="resources/2.2.10.png" ALT="disconnecting boxes">
576 <figcaption><u>Fig. 2.2.10</u> Selecting a patch cord connection to delete it</figcaption>
577 </figure>
578
579 <H4> <A href="#s2.2.7" id="s2.2.7">2.2.7. Context menu for "Properties", "Open" and "Help"</A> </H4>
580
581 <P>All the "clicking" mentioned above is done with the left mouse button.
582 The right button, instead, opens a context menu offering "Properties",
583 "Open" and "Help" (either in edit or run mode). Apple users, who may only
584 have one button should know that <kbd>Control</kbd>+<kbd>Click</kbd> is mapped
585 to right-click and that new magic mouse devices can map gestures when you
586 click with two fingers (same is true for trackpads).</P>
587
588 <P>Selecting "Help" on any box opens a patch explaining and demonstrating
589 what it is and how it works. Asking "Help" for the canvas as a whole
590 (right-clicking outside any box) gives a list of all built-in boxes and
591 every object class.</P>
592
593 <P>The "Open" menu item is only enabled if you right-click on a
594 <A href="2.theory.of.operation.htm#s2.8">subpatch</A> and prompts Pd to open it.
595 Ordinary subpatches may also be opened by simply clicking on them,
596 but for <A href="2.theory.of.operation.htm#s2.8.2">graph-on-parent subpatches</A>
597 this is the only method available.</P>
598
599 <P>The "Properties" dialog allows you to change certain settings of GUI
600 boxes or of the patch itself (when clicking outside any box).</P>
601
602 <H3> <A href="#s2.3" id="s2.3">2.3. Advanced patch editing</A> </H3>
603
604 <P>This section describes advanced techniques and shortcuts for editing patches.</P>
605
606 <H4> <A href="#s2.3.1" id="s2.3.1">2.3.1. Tab navigation</A> </H4>
607
608 <P>When a single box is selected, pressing <kbd>Tab</kbd> allows you to
609 navigate and change the selection to other boxes in the sequence determined
610 by the order of their creation. Pressing <kbd>Tab</kbd> cycles through the
611 boxes from the earliest created to the next, and upon reaching the last box
612 in the window the selection loops back to the first one. Conversely, you can
613 press <kbd>Shift</kbd>+<kbd>Tab</kbd> to navigate in reverse order, moving from the
614 most recently created box back towards the first created ones.</P>
615
616 <figure>
617 <IMG src="resources/2.3.1.png" ALT="tab navigation boxes">
618 <figcaption><u>Fig. 2.3.1</u> Navigating through objects with Tab</figcaption>
619 </figure>
620
621 <P>Using <kbd>Tab</kbd> also works in a similar way for patch cords if
622 you have one selected. You can move from first to last with <kbd>Tab</kbd>
623 and from last to first with <kbd>Shift</kbd>+<kbd>Tab</kbd>.</P>
624
625 <figure>
626 <IMG src="resources/2.3.2.png" ALT="tab navigation cords">
627 <figcaption><u>Fig. 2.3.2</u> Navigating through patch cords with Tab</figcaption>
628 </figure>
629
630 <P>If you're creating a connection by clicking on an outlet and dragging a
631 patch cord, you can also use <kbd>Tab</kbd> to cycle through outlets.
632 The navigation order is left to right and it also cycles back. Pressing
633 <kbd>Shift</kbd>+<kbd>Tab</kbd> navigates from right to left.</P>
634
635 <figure>
636 <IMG src="resources/2.3.3.png" ALT="tab navigation outlets">
637 <figcaption><u>Fig. 2.3.3</u> Navigating through outlets with Tab</figcaption>
638 </figure>
639
640 <P>In Linux and Windows you can also cycle between inlets (this is currently
641 not possible on macOS). When dragging a connection into an inlet area without
642 releasing the mouse, you can use <kbd>Tab</kbd> to navigate to the next inlet.
643 <kbd>Shift</kbd>+<kbd>Tab</kbd> is also possible, but it might produce unexpected
644 results since pressing <kbd>Shift</kbd> while dragging a cord on an inlet creates
645 a connection (see "fan out" interaction below).</P>
646
647 <H4> <A href="#s2.3.2" id="s2.3.2">2.3.2. Autopatching</A> </H4>
648
649 <P>By default, Pd has an "autopatching" mode set to on. You can disable it
650 via startup flags (see "-autopatch" flag <A href="3.installing.configuring.htm#s3.4.1">3.4.1.
651 Startup flags</A>). This works with the shortcuts from the <b>Put menu</b>
652 for inserting boxes. If you have a selected box and use a shortcut to
653 create another one (such as <kbd>Ctrl</kbd>+<kbd>1</kbd> to create an
654 object box), the created box is placed below the selected box and a
655 connection is made from the first outlet of the selected box into the
656 inlet of the newly created box (granted that these boxes have an outlet
657 and an inlet for the connection to happen).</P>
658
659 <P>Once the new box is created, it is also selected, so you can continue with
660 autopatching by adding yet more boxes. In the case of object and message boxes
661 you can also start typing text into it before autopatching into another newly
662 created box, since when you autopatch for the next one, the object or message
663 box gets deselected and instantiated.</P>
664
665 <figure>
666 <IMG src="resources/2.3.4.png" ALT="autopatch objects">
667 <figcaption><u>Fig. 2.3.4</u> Autopatching with shortcuts from the Put menu</figcaption>
668 </figure>
669
670
671 <P>You can also autopatch into a newly created subpatch (see <A href="2.theory.of.operation.htm#s2.8">
672 2.8. Subpatches</A>). By creating an object box and typing "pd", as soon as you
673 deselect the object, a <b>[pd]</b> subpatch is created with an
674 inlet - either a control <b>[inlet]</b> if the object
675 above is a control object, or a signal <b>[inlet~]</b> if
676 it is a tilde object instead.</P>
677
678 <figure>
679 <IMG src="resources/2.3.5.png" ALT="autopatching subpatches">
680 <figcaption><u>Fig. 2.3.5</u> Creating subpatches with autopatching</figcaption>
681 </figure>
682
683
684 <H4> <A href="#s2.3.3" id="s2.3.3">2.3.3. Duplicate connections</A> </H4>
685
686 <P>If you select a connection between two boxes that have more than one
687 outlet and inlet for connections, you can use <kbd>Ctrl</kbd>+<kbd>D</kbd> to
688 duplicate and create more connections.</P>
689
690 <figure>
691 <IMG src="resources/2.3.6.png" ALT="duplicate connections">
692 <figcaption><u>Fig. 2.3.6</u> Duplicate connections with Ctrl+D</figcaption>
693 </figure>
694
695 <H4> <A href="#s2.3.4" id="s2.3.4">2.3.4. Managing connections with the shift key</A> </H4>
696
697 <P>You can swap connections if you selected a connection and use
698 <kbd>Shift</kbd>+<kbd>Click</kbd> on another one.</P>
699
700 <figure>
701 <IMG src="resources/2.3.7.png" ALT="swap connections">
702 <figcaption><u>Fig. 2.3.7</u> Swap connections</figcaption>
703 </figure>
704
705 <P>You can "fan out" connections when no boxes are selected. You can
706 start creating a connection by clicking an outlet and dragging a cord
707 and then use <kbd>Shift</kbd> when you reach the inlet destination
708 (without releasing the mouse button). This "fans out" out and creates
709 another connection from the outlet for you to drag somewhere else and
710 connect the same outlet to to multiple inlets sequentially.</P>
711
712 <figure>
713 <IMG src="resources/2.3.8.png" ALT="shift fan out">
714 <figcaption><u>Fig. 2.3.8</u> Faning out</figcaption>
715 </figure>
716
717 <P>Also for fanning out, if you have a group of target boxes that are selected,
718 you can drag a cord from an outlet of an unselected box and press <kbd>Shift</kbd>
719 to create a connection into the same inlet number of the selected boxes (which do
720 not need to be of the same type or class).</P>
721
722 <figure>
723 <IMG src="resources/2.3.9.png" ALT="select fan out">
724 <figcaption><u>Fig. 2.3.9</u> Faning out with box selections</figcaption>
725 </figure>
726
727 <P>You can create a connection from the same outlet number of multiple boxes to
728 a single inlet. If you have a selection of source boxes, you can drag a cord from
729 one of their outlets into another box and press <kbd>Shift</kbd> to create multiple
730 connections from the same outlet number of the selected boxes (which do not need to
731 be of the same type or class).</P>
732
733 <figure>
734 <IMG src="resources/2.3.10.png" ALT="select fan in">
735 <figcaption><u>Fig. 2.3.10</u> Faning in with box selections</figcaption>
736 </figure>
737
738 <P>You can connect multiple outlets and inlets of 2 boxes if you have 2 selected
739 boxes. Start creating a connection and click <kbd>Shift</kbd> at completion.
740 This creates all possible connections starting from the chosen outlet and inlet.</P>
741
742 <figure>
743 <IMG src="resources/2.3.11.png" ALT="multiple connections">
744 <figcaption><u>Fig. 2.3.11</u> Multiple connections between 2 objects</figcaption>
745 </figure>
746
747 <P>You can connect outlets of multiple boxes into multiple inlets of one box.
748 If there's a selected group of boxes, you start creating a connection into an
749 inlet of a box that is part of the selection. Then you can press <kbd>Shift</kbd>
750 so connections are made from the same outlet number of all source boxes (which do
751 not need to be of the same type or class) into separate inlets, starting from the
752 chosen inlet.</P>
753
754 <figure>
755 <IMG src="resources/2.3.12.png" ALT="many to one">
756 <figcaption><u>Fig. 2.3.12</u> Multiple connections between many to one</figcaption>
757 </figure>
758
759 <P>You can spread multiple outlets of one box into same inlets of other boxes.
760 Similarly to the scenario above, you can start dragging from one outlet of a
761 selected box with multiple outlets to an inlet of one of many selected boxes.
762 In this case, when you press <kbd>Shift</kbd>, all possible connections are
763 made from the outlets of the source box to the same inlet numbers of the target
764 boxes.</P>
765
766 <figure>
767 <IMG src="resources/2.3.13.png" ALT=" one to many">
768 <figcaption><u>Fig. 2.3.13</u> Multiple connections between one to many</figcaption>
769 </figure>
770
771 <H4> <A href="#s2.3.5" id="s2.3.5">2.3.5. (Dis)Connect selection</A> </H4>
772
773 <P>This is a menu entry in the <span class="pdobj">Edit menu</span>, also available via the shortcut
774 <kbd>Ctrl</kbd>+<kbd>K</kbd>. It allows you to connect and disconnect selected
775 boxes in different ways.</P>
776
777 <figure>
778 <IMG src="resources/2.3.14.png" ALT="ctrl+k">
779 <figcaption><u>Fig. 2.3.14</u> The "(Dis)Connect selection" entry from the Edit menu</figcaption>
780 </figure>
781
782 <P>For 2 selected boxes you can use <kbd>Ctrl</kbd>+<kbd>K</kbd> to connect
783 them. It starts by connecting the leftmost outlet to the leftmost inlet. It
784 there are more outlets and inlets to connect, you can repeat using
785 <kbd>Ctrl</kbd>+<kbd>K</kbd> to make multiple connections from possible the
786 remaining outlets to inlets.</P>
787
788 <figure>
789 <IMG src="resources/2.3.15.png" ALT="repeat ctrl+k">
790 <figcaption><u>Fig. 2.3.15</u> Using ctrl+k for one or multiple connections between 2 selected boxes</figcaption>
791 </figure>
792
793
794 <P>For 2 selected tilde objects, if the origin object has a single outlet and
795 the target object has many inlets, you can repeatedly use <kbd>Ctrl</kbd>+<kbd>K</kbd>
796 to fan out and connect the same outlet to all inlets.</P>
797
798 <figure>
799 <IMG src="resources/2.3.16.png" ALT="fan out audio">
800 <figcaption><u>Fig. 2.3.16</u> Fan out audio connections with ctrl+k</figcaption>
801 </figure>
802
803 <P>As for disconnecting, you can use this shortcut to remove all connections from a
804 single selected box.</P>
805
806 <figure>
807 <IMG src="resources/2.3.17.png" ALT="exclude box">
808 <figcaption><u>Fig. 2.3.17</u> Remove connections</figcaption>
809 </figure>
810
811 <P>For last, you can include or bypass a box into or from a connection
812 (being it any connection from any outlet into any inlet). To include a box,
813 you can select it and the connection between the other 2 boxes by using
814 <kbd>Shift</kbd>+<kbd>Click</kbd> and then use <kbd>Ctrl</kbd>+<kbd>K</kbd> to include
815 the selected box into the connection. Alternatively, you can select the 3
816 boxes with a connection between 2 of them and then use <kbd>Shift</kbd>+<kbd>Click</kbd>
817 to include the third one in the connection.</P>
818
819 <figure>
820 <IMG src="resources/2.3.18.png" ALT="insert box">
821 <figcaption><u>Fig. 2.3.18</u> Insert box</figcaption>
822 </figure>
823
824 <P>To bypass a box, you can select 3 boxes connected in a row and use
825 <kbd>Ctrl</kbd>+<kbd>K</kbd> to bypass and remove the middle box from the connection.</P>
826
827 <figure>
828 <IMG src="resources/2.3.19.png" ALT="exclude box">
829 <figcaption><u>Fig. 2.3.19</u> Exclude box</figcaption>
830 </figure>
831
832 <H4> <A href="#s2.3.6" id="s2.3.6">2.3.6. Triggerize</A> </H4>
833
834 <P>The "Triggerize" entry in the <b>Edit menu</b> (with the <kbd>Ctrl</kbd>+<kbd>T</kbd>
835 shortcut) was designed to insert a <b>[trigger]</b> object (in its
836 abbreviated form <b>[t]</b>) into your patch. Start by selecting a single
837 box that is connected to many inlets (of one or more boxes), then use "Triggerize" to insert
838 a <b>[trigger]</b> object after the selected object.</P>
839
840 <P>The <b>[trigger]</b> object is widely used in Pd to control the order
841 of execution from right to left and is briefly described in
842 <A href="2.theory.of.operation.htm#s2.4.3">2.4.3. Hot and cold inlets and right to left outlet order</A>.
843 "Triggerize" then creates the <b>[trigger]</b> object taking into account
844 the order in which the connections were made, where the first connection starts at the
845 rightmost outlet of <b>[trigger]</b> and continues to the leftmost.</P>
846
847 <P>In the example below, a <b>[pack]</b> object is selected and connected
848 to three <b>[s]</b> (<b>[send]</b>) objects. Triggerize
849 then introduces <b>[t a a a]</b> (short for
850 <b>[trigger anything anything anything]</b>) with three outlets and the
851 order that the connections from <b>[pack]</b> were made reflect the order
852 from right to left. You can swap connections with the <kbd>Shift</kbd> key (as described
853 in subsection <A href="2.theory.of.operation.htm#s2.3.4">2.3.4.</A>) if you need to adjust the order of
854 connections.</P>
855
856 <figure>
857 <IMG src="resources/2.3.20.png" ALT="triggerize object">
858 <figcaption><u>Fig. 2.3.20</u> Add a [trigger] object</figcaption>
859 </figure>
860
861 <P>Additionally, the "Triggerize" option can be used to insert a dummy object. To do so,
862 select a connection and use <kbd>Ctrl</kbd>+<kbd>T</kbd>. For a control connection, a
863 <b>[t a]</b> object is created with the text selected, so you can type
864 new text to create another object instead. Similarly, for a signal connection, a
865 <b>[pd nop~]</b> ("no operation") subpatch is created.</P>
866
867
868 <figure>
869 <IMG src="resources/2.3.21.png" ALT="insert dummy">
870 <figcaption><u>Fig. 2.3.21</u> Insert a dummy subpatch</figcaption>
871 </figure>
872
873 <P>Triggerize also allows you to create or remove outlets of a selected
874 <b>[trigger]</b> object. The result depends on the existing connections
875 and outlets. As shown below, if each outlet has a single connection, it will insert an
876 outlet on the left.</P>
877
878 <figure>
879 <IMG src="resources/2.3.22.png" ALT="add 1st outlet">
880 <figcaption><u>Fig. 2.3.22</u> Add a leftmost outlet</figcaption>
881 </figure>
882
883 Now, if the <b>[trigger]</b> object has more outlets than outgoing
884 connections, "Triggerize" removes the unused outlets.
885
886 <figure>
887 <IMG src="resources/2.3.23.png" ALT="reduce outlets">
888 <figcaption><u>Fig. 2.3.23</u> Reduce outlets</figcaption>
889 </figure>
890
891 In case there are more connections than outlets, "Triggerize" adds outlets
892 to distribute all connections to separate ones (following the creation order
893 of the connections from right to left).
894
895 <figure>
896 <IMG src="resources/2.3.24.png" ALT="distribute connections">
897 <figcaption><u>Fig. 2.3.24</u> Distribute connections</figcaption>
898 </figure>
899
900 <H4> <A href="#s2.3.7" id="s2.3.7">2.3.7. Paste replace</A> </H4>
901
902 <P>The "Paste Replace" entry in the <b>Edit menu</b> doesn't have a shortcut and performs
903 a special paste operation where it replaces a selection of boxes for another kind. For
904 example, first copy one box such as a <b>[float]</b> object. Then select
905 a group of boxes of the same type, for instance, a group of object boxes (note that they
906 don't need to be of the same class). Now go to the <b>Edit menu</b> and select "Paste
907 Replace". All the selected boxes of the same type get replaced by the copied box and
908 connections are preserved.</P>
909
910 <figure>
911 <IMG src="resources/2.3.25.png" ALT="paste replace entry">
912 <figcaption><u>Fig. 2.3.25</u> Paste replacing an object</figcaption>
913 </figure>
914
915 <P>Alternatively, you can copy a number box instead of a <b>[float]</b> object
916 and replace it in the selected group of objects, or in a selected group
917 of another kind, such as message boxes. Note that the box types in Pd
918 are: objects, messages, GUIs and comments, whereas IEMguis are actually
919 treated as regular object boxes in this case. Hence, the GUI boxes are
920 only the number box, the symbol box and the list box. Also note that
921 these three GUIs are not of the same kind for the purpose of "Paste Replace".
922 A subpatch or an abstraction can also be used for "Paste Replace" and they
923 count as the same object group type.</P>
924
925 <figure>
926 <IMG src="resources/2.3.26.png" ALT="paste replace boxes">
927 <figcaption><u>Fig. 2.3.26</u> Paste replacing a number box</figcaption>
928 </figure>
929
930 <P>If you have a selection of boxes to replace that includes different
931 types of boxes, the "Paste Replace" will only replace the boxes of the
932 same type that was copied.</P>
933
934 <figure>
935 <IMG src="resources/2.3.27.png" ALT="paste replace similar type">
936 <figcaption><u>Fig. 2.3.27</u> Paste replacing the same box type</figcaption>
937 </figure>
938
939 <H3> <A href="#s2.4" id="s2.4">2.4. Messages</A> </H3>
940
941 <P>In Pd, boxes intercommunicate by sending messages and/or audio signals.
942 Pd messages are sporadic, like MIDI messages or Music N "Note cards".
943 The management of messages in Pd corresponds to the "control" realm, as
944 opposed to audio signals, described in the next section.</P>
945
946 <H4> <A href="#s2.4.1" id="s2.4.1">2.4.1. Message types (selectors)</A> </H4>
947
948 <P>Messages contain a selector followed by any number of arguments. The selector
949 is a symbol that defines the message type. There are common, or <i>special</i>,
950 selectors that Pd defines, so that objects can be connected with maximum flexibility.
951 These special types are: <i>"float"</i>, <i>"symbol"</i>, <i>"list"</i>, <i>"bang"</i>
952 and <i>"pointer"</i>. These represent the special bang message, then types of atoms
953 (float, symbol and pointer), and the list message (which is a list of atoms).</P>
954
955 <P>The arguments of the message are any following <i>atoms</i> after the selector.
956 For instance "list a b c" has a "list" selector, which defines the "list" data type,
957 and "a b c" is the actual message formed by 3 symbol atoms. This message is only
958 composed of symbols but a list message can combine any type of atom, a symbol, a
959 float or a pointer (but usually just floats and symbols).</P>
960
961 <P>The <I>pointer</I> type is only used for data structures and is relatively rare to
962 use them in patches. In fact, you cannot see or type a pointer value on the patch level.
963 So all you can actually see in boxes and printed in the console log are number and symbol
964 atoms. When trying to print a list of pointers in the Pd console, you'll see something
965 like "list (pointer) (pointer)". See more about pointers and data structures in the
966 section <A href="2.theory.of.operation.htm#s2.10">2.10. Data structures.</A>.</P>
967
968
969 <figure>
970 <IMG src="resources/2.4.1.png" ALT="list selector">
971 <figcaption><u>Fig. 2.4.1</u> List messages</figcaption>
972 </figure>
973
974 <P>Above, we see some variations of list messages. Note that when you have messages
975 with two or more elements that start with a number, the list selector is not necessary:
976 if you don't specify it, Pd will implicitly interpret it as a list message. Hence,
977 numbers cannot be used as selectors. While a message with a number followed by other
978 arguments is automatically given the "list" selector, a single number message is
979 automatically given the "float" selector.</P>
980
981 <P>Besides the special selectors, other message selectors can be defined as any other
982 symbol. If a message contains only one symbol, like "stop", it is considered a selector
983 with no actual message (i.e., no arguments) attached. The bang message is a special
984 selector and takes no arguments. The symbol selector can only have one symbol argument.
985 See below.</P>
986
987 <figure>
988 <IMG src="resources/2.4.2.png" ALT="Different selectors">
989 <figcaption><u>Fig. 2.4.2</u> Different selectors</figcaption>
990 </figure>
991
992 <P>When a message is passed to something (which is commonly an inlet of a box, but could
993 be anything that can receive a message), the selector of the message is checked against
994 the receiver. If the receiver recognizes messages of that selector, it carries out some
995 corresponding action. Let's take the <b>[float]</b> object below as an example.</P>
996
997 <figure>
998 <IMG src="resources/2.4.3.png" ALT="float help">
999 <figcaption><u>Fig. 2.4.3</u> The help file of the <b>[float]</b> object</figcaption>
1000 </figure>
1001
1002 <P>Note that the <b>[float]</b> object has two rectangles at the top, called
1003 <i>inlets</i>, where the one on the left directs incoming messages to the <b>[float]</b>
1004 object itself, while the one on the right directs messages to an auxiliary "inlet"
1005 object. The <b>[float]</b> object itself (represented by the left inlet) accepts messages
1006 with the selectors "float", "bang", "symbol" and "send". The right inlet only accepts
1007 messages with the "float" selector. Out of the special selectors, "list" and "pointer"
1008 are not accepted, and the object has only a single custom selector: "send". The help
1009 files of objects have a "reference" subpatch with detailed explanations for the functions
1010 of all inlets and outlets, also specifying what kind of messages they take and output.
1011 See below.</P>
1012
1013 <figure>
1014 <IMG src="resources/2.4.4.png" ALT="reference">
1015 <figcaption><u>Fig. 2.4.4</u> The <b>[float]</b>'s reference</figcaption>
1016 </figure>
1017
1018 <H4> <A href="#s2.4.2" id="s2.4.2">2.4.2. Floats and numerical precision</A> </H4>
1019
1020 <P>Number atoms are always of type <i>float</i>, meaning that Pd does not have an
1021 <i>integer</i> number type. Numbers in Pd are formatted with the '%g' pattern from
1022 the 'sprintf' function, with a precision of '6'. This allows formatting numbers
1023 with and without exponential (or scientific) notation. One example of this notation
1024 is "4.5e+06", which means 4.5*10<sup>6</sup>, resulting in <i>4'500'000</i>.
1025 Negative exponents also work, such as 1.5e-06, which means 1.5*10<sup>&minus;6</sup>
1026 and results in <i>0.0000015</i>.</P>
1027
1028 <P>Depending on their value, numbers are displayed either in decimal or exponential
1029 notation. For negative exponential notation, the exponent number needs to be '-5'
1030 or lower. This means you'll only see up to three zeros after the decimal point before
1031 the first non-zero digit. For instance, "0.0001". If you add another zero, Pd turns it
1032 into exponential notation for display, so "0.00001" becomes "1e-05". Conversely, if
1033 you type "1e-04", Pd converts it to "0.0001" for display.</P>
1034
1035
1036 <P>As for positive exponent numbers, the scientific notation is only used if the
1037 exponent value is '6' or higher. '6' is also the default numeric precision, so Pd
1038 only displays 6 significant digits. This means that you can have "100000", but
1039 adding another zero will switch the representation to "1e+06". Similarly, typing
1040 "1e+05" results in "100000".</P>
1041
1042 <P>Having a 6 digit precision means that numbers are rounded. The 7th significant
1043 digit is rounded in a way that "0.9999994" or less becomes "0.999999" and
1044 "0.9999995" or higher becomes "1". You can display "0.000123456", which has 6
1045 significant digits, but adding another digit as in "0.0001234567" forces Pd to
1046 round it to "0.000123457". If instead you add another zero before the first
1047 significant digit, it turns it into exponential notation as "1.23456e-05",
1048 keeping the display of the 6 significant digits. Similarly to the earlier example,
1049 "1.234567e-05" becomes "1.23457e-05".</P>
1050
1051 <P>Trailing zeros are not displayed in Pd, and no decimal point is shown if there's
1052 no fractional part of the number. So if you type <b>1.</b>, it becomes <b>"1"</b>.</P>
1053
1054 <P>Don't mistake the display precision and rounding with the actual floating point
1055 precision though. If compiled for single precision, numbers in Pd are handled as
1056 32-bit floats, which allows you to represent any integer with 7 digits or less, even
1057 though Pd will only display 6.</P>
1058
1059 <P>Note that the display resolution remains the same when Pure Data is compiled for
1060 double precision, even though the resolution is much higher in Pd64. Since Pure Data
1061 has no integer data type, the range of representable integer numbers depends on the
1062 float precision. The integer range is shown below for single and double precision.</P>
1063
1064 <figure>
1065 <table class="center">
1066 <thead>
1067 <tr>
1068 <th> </th>
1069 <th>Pd</th>
1070 <th>Pd64</th>
1071 </tr>
1072 </thead>
1073 <tbody>
1074 <tr>
1075 <td></td>
1076 <td>32-bit floating point </td>
1077 <td>64-bit floating point </td>
1078 </tr>
1079 <tr>
1080 <td> <strong>min</strong> integer </td>
1081 <td>&minus;2<sup>24</sup> (&minus;16777216) </td>
1082 <td>&minus;2<sup>53</sup> (&minus;9007199254740992) </td>
1083 </tr>
1084 <tr>
1085 <td> <strong>max</strong> integer </td>
1086 <td>2<sup>24</sup> (16777216) </td>
1087 <td>2<sup>53</sup> (9007199254740992) </td>
1088 </tr>
1089 </tbody>
1090 </table>
1091 <figcaption><u>Table 2.1</u>Integer range for Pd / Pd64</figcaption>
1092 </figure>
1093
1094 <P>Hence, there is a discrepancy in what Pd displays and what the actual number
1095 is. In some cases you may not want to represent floats in a message or object as
1096 it is prone to rounding errors. For instance, Pd can only represent Pi as
1097 "3.14159", but it can be calculated with more precision from math objects.</P>
1098
1099 <figure>
1100 <IMG src="resources/2.4.5.png" ALT="precision">
1101 <figcaption><u>Fig. 2.4.5</u>Display precision</figcaption>
1102 </figure>
1103
1104 <P>In the picture above, the <b>[expr]</b> object takes a bang and calculates the
1105 value of pi. The number box displays "3.14159", with 6 significant digits, but
1106 internally the precision is higher. We then compare the output of the number box
1107 with <b>[!=]</b> ('not equal' object) to see if it differs from the number we
1108 can type in Pd with the possible display resolution of the number Pi. The <b>[!=]</b>
1109 object then outputs "1" and activates the toggle, which shows that they are not really
1110 the same number.</P>
1111
1112 <P>Note that while typing a number into a message or comment, Pd can display it
1113 with more precision or even with a different notation (decimal instead of exponential),
1114 but copying and pasting it or saving and reopening the patch forces rounding.</P>
1115
1116 <H4> <A href="#s2.4.3" id="s2.4.3">2.4.3. Depth first message passing</A> </H4>
1117
1118 <P>Whenever a message is triggered in Pd, the receiver may then send out
1119 further messages in turn, and the receivers of those messages can send yet
1120 others. So each message sets off a tree of subsequent messages. This tree is
1121 executed in depth first fashion. For instance in the patch below:</P>
1122
1123 <figure>
1124 <IMG src="resources/2.4.6.png" ALT="depth first">
1125 <figcaption><u>Fig. 2.4.6</u> A tree with depth first message passing</figcaption>
1126 </figure>
1127
1128 <P>The order of arrival of messages is either A-B-C-D or A-C-D-B. The "C"
1129 message is not done until the "D" one is also, and the "A" is not done until
1130 all four are. It is not visible whether "B" or "C" is done first; this
1131 depends on the order the connections were made in.</P>
1132
1133 <P>Message-passing can give rise to infinite loops of the sort shown here:</P>
1134
1135 <figure>
1136 <IMG src="resources/2.4.7.png" ALT="infinite loop">
1137 <figcaption><u>Fig. 2.4.7</u> An infinite loop (stack overflow)</figcaption>
1138 </figure>
1139
1140 <P>Here, the left-hand <b>[+ 1]</b> can't finish processing until the right-hand one has
1141 been sent the result "2", which can't finish processing until the left-hand one
1142 has been sent "3", and so on. This generates a "stack overflow" error (meaning there's
1143 an infinite loop) in the Pd window that you can interact with (as described
1144 <a href="2.theory.of.operation.htm#sfinderror">earlier</a>) to select the causing object.</P>
1145
1146 <figure>
1147 <IMG src="resources/2.4.8.png" ALT="find error source">
1148 <figcaption><u>Fig. 2.4.8</u> Find error via the console window</figcaption>
1149 </figure>
1150
1151 <P>However, it is legal to make a loop if there is a <b>[delay]</b> object somewhere
1152 in it. When <b>[delay]</b> receives a message, it schedules a message for the future
1153 (even if the time delay is 0) and is then "finished"; Pd's internal scheduler will
1154 wake the <b>[delay]</b> back up later.</P>
1155
1156 <H4> <A href="#s2.4.4" id="s2.4.4">2.4.4. Hot and cold inlets and right to left outlet order</A> </H4>
1157
1158 <P>With few exceptions (notably <b>[timer]</b>), objects treat their leftmost inlet as
1159 <i>hot</i> in the sense that messages to left inlets can result in output messages.
1160 So the following is a legal (and reasonable) loop construct:</P>
1161
1162 <figure>
1163 <IMG src="resources/2.4.9.png" ALT="hot and cold inlets">
1164 <figcaption><u>Fig. 2.4.9</u> Avoiding infinite loop with a cold inlet</figcaption>
1165 </figure>
1166
1167 <P>Here, the <b>[f]</b> object is an abbreviation for <b>[float]</b>. Note that the
1168 <b>[+ 1]</b> output is connected to the right-hand inlet of <b>[f]</b>. This <i>cold</i>
1169 inlet merely stores the value for the next time the <b>[f]</b> is sent the "bang" message.</P>
1170
1171 <P>It is frequently desirable to send messages to two or more inlets of an object
1172 to specify its action. For instance, you can use <b>[+]</b> to add two
1173 numbers; but to do it correctly you must make sure the right hand inlet gets its value
1174 first. Otherwise, when the left hand side value comes in, <b>[+]</b>
1175 will carry out the addition (since the left hand inlet is the "hot" one) and will add this
1176 value to whatever was previously sitting in the right hand inlet.</P>
1177
1178 <P>Problems can arise when a single outlet is connected (either directly or
1179 through arbitrarily long chains of message passing) to different inlets of a
1180 single object. In this case it is indeterminate which order the two inlets will
1181 receive their messages. Suppose for example you wish to use <b>[+]</b>
1182 to double a number. The following is incorrect:</P>
1183
1184 <figure>
1185 <IMG src="resources/2.4.10.png" ALT="incorrect inlet connection">
1186 <figcaption><u>Fig. 2.4.10</u> An undefined connection order</figcaption>
1187 </figure>
1188
1189 <P>Here, the left inlet was connected before connecting the right hand one
1190 (although this is not evident in the appearance of the patch). The
1191 <b>[+]</b> thus adds the new input (at left) to the previous input
1192 (at right).</P>
1193
1194 <P>The <b>[trigger]</b> object, abbreviated <b>[t]</b>, can be used to split
1195 out connections from a single outlet in a determinate order. By convention,
1196 all objects in Pd, when sending messages out more than one outlet, do so from
1197 right to left. If you connect these to inlets of a second object without
1198 crossing wires, the second object will get its leftmost inlet last, which is
1199 usually what you want. Here is how to use <b>[trigger]</b> to disambiguate
1200 the previous example:</P>
1201
1202 <figure>
1203 <IMG src="resources/2.4.11.png" ALT="trigger to disambiguate">
1204 <figcaption><u>Fig. 2.4.11</u> A defined connection order with <b>[trigger]</b></figcaption>
1205 </figure>
1206
1207 <P>"Cold" (non-leftmost) inlets are almost universally used to store single
1208 values (either numbers or symbols). With the exception of <b>[line]</b>,
1209 <b>[line~]</b> and <b>[vline~]</b>, these values are
1210 "sticky", i.e., once you set the value it is good until the next time you set it. (The
1211 "line family" exception is for sanity's sake.)</P>
1212
1213
1214 <P>One more question sometimes comes up concerning execution order when two
1215 messages are sent to a single "cold" inlet. In this situation, since the messages
1216 are merged, the last value to be received is the value that is used for the next
1217 computation.</P>
1218
1219 <H4> <A href="#s2.4.5" id="s2.4.5">2.4.5. Message boxes</A> </H4>
1220
1221 <p>Message boxes are text boxes in which you type a message. When the message
1222 box is activated, either by clicking on it or by sending something to its inlet,
1223 the message or messages are sent, either to the message box's outlet or
1224 elsewhere as specified.</p>
1225
1226 <figure>
1227 <IMG src="resources/2.4.12.png" ALT="message boxes">
1228 <figcaption><u>Fig. 2.4.12</u> Messages with different selectors</figcaption>
1229 </figure>
1230
1231 <P>The first of the message boxes above contains the single number 1.5; this
1232 message has an implicit selector of "float". The second is a list with three
1233 numbers in it and has an implicit selector of "list". The third message has
1234 the selector "my" and the two arguments are the number 5 and the symbol "toes".</P>
1235
1236 <P>Multiple messages may be separated by commas as shown:</P>
1237
1238 <figure>
1239 <IMG src="resources/2.4.13.png" ALT="multiple messages in one box">
1240 <figcaption><u>Fig. 2.4.13</u> Messages separated by commas</figcaption>
1241 </figure>
1242
1243 <P>Here, the three messages are the numbers 1, 2, and 3, and they are sent in
1244 sequence (with no intervening time between them, as with the
1245 <b>[trigger]</b> object, and having depth-first consequences so that
1246 whatever chain of actions depending on "1" takes place before anything depending
1247 on "2" and so on).</P>
1248
1249 <P>Semicolons may also separate messages. A message following a semicolon must
1250 specify a symbol giving a destination (in other words, semicolons are like commas
1251 except that they clear the "current destination" so that the next message
1252 specifies a new one). The "current destination" is at first the message box's own
1253 outlet. In the example below, the leading semicolon immediately redirects messages
1254 from the outlet to an object named "fred" (which is a receive object here), and
1255 likewise the next message is sent to "sue".</P>
1256
1257 <figure>
1258 <IMG src="resources/2.4.14.png" ALT="semicolons to send messages">
1259 <figcaption><u>Fig. 2.4.14</u> Messages sent to receive symbols</figcaption>
1260 </figure>
1261
1262 <P>Certain other objects (Pd windows for example, and arrays) have Pd names as
1263 destination symbols so you can send them messages this way. Also, the special
1264 receiver "pd" is defined to which you may send messages to start and stop DSP and
1265 more.</P>
1266
1267 <P>The <b>Tools menu</b> has a "Message..." entry that works as a message box with
1268 a semicolon. This allows you to type in a message while in run mode. You need to
1269 start the message with the receive symbol (and you can also send messages to "pd"
1270 this way).</P>
1271
1272 <figure>
1273 <IMG src="resources/2.4.15.png" ALT="message dialog">
1274 <figcaption><u>Fig. 2.4.15</u> Sending messages via the message dialog</figcaption>
1275 </figure>
1276
1277 <P>You can put variables in message boxes as shown below:</P>
1278
1279 <figure>
1280 <IMG src="resources/2.4.16.png" ALT="variables in message boxes">
1281 <figcaption><u>Fig. 2.4.16</u> A message with a "$1" variable</figcaption>
1282 </figure>
1283
1284 <P>Here, "$1" etc., refer to the arguments of the arriving message (and aren't
1285 defined if you send a "bang" message or if you click on the message box to
1286 activate it). Dollar sign variables are either numbers or symbols depending
1287 on the incoming message; if they are symbols, you may even use them to specify
1288 variable message selectors or destinations.</P>
1289
1290 <H4> <A href="#s2.4.6" id="s2.4.6">2.4.6. Escaping characters</A> </H4>
1291
1292 <p>The "\" (backslash) character is used in Pd to escape special characters that
1293 are handled differently in Pd. Such characters are: "Space", "," (comma), ";"
1294 (semicolon) and "$" (dollar sign) followed by numbers. Also, the backslash
1295 character itself can be escaped. In other cases, backslashes are simply dropped.</p>
1296
1297 <p>This way, the "Hi\, how are you?" message in a message box does
1298 not interpret the comma as it normally would, splitting the message in two.
1299 Instead, you have a literal comma and a "Hi" symbol.
1300 The help file of message boxes has examples on escaping characters, as well as
1301 information of previously discussed topics.</p>
1302
1303 <p>See also the "2.control.examples" from the documentation folder with more
1304 examples about messages and more.</p>
1305
1306 <H3> <A href="#s2.5" id="s2.5">2.5. Audio signals</A> </H3>
1307
1308 <P>Using Pd, you can build audio patches which can synthesize musical sounds,
1309 analyze incoming sounds, process incoming sounds to produce transformed
1310 audio outputs, or integrate audio processing with other media. This section
1311 describes how Pd treats audio signals.</P>
1312
1313 <H4> <A href="#s2.5.1" id="s2.5.1">2.5.1. Sample rate and format</A> </H4>
1314
1315 <P>Pd's audio signals are internally kept as 32-bit floating point numbers, so
1316 you have all the dynamic range you could want. However, depending on your
1317 hardware, audio I/O is usually limited to 16 or 24 bits. Regular input appears
1318 between the values of -1 and 1; and output values are expected in the same range.
1319 Values may be clipped beyond this range depending on OS and audio backend.
1320 Pd runs at a sample rate of 48000 unless you override this (in Pd's command line
1321 or in an "audio setup" or "preferences" dialog window).</P>
1322
1323 <P>Pd can read or write samples to files either in 16-bit or 24-bit fixed point
1324 or in 32-bit floating point, in 'wave', 'aiff', 'caf', and 'next' formats via
1325 the <b>[soundfiler]</b>, <b>[readsf~]</b>,
1326 and <b>[writesf~]</b> objects.</P>
1327
1328 <H4> <A href="#s2.5.2" id="s2.5.2">2.5.2. Tilde objects and audio connections</A> </H4>
1329
1330 <P>Audio computations in Pd are carried out by "tilde objects" such as
1331 <b>[osc~]</b>, whose names conventionally end with a tilde character (which
1332 resembles a sinusoid, symbolizing their function in handling audio signals).
1333 Tilde objects can intercommunicate via audio connections. When audio computation
1334 is turned on or when you change the audio network while audio is on, Pd sorts
1335 all the tilde objects into a linear order for running; this linear list is then
1336 by default run down in blocks of 64 samples each at 48000 Hz. The
1337 audio network then runs every 1-1/3 (about 1.33) milliseconds.</P>
1338
1339 <P>Inlets or outlets are configured in Pd either for messages or audio. You can't
1340 connect an audio outlet to a non-audio inlet. An object's leftmost inlet may accept
1341 audio and message input; any other inlet is either one or the other, but secondary
1342 audio inlets take floats at control rate and promote them automatically to signals.
1343 Nonetheless, in some cases, the inlet may take a float or a signal and run
1344 different algorithms in each case. One example is <b>[lop~]</b>,
1345 which runs a more efficient routine if no signals are connected to the right inlet.
1346 The <b>[+~]</b>, <b>[-~]</b>, <b>[*~]</b>,
1347 <b>[/~]</b>. <b>[max~]</b>, <b>[min~]</b>,
1348 <b>[log~]</b> and <b>[pow~]</b> objects can be
1349 configured to take control or signal inputs in their 2nd inlet depending on the
1350 creation argument.</P>
1351
1352
1353 <P>The audio network, that is, the tilde objects and their interconnections,
1354 must be non-cyclic. If there are loops at "sort time", you will see an error
1355 message on the main Pd window, saying "DSP loop detected (some tilde
1356 objects weren't scheduled)".</P>
1357
1358 <figure>
1359 <IMG src="resources/2.5.1.png" ALT="dsp loop error">
1360 <figcaption><u>Fig. 2.5.1</u> A DSP loop error</figcaption>
1361 </figure>
1362
1363 <P> You can build algorithms with feedback using nonlocal signal connections
1364 as explained in the <A href="2.theory.of.operation.htm#s2.5.5">2.5.5. subsection</A>.</P>
1365
1366 <P>Your subpatches can have audio inlets and outlets via the
1367 <b>[inlet~]</b> and <b>[outlet~]</b>
1368 objects (see <A href="2.theory.of.operation.htm#s2.8">2.8. Subpatches</A>).</P>
1369
1370 <H4> <A href="#s2.5.3" id="s2.5.3">2.5.3. Converting audio to and from messages</A> </H4>
1371
1372 <P>If you want to use a control value as a signal, you can use the <b>[sig~]</b>
1373 object to convert it. This is usually rare since objects mostly promote
1374 floats to signals as mentioned. At least this is true for all native objects
1375 in Pd, but there are externals that can behave differently. The <b>[sig~]</b>
1376 object is also useful for loading a default signal value with its creation argument.
1377 You can also use <b>[line~]</b> and <b>[vline~]</b>
1378 to "convert" from control to signal with a smoothing ramp, which can be quite useful.</P>
1379
1380 <P>The other direction, signal to control, requires that you specify at what
1381 moments you want the signal sampled. This is handled by the
1382 <b>[snapshot~]</b> object, but you can also sample a signal with
1383 <b>[tabwrite~]</b> and then access it via <b>[tabread]</b>
1384 or <b>[tabread4]</b> (note the missing tildes!) There are also analysis
1385 objects, the simplest of which is <b>[env~]</b>, the envelope follower,
1386 that outputs control rate floats.</P>
1387
1388 <H4> <A href="#s2.5.4" id="s2.5.4">2.5.4. Switching and blocking</A> </H4>
1389
1390 <P>You can use the <b>[switch~]</b> or <b>[block~]</b>
1391 objects to turn portions of your audio computation on and off and to control the block size
1392 of computation. There may be only one <b>[switch~]</b> or <b>[block~]</b> object
1393 per window; it acts on the entire window and all of its subwindows (which may
1394 still have their own nested <b>[switch~]</b>/<b>[block~]</b> objects though).
1395 Both <b>[switch~]</b> and <b>[block~]</b> take a block
1396 size and optional overlap and up-/downsampling factors as arguments; so for
1397 instance, [block~ 1024 4] specifies 1024 sample blocks, overlapped by a factor
1398 of 4 relative to the parent window. The <b>[switch~]</b> version carries
1399 a small computational overhead in addition to whatever overhead is associated with
1400 changing the block size.</P>
1401
1402 <P>Larger block sizes than 64 should result in a small increase of runtime
1403 efficiency. Also, the <b>[fft~]</b> and related objects operate on blocks
1404 so that setting the block size also sets the number of FFT channels. You may wish
1405 to use block sizes smaller than 64 to gain finer resolutions of message/audio
1406 interaction, or to reduce "block delay" in feedback algorithms. At the extreme,
1407 setting the block size to 1 allows you to write your own recursive filters or
1408 other DSP algorithms that require a 1-sample-feedback.</P>
1409
1410 <P>You can use <b>[switch~]</b> to budget your DSP computations.
1411 For instance you might want to be able to switch between two synthesis algorithms.
1412 To do this, put each algorithm in its own subpatch (which can have sub-subpatches in
1413 turn, for a voice bank for instance), and switch each one off as you switch the other one
1414 on. Beware of clicks; if you have a <b>[line~]</b> controlling output
1415 level, give it time to ramp to zero before you switch it off or it will be stuck at a non-zero
1416 value for the next time it comes back on.</P>
1417
1418 <P>When a subpatch is switched off, its audio outputs generate zeros, which
1419 costs a fairly small overhead. A cheaper way to get outputs is to use
1420 <b>[throw~]</b> inside the switched module and
1421 <b>[catch~]</b> outside it.</P>
1422
1423 <H4> <A href="#s2.5.5" id="s2.5.5">2.5.5. Nonlocal signal connections</A> </H4>
1424
1425 <P>You may wish to pass signals non-locally, either to get from one window to
1426 another, or to feed a signal back to your algorithm's input. This can be done
1427 using <b>[throw~]</b>/<b>[catch~]</b>, <b>[send~]</b>/<b>[receive~]</b>, or
1428 <b>[delwrite~]</b>/<b>[delread~]</b> or <b>[delread4~]</b> pairs.
1429 Both <b>[throw~]</b> and <b>[catch~]</b> implement a summing bus; <b>[throw~]</b>
1430 adds into the bus and <b>[catch~]</b> reads out the accumulated signal and
1431 zeros the bus for the next time around. There can be many <b>[throw~]</b>
1432 objects associated with a single <b>[catch~]</b>, but a
1433 <b>[throw~]</b> can't talk to more than one <b>[catch~]</b>.
1434 You can reset the destination of a <b>[throw~]</b> if you want to.</P>
1435
1436 <P>On the other hand, <b>[send~]</b> just saves a signal which may then
1437 be received by a <b>[receive~]</b> object any number of times; but a
1438 <b>[receive~]</b> can only pick up one <b>[send~]</b> at
1439 a time (you can switch between <b>[send~]</b> objects if you want though).</P>
1440
1441 <P>Don't try to <b>[throw~]</b> and <b>[catch~]</b>
1442 or <b>[send~]</b> and <b>[receive~]</b> between windows
1443 with different block sizes. The only well tested re-blocking mechanisms are
1444 <b>[inlet~]</b> and <b>[outlet~]</b>.</P>
1445
1446
1447 <P>When you send a signal to a point that is earlier in the sorted list of
1448 tilde objects, the signal doesn't get there until the next cycle of DSP
1449 computation (one block later), so your signal will be delayed by one block
1450 (1.45 msec by default). The <b>[delwrite~]</b> and
1451 <b>[delread~]</b>/<b>[delread4~]</b> have this</P>
1452
1453 same restriction, but here, the 1.45 msec are minimum attainable delay.
1454
1455 <H4> <A href="#s2.5.6" id="s2.5.6">2.5.6. Multichannel signals</A> </H4>
1456
1457 <P>As of Pd version 0.54-0, signals may be multichannel. Every signal has a
1458 <i>length</i> equal to the window's block size (64 by default), and also has a
1459 <i>channel count</i> which is 1 by default. The <b>[snake~]</b> object
1460 can combine any number of single-channel signals into a multichannel one, or alternatively
1461 can split a multichannel signal into its component single-channel ones. Non-local connections
1462 (<b>[send~]</b>, <b>[receive~]</b>,
1463 <b>[throw~]</b>, <b>[catch~]</b>,
1464 <b>[inlet~]</b> and <b>[outlet~]</b>) can be used to
1465 pass multichannel signals from window to window, and <b>[dac~]</b> and
1466 <b>[adc~]</b> can input and output several inputs or outputs into, or out of
1467 one multichannel signal.</P>
1468
1469 <P>The <b>[receive~]</b>, <b>[catch~]</b>, and
1470 <b>[adc~]</b> objects take arguments to specify the</P>
1471
1472 desired number of channels.
1473
1474 <P>Stateless objects, which have no memory from one DSP tick to the next, have
1475 all been adapted to handle multichannel inputs and outputs. The arithmetic and
1476 math objects (<b>[+~]</b>, <b>[-~]</b>,
1477 <b>[*~]</b>, <b>[/~]</b>, <b>[wrap~]</b>,
1478 <b>[sqrt~]</b> and so on) use their inputs to determine their channel counts.
1479 Binary operations like <b>[+~]</b> can combine single- and multichannel inputs.</P>
1480
1481 <P>Additionally, these objects also support multichannel signals: <b>[delread~]</b>,
1482 <b>[delwrite~]</b>, <b>[delread4~]</b>, <b>[tabread~]</b>, <b>[tabwrite~]</b>,
1483 <b>[tabread4~]</b>, <b>[tabplay~]</b>, <b>[tabsend~]</b>, <b>[tabreceive~]</b>,
1484 <b>[readsf~]</b>, <b>[writesf~]</b>, <b>[sig~]</b>, <b>[snapshot~]</b>, and <b>[print~]</b>.</P>
1485
1486 <P>Other objects, such as filters or oscillators, have not been adapted for
1487 multichannel signals, because there might be many ways to design multichannel
1488 versions of them. Instead, you can use the <b>[clone]</b> object to
1489 perform general operations on multichannel signals. Signal inputs and outputs of cloned
1490 patches can be used to distribute multichannel signals among the individual cloned
1491 patches.</P>
1492
1493 <H3> <A href="#s2.6" id="s2.6">2.6. Scheduling</A> </H3>
1494
1495 <P>Pd uses 64-bit floating point numbers to represent time, providing sample
1496 accuracy and essentially never overflowing. Time appears to the user
1497 in milliseconds.</P>
1498
1499 <H4> <A href="#s2.6.1" id="s2.6.1">2.6.1. Audio and messages</A> </H4>
1500
1501 <P>Audio and message processing are interleaved in Pd. Audio processing
1502 is scheduled every block (64 samples by default) at Pd's sample rate, which
1503 is 48000 Hz by default and results in a period of approximately 1.33
1504 milliseconds. You may turn DSP computation on and off in a patch by sending
1505 the messages "dsp 1" and "dsp 0" to "pd".</P>
1506
1507 <figure>
1508 <IMG src="resources/2.6.1.png" ALT="dsp on and off on patch level">
1509 <figcaption><u>Fig. 2.6.1</u> Setting the DSP status on the patch level</figcaption>
1510 </figure>
1511
1512 <P>In the intervals between, delays might time out or external conditions
1513 might arise (incoming MIDI, mouse clicks or whatnot). These may cause a
1514 cascade of depth-first message passing; each such message cascade is completely
1515 run out before the next message or DSP tick is computed. Messages are never
1516 passed to objects during a DSP tick; the ticks are atomic and parameter changes
1517 sent to different objects in any given message cascade take effect
1518 simultaneously.</P>
1519
1520 <P>In the middle of a message cascade, you may schedule another one at a delay
1521 of zero. This delayed cascade happens after the present cascade has finished,
1522 but at the same logical time.</P>
1523
1524 <H4> <A href="#s2.6.2" id="s2.6.2">2.6.2. Computation load</A> </H4>
1525
1526 <P>The Pd scheduler maintains a (user-specified) lead on its computations;
1527 that is, it tries to keep ahead of real time by a small amount in order to be
1528 able to absorb unpredictable, momentary increases in computation time. This
1529 is specified using the "-audiobuf" and "-blocksize" command line flags
1530 (see <A href="3.installing.configuring.htm#s3.4.1">3.4.1. Startup flags</A>).</P>
1531
1532 <P>If Pd gets late with respect to real time, gaps (either occasional or
1533 frequent) will appear in both the input and output audio streams. On the
1534 other hand, disk streaming objects will work correctly, so that you may use
1535 Pd as a batch program with soundfile input and/or output. The "-nogui"
1536 and "-send" startup flags are provided to aid in doing this.</P>
1537
1538 <P>Pd's "realtime" computations compete for CPU time with its own GUI, which
1539 runs as a separate process. A flow control mechanism will be provided someday
1540 to prevent this from causing trouble, but it is in any case wise to avoid
1541 having too much drawing going on while Pd is trying to make sound. If a
1542 sub-window is closed, Pd suspends sending the GUI update messages for it;
1543 but not so for minimized windows as of version 0.32 - you should really
1544 close them when you aren't using them.</P>
1545
1546 <H4> <A href="#s2.6.3" id="s2.6.3">2.6.3. Determinism</A> </H4>
1547
1548 <P>All message cascades that are scheduled (via <b>[delay]</b>
1549 and its relatives) to happen before a given audio tick will happen as scheduled,
1550 regardless of whether Pd as a whole is running on time; in other words, calculation
1551 is never reordered for any real-time considerations. This is done in order to make Pd's
1552 operation deterministic.</P>
1553
1554 <P>If a message cascade is started by an external event, a time tag is given
1555 to it. These time tags are guaranteed to be consistent with the times at which
1556 timeouts are scheduled and DSP ticks are computed; i.e., time never decreases.
1557 (However, either Pd or a hardware driver may lie about the physical time an
1558 input arrives; this depends on the operating system.) "Timer" objects which
1559 measure time intervals, measure them in terms of the logical time stamps of the
1560 message cascades, so that timing a <b>[delay]</b> object always
1561 gives exactly the theoretical value. (There is, however, a
1562 <b>[realtime]</b> object that measures real</P>
1563
1564 time, with nondeterministic results.)
1565
1566 <P>If two message cascades are scheduled for the same logical time, they are
1567 carried out in the order they were scheduled.</P>
1568
1569 <H3> <A href="#s2.7" id="s2.7">2.7. Semantics</A> </H3>
1570
1571 <p>This section describes how objects in Pd are created, how they store data
1572 and how object and other boxes pass messages among themselves.</p>
1573
1574 <H4> <A href="#s2.7.1" id="s2.7.1">2.7.1. Creation of objects</A> </H4>
1575
1576 <p>The text in a box has a different function depending on whether it is a message,
1577 atom (number/symbol), or object box. In message boxes, the text specifies the
1578 message or messages it will send as output. In atom boxes, the text changes
1579 at run time to show the state of the box, which is either a number or a symbol.</p>
1580
1581 <P>In an object box, as in a message box, the text specifies a message; but
1582 here, the message is to be passed to Pd itself, once, and the message's effect
1583 is to create the object in question. When you open a file, all the objects
1584 created are created using their text as "creation messages". If you type a new
1585 message into an object box (or change it), the old object is destroyed and the
1586 message is used to create the new one.</P>
1587
1588 <P>The selector of the message (the first word in the message) is a selector
1589 which Pd interprets to determine the type of object to create. Any message
1590 arguments (called "creation arguments") are used to parametrize the object
1591 being created. Thus, in <b>[makenote 64 250]</b> the selector
1592 "makenote" determines the class of object to create and the creation arguments "64"
1593 and "250" become the initial velocity and duration.</P>
1594
1595
1596 <H4> <A href="#s2.7.2" id="s2.7.2">2.7.2. Persistence of data</A> </H4>
1597
1598 <p>Among the design principles of Pd is that patches should be printable, in the
1599 sense that the appearance of a patch should fully determine its functionality.
1600 For this reason, if messages received by an object change its action, since the
1601 changes aren't reflected in the object's appearance, they are not saved as part
1602 of the file which specifies the patch and will be forgotten when the patch is
1603 reloaded. In the same way, if you delete and then recreate an object the
1604 original object's state is not retained but is instead reinitialized (possibly
1605 as specified by creation arguments).</p>
1606
1607 <P>An exception is made for subpatches whose "state" is the configuration of
1608 the subpatch; as a special case, this configuration is restored when the
1609 patch is read from a file. Also, if you rename the subpatch, for instance
1610 typing "pd jane" instead of "pd spot", the contents of the patch are preserved
1611 and only the text in the object box and the window title of the subpatch are
1612 changed.</P>
1613
1614 <P>It is probably bad style to specify creation arguments ala
1615 <b>[makenote 64 250]</b> if you are going to override them later;
1616 this is confusing to anyone who tries to understand the patch.</P>
1617
1618 <H4> <A href="#s2.7.3" id="s2.7.3">2.7.3. Message passing</A> </H4>
1619
1620 <p>Messages in Pd consist of a selector (a symbol) and zero or more arguments
1621 (which may be symbols or numbers). To pass a message to an object, Pd first
1622 checks the selector against the class of the object. Message boxes all are
1623 of one class and they all take the same incoming messages and dispense them
1624 according to their state, that is, the text typed into the box. The same
1625 holds for atom boxes (number or symbol) except that their state may change
1626 (it consists of the number or symbol showing).</p>
1627
1628 <P>Object boxes may have many different classes. The class is usually
1629 determined by the selector of the creation message, i.e., the first atom of the
1630 creation message which is usually a symbol.</P>
1631
1632 <P>Each class comes with a fixed collection of messages it may be sent. For
1633 example, the <b>[float]</b> or <b>[f]</b>
1634 object takes "bang" and "float". These messages are sent to <b>[float]</b>
1635 objects (objects whose class is float) via the leftmost,</P>
1636
1637 hot inlet (the right inlet is a separate, auxiliary object). Objects of
1638 class "float" respond to the message "bang" by outputting their current value,
1639 that is, by sending a "float" message to their outlet. They respond to "float"
1640 messages by setting their value and then outputting it.
1641
1642 <P>Each other class (like <b>[float]</b>) in Pd has its
1643 own protocol for responding to messages it is sent, and may take "float" and "bang"
1644 messages, or others in addition or instead of them.</P>
1645
1646
1647 <H4> <A href="#s2.7.4" id="s2.7.4">2.7.4. Inlets and lists</A> </H4>
1648
1649 <P>Most objects have connection inputs at the top (represented as a dark rectangle).
1650 The leftmost one is the main input inlet and represents the object itself. An object
1651 may have other secondary inlet inputs, but each is a separate object called an "inlet".
1652 There are 4 different inlet classes in Pd for these secondary inputs. The class of the
1653 inlet determines the type of message it will accept: symbol, float, pointer or signal;
1654 and the inlet passes the message either to the object itself or to a proxy, usually
1655 one created by the object for the occasion. The proxy can then receive any kind of
1656 message (such as a bang or list) and direct it to the object. The main input can
1657 receive any kind of message and you can add special methods for them. This includes
1658 <i>signal</i>, <i>float</i>, <i>symbol</i>, <i>pointer</i>, <i>bang</i>, <i>list</i>
1659 and <i>anything</i>.</P>
1660
1661 <P>Unless a "list" method is specified for the main inlet, objects respond to "list"
1662 messages by distributing their atoms sequentially across the main inlet and secondary
1663 inlets (if any). If there's just a single input for the object (that is, no secondary
1664 inlets for extra inputs), the first atom element of the list is passed to the object.
1665 Hence, a list of floats is truncated to the first float and is effectively a "float"
1666 message. The same happens for other atom types ("symbol" and "pointer").</P>
1667
1668 <P>In the case of many inlets and a list with many atoms, each atom is passed according
1669 to its type to each input. Here's a simple example with the <b>[/]</b> object. The object
1670 has a main inlet and a secondary inlet. It has no list method, hence, if you feed it with
1671 a list of two float atoms, they are distributed to each input. See picture below.</P>
1672
1673 <figure>
1674 <IMG src="resources/2.7.1.png" ALT="List distribution">
1675 <figcaption><u>Fig. 2.7.1</u> Distribution of lists between inlets</figcaption>
1676 </figure>
1677
1678 <H4> <A href="#s2.7.5" id="s2.7.5">2.7.5. Special cases for 0/1-element lists</A> </H4>
1679
1680 <p>A zero element list, that is a list message with only the "list" selector, is
1681 treated as a "bang" message. If you look at it the other way around, you can also
1682 say that a bang is en empty or zero element list! This is better exposed in the
1683 help file of the <b>[list]</b> object. Take, for instance, <b>[list append]</b>,
1684 which appends an incomming list on the main inlet to a list sent to the secondary
1685 inlet or via the object's argument. A bang to the main inlet sends an empty list
1686 and outputs the list from the secondary inlet or arguments, while a bang into the
1687 secondary inlet clears the stored list.</p>
1688
1689 <p>As mentioned in the last subsection, lists are distributed via inlets when
1690 there's not a list method. Hence, a "list 1" message sent to an object that
1691 only takes floats and not lists (such as the <b>[float]</b> object) will work
1692 by effectively converting the list to a float. Even though Pd can differentiate
1693 a list with one float and a float message, it is the common sense that both are
1694 actually the same and interchangeable. Therefore, you can send a float message
1695 to an object that handles lists, like the <b>[list]</b> object.</p>
1696
1697 <p>One way this is better exposed in Pd is when trying to print a zero or one
1698 element list. The figure below shows how a "list" message is converted to a
1699 "bang", a "list 1" will not print as a float because the selector is also
1700 implicit, but you can prove it's treated as a float with the <b>[route]</b>
1701 object. You can also see how a "list hi" message becomes "symbol hi".</p>
1702
1703 <figure>
1704 <IMG src="resources/2.7.2.png" ALT="Special List cases">
1705 <figcaption><u>Fig. 2.7.2</u> Special cases of 0/1-element lists</figcaption>
1706 </figure>
1707
1708 <H4> <A href="#s2.7.6" id="s2.7.6">2.7.6. Dollar signs</A> </H4>
1709
1710 <p>In message or object boxes, message arguments starting with a dollar sign
1711 and a number (like "$1" or "$3-bazoo") are variables which are substituted with
1712 values supplied as part of the environment the message is passed in. In the case
1713 of message boxes, the environment consists of the arguments of the "list" message
1714 (possibly extrapolated from "bang", "float", or other) that the message box is
1715 responding to. Thus, if a message box gets "23 skidoo" and if it contains the
1716 text, "$2 until $1", out comes the message, "skidoo until 23".</p>
1717
1718 <P>Object boxes contain text which forms a message to be sent to Pd to create
1719 and initialize the object. Here, $1, etc., are taken from the context in which
1720 the patch was loaded. When the patch is a new document or opened from a file
1721 the "$" variables are undefined. But if the patch is an abstraction (see the
1722 next section) they are taken from the abstractions' creation arguments.</P>
1723
1724 <P>Constructions such as "$1-x" are expanded by string concatenation. This
1725 is the mechanism for making local variables. In particular, $0 is a counter,
1726 where every patch gets its own value. In an abstraction this guarantees a unique
1727 ID number to that abstraction, so sends and receives with names like "$0-bear"
1728 can be used as local send/receive pairs. This is also useful for things like
1729 array names, variable names in <b>[value]</b> objects and text names (as defined
1730 in the <b>[text]</b> object).</P>
1731
1732 <P>Occasionally, you may want to have double or triple substitutions; this can
1733 be done one stage at a time by nesting abstractions (with each subpatch
1734 adding its own $-variable to a symbol and passing that on as argument to a
1735 further abstraction).</P>
1736
1737 <P>For example, if you want to get dog-food, dog-ears, and cat-food, for
1738 example, have an abstraction "a1" that invokes an abstraction "a2" twice, as
1739 "a2 $1-food" and "a2 $1-ears", and then in a third patch call a1 twice, as
1740 "a1 cat" and "a1 dog". Inside the four "a2" copies, $1 will evaluate to
1741 "dog-food", "cat-food", "dog-ears", and "cat-ears".</P>
1742
1743 <P>In the case of IEMguis, you can set a receive and/or send name via a message.
1744 Note that if you want to use the "$0" counter in this case you have to escape
1745 it with a backslash (see <A href="2.theory.of.operation.htm#s2.4.5">2.4.5. Escaping characters</A>).
1746 This is needed so the object receives a literal and unexpanded '$0' symbol to store
1747 when the patch is saved. Examples are given in their help files.</P>
1748
1749 <H3> <A href="#s2.8" id="s2.8">2.8. Subpatches</A> </H3>
1750
1751 <p>Pd offers two mechanisms for making subpatches, called "one-off subpatches"
1752 and "abstractions". In either case the subpatch appears as an object box
1753 in a patch. If you type <b>[pd]</b> or <b>[pd my-name]</b> into an object box,
1754 this creates a one-off subpatch. For instance, in this fragment:</p>
1755
1756 <figure>
1757 <IMG src="resources/2.8.1.png" ALT="subpatch">
1758 <figcaption><u>Fig. 2.8.1</u> A subpatch called "my-subpatch"</figcaption>
1759 </figure>
1760
1761 <p>The box in the middle, if clicked on, opens the subpatch shown here:</p>
1762
1763 <figure>
1764 <IMG src="resources/2.8.2.png" ALT="open subpatch window">
1765 <figcaption><u>Fig. 2.8.2</u> The insides of the subpatch</figcaption>
1766 </figure>
1767
1768 <P>The contents of the subpatch are saved as part of the parent patch, in
1769 one file. If you make several copies of a subpatch you may change them
1770 individually.</P>
1771
1772 <P>The objects <b>[inlet]</b>, <b>[inlet~]</b>, <b>[outlet]</b> and <b>[outlet~]</b>,
1773 when put in a subpatch, create inlets and outlets for the object box containing the
1774 subpatch. This works equally for one-off subpatches and abstractions and only accept
1775 control data messages. The <b>[inlet~]</b> and <b>[outlet~]</b> versions create inlets
1776 and outlets for audio signals. Note you can also mix control messages in an <b>[inlet~]</b>
1777 via its right outlet, but a signal outlet only takes signals. Inlets and outlets
1778 appear on the invoking box in the same left-to-right order as they appear in the
1779 subpatch.</P>
1780
1781 <H4> <A href="#s2.8.1" id="s2.8.1">2.8.1. Abstractions</A> </H4>
1782
1783 <P>To make an abstraction, save a patch with a name such as "abstraction1.pd"
1784 and then invoke it in an object box as <b>[abstraction1]</b>:</P>
1785
1786 <figure>
1787 <IMG src="resources/2.8.3.png" ALT="abstraction">
1788 <figcaption><u>Fig. 2.8.3</u> An abstraction (a patch file loaded as an object)</figcaption>
1789 </figure>
1790
1791 <P>Here, we're invoking a separate file named "abstraction1.pd", which holds the
1792 patch shown here:</P>
1793
1794 <figure>
1795 <IMG src="resources/2.8.4.png" ALT="abstraction example">
1796 <figcaption><u>Fig. 2.8.4</u> The insides of the <b>[abstraction1]</b> abstraction</figcaption>
1797 </figure>
1798
1799 <p>You may create many instances of <b>[abstraction1]</b> or invoke it from different
1800 patches. Changing and saving the contents of <b>[abstraction1]</b> will affect all
1801 invocations of it as they are created. An analogy from the "c" programming
1802 language is that one-off subpatches are like bracketed blocks of code and
1803 abstractions are like subroutines.</p>
1804
1805 <P>Abstractions are instantiated by typing the name of a patch (minus the ".pd"
1806 extension) into an object box. You may also type arguments; for instance if
1807 you have a file "my-abstraction.pd" you may have <b>[my-abstraction 5]</b> to set the
1808 variable "$1" to 5. This is defined only for object boxes (not for messages) in
1809 the abstraction. For message boxes, "$1", etc, have a different meaning as
1810 described above, so note that dollar signs are expanded at a different time in
1811 an object box than in a message box. In an object box, the "$" argument is
1812 expanded at creation time, and in a message box, at message time. If you want
1813 to send a message with a "$1" in the sense of a creation argument of an
1814 abstraction, you must generate it with an object box such as [float $1],
1815 [symbol $1], or perhaps [pack $1 $2], which may then be sent to a message box.</P>
1816
1817 <P> The <b>[pdcontrol]</b> object has an alternative strategy for retrieving arguments
1818 in an abstraction with the 'args' message, which makes the object output a list
1819 with all argument values. This has the advantage of being able to get a variable
1820 number of arguments, as well as varying their atom type.</P>
1821
1822 <P>A <b>[clone]</b> object is provided to automatically create and manage multiple copies
1823 of an abstraction. You can use it to make voice banks for polyphonic synthesis,
1824 for example.</P>
1825
1826 <P>Complex patches often have many subpatches. If you want to close all
1827 open subpatch windows, you can use the "Close subwindows" entry in the<b>Window
1828 menu</b>. Similarly, you can use the "Parent Window" entry to easily focus the
1829 parent patch.</P>
1830
1831 <H4> <A href="#s2.8.2" id="s2.8.2">2.8.2. Graph-on-parent subpatches</A> </H4>
1832
1833 <p>If you open the "properties" dialog for a subpatch or an abstraction, you can
1834 check the "graph on parent" box to have the controls of the subpatch/abstraction
1835 appear on the parent. For instance, here is an invocation of <b>[abstraction2]</b>:</p>
1836
1837 <figure>
1838 <IMG src="resources/2.8.5.png" ALT="graph-on-parent abstraction">
1839 <figcaption><u>Fig. 2.8.5</u> An abstraction with "Graph-on-Parent" enabled</figcaption>
1840 </figure>
1841
1842 <p>Where the patch "abstraction2.pd" contains:</p>
1843
1844 <figure>
1845 <IMG src="resources/2.8.6.png" ALT="inside graph-on-parent abstraction">
1846 <figcaption><u>Fig. 2.8.6</u> The insides of the "Graph-on-Parent" <b>[abstraction2.pd]</b> abstraction</figcaption>
1847 </figure>
1848
1849 <p>Here, the number box in the abstraction shows up on the box that invoked
1850 the abstraction. The "Graph-On-Parent" flag is set in the abstraction
1851 (and is saved as part of the abstraction); to set it, open the "Properties"
1852 dialog for the "abstraction2" canvas by right-clicking on any white space
1853 in the patch.</p>
1854
1855 <P>To open the subpatch, right click on the object and select "Open". It doesn't
1856 work just to click on the object in run mode since clicks are sent to visible
1857 controls and/or arrays.</P>
1858
1859 <P>When the subpatch is closed, all controls in it appear on the object
1860 instead; so the number box in the subpatch in the example above is the same
1861 one as you see in the box. Only controls are made visible in this way.</P>
1862
1863
1864 <H3> <A href="#s2.9" id="s2.9">2.9. Arrays</A> </H3>
1865
1866 <p>Linear arrays of numbers recur throughout the computer musician's bag of
1867 tricks, beginning with the wavetable oscillator. The wavetable oscillator later
1868 was reinvented as the looping sampler. Also, table lookup is used for nonlinear
1869 distortion of audio signals. In the domain of control, arrays of numbers
1870 can specify control mappings, probability densities, voicing data, and much
1871 more.</p>
1872
1873 <P>Arrays in Pd should be allocated (and possible read in from a file) before
1874 beginning to make sound, since memory allocation and disk operations may take
1875 long enough to cause audio buffer overruns or underruns. Pd provides two ways
1876 to define new arrays, as "graphs" and "tables". In either case, the array
1877 has a predefined name and size (i.e., number of points). Elements of the
1878 array are stored as floating-point numbers, 4 bytes apiece.</P>
1879
1880 <P>If you use an array to store a one-second sound at 48 kHz, you will need
1881 192 kilobytes, for a one-minute sound 11.5 megabytes. To store a sound with
1882 two or more channels, use a separate array for each channel.</P>
1883
1884 <P>Arrays are also useful as transfer functions, for example for nonlinear
1885 distortion of an audio signal, or to map a control onto a synthesis parameter.
1886 In situations like this, one typically uses much shorter arrays of no more
1887 than a few hundred elements. They are also useful for storing measured
1888 spectra derived from the fft~ objects, and probably for many other uses.</P>
1889
1890 <P>Arrays usually appear within subpatches created to house them, whether
1891 in "graph on parent" form (so that you see them within a rectangle drawn on
1892 the containing patch), or as a regular subpatch (which you see as a text box).
1893 In the "graph on parent" form, an array appears as shown:</P>
1894
1895 <figure>
1896 <IMG src="resources/2.9.1.png" ALT="array">
1897 <figcaption><u>Fig. 2.9.1</u> An array</figcaption>
1898 </figure>
1899
1900 <P>Arrays are indexed from 0 to N-1 where N is the number of points in the array.
1901 You can use objects to read and write arrays and manipulate them in many ways.</P>
1902
1903 <figure>
1904 <IMG src="resources/2.9.2.png" ALT="array indexing">
1905 <figcaption><u>Fig. 2.9.2</u> Reading an array with <b>[tabread]</b></figcaption>
1906
1907 </figure>
1908
1909 <p>Here, we see that the third point of the array (index 2) has the value '0.385'.
1910 To write into the array, you can use the <b>[tabwrite]</b> object:</p>
1911
1912 <figure>
1913 <IMG src="resources/2.9.3.png" ALT="setting an value in an array">
1914 <figcaption><u>Fig. 2.9.3</u>Writing to an array with <b>[tabwrite]</b></figcaption>
1915 </figure>
1916
1917 <p>In this example, sending the message sets the third element to 0.5. (You
1918 may also send the two numbers to the two inlets separately.)</p>
1919
1920 <P>The two previous examples showed control operations to read and write from
1921 and to arrays. These may also be done using audio signals. For example,
1922 the patch below creates a 440 Hz tone with "array1" as a waveform:</P>
1923
1924 <figure>
1925 <IMG src="resources/2.9.4.png" ALT="setting an array with a waveform">
1926 <figcaption><u>Fig. 2.9.4</u> Using signals to read an array with <b>[tabread4~]</b></figcaption>
1927 </figure>
1928
1929 <p>Here, <b>[phasor~]</b> outputs a ramp whose output range is from 0 to 1, repeating
1930 440 times per second. The multiplier and adder adjust the range from 1 to 11
1931 and then the values are used as indices for <b>[tabread4~]</b>, which is a 4-point</p>
1932
1933 interpolating table lookup module. (Much more detail is available in the
1934 "3.audio.examples" series in the documentation folder.)
1935
1936 <P>To create a new array, select "array" from the <span class="pdobj">Put menu</span>. A dialog
1937 will appear to set initial properties of the array. By default, a new graph is
1938 created to hold the array, but it may also be housed in the most recently
1939 created graph instead. Other properties may be specified there and/or changed
1940 later using the "Properties" dialog.</P>
1941
1942 <P>If you select "Properties" on an array in a graph, you get two dialogs, one
1943 for the array and one for the graph. The array dialog looks like this:</P>
1944
1945 <figure>
1946 <IMG src="resources/2.9.5.png" ALT="array properties window">
1947 <figcaption><u>Fig. 2.9.5</u> The array properties dialog</figcaption>
1948 </figure>
1949
1950
1951 <p>You may use this to change the name and size, in addition to another property,
1952 "Save contents". If "Save contents" is selected, the array's values are stored
1953 in the containing patch; otherwise they're initialized to zero each time the
1954 patch is reloaded. If you intend to use arrays to store sounds, you will
1955 probably not wish to store them in the patch but as separate soundfiles. This
1956 will be more efficient and you may also then use a sound editor to modify them
1957 outside Pd.</p>
1958
1959 <P>If you check "Delete array" and then "OK", the array will be deleted. This
1960 is an odd interface for deleting an object, and is only provided because Pd
1961 lacks a mechanism for selecting arrays (so that "cut" could serve this purpose).</P>
1962
1963 <P>The graph dialog (which also pops up) is shown here:</P>
1964
1965 <figure>
1966 <IMG src="resources/2.9.6.png" ALT="graph properties">
1967 <figcaption><u>Fig. 2.9.6</u> The canvas properties dialog</figcaption>
1968 </figure>
1969
1970 <P>The X bounds initially range from 0 to the number of points in the table
1971 minus one (this is a good choice for arrays, although graphs holding other
1972 kinds of objects might require other X bounds). The Y bounds should be
1973 chosen to reflect the natural range of the table, so that stored sounds
1974 would naturally range from -1 to 1, but a sequence of frequency values might
1975 range from 0 to 20000. Finally, you choose the width and height of the graph
1976 in pixels.</P>
1977
1978 <P>Many other operations are defined for arrays; see the related patches
1979 in the tutorial (starting at 2.control/15.array.pd) for more possibilities.</P>
1980
1981 <H3> <A href="#s2.10" id="s2.10">2.10. Data structures</A> </H3>
1982
1983 <p>(Note: this section is an adapted and updated version of an article
1984 submitted to ICMC 2002.)</p>
1985
1986 <P>The original idea in developing Pd was to make a real-time computer music
1987 performance environment like Max, but somehow to include also a facility for
1988 making computer music scores with user-specifiable graphical representations.
1989 This idea has important precedents in Eric Lindemann's Animal and Bill Buxton's
1990 SSSP. An even earlier class of precedents lies in the rich variety of paper
1991 scores for electronic music before it became practical to offer a
1992 computer-based score editor. In this context, scores by Stockhausen (<I>
1993 Kontakte</I> and <I>Studie II</I>) and Yuasa (<I>Toward the Midnight Sun</I>)
1994 come most prominently to mind, but also Xenakis's <I>Mycenae-alpha</I>, which,
1995 although it was realized using a computer, was scored on paper and only
1996 afterwards laboriously transcribed into the computer.</P>
1997
1998 <P>Pd is designed to to offer an extremely unstructured environment for
1999 describing data structures and their graphical appearance. The underlying
2000 idea is to allow the user to display any kind of data, associating it in
2001 any way with the display. To accomplish this Pd introduces a graphical
2002 data structure, somewhat like a data structure out of the C programming
2003 language, but with a facility for attaching shapes and colors to the data,
2004 so that the user can visualize and/or edit it. The data itself can be edited
2005 from scratch or can be imported from files, generated algorithmically, or
2006 derived from analyses of incoming sounds or other data streams.</P>
2007
2008 <P>There's a tutorial section dedicated to Data Structures (4.data.structures)
2009 with many examples. Here is one simple example from this series (09.sequencer.pd)
2010 with a very short musical sketch realized using Pd:</P>
2011
2012 <figure>
2013 <IMG src="resources/2.10.1.png" ALT="graphical score">
2014 <figcaption><u>Fig. 2.10.1</u> A graphical score with Data Structures</figcaption>
2015 </figure>
2016
2017 <P>The example, which only lasts a few seconds, is a polyphonic collection of
2018 time-varying noise bands. The graphical "score" consists of six objects, each
2019 marked with a small blue rectangle at left and with data shapes: a black shape
2020 to show dynamic and a colored shape to show changing frequency and bandwidth.
2021 The horizontal axis represents time and the vertical axis, frequency (although,
2022 as explained later, this behavior isn't built into Pd). The dynamic and frequency
2023 shapes aren't constrained to be connected or even to be proximate, but since they
2024 pertain to the same sound their horizontal positions line up. In this example the
2025 last (furthest-right) object is percussive (as seen by the black shape) and has a
2026 fixed frequency and bandwidth, whereas the large, articulated shape in the center
2027 has a complicated trajectory in both frequency and amplitude. The color of the
2028 frequency has no purpose, but could be used to determine a voice number to route it.</P>
2029
2030 <P>Each object is thus composed of a combination of scalar values (color;
2031 aggregate position in X and Y coordinates) and array values (time and envelope
2032 pairs for the black traces and time, frequency and bandwidth triples for the
2033 colored ones). This is all specified by the user using Pd's "template"
2034 mechanism. Here is the template associated with the graphical objects shown
2035 above.</P>
2036
2037 <figure>
2038 <IMG src="resources/2.10.2.png" ALT="template for graphical score">
2039 <figcaption><u>Fig. 2.10.2</u> The "struct" and drawing instructions for the score's elements</figcaption>
2040 </figure>
2041
2042 <p>Templates consist of a data structure definition (the <b>[struct]</b>
2043 object) and zero or more drawing instructions (such as <b>[filledpolygon]</b>
2044 and <b>[plot]</b>). The <b>[struct]</b> object gives the template the name
2045 "template-event". The data structure</p>
2046
2047 is defined to contain three floating point numbers named "chapter", "y", and "color",
2048 and two arrays, one named "pitch" whose elements belong to another template
2049 named "template-pitch", and similarly for the array "amp" (both data structures
2050 contain three floating point numbers named "chapter", "y", and "w", for x/y position
2051 and width.)
2052
2053 <P>In general, data structures are built from four data types: scalar floats
2054 and symbols, text and arrays (whose elements share another, specified template).
2055 The contents of a Pd window themselves form a list. <A href="2.theory.of.operation.htm#s2.9">Arrays</A>
2056 are actually implemented as a top-level data structure array, whose elements are
2057 scalars containing a single floating-point number.</P>
2058
2059 <P>Data structures in Pd may nest arbitrarily deeply using the array and text
2060 types. For example, a collection of sinusoidal tracks from an analysis engine
2061 could be implemented as an array of arrays of (pitch, amplitude) pairs.</P>
2062
2063 <P>After the <b>[struct]</b> object in the template shown above,
2064 the remaining three objects are <I>drawing instructions</I>, first for a rectangle (with the
2065 <b>[filledpolygon]</b> object), and then for two arrays (with the
2066 <b>[plot]</b> objects). The various graphical attributes that are
2067 specified for drawing instructions
2068 may be numerical constants or data structure field names; in the latter case
2069 the value varies depending on the data. For instance, the second creation
2070 argument to <b>[plot]</b> is the color. The first one plots
2071 "pitch" using the color "color". In this way the color is attached to the "color"
2072 slot in the data structure, so that color will vary according to its "color" slot.
2073 The second <b>[plot]</b> plots the "amp" field and the color is
2074 given as 0, which is black.</P>
2075
2076
2077 <H4> <A href="#s2.10.1" id="s2.10.1">2.10.1. Traversal</A> </H4>
2078
2079 <P>Pd objects are provided to traverse lists and arrays, and to address elements
2080 of data structures for getting and setting. Pd has no built-in sequencer, nor
2081 even any notion that "chapter" values should be used as a time axis. (However, a
2082 "sort" function is provided, which reorders a list from left to right, on the
2083 assumption that users might often want to use Pd data collections as x-ordered
2084 sequences.) Recording sequences of events into lists, and/or playing the lists
2085 back as sequences, are functionalities that the user is expected to supply on
2086 top of Pd's offerings, which, it is hoped, would allow those functionalities
2087 within a much larger range of possibilities, to include random re-orderings of
2088 events, score following, self-modifying scores, reactive improvisation, and
2089 perhaps much more.</P>
2090
2091 <P> Here is a screenshot of the subpatch that implements the graphical sequence
2092 score shown above. It takes a 'start' or 'stop' message and the sequencing is
2093 done in the [pd sequence] subpatch. It also uses the <b>[clone]</b> object to
2094 instantiate different copies of the <b>[voice]</b> abstraction, which is
2095 responsible for synthesizing each voice from the score.</P>
2096
2097 <figure>
2098 <IMG src="resources/2.10.3.png" ALT="score playing subpatch">
2099 <figcaption><u>Fig. 2.10.3</u> The subpatch that plays the graphcal score</figcaption>
2100 </figure>
2101
2102 <P>Traversal of data is made possible by the special "pointer" atom.
2103 Unlike numbers and symbols, pointers have no printed form and thus can't be
2104 uttered in message boxes. Traversal objects such as <b>[pointer]</b> and
2105 <b>[get]</b>(among several others) can generate or use pointers. The pointer
2106 data type is also integrated into pipe-fitting objects such as <b>[pack]</b>,
2107 <b>[unpack]</b>, and <b>[route]</b>. The <b>[trigger]</b> object also deals
2108 with pointers.</P>
2109
2110 <figure>
2111 <IMG src="resources/2.10.4.png" ALT="[pd sequence] subpatch">
2112 <figcaption><u>Fig. 2.10.4</u> The sequencing subpatch</figcaption>
2113 </figure>
2114
2115 <P>In the [pd sequence] subpatch shown above, a first <b>[pointer]</b> object
2116 is used to traverse through the data. It first takes a "traverse" message
2117 (sent from the parent) to set it to the head of the list (named "pd-data"),
2118 and "next" messages to move to (and output) the next datum in the list
2119 (i.e., the next in the list of six objects in the score).</P>
2120
2121 <P>A second <b>[pointer]</b> object is used here as a storage cell for pointers
2122 just as <b>[float]</b> is for numbers. The center of the sequencer is the
2123 <b>[delay]</b> object, which must be fed the time difference between each
2124 event (including the non-event of hitting "start") and the next.</P>
2125
2126 <P>The time difference needed to set the <b>[delay]</b> object is obtained using the
2127 <b>[get template-event]</b> object with the 'x' field. This is converted to incremental
2128 time with <b>[-]</b>, corrected for tempo, and fed to the <b>[delay]</b> object. Pd provides
2129 the <b>[get]</b> and <b>[set]</b> objects for reading and writing values from data structures.
2130 The <b>[get]</b> object shown here obtains the "chapter" and "y" fields of the current object.
2131 The template name (template-event) is supplied to the <b>[get]</b> objects so that they can
2132 look up the offset of the necessary field(s) in advance, for greater run-time efficiency.</P>
2133
2134 <P> As we extract each of the six objects in the score, we must wait the delay for playing
2135 that object. Once the delay time has expired, the object's pointer is recalled with the second
2136 <b>[pointer]</b> object and packed with the pitch base value to cloned instances of the
2137 <b>[voice]</b> abstraction (for that a 'next' message is prepended to the list, which is
2138 needed by <b>[clone]</b>). Let's check the <b>[voice]</b> abstraction below.</P>
2139
2140 <figure>
2141 <IMG src="resources/2.10.5.png" ALT="[voice] abstraction">
2142 <figcaption><u>Fig. 2.10.5</u> The cloned <b>[voice]</b> abstraction with sound synthesis</figcaption>
2143 </figure>
2144
2145 <P>The pointer and pitch value are unpacked. The pointer value is sent to <b>[data-array]</b>
2146 abstractions, which extract the pitch and dynamic breakpoints from the arrays (specified as
2147 the abstraction's argument,) so it contains two sub-sequencers itself. The nesting of
2148 the overall structure of the sequencer patch mirrors the nesting of the original data
2149 structures. Let's have a look at the <b>[data-array]</b> abstraction below.</P>
2150
2151 <figure>
2152 <IMG src="resources/2.10.6.png" ALT="[data-array] abstraction">
2153 <figcaption><u>Fig. 2.10.6</u> The <b>[data-array]</b> abstraction</figcaption>
2154
2155 </figure>
2156
2157 <P>We have to inspect the object itself to know the delay before playing it.
2158 So, in the loop, we peel off the first remaining object to play and inspect
2159 the time difference between it and the previous one, using this value to set
2160 the <b>[delay]</b> object.</P>
2161
2162 <P>More general patches can easily be constructed which access heterogeneous
2163 lists of objects (having different templates). In this way, an arbitrarily
2164 rich personal "score language" can be developed and sequenced.</P>
2165
2166 <H4> <A href="#s2.10.2" id="s2.10.2">2.10.2. Accessing and changing data</A> </H4>
2167
2168 <P>In general, accessing or changing data is done via "pointers" to "scalars".
2169 Numbers and symbols within scalars are accessed using the <b>[get]</b> object and
2170 changed, in the same way, using <b>[set]</b>. Since lists and arrays are composed of</P>
2171
2172 scalars, every actual number or symbol in a data heap will be a number or symbol
2173 element of some scalar. To access them, it suffices to have objects to chase
2174 down elements of lists and arrays (given either a global name or a pointer to
2175 the containing scalar).
2176
2177 <P>Lists are traversed in the way shown above; to get to a sublist of a scalar,
2178 the <b>[get]</b> object will provide a pointer, in the same way as it provides "float"
2179 or "symbol" elements of scalars. For arrays, an <b>[element]</b> object is provided</P>
2180
2181 which, given a scalar, a field name and a number, chases down the numbered,
2182 scalar, element of the named array field.
2183
2184 <P>To alter "float" or "symbol" elements of scalars is straightforward
2185 using the <b>[set]</b> object, but arrays and lists can't be set by assignment;</P>
2186
2187 there is no suitable data type available within messages. Lists could
2188 possibly be "settable" by passing pointers to other lists, but permitting this
2189 would have required either automatically doing deep copies of data structures
2190 to carry out the assignments, or else implementing a garbage collecting memory
2191 management system, either of which would be difficult to realize within
2192 real-time computation time constraints. Instead, all the data hanging from a
2193 scalar is considered as belonging to that scalar, and is left in memory until
2194 the scalar is deleted; the data may be changed atom by atom, but primitives
2195 are not provided which would imply unpredictable execution times.
2196
2197 <P>The <b>[getsize]</b> and <b>[setsize]</b> objects are provided to access or change
2198 the number of elements in the array. For lists, an <b>[append]</b> object
2199 appends a new scalar for a given template to a list, after the element pointed
2200 to. (To insert a scalar at the beginning of a list, the pointer can be set to
2201 the "head" of the list, a formal location before the first list item.)
2202 Deletion is less flexible; the only operation is to delete an entire list.
2203 (There's no reason not to provide finer-grain deletion mechanisms except that
2204 it's not clear how to protect against stale pointers efficiently, except by
2205 voiding the entire collection of pointers into a list.)</P>
2206
2207 <H4> <A href="#s2.10.3" id="s2.10.3">2.10.3. Editing</A> </H4>
2208
2209 <P>The graphical score shown above can be edited by dragging breakpoints, or
2210 by adding and deleting them, using mouse clicks. Also, entire objects or
2211 collections of them may be copied, pasted, and dragged around the screen.
2212 Alternatively, there is an editable (or computer generate-able or parse-able)
2213 text representation for the data, which may be seen or changed in a dialog
2214 window or read and written to external text files.</P>
2215
2216 <P>Since the graphical presentation of data objects is determined by drawing
2217 instructions, the drawing instructions are interpreted backward to alter data
2218 as a result of mouse operations. If a given graphical dimension is controlled
2219 by a variable, that variable is then controlled by dragging along that
2220 dimension; if the dimension is constant, it can't be altered by dragging.</P>
2221
2222 <P>Tricky situations can arise when the user changes the contents of templates.
2223 A change in drawing instructions can be accommodated by simply tracking
2224 down and redrawing all data objects using the template. However, changing
2225 the <b>[struct]</b> object itself make for less straightforward situations. The
2226 user might wish to reorder fields, delete them, add new ones, or rename them.
2227 When a <b>[struct]</b> object changes, Pd automatically conforms the data from the old
2228 structure to the new one. Fields with the same name as previously are maintained
2229 (reordering them as necessary) and if a field disappears but another of the
2230 same type appears, the new one(s) are taken to be renamings of the old one(s)
2231 in order of appearance. New fields which cannot be matched in this way with
2232 previously existing ones are assumed to be new and are initialized.</P>
2233
2234 <P>It can happen that two <b>[struct]</b> objects compete to define the same data
2235 structure, or that the user reads in data from a file which expects a different
2236 version of the structure, or alternatively, that the <b>[struct]</b> object for
2237 existing data objects disappears. For this reason, Pd maintains a private
2238 representation of the last active version of a <b>[struct]</b> until all
2239 similarly named "structs", as well as all data using that "struct", have
2240 disappeared. If the user introduces a new version of the "struct" and only
2241 later deletes the "current" one, the data is only conformed to the new version
2242 once the old one is deleted. In this way we avoid getting into situations
2243 where data is left hanging without its structure definition, or where data ends
2244 up belonging to two or more structures of the same name. The worst that can
2245 happen is that data may lose their drawing instructions, in which case Pd
2246 supplies a simple default shape.</P>
2247
2248 <H4> <A href="#s2.10.4" id="s2.10.4">2.10.4. Limitations</A> </H4>
2249
2250 <P>When examples get more complicated and/or dense than the one shown here, it
2251 becomes difficult to see and select specific features of a data collection;
2252 more work is needed to facilitate this. There should be some facility for
2253 turning drawing instructions on and off, or perhaps for switching between versions
2254 of a template, depending on the user's desired view. There should also be a
2255 callback facility in the template for when an object is edited with the mouse, so
2256 that the user can bind actions to mouse clicks.</P>
2257
2258 <P>More generally, the collection of traversal objects that Pd provides is
2259 adequate to support a variety of modes of data collection and use, such as
2260 analysis and sequencing. But the patches required to traverse the data
2261 collections are not always simple. It would be desirable to find a more
2262 straightforward mechanism than that provided by the <b>[pointer]</b>, <b>[get]</b>
2263 and <b>[set]</b> objects.</P>
2264
2265 <P>The "data" facility, although part of the original plan for Pd, has only
2266 recently been implemented in its current form, and as (hopefully) the user base
2267 grows there will surely be occasions for many further extensions of the data
2268 handling primitives and the graphical presentation and editing functions.</P>
2269
2270
2271 <H3> <A href="#s2.11" id="s2.11">2.11. Pd vs. MAX </A> </H3>
2272
2273 <P> You may be aware that Miller Puckette, the creator and author of Pd, was also
2274 the original creator and author of MAX, which was developed in the 1980s
2275 at IRCAM. Pd was designed later with first drafts from 1996 and it does resemble
2276 the MAX system. This section addresses the relationship between the two
2277 environments.</P>
2278
2279 <P> Some external objects and libraries for MAX are also provided for Pd (such
2280 as 'Flucoma', 'FFTease', 'soundhack' and more). This depends on the will and intent
2281 of the external developer though. In the early days, it was easier to design
2282 externals that could run in both systems, but the APIs diverged over the years.</P>
2283
2284 <H4> <A href="#s2.11.1" id="s2.11.1"> 2.11.1. Differences between Pd and MAX</A> </H4>
2285
2286 <P> Although Pd wasn't intended to be a MAX clone, there were many similarities in
2287 its origin and some effort had been undertaken to make the two interoperable.
2288 It was possible to import and export patches from and to MAX/MSP; you just needed to
2289 save as text to a file with extension '.pat' and then open in the other program to
2290 get at least some results. By sticking to common or commonizable features, you could
2291 develop patches for both platforms.</P>
2292
2293 <P> To this day, Pd can still open and save MAX patches with the '.pat' extension as
2294 well as MAX text files with the '.mxt' extension. However, these are legacy and
2295 unsupported MAX formats. Today, MAX uses a JSON-based file format with the '.maxpat
2296 extension introduced in MAX 5, released in 2008.</P>
2297
2298 <P> Since then, MAX and Pd have further diverged, but Pd is still closely related to
2299 MAX/MSP. Nonetheless, there are differences in semantics between the two; a partial
2300 list follows.</P>
2301
2302 <P> In MAX, there are separate data types for integers and floating point numbers.
2303 You can use a '.' at the end of the number to specify it as a float, which may be
2304 needed as an argument in some objects. Similarly, MAX has a 'float' and an 'int'
2305 selector that you can use to define whether a '1' is a float or an int in a message.
2306 Pd only has a float type and selector, so you don't need to worry about any of this
2307 (all numbers are floats and there is no distinction between '1' and '1.'). MAX has
2308 a higher integer resolution with its int type, but with the double precision
2309 version of Pd (Pd64), this is not a significant issue.</P>
2310
2311 <P> MAX has a 'list' selector, but it is always implicit for messages with more
2312 than one element. In Pd it is only implicit if the list starts with a float. Hence,
2313 if you have a list that starts with a symbol, you need the 'list' selector in Pd.
2314 MAX has no 'symbol' selector, but a one element symbol message is considered a
2315 symbol and not a list. Pd explicitly needs to define a symbol data type with a
2316 'symbol' selector. For more, see sections
2317 <A href="2.theory.of.operation.htm#s2.4">2.4.</A> and subsection
2318 <A href="2.theory.of.operation.htm#s2.7.5">2.7.5.</A>.</P>
2319
2320 <P> Moreover, even though Pd can differentiate a one element list from a float or
2321 symbol, it virtually never has to as a one element list is effectively considered
2322 either a float or a symbol (or even a pointer for that matter). In MAX you need to
2323 explicitly differentiate a one element list with a list selector and a float/int or
2324 symbol. Also, in Pd, a list without any elements (hence, an empty list) is considered
2325 as a bang message, unlike MAX.</P>
2326
2327 <P> In MAX, a list of elements inside quotes specify a symbol, so <i>"a b c"</i>
2328 or <i>"1 2 3"</i> are actually a single symbol. Pd has no quote mechanism but
2329 you can escape spaces and form a symbol with it, so <i>a\ b\ c</i> and
2330 <i>1\ 2\ 3</i> actually form symbols. In MAX, you can also force a float to
2331 become a symbol with <i>"1"</i>. In Pd, this is trickier, since anything that
2332 looks like numbers are floats - but you can use <i>[makefilename]</i> to turn
2333 a number into a symbol.</P>
2334
2335 <P> In MAX, if an object's outlet is connected to several inlets, corresponding
2336 messages are always sent in right-to-left order of the inlets' positions. In Pd,
2337 the messages are sent in the order that the connections were made. Either way,
2338 when you care about the order, it's appropriate to use a <b>[trigger]</b> object to
2339 clearly define it.</P>
2340
2341 <P> In Pd, <b>[inlet]</b> / <b>[outlet]</b> and <b>[inlet~]</b> / <b>[outlet~]</b>
2342 are regular objects, whereas in MAX they're GUI objects and work for signal
2343 and control data.</P>
2344
2345 <P> MAX offers many GUI objects such as sliders, dials, VU meters, piano
2346 keyboards, even 'bpatchers'. Up until version 0.34, the only two GUI objects
2347 in Pd were number/symbol box and graphical arrays. Starting from version 0.34,
2348 Pd incorporates Thomas Musil's GUI objects: sliders, switches and so on
2349 (Thanks Thomas!). Beyond this essential collection of GUI objects, it's unlikely
2350 that you'll ever find any commonality between the two, unless you install
2351 externals that offer more GUI options in Pd.</P>
2352
2353 <P> Pd's correlate of MAX's <b>[poly~]</b> object is <b>[clone]</b>. In Pd, there
2354 is no <b>[pfft~]</b> object for managing spectral processing and you just use
2355 regular subpatches or abstractions that are adapted for it.</P>
2356
2357 <P> Pd has multichannel connections, but currently, no visual distinction is made.
2358 In MAX, you need to create a special version of the object, such as <b>[mc.+~]</b>,
2359 which actually is a wrapper that loads <b>[+~]</b> for multichannel capabilities. In
2360 Pd, objects like <b>[+~]</b> simply also work for multichannel and <b>[clone]</b>
2361 can be used to customly wrap abstractions and give them multichannel capabilities
2362 if you are using objects without multichannel features.</P>
2363
2364 <P> In abstractions, the corresponding feature for '$1' in Max is the '#1'
2365 construct. In a MAX abstraction, '#1' etc. are replaced by the creation
2366 argument when you have a look at the patch. In Pd, the '$' variables in object
2367 boxes are always spelled literally as '$' variables. Patches in Pd are also
2368 ready to be edited, while an abstraction in MAX is locked and "Read Only" if
2369 you open it; but can be edited in place using the "Modify Read Only" command.
2370 If you then unlock the abstraction to edit it, you can see the '$1' variables.</P>
2371
2372 <P> In MAX, the same '#1' construct is used to expand abstraction or clone arguments
2373 in messages, while Pd can only use '$1' for objects' variables and you cannot load
2374 arguments in messages. In that case, you need to use '$1' inside an object and then
2375 send it to a message with a '$1' variable.</P>
2376
2377 <P> In MAX, the local patch ID '#0' is used for objects and messages,
2378 but only inside abstractions. In Pd, you can use '$0' only as an object argument,
2379 but it also gets expanded when not loaded in abstractions. Also, unlike Pd, MAX does
2380 not let you open multiple copies of the same patch document.</P>
2381
2382 <P> MAX has a <b>[pv]</b> object that is similar to <b>[value]</b> and can
2383 force locality of variables in subpatches. In Pd, you need to set different
2384 names to <b>[value]</b> in each subpatch.</P>
2385
2386 <P> In Pd, you can change the send destination of a <b>[send]</b> object,
2387 while in MAX, you can set the receive name in a <b>[receive]</b> object.
2388 The <b>[float]</b>, <b>[int]</b> and <b>[value]</b> objects in Pd have a
2389 built-in 'send' message that communicates to receive addresses. GUIs in Pd
2390 have built-in 'send' and 'receive' names. The <b>[expr]</b> object in Pd
2391 can load variables defined by <b>[value]</b>.</P>
2392
2393 <P> In Pd, if you select "save" while in a subpatch, the parent is saved. In
2394 MAX, you can only save from the parent and you can save the subpatch as a
2395 separate file (if you want to save a subpatch to a file in Pd, you have to
2396 copy and paste the contents to a new document).</P>
2397
2398 <P> In Pd, there's no <b>[gate]</b>; instead there's a <b>[spigot]</b> with
2399 the inlets in the opposite, more natural order.</P>
2400
2401 <P> Switching subsets of the DSP patch on and off is done in completely different
2402 ways in Pd and MAX, and block sizes are handled differently as well.</P>
2403
2404 <P> The 'bpatcher' feature in MAX has a correlate in Pd
2405 (<A href="2.theory.of.operation.htm#s2.8.2">Graph-on-parent subpatches</A>); however, Pd's version is
2406 quite different from the one in MAX.</P>
2407
2408 <P> Pd's correlate of Max's <b>[itable]</b> object is an "array", implemented
2409 as a high level data structure construct.</P>
2410
2411 <P> In Pd, there's no <b>[preset]</b>, <b>[pattrstorage]</b> or related object.
2412 This is intentional, as Miller considers this to be basically a bad idea, so you
2413 have to use explicit sends and receives to restore values to number boxes. Then
2414 just make a "message" box to re-send the values you want. You can also save data
2415 as text from arrays and [text] objects. Also, a <b>[savestate]</b> is provided to
2416 save the state of different instances of an abstraction within the parent patch.</P>
2417
2418 <P> In MAX, using <b>[tabosc4~]</b> with an array, you'd use <b>[cycle~]</b>
2419 with <b>[buffer~]</b>. The only gotcha is that you can't draw in <b>[buffer~]</b> with
2420 the mouse like you can with arrays in Pd - but at least it's possible to make a patch
2421 that copies a 'table' into a <b>[buffer~]</b> object.</P>
2422
2423 <P> MAX can deal with multi-core processing, while Pd relies on an object called
2424 <b>[pd~]</b> for that, which opens a new Pd subprocess.</P>
2425
2426 <H4><A href="#s2.11.2" id="s2.11.2"> 2.11.2. Running Pd inside MAX with the <b>[pd~]</b>
2427 external</A></H4>
2428
2429 <P> There is a MAX version of the <b>[pd~]</b> object. If you install this external for MAX,
2430 you can run Pd as a subprocess inside MAX. A download of the external is provided at
2431 <A href="https://msp.ucsd.edu/software.html">https://msp.ucsd.edu/software.html</A>.</P>
2432
2433 <P> This allows you to run not only Pd's core objects, but also any external you might have
2434 installed for Pd. The picture below shows a <b>[pd~]</b> object in MAX 8.</P>
2435
2436 <figure>
2437 <IMG src="resources/2.11.1.png" ALT="pd~ in max">
2438 <figcaption><u>Fig. 2.11.1</u> The <b>[pd~]</b> external for MAX</figcaption>
2439 </figure>
2440
2441 <H4> <A href="#s2.11.3" id="s2.11.3"> 2.11.3. The Cyclone library</A> </H4>
2442
2443 <P> The Cyclone library for Pd includes a collection of objects cloned from MAX and includes
2444 control (MAX) and signal (MSP) objects. This can be useful for MAX users to feel more at
2445 home and adapt MAX patches in Pd. For more details, please check
2446 <A href="https://github.com/porres/pd-cyclone"> https://github.com/porres/pd-cyclone</A>.</P>
2447
2448 <P> Cyclone is an old and legacy external library for Pd. It was created and
2449 developed by Krzysztof Czaja from 2002 to 2005. A recent update by Alexandre
2450 Porres, Derek Kwan and Matt Barber has included some new objects and paired
2451 up Cyclone to MAX version 7.3.5. Currently, Cyclone is under maintenance mode,
2452 so don't expect updates besides bug fixes. No new objects are planned.</P>
2453
2454 <P>Note that other external libraries may offer functionalities and alternatives
2455 to MAX objects though (while Cyclone's aim is to exactly imitate MAX objects - even
2456 with their flaws). For instance, the main current maintainer of Cyclone (Porres)
2457 develops the ELSE library, which has alternatives for almost all cyclone objects
2458 and many objects in ELSE are actually inspired by MAX/MSP objects that were not
2459 cloned in Cyclone. The 'ceammc' library also provides a complete and cohesive
2460 system with lots of GUIs and functions you can find in MAX.</P>
2461
2462 </div>
2463 <div class="nav nav-bottom">
2464 <div class="nav-back"><A href="1.introduction.htm">&lt; Chapter 1: Introduction</A></div>
2465 <div class="nav-home"><A href="index.htm#s2">Table of contents</A></div>
2466 <div class="nav-forward"><A href="3.installing.configuring.htm">Chapter 3: Installing and configuring Pd &gt;</A></div>
2467 </div>
2468
2469 </BODY>
2470 </HTML>