diff options
Diffstat (limited to 'pd/doc/1.manual')
37 files changed, 3651 insertions, 0 deletions
diff --git a/pd/doc/1.manual/1.introduction.txt b/pd/doc/1.manual/1.introduction.txt new file mode 100644 index 00000000..c8fa88a8 --- /dev/null +++ b/pd/doc/1.manual/1.introduction.txt @@ -0,0 +1,19 @@ +PD_VERSION + +A real-time graphical programming environment for live interactive +computer music, Pd works on SGI machines, Microsoft Windows, +Linux, and Max OSX. + +Pd is copyrighted, but is free for you to use for any reasonable purpose. +See the file: + PD_BASEDIR/LICENSE.txt + +HTML documentation for Pd lives in: + file:PD_BASEDIR/doc/1.manual/index.htm +or: + http://www.crca.ucsd.edu/~msp/Pd_documentation/index.htm + +The Pd mailing list archive lives in: + http://iem.kug.ac.at/mailinglists/pd-list/ + +Many more useful links are listed in the HTML documentation, section 1.2. diff --git a/pd/doc/1.manual/fig1.1.jpg b/pd/doc/1.manual/fig1.1.jpg Binary files differnew file mode 100644 index 00000000..bfc76f64 --- /dev/null +++ b/pd/doc/1.manual/fig1.1.jpg diff --git a/pd/doc/1.manual/fig1.2.jpg b/pd/doc/1.manual/fig1.2.jpg Binary files differnew file mode 100644 index 00000000..c33c755c --- /dev/null +++ b/pd/doc/1.manual/fig1.2.jpg diff --git a/pd/doc/1.manual/fig1.3.jpg b/pd/doc/1.manual/fig1.3.jpg Binary files differnew file mode 100644 index 00000000..caf29b2d --- /dev/null +++ b/pd/doc/1.manual/fig1.3.jpg diff --git a/pd/doc/1.manual/fig1.4.jpg b/pd/doc/1.manual/fig1.4.jpg Binary files differnew file mode 100644 index 00000000..28a29dc6 --- /dev/null +++ b/pd/doc/1.manual/fig1.4.jpg diff --git a/pd/doc/1.manual/fig1.5.jpg b/pd/doc/1.manual/fig1.5.jpg Binary files differnew file mode 100644 index 00000000..4b01c59f --- /dev/null +++ b/pd/doc/1.manual/fig1.5.jpg diff --git a/pd/doc/1.manual/fig3.1.jpg b/pd/doc/1.manual/fig3.1.jpg Binary files differnew file mode 100644 index 00000000..f8348970 --- /dev/null +++ b/pd/doc/1.manual/fig3.1.jpg diff --git a/pd/doc/1.manual/fig3.10.jpg b/pd/doc/1.manual/fig3.10.jpg Binary files differnew file mode 100644 index 00000000..4625ce0c --- /dev/null +++ b/pd/doc/1.manual/fig3.10.jpg diff --git a/pd/doc/1.manual/fig3.2.jpg b/pd/doc/1.manual/fig3.2.jpg Binary files differnew file mode 100644 index 00000000..994d41c7 --- /dev/null +++ b/pd/doc/1.manual/fig3.2.jpg diff --git a/pd/doc/1.manual/fig3.3.jpg b/pd/doc/1.manual/fig3.3.jpg Binary files differnew file mode 100644 index 00000000..91cac54a --- /dev/null +++ b/pd/doc/1.manual/fig3.3.jpg diff --git a/pd/doc/1.manual/fig3.4.jpg b/pd/doc/1.manual/fig3.4.jpg Binary files differnew file mode 100644 index 00000000..e2f2fe53 --- /dev/null +++ b/pd/doc/1.manual/fig3.4.jpg diff --git a/pd/doc/1.manual/fig3.5.jpg b/pd/doc/1.manual/fig3.5.jpg Binary files differnew file mode 100644 index 00000000..9a79a2b3 --- /dev/null +++ b/pd/doc/1.manual/fig3.5.jpg diff --git a/pd/doc/1.manual/fig3.6.jpg b/pd/doc/1.manual/fig3.6.jpg Binary files differnew file mode 100644 index 00000000..fcbcf3da --- /dev/null +++ b/pd/doc/1.manual/fig3.6.jpg diff --git a/pd/doc/1.manual/fig3.7.jpg b/pd/doc/1.manual/fig3.7.jpg Binary files differnew file mode 100644 index 00000000..84dcd7f7 --- /dev/null +++ b/pd/doc/1.manual/fig3.7.jpg diff --git a/pd/doc/1.manual/fig3.8.jpg b/pd/doc/1.manual/fig3.8.jpg Binary files differnew file mode 100644 index 00000000..ab03a207 --- /dev/null +++ b/pd/doc/1.manual/fig3.8.jpg diff --git a/pd/doc/1.manual/fig3.9.jpg b/pd/doc/1.manual/fig3.9.jpg Binary files differnew file mode 100644 index 00000000..6e9655c7 --- /dev/null +++ b/pd/doc/1.manual/fig3.9.jpg diff --git a/pd/doc/1.manual/fig7.1.jpg b/pd/doc/1.manual/fig7.1.jpg Binary files differnew file mode 100644 index 00000000..b677f6bd --- /dev/null +++ b/pd/doc/1.manual/fig7.1.jpg diff --git a/pd/doc/1.manual/fig7.2.jpg b/pd/doc/1.manual/fig7.2.jpg Binary files differnew file mode 100644 index 00000000..54690d0e --- /dev/null +++ b/pd/doc/1.manual/fig7.2.jpg diff --git a/pd/doc/1.manual/fig7.3.jpg b/pd/doc/1.manual/fig7.3.jpg Binary files differnew file mode 100644 index 00000000..a3b70ed3 --- /dev/null +++ b/pd/doc/1.manual/fig7.3.jpg diff --git a/pd/doc/1.manual/fig7.4.jpg b/pd/doc/1.manual/fig7.4.jpg Binary files differnew file mode 100644 index 00000000..88ba5b40 --- /dev/null +++ b/pd/doc/1.manual/fig7.4.jpg diff --git a/pd/doc/1.manual/fig7.5.jpg b/pd/doc/1.manual/fig7.5.jpg Binary files differnew file mode 100644 index 00000000..f9de4b3b --- /dev/null +++ b/pd/doc/1.manual/fig7.5.jpg diff --git a/pd/doc/1.manual/fig7.6.jpg b/pd/doc/1.manual/fig7.6.jpg Binary files differnew file mode 100644 index 00000000..5f24af7a --- /dev/null +++ b/pd/doc/1.manual/fig7.6.jpg diff --git a/pd/doc/1.manual/fig8.1.jpg b/pd/doc/1.manual/fig8.1.jpg Binary files differnew file mode 100644 index 00000000..57e59313 --- /dev/null +++ b/pd/doc/1.manual/fig8.1.jpg diff --git a/pd/doc/1.manual/fig8.2.jpg b/pd/doc/1.manual/fig8.2.jpg Binary files differnew file mode 100644 index 00000000..1dd48cd9 --- /dev/null +++ b/pd/doc/1.manual/fig8.2.jpg diff --git a/pd/doc/1.manual/fig8.3.jpg b/pd/doc/1.manual/fig8.3.jpg Binary files differnew file mode 100644 index 00000000..165c1c88 --- /dev/null +++ b/pd/doc/1.manual/fig8.3.jpg diff --git a/pd/doc/1.manual/fig8.4.jpg b/pd/doc/1.manual/fig8.4.jpg Binary files differnew file mode 100644 index 00000000..afc89a73 --- /dev/null +++ b/pd/doc/1.manual/fig8.4.jpg diff --git a/pd/doc/1.manual/fig8.5.jpg b/pd/doc/1.manual/fig8.5.jpg Binary files differnew file mode 100644 index 00000000..6fa3d0d1 --- /dev/null +++ b/pd/doc/1.manual/fig8.5.jpg diff --git a/pd/doc/1.manual/fig8.6.jpg b/pd/doc/1.manual/fig8.6.jpg Binary files differnew file mode 100644 index 00000000..2823e032 --- /dev/null +++ b/pd/doc/1.manual/fig8.6.jpg diff --git a/pd/doc/1.manual/fig9.1.jpg b/pd/doc/1.manual/fig9.1.jpg Binary files differnew file mode 100644 index 00000000..bab4b689 --- /dev/null +++ b/pd/doc/1.manual/fig9.1.jpg diff --git a/pd/doc/1.manual/fig9.2.jpg b/pd/doc/1.manual/fig9.2.jpg Binary files differnew file mode 100644 index 00000000..88ef528c --- /dev/null +++ b/pd/doc/1.manual/fig9.2.jpg diff --git a/pd/doc/1.manual/fig9.3.jpg b/pd/doc/1.manual/fig9.3.jpg Binary files differnew file mode 100644 index 00000000..ecb66004 --- /dev/null +++ b/pd/doc/1.manual/fig9.3.jpg diff --git a/pd/doc/1.manual/index.htm b/pd/doc/1.manual/index.htm new file mode 100644 index 00000000..ddaa292d --- /dev/null +++ b/pd/doc/1.manual/index.htm @@ -0,0 +1,161 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> +<FONT size=+5> +<B>Pd Documentation</B><BR> +</FONT></CENTER> +<P> +This is the HTML documentation for Pd, a patchable environment for audio +analysis, synthesis, and processing, +with a rich set of multimedia capabilities. The latest version of this page +can be found at: + <a href="http://www.crca.ucsd.edu/~msp/software.html" name=s1> + http://www.crca.ucsd.edu/~msp/software.html</A> . +<OL> +<LI> <a href="x1.htm" name=s1>introduction </A> +<OL> + <LI> <a href="x1.htm#s1">guide to the documentation </A> + <LI> <a href="x1.htm#s2">other resources </A> +</OL> + +<LI> <A href="x2.htm" name=s2>theory of operation </A> +<OL> + <LI> <A href="x2.htm#s1"> overview </A> + <OL> + <LI> <A href="x2.htm#s1.1"> main window, canvases, and printout </A> + <LI> <A href="x2.htm#s1.2"> object boxes </A> + <LI> <A href="x2.htm#s1.3"> message, number, and symbol boxes </A> + <LI> <A href="x2.htm#s1.4"> patches and files </A> + </OL> + <LI> <A href="x2.htm#s2"> how to edit patches </A> + <OL> + <LI> <A href="x2.htm#s2.1"> edit and run mode </A> + <LI> <A href="x2.htm#s2.2"> creating boxes </A> + <LI> <A href="x2.htm#s2.3"> the selection </A> + <LI> <A href="x2.htm#s2.4"> deleting, cutting, and pasting </A> + <LI> <A href="x2.htm#s2.5"> changing the text </A> + <LI> <A href="x2.htm#s2.6"> connecting and disconnecting boxes </A> + <LI> <A href="x2.htm#s2.7"> properties and help </A> + </OL> + <LI> <A href="x2.htm#s3"> messages </A> + <OL> + <LI> <A href="x2.htm#s3.1"> anatomy of a message </A> + <LI> <A href="x2.htm#s3.2"> depth first message passing </A> + <LI> <A href="x2.htm#s3.3"> + hot and cold inlets and right to left outlet order </A> + <LI> <A href="x2.htm#s3.3"> message boxes </A> + </OL> + <LI> <A href="x2.htm#s4"> audio signals </A> + <OL> + <LI> <A href="x2.htm#s4.1"> sample rate and format </A> + <LI> <A href="x2.htm#s4.2"> tilde objects and audio connections </A> + <LI> <A href="x2.htm#s4.3"> converting to and from messages </A> + <LI> <A href="x2.htm#s4.4"> switching and blocking </A> + <LI> <A href="x2.htm#s4.5"> nonlocal signal connections </A> + </OL> + <LI> <A href="x2.htm#s5"> scheduling </A> + <OL> + <LI> <A href="x2.htm#s5.1"> audio and messages </A> + <LI> <A href="x2.htm#s5.2"> computation load </A> + <LI> <A href="x2.htm#s5.3"> determinism </A> + </OL> + <LI> <A href="x2.htm#s6"> semantics </A> + <OL> + <LI> <A href="x2.htm#s6.1"> creation of objects </A> + <LI> <A href="x2.htm#s6.2"> persistence of data </A> + <LI> <A href="x2.htm#s6.3"> message passing </A> + <LI> <A href="x2.htm#s6.4"> inlets and lists </A> + <LI> <A href="x2.htm#s6.5"> dollar signs </A> + </OL> + <LI> <A href="x2.htm#s7"> subpatches </A> + <OL> + <LI> <A href="x2.htm#s7.1"> abstractions </A> + <LI> <A href="x2.htm#s7.2"> graph-on-parent subpatches </A> + </OL> + <LI> <A href="x2.htm#s8"> numeric arrays </A> + <LI> <A href="x2.htm#s9"> data structures </A> + <OL> + <LI> <A href="x2.htm#s9.1"> abstractions </A> + <LI> <A href="x2.htm#s9.2"> graph-on-parent subpatches </A> + <LI> <A href="x2.htm#s9.3"> limitations </A> + </OL> + +</OL> + +<LI> <a href="x3.htm" name=s3> getting Pd to run </A> +<OL> + <LI> <a href="x3.htm#s1.1">IRIX (SGI) </A> + <LI> <a href="x3.htm#s1.2">Microsoft Windows </A> + <LI> <a href="x3.htm#s1.3">Linux </A> + <LI> <a href="x3.htm#s1.4">Mac OSX </A> + <LI> <a href="x3.htm#s3"> graphics rendering using GEM </A> + <LI> <a href="x3.htm#s4"> The Pd command line </A> + <LI> <a href="x3.htm#s5"> dealing with files </A> +</OL> +<LI> <a href="x4.htm" name=s4> writing Pd objects in C </A> + +<LI> <a href="x5.htm" name=s5> current status </A> +<OL> + <LI> <a href="x5.htm#s1"> release notes </A> + <LI> <a href="x5.htm#s2"> known bugs </A> + <LI> <a href="x5.htm#s3"> differences from Max/MSP </A> +</OL> + +</OL> + +<! + intro: what Pd is + guide to the documentation + other resources + + Theory of operation + main window and canvases + messages + signals + loading, editing, and saving patches + subpatches + one-off and abstractions + blocking for signals + data + + Making Pd work + how to get and install Pd + IRIX + NT + Linux + audio + testing it + the scheduler advance + IRIX + NT + Linux + GEM + getting it + running it + running Pd patches + command line options + opening & saving files + editing + file stuff + the path + abstractions + externs + the help feature + Writing Pd objects in C + release notes + features + bugs + + + + +> + +</BODY> +</HTML> diff --git a/pd/doc/1.manual/x1.htm b/pd/doc/1.manual/x1.htm new file mode 100644 index 00000000..946949e9 --- /dev/null +++ b/pd/doc/1.manual/x1.htm @@ -0,0 +1,112 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation 1</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> <B> +Pd Documentation chapter 1: introduction +</B> </CENTER> +<BR> +<A href=index.htm#s1> back to table of contents </A> + <BR><BR> +<P> +This is the HTML documentation for the Pd computer program. +Pd is free and can be downloaded from the internet; +go to + <A href="http://www.crca.ucsd.edu/~msp/software.html"> + http://www.crca.ucsd.edu/~msp/software.html</A> +to get it. +<H4> <A name=s1> 1.1. guide to the documentation </A> </H4> + +<P> Pd's documentation consists of: + +<UL> +<LI> this HTML manual +<LI> "reference" patches, one for each kind of object in Pd +<LI> "example" patches showing how to do things +<LI> sample C code +</UL> + +<P> +This manual has five sections: + +<OL> +<LI> this overview +<LI> <A href="x2.htm"> + a theory of operations, explaining how Pd works </A> +<LI> <A href="x3.htm"> + instructions on installing Pd and getting it to run </A> +<LI> <A href="x4.htm"> how to write C extensions to Pd </A> +<LI> <A href="x5.htm"> release notes and known bugs </A> +</OL> + +<P> In order to consult the reference and example patches, you'll first have +to get Pd started as explained in this manual. + +<P> +For a list of all the objects you can use in Pd, see the text file, +"0.INTRO.txt" in the directory, "../5.reference". To get help on any +Pd object you can right click on it; or you can browse the help patches +by choosing "Pure Documentation..." in the Pd help menu and looking in +5.reference. + +<P> +The example patches are also available from the "Pure Documentation..." item +in Pd's +"help" menu. The example patches appear in subdirectories named +"2.control.examples", "3.audio.examples" and "4.fft.examples." Some additional +patches in "7.stuff" might also be helpful. + +<P> +To get started writing your own C extensions, refer to chapter 4 of this manual. + +<H4> <A name=s2> 1.2. other resources </A> </H4> + +<P> +Most of the interesting resources related to Pd show up on the Pd mailing list, +maintained by Iohannes Zmoelnig. To subscribe or browse the archives +visit: + <A href="http://iem.kug.ac.at/mailinglists/pd-list/"> + http://iem.kug.ac.at/mailinglists/pd-list/</A>. + +. This is the +best source of recent information regarding installation problems and bugs. It +is perfectly reasonable to post "newbie" questions on this list; alternatively +you can contact msp@ucsd.edu for help. + +<P> Many extensions to Pd are announced on the mailing list. In particular, +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: <A href=http://iem.kug.ac.at/GEM>http://iem.kug.ac.at/GEM</A> . + +<P> A video processing package, Framestein, is by Juha Vehvilainen. This runs +on Windows only: <A href=http://framestein.org> http://framestein.org </A>. + +<P> +Here are some more Pd links (in the order I found them): <BR> + +<a href="http://www.crca.ucsd.edu/~msp"> Miller Puckette's home page</a><br> +<a href="http://gige.epy.co.at/"> Guenter Geiger's home page</a><br> +<a href="http://www.danks.org/mark"> Mark Dank's home page</a><br> +<a href="http://wonk.epy.co.at">Pd page on Wonk (Klaus)</a><br> +<a href="http://iem.kug.ac.at/~zmoelnig/index.html"> + Johannes M Zmoelnig</a><br> +<a href="http://iem.kug.ac.at/~math/pd/"> Norbert Math's Pd page</a> <br> +<a href="http://iem.kug.ac.at/iemlib/"> Thomas Musil's IEMLIB</a> <br> +<a href="http://www.pure-data.org/"> jfm3's Pure Data FAQ and downloads</a> +(also available in Japanese translation).<br> +<a href="http://iem.kug.ac.at/pdwiki/"> +Nicolas Lhommet's WikiWikiWeb page for Pd</a><br> +<a href="http://iem.kug.ac.at/pdb/"> Norbert's searchable list of all known +Pd objects</a><br> +<a href="http://suita.chopin.edu.pl/~czaja/miXed/externs/xeq.html"> +Krzysztof Czaja's MIDI file support </a><br> +<a href="http://www.davesabine.com/media/puredata.asp?action=pddp"> +David Sabine's Pd Documentation Project: new, highly detailed help windows</a><br> +</BODY> +</HTML> diff --git a/pd/doc/1.manual/x2.htm b/pd/doc/1.manual/x2.htm new file mode 100644 index 00000000..cc382e67 --- /dev/null +++ b/pd/doc/1.manual/x2.htm @@ -0,0 +1,1215 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> <B> +Pd Documentation chapter 2: theory of operation +</B> </CENTER> +<BR> +<A href=index.htm#s2> back to table of contents</A> + <BR><BR> +<P> + +<P> 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, <I> Computer Music </I>. + +<H4> <A name=s1> 2.1 overview </A> </H4> + +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. + +<H4> <A name=s1.1> 2.1.1. the main window, canvases, and printout </A> </H4> + +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: + +<P><CENTER> + <IMG src="fig1.1.jpg"> +</CENTER><P> + +<P> 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 +on input and output. You can turn the peak meters on and off using the +control at bottom left. + +<P> 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.) + +<P> 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 +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 +<a href="x3.htm#s2"> audio and MIDI support </A>. + +<P> 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 +whether you can see them or not. Here is a simple Pd patch: + +<P><CENTER> + <IMG src="fig1.2.jpg"> +</CENTER><P> + +There are four <I> text items </I> 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 +on bottom. + +<P> +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. + +<H4> <A name=s1.2> 2.1.2. object boxes </A> </H4> +<P> Pd patches can have four types of boxes: <I> object, message, GUI, </I> +and <I> comment </I>. + +<P> You make <I> objects </I> by typing text into object boxes. The text is +divided into <I> atoms </I> separated by white space. The first atom specifies +what type of object Pd will make, and the other atoms, called <I> creation +arguments </I>, tell Pd how to initialize the object. If you type for example, + +<P><CENTER> + <IMG src="fig1.3.jpg"> +</CENTER><P> + +the "+" specifies the <I> class </I> 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 <I> +symbols </I> like "+". + +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. + +<P> +Here for example is a simple MIDI synthesizer: + +<P><CENTER> + <IMG src="fig1.4.jpg"> +</CENTER><P> + +This patch mixes <I> control </I> objects (notein, stripnote, and ftom) with +<I> tilde </I> objects osc~, *~, and dac~. The control objects carry out their +function sporadically, as a result of one or more type of <I> event </I>. In +this case, incoming MIDI note messages set off the control computation. The +result of the computation is, when the note happens to be a "note on" (and not +a "note off", to compute the frequency in cycles per second and pass it on to +the oscillator ("osc~"). + +<P> The second half of the patch, the osc~, *~, and dac~ objects, compute audio +samples, in the same way as an analog synthesizer works. The osc~ object is +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. + +<H4> <A name=s1.3> 2.1.3. message and GUI boxes </A> </H4> + +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. <I> Message </I> 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 +box which adds 13 to it. + +<P><CENTER> + <IMG src="fig1.5.jpg"> +</CENTER><P> + +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 <A href="x2.htm#s2.7"> getting help </A> to find out how to look +this up). + +<P> 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. + +<H4> <A name=s1.4> 2.1.4. patches and files </A> </H4> + +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 <I> path </I> 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. + +<H4> <A name=s2> 2.2. editing Pd patches </A> </H4> + +<H4> <A name=s2.1> 2.2.1. edit and run mode </A> </H4> + +<P> 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 +moves boxes or makes and cuts connections; in run mode clicking on boxes sends +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. + +<H4> <A name=s2.2> 2.2.2. creating boxes </A> </H4> + +<P> You can create boxes (objects, messages, GUIs, and comments) using the +"put" menu. Note the handy accelerators. Object and message boxes are empty +at first; drag them where you want them and type in the text. The GUI +objects (which come in several flavors) require no typing; just create and +place them. + +<P> You will often find it more convenient to select a box and "duplicate" it +(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. + +<H4> <A name=s2.3> 2.2.3. the selection </A> </H4> + +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. + +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. + +<H4> <A name=s2.4> 2.2.4. deleting, cutting, and pasting </A> </H4> + +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. + +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. + +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.) + +<H4> <A name=s2.5> 2.2.5. changing the text </A> </H4> + +<P> 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 +everything. Click again and drag to select a portion of the text to retype. + +<P> If there's +more than a small amount of text (in a comment, for example) you might want to +select the text and choose "text editor" from the Edit menu, which opens a text +editing window with a copy of the text in it. Hitting "send" in that window is +exactly equivalent to retyping the text into Pd; you can send it to more than +one box in sequence if you want. + +<P> 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 +selecting text instead of moving the box. + +<P> <I> The updated text only becomes part of the patch when you deselect the +object. </I> Changing the text in an "object" box actually deletes the old +object and creates a new one; the internal state of the old one is lost. + +<H4> <A name=s2.6> 2.2.6. connecting and disconnecting boxes </A> </H4> + +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 +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.) + +<H4> <A name=s2.7> 2.2.7. Properties and help </A> </H4> + +<P> 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. + +<H4> <A name=s2.7> 2.2.8. miscellaneous </A> </H4> + +<P> Control-q "quits" Pd, but asks you to comfirm the quit. To quit without +having to confirm, use command-shift-Q. + +<H4> <A name=s3> 2.3. messages </A> </H4> + +<P> In Pd, objects intercommunicate by sending messages and/or audio signals. +Pd messages are sporadic, like MIDI messages or music N "Note cards." + +<H4> <A name=s3.1> 2.3.1. anatomy of a message </A> </H4> + +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 +point, so that they can represent integers exactly between -8388608 and +8388608. (In Max, there are separate data types for integers and floating +point numbers; Pd uses only float.) + +<P> When a message is passed to something (which is often an inlet of a box +but could be anything that can receive a message), the selector of the message +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: + +<P><CENTER> + <IMG src="fig3.1.jpg"> +</CENTER><P> + +<P> 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" +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 +"list", are usually used to denote an object's main action, whatever it may be, +so that objects can be interconnected with maximum flexibility. + +<P> It is possible to type messages which start with a number, +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". + +<H4> <A name=s3.2> 2.3.2. depth first message passing </A> </H4> + +<P> 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: + +<P><CENTER> + <IMG src="fig3.2.jpg"> +</CENTER><P> + +<P> 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 +all four are. It is indeterminate which of "B" or "C" is done first; this +depends on what order you made the connections in (in Max, it's automatically +sorted right to left). + +<P> Message-passing can give rise to infinite loops of the sort shown here: + +<P><CENTER> + <IMG src="fig3.3.jpg"> +</CENTER><P> + +<P> 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 +left-hand one has been sent "3", and so on. Pd will print an error message +reporting a "stack overflow" if this happens. + +<P> 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 +future (even if the time delay is 0) and is then "finished;" Pd's internal +scheduler will wake the delay back up later. + +<H4> <A name=s3.3> +2.3.3. hot and cold inlets and right to left outlet order </A> </H4> + +<P> 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: + +<P><CENTER> + <IMG src="fig3.4.jpg"> +</CENTER><P> + +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 +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 +the addition (since the left hand inlet is the "hot" one) and will add this +value to whatever was previously sitting in the right hand inlet. + +<P> Problems can arise when a single outlet is connected (either directly or +through arbitrarily long chains of message passing) to different inlets of a +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: + +<P><CENTER> + <IMG src="fig3.5.jpg"> +</CENTER><P> + +<P> 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 +new input (at left) to the previous input (at right). + +<P> The "trigger" object, abbreviated "t", can be used to split out connections +from a single outlet in a determinate order. By convention, all objects in Pd, +when sending messages out more than one outlet, do so from right to left. If +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: + +<P><CENTER> + <IMG src="fig3.6.jpg"> +</CENTER><P> + +<P> "Cold" (non-leftmost) inlets are almost universally used to store single +values (either numbers or symbols.) With the exception of "line" and "line~", +these values are "sticky," i.e., once you set the value it is good until the +next time you set it. (The "line" exception is for sanity's sake.) + +<P> One more question sometimes comes up in execution order, which is +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. + +<H4> <A name=s3.4> 2.3.4. message boxes </A> </H4> + +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. + +<P><CENTER> + <IMG src="fig3.7.jpg"> +</CENTER><P> + +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." + +<P> Multiple messages may be separated by commas as shown: + +<P><CENTER> + <IMG src="fig3.8.jpg"> +</CENTER><P> +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.) + +<P> Semicolons may also separate messages. A message following a semicolon must +specify a symbol giving a destination (in other words, semicolons are like +commas except that they clear the "current destination" +so that the next message specifies a new one). The "current destination" is +at first the message box's own outlet. In the example below, the leading +semicolon immediately redirects messages from the outlet to an object named +"fred" (which is here a receive object), and likewise the next message is sent +to "sue." + + +<P><CENTER> + <IMG src="fig3.9.jpg"> +</CENTER><P> + +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. + +<P> You can put variables in message boxes as shown below: + +<P><CENTER> + <IMG src="fig3.10.jpg"> +</CENTER><P> + +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. + +<H4> <A name=s4> 2.4. audio signals </A> </H4> + +<P> +Using Pd you can build audio patches which can synthesize musical sounds, +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. + +<H4> <A name=s4.1> 2.4.1. sample rate and format </A> </H4> + +<P> +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. + +<P> +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). + +<P> +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. + +<H4> <A name=s4.2> 2.4.2. tilde objects and audio connections </A> </H4> + +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 +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 +linear list is run down in blocks of 64 samples each; at 44100 Hz. this means +the audio network runs every 1.45 milliseconds. + +<P> Inlets or outlets are configured in Pd either for messages or audio; it's +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. + +<P> +The audio network, that is, the tilde objects and their interconnections, +must be acyclic. If there are loops, you will see the error message at "sort +time." When errors are reported at sort time there is no easy way to +find the source of the error. You can build algorithms with feedback using +nonlocal signal connections. + +<P> +Your subpatches can have audio inlets and outlets via the inlet~ and outlet~ +objects. + +<H4> <A name=s4.3> 2.4.3. converting audio to and from messages </A> </H4> + +<P> 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 +to take control or signal inputs. + +<P> The other direction, signal to control, requires that you specify at what +moments you want the signal sampled. This is handled by the snapshot~ object, +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. + +<H4> <A name=s4.4> 2.4.4. switching and blocking </A> </H4> + +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 +switch~/block~ objects. Switch~ and block~ take a block size and an overlap +factor as arguments; so for instance, "block~ 1024 4" specifies 1024 sample +blocks, overlapped by a factor of 4 relative to the parent window. Switch~ +carries a small computational overhead in addition to whatever overhead is +associated with changing the block size. + +<P> Larger block sizes than 64 should result in small increases in run-time +efficiency. Also, the fft~ and related objects operate on blocks so that +setting the block size also sets the number of FFT channels. You may wish +to use block sizes smaller than 64 to gain finer resolutions of message/audio +interaction, or to reduce "block delay" in feedback algorithms. At the +(untested) extreme, setting the block size to one allows you to write your +own recursive filters. + +<P> 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. + +<P> 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. + +<H4> <A name=s4.5> 2.4.5. nonlocal signal connections </A> </H4> + +You may wish to pass signals nonlocally, 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 +accumulated signal and zeros the bus for the next time around. There can be +many throw~ objects associated with a single catch~, but a throw~ can't talk to +more than one catch~. You can reset the destination of a throw~ if you want to. + +<P> Send~ just saves a signal which may then be receive~d any number of times; but +a receive~ can only pick up one send~ at a time (but you can switch between +send~s if you want.) + +<P> Don't try to throw~ and catch~ or send~ and receive~ between windows with +different block sizes. The only re-blocking mechanisms which are well tested +are inlet~ and outlet~. + +<P> When you send a signal to a point that is earlier in the sorted list of tilde +objects, the signal doesn't get there until the next cycle of DSP computation, +one block later; so your signal will be delayed by one block (1.45 msec by +default.) Delread~ and delwrite~ have this same restriction, but here the 1.45 +msec figure gives the minimum attainable delay. For nonrecursive algorithms, a +simple flanger for example, you might wish to ensure that your delread~ is +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~. + +<H4> <A name=s5> 2.5. scheduling </A> </H4> + +Pd uses 64-bit floating point numbers to represent time, providing sample +accuracy and essentially never overflowing. Time appears to the user +in milliseconds. + +<H4> <A name=s5.1> 2.5.1. audio and messages </A> </H4> + +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." + +<P> In the intervals between, delays might time out or external conditions +might arise (incoming MIDI, mouse clicks, or whatnot). These may cause a +cascade of depth-first message passing; each such message cascade is completely +run out before the next message or DSP tick is computed. Messages are never +passed to objects during a DSP tick; the ticks are atomic and parameter changes +sent to different objects in any given message cascade take effect +simultaneously. + +<P> In the middle of a message cascade you may schedule another one at a delay +of zero. This delayed cascade happens after the present cascade has finished, +but at the same logical time. + +<H4> <A name=s5.2> 2.5.2. computation load </A> </H4> + +<P> 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 +able to absorb unpredictable, momentary increases in computation time. This +is specified using the "audiobuffer" or "frags" command line flags (see <a +href="x3.htm" name=s3>getting Pd to run </A>). + +<P> 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 +Pd as a batch program with soundfile input and/or output. The "-nogui" +and "-send" startup flags are provided to aid in doing this. + +<P> Pd's "realtime" computations compete for CPU time with its own GUI, which +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; +but not so for miniaturized windows as of version 0.32. You should really +close them when you aren't using them. + +<H4> <A name=s5.3> 2.5.3. determinism </A> </H4> + +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 +in order to make Pd's operation deterministic. + +<P> If a message cascade is started by an external event, a time tag is given +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 +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.) + +<P> If two message cascades are scheduled for the same logical time, they are +carried out in the order they were scheduled. + +<H4> <A name=s6> 2.6. semantics </A> </H4> + +This section describes how objects in Pd are created, how they store data and +how object and other boxes they pass messages among themselves. + +<H4> <A name=s6.1> 2.6.1. creation of objects </A> </H4> + +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 +message or messages it will send as output. In atom boxes the text changes +at run time to show the state of the box, which is either a number or a symbol. + +<P> In an object box, as in a message box, the text specifies a message; but +here the message is to be passed to Pd itself, once, and the +message's effect is to create the object in question. When you open a file, +all the objects created are created using their text as "creation messages." +If you type a new message into an object box (or change it), the old object is +destroyed and the message is used to create the new one. + +<P> 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 +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. + +<H4> <A name=s6.2> 2.6.2. persistence of data </A> </H4> + +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. +For this reason, if messages received by an object change its action, since the +changes aren't reflected in the object's appearance, they are not saved as part +of the file which specifies the patch and will be forgotten when the patch is +reloaded. In the same way, if you delete and then recreate an object the +original object's state is not retained but is instead reinitialized (possibly +as specified by creation arguments.) + +<P> An exception is made for subpatches whose "state" is the configuration of +the subpatch; as a special case, this configuration is restored when the +patch is read from a file. Also, if you rename the subpatch, for instance +typing "pd jane" instead of "pd spot," the contents of the patch are preserved +and only the text in the object box and the window title of the subpatch are +changed. + +<P> It is probably bad style to specify creation arguments ala "makenote 64 250" +if you are going to override them later; this is confusing to anyone who tries +to understand the patch. + +<H4> <A name=s6.3> 2.6.3. message passing </A> </H4> + +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 +checks the selector against the class of the object. Message boxes all are +of one class and they all take the same incoming messages and dispense them +according to their state, that is, the text typed into the box. The same +holds for atom boxes (number or symbol) except that their state may change +(it consists of the number or symbol showing). + +<P> Object boxes may have many different classes. The class is usually +determined by the selector of the creation message, i.e., the first atom of the +creation message which is usually a symbol. + +<P> 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 +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, +that is, by sending a "float" message to their outlet. They respond to "float" +messages by setting their value and then outputting it. + +<P> Each other class (like "float") in Pd has its own protocol for responding +to messages it is sent, and may take "float" and "bang" messages, or others +in addition or instead of them. + +<H4> <A name=s6.4> 2.6.4. inlets and lists </A> </H4> + +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" +although in Pd there are 4 individual inlet classes. The class of the inlet +determines which messages it will take: symbol, float, or other; and the inlet +forwards the message either to the object proper or to some proxy, usually +one that the object creates for the occasion. + +<P> Unless they arrange otherwise by defining a "list" method, objects respond +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. + +<H4> <A name=s6.5> 2.6.5. dollar signs </A> </H4> + +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 +with values supplied as part of the environment the message is passed in. +In the case of message boxes, the environment consists of the arguments of +the "list" message (possibly extrapolated from "bang," "float," +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." + +<P> Object boxes contain text wwhich 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. + +<P> Constructions such as "$1-x" are expanded by string concatentation. 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. + +<H4> <A name=s7> 2.7. subpatches </A> </H4> + +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: + +<P><CENTER> <IMG src="fig7.1.jpg"> </CENTER><P> + +the box in the middle, if clicked on, opens the sub-patch shown here: + +<P><CENTER> <IMG src="fig7.2.jpg"> </CENTER><P> + +<P> 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 +individually. + +<P> The objects, "inlet,", "inlet~," "outlet," and "outlet~,", when put in a +subpatch, create inlets and outlets for the object box containing the subpatch. +This works equally for one-off subpatches and abstractions. The inlet~ and +outlet~ versions create inlets and outlets for audio signals. You can't mix +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. + +<H4> <A name=s7.1> 2.7.1. abstractions </A> </H4> + +<P> To make an abstraction, save a patch with a name such as "abstraction1.pd" +and then invoke it as "abstraction1" in an object box: + +<P><CENTER> <IMG src="fig7.3.jpg"> </CENTER><P> + +<P> 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): + +<P><CENTER> <IMG src="fig7.4.jpg"> </CENTER><P> + +You may create many instances of "abstraction1" or invoke it from several +different patches; and changing the contents of "abstraction1" will affect all +invocations of it as they are created. An analogy from the "c" programming +language is that one-off subpatches are like bracketed blocks of code and +abstractions are like subroutines. + +<P> Abstractions are instantiated by typing the name of a patch (minus the ".pd" +extension) into an object box. You may also type arguments; for instance if +you have a file "my-abstraction.pd" you may type "my-abstraction 5" to set the +variable $1 to 5. This is defined only for object boxes (not for messages) in +the abstraction. (For message boxes, "$1", etc, have a different meaning as +described above.) If you want to send a message with a $1 in the sense of a +creation argument of an abstraction, you must generate it with an object box +such as "float $1", "symbol $1", or perhaps "pack $1 $2", which may then be +sent to a message box. + +<P> The corresponding feature in Max (both Opcode and Ircam) was the "#1" +construct. In a Max abstraction, "#1", etc., are replaced by the creation +argument. This has the disadvantage that you can't edit the abstraction as +instantiated in the patch since the "#" variables are substituted. In Pd the +"$" variables in object boxes are spelled literally as "$" variables so that +it's meaningful to edit them from within their calling patch. On the Pd side, +however, there is the disadvantage that it's confusing to have "$" expanded at +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. + +<H4> <A name=s7.2> 2.7.2. Graph-on-parent subpatches </A> </H4> + +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": + +<P><CENTER> <IMG src="fig7.5.jpg"> </CENTER><P> + +where the patch "abstraction2.pd" contains: + +<P><CENTER> <IMG src="fig7.6.jpg"> </CENTER><P> + +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 +(and is saved as part of the abstraction); to set it, open the "properties" +dialog for the "abstraction2" canvas by right-clicking on any white space +in the patch. + +<P> To open the subpatch, right click on the object and select "open". (On +Macintoshes without a 2-button mouse, you can double-click in edit mode +instead.) It doesn't work just to click on the object in run mode since clicks +are sent to visible controls and/or arrays. + +<P> When the sub-patch is closed, all controls in it appear on the object +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 + +<H4> <A name=s8> 2.8. numeric arrays </A> </H4> + +Linear arrays of numbers recur throughout the computer musician's bag of tricks, +beginning with the wavetable oscillator. The wavetable oscillator later was +reinvented as the looping sampler. Also, table lookup is used for nonlinear +distortion of audio signals. In the domain of control, arrays of numbers +can specify control mappings, probability densities, voicing data, and much +more. + +<P> Arrays in Pd should be allocated (and possible read in from a file) before +beginning to make sound, since memory allocation and disk operations may take +long enough to cause audio buffer overruns or underruns. Pd provides two ways +to define new arrays, as "graphs" and "tables". In either case the array +has a pre-defined name and size (i.e., number of points). Elements of the +array are stored as floating-point numbers, 4 bytes apiece + +<P> If you use an array to store a one-second sound at 44.1 kHz you will need +176 kilobytes, or a one-minute sound, 10.6 megabytes. To store a sound with +two or more channels, use a separate array for each channel. + +<P> 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 +spectra derived from the fft~ objects, and probably for many other uses. + +<P> Arrays usually appear within subpatches created to house them, whether +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: + +<P><CENTER> <IMG src="fig8.1.jpg"> </CENTER><P> + +<P> 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: + +<P><CENTER> <IMG src="fig8.2.jpg"> </CENTER><P> + +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: + +<P><CENTER> <IMG src="fig8.3.jpg"> </CENTER><P> + +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.) + +<P> The two previous examples showed control operations to read and write from +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: + +<P><CENTER> <IMG src="fig8.4.jpg"> </CENTER><P> + +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 +1 to 11, and then the values are used as indices for tabread4~, which is a +4-point interpolating table lookup module. (Much more detail is available in +the audio example patches in the "pure documentation" series.) + +<P> To create a new array, select "array" from the "put" menu. Up will come +a dialog window to set initial properties of the array. By default, a +new graph is created to hold the array, but it may also be housed in the +most recently created graph instead. Other properties may be specified there +and/or changed later using the "properties" dialog. + +<P> 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: + +<P><CENTER> <IMG src="fig8.5.jpg"> </CENTER><P> + +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 +in the containing patch; otherwise they're initialized to zero each time the +patch is reloaded. If you intend to use arrays to store sounds, you will +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. + +<P> If you check "delete me" and then "OK", the array wil 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). + +<P> The graph dialog (which also pops up) is shown here: + +<P><CENTER> <IMG src="fig8.6.jpg"> </CENTER><P> + +<P> 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 +kinds of objects might require other X bounds.) The Y bounds should be +chosen to reflect the natural range of the table, so that stored sounds +would naturally range from -1 to 1, but a sequence of frequency values might +range from 0 to 20,000. Finally, you choose the screen size of the graph, +width and height, in screen pixels. + +<P> Many other operations are defined for arrays; see the related patches +in the tutorial (starting at 2.control/15.array.pd) for more possibliities. + +<H4> <A name=s8> 2.9. Data structures </A> </H4> +(Note: this section is adapted from an article submitted to ICMC 2002.) + +<P> The original idea in developing Pd was to make a real-time computer music +performance environment like Max, but somehow to include also a facility for +making computer music scores with user-specifiable graphical representations. +This idea has important precedents in Eric Lindemann's Animal and Bill Buxton's +SSSP. An even earlier class of precedents lies in the rich variety of paper +scores for electronic music before it became practical to offer a +computer-based score editor. In this context, scores by Stockhausen (<I> +Kontakte</I> and <I> Studie II</I>) and Yuasa (<I>Toward the Midnight Sun</I>) +come most prominently to mind, but also Xenakis's <I>Mycenae-alpha</I>, which, +although it was realized using a computer, was scored on paper and only +afterward laboriously transcribed into the computer. + +<P> Pd is designed to to offer an extremely unstructured environment for +describing data structures and their graphical appearance. The underlying +idea is to allow the user to display any kind of data he or she wants to, +associating it in any way with the display. To accomplish this Pd introduces +a graphical data structure, somewhat like a data structure out of the C +programming language, but with a facility for attaching shapes and colors to +the data, so that the user can visualize and/or edit it. The data itself can +be edited from scratch or can be imported from files, generated +algorithmically, or derived from analyses of incoming sounds or other data +streams. + +Here is one simple +example of a very short musical sketch realized using Pd: + +<P><CENTER> <IMG src="fig9.1.jpg"> </CENTER><P> + +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 +having a small grab point at left, a black shape to show dynamic, and a colored +shape to show changing frequency and bandwidth. The horizontal axis represents +time and the vertical axis, frequency (although, as explained later, this +behavior isn't built into pd). The dynamic and frequency shapes aren't +constrained to be connected or even to be proximate, but since they pertain to +the same sound their horizontal positions line up. In this example the last +(furthest-right) object is percussive (as seen by the black shape) and has a +fixed frequency and bandwidth, whereas the large, articulated shape in the +center has a complicated trajectory in both frequency and dynamic. The color +of the frequency trace determines the voice number used to realize it. + +<P> Each object is thus composed of a combination of scalar values (color; +aggregate position in X and Y coordinates) and array values (time/value +pairs for the black traces and time/frequency/bandwidth triples for the +colored ones.) This is all specified by the user using Pd's ``template" +mechanism. + +<P> Here is the template associated with the graphical objects +shown above: + +<P><CENTER> <IMG src="fig9.2.jpg"> </CENTER><P> + +Templates consist of a data structure definition (the "struct" object) and +zero or more drawing instructions ("filledpolygon" and "plot"). The "struct" +object gives the template the name, "template-toplevel." The data structure +is defined to contain three floating point numbers named "x", "y", and +"voiceno," and two arrays, one named "pitch" whose elements belong to another +template named "template-pitch," and similarly for the array "amp." + +<P> In general, data structures are built from four data types: scalar floats +and symbols, arrays (whose elements share another, specified template) and +lists (whose elements may have a variety of templates). The contents of a Pd +window themselves form a list. Pd's correlate of Max's "table" object is +implemented as a top-level array whose elements are scalars containing a single +floating-point number. + +<P> Data structures in Pd may nest arbitrarily deeply using the array and list +types. For example, a collection of sinusoidal tracks from an analysis engine +could be implemented as an array of arrays of (pitch, amplitude) +pairs; this appears as example 12 in Pd's FFT object online tutorial. + +<P> After the "struct" object in the template shown above, the remaining +three objects are <I> drawing instructions </I> , first for a rectangle +("filledpolygon"), and then for two arrays. The various graphical +attributes that are specified for drawing instructions may be numerical +constants or data structure field names; in the latter case the value varies +depending on the data. For instance, the second creation argument to +"plot" is the color. The first "plot" plots the "amp" field and the +color is given as 0, or black. The second one plots "pitch" using the color +"voiceno". In this way the color of the second trace is attached to the +"voiceno" slot in the data structure, so that color will vary according to its +"voiceno" slot. + +<H4> <A name=s9.1> 2.9.1. Traversal </A> </H4> + +<P> 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: + +<P><CENTER> <IMG src="fig9.3.jpg"> </CENTER><P> + +<P> 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 +a list from left to right, on the assumption that users might often want to use Pd +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, +reactive improvisation, and perhaps much more. + +<P> Traversal of data is made possible by adding a new type of atom, "pointer", +to the two previously defined types that make up messages, to wit, numbers and +symbols. Unlike numbers and symbols, pointers have no printed form and thus +can't be uttered in message boxes. Traversal objects such as "pointer" and +"get" (among several others) can generate or use pointers. The pointer data +type is also integrated into pipe-fitting objects such as "pack", +"unpack", +and "route". + +<P> In the patch shown above, the topmost "pointer" object holds a pointer to +the next object to "play" (by sending it to one of the "voice" +abstractions at bottom.) The pointer object takes a "traverse" message to +set it to the head of the list (named "pd-data"), and "next" messages to +move to (and output) the next datum in the list (i.e., the next in the list of +six objects in the score). Another "pointer" object is also used, further +down, as a storage cell for pointers just as "float" is for numbers. + +<P> The center of any sequencer is always the "delay" object, which must be +fed the time difference between each event (including the non-event of hitting +"start") and the next. As we extract each of the six objects in the score, we +must wait the delay for playing that object, and then send its pointer to one +of the "voice" abstractions to play it. However, we have to inspect the +object itself to know the delay before playing it. So, in the loop, we peel off +the first remaining object to play and inspect the time difference between it +and the previous one, using this value to set the delay, but also storing the +pointer in the lower "pointer" and "pack" objects. + +<P> The time difference needed to set the delay object is obtained using the +"get template-toplevel x" object. (This is converted to incremental time +("-"), corrected for tempo, and fed to the delay.) Pd provides +the "get" and "set" +objects for reading and writing values from data structures. +The two "get" objects shown here obtain the "x" and "voiceno" fields +of the current object. The template name (template-toplevel) is supplied +to the "get" objects so that they can look up the offset of the necessary +field(s) in advance, for greater run-time efficiency. + +<P> Once the delay has expired, the object's pointer is recalled (the lower +"pointer" object), and the voice number is recalled. This is packed with +the pointer itself and routed, so that the pointer goes to the appropriate +voice. The voice number is shown as the color of the frequency trace in +"999" units (first digit red, second green, third blue) and the "route" is +arbitrarily set up to select among the six primary and secondary colors plus +black. + +<P> The details of extracting the pitch and dynamic breakpoints from the arrays +defined in the template are managed in the "voice" abstraction. +The "voice" +abstraction receives a +pointer to a given object and manages the sequencing of the arrays; so it +contains two sequencers itself. The nesting of the overall structure of +the sequencer patch mirrors the nesting of the original data structures. +Finally, the voice abstraction puts its audio output on a summing bus. + +<P> More general patches can easily be constructed which access heterogeneous lists +of objects (having different templates). In this way, an arbitrarily rich +personal "score language" can be developed and sequenced. + +<H4> <A name=s9.2> 2.9.2. Accessing and changing data </A> </H4> + +<P> In general, accessing or changing data is done via "pointers" to +"scalars". Numbers and symbols withing 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 +suffices to have objects to chase down elements of lists and arrays (given +either a global name or a pointer to the containing scalar). + +<P> Lists are traversed in the way shown above; to get to a sublist of a scalar, +the "get" object will provide a pointer, in the same way as it provides +"float" or "symbol" elements of scalars. For arrays, an +"element" object is provided which, given a scalar, a field name and +a number, chases down the numbered, scalar, element of the named array field. + +<P> 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 +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 +management system, either of which would be difficult to realize within +real-time computation time constraints. Instead, all the data hanging from a +scalar is considered as belonging to that scalar, and is left in memory until +the scalar is deleted; the data may be changed atom by atom, but primitives +are not provided which would imply unpredictable execution times. + +<P> The "getsize" and "setsize" objects are provided to access or change +the number of elements in the array. For lists, an "append" object +appends a new scalar for a given template to a list, after the element pointed +to. (To insert a scalar at the beginning of a list, the pointer can be set to +the "head" of the list, a formal location before the first list item.) +Deletion is less flexible; the only operation is to delete an entire list. +(There's no reason not to provide finer-grain deletion mechanisms except that +it's not clear how to protect against stale pointers efficiently, except by +voiding the entire collection of pointers into a list.) + +<H4> <A name=s9.3> 2.9.3. Editing </A> </H4> + +<P> The graphical score shown above can be edited by dragging breakpoints, or +by adding and deleting them, using mouse clicks. Also, entire objects or +collections of them may be copied, pasted, and dragged around the screen. +Alternatively, there is an editable (or computer generate-able or parse-able) +text representation for the data, which may be seen or changed in a dialog +window or read and written to external text files. + +<P> Since the graphical presentation of data objects is determined by drawing +instructions, the drawing instructions are interpreted backwards to alter data +as a result of mouse operations. If a given graphical dimension is controlled +by a variable, that variable is then controlled by dragging along that +dimension; if the dimension is constant, it can't be altered by dragging. + +<P> Tricky situations can arise when the user changes the contents of templates. +A change in drawing instructions can be accommodated by simply tracking +down and redrawing all data objects using the template. However, changing +the "struct" object itself make for less straightforward situations. The +user might wish to reorder fields, delete them, add new ones, or rename them. +When a "struct" object changes, Pd automatically conforms the data from the old +structure to the new one. Fields with the same name as previously are maintained +(reordering them as necessary); and if a field disappears but another of the +same type appears, the new one(s) are taken to be renamings of the old one(s) +in order of appearance. New fields which cannot be matched in this way with +previously existing ones are assumed to be new and are initialized. + +<P> 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 +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 +later deletes the "current" one, the data is only conformed to the new version +once the old one is deleted. In this way we avoid getting into situations +where data is left hanging without its structure definition, or where data ends +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. + +<H4> <A name=s9.4> 2.9.4. Limitations </A> </H4> + +<P> 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; +more work is needed to facilitate this. +There should be some facility for turning drawing instructions on and off, or +perhaps for switching between versions of a template, depending on the user's +desired view. There should also be a callback facility in the template for +when an object is edited with the mouse, so that the user can bind actions to +mouse clicks. + +<P> More generally, the collection of traversal objects that Pd provides is +adequate to support a variety of modes of data collection and use, such as +analysis and sequencing. But the patches required to traverse the data +collections are not always simple. It would be desirable to find a more +straightforward mechanism than that provided by the "pointer", "get" +and "set" objects. + +<P> The "data" facility, although part of the original plan for Pd, has only +recently been implemented in its current form, and as (hopefully) the user base +grows there will surely be occasions for many further extensions of the data +handling primitives and the graphical presentation and editing functions. + +</BODY> +</HTML> diff --git a/pd/doc/1.manual/x3.htm b/pd/doc/1.manual/x3.htm new file mode 100644 index 00000000..18d220a6 --- /dev/null +++ b/pd/doc/1.manual/x3.htm @@ -0,0 +1,854 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation 3</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> <B> +Pd Documentation chapter 3: Getting Pd to run +</B> </CENTER> +<BR> +<A href=index.htm#s3> back to table of contents </A> +<BR><BR> + +Pd runs under Irix, Windows, and Linux. +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. + +In case of trouble also consult the Pd mailing list archive on + <A href="http://iem.kug.ac.at/mailinglists/pd-list/"> + http://iem.kug.ac.at/mailinglists/pd-list/</A> +, which often has late-breaking news about configuration problems and solutions. + + +<P> +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. + +<P> +Depending on your application you will have a more or less stringent latency +requirement. Ideally, when any input (audio, MIDI, keyboard, network) is +available, the outputs (in particular the audio output) should react instantly. +In real life, it is necessary to buffer the audio inputs and outputs, trying +always to keep some number of milliseconds ahead of real time to prepare for the +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. + +<P> +To test audio and MIDI, start Pd and select "test Audio and MIDI" from the +"help" menu. + +<P> 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. + +<P> Here are instructions for getting and installing Pd for the four +operating systems it runs on: IRIX, MS Windows, Linux, and Max OSX. + +<H4> <A name=s1.1> 3.1. IRIX (SGI machines) </A> </H4> + +<P> 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". + +<P> +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." + +<P> 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. + +<P> +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. + +<P> +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. + +<P> +The simplest way to invoke Pd is to +make an alias in your ".cshrc" file (assuming you use the "c" shell) such as: +<PRE> + + alias pd ~/pd/bin/pd + +</PRE> +(assuming your Pd distribution landed in ~, for example). + +<P> +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.) + +<P> +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. + +<P> 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. + +<H5> Audio and MIDI in IRIX </H5> + +<P> +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. + +<P> +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 +<PRE> + + startmidi -d /dev/ttyd2 + +</PRE> +to get port 2 speaking MIDI, and +<PRE> + + stopmidi + +</PRE> +to stop it. You can test whether MIDI is configured by typing, +<PRE> + + ps -dafe | grep midi + +</PRE> +and looking for "startmidi" processes. +<P> +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. + +<P> +The O2 apparently has RS232 ports, not RS422. I think SGI's web site says +something about how to deal with this. + +<H4> <A name=s1.2> 3.2. Microsoft Windows </A> </H4> + +<P> 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.) + +<P> +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. + +<P> 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. + +<H5> The vanishing window </H5> + +<P> Pd is a "command line" program. Most error and diagnostic +messages from Pd appear on the command prompt window Pd runs from. + +<P> If you start Pd from the "run" menu or as a shortcut, and if there's +a problem with run-time flags (see the Pd command line below), Pd will +print an error and exit. You won't see this error unless you arrange for the +"command prompt" or "msdos" window to stay open after Pd exits. One way +to do this is to make a "batch" file ("run.bat", say) containing the Pd +command line. + +<H5> Audio in Microsoft Windows </H5> + +<P> +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. + +<P> +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. + +<P> +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. + +<P> 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. + +<H5> ASIO </H5> + +<P> 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 +"the Pd command line" below.) You can also specify a "-blocksize" different +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. + +<P> 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). + +<H5> The special joys of Windows 95 </H5> + +<P> +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. + +<P> +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. + +<P> +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. + +<P> +It is often necessary to specify a huge audio buffer to get steady audio +output in W95; see the command line arguments below. + +<H4> <A name=s1.3> 3.3. Linux </A> </H4> + +<P> 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, but if you have any trouble just mail msp@ucsd.edu and I'll try +to figure out what's wrong and update the instructions accordingly. + +<P> 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. + +<P> 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. + +<P> 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. + +<H5> Getting Pd as an RPM </H5> + +<P> Download Pd, perhaps from + <a href="http://www.crca.ucsd.edu/~msp/software.html"> + http://www.crca.ucsd.edu/~msp/software.html</A> , +to a file such as "pd-0.33-0.i386.rpm". +Open a "shell" window, cd to +the directory containing the file, and type the command, +<PRE> + rpm -i pd-0.33-0.i386.rpm +</PRE> + +<P> (substituting the real file name.) Then you should be able to type "pd" +to a shell and watch the Pd main window appear. + +<H5> Getting Pd as a .tar.gz </H5> + +<P> +Download Pd, perhaps from + <a href="http://www.crca.ucsd.edu/~msp/software.html"> + http://www.crca.ucsd.edu/~msp/software.html</A> , +to file such as "pd-linux-033.tar.gz". Open a "shell" +window, cd to +the directory containing the file, and type the command, +<PRE> + zcat pd-linux-033.tar.gz | tar xf - +</PRE> +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 + +<BR> ./configure +<BR> make depend +<BR> make + +<P> You can pass flags to "configure" to customize your compilation: + +<PRE> + 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 put Pd in /usr/bin instead of /usr/local/bin, add "--prefix=/bin". +</PRE> + +<P> After "make", just type "~/pd/bin/pd" to run pd. + +<P> Alternatively, as superuser, you can run "make install" after "make depend" +and then anyone on your system can just type "pd" to run it. + +<H5> TK support trouble </H5> + +Some people have reported a problem with Pd findind the shared libraries, +"libtcl.so" and "libtk.so". I don't know what causes this, but apparently you +can fix it, as root, by linking /usr/lib/libtcl8.3.so to /usr/lib/libtcl.so and +similarly for tk: + +<PRE> + +# cd /usr/lib +# ln -s libtk8.3.so libtk.so +# ln -s libtcl8.3.so libtcl.so + +</PRE> + +<H5> Testing audio and MIDI. </H5> + +<P> +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". +Then test audio output by running +<PRE> + pd -noadc +</PRE> +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 +business. + +<P> +Then quit Pd and test audio input via +<PRE> + pd -nodac +</PRE> +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. + +<P> Now see if your audio driver can do full duplex by typing "pd" with no +flags. If you see error messages involving /dev/dsp or /dev/dsp2, you're +probably not able to run audio in and out at the same time. If on the other +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. + +<H4> Audio hardware in Linux </H4> + +<P> +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. In addition to the information here, you should +see what's posted on Guenter's page, + + <a href="http://gige.epy.co.at/"> + http://gige.epy.co.at/</A> . + + +<P> +Depending on your hardware and software, you might or might not be able to +run "full duplex," i.e., use audio input and output at the same time. For +many applications it's important to be able to do this, but if by any chance +you don't need simultaneous input and output you will have much less trouble +than if you do. + +<P> +There are two widely-used driver sets, called "OSS" and "ALSA". OSS is +included in the standard Linux kernels since version 2.2. However, for some +audio cards you can find newer versions than are included in the kernel +releases. You can get ALSA from + + <a href="http://www.alsa-project.org/"> + http://www.alsa-project.org/</A> . + +<P> +(There is also a commercial version of the OSS drivers which costs $30 (slightly +more for certain audio cards.) Hit + + <a href="http://www.opensound.com/"> + http://www.opensound.com/</A> . + +These might be easier to use than the free OSS drivers, but I've never tried +them.) + +<P> 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. + +<H5> Installing and configuring FREE OSS </H5> + +<P> +OSS is really a collection of loadable device drivers. The commands +for loading and unloading the drivers are "insmod" and "rmmod". +You can see if the audio drivers are +running using "lsmod" (as root.) If you see something like: +<PRE> + +Module Pages Used by +eepro100 3 1 (autoclean) +opl3 3 0 +opl3sa2 1 0 +ad1848 4 [opl3sa2] 0 +mpu401 5 [opl3sa2] 0 +sound 15 [opl3 opl3sa2 ad1848 mpu401] 0 +soundcore 1 [sound] 6 +soundlow 1 [sound] 0 +aic7xxx 23 2 + +</PRE> +then OSS is running, and if all you see is: +<PRE> + +eepro100 3 1 (autoclean) +aic7xxx 23 2 + +</PRE> +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. + +<P> +The file, "/etc/modules.conf" apparently controls which sound drivers are +started at boot time. The sndconfig program updates this file but you can +also change things manually, for instance to switch between two different sound +cards. In Redhat 6.x and earlier, the file is named "conf.modules." + +<P> Here is a modules.conf file for OSS: + +<PRE> + +alias eth0 e100 +alias parport_lowlevel parport_pc +alias char-major-81 bttv +alias usb-controller usb-uhci +alias sound-slot-0 i810_audio +alias sound-slot-1 es1371 + +</PRE> + +Here the two sound cards are the (motherboard resident) i810 driver and an +ensoniq es1371. + +<P> In RedHat at least, the "sndconfig" program tries to automatically search +for your soundcard. Unfortunlately it only finds the "first" one which is +often not the one you want to use! + +<P> Under OSS, programs can stream sound using either +"block" or "stream" mode. Stream mode is the more modern and better of the +two, but the majority of drivers, even for new sound cards, only +support "block." Pd makes "block" the default. + +<H5> ALSA (Advanced Linux Sound Architecture) </H5> + +<P> 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. + +<P> As of version 0.33 Pd works with either 0.5.x or 0.9.x versions. +The RPM version of Pd is compiled for 0.9.x. If you're starting from the +".tar.gz" version, you have to "./configure --enable-alsa" to get it; see +the "INSTALL.txt" file in the installation. + +<P> By default, Pd uses OSS. If you are running ALSA, Pd will use ALSA's OSS +emulation. To make Pd use ALSA "natively", i.e., the way ALSA is designed +to be used, include the "-alsa" flag in the command line. + +<P> In ALSA, you can specify which sound card to use using the "-alsadev" +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". + +<H5> Which sound card? </H5> + +<P> +Here's a rundown on my experiences with sound cards so far. See +also the Pd mailing list archives. + +<H6> opl3sa </H6> + +This is the old ISA "Yamaha" audio system. It comes on many Dell machines and +seems to offer reasonable consumer quality audio, at least under NT. I +believe the current version of OSS can get full duplex operation out of an +OPL3sa audio system. +This is an ISA ("plug and play" device and you have to deal with I/O +addresses and all that. + +<H6> cs4232 </H6> + +The 1999 vintage dual-processor Dell machines have "cs4232" audio, which I +couldn't get working. + +<H6> es1370 (old Creative PCI128s; Ensoniq AudioPCI) </H6> + +<P> +The audio inputs and outputs on my PCI128 aren't clearly labelled and various +documents give them inconsistent names. On my card there are 4 stereo +mini jacks and a joystick port, in this order: + +<PRE> +joystick black green red blue + bidirectional line-out mic-in line-in +</PRE> + +<P> It used to be possilbe to get quadraphonic audio in and out +of this card, but I haven't tried this in years. + +<H6> Creative SBLive </H6> + +This seems to work fine either with ALSA or OSS as of Pd version 0.35; earlier +versions of Pd didn't see MIDI input under OSS (the driver's fault, not Pd's, +but I figured out a workaround.) + +<H6> Sonorus Stud I/O </H6> + +This $1000 card is supposed to do multichannel digital I/O +in Linux, via a beta version of a commercial OSS driver ($40). +I don't know if anyone has used it with Pd. + +<H6> RME 9652 (Hammerfall) </H6> + +<P> This is the best sound card out there; it costs around $500 and has 3 ADAT +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. + +<P> 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: + + <A HREF=http://gige.xdv.org/pages/rme> + http://gige.xdv.org/pages/rme </A>. + +<P> You must then run Pd using the "-32bit' flag, because this uses a +non-standard extension of OSS to 32 bit samples. + +<P> There's an older driver by Winfried Ritsch, invoked using the "-rme" +flag to Pd. This only works on 2.2 kernels, and you probably shouldn't +try it. It will probably be discontinued after Pd version 0.35. + +<P> 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"). + +<H6> MIDIMAN </H6> + +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". + +<P> 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 +SPDIF input, or "SPDIF" if you do. I think the default is now "internal" +but don't take it for granted... + +<H6> i810/i815 </H6> + +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. + +<H6> Yamaha YMF724 </H6> + +The OSS driver for this card appears not to support MIDI. I haven't +tried with ALSA. + +<H6> ES1371 </H6> + +In OSS, audio and MIDI seem both to work fine with this chipset. + +<H4> <A name=s1.4> 3.4. Macintosh OSX </A> </H4> + +Pd version 0.35 supports Macintosh OSX, although there are still various +problems. You can either download Pd with Mac OSX binaries, or just download +the sources and compile it yourself. + +<H5> To install the binary OSX release: </H5> + +<P> First download and install TK for OSX +(http://sourceforge.net/projects/tcl/). Get a recent one compiled for +OSX, by chasing through "Mac OS X Tk Snapshots." I got +version 8.4a4-2, in a file named "MacOSXTk8.4a4-2.tar.gz ". Unpacking this +yields three directories: ./Applications/Wish Shell.app, +./Library/Frameworks/Tcl.framework, +and ./Library/Frameworks/Tk.framework. These must be moved, either to: +<pre> + ~/Applications/Wish Shell.app + ~/Library/Frameworks/Tcl.framework + ~/Library/Frameworks/Tk.framework +</pre> +or, if you wish to make them available to other users (or make it possible to +recompile Pd), in /Applications and /Library instead. + +<P> Then download and unpack the Pd binary distribution for OS X. This will +create a directory with a name like ~/Desktop/pd-0.35-test22. You can move +this elsewhere if you wish (to ~/pd, for example). To a shell window, type +either "~/Desktop/pd-0.35-test22/bin/pd" or, if you moved it as suggested, +"~/pd/bin/pd" . If you wish you can put the line, + +<pre> + alias pd ~/pd/bin/pd +</pre> + +in the file, ~/.tcshrc, so that you can later just type "pd" to a shell. (The +shell only reads the ~/.tcshrc file onstartup, so this won't take effect in +any existing shells unless you specially type +<pre> + source ~/.tcshrc +</pre> +to them.) + +<P> In some cases you have to explicitly give "-soundindev" and "-soundoutdev" +flags for Pd to open audio correctly; "pd -listdev" should show you the +correct device numbers. + +<P> To get MIDI working, you have to do the Mac OSX magic to get a USB +MIDI interface installed. I've seen this done with Midisport devices and +I think you just download the OSX driver and follow directions. + +<P> On the machine I tried, it was necessary to type, + +<pre> + pd -midiindev 1 -midioutdev 2 +</pre> + +to get MIDI working. At the moment, using a midiman Midisport 2x2, I'm getting +several lines of debugging printout for each incoming MIDI message; it seems to +be the driver printing it out. I don't know how to turn this off. + +<P> To get Pd running at high priority, so that you'll get fewer skips in the +audio input and output, you must "renice" it. The easiest way to do this is +to make it SETUID and use the "-rt" flag. To do this, become root (you might +have to add a root account to do this) and type: + +<pre> + chown root ~ferguson/pd/bin/pd + chmod 4755 ~ferguson/pd/bin/pd +</pre> +(assuming your username is "ferguson"). + +<H5> To compile your own Pd in OSX: </H5> + +Whether you've downloaded the source or the OSX binary distribution you can +always 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. + +<P> 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. + +You must also get the "h" files from XFree86 and put them in +/usr/X11R6/include. You can download just the H files from: +<pre> + http://www.crca.ucsd.edu/~msp/x.tgz +</pre> +(the individual files seem to have adequate copyright notices so that +I can just redistribute them.) + +Then, just as for linux, just unload pd-whatever.tar.gz into a directory +such as ~/pd-0.35-test17 , cd to pd-0.35-test17/src, type "./configure" +and "make". + +then type ~/pd-0.35-test17/bin/pd to a shell and enjoy! + + +<H4> <A name=s3> 3.5. graphics rendering using GEM </A> </H4> + +<P> +GEM, originally by Mark Danks but now supported by Iohannes Zmoelnig, is essentially an extension of Pd that allows you to do OpenGL programming +using a suite of "GEM objects" roughly parallel to the tilde objects built +into Pd for audio. Find out more from +<a href="http://iem.kug.ac.at/~zmoelnig/index.html"> Johannes's page</a>. + + +<H4> <A name=s4> 3.6. The Pd command line </A> </H4> + +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: + +<PRE> + + pd [options] [patches to open] + +</PRE> + +although you may have to specify a path so your command interpreter can find +Pd (OS dependent.) Possible options include: + +<PRE> + +audio configuration flags: +-r <n> -- specify sample rate +-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 <n> -- specify size of audio 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 + +(linux specific audio:) +-frags <n> -- specify number of audio fragments (defeats audiobuf) +-fragsize <n> -- 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 <n> -- ALSA device # (counting from 1) or name: default hw:0,0 + +MIDI configuration flags: +-midiindev ... -- midi in device list; e.g., "1,3" for first and third +-midioutdev ... -- midi out device list, same format +-mididev ... -- specify -midioutdev and -midiindev together +-nomidiin -- suppress MIDI input +-nomidiout -- suppress MIDI output +-nomidi -- suppress MIDI input and output + +general flags: +-path <path> -- add to file 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 <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 <n> -- specify number of audio fragments (defeats audiobuf) +-fragsize <n> -- specify log of fragment size ('blocksize' is better...) +-blocksize <n> -- 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 <n> -- 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) + +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 + +general flags: +-path <path> -- add to file 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 <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) + +</PRE> + +Here are some details on some of the audio and MIDI options (but see also the +next section on file management.) + +<H5> sample rate </H5> + +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. + +<H5> audio buffer size </H5> + +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. + +<P> 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). + +<H5> MIDI devices </H5> + +<P> 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 +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. + +<P> 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 +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." + +<H4> <A name=s5> 3.7. dealing with files </A> </H4> + +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 +"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. + +<P> 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. <BR> + +<P> 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.) + +<P> 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 +the search path. + +</BODY> +</HTML> + + diff --git a/pd/doc/1.manual/x4.htm b/pd/doc/1.manual/x4.htm new file mode 100644 index 00000000..5fe5d25d --- /dev/null +++ b/pd/doc/1.manual/x4.htm @@ -0,0 +1,59 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> <B> +Pd Documentation chapter 4: writing Pd objects in C +</B> </CENTER> +<BR> +<H5> <A href=index.htm#s4> back to table of contents </A></H5> + <BR><BR> +<P> + +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. + +<P> HOW EXTERNS ARE LOADED + +<P> Whenever you type the name of an object +(into an "object" text box) that Pd doesn't yet know about, Pd looks for a +relocatable object file, named, for instance, "profile.pd_irix5". Pd looks +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 +object built into Pd. + +<P> Once you load a new object into Pd, it's there for the duration of your Pd +session. If you load another Pd document which supplies a different version of +some Pd object, the object won't be updated. IF you're working on a new object +and decide to change it, you have to exit and re-enter Pd to get the change to +take. + +<P> In the "externs" subdirectory of the documentation you +can find simple examples of "externs" with their source code and test patches; +there are many other on the web (see <a href="x1.htm#s2">section 1.2 </A>). + +<P> Iohannes Zmoelnig has written an excellent guide to writing externs at +<A href="http://iem.kug.ac.at/pd/externals-HOWTO/"> + http://iem.kug.ac.at/pd/externals-HOWTO/</A> . + +<P> A paper by Theo Stojanov on the subject is at: +<A href="http://www.music.mcgill.ca/~theo/html/audio/pd_externs.pdf"> +http://www.music.mcgill.ca/~theo/html/audio/pd_externs.pdf </A> . + +<P> NT HINT: In NT, Pd is compiled using Visual C 6.0. If you have VC 5.x +your externs won't compile against Pd; you'll get an error about "disk full +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. + + +</BODY> +</HTML> diff --git a/pd/doc/1.manual/x5.htm b/pd/doc/1.manual/x5.htm new file mode 100644 index 00000000..2203ebc7 --- /dev/null +++ b/pd/doc/1.manual/x5.htm @@ -0,0 +1,1231 @@ +<HTML> +<HEAD> +<TITLE>Pd Documentation</TITLE> +</HEAD> +<BODY bgcolor="#ffffff"> +<SMALL> +<div style="width:6.5in; margin-left:.5in"> + +<CENTER> <B> +Pd Documentation chapter 5. current status +</B> </CENTER> +<P> +This section tracks changes in Pd's current implementation. +<BR> +<H5> <A href=index.htm#s5> back to table of contents </A></H5> + +<H4> <A name=s2> 5.1. release notes </A> </H4> + +<P> ------------------ 0.35 ------------------------------- + +<P> 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 +documentation and an example is shown in 7.stuff/synth1/. + +<P> Spaces are allowed in pathnames to Pd and to patches; however, the "path" +variable still can't have spaces. (You can address path directories using +relative pathnames as in "../sound" (or ..\sound on Windows), even if there +are spaces further "up" the path to the patch. See 3.7, "dealing with files." + +<P> The soundfile reading routine (used in readsf~ and soundfiler) is much +better at opening wav files with different header sizes and odd chunks. +You can now read floating-point "wav" files -- although you can't write them +yet. + +<P> Templates and data structures are extensively reworked. A "struct" +object replaces "template", so that you specify the name of the structure as +the first argument to "struct" (previously it was derived from the +window name.) You can now have multiple "structs" of the same name; the +oldest one is the "real" one, but if you delete that, the structures are +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 +automatically to the new data structures. + +<P> A new version of Thomas Musil's GUI objects was merged in. + +<P> The testtone patch works for up to 6 channels of audio input and output. + +<P> Lots of improvements got made to audio I/O in general. In NT you may +specify "-asio" to use ASIO drivers; see HTML documentation section 3.2. +You may specify lists of audio input and output devices. In Linux, Pd +will now attempt to open each /dev/dsp* only once, even if it's requested +for reading and writing. + +<P> The "extra" directory is now searched after the directories in the +search path, not before (so now you can override objects like "fiddle~"). + +<P> A bug in paf~ is fixed. + +<P> In Linux, the ".pdrc" is now read before the command line arguments, so +that command line arguments override the .pdrc (it was backwards before.) + +<P> In Linux, "help" now can invoke either mozilla or netscape to start +up the HTML documentation. This doesn't work in Windows or Mac land yet. + +<P> 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 +to open some other cards in 32bit mode inappropriately.) + +<P> In Linux, MIDI is now opened "-NODELAY" ... this makes the OSS Creative +driver take MIDI input correctly which it didn't before. + +<P> In MS windows, you can now use "readsf~/writesf~" for spooling sounds to +and from disk. + +<P> MS Windows bug fixes: -nosound was ignored, and now works. Also, clicking +to open abstractions, when they were already open anyway, used to lose the +keyboard; this should be fixed now. Finally, "netreceive" didn't work when +running "-nogui". This is fixed, and moreover, you should definitely include +a netreceive object in any -nogui patch in MSW, otherwise it eats up all +available CPU time gratuitously. + +<P> The outlet is removed from the "table" object. + +<P> In MS Windows, Pd now has "-resync" and "-noresync" flags so that you +can specify how to deal with audio input and output blocksize nonsense in +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 +default is "resync". + +<P> In soundfiler's read method, if you specify "-maxsize", that implies +"-resize" (as it ought to.) + +<P> You can use $1-stlye names for arays and tables. + +<P> Pd will now refuse to make duplicate connections between objects. + +<P> Pd is (somewhat shakily) running on Macintosh OS/X. See section 3.4 of +the HTML doc. For Macs with one-button mice, you can double-click in edit +mode to simulate a right click. Unfortunately, the "alt" key doesn't work +yet. + +<P> In Linux, ALSA audio is now fixed to clip, not wrap around, on output +overflows. + +<P> Various problems were fixed with objects changing size. Number boxes never +wrap to two lines (as they used to), and lines are reconnected appropriately +when objects are resized. + +<P> A function call is added to retrieve a unique event-dependent number, +so that objects like "buddy" can be written. + +<P> All the "sound" command-line flags now have "audio" equivalents. + +<P> The "-listdev" flag now works on Mac and MSW/ASIO. + +<P> Help file updates for env~, route, and pointer + +<P> ------------------ 0.34.3 ------------------------------- + +<P> fixed a bug in "udp" netreceive that crashed pd + +<P> fixed a bug in tabosc4~ that caused gritty sound + +<P> changed "specfile" for RPM releases (thanks Fernando) + +<P> adopted Krzysztof's glob_setfilename bug fix + +<P> bug fixes from "the joy of global variables" thread in Pd list + +<P> made a help window for "table". + +<P> ------------------ 0.34.2 ------------------------------- + +<P> fixed ".pdrc" bug + +<P> added an experimental "pd restart-audio" feature for (new) Alsa + +<P> ------------------ 0.34.1 ------------------------------- + +<P> Bug fixes: + +<P> 1. Closing a window with objects selected crashed Pd. + +<P> 2. "find" when it opened a window to show the found object crashed Pd. + +<P> 3. (Linux only) Oversized .pdrc files crashed pd... + +<P> Also, I updated Thomas Musil's IEM GUI objects and their help files. + + +<P> ------------------ 0.34 ------------------------------- + +<P> NEW FEATURES: + +<P> I incorporated Thomas Musil's GUI objects (slider, button, etc.) into +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. + +<P> Many new examples were added to the "2.control" amd expecially +"3.audio" example patches. A list of differences batween Max/MSP and Pd +now appears at the end of this section. + +<P> Finally, I fixed Pd to notice window iconification and suspend graphical +updates for iconified windows. + +<P> Numbering of versions of Pd will now be as in "0.34.2" instead of +"0.34PATCH2" which was confusing. + +<P> BUGS FIXED: + +<P> I incorporated Krzysztof Czaja's menuclose bug fix in g_canvas.c. + +<P> (lunix) the configure script is more rational. + +<P> the qlist and pack objects were fixed to handle reentrancy correctly. + +<P> 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. + +<P> Typing into a message box sometimes left you with lines from the output +pointing to the wrong location. Fixed. + +<P> Reading of "wav" and nextstep soundfiles now handles the headers better. + +<P> ------------------ 0.33 ------------------------------- + +<P> AUDIO AND MIDI: + +<P> MIDI time jitter is reduced. Theoretically, it could now be +as low as the audio blocksize (and so if you care about MIDI timing, keep your +audio blocksize low.) If you run Pd with audio in stream mode or without +audio at all, and perhaps in some cases in block more too (?), +the controlling parameter for MIDI jitter is "-sleepgrain", which specifies +the interval of time Pd sleeps when it believes it's idle. + +<P> You can now 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 +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. + +<P> (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. + +<P> (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. + +<P> (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 +with Midiman Delta 66 and Soundblaster live. I plan to update the linux audio +setup documentation accordingly. + +<P> NEW FEATURES: + +<P> I've put in Shahrokh's new expr, expr~, and fexpr~ objects. The latter +allows you to make expressions referring to prior input and output samples in +case you're interested in writing your own recursive filters, oscillators, +or chaotic sound generators... + +<P> In support of expr, you can now use commas in "object" boxes; they just +become symbols. + +<P> sqrt~ is fixed so that it apparently has 24-bit accurate mantissas. +It turned out to be easier to just make it accurate than to confront the +question of how a reduced-accuracy version should be named. + +<P> The bizarre framp~ object which does phase vocoder analysis got a help +window. The phase vocoder example doesn't use framp~ and I had forgotten +what it did until Guenter dug it back up. + +<P> (linux only) I finally got around to incorporating Guenter's autoconf +stuff, and learned about rpms. 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 +installation prefixes before you actually install them. + +<P> (NT only) I added support for directX using the portaudio package +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 +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. + +<P> BUG FIXES: + +<P> "drawnumber" was broken in 0.32 -- fixed. + +<P> new arrays in 0.32p6 got ill-fitting graphs -- fixed. + +<P> ------------------ 0.32 PATCH 6 ------------------- + +<P> Got array and graph dialogs to behave better when there are more +than one. + +<P> put in mtof~, etc. + +<P> made Pd search the "extra" directory without having to specify it in "path." + +<P> bug fix in exporting patches to Max + +<P> ------------------ 0.32 PATCH 5 ------------------- + +<P> Reversed the order of these release notes so that the newest appear first. + +<P> Arrays can save their content with containing patch; the properties +dialog selects this. The dialog shows up when you create a new array from +the menu, and allows you to set the name and size. Only floating point arrays +can be created and edited this way. + +<P> Bug fix: the figures in the NT web doc were garbage. + +<P> Bug fix: large tables (> 800 pixels and points) no longer crash the GUI. +A related problem remains; large arrays are truncated to either 1000 points +or 1000 pixels. + +<P> Bug fix: doing "save as" on an instantiated abstraction no longer sets +the window title. + +<P> in linux, a couple of status messages on opening /dev/dsp only appear now +if Pd is run "-verbose". + + +<BR> <BR> +<P> ------------------ 0.32 PATCH 2, 3, 4 ------------------- + +<P> Hassled more with font size differnces between NT and Linux, and updated +many help files. Minor bug fixes here and there. + +<P> the table object now takes a second argument to set size in points. + +<P> Improved underflow protection in some DSP objects. + +<P> pointer now has a "vnext" traversal method which goes forward to the +next SELECTED object. + +<P> improvements to throw~ (it now sums) and receive~ fixed to be settable. + +<P> bug fix in which RME driver always thought sample rate was 44100. + +<BR> <BR> +<P> ------------------ 0.32 PATCH 1 ------------------- + +<P> bug fixes (bugs flagged by mik): vcf~ help window crashed; writesf~ +only wrote 1 channel soundfiles; "table" object didn't open when clicked +on; + +<P> new object: tabosc4~ -- finally, a real wavetable oscillator for Pd. + +<P> much work on "data" editing; go to 7.stuff/data-structures, open patches +5 and 7, and try clicking on things. Alt clicks delete or add points; regular +clicks drag values around. The cursor changes to show you what will happen +if you click. + +<BR> <BR> +------------------- 0.32 ----------------- + +<P> <strong> New objects: </strong> + +<P> midiin, sysexin, midiout. (I don't think MIDI sysex is working +in Windows yet though.) + +<P> threshold~ as in Jmax, triggers from audio level. + +<P> value as in Max and Jmax. + +<P> writesf as in Jmax. + +<P> <strong> New startup flags: </strong> + +<P> -sleepgrain: if you aren't using audio I/O, this can reduce time jitter in +MIDI I/O. Otherwise, MIDI I/O jitter is limited by the audio buffer size. + +<P> -noloadbang: cancels loadbangs. + +<P> -nogui: supress 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. + +<P> -guicmd: lets you specify the command string Pd calls to start the GUI, +in case you've written your own GUI to replace the TK one Pd comes with. + +<P> -send: after loading all the patches specified in the command line, +you can specify "startup" messages to send. For example, if you want to use +Pd just to play 50-channel soundfiles from a shell, this is how you can specify +the soundfile name on the command line. + +<P> <strong> bug fixes. </strong> + +<P> A readsf~ problem got fixed. + +<P> hitting the tab key used to cause Pd windows to relinquish the keyboard. + +<P> The $0 feature apperas now to work. + +<P> Inlets and outlets of subpatches sometimes got out of left-to-right order. + +<P> Scrollbars are less out of whack than they were before. + +<P> Pd now knows to de-iconify windows if you "vis" them from the parent. + +<P> <strong> in general: </strong> + +<P> In Linux the treatment of MIDI input is now much more efficient. Also, +bugs were fixed in notin and (for SGI) bendin. + +<P> You can "select all" from the Edit menu. + +<P> standalone programs "pd-send" and "pd-receive" are provided that can send +mesages to Pd or receive messages from Pd via the netsend~ and netreceive~ +objects. This should allow you to interface a wide variety of other programs +with Pd either on the same machine or over the network. Also you should be +able to hack the code into your own programs to make them interoperate with +Pd and/or each other. The underlying protocol is called FUDI. + +<P> "Properties" for scalars, graphs, and number boxes: left click on them. +In particular, number boxes can have fixed widths and finite ranges; if you +make them one character wide they act as toggles. Later you'll be able to +configure them as sliders. + +<P> As to scalars, the properties dialog lets you edit the data in the raw. +Don't try to edit the template though; you can't. + +<P> You can now type into a "pd" object to change its name without losing the +contents. + +<P> An experimental "scalar" _text_ object now allows abstractions to draw +primitive control panels on their parents when you invoke them, as if they were +Moog or Buchla modules. See the "7.stuff/data" examples. + +<P> New help windows for the "data" classes (pointer, append, template, etc.) +and for send/receive which somehow I had neglected. + +<P> When you hit "copy" with nothing selected, the copy buffer used to be +cleared. This is fixed to do nothing. + +<BR> <BR> +------------------- 0.31 ----------------- + +<P> ALSA support in Linux has been completely overhauled. It now works with +Midiman (up to 10 in/12 out!) and es1370. There are problems with SBLive under +ALSA but it works in OSS emulation with a "-frags" setting. See the "getting +started" documentation. + +<P> In NT, the default is now "noresync" if you're running stereo. You can +override this with the "-resync" flag. If you're running more than 2 channels +it's the opposite (as it was before.) + +<P> "symbol" boxes now display symbols and let you type them in. + +<P> There was a bug when you renamed a patch from outside Pd; the old filename +still showed in the title bar (and there were other bad side effects.) FIxed. + +<P> Protection was added against patches opening themselves as abstractions. + +<P> The "route" object's handling of leading symbols was improved. I'm not +sure whether it's Max compatible or not. + +<P> You can draw into arrays with the mouse, at least in the case where there's +at least one pixel per point. (I'm not sure if the other case even makes +sense.) + +<P> Abstractions display their "$1", etc., arguments in the window title bar. + +<P> A "sort" method was added for lists to make them easier to use as +sequencers. + +<P> The "save as" dialog makes a more reasonable choice of start-up directory. + +<P> "Trigger i" is now disallowed (it used to crash Pd.) + +<P> Getbytes and resizebytes now zero out new memory. + +<P> A memory leak reported by Hannes has been partly, hopefully mostly, fixed. + +<P> The "signal_free 2" bug reported by Fogar is fixed. + +<P> New graphs now reliably avoid using already-taken "graph%d" names. + +<P> The old bug which showed up as ".xxxxxxxxx: no such object" is fixed. + +<P> The FFT examples have been reworked and the "pique" and "shift" objects +are moved to "extra". + +<BR> <BR> +------------------- 0.30 ----------------- +<P> in Linux, you can get Pd to promote itself to "real time" priority. +A "watchdog" process protects you from having Pd lock your machine up. You +must request real time by running "pd -rt" or "pd -realtime". You must either +be superuser or make Pd a root-owned SETUID program (chown root .../pd/bin/pd; +chmod 4755 .../pd/bin/pd). For security reasons, Pd relinquishes root +privelige immediately after setting its priority, before loading +any patches or externs. + +<P> Protection was added against message loops. + +<P> loadbang was fixed so that loadbangs in abstractions go off before loadbangs +in the owner patch. Within each patch, loadbangs go off forst in subpatches. + +<P> new object: tabplay~, a non-imterpolating sample reader. + +<P> new objects (in "extra" library): loop~; rev1~. + +<P> The "toys" library was renamed "extra" and incorporated in the Pd release. + +<P> In Linux, timeouts were added to the driver opening and closing code +(which used to hang under some conditions.) + +<P> the "field" object was replaced by "template"; see "data.structures" +examples in 7.stuff. Data lists can be read from and written to files now. + +<P> You can invoke an external object by pathname, as in "../../extra/loop~". + +<P> hip~, etc. should no longer get stuck when they get a NAN on input. + +<P> a bug was fixed in expanding symbols such as "$1-foo". + +<BR> <BR> +------------------- 0.29 ----------------- + +<P> readsf~ - a MAX/FTS style soundfile player, which reads multichannel +soundfiles in wave, aiff, or next formats. The files must be 16 or 24 bit +fixed point or 32 bit floating point (only nextstep headers understand the +latter.) You can also override the header. A "skip" flag lets you read +starting anywhere in the file. (Sorry: linux only for now; I can't find +Posix threads packages for the other platforms.) + +<P> soundfiler - support for reading and writing soundfiles (wave, aiff, +nextstep) to and from arrays. Multichannel soundfiles can be read into or +written from several arrays at once. When reading you can ask that the tables +be automatically resized; in any event the object obligingly outputs the number +of samples actually read. When writing you can specify a sub-segment of the +arrays, and/or request that the soundfile's maximum amplitude be normalized to +one. + +<P> tabplay~ - a non-interpolating sample player + +<P> Garry Kling reports having compiled Pd for "yellowdog" linux on Macintosh +computers. One "fix" has been made to s_linux.c to facilitate this. I don't +have access to a Mac running linux at the moment so I can't verify whether +any particular repease of mine actually works there. + +<P> Signal objects now automatically convert scalars to vectors, so that you +can just run a number box into a signal input. One caveat is that the binops +"+~", "-~", "*~", "/~", "max~", "min~" run slightly faster if you give them +an argument to tell them that their right inlet will be scalar; so the +construction "+~ 0" is still meaningful. This will get fixed at some later +date... + +<P> Font sizes work in what I hope will be a more machine-portable way. On +any machine, the point sizes 8, 10, 12, 14, 16, 24 are DEFINED to be the +largest fonts Pd can find that don't exceed their size on my linux machine. +This way I can write patches that everyone else can read, and others will +at least have fewer portability problems than before. The downside is that +your old patches may appear with a different type size than you want; use the +"font" menu item to fix them. + +<P> The OSS support no longer asks the audio driver whether full duplex +is needed; it just tries to open it. Apparently some drivers (such as +ALSA's OSS emulation) might do full duplex but not implement the call Pd +used to query for it. + +<P> You can give "-nomidi" as a flag (previously you had to type "-nomidiin +-nomidiout".) + +<P> A GUI bug reported by Iain Mott was fixed. + +<P> You can now type symbols such as "$3-poodle" and the "$3" portion gets +expanded properly. Someone was also asking about the FTS-style #0 feature, +but I couldn't figure out how to reconcile it with Pd's usage of "$" for "#" +in abstractions. So I'm still searching for a good way to provide local +symbols. + +<P> the GUI now protects itself from "\", "{" and "}" characters by dropping +them. I wonder how many NT users have crashed Pd trying to type in filenames +with backslashes... + +<P> samphold_set and tabwrite_stop methods added. There turned out to be +no help window for samphold~ so one was supplied. + +<BR> <BR> +------------------- 0.28 ----------------- + +<P> Version 0.28 has a primitive in-box text editor... about time! + +<P> the "front panel" now gives you information on audio levels and +sync errors. + +<P> Message boxes flash, sort of, when you click them. + +<P> +Support has been added for RME 9652 soundcards; see the Linux soundcard section of +the documentation. Support files for RME and PCI128 (Ensoniq es1370) cards +are released separately from Pd. + +<P> The delete and backspace keys clear the current selection. There is +unfortunately no "undo" though; I'm not sure this is a good thing to have +put in. + +<P> The "until" object has a "float" method which limits the number of bangs +it will output. + +<P> The audio setup is better documented for NT and Linux. + +<P> The externs in 4.fft and 6.externs got recompiled and tested. + +<P> BUG FIX: the "read16" message to tables was broken on NT and is now fixed. + +<P> BUG FIX: In Linux, starting Pd up sometimes changed the audio mixer +setting. + +<P> BUG FIX: sending "floats" to inlets expecting lists now works correctly. + +<P> BUG FIX: "route" on symbols now deals better with symbols, floats and lists. + +<BR> <BR> +------------------- 0.27 ----------------- +<P> +The main new feature is the "find" menu stuff. You can search for boxes +containing specified atoms, including semicolons or commas. Most errors are +now trackable, allowing you to "find last error". Look in the "Find" menu. + +<P> +New objects written: change, max, max~, min, min~, and swap. + +<P> +I looked in 0.INTRO.txt in 5.reference, and found that the objects +bag, cputime, realtime, pipe, symbol, poly, and bang were missing. + +<P> +Five or six bug fixes. + +<P> +Some audio problems in 0.25 were addresses. In Linux, audio drivers that +don't support the GETISPACE/GETOSPACE ioctl calls can be called using the +(inferior) "-frags/-fragsize" mechanism. If you specify either a "-frags" +or a "-fragsize" option, the GETIOSPACE calls are cancelled. + +<P> +Under NT, for some audio drivers the 0.26 release gave a constant stream of +"resync" events. I don't know what causes this but I added a "-noresync" +option which simply never resyncs at all. + +<BR> <BR> +------------------- 0.26 ----------------- +<P> +phasor~ and osc~ can be configured to take floating point messages to set +their frequencies, as an alternative to having an input signal to do the +same. Also, +~, etc, can take floating point arguments (and messages) to +add or multiply scalars. THe +~, etc, loops were unrolled to make them +run faster. + +<P> +A switch~ object is provided to let you switch sub-patches on and off. The +inlet~ and outlet~ objects were re-written to avoid adding any overhead when +moving signals in or out of sub patches. + +<P> +In Linux at least, the audio latency is much reduced. It's possible to poll +for audio I/O lateness errors by sending "pd audiostatus". + +<P> +When reading a sample using tabread4~, you can switch between sample tables +using the "set" message. + +<P> +A new "textfile" object is like qlist but more flexible. + +<P> +Many help windows got updated (but at least a dozen more need work urgently). + +<P> +A dsp_addv function was added to allow variable-length DSP calls (for writers +of tilde externs.) + +<P> +It's possible for a tilde extern to have a name ending in "tilde" now. Name +the setup routine "foo_tilde" for "foo~", etc. + +<P> +The dac~ object was fixed to clip its output when out of range (before it +wrapped around.) + +<P> +A first line of protection was added against getting numerical underflow +in delay feedback loops. Before, when a reverberator taled out there was +a sudden jump in CPU usage because the numerical underflows would trap to the +kernel. Now, if any delwrite~ is given a value less than 1e-20 or so, it +records a true zero to avoid this. + +<P> +Signal division checks for divide by zero. + +<P> +A "Font bomb" feature is provided for resizing fonts and stretching and +contracting patches to fit. + +<P> +Pds now bind themselves to the symbol pd-<window-name). + +<P> +IN Linux, if Pd is called as root it tries to promote its run-time +priority. You can make pd a setuid root owned program if you want this +behavior for non-root users who start pd. +(Don't make pd-gui setuid though. That would make a security +hole in your system.) + +<P> +The Pd commend line can take multiple "open" arguments. + +<P> +The file search path feature was fixed amd generalized. + +<P> +Alt-clicking a table gives you a dialog to set its x and y range and pixel +size. + +<BR> <BR> +------------------- 0.25 ----------------- +<P> +Lots of minor, under-the-hood improvements and bug fixes... +<P> +The Netsend/netreceive objects were improved; you can now choose between UDP +and TCP and there's an outlet to tell you whether they're connected. +<P> +You can now alt click on an object to get its help window (and the help +windows got a fair amount of work.) +<P> +multichannel audio I/O -- you can get up to 8 audio cnahhelsin and out. +On SGI this is sdone correctly; on NT it's done using sequential "stereo" +devices. I'm not sure of the status of multichannel in linux... +<P> +The "text" window got new accelerators and a bigger font size +<P> +there are 3 "tool" patches in 7.stuff: filtering, pvoc, ring mod. +<P> +In NT, command-line backslashes are converted to forward slashes. +<P> +There's a load measurement tool in the "help" menu. +<P> +The SGI version contains an n32 binary (look at the "bin" directory). + +<BR> <BR> +------------------- 0.24 --------------- +<P> +new objects: +<BR> - bang - convert any message to a "bang" +<BR> - qlist - message sequencer +<BR> - textfile - file to message converter +<BR> - makefilename - format a name with a variable field +<BR> - openpanel - "Open" dialog +<BR> - savepanel - "Save as" dialog +<P> +Bug fixes: +<BR> - Fixed a bug in "const" message to arrays +<BR> - "exp" was broken on NT, now fixed +<BR> - phase vocoder example improved +<BR> - "read" message to arrays now zero out unread samples +<BR> - bug fix in "key" object +<BR> - bug fix in ifft~ (thanks to Peter Lunden) +<BR> - "print" object fixed to distinguish between lists starting with symbols and + other messages +<BR> - polygon, curve, fpolygon, fcurve renamed to fix name clash with Gem +<BR> - improved "new object" placement on screen +<BR> - fixed help dialog to remember previous directory (thanks to Harry Castle) +<BR> - heterogeneous lists +<P> + +Arrays can be written to and read from text files or from 16-bit +binary files. See ../2.starter/2G for an overview. +<P> + +Guenter Geiger has contributed a Max-style "table" object which +creates an "array" object in a subwindow. +<P> + +Guenter has also put in a "search path" feature for externs, abstractions, +etc. +<P> + +The Help menu got reworked. +<P> + +Select and Route were extended to work Zack-style with symbols. +<P> + +"random" takes seeds now (see the "help" window) +<P> + +Some more work on graphical lists; you can see the current state in +../7.stuff/data-structures. It's still nascent. + +------------------- 0.23 ------------------- +<P> +A first cut at the "pure data" feature is now included. See section 6 +of the documentation for a quick introduction to it; see also patches 12 and +14 in the FFT examples. +<P> +The documentation has been reorganized. The most interesting new features are: +<BR> - some new "tutorial" patches +<BR> - 15 "fft" examples +<BR> - improved help navigation +<P> +more bug fixes: +<BR> - titles on abstractions no longer saved inside file +<BR> - left-to-right sorting of inlets/outlets now seems to work +<BR> - nt audio setup got confused when driver couldn't do full duplex +<BR> - opening window with audio on is now fixed +<BR> - deleting inlets/outlets deletes connections first (used to crash) +<BR> - 1e20 parsed correctly now +<BR> - osc1~ fixed and optimized +<BR> - resizing arrays with DSP on used to crash; now fixed +<BR> - pasting now adds to the end of the list (used to add to beginning) +<BR> - clicking now selects the most recent object when two or more overlap +<BR> - Pd's "open" and "help" dialogs now maintain separate paths +<P> +The phasor~ object's "float" method has been REMOVED -- use the right-hand +inlet to set the internal phase. This is so that I can later fix all tilde +objects to convert messages to signals automatically at all signal inputs. + +<BR> <BR> +------------------- 0.22 ------------------- +<BR> +bug fixes +<BR> - parsing 1e+006 gave symbol (now float) +<BR> - "." parsed as number, should be symbol +<BR> - change GUI polling loop to TK event dispatch (unix only) +<BR> - improved "tidy up" feature +<BR> - size check added to text boxes (used to crash; still not correct.) +<BR> - occasional bug sending text with CRs to tk +<BR> - binop startup bug +<BR> - key accelerators for creators wrong +<BR> - ftom range to 1500 +<BR> - bug in pack, unpack +<BR> - windows restore bigger than saved +<BR> +<BR> + +Nt-specific bug fixes: +<BR> - getsockopt for netreceive fails. Just omitted it for NT. +<BR> - put tcl dlls in tcl bin, not pd bin +<BR> --- archive tcl subsystem for easier version updates +<BR> --- fix README accordingly +<BR> - deal with bell sound +<BR> - turn on optimization +<BR> - looked for audio timeout bug but couldn't find it. +<BR> <BR> + +------------------- 0.21 ------------------- + +<P> +bug fixes: + +<P> +table size change with DSP on: It used to crash Pd to resize an array +when DSP was turned on. This is now fixed. + +<P> +deselect all when locking. When you lock a patch the selection is cleared. + +<P> +unlock when pasting. .. and if you paste into a petch, it's unlocked. + +<P> + +lost keyboard events. Version 0.20 lost keyboard events and +forgot window size changes. This should now be fixed. + +<BR> subpatches came up in wrong font size +<BR> dirty flag on window title bar fixed +<BR> improvement to netreceive suggested by Mark Danks +<BR> style notes fleshed out as suggested by Larry Troxler +<BR> fixed Bill Kleinsasser's bug (short and long array in same graph) + +<P> +new features: + +<BR> phase setting for phasor~ +<BR> fft objects. Also, block~, for specifying block sizes and overlaps for FFTs. +<BR> canvas_makefilename() (used, e.g., by array_read and write) +<BR> "stuff" directory with examples of real Pd applications. + +<BR> <BR> +------------------- 0.20 ------------------- + +<P> +In NT, the 0.19 release turned out not to contain all the files needed to make +TCL run. This problem should now be fixed. + +<P> +Also, the array_write routine was fixed. + +<BR> <BR> +------------------- 0.19 ------------------- + +<BR> +notable new objects: + +<BR> +- vcf~, a bandpass filter with a signal input for center frequency. +<BR> +- delread, delwrite, vd, as in ISPW Max. +<BR> +- various math and midi stuff +<BR> +- catch~, throw~, send~, receive~ for nonlocal signal connections +<P> +- 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 <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 +samples into the table. +<P> +Numbers now default to floating point, although certain objects like "spigot" +and "metro" still convert their boolean inputs to integers so that 0.5 is +"false." This behavior will probably change later. The "div" and "mod" +objects are introduced for explicit integer division and remainder. +<P> +Number boxes drag in integer increments, or in hundredths if you hold the +"shift" key down when you click. +<P> +Pd documents now save their font sizes. The font size is global to an entire +document. New documents come up in the font size Pd was started in (using +the "-font" flag.) If you want to change the font size of an existing +document, use a text editor; the font size is the last argument on the first +line. 8, 10, 12, 14, 16, 18, and 24 are supported. +<P> +The abbreviations "t," "f," and "i" stand for "trigger,", "float", and "int." +<P> +Inlets and outlets of subpatches are now sorted correctly; although there is +still a problem deleting inlets/outlets which have connections. +<P> +The size and screen location of Pd documents is saved correctly. +<P> +Tilde objects now work in "subpages" although there is no way to send +signals through their inlets and outlets; use throw~/catch~ or send~/receive~. +<P> +On NT, the default is to open both audio output and input (this used not +to work.) The situation is still shaky; audio seems to hang up sporadically +on my machine; but I seem to have installed my audio driver wrong anyway. +I had to set a huge output FIFO (1/3 sec or so!) to get it to work at all. +You can type "pd -dac", "pd -adc", or "pd -nosound" to get output only, +input only, or no audio at all. +NT's MIDI input and output are supported, but on my machine MIDI output is +flaky. I'm curious how all this will work on other machines... +<P> +The list of classes is now: +<P> + +GENERAL: +field inlet outlet print int float send receive select route pack unpack +trigger spigot moses delay metro line timer makenote stripnote random loadbang +serial get netsend netreceive +<P> + +MATH: ++ - * / == != > < >= <= & && | || % +mod div sin cos tan atan atan2 sqrt log exp abs +mtof ftom powtodb rmstodb dbtopow dbtorms +<P> + +MIDI: +notein ctlin pgmin bendin touchin polytouchin noteout ctlout pgmout bendout +touchout polytouchout +<P> + +SIGNAL: +dac~ adc~ sig~ line~ snapshot~ +~ -~ *~ /~ phasor~ cos~ vcf~ noise~ env~ hip~ +lop~ bp~ biquad~ samphold~ clip~ rsqrt~ sqrt~ wrap~ print~ scope~ tabwrite~ +tabread4~ send~ receive~ catch~ throw~ delwrite~ delread~ vd~ + +<BR> <BR> +------------------- 0.18 ------------------- + +<BR> +Release notes now descrie the three platforms Pd runs on: IRIX and +NT (maintained at UCSD) and LINUX, maintained by Guenter Geiger. + +<P> +menu "close" on a dirty document now checks if you really want to close +without saving (although "quit" will still exit Pd without verification.) + +<P> +Got rid of "dll" error printout when loading abstractions + +<BR> <BR> +------------------- 0.12 - 0.17 ------------------- + +<BR> +got Pd running under NT, although driver problems remain. Gem is also +distributed for both platforms. + +<BR> <BR> +------------------- 0.11 ------------------- + +<BR> +Here's a list of all the objects in this release: + +<BR> +general: print int float send receive select pack unpack trigger spigot +<BR> +time handling: delay metro line timer +<BR> +arithmetic: + + - - * * / / == == != != > > < < >= >= <= <= & && | || % +<BR> +midi: notein noteout makenote stripnote +<BR> +other: random get +<BR> +signals: dac~ adc~ sig~ line~ snapshot~ +~ *~ +<BR> +signal oscillators: phasor~ cos~ +<BR> +signal filters: env~ hip~ +<BR> +signal debugging : print~ scope~ +<BR> +<BR> + +"spigot" replaces "gate" but has the inputs reversed. + +<BR> <BR> +------------------- 0.10 ------------------- +<BR> + +Many bug fixes. This was the first pre-release to be put on the FTP site. + +<BR> <BR> +------------------- 0.09 ------------------- + +<BR> set up the "Help" menu +<BR> Bug in DSP sorting fixed +<BR> "Notein" and "noteout" objects +<BR> Comments from the Put menu say "comment" (they were invisible before) +<BR> The scheduler deals better when sound I/O malfunctions + +<BR> <BR> +------------------- 0.08 ------------------- + +<BR> metro bug +<BR> scrollbars +<BR> scheduler bug +<BR> text box wraparound at 80 chars. +<BR> fixed boxes to reconnect on retype + +<BR> <BR> +------------------- 0.07 ------------------- + +<BR> +- made an adc~ object + +<BR> <BR> +------------------- 0.06 ------------------- + +<BR> +- fixed two bugs in DSP sorting +<BR> +- added DSP on/off gui +<BR> +- added lock/unlock and changed the cursor behavior +<BR> +- fixed -font flag to set font pointsize + +<BR> <BR> +------------------- 0.05 ------------------- +<P> +- added scope~, which is just a stopgap until real sound editing comes up. +<BR> +- improved the open panel slightly. +<BR> +- added atoms (int only). +<BR> +- reworked text editing to reside in Pd, not Pd-gui. +<BR> +- included a dbx-debuggable Pd in the distribution. I haven't yet figured + out how to get dbx to work with externs though. + +<BR> <BR> +------------------- 0.04 ------------------- +<P> +fixed "cut" which crashed 0.03 if DSP was running. +added clip~, print~, line~, snapshot~. + + +<BR> <BR> +------------------- 0.03 ------------------- +<P> +"pd dsp 1", "pd dsp 0" messages added. If you edit a patch with DSP on, +PD resorts the DSP network as needed. Unconnected and multiple signal inlets +are allowed. + +<BR> <BR> +------------------- 0.02 ------------------- +<P> +A DSP network mechanism has been added. DSP objects are: +sig~, +~, *~, phasor~, cos~. +<P> +Loading of externs is provided (although there is no search path mechanism +so the extern has to be in the patch's current directory.) Look in +pd/externs for an example. + +<BR> <BR> + +------------------- 0.01. ------------------- +<P> +This first release serves mostly to test the "release" mechanism. A Pd +"canvas" object is provided which does both graphing and patch editing. +The editing features apply only to the Max-like part; the graphs have +to be edited into a Pd file via text editor. +<P> +Four menu items (in the "put" menu) create the four kinds of "patchable" +objects; they can be dragged and connected as in Max; to break a connection, +just click on it (the cursor becomes a turkey to indicate this.) Cut, +paste, and duplicate seem to work, and a "Pd" class offers subwindows. +<P> +The following max-like objects are included: + + print; + +, *, -, /, ==, !=, >, <, >=, <=, &, |, &&, ||, %; + int, float, pack, unpack, trigger; + delay, metro, timer; + send, receive. +<P> ----------------------------------------- + +<H4> <A name=s2> 5.2. known bugs </A> </H4> + +<P> In the list below, starred items are still things needing attention... + +<P> *1. Timing of MIDI input/output is very shaky. Audio I/O is primitive, but +there's at least a way to detect errors now for linux and NT. + +<P> *2. There is no flow control for graphical updates yet; the +real-time process can easily block trying to write too fast to the GUI. + +<P> 3. PD dies if your patch has an infinite loop [fixed in 0.30 release.] + +<P> *4. If you cut a box which is a "Pd" or abstraction whose subpatch has +items selected, Pd dies. + +<P> *5. Tables and other drawable items can draw far outside the window; there's +no sanity check, Huge tables (>1000 points) are only partially drawn +(the first 1000 points.) + +<P> 6. There's no way to order force a delread~ to make it read after +a delwrite~ has written. [but see under 3.audio.examples how to do this now.] + +<P> 7. Pd doesn't know to suspend graphics updates when you minimize objects. +Presumably minimization makes things better but it doesn't cut off graphics +computation entirely as it should. [fixed for 0.34] + +<P> 8. If you load a nonexistent extern you get a spurious message, +"consistency check failed: canvas_setargs". [fixed for 0.27 release.] + +<P> 9. Typing backslashes into objects upsets Tk [0.29 should suppress all +backslashes; a real fix might come later.] + +<P> 10. Never type a dollar sign into a comment; you may have trouble +opening your patch afterward... [fixed somewhere around 0.32] + +<P> *11. You'd better Turn DSP off before you type into a box that currently +holds a "pd" object with tilde objects in the subpatch. + +<P> *12. In Linux, if you hit control C while Pd is opening MIDI, Pd hangs. + +<P> *13. In linux, Pd doesn't report audio data-late errors yet. + +<P> *14. Several objects, notably dac~, adc~, and env~, are incompatible with +uses of block~ or switch~ objects that change block size frmo the default of +64. Using switch~ without reblocking causes no problem. Don't try to +read/write delay lines or use send~/receive~, or throw~/catch~, between +windows with different block sizes. + +<H4> <A name=s3> 5.3. differences from Max/MSP </A> </H4> + +<P> 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 +Pd than in Max/MSP, the choices in Pd tend to hew to those in Max/MSP. +Moreover, some effort has been undertaken (but more is needed) to make the +two interoperable. + +<P> You can use Pd to import and export patches to Max/MSP; just save as +text to a file with extension ".pat", and then open it in Pd. You'll at +least get something. If you stick to common or commonizable features +you can actually develop patches for both platforms. + +<P> When specific objects exist on one platform and not on the other, it's +often possible to make abstractions to imitate the missing objects, in a +kind of personalized compatibility library. + +<P> There are, however, differences in semantics you'll want to know about; +a partial list follows. + +<P> <bold> abstraction arguments. </bold> +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., +are replaced by the instantiation arguments. In Pd, these arguments appear +as "$1", etc, and are translated at a slightly later stage of the instantiation +process so that you still see them as "$" variables in the instantiation. +<A href="x2.htm#s7.1"> (see Section 2.7. abstractions) </A> + +<P> In Pd, to make current all instantiations of the +abstraction, either delete and recreate them or close and open the patch; +this is done automatically in Max/MSP. + +<P> In Pd, if you select "save" while in a subpatch, the parent is saved. In +Max/MSP, if you do this a dialogue box comes up asking if you want to save the +subpatch as a separate file. (if you want to save a subpatch to a file in Pd, +you have to copy and paste the contents to a new document. + +<P> In Pd, inlets and outlets are ordinary text objects; in Max/MSP they're +"gui" objects from the palette. + +<P> In Max/MSP, if an object's outlet is connected to several destinations, +corresponding messages are always sent in right-to-left screen order. In +Pd, the messages are sent in the order you made the connections in. In either +case, in situations where you care about the order it's appropriate to use +a "trigger" object to specify. + +<P> In Pd, there's no "gate"; instead it's "spigot" with the inlets in the +opposite, more natural order. + +<P> Switching subsets of the DSP patch on and off is done in completely +different ways in Pd and Max/MSP, and block sizes are handled differently as +well. + +<P> Max offers many "GUI" objects such as sliders, dials, VU meters, piano +keyboards, even "bpatchers." Until version 0.34, the only two in Pd were the +number box and graphical arrays. Starting in version 0.34, Pd incorporates +Thomas Musil's GUI objects: sliders, switches, and so on. (Thanks Thomas!) +Beyond this essential collection of GUI objects, it's unlikely you'll ever find +any commonality between the two. Also, as of 0.34, importing and exporting to +Max doesn't know about the Musil objects; I'll try to get that fixed for 0.35. + +<P> In Pd there's no "preset" object (I now think it's basically a bad idea) +and you have to use explicit sends and receives to restore values to number +boxes. Then just make a "message" box to re-send the values you want. + +<P> In Macintosh land, instead of getting tabosc4~ and arrays, you get cycle~ +and buffer~. The only gotcha is that you probably can't draw in buffer~ with +the mouse as you can with arrays, but at least it's possible to +make a patch that copies a "table" into a "buffer~". + +<P> The "bpatcher" feature in Max has a correlate, "graph on parent" subpatches, +in Pd; however, Pd's version is quite different from Max's. + +</BODY> +</HTML> |
