From 64fdb009695828b788fce074135b20a5e52c5fc4 Mon Sep 17 00:00:00 2001 From: Thomas Grill Date: Tue, 23 Sep 2003 00:21:28 +0000 Subject: imported version 0.37-0 svn path=/trunk/; revision=1016 --- pd/doc/1.manual/fig1.1.jpg | Bin 6794 -> 0 bytes pd/doc/1.manual/fig1.1.png | Bin 0 -> 1980 bytes pd/doc/1.manual/fig1.2.jpg | Bin 4361 -> 446 bytes pd/doc/1.manual/fig1.3.jpg | Bin 1056 -> 381 bytes pd/doc/1.manual/fig1.4.jpg | Bin 5965 -> 0 bytes pd/doc/1.manual/fig1.4.png | Bin 0 -> 1154 bytes pd/doc/1.manual/fig1.5.jpg | Bin 6187 -> 180 bytes pd/doc/1.manual/fig11.1.png | Bin 0 -> 5542 bytes pd/doc/1.manual/fig11.2.png | Bin 0 -> 2887 bytes pd/doc/1.manual/fig3.1.jpg | Bin 1201 -> 425 bytes pd/doc/1.manual/fig3.10.jpg | Bin 2884 -> 180 bytes pd/doc/1.manual/fig3.2.jpg | Bin 2932 -> 180 bytes pd/doc/1.manual/fig3.3.jpg | Bin 2177 -> 403 bytes pd/doc/1.manual/fig3.4.jpg | Bin 2359 -> 611 bytes pd/doc/1.manual/fig3.5.jpg | Bin 2029 -> 180 bytes pd/doc/1.manual/fig3.6.jpg | Bin 2977 -> 408 bytes pd/doc/1.manual/fig3.7.jpg | Bin 2846 -> 105 bytes pd/doc/1.manual/fig3.8.jpg | Bin 1267 -> 295 bytes pd/doc/1.manual/fig3.9.jpg | Bin 5708 -> 180 bytes pd/doc/1.manual/fig7.1.jpg | Bin 2410 -> 77 bytes pd/doc/1.manual/fig7.2.jpg | Bin 7327 -> 77 bytes pd/doc/1.manual/fig7.3.jpg | Bin 2588 -> 77 bytes pd/doc/1.manual/fig7.4.jpg | Bin 3245 -> 77 bytes pd/doc/1.manual/fig7.5.jpg | Bin 2490 -> 77 bytes pd/doc/1.manual/fig7.6.jpg | Bin 7758 -> 77 bytes pd/doc/1.manual/fig8.1.jpg | Bin 2551 -> 77 bytes pd/doc/1.manual/fig8.2.jpg | Bin 2414 -> 77 bytes pd/doc/1.manual/fig8.3.jpg | Bin 2036 -> 77 bytes pd/doc/1.manual/fig8.4.jpg | Bin 3428 -> 77 bytes pd/doc/1.manual/fig8.5.jpg | Bin 5182 -> 77 bytes pd/doc/1.manual/fig8.6.jpg | Bin 7549 -> 77 bytes pd/doc/1.manual/fig9.1.jpg | Bin 15267 -> 77 bytes pd/doc/1.manual/fig9.2.jpg | Bin 17390 -> 77 bytes pd/doc/1.manual/fig9.3.jpg | Bin 38881 -> 77 bytes pd/doc/1.manual/index.htm | 38 ++- pd/doc/1.manual/pdmanual.css | 39 +++ pd/doc/1.manual/x1.htm | 58 ++-- pd/doc/1.manual/x2.htm | 542 +++++++++++++++++--------------- pd/doc/1.manual/x3.htm | 723 +++++++++++++++++++++++-------------------- pd/doc/1.manual/x4.htm | 34 +- pd/doc/1.manual/x5.htm | 141 ++++++--- 41 files changed, 905 insertions(+), 670 deletions(-) delete mode 100644 pd/doc/1.manual/fig1.1.jpg create mode 100644 pd/doc/1.manual/fig1.1.png delete mode 100644 pd/doc/1.manual/fig1.4.jpg create mode 100644 pd/doc/1.manual/fig1.4.png create mode 100644 pd/doc/1.manual/fig11.1.png create mode 100644 pd/doc/1.manual/fig11.2.png create mode 100755 pd/doc/1.manual/pdmanual.css (limited to 'pd/doc/1.manual') diff --git a/pd/doc/1.manual/fig1.1.jpg b/pd/doc/1.manual/fig1.1.jpg deleted file mode 100644 index bfc76f64..00000000 Binary files a/pd/doc/1.manual/fig1.1.jpg and /dev/null differ diff --git a/pd/doc/1.manual/fig1.1.png b/pd/doc/1.manual/fig1.1.png new file mode 100644 index 00000000..a2399935 Binary files /dev/null and b/pd/doc/1.manual/fig1.1.png differ diff --git a/pd/doc/1.manual/fig1.2.jpg b/pd/doc/1.manual/fig1.2.jpg index c33c755c..e4428091 100644 Binary files a/pd/doc/1.manual/fig1.2.jpg and b/pd/doc/1.manual/fig1.2.jpg differ diff --git a/pd/doc/1.manual/fig1.3.jpg b/pd/doc/1.manual/fig1.3.jpg index caf29b2d..27bde2f0 100644 Binary files a/pd/doc/1.manual/fig1.3.jpg and b/pd/doc/1.manual/fig1.3.jpg differ diff --git a/pd/doc/1.manual/fig1.4.jpg b/pd/doc/1.manual/fig1.4.jpg deleted file mode 100644 index 28a29dc6..00000000 Binary files a/pd/doc/1.manual/fig1.4.jpg and /dev/null differ diff --git a/pd/doc/1.manual/fig1.4.png b/pd/doc/1.manual/fig1.4.png new file mode 100644 index 00000000..1dc8e037 Binary files /dev/null and b/pd/doc/1.manual/fig1.4.png differ diff --git a/pd/doc/1.manual/fig1.5.jpg b/pd/doc/1.manual/fig1.5.jpg index 4b01c59f..3b72fc7f 100644 Binary files a/pd/doc/1.manual/fig1.5.jpg and b/pd/doc/1.manual/fig1.5.jpg differ diff --git a/pd/doc/1.manual/fig11.1.png b/pd/doc/1.manual/fig11.1.png new file mode 100644 index 00000000..c8283cdb Binary files /dev/null and b/pd/doc/1.manual/fig11.1.png differ diff --git a/pd/doc/1.manual/fig11.2.png b/pd/doc/1.manual/fig11.2.png new file mode 100644 index 00000000..1fcfd7e7 Binary files /dev/null and b/pd/doc/1.manual/fig11.2.png differ diff --git a/pd/doc/1.manual/fig3.1.jpg b/pd/doc/1.manual/fig3.1.jpg index f8348970..6024abe8 100644 Binary files a/pd/doc/1.manual/fig3.1.jpg and b/pd/doc/1.manual/fig3.1.jpg differ diff --git a/pd/doc/1.manual/fig3.10.jpg b/pd/doc/1.manual/fig3.10.jpg index 4625ce0c..29e31c7d 100644 Binary files a/pd/doc/1.manual/fig3.10.jpg and b/pd/doc/1.manual/fig3.10.jpg differ diff --git a/pd/doc/1.manual/fig3.2.jpg b/pd/doc/1.manual/fig3.2.jpg index 994d41c7..a91c0e2e 100644 Binary files a/pd/doc/1.manual/fig3.2.jpg and b/pd/doc/1.manual/fig3.2.jpg differ diff --git a/pd/doc/1.manual/fig3.3.jpg b/pd/doc/1.manual/fig3.3.jpg index 91cac54a..640cacd8 100644 Binary files a/pd/doc/1.manual/fig3.3.jpg and b/pd/doc/1.manual/fig3.3.jpg differ diff --git a/pd/doc/1.manual/fig3.4.jpg b/pd/doc/1.manual/fig3.4.jpg index e2f2fe53..62bfc517 100644 Binary files a/pd/doc/1.manual/fig3.4.jpg and b/pd/doc/1.manual/fig3.4.jpg differ diff --git a/pd/doc/1.manual/fig3.5.jpg b/pd/doc/1.manual/fig3.5.jpg index 9a79a2b3..875e2782 100644 Binary files a/pd/doc/1.manual/fig3.5.jpg and b/pd/doc/1.manual/fig3.5.jpg differ diff --git a/pd/doc/1.manual/fig3.6.jpg b/pd/doc/1.manual/fig3.6.jpg index fcbcf3da..76775b80 100644 Binary files a/pd/doc/1.manual/fig3.6.jpg and b/pd/doc/1.manual/fig3.6.jpg differ diff --git a/pd/doc/1.manual/fig3.7.jpg b/pd/doc/1.manual/fig3.7.jpg index 84dcd7f7..5cddde32 100644 Binary files a/pd/doc/1.manual/fig3.7.jpg and b/pd/doc/1.manual/fig3.7.jpg differ diff --git a/pd/doc/1.manual/fig3.8.jpg b/pd/doc/1.manual/fig3.8.jpg index ab03a207..66f3db82 100644 Binary files a/pd/doc/1.manual/fig3.8.jpg and b/pd/doc/1.manual/fig3.8.jpg differ diff --git a/pd/doc/1.manual/fig3.9.jpg b/pd/doc/1.manual/fig3.9.jpg index 6e9655c7..4097af46 100644 Binary files a/pd/doc/1.manual/fig3.9.jpg and b/pd/doc/1.manual/fig3.9.jpg differ diff --git a/pd/doc/1.manual/fig7.1.jpg b/pd/doc/1.manual/fig7.1.jpg index b677f6bd..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.1.jpg and b/pd/doc/1.manual/fig7.1.jpg differ diff --git a/pd/doc/1.manual/fig7.2.jpg b/pd/doc/1.manual/fig7.2.jpg index 54690d0e..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.2.jpg and b/pd/doc/1.manual/fig7.2.jpg differ diff --git a/pd/doc/1.manual/fig7.3.jpg b/pd/doc/1.manual/fig7.3.jpg index a3b70ed3..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.3.jpg and b/pd/doc/1.manual/fig7.3.jpg differ diff --git a/pd/doc/1.manual/fig7.4.jpg b/pd/doc/1.manual/fig7.4.jpg index 88ba5b40..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.4.jpg and b/pd/doc/1.manual/fig7.4.jpg differ diff --git a/pd/doc/1.manual/fig7.5.jpg b/pd/doc/1.manual/fig7.5.jpg index f9de4b3b..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.5.jpg and b/pd/doc/1.manual/fig7.5.jpg differ diff --git a/pd/doc/1.manual/fig7.6.jpg b/pd/doc/1.manual/fig7.6.jpg index 5f24af7a..643a155a 100644 Binary files a/pd/doc/1.manual/fig7.6.jpg and b/pd/doc/1.manual/fig7.6.jpg differ diff --git a/pd/doc/1.manual/fig8.1.jpg b/pd/doc/1.manual/fig8.1.jpg index 57e59313..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.1.jpg and b/pd/doc/1.manual/fig8.1.jpg differ diff --git a/pd/doc/1.manual/fig8.2.jpg b/pd/doc/1.manual/fig8.2.jpg index 1dd48cd9..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.2.jpg and b/pd/doc/1.manual/fig8.2.jpg differ diff --git a/pd/doc/1.manual/fig8.3.jpg b/pd/doc/1.manual/fig8.3.jpg index 165c1c88..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.3.jpg and b/pd/doc/1.manual/fig8.3.jpg differ diff --git a/pd/doc/1.manual/fig8.4.jpg b/pd/doc/1.manual/fig8.4.jpg index afc89a73..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.4.jpg and b/pd/doc/1.manual/fig8.4.jpg differ diff --git a/pd/doc/1.manual/fig8.5.jpg b/pd/doc/1.manual/fig8.5.jpg index 6fa3d0d1..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.5.jpg and b/pd/doc/1.manual/fig8.5.jpg differ diff --git a/pd/doc/1.manual/fig8.6.jpg b/pd/doc/1.manual/fig8.6.jpg index 2823e032..643a155a 100644 Binary files a/pd/doc/1.manual/fig8.6.jpg and b/pd/doc/1.manual/fig8.6.jpg differ diff --git a/pd/doc/1.manual/fig9.1.jpg b/pd/doc/1.manual/fig9.1.jpg index bab4b689..643a155a 100644 Binary files a/pd/doc/1.manual/fig9.1.jpg and b/pd/doc/1.manual/fig9.1.jpg differ diff --git a/pd/doc/1.manual/fig9.2.jpg b/pd/doc/1.manual/fig9.2.jpg index 88ef528c..643a155a 100644 Binary files a/pd/doc/1.manual/fig9.2.jpg and b/pd/doc/1.manual/fig9.2.jpg differ diff --git a/pd/doc/1.manual/fig9.3.jpg b/pd/doc/1.manual/fig9.3.jpg index ecb66004..643a155a 100644 Binary files a/pd/doc/1.manual/fig9.3.jpg and b/pd/doc/1.manual/fig9.3.jpg differ diff --git a/pd/doc/1.manual/index.htm b/pd/doc/1.manual/index.htm index 2d8bb4dd..c403ae99 100644 --- a/pd/doc/1.manual/index.htm +++ b/pd/doc/1.manual/index.htm @@ -1,15 +1,17 @@ + + - -Pd Documentation - - - -
- -
- -Pd Documentation
-
+ + Pd Documentation + + + + + + + +

Pd Documentation

+

This is the HTML documentation for Pd, a patchable environment for audio analysis, synthesis, and processing, @@ -91,10 +93,11 @@ can be found at:

  • getting Pd to run
      -
    1. IRIX (SGI) -
    2. Microsoft Windows -
    3. Linux -
    4. Mac OSX +
    5. Overview +
    6. Installing Pd in Microsoft Windows +
    7. Installing Pd in Linux +
    8. Installing Pd in MacOS X +
    9. Installing Pd in IRIX (SGI)
    10. graphics rendering using GEM
    11. The Pd command line
    12. dealing with files @@ -110,7 +113,7 @@ can be found at:
    - -> + diff --git a/pd/doc/1.manual/pdmanual.css b/pd/doc/1.manual/pdmanual.css new file mode 100755 index 00000000..01d66ab2 --- /dev/null +++ b/pd/doc/1.manual/pdmanual.css @@ -0,0 +1,39 @@ + +HTML { + background: #ffffff; + color: #000000; + font-family: Times, Times New Roman, serif; + font-size: 10pt; +} +BODY { + width: 6.5in; + margin-left: 0.5in +} +H1 { + font-size: 36pt; + text-align: center; +} +H2 { + font-size: 10pt; + text-align: center; +} +H3 { + font-size: 12pt; + text-align: left; +} +H4 { + font-size: 10pt; + text-align: left; +} +H5 { + font-size: 8pt; + text-align: left; +} +H6 { + font-size: 8pt; + text-align: left; +} +PRE { + font-size: 8pt; + text-align: left; +} diff --git a/pd/doc/1.manual/x1.htm b/pd/doc/1.manual/x1.htm index 6a78040e..e46098cd 100644 --- a/pd/doc/1.manual/x1.htm +++ b/pd/doc/1.manual/x1.htm @@ -1,17 +1,22 @@ + + - -Pd Documentation 1 - - - -
    - -
    -Pd Documentation chapter 1: introduction -
    -
    - back to table of contents -

    + + Pd Documentation 1 + + + + + + +

    Pd Documentation chapter 1: introduction

    + +

    + back to table of contents +

    +

    + +

    This is the HTML documentation for the Pd computer program. Pd is free and can be downloaded from the internet; @@ -19,7 +24,7 @@ go to http://www.crca.ucsd.edu/~msp/software.html to get it. -

    1.1. guide to the documentation

    +

    1.1. guide to the documentation

    Pd's documentation consists of: @@ -63,7 +68,17 @@ patches in "7.stuff" might also be helpful.

    To get started writing your own C extensions, refer to chapter 4 of this manual. -

    1.2. other resources

    +

    1.2. other resources

    + +

    There is a new Pd community web site, + pure-data.org, which aims to be the +central resource for Pd, from documentation and +downloads; to forums, member pages, a patch exchange. + +

    There is a growing number of Pd-related projects hosted at +SourceForge. This is open to all Pd +developers, and all are encouraged to join. Send an email to the pd-dev list, +pd-dev[AT]iem.kug.ac.at, to join.

    Most of the interesting resources related to Pd show up on the Pd mailing list, @@ -82,10 +97,10 @@ for people interested in graphics, there is a A 3D graphics rendering package, named GEM, based on OpenGL, was written by Mark Danks, adapted to Linux by Guenter Geiger, and is now maintained by Iohannes Zmoelnig. GEM runs on Windows and Linux and probably will run with some coaxing on IRIX. You can get -it from: http://iem.kug.ac.at/GEM . +it from: http://iem.kug.ac.at/GEM .

    A video processing package, Framestein, is by Juha Vehvilainen. This runs -on Windows only: http://framestein.org . +on Windows only: http://framestein.org .

    Here are some more Pd links (in the order I found them):
    @@ -98,8 +113,6 @@ Here are some more Pd links (in the order I found them):
    Johannes M Zmoelnig
    Norbert Math's Pd page
    Thomas Musil's IEMLIB
    - jfm3's Pure Data FAQ and downloads -(also available in Japanese translation).
    Nicolas Lhommet's WikiWikiWeb page for Pd
    Norbert's searchable list of all known @@ -109,8 +122,13 @@ Krzysztof Czaja's MIDI file support
    David Sabine's Pd Documentation Project: new, highly detailed help windows
    - + Fernando Pablo Lopez's augmented Pd RPMs from Planet CCRMA
    + +Cyclone - Krzysztof Czaja's Max compatibility library
    +On-line book project: + Theory and Techniques of Electronic Music
    diff --git a/pd/doc/1.manual/x2.htm b/pd/doc/1.manual/x2.htm index 334e6ae2..8d656a64 100644 --- a/pd/doc/1.manual/x2.htm +++ b/pd/doc/1.manual/x2.htm @@ -1,75 +1,85 @@ + + - -Pd Documentation - - - -

    - -
    -Pd Documentation chapter 2: theory of operation -
    -
    -     back to table of contents -

    + + Pd Documentation 2 + + + + + + + +

    Pd Documentation chapter 2: theory of operation

    + +

    + back to table of contents +

    +

    +

    The purpose of this chapter is to describe Pd's design and how it is supposed to work. Practical details about how to obtain, install, and run Pd are described in the next chapter. To learn digital audio processing basics -such as how to generate time-varying sounds that don't click or fold over, a -good reference is Dodge and Jerse, Computer Music . +such as how to generate time-varying sounds that don't click or fold over, try +the on-line book, + Theory and Techniques of Electronic Music . -

    2.1 overview

    +

    2.1 overview

    -Pd is a real-time graphical programming environment for audio and graphical +

    Pd is a real-time graphical programming environment for audio and graphical processing. It resembles the Max/MSP system but is much simpler and more portable; also Pd has two features not (yet) showing up in Max/MSP: first, via Mark Dank's GEM package, Pd can be used for simultaneous computer animation and computer audio. Second, an experimental facility is provided for defining and accessing data structures. -

    2.1.1. the main window, canvases, and printout

    +

    2.1.1. the main window, canvases, and printout

    -When Pd is running, you'll see a main "Pd" window, and possibly one or more +

    When Pd is running, you'll see a main "Pd" window, and possibly one or more "canvases" or "patches". The main Pd window looks like this: -

    - -

    +

    + pd window +

    There are peak level and clip indicators for audio input and output; these report peak levels over all input and all output channels. Note that DC shows up as an input level; many cards have DC levels which show up in the -50s. To see an RMS audio level, select "test audio and MIDI" from the help -window. The main window display is intended only to help you avoid clipping +50s. To see an RMS audio level, select "test audio and MIDI" from the Media +menu. The main window display is intended only to help you avoid clipping on input and output. You can turn the peak meters on and off using the control at bottom left. -

    At bottom right is a control to turn audio processing on and off globally. -Turning audio off does not relinquish the audio devices, it just stops the -computation. The "audio" menu is also provided, with accelerators "Control-." -to turn audio computation off and "Control-/" to turn it on. When audio is -on, Pd is computing audio samples in real time according to whatever patches -you have open (visible or not.) +

    At bottom right is a control to turn audio processing on and off +globally. Turning audio off stops the computation and relinquishes any audio +devices Pd is using. The "Media" menu is also provided, with accelerators +"Control-." to turn audio computation off and "Control-/" to turn it on. When +audio is on, Pd is computing audio samples in real time according to whatever +patches you have open (whether they are visible or not).

    The DIO (Digital I/O) error indicator flashes if there is a synchronization -error for audio input or output. Click there to see a list of recent errors. -This indicator is normally red at startup, and will turn red whenever the +error for audio input or output. (But note that on some platforms Pd doesn't +find out about them. If you never see red, you're probably not seeing the +truth.) +Click the "DIO errors" button to see a list of recent errors. +This indicator should turn red whenever the computation runs late (so that the DAC FIFOs fill and/or the ADC FIFOs empty) or if audio input and output are not running at the same rate. See audio and MIDI support .

    Pd documents are called "patches" or "canvases." Each open document has one main window and any number of -subwindows. The subwindows can be opened and closed but are always running +sub-windows. The sub-windows can be opened and closed but are always running whether you can see them or not. Here is a simple Pd patch: -

    - -

    +

    + hello world patch +

    -There are four text boxes in this patch: a number box (showing zero), +

    There are four text boxes in this patch: a number box (showing zero), an object box showing "print," and two comments. The number box and the object box are connected, the number box's output to the print box's input. Boxes may have zero or more inputs and/or outputs, with the inputs on top and the outputs @@ -80,7 +90,7 @@ Pd's printout appears on its standard output. Normally, you'll run Pd in a "shell" or "terminal" window which you'll keep open to see any printout or error messages. -

    2.1.2. object boxes

    +

    2.1.2. object boxes

    Pd patches can have four types of boxes: object, message, GUI, and comment . @@ -89,29 +99,39 @@ divided into atoms separated by white space. The first atom specifies what type of object Pd will make, and the other atoms, called creation arguments , tell Pd how to initialize the object. If you type for example, -

    - -

    +

    + object +

    -the "+" specifies the class of the object. +

    the "+" specifies the class of the object. In this case the object will be the kind that carries out addition, -and the "13" initializes the amount to add. Atoms are either numbers or -symbols like "+". +and the "13" initializes the amount to add. + +

    Atoms are either numbers or +symbols like "+". Anything that is not a valid number os considered a +symbol. Valid numbers may or may not have a decimal point (for instance, 12, +15.6, -.456), or may be +written in exponential notation (such as "4.5e6", which means "4.5 multiplied +by 10 six times, i.e., 4500000). Negative exponentials divide by 10 (so +that 1.23e-5 comes to 0.0000123). -The text you type into an object box determines how +

    Non-valid numbers which are read as symbols +include things like "+5" and "0..6" as well as words and names such as "Zack" +or "cat". The symbols "gore", "Gore", and "GORE" are all distinct. + +

    The text you type into an object box determines how many and what kinds of inlets and outlets the object will have. Some classes (like "+" always have a fixed arrangement of inlets and outlets, and in the case of other classes, the inlets and outlets will depend on the creation arguments. -

    -Here for example is a simple MIDI synthesizer: +

    Here for example is a simple MIDI synthesizer: -

    - -

    +

    + simple MIDI synthesizer +

    -This patch mixes control objects (notein, stripnote, and ftom) with +

    This patch mixes control objects (notein, stripnote, and ftom) with tilde objects osc~, *~, and dac~. The control objects carry out their function sporadically, as a result of one or more type of event . In this case, incoming MIDI note messages set off the control computation. The @@ -125,53 +145,71 @@ acting as the interface between the two regimes, in that it takes control messages to set its frequency but talks to "*~" using an audio signal. Audio signals aren't sporadic; they are continuous streams of numbers. As a result tilde objects act under very different rules from control objects. The audio -portion of the patch is always running, whether MIDI messages arrive or not; -the function of control computations is to insert calculations between the -audio computation which may change audio computation parameters such as -the frequency of an oscillator. - -

    2.1.3. message and GUI boxes

    - -The border of a box tells you how its text is interpreted and how the box -functions. Object boxes use the text to create objects when you load a -patch. Message boxes interpret the text as a message to send whenever -the box is activated (by an incoming message or with the mouse.) In the example -below the message box, when clicked, sends the message "21" to an object +portion of the patch is always running, whether MIDI messages arrive or not. On +the other hand, the function of control computations is to insert calculations +between the audio computation which may change audio computation parameters +such as the frequency of an oscillator. + +

    The connections in the patch (the lines between the boxes) are also of two +types: control and signal. The type of connection depends on the outlet it +comes from. Signal connections are represented by thicker lines than control +connections; in the patch above, the two bottom conections are signal and the +others are control. In general, a control connection may be made to a signal +inlet; if numbers are sent over it they are automatially converted to +signals. Signal connections may not be made to control inlets; some sort +of explicit conversion must be specified. + +

    2.1.3. message and GUI boxes

    + +

    The border of a box tells you how its text is interpreted and how the box +functions. Object boxes (as in the previous example) use the text to create +objects when you load a patch or type text onto a new one. If you retype the +text in an object box, the old one is discarded and a new one is created, using +the new creation arguments. The contents of an object box describe a message +which is sent to Pd to create the object. + +

    Message boxes interpret the text as a message to send whenever +the box is activated (by an incoming message or with the mouse.) The message +may be sent many times while the patch is running (as opposed to object boxes +whose message is used once to create the object). Instead of going straight +to Pd, the message box's message (or messages) go either to the box's outlet +or to other specified receiving objects. In the example +below, the message box, when clicked, sends the message "21" to an object box which adds 13 to it. -

    - -

    +

    + [message( --> [object] -> [number] +

    -The third box shown is a GUI box. GUI boxes come in many forms including -number boxes (as in this example), toggles, sliders, and so on. Whereas the -appearance of an object or message box is static when a patch is running, a -number box's contents (the text) changes to reflect the current value held by -the box. You can also use a number box as a control by clicking and dragging -up and down, or by typing values in it. (There are also shift- and alt-click -actions; see getting help to find out how to look -this up). +

    The third box shown is a GUI ("graphical user interface") box. GUI +boxes come in many forms including number boxes (as in this example), toggles, +sliders, and so on. Whereas the appearance of an object or message box is +static when a patch is running, a number box's contents (the text) changes to +reflect the current value held by the box. You can also use a number box as a +control by clicking and dragging up and down, or by typing values in it. +(There are also shift- and alt-click actions; see +getting help to find out how to look this up).

    You can also create a "symbol" box which is like a number box but deals in symbols like "cat." You can type your own strings in (followed by "enter") or use it to display strings which arrive as messages to its inlet. -

    2.1.4. patches and files

    +

    2.1.4. patches and files

    -When you save a patch to a file, Pd doesn't save the entire state of all the +

    When you save a patch to a file, Pd doesn't save the entire state of all the objects in the patch, but only what you see: the objects' creation arguments and their interconnections. Certain data-storage objects have functions for reading and writing other files to save and restore their internal state. -Pd finds files using a path which can be specified as part of Pd's +

    Pd finds files using a path which can be specified as part of Pd's startup arguments. The path specifies one or more directories, separated by colons (semicolons if you're using windows.) Most objects which can read files search for them along the search path, but when Pd writes files they go to the directory where the patch was found. -

    2.2. editing Pd patches

    +

    2.2. editing Pd patches

    -

    2.2.1. edit and run mode

    +

    2.2.1. edit and run mode

    A patch can be in edit or run mode; this really only affects how mouse clicks affect the patch. In edit mode, clicking and dragging selects and @@ -180,7 +218,7 @@ them messages which they react to in different ways. In run mode, number and message boxes can be used as controls. Normally, when you are in a performance you will stay in run mode; to change the patch you go to edit mode. -

    2.2.2. creating boxes

    +

    2.2.2. creating boxes

    You can create boxes (objects, messages, GUIs, and comments) using the "put" menu. Note the handy accelerators. Object and message boxes are empty @@ -192,34 +230,37 @@ place them. (in the Edit menu) than to use the "Put" menu. If you select and duplicate several items, any connections between them will be duplicated as well. -

    2.2.3. the selection

    +

    2.2.3. the selection

    -Boxes in a Pd window may be selected by clicking on them. To select more -than one object you may use shift-click or click "outside" and select all -objects within a rectangle. You can't select lines, only boxes. +

    Boxes in a Pd window may be selected by clicking on them. To select more +than one object you may use shift-click or click on a blank portion of +the window and drag the cursor to select all objects within a rectangle. -Clicking on an unselected object, message, or comment box makes the text -active, i.e., ready to be text edited. If you select using the rectangle -method, the text isn't activated. This affects whether further clicks will -displace teh object or select text within it. +

    Clicking on an unselected object, message, or comment box makes the text +active, i.e., ready to be text edited. (If you select using the rectangle +method, the text isn't activated.) Once you've activated a text box, you +may type into it (replacing the selected text) or use the mouse to change the +selection. -

    2.2.4. deleting, cutting, and pasting

    +

    You may also select a single connection (patch cord) by clicking on it. +You can't have connections and boxes selected simultaneously. -If you select a box but don't activate the text in it, you can "delete" it -by hitting the backspace key. You can "cut" "copy" and "paste" using menu -items. Notice that pasting puts the new object(s) right down on top of the -old ones. +

    2.2.4. deleting, cutting, and pasting

    -The "duplicate" menu item performs a copy and paste with a small offset so you -can see the new boxes. You can drag them together to a new place on the -screen. +

    If you select a box, a connection, or several boxes, and if you haven't made +any text active, you can "delete" the selection by hitting the backspace or +delete key. You can also "cut" "copy" and "paste" using menu items. Notice +that pasting puts the new object(s) right down on top of the old ones. -You can cut and paste between windows within Pd but cut/paste isn't -integrated with the OS in any way. Cut/copy/paste for text strings isn't -implemented yet, although in Linux and Irix at least you can "X-paste" into -and out of "text" dialogs (created with the "edit text" menu item.) +

    The "duplicate" menu item performs a copy and paste with a small offset so you +can see the new boxes. You can drag them together to a new place on the screen. -

    2.2.5. changing the text

    +

    You can cut and paste between windows within Pd but cut/paste isn't +integrated with the OS in any way. Cut/copy/paste for activated text in boxes +isn't implemented yet, although in Linux and Irix at least you can "X-paste" +into and out of "text" dialogs (created with the "edit text" menu item.) + +

    2.2.5. changing the text

    To change a text item, you can select it and then edit the text. If you only click once, the entire text is selected and your typing will replace @@ -234,45 +275,56 @@ one box in sequence if you want.

    If you click a box and move the mouse without releasing the button this displaces the entire box. If you wish to displace a box which is already -sepected, first deselect the box by clicking outside it; otherwise you will be +selected, first de-select the box by clicking outside it; otherwise you will be selecting text instead of moving the box. -

    The updated text only becomes part of the patch when you deselect the -object. Changing the text in an "object" box actually deletes the old +

    The updated text only becomes part of the patch when you de-select the +object. Changing the text in an "object" box deletes the old object and creates a new one; the internal state of the old one is lost. -

    2.2.6. connecting and disconnecting boxes

    +

    2.2.6. connecting and disconnecting boxes

    -To make a connection between two boxes, click on any outlet of the first -one, drag toward an inlet of the second one, and release. You can actually +

    To make a connection between two boxes, click on any outlet of the first +one, drag toward an inlet of the second one, and release. You can release the mouse button anywhere within the target object and the connection will be made to the nearest inlet. -Connections are broken simply by clicking on them (the cursor changes to an -"X" when appropriate.) +

    Connections are broken by selecting them and using "cut" or the backspace +or delete key. + +

    2.2.7. popup menu for properties, open, and help

    + +

    All the "clicking" mentioned above is done with the left mouse button. +The right button, instead, gives a popup menu offering "properties," "open," +and "help". +(For Macintosh users who may only have one button on their mouse, +double-clicking is mapped to right-click.) + +

    Selecting "help" on an object gets +a Pd patch that demonstrates how to use it. "Help" for the canvas as a whole +(right-clicking outside any object) gives a list of all built-in objects. -

    2.2.7. Properties and help

    +

    The "open" menu item is only enabled if you right-click on a subpatch +(see below) and causes Pd to open it. Ordinary subpatches may also be opened +by clicking on them, but for "graph-on-parent" ones, this is the only way to +do it. -

    all the "clicking" mentioned above is done with the left mouse button. -The right button, instead, gives a popup menu for "properties" and "help". -Properties are enabled for number boxes and graphs (and in the future may -be available for other things as well.) Selecting "help" on an object gets -a Pd patch that demonstrates how to use it. "Help for the canvas as a whole -(click outsize any object) gives a list of all built-in objects. +

    The "properties" dialog allows you to change certain settings of GUI +objects, or of the patch itself (by clicking outside any box.) -

    2.2.8. miscellaneous

    +

    2.2.8. miscellaneous

    Control-q "quits" Pd, but asks you to comfirm the quit. To quit without having to confirm, use command-shift-Q. -

    2.3. messages

    +

    2.3. messages

    In Pd, objects intercommunicate by sending messages and/or audio signals. Pd messages are sporadic, like MIDI messages or music N "Note cards." -

    2.3.1. anatomy of a message

    +

    2.3.1. anatomy of a message

    -Messages contain a selector followed by +

    Messages contain a selector followed by any number of arguments. The selector is a symbol, which appears in the patch as a non-numeric string with no white space, semicolons, or commas. The arguments may be symbols or numbers. Numbers in Pd are kept in 32-bit floating @@ -286,13 +338,13 @@ is checked against the receiver. If the receiver recognizes messages of that selector, it carries out some corresponding action. For instance, here is a "float" object: -

    - -

    +

    + float object +

    The two rectangles at the top are usually both called "inlets" but the one at the left directs incoming messages to the "float" object itself, -whereas the one at the right directs messages to an auxilliary "inlet" +whereas the one at the right directs messages to an auxiliary "inlet" object. The float object proper (represented by the left-hand inlet) accepts messages with selector "float" and "bang". The right-hand inlet takes only the message selector "float". These two selectors, along with "symbol" and @@ -304,16 +356,16 @@ which cannot be used as a selector. A single number is always given the "float" selector automatically, and a message with a number followed by other arguments is given the selector "list". -

    2.3.2. depth first message passing

    +

    2.3.2. depth first message passing

    In Pd whenever a message is initiated, the receiver may then send out further messages in turn, and the receivers of those messages can send yet others. So each message sets off a tree of consequent messages. This tree is executed in depth first fashion. For instance in the patch below: -

    - -

    +

    + depth first message passing +

    the order of arrival of messages is either A-B-C-D or A-C-D-B. The "C" message is not done until the "D" one is also, and the "A" is not done until @@ -323,9 +375,9 @@ sorted right to left).

    Message-passing can give rise to infinite loops of the sort shown here: -

    - -

    +

    + infinite message passing loop +

    Here the left-hand "+" can't finish processing until the right-hand one has been sent the result "2", which can't finish processing that until the @@ -333,26 +385,26 @@ left-hand one has been sent "3", and so on. Pd will print an error message reporting a "stack overflow" if this happens.

    However, it is legal to make a loop if there is a "delay" object somewhere -in it. When the "delay" receives a message it schedules a messsage for the +in it. When the "delay" receives a message it schedules a message for the future (even if the time delay is 0) and is then "finished;" Pd's internal scheduler will wake the delay back up later. -

    -2.3.3. hot and cold inlets and right to left outlet order

    +

    +2.3.3. hot and cold inlets and right to left outlet order

    With few exceptions (notably "timer"), objects treat their leftmost inlet as "hot" in the sense that messages to right inlets can result in output messages. So the following is a legal (and reasonable) loop construct: -

    - -

    +

    + hot and cold inlets +

    -Here the "f" is an abbreviation for "float". Note that the "+ 1" output is +

    Here the "f" is an abbreviation for "float". Note that the "+ 1" output is connected to the right-hand inlet of "f". This "cold" inlet merely stores the value for the next time the "f" is sent the "bang" message. -It is frequently desirable to send messages to two or more inlets of an object +

    It is frequently desirable to send messages to two or more inlets of an object to specify its action. For instance, you can use "+" to add two numbers; but to do it correctly you must make sure the right hand inlet gets its value first. Otherwise, when the left hand side value comes in, "+" will carry out @@ -365,9 +417,9 @@ single object. In this case it is indeterminate which order the two inlets will receive their messages. Suppose for example you wish to use "+" to double a number. The following is incorrect: -

    - -

    +

    + incorrect inlet connection +

    Here, I connected the left inlet before connecting the right hand one (although this is not evident in the appearance of the patch.) The "+" thus adds the @@ -380,9 +432,9 @@ you connect these to inlets of a second object without crossing wires, the second object will get its leftmost inlet last, which is usually what you want. Here is how to use "trigger" to disambiguate the previous example: -

    - -

    +

    + trigger to disambiguate +

    "Cold" (non-leftmost) inlets are almost universally used to store single values (either numbers or symbols.) With the exception of "line" and "line~", @@ -394,28 +446,29 @@ the order in which two messages are sent to a single "cold" inlet. In this situation, since the messages are merged, the last value to be received is the value that is used in the computation. -

    2.3.4. message boxes

    +

    2.3.4. message boxes

    Message boxes are text boxes in which you type a message. When the message box is activated, either by clicking on it or sending something to its inlet, the message or messages are sent, either to the message box's outlet or elsewhere as specified. -

    - -

    +

    + message boxes +

    -The first of the message boxes above contains the single number 1.5; this +

    The first of the message boxes above contains the single number 1.5; this message has an implicit selector of "float." The second is a list with three numbers in it, and in the third, the selector is "my" and the two arguments are the number 5 and the symbol "toes."

    Multiple messages may be separated by commas as shown: -

    - -

    -Here the three messages are the numbers 1, 2, and 3, and they are sent in +

    + multiple messages in one box +

    + +

    Here the three messages are the numbers 1, 2, and 3, and they are sent in sequence (with no intervening time between them, as with the "trigger" object, and having depth-first consequences so that whatever chain of actions depending on "1" takes place before anything depending on "2" and so on.) @@ -430,27 +483,27 @@ semicolon immediately redirects messages from the outlet to an object named to "sue." -

    - -

    +

    + semicolons to send messages +

    -Certain other objects (Pd windows, for example, and arrays) have Pd names and +

    Certain other objects (Pd windows, for example, and arrays) have Pd names and can be sent messages this way. Also, the special object "pd" is defined to which you may send messages to start and stop DSP.

    You can put variables in message boxes as shown below: -

    - -

    +

    + variables in message boxes +

    -Here, "$1", etc., refer to the arguments of the arriving message (and aren't +

    Here, "$1", etc., refer to the arguments of the arriving message (and aren't defined if you send a "bang" message or if you click on the message box to activate it.) Dollar sign variables are either numbers or symbols depending on the incoming message; if symbols, you may even use them to specify variable message selectors or destinations. -

    2.4. audio signals

    +

    2.4. audio signals

    Using Pd you can build audio patches which can synthesize musical sounds, @@ -458,31 +511,25 @@ analyze incoming sounds, process incoming sounds to produce transformed audio outputs, or integrate audio processing with other media. This section describes how Pd treats audio signals. -

    2.4.1. sample rate and format

    +

    2.4.1. sample rate and format

    Pd's audio signals are internally kept as 32-bit floating point numbers, so you have all the dynamic range you could want. However, depending on your hardware, audio I/O is usually limited to 16 or 24 bits. Inputs all appear between the values of -1 and 1; and output values will be clipped to that range. - -

    -Pd assumes a sample rate of 44100 unless you override this in Pd's command line. -Pd doesn't check that this matches the sample rate of audio input or output, -nor does Pd attempt to set your computer's audio sample rate to its own. If -the audio system is running at the wrong sample rate, audio output will -be transposed (you can check this using the "test audio and MIDI" patch; see -the help menu). +Pd assumes a sample rate of 44100 unless you override this ( +in Pd's command line or in the "audio setup" dialog).

    Pd can read or write samples to files either in 16-bit or 24-bit fixed point or in 32-bit floating point, in WAV, AIFF, or AU format, via the soundfiler, readsf, and writesf objects. -

    2.4.2. tilde objects and audio connections

    +

    2.4.2. tilde objects and audio connections

    -Audio computations in Pd are carried out by "tilde objects" such as "osc~" -whoswe names conventionally end in a tilde character to warn you what they +

    Audio computations in Pd are carried out by "tilde objects" such as "osc~" +whose names conventionally end in a tilde character to warn you what they are. Tilde objects can intercommunicate via audio connections. When audio computation is turned on, or when you change the audio network while audio is on, Pd sorts all the tilde objects into a linear order for running; then this @@ -493,9 +540,7 @@ the audio network runs every 1.45 milliseconds. an error to connect an audio outlet to a non-audio inlet or vice versa; usually these errors are detected at "sort time" when audio is started or the network changed with audio running. An object's leftmost inlet may accept both audio -and messages; any other inlet is either one or the other. There is no quick -way to tell whether an inlet or output is for audio or messages; consult the -help window for the object. +and messages; any other inlet is either one or the other.

    The audio network, that is, the tilde objects and their interconnections, @@ -508,7 +553,7 @@ nonlocal signal connections. Your subpatches can have audio inlets and outlets via the inlet~ and outlet~ objects. -

    2.4.3. converting audio to and from messages

    +

    2.4.3. converting audio to and from messages

    If you want to use a control value as a signal, you can use the sig~ object to convert it. The +~, -~, *~, /~, osc~, and phasor~ objects can be configured @@ -520,9 +565,9 @@ but you can also sample a signal with tabwrite~ and then get access it via tabread or tabread4 (note the missing tildes!). There are also analysis objects, the simplest of which is "env~", the envelope follower. -

    2.4.4. switching and blocking

    +

    2.4.4. switching and blocking

    -You can use the switch~ or block~ objects to turn portions of your audio +

    You can use the switch~ or block~ objects to turn portions of your audio computation on and off and to control the block size of computation. There may be only one switch~ or block~ object in any window; it acts on the entire window and all of its subwindows, which may still have their own nested @@ -541,20 +586,20 @@ interaction, or to reduce "block delay" in feedback algorithms. At the own recursive filters.

    You can use switch~ to budget your DSP computations; for instance you might -want to be able to switch between two synthesis algorithms. Put each algorithm -in its own subpatch (which can have sub-sub patches in turn, for a voice bank -for instance), and switch each one off as you switch the other one on. Beware -of clicks; if you have a line~ controlling output level, give it time to ramp to -zero before you switch it off or it will be stuck at a nonzero value for the -next time it comes back on. +want to be able to switch between two synthesis algorithms. To do this, put +each algorithm in its own subpatch (which can have sub-sub patches in turn, for +a voice bank for instance), and switch each one off as you switch the other one +on. Beware of clicks; if you have a line~ controlling output level, give it +time to ramp to zero before you switch it off or it will be stuck at a nonzero +value for the next time it comes back on. -

    When a subpatch is switched off its audio outputs generate zeros; this costs a -fairly small overhead; a cheaper way to get outputs is to use throw~ inside -the switched module and catch~ outside it. +

    When a subpatch is switched off its audio outputs generate zeros; this +costs a fairly small overhead; a cheaper way to get outputs is to use throw~ +inside the switched module and catch~ outside it. -

    2.4.5. nonlocal signal connections

    +

    2.4.5. nonlocal signal connections

    -You may wish to pass signals nonlocally, either to get from one window to another, or +

    You may wish to pass signals non-locally, either to get from one window to another, or to feed a signal back to your algorithm's input. This can be done using throw~/catch~, send~/receive~, or delwrite~/delread~ pairs. Throw~ and catch~ implement a summing bus; throw~ adds into the bus and catch~ reads out the @@ -580,15 +625,15 @@ sorted after your delwrite~. The only way to ensure this is to create the delread~ after you created the delwrite~; if things get out of whack, just delete and re-create the delread~. -

    2.5. scheduling

    +

    2.5. scheduling

    -Pd uses 64-bit floating point numbers to represent time, providing sample +

    Pd uses 64-bit floating point numbers to represent time, providing sample accuracy and essentially never overflowing. Time appears to the user in milliseconds. -

    2.5.1. audio and messages

    +

    2.5.1. audio and messages

    -Audio and message processing are interleaved in Pd. Audio processing is +

    Audio and message processing are interleaved in Pd. Audio processing is scheduled every 64 samples at Pd's sample rate; at 44100 Hz. this gives a period of 1.45 milliseconds. You may turn DSP computation on and off by sending the "pd" object the messages "dsp 1" and "dsp 0." @@ -605,7 +650,7 @@ simultaneously. of zero. This delayed cascade happens after the present cascade has finished, but at the same logical time. -

    2.5.2. computation load

    +

    2.5.2. computation load

    The Pd scheduler maintains a (user-specified) lead on its computations; that is, it tries to keep ahead of real time by a small amount in order to be @@ -615,7 +660,7 @@ href="x3.htm" name=s3>getting Pd to run ).

    If Pd gets late with respect to real time, gaps (either occasional or frequent) will appear in both the input and output audio streams. On the -other hand, disk strewaming objects will work correctly, so that you may use +other hand, disk streaming objects will work correctly, so that you may use Pd as a batch program with soundfile input and/or output. The "-nogui" and "-send" startup flags are provided to aid in doing this. @@ -623,13 +668,13 @@ and "-send" startup flags are provided to aid in doing this. runs as a separate process. A flow control mechanism will be provided someday to prevent this from causing trouble, but it is in any case wise to avoid having too much drawing going on while Pd is trying to make sound. If a -subwindow is closed, Pd suspends sending the GUI update messages for it; +sub-window is closed, Pd suspends sending the GUI update messages for it; but not so for miniaturized windows as of version 0.32. You should really close them when you aren't using them. -

    2.5.3. determinism

    +

    2.5.3. determinism

    -All message cascades that are scheduled (via "delay" and +

    All message cascades that are scheduled (via "delay" and its relatives) to happen before a given audio tick will happen as scheduled regardless of whether Pd as a whole is running on time; in other words, calculation is never reordered for any real-time considerations. This is done @@ -640,7 +685,7 @@ it. These time tags are guaranteed to be consistent with the times at which timeouts are scheduled and DSP ticks are computed; i.e., time never decreases. (However, either Pd or a hardware driver may lie about the physical time an input arrives; this depends on the operating system.) "Timer" objects which -meaure time intervals measure them in terms of the logical time stamps of the +measure time intervals measure them in terms of the logical time stamps of the message cascades, so that timing a "delay" object always gives exactly the theoretical value. (There is, however, a "realtime" object that measures real time, with nondeterministic results.) @@ -648,12 +693,12 @@ time, with nondeterministic results.)

    If two message cascades are scheduled for the same logical time, they are carried out in the order they were scheduled. -

    2.6. semantics

    +

    2.6. semantics

    This section describes how objects in Pd are created, how they store data and how object and other boxes pass messages among themselves. -

    2.6.1. creation of objects

    +

    2.6.1. creation of objects

    The text in a box has a different function depending on whether it is a message, atom (number/symbol), or object box. In message boxes the text specifies the @@ -669,12 +714,12 @@ destroyed and the message is used to create the new one.

    The selector of the message (the first word in the message) is a selector which Pd interprets to mean which type of object to create. Any message -arguments (called "creation arguments") are used to parametrize the object +arguments (called "creation arguments") are used to parameterize the object being created. Thus in "makenote 64 250" the selector "makenote" determines the class of object to create and the creation arguments 64 and 250 become the initial velocity and duration. -

    2.6.2. persistence of data

    +

    2.6.2. persistence of data

    Among the design principles of Pd is that patches should be printable, in the sense that the appearance of a patch should fully determine its functionality. @@ -696,7 +741,7 @@ changed. if you are going to override them later; this is confusing to anyone who tries to understand the patch. -

    2.6.3. message passing

    +

    2.6.3. message passing

    Messages in Pd consist of a selector (a symbol) and zero or more arguments (which may be symbols or numbers). To pass a message to an object, Pd first @@ -711,7 +756,7 @@ determined by the selector of the creation message, i.e., the first atom of the creation message which is usually a symbol.

    Each class comes with a fixed collection of messages it may be sent. For -esxample, the "float" or "f" object takes "bang" and "float." These messages +example, the "float" or "f" object takes "bang" and "float." These messages are sent to "float" objects (objects whose class is float) via the leftmost, hot inlet. (The right inlet is a separate, auxiliary object.) Objects of class "float" respond to the message "bang" by outputting their current value, @@ -722,7 +767,7 @@ messages by setting their value and then outputting it. to messages it is sent, and may take "float" and "bang" messages, or others in addition or instead of them. -

    2.6.4. inlets and lists

    +

    2.6.4. inlets and lists

    The leftmost connection point at the top of most objects represents the object itself. Any other dark rectangle is a separate object called an "inlet" @@ -736,7 +781,7 @@ to the "list" message by distributing the arguments of the message to their inlets, except for the first argument which is passed as a "float" or "symbol" message to the object proper. -

    2.6.5. dollar signs

    +

    2.6.5. dollar signs

    In message or object boxes, message arguments starting with a dollar sign and a number (like "$1" or "$3-bazoo") are variables which are substituted @@ -747,14 +792,14 @@ or other) that the message box is responding to. Thus, if a message box gets "23 skidoo" and if it contains the text, "$2 until $1," out comes the message, "skidoo until 23." -

    Object boxes contain text wwhich forms a message to be sent to Pd to create +

    Object boxes contain text which forms a message to be sent to Pd to create and initialize the object. Here, $1, etc., are taken from the context in which the patch was loaded. When the patch is a new document or opened from a file the "$" variables are undefined. But if the patch is an abstraction (see the next section) they are -taked from the abstractions' creation arguments. +taken from the abstractions' creation arguments. -

    Constructions such as "$1-x" are expanded by string concatentation. This +

    Constructions such as "$1-x" are expanded by string concatenation. This is the mechanism for making local variables. In particular, $0 in an abstraction is a counter which is guaranteed to be unique to that abstraction, so sends and receives with names like "$0-bear" can be used as local send/receive pairs. @@ -764,20 +809,26 @@ beginning of the symbol; so, for instance, "rats-$1" will not be expanded. Occasionally you may want to have double or triple substitutions; this can be done one stage at a time by nesting abstractions (with each subpatch adding its own $-variable to the beginning of a symbol and passing that on -as argument to a further anstraction.) +as argument to a further abstraction.) + +

    For example, if you want to get dog-food, dog-ears, and cat-food, for +example, have an abstraction "a1" that invokes an abstraction "a2" twice, as +"a2 $1-food" and "a2 $1-ears", and then in a third patch call a1 twice, as +"a1 cat" and "a1 dog". Inside the four "a2" copioes, $1 will evaluate to +"dog-food", "cat-food", "dog-ears", and "cat-ears". -

    2.7. subpatches

    +

    2.7. subpatches

    Pd offers two mechanisms for making subpatches, called "one-off subpatches" and "abstractions." In either case the subpatch appears as an object box in a patch. If you type "pd" or "pd my-name" into an object box, this creates a one-off subpatch. For instance, in this fragment: -

    +

    subpatch

    the box in the middle, if clicked on, opens the sub-patch shown here: -

    +

    open subpatch window

    The contents of the subpatch are saved as part of the parent patch, in one file. If you make several copies of a subpatch you may change them @@ -791,17 +842,17 @@ messages and audio in a subpatch inlet or outlet; they must be one or the other exclusively. Inlets and outlets appear on the invoking box in the same left-to-right order as they appear in the subpatch. -

    2.7.1. abstractions

    +

    2.7.1. abstractions

    To make an abstraction, save a patch with a name such as "abstraction1.pd" and then invoke it as "abstraction1" in an object box: -

    +

    abstraction

    Here we're invoking a separate file, "abstraction1.pd", which holds the patch shown here (the border is the same as for the subpatch above): -

    +

    abstraction example

    You may create many instances of "abstraction1" or invoke it from several different patches; and changing the contents of "abstraction1" will affect all @@ -830,17 +881,17 @@ a different time in an object box than in a message box. In an object box, the "$" argument is expanded at creation time, and in a message box, at message time. -

    2.7.2. Graph-on-parent subpatches

    +

    2.7.2. Graph-on-parent subpatches

    If you open the "properties" dialog for a subpatch or an abstraction, you can check the "graph on parent" box to have the controls of the subpatch/abstraction appear on the parent. For instance, here is an invocation of "abstraction2": -

    +

    graph-on-parent abstraction

    where the patch "abstraction2.pd" contains: -

    +

    inside graph-on-parent abstraction

    Here, the number box in the abstraction shows up on the box that invoked the abstraction. The "graph on parent" flag is set in the abstraction @@ -857,7 +908,7 @@ are sent to visible controls and/or arrays. instead; so the number box in the sub-patch in the example above is the same one as you see in the box. Only controls are made visible in this way -

    2.8. numeric arrays

    +

    2.8. numeric arrays

    Linear arrays of numbers recur throughout the computer musician's bag of tricks, beginning with the wavetable oscillator. The wavetable oscillator later was @@ -880,7 +931,7 @@ two or more channels, use a separate array for each channel.

    Arrays are also useful as transfer functions, for example for nonlinear distortion of an audio signal, or to map a control onto a synthesis parameter. In situations like this one typically uses much shorter arrays, of no more -than a few hundered elements. They are also useful for storing measured +than a few hundred elements. They are also useful for storing measured spectra derived from the fft~ objects, and probably for many other uses.

    Arrays usually appear within subpatches created to house them, whether @@ -888,17 +939,17 @@ in "graph on parent" form (so that you see them within a rectangle drawn on the containing patch), or as a regular subpatch (which you see as a text box.) In the "graph on parent" form, an array appears as shown: -

    +

    array

    Arrays are indexed from 0 to N-1 where N is the number of points in the array. You can read an array value using the tabread object: -

    +

    array indexing

    Here we see that the third point of the array (index 2) has the value 0.4. To write into the array you can use the tabwrite object: -

    +

    setting an value in an array

    In this example, sending the message sets the third element to 0.5. (You may also send the two numbers to the two inlets separately.) @@ -907,7 +958,7 @@ may also send the two numbers to the two inlets separately.) and to arrays. These may also be done using audio signals. For example, the patch below creates a 440 Hz. tone with "array1" as a waveform: -

    +

    setting an array with a waveform

    Here phasor~'s outputs a sawtooth wave, repeating 440 times per second, whose output range is from 0 to 1. The multiplier and adder adjust the range from @@ -924,7 +975,7 @@ and/or changed later using the "properties" dialog.

    If you select "properties" on an array in a graph, you two dialogs, one for the array and one for the graph. The array dialog looks like this: -

    +

    array properties window

    You may use this to change the name and size, in addition to another property, "save contents". If "save contents" is selected, the array's values are stored @@ -934,13 +985,13 @@ probably not wish to store them in the patch but as separate soundfiles. This will be more efficient, and you may also then use a sound editor to modify them outside Pd. -

    If you check "delete me" and then "OK", the array wil be deleted. This is +

    If you check "delete me" and then "OK", the array will be deleted. This is an odd interface for deleting an object, and is only provided because Pd lacks a mechanism for selecting arrays (so that "cut" could serve).

    The graph dialog (which also pops up) is shown here: -

    +

    graph properties

    The X bounds initially range from 0 to the number of points in the table minus one (this is a good choice for arrays, although graphs holding other @@ -951,9 +1002,9 @@ range from 0 to 20,000. Finally, you choose the screen size of the graph, width and height, in screen pixels.

    Many other operations are defined for arrays; see the related patches -in the tutorial (starting at 2.control/15.array.pd) for more possibliities. +in the tutorial (starting at 2.control/15.array.pd) for more possibilities. -

    2.9. Data structures

    +

    2.9. Data structures

    (Note: this section is adapted from an article submitted to ICMC 2002.)

    The original idea in developing Pd was to make a real-time computer music @@ -982,7 +1033,7 @@ streams. Here is one simple example of a very short musical sketch realized using Pd: -

    +

    graphical score

    The example, which only lasts a few seconds, is a polyphonic collection of time-varying noise bands. The graphical ``score" consists of six objects, each @@ -1006,7 +1057,7 @@ mechanism.

    Here is the template associated with the graphical objects shown above: -

    +

    template for graphical score

    Templates consist of a data structure definition (the "struct" object) and zero or more drawing instructions ("filledpolygon" and "plot"). The "struct" @@ -1039,14 +1090,14 @@ color is given as 0, or black. The second one plots "pitch" using the color "voiceno" slot in the data structure, so that color will vary according to its "voiceno" slot. -

    2.9.1. Traversal

    +

    2.9.1. Traversal

    Pd objects are provided to traverse lists and arrays, and to address elements of data structures for getting and setting. Here is a patch showing how these facilities could be used, for example, to sequence the graphical score shown above: -

    +

    traversal example patch

    Pd has no built-in sequencer, nor even any notion that "x" values should be used as a time axis. (However, a "sort" function is provided, which reorders @@ -1055,7 +1106,7 @@ data collections as x-ordered sequences.) Recording sequences of events into lists, and/or playing the lists back as sequences, are functionalities that the user is expected to supply on top of Pd's offerings, which, it is hoped, would allow those functionalities within a much larger range of possibilities, to -include random reorderings of events, score following, self-modifying scores, +include random re-orderings of events, score following, self-modifying scores, reactive improvisation, and perhaps much more.

    Traversal of data is made possible by adding a new type of atom, "pointer", @@ -1116,10 +1167,10 @@ Finally, the voice abstraction puts its audio output on a summing bus. of objects (having different templates). In this way, an arbitrarily rich personal "score language" can be developed and sequenced. -

    2.9.2. Accessing and changing data

    +

    2.9.2. Accessing and changing data

    In general, accessing or changing data is done via "pointers" to -"scalars". Numbers and symbols withing scalars are accessed using the +"scalars". Numbers and symbols within scalars are accessed using the "get" object and changed, in the same way, using "set". Since lists and arrays are composed of scalars, every actual number or symbol in a data heap will be a number or symbol element of some scalar. To access them, it @@ -1134,7 +1185,7 @@ a number, chases down the numbered, scalar, element of the named array field.

    To alter "float" or "symbol" elements of scalars is straightforward using the "set" object, but arrays and lists can't be set by assignment; -there is no suitable data type available withing messages. Lists could +there is no suitable data type available within messages. Lists could possibly be "settable" by passing pointers to other lists, but permitting this would have required either automatically doing deep copies of data structures to carry out the assignments, or else implementing a garbage collecting memory @@ -1154,7 +1205,7 @@ Deletion is less flexible; the only operation is to delete an entire list. it's not clear how to protect against stale pointers efficiently, except by voiding the entire collection of pointers into a list.) -

    2.9.3. Editing

    +

    2.9.3. Editing

    The graphical score shown above can be edited by dragging breakpoints, or by adding and deleting them, using mouse clicks. Also, entire objects or @@ -1184,7 +1235,7 @@ previously existing ones are assumed to be new and are initialized.

    It can happen that two "struct" objects compete to define the same data structure, or that the user reads in data from a file which expects a different version of the structure, or alternatively, that the "struct" object for -existing data objects disappears. For this reasn, Pd maintains a private +existing data objects disappears. For this reason, Pd maintains a private representation of the last active version of a "struct" until all similarly named "structs," as well as all data using that "struct", have disappeared. If the user introduces a new version of the "struct" and only @@ -1195,7 +1246,7 @@ up belonging to two or more structures of the same name. The worst that can happen is that data may lose their drawing instructions, in which case Pd supplies a simple default shape. -

    2.9.4. Limitations

    +

    2.9.4. Limitations

    When examples get more complicated and/or dense than the one shown here, it becomes difficult to see and select specific features of a data collection; @@ -1220,3 +1271,4 @@ handling primitives and the graphical presentation and editing functions. + diff --git a/pd/doc/1.manual/x3.htm b/pd/doc/1.manual/x3.htm index d34f70e8..c77f3571 100644 --- a/pd/doc/1.manual/x3.htm +++ b/pd/doc/1.manual/x3.htm @@ -1,37 +1,85 @@ + + - -Pd Documentation 3 - - - -

    - -
    -Pd Documentation chapter 3: Getting Pd to run -
    -
    - back to table of contents + + Pd Documentation 3 + + + + + + + +

    Pd Documentation chapter 3: Getting Pd to run

    + +

    + back to table of contents

    +

    -Pd runs under Irix, Microsoft Windows, Linux, and Mac OS 10.2 (Jaguar). +

    Pd runs under Irix, Microsoft Windows, Linux, and MacOS 10.2 (Jaguar). How to get Pd up and running depends on your operating system, but the overall strategy is the same. You must first get and install it, and then untangle whatever problems arise in handling audio and MIDI input and output, and finally get Pd to meet its real-time obligations reliably. +

    Installation instructions are platform-specfic; the following four +sections +will describe what to do for various operating systems you might have. In case of trouble also consult the Pd mailing list archive on http://iem.kug.ac.at/mailinglists/pd-list/ , which often has late-breaking news about configuration problems and solutions. +The rest of this section describes how to get audio and MIDI to work. +

    +To test audio and MIDI, start Pd and select "test Audio and MIDI" from the +"Media" menu. You should see a window like this: + +

    + test tone patch +

    + +

    First, try to get Pd to play a sine wave over your speakers. The "TEST +TONE" control at top left turns this on and off. Normally, all the output +channels are turned on so that when you turn the tone on (to a soft -40 dB or a +louder -20 dB) you should get output on the first six of your output channels. +(If you have fewer than six output channnels open, the extra +channels aren't played; and if you have more, this particular patch won't +use them.) + +

    If there's anything wrong, the most likely outcome is that you will hear +nothing at all. This could be for any of at least three reasons: Pd might +have failed to open the audio device; the audio card's output volume might +be set to zero; or your audio system might not be set to amplify the computer +output. + +

    The number boxes labeled "AUDIO INPUT" show the levels of incoming +audio, in dB, with 100 being maximum. (Incoming signals may clip at +RMS levels below 100; for instance, a sinusoid clips at about 97 dB.) +Any DC present in the input (such as you get with cheap audio hardware) +will show up as level unless you turn on the "input hipass" toggle +at right; then the DC component is filtered out before metering. + +

    To test the quality of audio input and output, turn on "monitor" +(also at right) which causes the inputs to be played to the outputs at +unit gain. You should hear a faithful, non-distored copy of whatever is +sent through the patch. + +

    It is easy to get two copies of Pd running by accident; on most machines +only one at a time may be inputting and outputting sound. (Some copy of Pd +might have audio or MIDI devices open and prevent the copy you're trying to use +from getting access to them.) Having extra +copies of Pd around will also eat CPU cycles uselessly.

    You may be interested in getting only audio output or audio input, or you may need both to run simultaneously. By default, Pd will try to run both, but if you don't need either input or output, you may find that Pd runs more reliably, or at least more efficiently, with the unused direction -turned off. This is controlled by Pd's command line flags. +turned off. This may be specified in Pd's command line flags or using the +"audio settings" dialog panel.

    Depending on your application you will have a more or less stringent latency @@ -43,141 +91,66 @@ inevitable occasions where the CPU runs off to service some different task from Pd. How small this latency can be chosen depends on your OS and your audio driver. -

    -To test audio and MIDI, start Pd and select "test Audio and MIDI" from the -"help" menu. -

    TIP: If Pd starts up but you get distortion or glitches in the audio output, this could be either because the "audio I/O buffer" isn't big enough, or else because the CPU load of the patch you're running is too great for the machine you have, or else because the ADC and DAC are out of sync or even at different sample rates. To test for the first possibility, try increasing the -"-audiobuf" parameter in the command line (but see also under your OS below.) -For the second, start up your favorite performance monitor program; and for the -third, try starting Pd up with ADCs disabled. - -

    Here are instructions for getting and installing Pd for the four -operating systems it runs on: IRIX, MS Windows, Linux, and Max OSX. - -

    3.1. IRIX (SGI machines)

    - -

    (NOTE: as of release 0.35 I haven't had an IRIX machine to compile -Pd on. Soeren Bovbjerg has kindly compiled 0.35 and 0.36 for IRIX; -you can find these at - http://www.cvmt.dk/~sb/. ) - -

    Download Pd, which will be a "tar.Z" file. You can unpack this by -typing "zcat [name].tar.Z | tar xf -" to a shell. This creates a directory -named "pd". - -

    -Starting with release 0.25, Pd should come in "n32" and "o32" versions. -"o32" is the default and will run on IRIX 5.x and up. "n32" runs faster, -but only on 6.x and up. Also, "externs" have to be updated for n32. The -"pd" executable (bin/pd in the distribution) is a symbolic link to either -"pd-o32" or "pd-n32." - -

    NOTE: "externs" appear to be broken in the N32 version... I'm not sure -how long this has been true. If you want to use external objects, you have -to use the O32 version. - -

    -Please note that the path to the Pd executable program can't contain -space characters; don't put it in a directory named "Program Files" -for example. - -

    -If for example you put Pd in ~, the executable program -will be ~/pd/bin/pd. The program looks at its command line to -figure out where it is, so it's best to invoke Pd by its full pathname. -You should always invoke Pd from a Unix shell because many important -messages appear on the standard error. - -

    -The simplest way to invoke Pd is to -make an alias in your ".cshrc" file (assuming you use the "c" shell) such as: -

    -
-    alias pd ~/pd/bin/pd
-
-
    -(assuming your Pd distribution landed in ~, for example). - -

    -Pd will open the "default" audio input and output devices, without regard -for whether they are in sync or not. This will be bad if they aren't; use -the "-noadc" or "-nodac" flag to disable either the input or output. Pd is -supposed to handle up to 8 channels of audio in and/or out. (But at least -one user had to recompile Pd on his Onyx to get 8 channels working.) - -

    -As to MIDI, Pd simply attempts to open all available MIDI devices for input and -output, which is probably very bad on anything more recent than my Indy. If -any MIDI ports fail to open either for input or output, all MIDI is disabled. - -

    Pd has not been fixed to request real-time priority from Irix; it will -compete with all other processes on your machine for CPU time. - -

    Audio and MIDI in IRIX
    - -

    -Pd takes command line arguments to set the number of input and output channels -and the sample rate. These don't affect the SGI's audio settings, which you -have to set separately using the "audio panel." Pd does detect the audio -sample rate if you don't specify one on the command line. - -

    -On SGI machines, you have to work to get MIDI running. Before you start Pd, verify -that least one MIDI port is configured open. Pd opens the FIRST MIDI port -that's open. You might want to get rid of the "software" MIDI port if you're -running 6.x. On Indys, the usual practice is to open serial port number 2 -because some systems configure port 1 as "console" by default. You can use the -GUI if you want, or else just type -

    -
-    startmidi -d /dev/ttyd2
-
-
    -to get port 2 speaking MIDI, and -
    -
-    stopmidi
-
-
    -to stop it. You can test whether MIDI is configured by typing, -
    -
-    ps -dafe | grep midi
-
-
    -and looking for "startmidi" processes. -

    -It's a good idea to connect your serial port to your MIDI interface before -typing the "startmidi" command, not afterward, at least in 5.x. We use the -Opcode Studio 3 interface but in principle any Mac-compatible one should work. - -

    -The O2 apparently has RS232 ports, not RS422. I think SGI's web site says -something about how to deal with this. - -

    3.2. Microsoft Windows

    - -

    Pd is compiled under NT, but shoould work under any version of Windows -since 95. Pd will appear as a "zip" file. Unzip this, creating a directory -such as \pd. (You can put it wherever you like but the path should have no -spaces in it; so "Program Files" would be a bad place.) +audio latency in the command line or the "audio settings" dialog (but see also +under your OS below.) For the second, start up your favorite performance +monitor program; and for the third, try starting Pd up with ADCs disabled. + +

    In addition to the "test audio and MIDI" patch, the "Media" menu +contains items for controlling audio and MIDI settings. The first two +items, "Audio on" and "Audio off", open or close the audio devices and +start or stop Pd's audio computation. + +

    If there is a choice of +audio API to make, the Media menu will display them. (On Linux, they are +OSS, ALSA, and Portaudio; on Windows, you get MMIO and ASIO). More information +about the APIs appears in the sections below. + +

    Next is the "Audio settings..." menu item, which opens a dialog like this: + +

    + audio settings dialog +

    + +The exact choices you get depend on the operating system and API. The sample +rate controls both audio output and input. The audio throughput delay is +the nominal amount of time, in milliseconds, that a sound coming into the +audio input will be delayed if it is copied through Pd straight to the +output. Naturally you would like this to be as small as possible, but, +depending on OS, API, and even the specific choice of audio hardware, there +will be a limit to how small you can make this. You can typically get +10 msec on linux (and lower still if you use special tricks), 30 msec on Mac +OSX, and 60 msec on Windows (but note that there might be ways that a +patient Windows user can reduce this). + +

    Next you get a choice of input and output device. If you want to open +more than one, hit "use multiple devices" and you'll be allowed up to 4 +in and 4 out. Each audio device is 2 channels by default, but you may +specify more if your hardware supports it. + +

    3.1. Installing Pd in Microsoft Windows

    + +

    Pd is compiled under NT, but should work under any version of Windows since +95. Pd will appear as a self-extracting archive (a ".exe" file). Run this and +select a destination directory when prompted, such as "\pd" or "Program +Files\pd".

    -If for example you put Pd in C:\pd, the executable program will be -C:\pd\bin\pd. You can simply adjust your path to include C:\pd\bin and just -invoke "pd" in a command prompt window. You can also make a "command prompt" -shortcut to start Pd. +If for example you put Pd in "C:Program Files\pd", the executable program will be +"C:Program Files\pd\bin\pd". You can simply adjust your path to include +C:\pd\bin and then +invoke "pd" in a command prompt window. You can also make a shortcut to the +executable program (left-click on it and drag to the desktop, for example.)

    Pd requires "TCP/IP networking" to be turned on. This doesn't mean you have to be on a real network, but simply that Pd actually consists of two -programs that make a "network link" to intercommunicate. +programs that make a "network link" (locally) to intercommunicate. -

    The vanishing window
    +

    The vanishing window

    Pd is a "command line" program. Most error and diagnostic messages from Pd appear on the command prompt window Pd runs from. @@ -189,31 +162,39 @@ print an error and exit. You won't see this error unless you arrange for the to do this is to make a "batch" file ("run.bat", say) containing the Pd command line. -

    Audio in Microsoft Windows
    +

    Audio in Microsoft Windows

    You can ask for a list of audio and MIDI devices by typing "pd -listdev"; you can then specify which audio and MIDI device to use. Type "pd -help" (or make any mistake) to get the syntax for specifying -which device to use. +which device to use. You can modify the Pd shortcut (or batch file) to +set these.

    -Most PC sound cards seem to have MIDI built in; you don't seem to have to -do anything special to get Pd to send and receive MIDI. You can list and -choose MIDI devices in the same way as audio. +Alternatively, (and especially when just starting out) you can experiment +with different audio configurations using the "audio settings" +item in the Media menu. + +

    +You can list and +choose MIDI devices in the same way as audio; note that, by default, MIDI +input is disabled in Windows (because it's possible to hang up some MIDI +devices if Pd exits unexpectedly).

    MIDI timing is very poor if you are using simultaneous audio input and output; if you suppress either audio input or output things will improve somewhat under NT; you can apparently get the jitter down to ~40 msec. On W95 performance is simply terrible. W98, with either audio input or output suppressed, offers -fairly good MIDI timing (~5 msec jitter) but crashes occasionally. +fairly good MIDI timing (~5 msec jitter). The "first edition" used to crash +occasionally; this might be fixed in the "second edition".

    Some NT and W98 drivers greet you with a constant trail of "resyncing audio" messages. Sometimes you can fix this by invoking Pd with the "-noresync" flag. -

    ASIO
    +

    ASIO

    As of version 0.35 Pd supports ASIO. Invoke Pd as "pd -asio" and, if needed, specify "-sounddev" (etc.) flags to specify which device (see @@ -222,58 +203,19 @@ from the default (256 samples) and "-audiobuf" in milliseconds. Pd will round this down to a power of two buffers, each of "-blocksize" in sample frames. -

    Using an RME Hammerfall, and specifying "-audiobuf 5 -blocksize 32" I -was able to get about 7 milliseconds of throughput delay (as measured by -the latency-measurement patch in 7.stuff/tools.) As always, you can specify -"-channels" to any even number up to the maximum (32, I think) or can specify -channel count separately for input and output (-inchannels and -outchannels). - -

    The special joys of Windows 95
    - -

    -On Windows 95 you can expect a hard time. Every user who tries it seems to -encounter a new problem. The best way to run Pd is to get into the "MSDOS -Prompt" program and type \pb\bin\pd to it (or whatever the path ends up being.) -You can probably put pd's "bin" directory in your path so that you just type -"pd" to the prompt. - -

    -You don't want to run Pd from the "run" menu because if it fails to start up -the window holding the error message will disappear instantly. Ditto for -clicking on "batch files" or on the Pd executable itself. - -

    -The most common reason Pd might fail to start up in W95 is not having -"networking" turned on. Pd is actually two programs that establish an IP -interconnection. Beware that this sometimes fools Windows into calling your -ISP for no reason. - -

    -It is often necessary to specify a huge audio buffer to get steady audio -output in W95; see the command line arguments below. - -

    3.3. Linux

    +

    3.2. Installing Pd in Linux

    What to do depends on which flavor of Linux you are running (e.g., Debian or Red Hat). The instructions here should work for Pd 0.33 and up regardless of -your situation. (If not, you can read the Pd mailing list archives for -recent problems; if you have found a new problem you're welcome to post it +your situation. (If not, you can read the Pd mailing list archives for +recent problems; if you have found a new problem you're welcome to post it to the list.) -

    Before you start, you might want to check that you have the resources Pd -needs. The main things you need are the C compiler, X windows (including -the X development package for Pd to link against) and TK. If you're running -Redhat or Mandrake 7.x or up, I think these are all present by default. -The RedHat X client developer "RPM" package is called XFree86-devel. - -

    You don't absolutely have to have the X server package running; you can run -Pd on the microprocessor in your refrigerator as long as it can connect to an X -server on another machine. - -

    If you're running RedHat you might want to use RPM to install Pd. For -other linux distributions, download the "tar.gz" version and compile it. +

    If you're running RedHat or Mandrake you might want to use RPM to install +Pd. For other linux distributions, download the "tar.gz" version and compile +Pd. -

    Getting Pd as an RPM
    +

    Getting Pd as an RPM

    Download Pd, perhaps from @@ -288,7 +230,13 @@ the directory containing the file, and type the command,

    (substituting the real file name.) Then you should be able to type "pd" to a shell and watch the Pd main window appear. -

    Getting Pd as a .tar.gz
    +

    Getting Pd as a .tar.gz

    + +

    Before you start, you might want to check that you have the resources Pd +needs. The main things you need are the C compiler, X windows (including +the X development package for Pd to link against) and TK. If you're running +Redhat or Mandrake 7.x or up, I think these are all present by default. +The RedHat X client developer "RPM" package is called XFree86-devel.

    Download Pd, perhaps from @@ -300,20 +248,22 @@ the directory containing the file, and type the command, 

         zcat pd-linux-033.tar.gz | tar xf -
    -which creates a directory named "pd". I do this from my home directory. +

    which creates a directory named "pd". I do this from my home directory. Next, compile it. "CD" to pd and read the INSTALL.txt, or else just cd to "pd/src" and type +


    ./configure
    make depend
    make +

    You can pass flags to "configure" to customize your compilation: 

    -    To enable ALSA 0.9x (the latest one), add "--enable-alsa".
-    To enable the older ALSA 0.5x, add "--enable-old-alsa". 
-    To enable Ritsch's RME 9652 driver, add --enable-rme".
+    To enable debugging (and losing code optimization) add "--enable-debug".
+    To enable ALSA 0.9x or up, add "--enable-alsa".
+    To use Portaudio version 19 (experimental), add "--enable-portaudio".
     To put Pd in /usr/bin instead of /usr/local/bin, add "--prefix=/bin".
    @@ -322,18 +272,20 @@ to "pd/src" and type

    Alternatively, as superuser, you can run "make install" after "make depend" and then anyone on your system can just type "pd" to run it. -

    Testing audio and MIDI.
    +

    Testing audio and MIDI.

    Next try audio. We want to know whether audio output works, whether audio -input works, and whether they work simultaneously. First run "aumix" to -see audio input and output gains and which device is "recording". +input works, and whether they work simultaneously. First run "aumix" (or +any newer audio mixer app) to +check audio input and output gains and learn which input (mic; line; +etc.) is "recording". Then test audio output by running 

         pd -noadc
    -and selecting "test audio and MIDI" from the "help" menu. You should see a -patch. Turn on the test tone and listen. Do the usual where's-the-signal +

    and selecting "test audio and MIDI" from the "Media" menu. You should see +a patch. Turn on the test tone and listen. Do the usual where's-the-signal business.

    @@ -341,7 +293,7 @@ Then quit Pd and test audio input via 

         pd -nodac
    -Re-open the test patch and hit "meter"; look at the levels. 100 dB is a +

    Re-open the test patch and hit "meter"; look at the levels. 100 dB is a hard clip; arrange gains so that the input signal tops out around 80 or 90, but no higher. @@ -352,12 +304,12 @@ hand there's no complaint, and if the audio test patch does what you want, you might wish to experiment with the "-audiobuffer" flag to see what values of audio latency your audio system can handle. -

    Audio hardware in Linux

    +

    Audio hardware in Linux

    Be forewarned: installing and testing audio and MIDI drivers in Linux can take days or weeks. There apears to be no single place where you can get detailed -information on Linux audio. +information on Linux audio.

    Depending on your hardware and software, you might or might not be able to @@ -375,20 +327,10 @@ releases. You can get ALSA from http://www.alsa-project.org/ . -

    -(There is also a commercial version of the OSS drivers which costs $30 (slightly -more for certain audio cards.) Hit - - - http://www.opensound.com/ . - -These might be easier to use than the free OSS drivers, but I've never tried -them.) -

    ALSA is able to emulate OSS, so that you can usually run Pd using the default "OSS" settings even if it's actually ALSA that's running. -

    Installing and configuring FREE OSS
    +

    Installing and configuring FREE OSS

    OSS is really a collection of loadable device drivers. The commands @@ -409,14 +351,16 @@ soundlow 1 [sound] 0 aic7xxx 23 2 -then OSS is running, and if all you see is: + +

    then OSS is running, and if all you see is: + 

     
 eepro100           3            1 (autoclean)
 aic7xxx           23            2
    -then it isn't. You can turn OSS off by running "rmmod" repeatedly, starting +

    then it isn't. You can turn OSS off by running "rmmod" repeatedly, starting with "opl3" (or whatever) so as not to remove any module before you remove all the modules that depend on it. In the above listing, "opl3*" is device dependent and you might see different names. @@ -440,7 +384,7 @@ alias sound-slot-1 es1371 -Here the two sound cards are the (motherboard resident) i810 driver and an +

    Here the two sound cards are the (motherboard resident) i810 driver and an ensoniq es1371.

    In RedHat at least, the "sndconfig" program tries to automatically search @@ -452,14 +396,14 @@ often not the one you want to use! two, but the majority of drivers, even for new sound cards, only support "block." Pd makes "block" the default. -

    ALSA (Advanced Linux Sound Architecture)
    +

    ALSA (Advanced Linux Sound Architecture)

    ALSA is newer, hence less stable and harder to use, than OSS. Alsa comes in a "finished" version (0.5.x) and a different, redesigned, "beta" version, 0.9. Installing ALSA can be tricky and/or confusing. -

    As of version 0.37 Pd works only with 0.9.x versions. +

    As of version 0.37 Pd works only with 0.9.x versions. The RPM version of Pd is compiled for 0.9.x.

    By default, Pd uses OSS. If you are running ALSA, Pd will use ALSA's OSS @@ -470,7 +414,7 @@ to be used, include the "-alsa" flag in the command line. flag. So, for instance, "-alsadev 3" means your third card, counting from one. You can also specify it the ALSA way: "-alsadev hw:3,0". -

    Which sound card?
    +

    Which sound card?

    Here's a rundown on my experiences with sound cards so far. See @@ -483,24 +427,17 @@ I/O ports and one SPDIF. There is a "baby hammerfall" also, which I think is the "9632." DO NOT CONFUSE THE 9652/9632 WITH OTHER RME BOARDS WHICH MIGHT NOT WORK WITH PD. -

    Guenter Geiger has an OSS driver for Hammerfall for 2.4 kernels (such as -RedHat 7.1 and up). You have to download and compile it: - - - http://gige.xdv.org/pages/rme . - -

    You must then run Pd using the "-32bit' flag, because this uses a -non-standard extension of OSS to 32 bit samples. - -

    Hammerfalls now have an ALSA driver; from what I hear -it won't work yet with Pd. I was unable to install the ALSA driver on the -two machines I tried ("no such device"). +

    Hammerfalls now have an ALSA driver; aapparently, it works well to install +this and then run Pd using OSS emulation. (Unfortunately, this will only give +you 16 bit resolution. Maybe the also "plug" device will work better; I +haven't tried this.)

    MIDIMAN
    -Midiman sells devices with between 4 and 12 analog channels in and out, for -which there are ALSA drivers. It seems to work fine with the old ALSA driver -(0.5). I'm running mine in Alsa 0.9 beta 10. The driver name is "ice1712". +

    Midiman sells PCI devices (delta 44, 66, 1010, and 1010LT) +with between 4 and 10 channels in and out, for +which there are ALSA drivers. +I'm running mine in Alsa 0.9 beta 10. The driver name is "ice1712".

    Alsa provides an "envy24control" program (in "utils". You should run this and check that your ice1712's sync source is internal if you have no @@ -509,33 +446,35 @@ but don't take it for granted...

    i810/i815
    -In RedHat 7.0, motherboards with native i810 audio systems don't work in +

    In RedHat 7.0, motherboards with native i810 audio systems don't work in full duplex (they crash linux). Either run Pd -noadc or else (better) install ALSA. -

    3.4. Macintosh OSX

    +

    3.3. Installing Pd in Macintosh OSX

    -Pd version 0.35 and up support Macintosh OSX, although there are still some -problems. You can always just download -the sources and compile it yourself, or (easier) +

    Pd version 0.35 and up support Macintosh OSX, although there are still some +problems. You can always just download +the sources and compile them yourself, or (easier) find a MacOSX-style "package". The first package was put together by Adam -Lindsay and can be found on - -http://homepage.mac.com/atl/sw. The package simply installs itself -and you needn't follow the directions below. - -

    To install on OSX from source:
    +Lindsay and can be found on + +http://homepage.mac.com/atl/sw. The package simply installs itself +and you needn't follow the directions below. +

    +

    To install on OSX from source:

    -Whether you've downloaded the source or the "package" you can -always compile Pd for yourself, whether to make your own improvements, or +

    +Whether you've downloaded the source or the "package" you can +always compile Pd for yourself, whether to make your own improvements, or possibly so that you can get the newest version before it shows up compiled for -Mac OS X. +Mac OS X.

    To be able to compile Pd, you must have installed Tcl/Tk -specifically in -/Applications/Wish Shell.app -and /Library/Frameworks/Tk.framework and /Library/Frameworks/Tcl.framework. +specifically in +/Applications/Wish Shell.app +and /Library/Frameworks/Tk.framework and /Library/Frameworks/Tcl.framework. +

    First download and install TK for OSX (http://sourceforge.net/projects/tcl/). Get a recent one compiled for OSX, by chasing through "latest file releases", and finding a "download" @@ -547,9 +486,13 @@ on your system.

    For old versions of Tcl/Tk you also had to get the "h" files from XFree86 and put them in /usr/X11R6/include. You can download just the H files from: -

    -    http://www.crca.ucsd.edu/~msp/x.tgz
-
    + +

           + +http://www.crca.ucsd.edu/~msp/x.tgz + + +

    (the individual files seem to have adequate copyright notices so that I can just redistribute them.) ((I hope this is no longer necessary but I notice people keep downloading these files anyway, so I'll leave them there @@ -559,19 +502,19 @@ a while longer until I'm sure they're not needed.)) such as ~/pd-0.35-test17 , cd to pd-0.36-0/src, type "./configure" and "make". Then type ~/pd-0.36-0/bin/pd to a shell and enjoy! -

    If you wish you can put the line, +

    If you wish you can put a line such as, 

         alias pd ~/pd/bin/pd
    -in the file, ~/.tcshrc, so that you can later just type "pd" to a shell. (The +

    in the file, ~/.tcshrc, so that you can later just type "pd" to a shell. (The shell only reads the ~/.tcshrc file on startup, so this won't take effect in any existing shells unless you specially type 

         source ~/.tcshrc
    -to them.) +

    to them.)

    In some cases you have to explicitly give "-soundindev" and "-soundoutdev" flags for Pd to open audio correctly; "pd -listdev" should show you the @@ -587,9 +530,113 @@ I think you just download the OSX driver and follow directions. pd -midiindev 1 -midioutdev 2 -to get MIDI working. +

    to get MIDI working. + +

    3.4. Installing Pd in IRIX (SGI machines)

    + +

    (NOTE: as of release 0.35 I haven't had an IRIX machine to compile +Pd on. Soeren Bovbjerg has kindly compiled 0.35 and 0.36 for IRIX; +you can find these at + http://www.cvmt.dk/~sb/ .) + +

    Download Pd, which will be a "tar.Z" file. You can unpack this by +typing "zcat [name].tar.Z | tar xf -" to a shell. This creates a directory +named "pd". + +

    +Starting with release 0.25, Pd should come in "n32" and "o32" versions. +"o32" is the default and will run on IRIX 5.x and up. "n32" runs faster, +but only on 6.x and up. Also, "externs" have to be updated for n32. The +"pd" executable (bin/pd in the distribution) is a symbolic link to either +"pd-o32" or "pd-n32." + +

    NOTE: "externs" appear to be broken in the N32 version... I'm not sure +how long this has been true. If you want to use external objects, you have +to use the O32 version. + +

    +If for example you put Pd in ~, the executable program +will be ~/pd/bin/pd. The program looks at its command line to +figure out where it is, so it's best to invoke Pd by its full pathname. +You should always invoke Pd from a Unix shell because many important +messages appear on the standard error. + +

    +The simplest way to invoke Pd is to +make an alias in your ".cshrc" file (assuming you use the "c" shell) such as: +

    +
    +
+    alias pd ~/pd/bin/pd
+
+
    +

    (assuming your Pd distribution landed in ~, for example). + +

    +Pd will open the "default" audio input and output devices, without regard +for whether they are in sync or not. This will be bad if they aren't; use +the "-noadc" or "-nodac" flag to disable either the input or output. Pd is +supposed to handle up to 8 channels of audio in and/or out. (But at least +one user had to recompile Pd on his Onyx to get 8 channels working.) + +

    +As to MIDI, Pd simply attempts to open all available MIDI devices for input and +output, which is probably very bad on anything more recent than my Indy. If +any MIDI ports fail to open either for input or output, all MIDI is disabled. -

    3.5. graphics rendering using GEM

    +

    Pd has not been fixed to request real-time priority from Irix; it will +compete with all other processes on your machine for CPU time. + +

    Audio and MIDI in IRIX

    + +

    +Pd takes command line arguments to set the number of input and output channels +and the sample rate. These don't affect the SGI's audio settings, which you +have to set separately using the "audio panel." Pd does detect the audio +sample rate if you don't specify one on the command line. + +

    +On SGI machines, you have to work to get MIDI running. Before you start Pd, verify +that least one MIDI port is configured open. Pd opens the FIRST MIDI port +that's open. You might want to get rid of the "software" MIDI port if you're +running 6.x. On Indys, the usual practice is to open serial port number 2 +because some systems configure port 1 as "console" by default. You can use the +GUI if you want, or else just type +

    +
+    startmidi -d /dev/ttyd2
+
+
    + +

    to get port 2 speaking MIDI, and + +

    +
+    stopmidi
+
+
    + +

    to stop it. You can test whether MIDI is configured by typing, + +

    +
+    ps -dafe | grep midi
+
+
    + +

    and looking for "startmidi" processes. + +

    +It's a good idea to connect your serial port to your MIDI interface before +typing the "startmidi" command, not afterward, at least in 5.x. We use the +Opcode Studio 3 interface but in principle any Mac-compatible one should work. + +

    +The O2 apparently has RS232 ports, not RS422. I think SGI's web site says +something about how to deal with this. + + +

    3.5. graphics rendering using GEM

    GEM, originally by Mark Danks but now supported by Iohannes Zmoelnig, is essentially an extension of Pd that allows you to do OpenGL programming @@ -598,9 +645,9 @@ into Pd for audio. Find out more from Johannes's page. -

    3.6. The Pd command line

    +

    3.6. The Pd command line

    -Pd is a "command line" program. The best way to run it is from your +

    Pd is a "command line" program. The best way to run it is from your "terminal emulator," "shell," or "MSDOS prompt." The command line is: 

    @@ -609,33 +656,40 @@ Pd is a "command line" program.  The best way to run it is from your
    -although you may have to specify a path so your command interpreter can find -Pd (OS dependent.) Possible options include: +

    although you may have to specify a path (such as "~/pd/bin/pd" or +"C:\program files\pd\bin\pd") so your command interpreter can find +Pd. Possible options include: 

     
 audio configuration flags:
--r            -- specify sample rate
+-r <n>           -- specify sample rate
+-audioindev ...  -- sound in device list; e.g., "2,1" for second and first
+-audiooutdev ... -- sound out device list, same as above 
+-audiodev ...    -- specify both -audioindev and -audiooutdev together
 -inchannels ...  -- number of audio in channels (by device, like "2" or "16,8")
 -outchannels ... -- number of audio out channels (by device)
 -channels ...    -- specify both input and output channels
--audiobuf     -- specify size of audio buffer in msec
--blocksize    -- specify audio I/O block size in sample frames
--sleepgrain   -- specify number of milliseconds to sleep when idle
+-audiobuf <n>    -- specify size of audio I/O buffer in msec
+-blocksize <n>   -- specify audio I/O block size in sample frames
+-sleepgrain <n>  -- specify number of milliseconds to sleep when idle
 -nodac           -- suppress audio output
 -noadc           -- suppress audio input
 -noaudio         -- suppress audio input and output (-nosound is synonym) 
--listdev          -- list audio and MIDI devices
--audioindev ...  -- sound in device list; e.g., "2,1" for second and first
--audiooutdev ... -- sound out device list, same as above 
--audiodev ...    -- specify both -audioindev and -audiooutdev together
+-listdev         -- list audio and MIDI devices
 
 (linux specific audio:)
--frags        -- specify number of audio fragments (defeats audiobuf)
--fragsize     -- specify log of fragment size ('blocksize' is better...)
--stream          -- use stream mode audio (e.g., for es1370 audio cards)
--alsa            -- use ALSA audio drivers
--alsadev      -- ALSA device # (counting from 1) or name: default hw:0,0
+-frags <n>       -- specify number of audio fragments (defeats audiobuf)
+-fragsize <n>    -- specify log of fragment size ('blocksize' is better...)
+-oss            -- use ALSA audio drivers
+-alsa           -- use ALSA audio drivers
+-pa             -- use portaudio (experimental version 19)
+-alsadev <n>     ----- obsolete: use -audiodev
+-32bit             ---- (probably obsolete) -- use 32 bit OSS extension
+
+(Windows specific audio:)
+-mmio           -- use MMIO drivers and API
+-asio           -- use ASIO drivers and API
 
 MIDI configuration flags:
 -midiindev ...   -- midi in device list; e.g., "1,3" for first and third
@@ -646,85 +700,73 @@ MIDI configuration flags:
 -nomidi          -- suppress MIDI input and output
 
 general flags:
--path      -- add to file search path
--open      -- open file(s) on startup
--lib       -- load object library(s)
--font         -- specify default font size in points
+-path <path>     -- add to file search path
+-helppath <path> -- add to help search path
+-open <file>     -- open file(s) on startup
+-lib <file>      -- load object library(s)
+-font <n>        -- specify default font size in points
 -verbose         -- extra printout on startup and when searching for files
--d            -- specify debug level
+-version         -- don't run Pd; just print out which version it is
+-d <n>           -- specify debug level
 -noloadbang      -- suppress all loadbangs
 -nogui           -- suppress starting the GUI
 -guicmd "cmd..." -- substitute another GUI program (e.g., rsh)
 -send "msg..."   -- send a message at startup (after patches are loaded)
 -rt or -realtime -- use real-time priority (needs root privilege)
 
--frags        -- specify number of audio fragments (defeats audiobuf)
--fragsize     -- specify log of fragment size ('blocksize' is better...)
--blocksize    -- specify audio I/O block size in sample frames
--stream          -- use stream mode audio (e.g., for es1370 audio cards)
--alsa            -- use ALSA audio drivers
--alsadev      -- ALSA device # (counting from 1) or name: default hw:0,0
+
    -(MS Windows specific audio:) --resync -- resynchronize audio (default if more than 2 channels) --noresync -- never resynchronize audio I/O (default for stereo) --asio -- use ASIO audio driver (and not the 'MMIO' default) +

    Here are some details on some of the audio, MIDI, and scheduler options (but +see also the next section on file management.) -MIDI configuration flags: --midiindev ... -- midi in device list; e.g., "1,3" for first and third --midioutdev ... -- midi out device list, same format --nomidiin -- suppress MIDI input --nomidiout -- suppress MIDI output --nomidi -- suppress MIDI input and output +

    multiple devices.

    -general flags: --path -- add to file search path --open -- open file(s) on startup --lib -- load object library(s) --font -- specify default font size in points --verbose -- extra printout on startup and when searching for files --d -- specify debug level --noloadbang -- suppress all loadbangs --nogui -- suppress starting the GUI --guicmd "cmd..." -- substitute another GUI program (e.g., rsh) --send "msg..." -- send a message at startup (after patches are loaded) --rt or -realtime -- use real-time priority (needs root privilege) - - +

    You can specify multiple MIDI input and output devices. For example, +"pd -midiindev 3 -midioutdev 4,2" asks for the third MIDI input device and the +fourth and second MIDI output device. -Here are some details on some of the audio and MIDI options (but see also the -next section on file management.) +

    Audio device selection is similar, except that you can also specify +channels by device: "-audioindev 1,3 -inchannels 2,8" will try to open device 1 +(2 channels) and device 3 (8 channels.) -

    sample rate
    +

    sample rate.

    -The sample rate controls Pd's logical sample rate which need not be that of +

    The sample rate controls Pd's logical sample rate which need not be that of the audio input and output devices. If Pd's sample rate is wrong, time will flow at the wrong rate and synthetic sounds will be transposed. If the output and input devices are running at different rates, Pd will constantly drop frames to re-sync them, which will sound bad. You can disable input or output if this is a problem. -

    audio buffer size
    +

    audio buffer size, block size, and sleep grain.

    -You can specify an audio buffer size in milliseconds, typically between 10 and +

    You can specify an audio buffer size in milliseconds, typically between 10 and 300, depending on how responsive your OS and drivers are. If this is set too low there will be audio I/O errors ("data late"). The higher the value is, on the other hand, the more throughput delay you will hear from the audio and/or control inputs (MIDI, GUI) and the audio coming out. -

    In Linux and Windows, you can also specify the audio block size in sample -frames (but in Windows, this is only effective when using ASIO). +

    You can also specify the audio block size in sample +frames. This is 64 by default (except for MMIO for which it's 256), and may +be 64, 128, or 256. -

    MIDI devices
    -

    You can specify multiple MIDI input and output devices. For example, -"pd -midiindev 3 -midioutdev 4,2" asks for the third MIDI input device and the -fourth and second MIDI output device. The "channel message" midi objects in Pd +

    The "sleepgrain" controls how long (in milliseconds) Pd sleeps between +periods of computation. This is normally the audio buffer divided by 4, but +no less than 0.1 and no more than 5. On most OSes, ingoing and outgoing MIDI +is quantized to this value, so if you care about MIDI timing, reduce this to 1. + +

    MIDI

    + + The "channel message" midi objects in Pd such as notein or pgmout will take channels 1-16 to mean the first open MIDI port, 17-32 the second one, and so on. The midiin, sysexin, midiout objects give you a separate inlet to specify which of the open MIDI port numbers you want. +

    System exclusive MIDI message inupt and output is theoretically supported +in version 0.37 but has not been tested. +

    In Linux, if you ask for "pd -midioutdev 1" for instance, you get /dev/midi0 or /dev/midi00 (or even /dev/midi). "-midioutdev 45" would be /dev/midi44. In NT, device @@ -732,26 +774,45 @@ number 0 is the "MIDI mapper", which is the default MIDI device you selected from the control panel; counting from one, the device numbers are card numbers as listed by "pd -listdev." -

    3.7. dealing with files

    +

    3.7. dealing with files

    -Pd has a search path feature; you specify the path on the command line +

    Pd has a search path feature; you specify the path on the command line using the "-path" option. Paths may contain any number of files. If you specify several files in a single "-path" option they're separated by colons -in unix or semicolons in NT. When Pd searches for an abstraction or an +in unix or semicolons in NT. + +

    You can see and edit the path while Pd is running using the "path..." +item in the "File" menu. The path must be correctly set before you load +a patch or it may fail to find abstractions, etc., that are needed to +construct the patch. + +

    When Pd searches for an abstraction or an "extern" it uses the path to try to find the necessary file. The "read" messages to qlists and arrays (aka tables) work the same way. NO SPACES MAY APPEAR ANYWHERE IN THE SEARCH PATH, e.g., "c:\my nonsense\goobers" won't work. +

    Path entries may be relative to the patch directory; for instance, +if your path has an item, "../sound", and your patch is in "my stuff/all mine", +then Pd will look in "my stuff/sound". Spaces should be OK in the path to +the patch, but not in the path entry (../sound) itself. This is useful if +you have a patch and supporting files (even a supporting snapshot of pd) +that you want to distribute or carry around together. + +

    Regardless of path, Pd should look first in the directory containing +the patch before searching down the path. (However, sometimes, for +reasons I can't explain yet, you have to put the entry "." in the +search path for this to happen, as least within linux!) +

    Filenames in Pd are always separated by (unix-style) forward slashes, even if you're on Windows (which uses backslashes). This is so that patches can be ported more easily between operating systems. On the other hand, if you specify a filename on the command line (as in "pd -path c:\pdlib") the file separator should agree with the operating system.
    -

    If a filename in a patch has any "/" characters in it, the "path" is not -used; thus, "../sounds/sample1.wav" causes Pd only to look relative to the -directory containing the patch. (You may also invoke externs that way.) +

    If a filename specified in a patch has any "/" characters in it, the "path" +is not used; thus, "../sounds/sample1.wav" causes Pd only to look relative to +the directory containing the patch. (You may also invoke externs that way.)

    As of version 0.35, there may be spaces in the path to Pd itself; also, the "openpanel" and "savepanel" objects can handle spaces. But still not diff --git a/pd/doc/1.manual/x4.htm b/pd/doc/1.manual/x4.htm index 5fe5d25d..faaf2f48 100644 --- a/pd/doc/1.manual/x4.htm +++ b/pd/doc/1.manual/x4.htm @@ -1,20 +1,23 @@ + + - -Pd Documentation - - - -

    - -
    -Pd Documentation chapter 4: writing Pd objects in C -
    -
    -
    back to table of contents
    -

    + + Pd Documentation 4 + + + + + + + +

    Pd Documentation chapter 4: writing Pd objects in C

    +

    + back to table of contents +

    +

    -You can write your own objects that you and others can use in their Pd +

    You can write your own objects that you and others can use in their Pd applications. You can write them in C or (if you're smart and brave) in C++ or FORTRAN. @@ -27,7 +30,7 @@ first in the directory containing the patch, then in directories in its "path." Pd will then add whatever object is defined there to its "class list," which is the set of all Pd classes you can use. If all this works, Pd then attempts again to create the object you asked for, this time perhaps -sucessfully. There is no difference between an object defined this way and an +successfully. There is no difference between an object defined this way and an object built into Pd.

    Once you load a new object into Pd, it's there for the duration of your Pd @@ -54,6 +57,5 @@ or bad DLL." Simply recompile Pd under 5.x and the problem goes away. Externs compiled under 5.x and 6.x are binary compatible; it's just the compilation that's sensitive. - diff --git a/pd/doc/1.manual/x5.htm b/pd/doc/1.manual/x5.htm index 0b18cf1a..ac7b6e5a 100644 --- a/pd/doc/1.manual/x5.htm +++ b/pd/doc/1.manual/x5.htm @@ -1,26 +1,87 @@ + + - -Pd Documentation - - - -

    - -
    -Pd Documentation chapter 5. current status -
    -

    -This section tracks changes in Pd's current implementation. -
    -

    back to table of contents
    + + Pd Documentation 5 + + + + + + +

    Pd Documentation chapter 5. current status

    + +

    + back to table of contents +

    +

    + +

    This section tracks changes in Pd's current implementation.

    + +

    5.1. release notes

    + +

    ------------------ 0.37 -------------------------- + +

    Pd is finally fixed so that it can open and close audio and MIDI devices +on-the-fly (previously it opened them once at startup and hogged them until +Pd quit). Starting DSP causes audio devices to be opened, and +stopping it closes them. +There are dialog panels in the "Media" menu (which used to be called +"Audio") for choosing audio and MIDI settings. The "path" also can be changed +on the fly via a dialog in the "File" menu. + +

    A "vline" object acts like "line" but to sub-sample accuracy. See +the audio example, C04.control.to.signal.pd (and/or chapter 3 of + Theory and Techniques of Electronic Music ). + +

    The block~/switch~ object now takes a "set" message to dynamically change +block size, etc. + +

    The makefilename object takes a "set" message to set the "pattern". You +can use this to kludge multiple substitutions (as shown in the help file). + +

    The writesf~ object got an update and a better help window. It now should +be able to write 32bit floating-point WAV soundfiles. The file's sample rate +is now set "correctly". + +

    Various improvements were made in audio I/O to improve stability and +reduce latency. + +

    Jack support should work for Mac OSX (it appears as a separate API). +Linux is offering experimental portaudio V19 support (but Mac and Window/ASIO +are still based on PA V18.) + +

    The fiddle~ object (in extra) has an "npoints" method to set the analysis +window size dynamically. + +

    (windows) Pd is now distributed as a self-extracting archive. + +

    (windows) url files in the help directories are opened correctly. + +

    (Mac) the arrow keys should now be fixed. + +

    (linux) The "configure" script should be better at finding TK in various +distributions (debian users previously had to use a special configure script.) + +

    (developers) Pd now exits cleanly from its main loop instead of bailing +out. A mutex protects Pd's data so it can be accessed from other threads. +(Thomas Grill's improvements.) + +

    (developers) The "savefunction" and "dialog" widget behaviors +were replaced by a better mechanism (class_setsavefn() and +class_setpropertiesfn()). THey're declared in m_pd.h so you don't have to +include the (unstable) g_canvas.h to get them. + +

    (developers) Better flag handling in the IEM GUIs (g_toggle.c, etc) should +compile with fewer warnings and be more portable. -

    5.1. release notes

    ------------------ 0.37-test 1 --------------------------

    The MacOSX version now prioritizes itself effectively (thanks to gert@test.at (v93r)) via Adam Lindsay). Adam has made a proper MacOSX -"package" for Pd; see +"package" for Pd; see http://homepage.mac.com/atl/sw.

    A bug was fixed in readsf~/writesf~ (things were coming out in the wrong @@ -50,8 +111,6 @@ See the way "extras" is organized. as an abstraction and reloads them. This unfortunately has the side effect of making all the containing windows visible, but it's better than nothing. - -

    ------------------ 0.36-1 -------------------------------

    "print" now queries you for a file to save the postscript to. @@ -106,7 +165,7 @@ be fixed.

    An experimental new feature called graph-on-parent allows subpatches and abstractions to show GUI features; so, for instance, you can make an oscillator with a number box to -control the frewuency. This is described in section 2.7.2 of the HTML +control the frequency. This is described in section 2.7.2 of the HTML documentation and an example is shown in 7.stuff/synth1/.

    Spaces are allowed in pathnames to Pd and to patches; however, the "path" @@ -128,7 +187,7 @@ all conformed to the next-oldest one, and so on. You can alter the contents of a "struct" and all the associated data will be modified to fit the new structure definition. Data are persistent, i.e., saved with the containing patch. You can copy and paste data between patches. If you save data to a file -explicityly, you can read it into another patch and the data are conformed +explicitly, you can read it into another patch and the data are conformed automatically to the new data structures.

    A new version of Thomas Musil's GUI objects was merged in. @@ -154,7 +213,7 @@ up the HTML documentation. This doesn't work in Windows or Mac land yet.

    In Linux, the "-32bit" flag was added, which you must now use if running Guenter's OSS RME Hammerfall driver. (This was necessary because -OSS went and used the same "bit" for a different purpose, so taht Pd tried +OSS went and used the same "bit" for a different purpose, so that Pd tried to open some other cards in 32bit mode inappropriately.)

    In Linux, MIDI is now opened "-NODELAY" ... this makes the OSS Creative @@ -178,13 +237,13 @@ MMIO. If "resync" is on, whenever the audio input and output seem out of whack the audio driver resynchronizes all input and output devices; otherwise the situation is simply ignored. "Noresync" is probably best for consumer stereo cards (and is the default if you're running only 2 channels in -and out). If you're runnimg more than 2 channels in either direction, the +and out). If you're running more than 2 channels in either direction, the default is "resync".

    In soundfiler's read method, if you specify "-maxsize", that implies "-resize" (as it ought to.) -

    You can use $1-stlye names for arays and tables. +

    You can use $1-style names for arrays and tables.

    Pd will now refuse to make duplicate connections between objects. @@ -251,8 +310,8 @@ the Pd release so Thomas won't have to publish patches to Pd anymore. I didn't take the graphical inlets and outlets for reasons explained elsewhere, but Thomas might decide to continue supplying them on a patch basis. -

    Many new examples were added to the "2.control" amd expecially -"3.audio" example patches. A list of differences batween Max/MSP and Pd +

    Many new examples were added to the "2.control" and especially +"3.audio" example patches. A list of differences between Max/MSP and Pd now appears at the end of this section.

    Finally, I fixed Pd to notice window iconification and suspend graphical @@ -265,13 +324,13 @@ updates for iconified windows.

    I incorporated Krzysztof Czaja's menuclose bug fix in g_canvas.c. -

    (lunix) the configure script is more rational. +

    (Linux) the configure script is more rational.

    the qlist and pack objects were fixed to handle reentrancy correctly.

    Pd now complains about running out of memory (before it dies.) I intend to provide advance warning and automatically back out of loading patches that -woudl run out of memory, but that's not in place yet. +would run out of memory, but that's not in place yet.

    Typing into a message box sometimes left you with lines from the output pointing to the wrong location. Fixed. @@ -297,19 +356,19 @@ port, 17-32 the second one, and so on. The midiin, sysexin, midiout objects give you a separate inlet to specify which of the open MIDI port numbers you want. -

    (linux only) By default, Pd now reads and write audio in "block mode." +

    (Linux only) By default, Pd now reads and write audio in "block mode." Previously you have to specify "-frags" and/or "-fragsize" to get this. As of this version you have to specify "-streammode" to get the opposite, streaming mode. This mode seems only to work with a small number of sound cards, notably Ensoniq ens1370 and ens1371. -

    (linux only) Also, "-fragsize" is replaced with a more convenient +

    (Linux only) Also, "-fragsize" is replaced with a more convenient "-blocksize" which you specify in sample frames. It defaults to 64 which is Pd's audio computation block size but may be larger or smaller. Typically you would specify "-audiobuf" and "-blocksize" and Pd will compute "-frags" for you; but you can also specify "-frags" explicitly. -

    (linux only) OSS and ALSA audio support are improved. You can now talk to +

    (Linux only) OSS and ALSA audio support are improved. You can now talk to RME9652 using Guenter's OSS driver; this is different from the "-RME" support which uses Winfried's older driver. Other multichannel OSS drivers might now work as well. Pd also seems to work with ALSA 0.9 Beta 4; I've tested this @@ -334,8 +393,8 @@ question of how a reduced-accuracy version should be named. window. The phase vocoder example doesn't use framp~ and I had forgotten what it did until Guenter dug it back up. -

    (linux only) I finally got around to incorporating Guenter's autoconf -stuff, and learned about rpms. Major new linux releases will probably be +

    (Linux only) I finally got around to incorporating Guenter's autoconf +stuff, and learned about RPM. Major new Linux releases will probably be in .tar.gz and .rpm formats; "test" releases will probably just be in .tar.gz. I also fixed it so that the installation prefix is overridden if you invoke pd by its full pathname, so that you can still use compilations with @@ -345,7 +404,7 @@ installation prefixes before you actually install them. by Ross Bencina and Phil Burk. I couldn't discover any way this would ever outperform the old "multimedia" API Pd uses. So the release contains the sources, but you have to recompile Pd to use directX. Use "makefile.nt.portaudio". Only -1 or 2 channels of audio are supported. THe interesting thing is that the same +1 or 2 channels of audio are supported. The interesting thing is that the same code will run on Macintosh. There are a couple of other obstacles to a MacOS port of Pd though; it's hard to predict when this will be feasible. @@ -391,7 +450,7 @@ if Pd is run "-verbose".

    ------------------ 0.32 PATCH 2, 3, 4 ------------------- -

    Hassled more with font size differnces between NT and Linux, and updated +

    Hassled more with font size differences between NT and Linux, and updated many help files. Minor bug fixes here and there.

    the table object now takes a second argument to set size in points. @@ -440,7 +499,7 @@ MIDI I/O. Otherwise, MIDI I/O jitter is limited by the audio buffer size.

    -noloadbang: cancels loadbangs. -

    -nogui: supress starting the GUI. You can then still talk to Pd using, +

    -nogui: suppress starting the GUI. You can then still talk to Pd using, perhaps among other possibilities, the new network connection programs now included in the release. @@ -469,7 +528,7 @@ the soundfile name on the command line.

    in general:

    In Linux the treatment of MIDI input is now much more efficient. Also, -bugs were fixed in notin and (for SGI) bendin. +bugs were fixed in notein and (for SGI) bendin.

    You can "select all" from the Edit menu. @@ -763,7 +822,7 @@ A "Font bomb" feature is provided for resizing fonts and stretching and contracting patches to fit.

    -Pds now bind themselves to the symbol pd- IN Linux, if Pd is called as root it tries to promote its run-time @@ -974,7 +1033,7 @@ notable new objects:

    - an experimental facility for array of floats is included. You can make a new array (from the "put" menu) which will be given a name such as "array1". You -can then send it "read ", "write ", "resize ", and "print" +can then send it "read <file>", "write <file>", "resize <N>", and "print" messages. File reading and writing is in ascii. "resize" changes the size of the array, and "print" prints its vital signs. You can then use "tabread4~" to do a 4-point interpolating table lookup, and tabwrite~ to write audio @@ -1191,7 +1250,7 @@ The following max-like objects are included: send, receive.

    ----------------------------------------- -

    5.2. known bugs

    +

    5.2. known bugs

    In the list below, starred items are still things needing attention... @@ -1239,7 +1298,7 @@ uses of block~ or switch~ objects that change block size frmo the default of read/write delay lines or use send~/receive~, or throw~/catch~, between windows with different block sizes. -

    5.3. differences from Max/MSP

    +

    5.3. differences from Max/MSP

    It wasn't anyone's intention to make Pd a Max/MSP clone, but on the other hand, if there's no reason for a feature to appear differently in @@ -1259,7 +1318,7 @@ kind of personalized compatibility library.

    There are, however, differences in semantics you'll want to know about; a partial list follows. -

    abstraction arguments. +

    abstraction arguments. In Pd you can edit instantiations of abstractions and save the result back to the file of the abstraction. This isn't possible in Max, because the instantiations are different from the abstraction itself in that "#1", etc., -- cgit v1.2.1