| 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">< 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 ></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>−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>−2<sup>24</sup> (−16777216) </td> |
| 1082 |
<td>−2<sup>53</sup> (−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">< 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 ></A></div> |
| 2467 |
</div> |
| 2468 |
|
| 2469 |
</BODY> |
| 2470 |
</HTML> |