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

Final touches.

parent 62309f3a
......@@ -27,28 +27,28 @@ Computer Music Dept., Institute of Art History and Musicology<br/>
Johannes Gutenberg University (JGU) Mainz, Germany<br/>
February 2017</p>
<p>Purr Data a.k.a. Pd-l2ork 2.0 is an improved version of Miller Puckette&#8217;s Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data&#8217;s role in the Pd ecosystem and how it came about.</p>
<p>Purr Data a.k.a. Pd-l2ork 2.x is an improved version of Miller Puckette&#8217;s Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data&#8217;s role in the Pd ecosystem and how it came about.</p>
<h2 id="whatispurrdata">What is Purr Data?</h2>
<p><strong>Purr Data</strong> is the latest (2.0) version of Ivica Ico Bukvic&#8217;s Pd-l2ork. <strong>Pd-l2ork</strong> in turn is a fork of Hans-Christoph Steiner&#8217;s <strong>Pd-extended</strong>, which has been the longest-running (and arguably the most popular) variant of Miller Puckette&#8217;s Pd. <strong>Pd</strong> a.k.a. <strong>Pure Data</strong>, the common basis of all these variants, is Miller Puckette&#8217;s interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74&#8217;s well-known commercial <strong>Max</strong> program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical &#8220;patching&#8221; environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a &#8220;real&#8221; programming language.</p>
<p><strong>Purr Data</strong> is the latest (2.x) branch of Ivica Ico Bukvic&#8217;s Pd-l2ork. <strong>Pd-l2ork</strong> in turn is a fork of Hans-Christoph Steiner&#8217;s <strong>Pd-extended</strong>, which has been the longest-running (and arguably the most popular) variant of Miller Puckette&#8217;s Pd. <strong>Pd</strong> a.k.a. <strong>Pure Data</strong>, the common basis of all these variants, is Miller Puckette&#8217;s interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74&#8217;s well-known commercial <strong>Max</strong> program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical &#8220;patching&#8221; environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a &#8220;real&#8221; programming language.</p>
<p>Puckette&#8217;s version of the program is often jokingly referred to as <strong>&#8220;vanilla&#8221;</strong> Pd, because it comes without any extras and thus provides the purest taste of Pd, you might say. In keeping with this metaphor, the other Pd variants are often called its different <strong>flavors</strong>.</p>
<p>While vanilla Pd, being the reference implementation, remains critically important for the development of Pd&#8217;s real-time engine, its Tcl/Tk-based graphical user interface has never been very pretty or convenient. Consequently there have been several attempts by the community to improve Pd&#8217;s user interface in various ways. Pd-extended is the earliest and the longest-running of these, which also includes a fairly complete selection of 3rd party add-ons. However, its development has stopped in 2013 due to lack of contributions, and thus it receives no more bugfixes and updates of the real-time engine.</p>
<p>Ico Bukvic introduced <strong>Pd-l2ork</strong> in 2010 as a fork of Pd-extended to be used by the &#8220;Linux Laptop Orchestra&#8221; (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugs to be fixed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is expected to run even the oldest of patches.</p>
<p>Ico Bukvic introduced <strong>Pd-l2ork</strong> in 2010 as a fork of Pd-extended to be used by the &#8220;Linux Laptop Orchestra&#8221; (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is required to run even <em>very</em> old patches created with ancient Pd versions.</p>
<p>Despite the many and substantial improvements it offers, Pd-l2ork&#8217;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, 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 GUI, multimedia and web technologies. But most importantly, Pd-l2ork&#8217;s adoption was seriously hampered by the fact that in order to implement some of the graphical improvements it relies on Tcl/Tk extensions which are not available on non-Linux platforms, which means that it wouldn&#8217;t run on Windows or the Mac without substantial effort.</p>
<p>Despite the many and substantial improvements it offers, Pd-l2ork&#8217;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. But most importantly, Pd-l2ork&#8217;s adoption was seriously hampered by the fact that in order to implement some of the graphical improvements, it relies on some more or less Linux-specific Tcl/Tk extensions, which means that it wouldn&#8217;t run on Windows or the Mac without substantial effort.</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. It uses <a href="https://nwjs.io/">nw.js</a> a.k.a. &#8220;node-webkit&#8221;, 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>). All components are open-source, and nw.js has the advantage of being cross-platform, so that Purr Data also runs on Mac and Windows systems. It also makes it possible to leverage standard web technologies such as JavaScript and HTML5 which are much more widespread and have better support than Tcl/Tk these days.</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 a framework called <a href="https://nwjs.io/">nw.js</a> a.k.a. &#8220;node-webkit&#8221;, 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>). Both these components are open-source, and while they were originally invented for developing server-side web applications, frameworks like nw.js combine them in a way so that they can be used for creating full-featured and portable desktop applications. Thus nw.js makes sure that Purr Data also runs on Mac and Windows systems, and it also paves the way to leverage standard web technologies such as JavaScript, HTML5 and SVG which have way better support than Tcl/Tk these days. Last but not least, JavaScript is a much more capable and widespread programming language than Tcl, which makes developing Purr Data&#8217;s graphical user interface a lot easier now that the initial GUI port is done.</p>
<p>Consequently, Purr Data&#8217;s GUI is written entirely in JavaScript. Patches are implemented as SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. 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>
<p>So Purr Data&#8217;s GUI is written entirely in JavaScript. Patches are implemented as HTML5 SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. 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>
<p><img src="purr-data.png" alt="Fig. 1: Purr Data running on Mac OSX." /><br/>
Fig. 1: Purr Data running on Mac OSX.</p>
<p>Purr Data&#8217;s nw.js GUI also has some disadvantages. Most notably, 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 packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, 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 contraints. So you&#8217;ll have to weigh the advantages against the disadvantages, considering your use case and target platform.</p>
<p>Purr Data&#8217;s nw.js GUI also has some disadvantages. Most notably, 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 packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, 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. None of these should normally be a real show-stopper, however. Just give it a try and see whether it works for your use case and target platform.</p>
<p>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>
......@@ -76,7 +76,7 @@ Fig. 1: Purr Data running on Mac OSX.</p>
<h2 id="gettingstarted">Getting Started</h2>
<p>Once you&#8217;ve installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run <code>pd-l2ork</code> from the command line, or look in your desktop environment&#8217;s program menu or launcher for the <code>Pd-l2ork</code> entry and click on that. (If you installed Purr Data from one of the JGU packages, use the <code>purr-data</code> command or the <code>Purr-Data</code> desktop icon instead.)</p>
<p>Once you&#8217;ve installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run <code>pd-l2ork</code> from the command line, or look in your desktop environment&#8217;s program menu or launcher for the <code>Pd-L2Ork</code> entry and click on that. (If you installed Purr Data from one of the JGU packages, use the <code>purr-data</code> command or the <code>Purr-Data</code> desktop icon instead.)</p>
<p>On Mac OSX and Windows, double-click on the application icon (normally to be found in the application or program folder, depending on how you installed it). </p>
......@@ -88,7 +88,9 @@ Fig. 1: Purr Data running on Mac OSX.</p>
<h3 id="singleapplicationinstance">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&#8217;s built-in messaging system (send/receive) and the internal clipboard requires that patches are loaded in the same program instance, and Purr Data makes sure that this is always the case. (This also means that Purr Data&#8217;s real-time processing is all done in a single process right now. In the future, it will also 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&#8217;t been implemented yet.)</p>
<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&#8217;s built-in messaging system (send/receive), or if you&#8217;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&#8217;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&#8217;t been implemented yet.</p>
<h2 id="configuration">Configuration</h2>
......@@ -98,18 +100,16 @@ Fig. 1: Purr Data running on Mac OSX.</p>
<p>The following screenshot (Fig. 2) shows how the &#8220;Audio&#8221; and &#8220;MIDI&#8221; 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 &#8220;API&#8221;. 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>
<p><img src="prefs-audio+midi.png" alt="Fig. 2: Audio and MIDI setup." /><br/>
Fig. 2: Audio and MIDI setup.</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 &#8220;API&#8221;. 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>
<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&#8217;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="guiandstartupoptions">GUI and Startup Options</h3>
<p>The GUI theme can be selected on the &#8220;GUI&#8221; 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&#8217;s library directory, so if you&#8217;re familiar with HTML5 and CSS then you can easily change them or create your own.</p>
<p>Another useful option on the GUI tab is &#8220;save/load zoom level with patch&#8221;. 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 GUI theme can be selected on the &#8220;GUI&#8221; 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&#8217;s library directory, so if you&#8217;re familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is &#8220;save/load zoom level with patch&#8221;. 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><img src="prefs-gui+startup.png" alt="Fig. 3: GUI and Startup options." /><br/>
Fig. 3: GUI and Startup options.</p>
......@@ -138,11 +138,11 @@ Fig. 3: GUI and Startup options.</p>
<p>Using the Help / Help Browser menu option (shortcut: ctrl + B, or cmd + B on the Mac) fires up Purr Data&#8217;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&#8217;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>
<p>On the right in Fig. 4 you can see how the display changes after you entered a search term like &#8220;audio devices&#8221; 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 &#8220;x&#8221; symbol in the search entry returns you to the home screen.</p>
<p><img src="browser.png" alt="Fig. 4: Help browser." /><br/>
Fig. 4: Help browser.</p>
<p>On the right in Fig. 4 you can see how the display changes after you entered a search term like &#8220;audio devices&#8221; 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 &#8220;x&#8221; 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 &#8220;official&#8221; 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 &#8220;extra/mrpeach&#8221; and Enter provides a quick way to access the help patches for the mrpeach externals.</p>
......@@ -153,13 +153,6 @@ Fig. 4: Help browser.</p>
<p>We conclude this primer with a little grab bag of helpful tips and tricks. If your questions aren&#8217;t answered here, please post them to the DISIS <a href="http://disis.music.vt.edu/listinfo/l2ork-dev">Pd-l2ork mailing list</a>. Questions (and answers) which are of interest to all Purr Data users will likely be added to this section in the future. </p>
<h3 id="legacytclcommandsinexternals">Legacy Tcl commands in externals</h3>
<p>Every so often you may run into warnings about &#8220;legacy Tcl commands&#8221; in Purr Data&#8217;s console window which typically look like this:</p>
<pre><code class="(null)">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&#8217;s new nw.js GUI yet. In any case, feel free to report such messages at Purr Data&#8217;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&#8217;re seeing has not been reported in the issue tracker already.</p>
<h3 id="pd-l2orkandpurrdatagoodies">Pd-l2ork and Purr Data goodies</h3>
<p>Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the <a href="http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf">PdCon 2016 paper</a> for details. The paper also has a detailed account on the history and motivation of the Pd-l2ork project.</p>
......@@ -176,7 +169,7 @@ Fig. 4: Help browser.</p>
<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. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little <a href="intelligent-patching.pd">intelligent-patching.pd</a> patch with this primer for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.</p>
<p>Other features will be more useful for advanced users, like the reflection capabilities (see the <code>pdinfo</code>, <code>canvasinfo</code>, <code>classinfo</code> and <code>objectinfo</code> help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the &#8220;Pd-L2Ork Data Structures&#8221; section in the help browser.</p>
<p>Other features will be more useful for advanced users, like the reflection capabilities (see the <code>pdinfo</code>, <code>canvasinfo</code>, <code>classinfo</code> and <code>objectinfo</code> help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the &#8220;Pd-L2Ork Data Structures&#8221; section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a &#8220;real&#8221; programming language.</p>
<h3 id="installclassicpd-l2orkalongsidepurrdata">Install classic Pd-l2ork alongside Purr Data</h3>
......@@ -194,14 +187,6 @@ Fig. 4: Help browser.</p>
<p>For singleton externals it will usually be enough if you just copy them into one of these folders and then relaunch Purr Data. External libraries containing a collection of different externals, on the other hand, will typically require that you also load the library at startup, using the available startup configuration options in the preferences (see &#8220;GUI and Startup Options&#8221; above). </p>
<h3 id="stickypreferences">&#8220;Sticky&#8221; preferences</h3>
<p>One pitfall with Purr Data&#8217;s preferences system (which it shares with its predecessors) is that some options in the startup flags may override other changes done manually in the preferences dialog, and will then appear to &#8220;stick&#8221; when you relaunch Purr Data. E.g., if a library gets loaded via the <code>-lib</code> option in the startup flags, it will <em>also</em> show up in the list of libraries next time you run Purr Data. But if you just remove it there, and not also in the startup flags, then the library will <em>still</em> be loaded next time you run Purr Data. The same caveat applies if you have some options setting up aspects of the audio and MIDI configuration in the startup flags and then reconfigure your devices in the Audio and MIDI tabs of the dialog. Thus, if Purr Data appears to stick to a certain audio or MIDI setup even though you&#8217;re certain that you set (and saved) a new configuration, check the startup flags, they&#8217;re almost certainly to blame. (Another possible culprit are the Linux desktop files, see below.) </p>
<p>This somewhat confusing behavior is due to how Pd handles the startup flags, especially flags which may override some behavior in other configuration options. The easiest way to get rid of all these mishaps is to remove the relevant options in the startup flags (when in doubt, just delete them all so that the startup flags field is completely empty) and save your options by clicking <code>Ok</code> in the preferences dialog.</p>
<p>Sometimes options may seem to stick even if the startup flags field is in fact empty, so that the preferences dialog appears to be partially dysfunctional. This is almost certainly due to some stray startup options in the application&#8217;s desktop files, most likely on Linux (Pd-l2ork&#8217;s original desktop files, which Purr Data inherited in the Linux version, seem to be the main culprit here). Remove the offending options in the desktop icons that you use to launch Purr Data, then this will go away. (Again, when in doubt, just remove <em>all</em> of the extra options in the desktop file, so that just the program name remains; none of these options are essential for Purr Data&#8217;s proper operation.)</p>
<h3 id="resettingthepreferences">Resetting the preferences</h3>
<p>It happens to the best of us that we mess up our Pd configuration so badly that it is beyond repair. In such a case you probably want to go back to Purr Data&#8217;s default setup and start from a clean slate again. Unfortunately, Purr Data&#8217;s preferences dialog does not provide a button for this (yet), but there are ways to accomplish this. They depend on the particular platform, however.</p>
......@@ -214,6 +199,14 @@ Fig. 4: Help browser.</p>
<p>Then just relaunch Purr Data. Your preferences should now be in pristine state again, and all the default search paths and startup libraries will be restored. Of course, you will then have to reconfigure your audio and MIDI devices as needed.</p>
<h3 id="stickypreferences">&#8220;Sticky&#8221; preferences</h3>
<p>One pitfall with Purr Data&#8217;s preferences system (which it shares with its predecessors) is that some options in the startup flags may override other changes done manually in the preferences dialog, and will then appear to &#8220;stick&#8221; when you relaunch Purr Data. E.g., if a library gets loaded via the <code>-lib</code> option in the startup flags, it will <em>also</em> show up in the list of libraries next time you run Purr Data. But if you just remove it there, and not also in the startup flags, then the library will <em>still</em> be loaded next time you run Purr Data. The same caveat applies if you have some options setting up aspects of the audio and MIDI configuration in the startup flags and then reconfigure your devices in the Audio and MIDI tabs of the dialog. Thus, if Purr Data appears to stick to a certain audio or MIDI setup even though you&#8217;re certain that you set (and saved) a new configuration, check the startup flags, they&#8217;re almost certainly to blame. (Another possible culprit are the Linux desktop files, see below.) </p>
<p>This irritating behavior is due to how Pd handles the startup flags, especially flags which may override some behavior in other configuration options. The easiest way to get rid of all these mishaps is to remove the relevant options in the startup flags (when in doubt, just delete them all so that the startup flags field is completely empty) and save your options by clicking <code>Ok</code> in the preferences dialog.</p>
<p>Sometimes options may seem to stick even if the startup flags field is in fact empty, so that the preferences dialog appears to be partially dysfunctional. This is almost certainly due to some stray startup options in the application&#8217;s desktop files, most likely on Linux (Pd-l2ork&#8217;s original desktop files, which Purr Data inherited in the Linux version, seem to be the main culprit here). Remove the offending options in the desktop icons that you use to launch Purr Data, then this will go away. (Again, when in doubt, just remove <em>all</em> of the extra options in the desktop file, so that just the program name remains; none of these options are essential for Purr Data&#8217;s proper operation.)</p>
<h3 id="purrdatahangsduringstartup">Purr Data hangs during startup</h3>
<p>As far as I can tell, this was only reported on Mac OS X so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message <code>incoming connection to GUI</code> in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it (&#8220;force quit&#8221;).</p>
......@@ -227,6 +220,13 @@ Fig. 4: Help browser.</p>
<p>Again, this seems to be a Mac-specific issue. Older (pre&#8211;2.0) Mac versions of Purr Data had the defect that old search paths and startup libraries from previous installations would keep piling up in the configuration until eventually Purr Data&#8217;s startup would become <em>very</em> slow. This has been fixed in the 2.0 version (and startup time on the Mac has generally been improved as well), but if you&#8217;re still using an old configuration from the pre&#8211;2.0 days, then you might still see remnants of this issue even in the 2.0 version.</p>
<p>One thing you can try in this case is to launch the preferences dialog, press <code>Ok</code> and then quit and relaunch Purr Data. If that doesn&#8217;t help, reset the configuration as explained under &#8220;Resetting the preferences&#8221; above. (If that doesn&#8217;t help either, then you probably have a different issue which you should report on Purr Data&#8217;s <a href="https://git.purrdata.net/jwilkes/purr-data/issues">issue tracker</a>.)</p>
<h3 id="legacytclcommandsinexternals">Legacy Tcl commands in externals</h3>
<p>Every so often you may run into warnings about &#8220;legacy Tcl commands&#8221; in Purr Data&#8217;s console window which typically look like this:</p>
<pre><code class="(null)">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&#8217;s new nw.js GUI yet. In any case, feel free to report such messages at Purr Data&#8217;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&#8217;re seeing has not been reported in the issue tracker already.</p>
<!-- ##END MARKED WRAPPER## -->
</div>
......
......@@ -5,28 +5,28 @@ Computer Music Dept., Institute of Art History and Musicology
Johannes Gutenberg University (JGU) Mainz, Germany
February 2017
Purr Data a.k.a. Pd-l2ork 2.0 is an improved version of Miller Puckette's Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data's role in the Pd ecosystem and how it came about.
Purr Data a.k.a. Pd-l2ork 2.x is an improved version of Miller Puckette's Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data's role in the Pd ecosystem and how it came about.
## What is Purr Data?
**Purr Data** is the latest (2.0) version of Ivica Ico Bukvic's Pd-l2ork. **Pd-l2ork** in turn is a fork of Hans-Christoph Steiner's **Pd-extended**, which has been the longest-running (and arguably the most popular) variant of Miller Puckette's Pd. **Pd** a.k.a. **Pure Data**, the common basis of all these variants, is Miller Puckette's interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74's well-known commercial **Max** program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical "patching" environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a "real" programming language.
**Purr Data** is the latest (2.x) branch of Ivica Ico Bukvic's Pd-l2ork. **Pd-l2ork** in turn is a fork of Hans-Christoph Steiner's **Pd-extended**, which has been the longest-running (and arguably the most popular) variant of Miller Puckette's Pd. **Pd** a.k.a. **Pure Data**, the common basis of all these variants, is Miller Puckette's interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74's well-known commercial **Max** program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical "patching" environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a "real" programming language.
Puckette's version of the program is often jokingly referred to as **"vanilla"** Pd, because it comes without any extras and thus provides the purest taste of Pd, you might say. In keeping with this metaphor, the other Pd variants are often called its different **flavors**.
While vanilla Pd, being the reference implementation, remains critically important for the development of Pd's real-time engine, its Tcl/Tk-based graphical user interface has never been very pretty or convenient. Consequently there have been several attempts by the community to improve Pd's user interface in various ways. Pd-extended is the earliest and the longest-running of these, which also includes a fairly complete selection of 3rd party add-ons. However, its development has stopped in 2013 due to lack of contributions, and thus it receives no more bugfixes and updates of the real-time engine.
Ico Bukvic introduced **Pd-l2ork** in 2010 as a fork of Pd-extended to be used by the "Linux Laptop Orchestra" (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugs to be fixed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is expected to run even the oldest of patches.
Ico Bukvic introduced **Pd-l2ork** in 2010 as a fork of Pd-extended to be used by the "Linux Laptop Orchestra" (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is required to run even *very* old patches created with ancient Pd versions.
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, 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 GUI, multimedia and web technologies. But most importantly, Pd-l2ork's adoption was seriously hampered by the fact that in order to implement some of the graphical improvements it relies on Tcl/Tk extensions which are not available on non-Linux platforms, which means that it wouldn't run on Windows or the Mac without substantial effort.
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. But most importantly, Pd-l2ork's adoption was seriously hampered by the fact that in order to implement some of the graphical improvements, it relies on some more or less Linux-specific Tcl/Tk extensions, which means that it wouldn't run on Windows or the Mac without substantial effort.
In 2015 Jonathan Wilkes stepped in and started creating **Purr Data** 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. It uses [nw.js](https://nwjs.io/) a.k.a. "node-webkit", which is essentially a stand-alone web browser engine ([Chromium](http://www.chromium.org/)) combined with a JavaScript runtime ([Node.js](http://nodejs.org/)). All components are open-source, and nw.js has the advantage of being cross-platform, so that Purr Data also runs on Mac and Windows systems. It also makes it possible to leverage standard web technologies such as JavaScript and HTML5 which are much more widespread and have better support than Tcl/Tk these days.
In 2015 Jonathan Wilkes stepped in and started creating **Purr Data** 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 a framework called [nw.js](https://nwjs.io/) a.k.a. "node-webkit", which is essentially a stand-alone web browser engine ([Chromium](http://www.chromium.org/)) combined with a JavaScript runtime ([Node.js](http://nodejs.org/)). Both these components are open-source, and while they were originally invented for developing server-side web applications, frameworks like nw.js combine them in a way so that they can be used for creating full-featured and portable desktop applications. Thus nw.js makes sure that Purr Data also runs on Mac and Windows systems, and it also paves the way to leverage standard web technologies such as JavaScript, HTML5 and SVG which have way better support than Tcl/Tk these days. Last but not least, JavaScript is a much more capable and widespread programming language than Tcl, which makes developing Purr Data's graphical user interface a lot easier now that the initial GUI port is done.
Consequently, Purr Data's GUI is written entirely in JavaScript. Patches are implemented as SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. 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).
So Purr Data's GUI is written entirely in JavaScript. Patches are implemented as HTML5 SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. 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).
![Fig. 1: Purr Data running on Mac OSX.](purr-data.png)
Fig. 1: Purr Data running on Mac OSX.
Purr Data's nw.js GUI also has some disadvantages. Most notably, 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 packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with *very* tight memory contraints. So you'll have to weigh the advantages against the disadvantages, considering your use case and target platform.
Purr Data's nw.js GUI also has some disadvantages. Most notably, 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 packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with *very* tight memory constraints. None of these should normally be a real show-stopper, however. Just give it a try and see whether it works for your use case and target platform.
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.
......@@ -53,7 +53,7 @@ Because of the large number of included externals, Purr Data's build process is
## Getting Started
Once you've installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run `pd-l2ork` from the command line, or look in your desktop environment's program menu or launcher for the `Pd-l2ork` entry and click on that. (If you installed Purr Data from one of the JGU packages, use the `purr-data` command or the `Purr-Data` desktop icon instead.)
Once you've installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run `pd-l2ork` from the command line, or look in your desktop environment's program menu or launcher for the `Pd-L2Ork` entry and click on that. (If you installed Purr Data from one of the JGU packages, use the `purr-data` command or the `Purr-Data` desktop icon instead.)
On Mac OSX and Windows, double-click on the application icon (normally to be found in the application or program folder, depending on how you installed it).
......@@ -65,7 +65,9 @@ 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's built-in messaging system (send/receive) and the internal clipboard requires that patches are loaded in the same program instance, and Purr Data makes sure that this is always the case. (This also means that Purr Data's real-time processing is all done in a single process right now. In the future, it will also 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.)
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.
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.
## Configuration
......@@ -75,18 +77,16 @@ When you launch Purr Data for the first time, most likely you will have to confi
The following screenshot (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 `Apply` button applies the settings *without* closing the dialog or saving the options permanently. If you want to make your changes permanent, you must use the `Ok` button instead. This also closes the dialog.
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 [qjackctl](https://qjackctl.sourceforge.io/) to connect these ports to the hardware devices as needed.
![Fig. 2: Audio and MIDI setup.](prefs-audio+midi.png)
Fig. 2: Audio and MIDI setup.
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 [qjackctl](https://qjackctl.sourceforge.io/) to connect these ports to the hardware devices as needed.
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 [IAC](https://sites.google.com/site/mfalab/mac-stuff/how-to-use-the-iac-driver) devices, on Windows a MIDI loopback driver such as [loopMIDI](http://www.tobias-erichsen.de/software/loopmidi.html) 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 [Jack](http://www.jackaudio.org/).
### GUI and Startup Options
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.
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.
![Fig. 3: GUI and Startup options.](prefs-gui+startup.png)
Fig. 3: GUI and Startup options.
......@@ -115,11 +115,11 @@ Purr Data's central point of entry to the help system is its *Help Browser*, dis
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 *home screen*, which is what gets shown initially below the search entry, by just clicking on one of the section titles.
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.
![Fig. 4: Help browser.](browser.png)
Fig. 4: Help browser.
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.
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 *all* 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.
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.
......@@ -130,16 +130,6 @@ Note that in any case, you can always return to the home screen of the help brow
We conclude this primer with a little grab bag of helpful tips and tricks. If your questions aren't answered here, please post them to the DISIS [Pd-l2ork mailing list](http://disis.music.vt.edu/listinfo/l2ork-dev). Questions (and answers) which are of interest to all Purr Data users will likely be added to this section in the future.
### Legacy Tcl commands in externals
Every so often you may run into warnings about "legacy Tcl commands" in Purr Data's console window which typically look like this:
~~~
legacy tcl command at 201 of ../shared/hammer/file.c: hammereditor_close .86439b0 0
~~~
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 [issue tracker](https://git.purrdata.net/jwilkes/purr-data/issues), 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 *first* that the specific message you're seeing has not been reported in the issue tracker already.
### Pd-l2ork and Purr Data goodies
Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the [PdCon 2016 paper](http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf) for details. The paper also has a detailed account on the history and motivation of the Pd-l2ork project.
......@@ -156,7 +146,7 @@ Another big time-saver is Pd-l2ork's *intelligent patching* facility, which lets
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. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little [intelligent-patching.pd](intelligent-patching.pd) patch with this primer for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.
Other features will be more useful for advanced users, like the reflection capabilities (see the `pdinfo`, `canvasinfo`, `classinfo` and `objectinfo` help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the "Pd-L2Ork Data Structures" section in the help browser.
Other features will be more useful for advanced users, like the reflection capabilities (see the `pdinfo`, `canvasinfo`, `classinfo` and `objectinfo` help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the "Pd-L2Ork Data Structures" section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a "real" programming language.
### Install classic Pd-l2ork alongside Purr Data
......@@ -172,14 +162,6 @@ Purr Data already bundles many if not most of the 3rd party externals commonly u
For singleton externals it will usually be enough if you just copy them into one of these folders and then relaunch Purr Data. External libraries containing a collection of different externals, on the other hand, will typically require that you also load the library at startup, using the available startup configuration options in the preferences (see "GUI and Startup Options" above).
### "Sticky" preferences
One pitfall with Purr Data's preferences system (which it shares with its predecessors) is that some options in the startup flags may override other changes done manually in the preferences dialog, and will then appear to "stick" when you relaunch Purr Data. E.g., if a library gets loaded via the `-lib` option in the startup flags, it will *also* show up in the list of libraries next time you run Purr Data. But if you just remove it there, and not also in the startup flags, then the library will *still* be loaded next time you run Purr Data. The same caveat applies if you have some options setting up aspects of the audio and MIDI configuration in the startup flags and then reconfigure your devices in the Audio and MIDI tabs of the dialog. Thus, if Purr Data appears to stick to a certain audio or MIDI setup even though you're certain that you set (and saved) a new configuration, check the startup flags, they're almost certainly to blame. (Another possible culprit are the Linux desktop files, see below.)
This somewhat confusing behavior is due to how Pd handles the startup flags, especially flags which may override some behavior in other configuration options. The easiest way to get rid of all these mishaps is to remove the relevant options in the startup flags (when in doubt, just delete them all so that the startup flags field is completely empty) and save your options by clicking `Ok` in the preferences dialog.
Sometimes options may seem to stick even if the startup flags field is in fact empty, so that the preferences dialog appears to be partially dysfunctional. This is almost certainly due to some stray startup options in the application's desktop files, most likely on Linux (Pd-l2ork's original desktop files, which Purr Data inherited in the Linux version, seem to be the main culprit here). Remove the offending options in the desktop icons that you use to launch Purr Data, then this will go away. (Again, when in doubt, just remove *all* of the extra options in the desktop file, so that just the program name remains; none of these options are essential for Purr Data's proper operation.)
### Resetting the preferences
It happens to the best of us that we mess up our Pd configuration so badly that it is beyond repair. In such a case you probably want to go back to Purr Data's default setup and start from a clean slate again. Unfortunately, Purr Data's preferences dialog does not provide a button for this (yet), but there are ways to accomplish this. They depend on the particular platform, however.
......@@ -192,6 +174,14 @@ It happens to the best of us that we mess up our Pd configuration so badly that
Then just relaunch Purr Data. Your preferences should now be in pristine state again, and all the default search paths and startup libraries will be restored. Of course, you will then have to reconfigure your audio and MIDI devices as needed.
### "Sticky" preferences
One pitfall with Purr Data's preferences system (which it shares with its predecessors) is that some options in the startup flags may override other changes done manually in the preferences dialog, and will then appear to "stick" when you relaunch Purr Data. E.g., if a library gets loaded via the `-lib` option in the startup flags, it will *also* show up in the list of libraries next time you run Purr Data. But if you just remove it there, and not also in the startup flags, then the library will *still* be loaded next time you run Purr Data. The same caveat applies if you have some options setting up aspects of the audio and MIDI configuration in the startup flags and then reconfigure your devices in the Audio and MIDI tabs of the dialog. Thus, if Purr Data appears to stick to a certain audio or MIDI setup even though you're certain that you set (and saved) a new configuration, check the startup flags, they're almost certainly to blame. (Another possible culprit are the Linux desktop files, see below.)
This irritating behavior is due to how Pd handles the startup flags, especially flags which may override some behavior in other configuration options. The easiest way to get rid of all these mishaps is to remove the relevant options in the startup flags (when in doubt, just delete them all so that the startup flags field is completely empty) and save your options by clicking `Ok` in the preferences dialog.
Sometimes options may seem to stick even if the startup flags field is in fact empty, so that the preferences dialog appears to be partially dysfunctional. This is almost certainly due to some stray startup options in the application's desktop files, most likely on Linux (Pd-l2ork's original desktop files, which Purr Data inherited in the Linux version, seem to be the main culprit here). Remove the offending options in the desktop icons that you use to launch Purr Data, then this will go away. (Again, when in doubt, just remove *all* of the extra options in the desktop file, so that just the program name remains; none of these options are essential for Purr Data's proper operation.)
### Purr Data hangs during startup
As far as I can tell, this was only reported on Mac OS X so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message `incoming connection to GUI` in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it ("force quit").
......@@ -205,3 +195,13 @@ As it's impossible to launch the GUI and remove the offending external in the pr
Again, this seems to be a Mac-specific issue. Older (pre-2.0) Mac versions of Purr Data had the defect that old search paths and startup libraries from previous installations would keep piling up in the configuration until eventually Purr Data's startup would become *very* slow. This has been fixed in the 2.0 version (and startup time on the Mac has generally been improved as well), but if you're still using an old configuration from the pre-2.0 days, then you might still see remnants of this issue even in the 2.0 version.
One thing you can try in this case is to launch the preferences dialog, press `Ok` and then quit and relaunch Purr Data. If that doesn't help, reset the configuration as explained under "Resetting the preferences" above. (If that doesn't help either, then you probably have a different issue which you should report on Purr Data's [issue tracker](https://git.purrdata.net/jwilkes/purr-data/issues).)
### Legacy Tcl commands in externals
Every so often you may run into warnings about "legacy Tcl commands" in Purr Data's console window which typically look like this:
~~~
legacy tcl command at 201 of ../shared/hammer/file.c: hammereditor_close .86439b0 0
~~~
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 [issue tracker](https://git.purrdata.net/jwilkes/purr-data/issues), 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 *first* that the specific message you're seeing has not been reported in the issue tracker already.
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