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

Update for version 2.14.1.

parent 4d63c234
......@@ -12,6 +12,7 @@
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<link rel="stylesheet" href="github-pandoc.css" />
<!--[if lt IE 9]>
......@@ -23,7 +24,7 @@
<p>Albert Gräf &lt;<a href="mailto:aggraef@gmail.com" class="email">aggraef@gmail.com</a>&gt;<br />
Computer Music Dept., Institute of Art History and Musicology<br />
Johannes Gutenberg University (JGU) Mainz, Germany<br />
July 2020</p>
September 2020</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 2</strong> 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>
......@@ -36,7 +37,7 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<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>
<figure>
<img src="purr-data.png" id="fig:fig1" alt="" /><figcaption>Figure 1: Purr Data running on macOS.</figcaption>
<img src="purr-data.png" id="fig:fig1" alt="Figure 1: Purr Data running on macOS." /><figcaption aria-hidden="true">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>
......@@ -71,14 +72,14 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<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>
<figure>
<img src="prefs-audio+midi.png" id="fig:fig2" alt="" /><figcaption>Figure 2: Audio and MIDI setup.</figcaption>
<img src="prefs-audio+midi.png" id="fig:fig2" alt="Figure 2: Audio and MIDI setup." /><figcaption aria-hidden="true">Figure 2: Audio and MIDI setup.</figcaption>
</figure>
<p>The setup on Windows works in a similar fashion. More information for Linux users can be found in the <a href="https://github.com/agraef/purr-data/wiki/Installation#linux-users">wiki</a>.</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’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. The remaining options on the GUI tab are related to the help browser, we’ll discuss these in section <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below.</p>
<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. In Purr Data version 2.14.1 and later, the “grid background in edit mode mode” option enables the edit mode grid, which helps positioning objects and lets you see at a glance when edit mode is active. 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 remaining options on the GUI tab are related to the help browser, we’ll discuss these in section <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below.</p>
<figure>
<img src="prefs-gui+startup.png" id="fig:fig3" alt="" /><figcaption>Figure 3: GUI and Startup options.</figcaption>
<img src="prefs-gui+startup.png" id="fig:fig3" alt="Figure 3: GUI and Startup options." /><figcaption aria-hidden="true">Figure 3: GUI and Startup options.</figcaption>
</figure>
<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>
<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>
......@@ -93,22 +94,28 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
<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>
<figure>
<img src="browser.png" id="fig:fig4" alt="" /><figcaption>Figure 4: Help browser.</figcaption>
<img src="browser+search.png" id="fig:fig4" alt="Figure 4: Help browser." /><figcaption aria-hidden="true">Figure 4: Help browser.</figcaption>
</figure>
<p>On the right in fig. 4 you can see how the display changes after you entered some search terms like “audio devices” and hit Enter. As indicated, you can enter multiple search terms and they will all be searched for in one go (which amounts to matching any of the given search terms, i.e., all patches will be shown for which at least one of the search terms matches). The found help patches will be shown in the list (with short descriptions of the patches if available). You can then click on one of the 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) by default. There are ways to change the scope of the keyword search in the GUI preferences, see <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing 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 navigate to that directory in the file browser 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>
<p>Note that in any case, you can always return to the home screen of the help browser by clicking that tiny “x” symbol in the search entry (or by just hitting Enter in the field if it is empty).</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) by default. There are ways to change the scope of the keyword search in the GUI preferences, see <a href="#configuring-the-help-browser">Configuring The Help Browser</a> below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing 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 located <em>anywhere</em> on your hard drive. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply navigate to that directory in the file browser 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. If you have help patches which live outside the program directory (e.g., somewhere in your home directory), you can also type an absolute directory name to access these.</p>
<p>Note that in any case, you can always return to the home screen of the help browser by clicking that tiny “x” symbol in the search entry (or by just hitting the Esc key with the cursor located in the field).</p>
<h3 id="bookmarks">Bookmarks</h3>
<p>As of Purr Data 2.14.1, the help browser offers a simple but effective bookmark feature which lets you add directories with Pd patches to the browser’s home screen, where they will be shown in their own “Bookmarks” section at the bottom of the home screen.</p>
<p>To add a new bookmark, first navigate to the directory that you’d like to add (using, e.g., the file browser, or by just typing the directory name into the search entry), and then push the little bookmark icon to the right of the file browser icon. A little red cross on the bookmark icon will indicate that the directory has been bookmarked, and that pushing the bookmark icon again will remove that bookmark (see fig. 5, left). The keyboard shortcuts Ctrl+D (Add bookmark) and Ctrl+Shift+D (Remove bookmark) can be used as well.</p>
<figure>
<img src="browser+bookmarks.png" id="fig:fig5" alt="Figure 5: Bookmarking." /><figcaption aria-hidden="true">Figure 5: Bookmarking.</figcaption>
</figure>
<p>You can then press Esc to return to the home screen, where the bookmarked directory will now be shown under the “Bookmarks” section at the bottom of the browser window (you’ll probably have to scroll down to see it). Note that the “Bookmarks” section header will only be displayed if there are any bookmarks to show (see fig. 5, right).</p>
<p>The bookmarks are stored in JSON format in the user’s configuration directory (which is located in the home directory, i.e., ~/.purr-data on Linux and Mac, and /Users/<em>username</em>/AppData/Roaming/Purr-Data on Windows). This file is in a human-readable and easily editable format, so if needed you can rearrange your bookmarks to your liking by editing this file in your favorite text editor.</p>
<h3 id="configuring-the-help-browser">Configuring The Help Browser</h3>
<p>The GUI tab in the preferences dialog (cf. <a href="#gui-and-startup-options">GUI and Startup Options</a> and fig. 3, left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there’s a checkbox which lets you enable this).</p>
<p>Once the browser has been launched, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options <em>will</em> have an impact on startup times. If Purr Data seems to launch slowly, being stuck in index generation, and you rarely use the help browser, then you want to make sure that the “prepare the help index at application start” option is unchecked (which is the default). On the other hand, if you’re using the help browser very frequently and it seems to come up very slowly on first launch, you may want to check that option so that index creation is already done after launching the program.</p>
<p>There are two options which let you change the scope of indexed patches:</p>
<p>The GUI tab in the preferences dialog (cf. <a href="#gui-and-startup-options">GUI and Startup Options</a> and fig. 3, left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there’s a checkbox which lets you enable this). As of Purr Data 2.14.1, the help index is cached in the user’s configuration directory (see <a href="#bookmarks">Bookmarks</a> above) and only rebuilt from scratch when needed (i.e., if the contents of the indexed directories changes).</p>
<p>Once the browser has been launched for the first time and the index has been built and cached, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options <em>will</em> have an impact on indexing time. This should not be much of a problem because the indexing will only have to be done once (after a fresh install or an upgrade of Purr Data). But if you rarely use the help browser at all, then you may want to ensure that the “prepare the help index at application start” option is unchecked (which is the default). Moreover, there are two options which let you change the scope of indexed patches (changing these options will take effect as soon as you relaunch the help browser, and trigger creation of a new index file):</p>
<ul>
<li><p>If “help browser only searches the doc folder” is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you’re an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down indexing considerably).</p></li>
<li><p>If “help browser only searches the doc folder” is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you’re an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down the indexing on first launch considerably).</p></li>
<li><p>The “help browser also searches the help path” option, when checked, lets you tailor the keyword search to the externals you’re working with, so that you won’t be swamped with keyword matches from externals you never use. These externals may be located anywhere you choose, including the extra/ hierarchy, but note that if you’ve already unchecked the “help browser only searches the doc folder” option, then there’s no need to also explicitly add subdirectories of extra/. In either case, the directories to be searched with this option are set using Purr Data’s <em>help path</em> (having them in the library search path is <em>not</em> enough). You do this using Purr Data’s <code>-helppath</code> option which can be added to the “startup flags” field at the bottom of the Startup tab. E.g., on Linux you may want to add something like <code>-helppath ~/pd-l2ork-externals</code> (that directory is often used on Linux for custom and personal external collections).</p></li>
</ul>
<p><strong>Caveat:</strong> Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on startup times, since all these patches will have to be scanned during index creation. Future Purr Data versions will hopefully provide some form of persistence and incremental updates of the search index to mitigate these effects. But for the time being, judicial use of the above options should in most cases give you a sensible setup which does not slow down index creation too much while fulfilling your documentation needs.</p>
<p>Also note that because the search index is created either during program startup or when the help browser is first launched, changing any of the help browser configuration options normally requires a restart of Purr Data to take effect.</p>
<p><strong>Caveat:</strong> Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on first launch times, since all these patches will have to be scanned during index creation.</p>
<h2 id="pd-l2ork-and-purr-data-goodies">Pd-l2ork and Purr Data Goodies</h2>
<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 covers the history and motivation of the Pd-l2ork project.</p>
<p>One of Pd-l2ork’s major advancements over vanilla Pd is its <em>infinite undo</em> capability, which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they’re under development. Many of the other new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren’t even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and “graph on parent” areas using the mouse. A helpful change also worth mentioning here is the improved <em>tidy up</em> option in the Edit menu, which first aligns objects and then spaces them equidistantly.</p>
......@@ -121,12 +128,18 @@ Permanent link: <a href="https://agraef.github.io/purr-data-intro/" class="uri">
</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">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>
<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 elements 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.</p>
<p>TODO: Add a description of Guillem’s subpatch creation, abstraction saving and private abstraction features.</p>
<h2 id="purr-data-and-pd-lua">Purr Data and Pd-Lua</h2>
<p>As of version 2.5, Purr Data includes the latest version of Claude Heiland-Allen’s excellent <a href="https://agraef.github.io/pd-lua/">Pd-Lua</a> extension for embedding the <a href="http://www.lua.org/">Lua</a> scripting language in Pd. This provides you with an easy means (much easier than Pd’s native C interface) to write your own custom Pd objects if they require the use of a real programming language offering loops, functions and complicated data structures.</p>
<p>Lua is perfectly suited for this purpose, because it is light-weight and easily embeddable by design. It is also small and easy to learn, yet very capable, offering a complete range of imperative, object-oriented and functional programming language elements. Like Pd, Lua is an interpreted language featuring dynamic typing, which makes interfacing between Pd and Lua quite easy.</p>
<p>Pd-Lua requires Lua 5.2 or 5.3, which should be readily available in all Linux distributions (on Mac and Windows the requisite Lua 5.3 library is included in the installer). There’s a <a href="https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html">tutorial</a> available to get you started, and a fairly extensive collection of examples can be found in the extra/pdlua/examples folder.</p>
<p>Pd-Lua requires Lua 5.2, 5.3, or 5.4, which should be readily available in all Linux distributions (on Mac and Windows the requisite Lua library is included in the installer). There’s a <a href="https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html">tutorial</a> available to get you started, and a fairly extensive collection of examples can be found in the extra/pdlua/examples folder.</p>
<h2 id="tips-and-tricks">Tips and Tricks</h2>
<p>We conclude this introduction with a little grab bag of helpful tips and tricks. If your questions aren’t answered here, please post them to the DISIS <a href="http://disis.music.vt.edu/listinfo/l2ork-dev">Pd-l2ork mailing list</a>.</p>
<h3 id="edit-mode-and-temporary-run-mode">Edit Mode and Temporary Run Mode</h3>
<p><em>Temporary run mode</em> is a facility present across different Pd flavors which allows you to quickly switch to run mode (where you can operate GUI elements in a patch) while in edit mode (where you can edit the patch). In vanilla Pd, as well as most other Pd flavors, this is activated by pressing and holding the Ctrl modifier key (or the Cmd key on the Mac).</p>
<p>In Purr Data, the modifier was changed to the Alt key in version 2.14.1, because the Ctrl key binding caused some conflicts with the menu shortcuts. This resulted in some rather serious regressions in the GUI, such as some menu keybindings not working in the expected way or interfering with edit mode.</p>
<p>Apart from having to get accustomed to the new key binding, this also implies a potential issue for Linux users, because many Linux desktop environments use Alt-click to initiate a window move action, which will interfere with temporary run mode. You have this issue if you try to operate GUI elements with a click-drag action while holding the Alt key, only to find that this moves the patch window instead. In order to make temporary run mode work again, make sure to rebind the window-move action to a different modifier key and/or mouse button, such as Meta+click or Alt+middle-click which are rarely used by window managers, at least not for important actions.</p>
<p>Version 2.14.1 also introduced the <em>edit mode grid</em> as a better means to indicate that edit mode is active, while also being useful as a positioning aid. (Please note that there’s no “snap-to-grid” option yet, but this may still be added in a future version.) The grid is enabled by default, but can be turned off in the GUI preferences if you don’t want/need it.</p>
<h3 id="install-classic-pd-l2ork-alongside-purr-data">Install classic Pd-l2ork alongside Purr Data</h3>
<p>On Linux there are some situations where you may want to run <em>both</em> classic Pd-l2ork and Purr Data on the same system. This may be useful, e.g., if you need some feature of Pd-l2ork like its K12 mode which hasn’t been ported to Purr Data yet. In order to do this, you need one of the JGU packages of Purr Data (see <a href="#where-to-get-it">Where to Get It</a> above). These will install into a separate directory (normally <code>/opt/purr-data</code>) so that the pathnames of the binaries and libraries in the package do not clash with those from a classic Pd-l2ork installation under <code>/usr</code>. The desktop icons will be named differently as well, and a symbolic link named <code>purr-data</code> will be created in the <code>/usr/bin</code> directory. The link points to <code>/opt/purr-data/bin/pd-l2ork</code> and lets you run Purr Data from the command line without having to specify the full path to the executable. Last but not least, the JGU packages have also been patched up so that they use a separate <code>.purr-data</code> configuration directory in your home directory instead of Pd-l2ork’s <code>.pd-l2ork</code> folder, so that the two programs can happily coexist.</p>
<h3 id="installing-externals">Installing externals</h3>
......
......@@ -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
July 2020
September 2020
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)
......@@ -96,7 +96,7 @@ One pitfall of the Pd engine is that it does not rescan the devices if you conne
### GUI and Startup Options
The GUI theme can be selected on the "GUI" tab (see [@fig:fig3], 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 remaining options on the GUI tab are related to the help browser, we'll discuss these in section [Configuring The Help Browser] below.
The GUI theme can be selected on the "GUI" tab (see [@fig:fig3], 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. In Purr Data version 2.14.1 and later, the "grid background in edit mode mode" option enables the edit mode grid, which helps positioning objects and lets you see at a glance when edit mode is active. 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 remaining options on the GUI tab are related to the help browser, we'll discuss these in section [Configuring The Help Browser] below.
![GUI and Startup options.](prefs-gui+startup.png){#fig:fig3}
......@@ -124,31 +124,39 @@ 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:fig4]) 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.
![Help browser.](browser.png){#fig:fig4}
![Help browser.](browser+search.png){#fig:fig4}
On the right in [@fig:fig4] you can see how the display changes after you entered some search terms like "audio devices" and hit Enter. As indicated, you can enter multiple search terms and they will all be searched for in one go (which amounts to matching any of the given search terms, i.e., all patches will be shown for which at least one of the search terms matches). The found help patches will be shown in the list (with short descriptions of the patches if available). You can then click on one of the 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) by default. There are ways to change the scope of the keyword search in the GUI preferences, see [Configuring The Help Browser] below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing 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 navigate to that directory in the file browser 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.
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) by default. There are ways to change the scope of the keyword search in the GUI preferences, see [Configuring The Help Browser] below. But in any case it is also possible to explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), by employing 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 located *anywhere* on your hard drive. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply navigate to that directory in the file browser 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.
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. If you have help patches which live outside the program directory (e.g., somewhere in your home directory), you can also type an absolute directory name to access these.
Note that in any case, you can always return to the home screen of the help browser by clicking that tiny "x" symbol in the search entry (or by just hitting Enter in the field if it is empty).
Note that in any case, you can always return to the home screen of the help browser by clicking that tiny "x" symbol in the search entry (or by just hitting the Esc key with the cursor located in the field).
### Configuring The Help Browser
### Bookmarks
The GUI tab in the preferences dialog (cf. [GUI and Startup Options] and [@fig:fig3], left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there's a checkbox which lets you enable this).
As of Purr Data 2.14.1, the help browser offers a simple but effective bookmark feature which lets you add directories with Pd patches to the browser's home screen, where they will be shown in their own "Bookmarks" section at the bottom of the home screen.
Once the browser has been launched, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options *will* have an impact on startup times. If Purr Data seems to launch slowly, being stuck in index generation, and you rarely use the help browser, then you want to make sure that the "prepare the help index at application start" option is unchecked (which is the default). On the other hand, if you're using the help browser very frequently and it seems to come up very slowly on first launch, you may want to check that option so that index creation is already done after launching the program.
To add a new bookmark, first navigate to the directory that you'd like to add (using, e.g., the file browser, or by just typing the directory name into the search entry), and then push the little bookmark icon to the right of the file browser icon. A little red cross on the bookmark icon will indicate that the directory has been bookmarked, and that pushing the bookmark icon again will remove that bookmark (see [@fig:fig5], left). The keyboard shortcuts Ctrl+D (Add bookmark) and Ctrl+Shift+D (Remove bookmark) can be used as well.
There are two options which let you change the scope of indexed patches:
![Bookmarking.](browser+bookmarks.png){#fig:fig5}
- If "help browser only searches the doc folder" is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you're an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down indexing considerably).
You can then press Esc to return to the home screen, where the bookmarked directory will now be shown under the "Bookmarks" section at the bottom of the browser window (you'll probably have to scroll down to see it). Note that the "Bookmarks" section header will only be displayed if there are any bookmarks to show (see [@fig:fig5], right).
- The "help browser also searches the help path" option, when checked, lets you tailor the keyword search to the externals you're working with, so that you won't be swamped with keyword matches from externals you never use. These externals may be located anywhere you choose, including the extra/ hierarchy, but note that if you've already unchecked the "help browser only searches the doc folder" option, then there's no need to also explicitly add subdirectories of extra/. In either case, the directories to be searched with this option are set using Purr Data's *help path* (having them in the library search path is *not* enough). You do this using Purr Data's `-helppath` option which can be added to the "startup flags" field at the bottom of the Startup tab. E.g., on Linux you may want to add something like `-helppath ~/pd-l2ork-externals` (that directory is often used on Linux for custom and personal external collections).
The bookmarks are stored in JSON format in the user's configuration directory (which is located in the home directory, i.e., ~/.purr-data on Linux and Mac, and /Users/*username*/AppData/Roaming/Purr-Data on Windows). This file is in a human-readable and easily editable format, so if needed you can rearrange your bookmarks to your liking by editing this file in your favorite text editor.
### Configuring The Help Browser
The GUI tab in the preferences dialog (cf. [GUI and Startup Options] and [@fig:fig3], left) offers some options to configure the scope of the keyword search. Note that in order to perform keyword searches, the help browser first needs to construct an index of all the help patches and their keywords. This is either done on the fly, when the help browser is first opened during a Purr Data session (this is the default), or when the application is launched (there's a checkbox which lets you enable this). As of Purr Data 2.14.1, the help index is cached in the user's configuration directory (see [Bookmarks] above) and only rebuilt from scratch when needed (i.e., if the contents of the indexed directories changes).
Once the browser has been launched for the first time and the index has been built and cached, it will always come up quickly on subsequent invocations. But depending on how many patches you are indexing, creating the index on first launch may take a while (anywhere from less than a second to several seconds on modern hardware), so changing these options *will* have an impact on indexing time. This should not be much of a problem because the indexing will only have to be done once (after a fresh install or an upgrade of Purr Data). But if you rarely use the help browser at all, then you may want to ensure that the "prepare the help index at application start" option is unchecked (which is the default). Moreover, there are two options which let you change the scope of indexed patches (changing these options will take effect as soon as you relaunch the help browser, and trigger creation of a new index file):
- If "help browser only searches the doc folder" is checked (which is the default), then keyword searches are confined to the doc/ hierarchy. This is the fastest option and will be sufficient for novice users at least, as it covers all the official documentation that ships with Purr Data. However, if you're an expert user and frequently use 3rd party externals living in the extra/ hierarchy, then you may want to uncheck this option to have all the remaining subdirectories in the pd-l2ork library directory indexed as well (note that this may slow down the indexing on first launch considerably).
**Caveat:** Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on startup times, since all these patches will have to be scanned during index creation. Future Purr Data versions will hopefully provide some form of persistence and incremental updates of the search index to mitigate these effects. But for the time being, judicial use of the above options should in most cases give you a sensible setup which does not slow down index creation too much while fulfilling your documentation needs.
- The "help browser also searches the help path" option, when checked, lets you tailor the keyword search to the externals you're working with, so that you won't be swamped with keyword matches from externals you never use. These externals may be located anywhere you choose, including the extra/ hierarchy, but note that if you've already unchecked the "help browser only searches the doc folder" option, then there's no need to also explicitly add subdirectories of extra/. In either case, the directories to be searched with this option are set using Purr Data's *help path* (having them in the library search path is *not* enough). You do this using Purr Data's `-helppath` option which can be added to the "startup flags" field at the bottom of the Startup tab. E.g., on Linux you may want to add something like `-helppath ~/pd-l2ork-externals` (that directory is often used on Linux for custom and personal external collections).
Also note that because the search index is created either during program startup or when the help browser is first launched, changing any of the help browser configuration options normally requires a restart of Purr Data to take effect.
**Caveat:** Again, be warned that changing these options and then installing external collections with gazillions of patches into either the extra/ hierarchy or on your personal help path may have a very negative impact on first launch times, since all these patches will have to be scanned during index creation.
## Pd-l2ork and Purr Data Goodies
......@@ -170,18 +178,30 @@ It is worth practicing these so that you can amaze your vanilla-running friends
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 elements 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.
TODO: Add a description of Guillem's subpatch creation, abstraction saving and private abstraction features.
## Purr Data and Pd-Lua
As of version 2.5, Purr Data includes the latest version of Claude Heiland-Allen's excellent [Pd-Lua](https://agraef.github.io/pd-lua/) extension for embedding the [Lua](http://www.lua.org/) scripting language in Pd. This provides you with an easy means (much easier than Pd's native C interface) to write your own custom Pd objects if they require the use of a real programming language offering loops, functions and complicated data structures.
Lua is perfectly suited for this purpose, because it is light-weight and easily embeddable by design. It is also small and easy to learn, yet very capable, offering a complete range of imperative, object-oriented and functional programming language elements. Like Pd, Lua is an interpreted language featuring dynamic typing, which makes interfacing between Pd and Lua quite easy.
Pd-Lua requires Lua 5.2 or 5.3, which should be readily available in all Linux distributions (on Mac and Windows the requisite Lua 5.3 library is included in the installer). There's a [tutorial](https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html) available to get you started, and a fairly extensive collection of examples can be found in the extra/pdlua/examples folder.
Pd-Lua requires Lua 5.2, 5.3, or 5.4, which should be readily available in all Linux distributions (on Mac and Windows the requisite Lua library is included in the installer). There's a [tutorial](https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html) available to get you started, and a fairly extensive collection of examples can be found in the extra/pdlua/examples folder.
## Tips and Tricks
We conclude this introduction 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).
### Edit Mode and Temporary Run Mode
*Temporary run mode* is a facility present across different Pd flavors which allows you to quickly switch to run mode (where you can operate GUI elements in a patch) while in edit mode (where you can edit the patch). In vanilla Pd, as well as most other Pd flavors, this is activated by pressing and holding the Ctrl modifier key (or the Cmd key on the Mac).
In Purr Data, the modifier was changed to the Alt key in version 2.14.1, because the Ctrl key binding caused some conflicts with the menu shortcuts. This resulted in some rather serious regressions in the GUI, such as some menu keybindings not working in the expected way or interfering with edit mode.
Apart from having to get accustomed to the new key binding, this also implies a potential issue for Linux users, because many Linux desktop environments use Alt-click to initiate a window move action, which will interfere with temporary run mode. You have this issue if you try to operate GUI elements with a click-drag action while holding the Alt key, only to find that this moves the patch window instead. In order to make temporary run mode work again, make sure to rebind the window-move action to a different modifier key and/or mouse button, such as Meta+click or Alt+middle-click which are rarely used by window managers, at least not for important actions.
Version 2.14.1 also introduced the *edit mode grid* as a better means to indicate that edit mode is active, while also being useful as a positioning aid. (Please note that there's no "snap-to-grid" option yet, but this may still be added in a future version.) The grid is enabled by default, but can be turned off in the GUI preferences if you don't want/need it.
### Install classic Pd-l2ork alongside Purr Data
On Linux there are some situations where you may want to run *both* classic Pd-l2ork and Purr Data on the same system. This may be useful, e.g., if you need some feature of Pd-l2ork like its K12 mode which hasn't been ported to Purr Data yet. In order to do this, you need one of the JGU packages of Purr Data (see [Where to Get It] above). These will install into a separate directory (normally `/opt/purr-data`) so that the pathnames of the binaries and libraries in the package do not clash with those from a classic Pd-l2ork installation under `/usr`. The desktop icons will be named differently as well, and a symbolic link named `purr-data` will be created in the `/usr/bin` directory. The link points to `/opt/purr-data/bin/pd-l2ork` and lets you run Purr Data from the command line without having to specify the full path to the executable. Last but not least, the JGU packages have also been patched up so that they use a separate `.purr-data` configuration directory in your home directory instead of Pd-l2ork's `.pd-l2ork` folder, so that the two programs can happily coexist.
......
No preview for this file type
prefs-audio+midi.png

172 KB | W: | H:

prefs-audio+midi.png

141 KB | W: | H:

prefs-audio+midi.png
prefs-audio+midi.png
prefs-audio+midi.png
prefs-audio+midi.png
  • 2-up
  • Swipe
  • Onion skin
prefs-gui+startup.png

179 KB | W: | H:

prefs-gui+startup.png

174 KB | W: | H:

prefs-gui+startup.png
prefs-gui+startup.png
prefs-gui+startup.png
prefs-gui+startup.png
  • 2-up
  • Swipe
  • Onion skin
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