Commit a5317740 authored by Albert Gräf's avatar Albert Gräf
Browse files

Add an explanation of the -unique flag (multiple application instances) which...

Add an explanation of the -unique flag (multiple application instances) which Purr Data supports since version 2.3.2.
parent 5bf152c6
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<title></title>
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet" href="github-pandoc.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Purr-Data-Intro</title>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.line-block{white-space: pre-line;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<link rel="stylesheet" href="github-pandoc.css">
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="meet-the-cat-a-quick-introduction-to-purr-data">Meet the Cat: A Quick Introduction to Purr Data</h1>
<p>Albert Gräf &lt;<a href="mailto:aggraef@gmail.com">aggraef@gmail.com</a>&gt;<br />
Computer Music Dept., Institute of Art History and Musicology<br />
Johannes Gutenberg University (JGU) Mainz, Germany<br />
February 2017</p>
December 2017</p>
<p>This document is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>. Other formats: <a href="Purr-Data-Intro.md">Markdown</a> source, <a href="Purr-Data-Intro.pdf">PDF</a><br />
Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">https://agraef.github.io/purr-data-intro/</a></p>
<p><strong>Purr Data</strong> a.k.a. <strong>Pd-l2ork</strong> 2.0 is an improved version of Miller Puckette’s interactive computer music and multimedia software <strong>Pd</strong>. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.</p>
......@@ -25,10 +33,9 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<p>Despite the many and substantial improvements it offers, Pd-l2ork’s GUI is still based on Tcl/Tk. This is both good and bad. The major advantage is compatibility with vanilla Pd. On the other hand, Tcl/Tk looks and feels outdated in this day and age, even when going to some lengths with theming, as Pd-l2ork does. Tcl is a rather basic programming language, and its libraries have been falling behind, making it hard to integrate the latest advancements in GUI, multimedia and web technologies. Also, Pd-l2ork’s adoption was hampered by the fact that it was essentially tied to Linux, and thus a cross-platform solution was needed.</p>
<p>In 2015 Jonathan Wilkes stepped in and started creating <strong>Purr Data</strong> to address these problems. In a nutshell, Purr Data is Pd-l2ork with the Tcl/Tk GUI part ripped out and replaced with modern web technology. To these ends, it uses an open-source framework called <a href="https://nwjs.io/">nw.js</a> a.k.a. “node-webkit”, which is essentially a stand-alone web browser engine (<a href="http://www.chromium.org/">Chromium</a>) combined with a JavaScript runtime (<a href="http://nodejs.org/">Node.js</a>). While the latter was originally invented for developing server-side web applications, frameworks like nw.js allow the two to be used in concert to create fully-fledged and portable desktop applications. Using nw.js ensures that Purr Data runs on Linux, Mac and Windows, looking the same on all supported platforms, and it paves the way to leverage standard web technologies such as <a href="https://en.wikipedia.org/wiki/JavaScript">JavaScript</a>, <a href="https://www.w3.org/TR/html5/">HTML5</a>, <a href="https://www.w3.org/Style/CSS/">CSS3</a> and <a href="https://www.w3.org/TR/SVG/">SVG</a>.</p>
<p>Purr Data’s GUI is written entirely in JavaScript, which is a much more advanced programming language than Tcl with an abundance of libraries and support materials. This makes the further development of Purr Data’s graphical user interface a lot easier now that the initial GUI port is done. Patches are implemented as HTML5 SVG documents which offer better responsiveness and graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. Purr Data also looks better and is easier on the eyes than Pd-l2ork, let alone vanilla Pd, especially on high-dpi displays (cf. fig. 1).</p>
<div class="figure">
<img src="purr-data.png" alt="Figure 1: Purr Data running on macOS." id="fig:fig1" style="width:100.0%" />
<p class="caption">Figure 1: Purr Data running on macOS.</p>
</div>
<figure>
<img src="purr-data.png" alt="Figure 1: Purr Data running on macOS." id="fig:fig1" style="width:100.0%" /><figcaption>Figure 1: Purr Data running on macOS.</figcaption>
</figure>
<p>Purr Data’s nw.js GUI also has some disadvantages. First, some of the included externals still rely on Tcl code, so their GUI features will not work in Purr Data until they get ported to the new GUI. Second, the size of the binary package is considerably larger than with Pd-l2ork or Pd-extended since it also includes the full nw.js binary distribution. (This is a valid concern with many of the so-called “portable desktop applications” being offered these days, but in the case of Purr Data it is mitigated by the fact that its Pd-l2ork base is not exactly a slim package either.) Third, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with <em>very</em> tight memory constraints. While none of these issues should normally be a real show-stopper on the supported platforms, it is worth keeping them in mind.</p>
<p>Finally, Purr Data is still comparatively young, but its basis is the tried and proven Pd-l2ork, the present release has been thoroughly tested and many bugs have been ironed out, so it is certainly ready for day-to-day use. It also offers some really compelling advancements over its predecessors. If you have been looking for a modern and actively-maintained successor of Pd-extended, this is it.</p>
<h2 id="the-name">The Name?</h2>
......@@ -53,25 +60,25 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<p>In any case, Purr Data should then launch its main “console” window which logs all messages from the program. If you opened a patch file, it will be shown in a separate “canvas” window.</p>
<p>Purr Data understands basically the same set of command line options as vanilla Pd or Pd-l2ork. On Linux, you can find out about these by running <code>pd-l2ork -help</code> (<code>purr-data -help</code> when using the JGU packages) from the command line. (This isn’t easy to do on Mac and Windows, since the program executable is stowed away somewhere in the application folder.) Some common options which can be placed into the startup flags are <code>-path</code> and <code>-lib</code>, see section <a href="#gui-and-startup-options">GUI and Startup Options</a> below.</p>
<h3 id="single-application-instance">Single Application Instance</h3>
<p>Unlike vanilla Pd, Purr Data always runs as a <em>single application instance</em>. If you load additional patch files (by invoking the <code>pd-l2ork</code> executable or by clicking patch files in the file manager), they will be opened as new canvas windows in that single unique instance. This prevents the kind of confusion which often arises with vanilla Pd if you accidentally open different patches in different instances of the application. Pd requires that patches are loaded in the same program instance if they are to communicate via Pd’s built-in messaging system (send/receive), or if you’d like to copy/paste subpatches between them using the internal clipboard. Purr Data makes sure that this is always the case.</p>
<p>Please note that this also means that Purr Data’s real-time processing is all done in a single process right now. In the future, it will become possible to run different patches on different instances of the real-time engine in order to take advantage of the multi-processing capabilities on modern multi-core systems, but this hasn’t been implemented yet.</p>
<p>Unlike vanilla Pd, Purr Data normally runs as a <em>single application instance</em>. If you load additional patch files (by invoking the <code>pd-l2ork</code> executable or by clicking patch files in the file manager), they will be opened as new canvas windows in that single unique instance. This prevents the kind of confusion which often arises with vanilla Pd if you accidentally open different patches in different instances of the application. Pd requires that patches are loaded in the same program instance if they are to communicate via Pd’s built-in messaging system (send/receive), or if you’d like to copy/paste subpatches between them using the internal clipboard. In its default configuration, Purr Data makes sure that this is always the case.</p>
<h3 id="multiple-application-instances">Multiple Application Instances</h3>
<p>As of version 2.3.2, Purr Data can also be invoked with the <code>-unique</code> flag to create multiple application instances. On Linux, you can do this by just specifying the <code>-unique</code> option on the command line or by editing the desktop icon you use to launch Purr Data. On Mac and Windows (as well as Linux), you can put this option into the startup flags in the preferences, see section <a href="#gui-and-startup-options">GUI and Startup Options</a> below. (Don’t forget to remove the option from the startup flags again when it is not needed any more, in order to revert to the normal single application instance behavior.)</p>
<p>For most applications this shouldn’t be needed, and the single application instance will be most convenient. But there are some situations in which you will want to run several instances of Purr Data instead. Because Purr Data’s real-time processing is all done in a single process associated with the application instance, a single application instance cannot take advantage of the multi-processing capabilities on modern multi-core systems. Some common use cases for multi-processing are if your Pd application involves both audio and graphics processing (typically using the Gem library), or if you have several independent audio processes which you’d like to be run in parallel. In such cases you will want to use the <code>-unique</code> option to launch two or more instances of Purr Data, each with their own sets of Pd patches which will then run on different instances of the real-time engine.</p>
<h2 id="configuration">Configuration</h2>
<p>When you launch Purr Data for the first time, most likely you will have to configure some things, such as the audio and MIDI devices that you want to use. Like Pd-l2ork, Purr Data provides a central “Preferences” dialog which lets you do this in a convenient way.</p>
<h3 id="audio-and-midi-devices">Audio and MIDI Devices</h3>
<p>The screenshot in fig. 2 shows how the “Audio” and “MIDI” tabs in this dialog look like on the Mac. For most purposes it should be sufficient to just select the audio and MIDI inputs and outputs that you want to use from the corresponding dropdown lists. Pressing the <code>Apply</code> button applies the settings <em>without</em> closing the dialog or saving the options permanently. If you want to make your changes permanent, you must use the <code>Ok</code> button instead. This also closes the dialog.</p>
<p>You can redo this procedure at any time if needed. Note that it is usually possible to select multiple input and output devices, but this depends on the platform and the selected audio/MIDI back-end or “API”. Also note that on Linux (using the ALSA API), the MIDI tab will only allow you to set the number of ALSA MIDI input/output ports to be created; you then still have to use a MIDI patchbay program such as <a href="https://qjackctl.sourceforge.io/">qjackctl</a> to connect these ports to the hardware devices as needed.</p>
<div class="figure">
<img src="prefs-audio+midi.png" alt="Figure 2: Audio and MIDI setup." id="fig:fig2" style="width:100.0%" />
<p class="caption">Figure 2: Audio and MIDI setup.</p>
</div>
<figure>
<img src="prefs-audio+midi.png" alt="Figure 2: Audio and MIDI setup." id="fig:fig2" style="width:100.0%" /><figcaption>Figure 2: Audio and MIDI setup.</figcaption>
</figure>
<p>One pitfall of the Pd engine is that it does not rescan the devices if you connect new external audio or MIDI gear while Purr Data is already running. Thus you need to relaunch the program to make the new devices show up in the preferences. In the case of MIDI, it is easy to work around this limitation by employing virtual MIDI devices, which ALSA MIDI does by default. On the Mac you’d use the <a href="https://sites.google.com/site/mfalab/mac-stuff/how-to-use-the-iac-driver">IAC</a> devices, on Windows a MIDI loopback driver such as <a href="http://www.tobias-erichsen.de/software/loopmidi.html">loopMIDI</a> for that purpose. You then wire these up to the MIDI hardware using a separate patchbay program. A similar approach is possible with audio loopback software such as <a href="http://www.jackaudio.org/">Jack</a>.</p>
<h3 id="gui-and-startup-options">GUI and Startup Options</h3>
<p>The GUI theme can be selected on the “GUI” tab (see fig. 3, left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data’s library directory, so if you’re familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is “save/load zoom level with patch”. Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded.</p>
<p>The final tab in the preferences dialog is the “Startup” tab (fig. 3, right), which lets you edit the lists of library paths and startup libraries, as well as the additional options the program is to be invoked with. By default, Purr Data loads most bundled external libraries at startup and adds the corresponding directories to its library search path. If you don’t need all of these, you can remove individual search paths and/or libraries using the “Search Paths” and “Libraries” lists on the Startup tab. Just click on a search path or library and click the <code>Delete</code> button. It is also possible to select an item and add your own search paths and external libraries with the <code>New</code> button, or change an existing entry with the <code>Edit</code> button.</p>
<div class="figure">
<img src="prefs-gui+startup.png" alt="Figure 3: GUI and Startup options." id="fig:fig3" style="width:100.0%" />
<p class="caption">Figure 3: GUI and Startup options.</p>
</div>
<figure>
<img src="prefs-gui+startup.png" alt="Figure 3: GUI and Startup options." id="fig:fig3" style="width:100.0%" /><figcaption>Figure 3: GUI and Startup options.</figcaption>
</figure>
<p>At the bottom of the Startup tab there is a “Startup Flags” field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like <code>-legacy</code> (which enforces bug compatibility with vanilla Pd) as well as the <code>-path</code> and <code>-lib</code> options which provide an alternative way to add search paths and external libraries. For instance, to add JGU’s Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: <code>-lib pure -lib faust/pdfaust</code></p>
<p>Any desired startup options can be set that way, i.e., anything that Pd usually accepts on the command line. However, note that the startup flags require that you relaunch Purr Data for the options to take effect (the same is true if you change the list of startup libraries). Also, while setting paths and libraries via the startup flags is often convenient, there are some downsides to having these options in two different places, see <a href="#sticky-preferences">“Sticky” preferences</a> in the <a href="#tips-and-tricks">Tips and Tricks</a> section below.</p>
<p>As with the other configuration options, remember to press the <code>Ok</code> button in order to have your changes recorded in permanent storage. This will also close the dialog.</p>
......@@ -83,10 +90,9 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<p>Purr Data’s central point of entry to the help system is its <em>Help Browser</em>, discussed below. In addition, as with other Pd flavors, it is also possible to open the help patch for an object by just right-clicking on that object in a patch and choosing the “Help” menu item.</p>
<h3 id="the-help-browser">The Help Browser</h3>
<p>Using the Help / Help Browser menu option (shortcut: ctrl + B, or cmd + B on the Mac) fires up Purr Data’s help browser, which looks deceptively simple (see fig. 4) and is actually quite easy to use, but offers a lot of functionality under the hood. You can search for object names or keywords by typing them in the search entry field at the top of the browser, or you can browse the available documentation sections in the browser’s <em>home screen</em>, which is what gets shown initially below the search entry, by just clicking on one of the section titles.</p>
<div class="figure">
<img src="browser.png" alt="Figure 4: Help browser." id="fig:fig4" style="width:100.0%" />
<p class="caption">Figure 4: Help browser.</p>
</div>
<figure>
<img src="browser.png" alt="Figure 4: Help browser." id="fig:fig4" style="width:100.0%" /><figcaption>Figure 4: Help browser.</figcaption>
</figure>
<p>On the right in fig. 4 you can see how the display changes after you entered a search term like “audio devices” and hit Enter. All related help patches will be shown in the list (with short descriptions of the help patches if available). You can then click on one of the help patches to open it in a canvas window. Clicking on the “x” symbol in the search entry returns you to the home screen.</p>
<p>Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the “official” documentation (the doc/ hierarchy). To explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), you must employ the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse <em>all</em> the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply point the file browser to that directory and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.</p>
<p>If you already know the name of a subdirectory with interesting help patches, you can also just type its name in the search entry (including the doc/ or extra/ prefix) to have the corresponding folder displayed in the help browser. For instance, typing “extra/mrpeach” and Enter provides a quick way to access the help patches for the mrpeach externals.</p>
......@@ -98,7 +104,7 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<ul>
<li><p>If you select <em>exactly</em> two objects A and B, say, and then connect one of the outlets from A to one of the inlets of B, then starting from the initial outlet-inlet pair the remaining outlets of A will be connected to the corresponding inlets of B.</p></li>
<li><p>If you select two (or more) objects B and C, say, and then connect an outlet of a third, <em>unselected</em> object A to an inlet of B, then the corresponding connection from A to C will be done automatically. Conversely, you can also connect an outlet of B to an inlet of A to have the corresponding C-A connection completed for you.</p></li>
<li><p>If you select <em>three</em> (or more) objects A, B and C, say, where A has two outlets or more, and then connect an outlet of A to an inlet of B, then the <em>next</em> outlet of A will be connected to the corresponding inlet of C. Conversely, you can also connect an outlet of B to an inlet of A, and have the corresponding outlet of C connected to the next inlet of A. This works for an arbitrary number of source or target objects, considering the “other” objects in left-to-right, top-to-bottom order.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a></p></li>
<li><p>If you select <em>three</em> (or more) objects A, B and C, say, where A has two outlets or more, and then connect an outlet of A to an inlet of B, then the <em>next</em> outlet of A will be connected to the corresponding inlet of C. Conversely, you can also connect an outlet of B to an inlet of A, and have the corresponding outlet of C connected to the next inlet of A. This works for an arbitrary number of source or target objects, considering the “other” objects in left-to-right, top-to-bottom order.<a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a></p></li>
<li><p>Finally, pressing the shift key while doing connections will let you do multiple connections from the same outlet in one go.</p></li>
</ul>
<p>It is worth practicing these so that you can amaze your vanilla-running friends with the speed at which you can construct rather complicated patches using these shortcuts. As of version 2.1, Purr Data has a help patch for this incredibly useful facility, which I have also provided with this document in the <a href="intelligent-patching.pd" class="uri">intelligent-patching.pd</a> patch for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal, and you can find some subpatches with exercises in the margin of the main patch.</p>
......@@ -138,11 +144,11 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<p>Every so often you may run into warnings about “legacy Tcl commands” in Purr Data’s console window which typically look like this:</p>
<pre><code>legacy tcl command at 201 of ../shared/hammer/file.c: hammereditor_close .86439b0 0</code></pre>
<p>In most cases these should be harmless, but they may indicate a missing piece of GUI functionality due to Tcl code which has not been ported to Purr Data’s new nw.js GUI yet. In any case, feel free to report such messages at Purr Data’s <a href="https://git.purrdata.net/jwilkes/purr-data/issues">issue tracker</a>, so that hopefully someone from the development team can look into them. A proper bug report should at least include the message itself and the Pd object it relates to. If some special steps are needed to reproduce the message, you should report these as well. Also, please do make sure <em>first</em> that the specific message you’re seeing has not been reported in the issue tracker already.</p>
<div class="footnotes">
<section class="footnotes">
<hr />
<ol>
<li id="fn1"><p>This operation works best if the “other” objects only have a single out- or inlet, since that makes the outcome unambiguous. Otherwise Purr Data will often prefer creating outgoing connections, in which case you’ll have to hold down the Ctrl key to enforce incoming connections.<a href="#fnref1"></a></p></li>
<li id="fn1"><p>This operation works best if the “other” objects only have a single out- or inlet, since that makes the outcome unambiguous. Otherwise Purr Data will often prefer creating outgoing connections, in which case you’ll have to hold down the Ctrl key to enforce incoming connections.<a href="#fnref1" class="footnote-back"></a></p></li>
</ol>
</div>
</section>
</body>
</html>
......@@ -3,7 +3,7 @@
Albert Gräf <<aggraef@gmail.com>>
Computer Music Dept., Institute of Art History and Musicology
Johannes Gutenberg University (JGU) Mainz, Germany
February 2017
December 2017
This document is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
Other formats: [Markdown](Purr-Data-Intro.md) source, [PDF](Purr-Data-Intro.pdf)
......@@ -70,9 +70,13 @@ Purr Data understands basically the same set of command line options as vanilla
### Single Application Instance
Unlike vanilla Pd, Purr Data always runs as a *single application instance*. If you load additional patch files (by invoking the `pd-l2ork` executable or by clicking patch files in the file manager), they will be opened as new canvas windows in that single unique instance. This prevents the kind of confusion which often arises with vanilla Pd if you accidentally open different patches in different instances of the application. Pd requires that patches are loaded in the same program instance if they are to communicate via Pd's built-in messaging system (send/receive), or if you'd like to copy/paste subpatches between them using the internal clipboard. Purr Data makes sure that this is always the case.
Unlike vanilla Pd, Purr Data normally runs as a *single application instance*. If you load additional patch files (by invoking the `pd-l2ork` executable or by clicking patch files in the file manager), they will be opened as new canvas windows in that single unique instance. This prevents the kind of confusion which often arises with vanilla Pd if you accidentally open different patches in different instances of the application. Pd requires that patches are loaded in the same program instance if they are to communicate via Pd's built-in messaging system (send/receive), or if you'd like to copy/paste subpatches between them using the internal clipboard. In its default configuration, Purr Data makes sure that this is always the case.
Please note that this also means that Purr Data's real-time processing is all done in a single process right now. In the future, it will become possible to run different patches on different instances of the real-time engine in order to take advantage of the multi-processing capabilities on modern multi-core systems, but this hasn't been implemented yet.
### Multiple Application Instances
As of version 2.3.2, Purr Data can also be invoked with the `-unique` flag to create multiple application instances. On Linux, you can do this by just specifying the `-unique` option on the command line or by editing the desktop icon you use to launch Purr Data. On Mac and Windows (as well as Linux), you can put this option into the startup flags in the preferences, see section [GUI and Startup Options] below. (Don't forget to remove the option from the startup flags again when it is not needed any more, in order to revert to the normal single application instance behavior.)
For most applications this shouldn't be needed, and the single application instance will be most convenient. But there are some situations in which you will want to run several instances of Purr Data instead. Because Purr Data's real-time processing is all done in a single process associated with the application instance, a single application instance cannot take advantage of the multi-processing capabilities on modern multi-core systems. Some common use cases for multi-processing are if your Pd application involves both audio and graphics processing (typically using the Gem library), or if you have several independent audio processes which you'd like to be run in parallel. In such cases you will want to use the `-unique` option to launch two or more instances of Purr Data, each with their own sets of Pd patches which will then run on different instances of the real-time engine.
## Configuration
......
No preview for this file type
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment