From 28e7d308d91556ec078f708b6c4ac855ac340fcc Mon Sep 17 00:00:00 2001 From: Frank Barknecht Date: Fri, 23 Apr 2004 16:26:21 +0000 Subject: This commit was generated by cvs2svn to compensate for changes in r1632, which included commits to RCS files with non-trunk default branches. svn path=/trunk/abstractions/rradical/; revision=1633 --- doc/Makefile | 13 ++ doc/README.txt | 19 ++ doc/caregui.png | Bin 0 -> 1659 bytes doc/communslider.pd | 8 + doc/communslider.png | Bin 0 -> 5279 bytes doc/default.css | 328 +++++++++++++++++++++++++++++++++ doc/memento.png | Bin 0 -> 152685 bytes doc/moresliders.pd | 13 ++ doc/moresliders.png | Bin 0 -> 5468 bytes doc/osccontrol.pd | 27 +++ doc/osccontrol.png | Bin 0 -> 8056 bytes doc/rradicalpd.html | 335 +++++++++++++++++++++++++++++++++ doc/rradicalpd.pdf | Bin 0 -> 273129 bytes doc/rradicalpd.png | Bin 0 -> 33929 bytes doc/rradicalpd.rst | 366 ++++++++++++++++++++++++++++++++++++ doc/rradicalpd.tex | 511 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/substates.pd | 17 ++ doc/substates.png | Bin 0 -> 6219 bytes 18 files changed, 1637 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/README.txt create mode 100644 doc/caregui.png create mode 100644 doc/communslider.pd create mode 100644 doc/communslider.png create mode 100644 doc/default.css create mode 100644 doc/memento.png create mode 100644 doc/moresliders.pd create mode 100644 doc/moresliders.png create mode 100644 doc/osccontrol.pd create mode 100644 doc/osccontrol.png create mode 100644 doc/rradicalpd.html create mode 100644 doc/rradicalpd.pdf create mode 100644 doc/rradicalpd.png create mode 100644 doc/rradicalpd.rst create mode 100644 doc/rradicalpd.tex create mode 100644 doc/substates.pd create mode 100644 doc/substates.png diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..2fc91bb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,13 @@ +REST = rradicalpd + +all: html tex pdf + +tex: + rest2latex --documentclass=scrartcl $(REST).rst $(REST).tex + +pdf: tex + pdflatex $(REST).tex + +html: + rest2html $(REST).rst $(REST).html + diff --git a/doc/README.txt b/doc/README.txt new file mode 100644 index 0000000..3d47aa6 --- /dev/null +++ b/doc/README.txt @@ -0,0 +1,19 @@ +===================================== + RRADical Pd - Conference Material +===================================== + +This folder contains an introduction to Rapid And Reuseable Application +Development (RRADical) with Pure Data as will be presented at the Linux +Audio Conference 2 in ZKM Karlsruhe. The main text is in rradicalpd.rst and +is a simple textfile using reStructuredText markup. You can either read +this file or convert it to HTML, Tex, XML, PDF and many more using the +Python-Docutils tool collection. HTML, Tex and PDF renderings are +included. The *.pd files are example patches for Pd. + +The text is full of spelling errors, needs some serious proof reading and +does not yet cover the last third of the talk which will be a practical +walkthrough to building a RRADical Pd patch. For that, just look ate the +"usecases" folder in the RRADical patch collection, which is included in +the archive rradical-wip-040325.tgz + +-- Frank Barknecht , 2004 diff --git a/doc/caregui.png b/doc/caregui.png new file mode 100644 index 0000000..b1d6680 Binary files /dev/null and b/doc/caregui.png differ diff --git a/doc/communslider.pd b/doc/communslider.pd new file mode 100644 index 0000000..64585ce --- /dev/null +++ b/doc/communslider.pd @@ -0,0 +1,8 @@ +#N canvas 186 212 371 285 10; +#X obj 35 25 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 +-1 -1 3800 1; +#X obj 129 76 commun /volume \$0; +#X obj 127 131 originator /mypatch \$0; +#X obj 21 174 careGUI; +#X connect 0 0 1 0; +#X connect 1 0 0 0; diff --git a/doc/communslider.png b/doc/communslider.png new file mode 100644 index 0000000..9cffa9d Binary files /dev/null and b/doc/communslider.png differ diff --git a/doc/default.css b/doc/default.css new file mode 100644 index 0000000..024a382 --- /dev/null +++ b/doc/default.css @@ -0,0 +1,328 @@ + +HTML { + background: #ffffff; + color: #000; + font-family: Verdana, Helvetica, Arial, Tahoma, sans-serif; + font-size: 8pt; +} + +BODY{ + padding: 5px; + font-family: Verdana, Helvetica, Arial, Tahoma, sans-serif; + font-size: 8pt; +} + +.footer { + background:#EEEEEE; + width: 650px; +} + +.bordered { + padding: 5px; +} + + +H1 { + color: #600; + border: solid 1px; + font-family: monospace; + padding: 5px; + background:#EEEEEE; +} + +H2 { + font-family: Courier, monospace; + border: solid 1px; + color: #000; + padding: 4px; +} + +H3 { + font-family: Courier, monospace; + border: solid 1px; + color: #000; + padding: 4px; +} + +pre { + color: #333333; + padding: 3px; + background:#EEEEEE; +} + +A { + text-decoration: none; +/* background: #FFFFFF; */ + color: #b00; +} + +A:hover { + text-decoration: underline; + /* background: #FFFFFF; */ + color: #003300 ; +} + +A.nonexistent { + background: #EEE; + color: #CC6600; +} + + + + +HR { + height:1px; + width: 75%; + /* background:#eeaa00; */ + background:#eee; + color:#000; +} + +P.small { + font-size: xx-small; + background:#fff; + text-align: right; + /*border: dotted 1px;*/ + padding: 5px; +} + +UL { + list-style-type: circle; +} + +#Content>p {margin:0px;} +#Content>p+p {text-indent:30px;} + +#Content { + margin:0px 50px 50px 160px; + padding:10px; + } +div.document>p {margin:0px;} +div.document>p+p {text-indent:30px;} + +div.document { + margin:0px 50px 50px 160px; + padding:10px; + } + +#Menu { + position:absolute; + top:120px; + left:10px; + width:150px; + padding:10px; + line-height:17px; +/* Again, the ugly brilliant hack. */ + voice-family: "\"}\""; + voice-family:inherit; + width:140px; + } +/* Again, "be nice to Opera 5". */ +body>#Menu {width:140px;} + +div."contents topic" { + position:absolute; + top:120px; + left:10px; + width:150px; + padding:10px; + line-height:17px; +/* Again, the ugly brilliant hack. */ + voice-family: "\"}\""; + voice-family:inherit; + width:140px; + } +/* Again, "be nice to Opera 5". */ +body>#"contents topic" {width:140px;} + + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date: 2004-04-23 16:25:52 $ +:version: $Revision: 1.1.1.1 $ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ + +.first { + margin-top: 0 } + +.last { + margin-bottom: 0 } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.line-block { + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option-argument { + font-style: italic } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +th.docinfo-name, th.field-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + font-size: 100% } + +tt { + background-color: #eeeeee } +tt.literal { + border: solid 1px; +} +ul.auto-toc { + list-style-type: none } diff --git a/doc/memento.png b/doc/memento.png new file mode 100644 index 0000000..4e38a42 Binary files /dev/null and b/doc/memento.png differ diff --git a/doc/moresliders.pd b/doc/moresliders.pd new file mode 100644 index 0000000..4eae09c --- /dev/null +++ b/doc/moresliders.pd @@ -0,0 +1,13 @@ +#N canvas 186 212 371 285 10; +#X obj 35 25 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 +-1 -1 3800 1; +#X obj 62 108 commun /volume \$0; +#X obj 63 142 originator /mypatch \$0; +#X obj 21 174 careGUI; +#X obj 108 64 hsl 128 15 0 127 0 0 empty empty empty -2 -6 0 8 -262144 +-1 -1 0 1; +#X obj 140 35 commun /pan \$0; +#X connect 0 0 1 0; +#X connect 1 0 0 0; +#X connect 4 0 5 0; +#X connect 5 0 4 0; diff --git a/doc/moresliders.png b/doc/moresliders.png new file mode 100644 index 0000000..f824b21 Binary files /dev/null and b/doc/moresliders.png differ diff --git a/doc/osccontrol.pd b/doc/osccontrol.pd new file mode 100644 index 0000000..fc25ee7 --- /dev/null +++ b/doc/osccontrol.pd @@ -0,0 +1,27 @@ +#N canvas 100 217 609 319 10; +#X obj 35 25 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 +-1 -1 8000 1; +#X obj 62 108 commun /volume \$0; +#X obj 220 145 originator /mypatch \$0; +#X obj 21 174 careGUI; +#X obj 108 64 hsl 128 15 0 127 0 0 empty empty empty -2 -6 0 8 -262144 +-1 -1 6400 1; +#X obj 140 35 commun /pan \$0; +#X floatatom 220 98 5 0 0 1 substate_selector - -; +#X msg 220 121 setsub \$1; +#X msg 411 59 /mypatch/volume \$1; +#X floatatom 411 30 5 0 0 2 set_volume_by_OSC_message - -; +#X floatatom 413 105 5 0 0 2 set_pan_by_OSC_message - -; +#X msg 413 134 /mypatch/pan \$1; +#X obj 369 181 print OSC; +#X connect 0 0 1 0; +#X connect 1 0 0 0; +#X connect 2 2 12 0; +#X connect 4 0 5 0; +#X connect 5 0 4 0; +#X connect 6 0 7 0; +#X connect 7 0 2 0; +#X connect 8 0 2 1; +#X connect 9 0 8 0; +#X connect 10 0 11 0; +#X connect 11 0 2 1; diff --git a/doc/osccontrol.png b/doc/osccontrol.png new file mode 100644 index 0000000..bd68a48 Binary files /dev/null and b/doc/osccontrol.png differ diff --git a/doc/rradicalpd.html b/doc/rradicalpd.html new file mode 100644 index 0000000..04d6a42 --- /dev/null +++ b/doc/rradicalpd.html @@ -0,0 +1,335 @@ + + + + + + +RRADical Pd + + + + +
+

RRADical Pd

+ +++ + + + +
Author:Frank Barknecht <fbar@footils.org>
+
+

Abstract

+

The goal of RRADical Pd is to create a collection of patches, that make +Pd easier and faster to use for people who are more used to commercial +software like Reason(tm) or Reaktor(tm). RRAD as an acronym stands for +"Reusable and Rapid Audio Development" or "Reusable and Rapid +Application Development", if it includes non-audio patches, with Pd. It +is spelled RRAD, but pronounced Rradical. ;)

+
+
+

What it takes to be a RRADical

+

RRAD as an acronym stands for "Reusable and Rapid Audio Development" or +"Reusable and Rapid Application Development", if it includes non-audio +patches, with Pd. It is spelled RRAD, but pronounced Rradical. ;)

+

The goal of RRADical Pd is to create a collection of patches, that make Pd +easier and faster to use for people who are more used to software like Reason(tm) +or Reaktor(tm). For that I would like to create patches, that solve real-world +problems on a higher level of abstraction than the standard Pd objects do. +Where suitable these high level abstractions should have a GUIs +built in.

+

So for example instead of a basic lop~ low pass filter something more +complete like a recreation of the Sherman filter bank could be included in +that collection. My older sseq and angriff patches followed this idea in +general, but there are much more patches needed. Like this:

+
    +
  • a sample player (adapt Gyre?)
    • +
  • Various OSC/LFO with preset waveforms
    • +
  • drum machine
    • +
  • guitar simulator
    • +
  • grain sample player
    • +
  • more sequencers
    • +
  • basically a lot of things like these things in Reason
    • +
+

Not that I want to make Pd be Reason, no way. But pre-fabricated high-level +abstractions may not only make Pd easier to use for beginners, they also +can spare lot of tedious, repeating patching work.

+
+
+

Problems and Solutions

+

To building above system several problems are to be solved. Two key areas +already targetted are:

+
+
Persistence
+
How to save the current state of a patch? How to save more than one +state (state sequencing)?
+
Communication
+
The various modules are building blocks for a larger application. How +should they talk to each other. (In Reason this is done by patching the +back or modules with horrible looking cables. We must do better.)
+
+

It turned out, that both tasks are possible to solve in a consistent way +using a unique abstraction. But first lets look a bit deeper at the +problems at hand.

+
+

Persistence

+

Pd offers no direct way to store the current state of a patch. Here's what +Pd author Miller S. Puckette writes about this in the Pd manual in section +"2.6.2. persistence of data":

+
+Among the design principles of Pd is that patches should be printable, +in the sense that the appearance of a patch should fully determine its +functionality. For this reason, if messages received by an object +change its action, since the changes aren't reflected in the object's +appearance, they are not saved as part of the file which specifies the +patch and will be forgotten when the patch is reloaded.
+

(I'll show an example of a float object changing "state" by a message in +its right inlet here.)

+

Still, in a musician's practice some kind of persistence turns out to be an +important feature, that many Pd beginners do miss. So there are several +approaches to add it. Max/MSP has the preset-object, Pd has the +state-object which saves the current state of (some) GUI objects inside +a patch. Both also support changing between several different states.

+

Both have at least two problems: They save only the state of GUI objects, +which might not be all that a user wants to save. And they don't handle +abstractions very well, which are crucial when creating modularized +patches.

+

Another approach is to (ab)use some of the Pd objects that can persist +itself to a file, especially textfile, qlist and table, which +works better, but isn't standardized.

+

A rather new candidate for state saving is Thomas Grill's pool +external. Basically it offers something, that is standard in many +programming languages: a data structure that stores key-value-pairs. This +also is known as hash, dictonary or map. With pool those pairs also can +be stored in hierarchies and they can be saved to or loaded from disk. The +last but maybe most important feature for us is, that several pools can be +shared by giving them the same name. A pool MYPOOL in one patch will +contain the same data as a pool MYPOOL in another patch. Changes to one +pool will change the data in the other as well.

+

A pool object is central to the persistence in RRADical patches, but it +is hidden behind an abstracted "API", if one could name it that. I'll +come back to haw this is done late.

+
+
+

Communication

+

Besides persistance it also is important to create a common path through +which the RRADical modules will talk to each other. Generally the modules +will have to use, what Pd offers them, and that is either a direct +connection through patch cords or the indirect use of the send/receive +mechanism in Pd. Patch cords are fine, but tend to clutter the interface. +Sends and receives on the other hand will have to make sure, that no name +clashes occur. A name clash is, when one target receives messages not +intended for it. A patch author has to remember all used send-names, but +this gets harder, if he uses prefabricated modules, which might use their +own senders.

+

So it is crucial, that senders in RRADical abstractions use local senders +only with as few exceptions as possible. This is achieved by prepending the +RRADical senders with the string "$0-". So you'd not use send volume, +but instead use send $0-volume. $0 makes those sends local inside their +own patch borders. This might be a bit difficult to understand to the +casual Pd user, but is a pretty standard idiom in the Pd world.

+

Still we will want to control a lot of parameters and do so not only +through the GUI Pd offers, but probably also through other ways, for +example through Midi controllers, through some kind of score on disk, +through satellite navigation receivers or whatever.

+

This creates a fundamental conflict:

+
+
We want borders
+
We want to separate our abstraction so they don't conflict with each +other.
+
We want border crossings
+
We want to have a way to reach their many internals and control them +from the outside.
+
+

The RRADical approach adheres to this in that it enforces a strict border +but drills a single hole in it: the OSC inlet. This idea is the result +of a discussion on the Pd mailing list and goes back to suggestions by +Eric Skogen and Ben Bogart. Every RRADical patch has (to have) a +rightmost inlet that accepts messages formatted according to the OSC +protocol. OSC stands for Open Sound Control and is a network transparent +system to control audio applications remotely developed at CNMAT in Berkley.

+

The nice thing about OSC is that it can control many parameters over a +single communication path. This is so, because OSC uses a URL-like scheme +to address parameters. An example would be this message:

+
+/synth/fm/volume 85
+
+

It sends the message "85" to the "volume" control of a "fm" module below a +"synth" module. OSC allows many parameters constructs like:

+
+/synth/fm/basenote              52
+/synth/virtualanalog/basenote   40
+/synth/*/playchords             m7b5 M6 7b9
+
+

This might set the base note of two synths, fm and virtualanalog and +send a chord progression to be played by both -- indicated by the wildcard +* -- afterwards.

+

The OSC-inlet of every RRADical patch is intended as the border crossing: +Everything the author of a certain patch intends to be controlled from the +outside can be controlled by OSC messages to the rightmost inlet.

+
+
+
+

Trying to remember it all: Memento

+

To realize the functionality requirements developed so far I resorted to a +so called Memento. "Memento" is a very cool movie by director +Christopher Nolan where - quoting IMDB:

+
+A man, suffering from short-term memory loss, uses notes and tattoos to +hunt down his wife's killer.
+

If you haven't already done so: Watch this movie! It's much better than +Matrix 2 and 3 and also stars Carrie-Anne "Trinity" Moss.

+

Here's a scene from "Memento":

+

memento.png

+

We see the film's main character Leonard who has a similar problem as Pd: he +cannot remember things. To deal with his persistence problem, his inability +to save data to his internal harddisk he resorts to taking a lot of photos. +These pictures act as what is called a Memento: a recording of the current +state of things.

+

In software development Mementos are quite common as well. The computer +science literature describes them in great detail. To make the best use of +a Memento science recommends an approach where certain tasks are in the +responsibility of certain independent players.

+

The Memento itself, as we have seen, is the photo, i.e. some kind of state +record. A module called the "Originator" is responsible for creating this +state and managing changes in it. In the movie, Leonard is the Originator, +he is the one taking photos of the world he is soon to forget.

+

The actual persistence, that could be the saving of a state to harddisk, +but could just as well be an upload to a webserver or a CVS check-in, is +done by someone called the "Caretaker" in the literature. A Caretaker could +be a safe, where Leonard puts his photos, or could be a person, to whom +Leonard gives his photos. In the movie Leonard also makes "hard saves" by +tattooing himself with notes he took. In that case, he is not only the +Originator of the notes, but also the Caretaker in one single person. The +Caretaker only has to take care, that those photos, the Mementos, are in a +safe place and noone fiddles around with them. Btw: In the movie some +interesting problems with Caretakers, who don't always act responsible, +occur.

+
+

Memento in Pd

+

I developed a set of abstractions, of patches for Pd, that follow this +design pattern. Memento for Pd includes a caretaker and an +originator abstraction, plus a third one called commun which is +responsible for the internal communication. commun basically is +just a thin extension of originator and should be considered part of +it. There is another patch, the careGUI which I personally use instead +of the caretaker directly, because it has a simple GUI included.

+

Here's how it looks:

+

caregui.png

+

The careGUI is very simple: select a FILE-name to save to, then +clicking SAVE you can save the current state, with RESTORE you can restore +a state previously saved. After restore, the outlet of careGUI sends a +bang message to be used as you like.

+

Internally caretaker has a named pool object using the global pool +called "RRADICAL". The same pool RRADICAL also is used inside the +originator object. This abstraction handles all access to this pool. A +user should not read or write the contents of pool RRADICAL directly. +The originator patch also handles the border crossing through OSC +messages by it's rightmost inlet. The patch accepts two mandatory +arguments: The first on is the name under which this patch is to be stored +inside the pool data. Each originator SomeName secondarg stores +it's data in a virtual subdirectory inside the RRADICAL-pool called like +its first argument - SomeName in the example. If the SomeName starts with a +slash like "/patch" , you can also accesse it via OSC through the rightmost inlet of +originator under the tree "/patch"

+

The second argument practically always will be $0. It is used to talk to +those commun objects which share the same second argument. As $0 is a +value local and unique to a patch (or to an abstraction to be correct) each +originator then only can talk to communs inside the same patch and +will not disturb other commun objects in other abstractions.

+

The commun objects finally are where the contents of a state are read +and set. They, too, accept two arguments, the second of which was +discussed before and will most of the time just be $0. The first argument +will be the key under which some value will be saved. You should use a slash +as first character here as well to allow OSC control. So an example for a +usage would be commun /vol $0.

+

commun has one inlet and one outlet. What comes in through the inlet is +send to originator who stores it inside its Memento under the key, that +is specified by the commun's first arg. Actually originator. The +outlet of a commun will spit out the current value stored under its key +inside the Memento, when originator tells it to do so. So communs +are intended to be cross-connected to some thing that can change. And +example would be a slider which can be connected as seen in the next +picture:

+

communslider.png

+

In this patch, every change to the slider will be reflected inside the +Memento. The little print button in careGUI can be used to print the +contents to the console from which Pd was started. Setting the slider will +result in something like this:

+
+/mypatch 0 , /volume , 38
+
+

Here a comma separates key and value pairs. "mypatch" is the toplevel +directory. This contains a 0, which is the default subdirectory, after that +comes the key "/volume", whose value is 38. Let's add another slider for +pan-values:

+

moresliders.png

+

Moving the /pan slider will let careGUI print out:

+
+/mypatch 0 , /volume , 38
+/mypatch 0 , /pan , 92
+
+

The originator can save several substates or presets by sending a +substate #number message to its first inlet. Let's do just this and +move the sliders again as seen in the next picture:

+

substates.png

+

Now careGUI prints:

+
+/mypatch 0 , /volume , 38
+/mypatch 0 , /pan , 92
+/mypatch 1 , /volume , 116
+/mypatch 1 , /pan , 27
+
+

You see, the substate 0 is unaffected, the new state can have different +values. Exchanging the substate message with a setsub message will +autoload the selected state and "set" the sliders to the stored values +immediatly.

+
+
+

OSC in Memento

+

The whole system now already is prepared to be used over OSC. You probably +already guess, how the message looks like. Any takers? Thank you, you're +right, the messages are built as /mypatch/volume #number and +/mypatch/pan #number as shown in the next stage:

+

osccontrol.png

+

Sometimes it is useful to also get OSC messages out of a patch, for example +to control other OSC software through Pd. For this the OSC-outlet of +originator can be used, which is the rightmost outlet of the +abstraction. It will print out every change to the current state. +Connecting a print OSC debug object to it, we get to see what's coming +out of the OSC-outlet when we move a slider:

+
+OSC: /mypatch/pan 92
+OSC: /mypatch/pan 91
+OSC: /mypatch/pan 90
+OSC: /mypatch/pan 89
+
+
+
+
+

Putting it all to RRADical use

+

Now that the foundation for a general preset and communication system are +set, it is possible to build real patches with it that have two main +characteristics:

+
+
Rapidity
+
Ready-to-use highlevel abstraction can save a lot of time when building +larger patches. Clear communication paths will let you think faster and +more about the really important things.
+
Reusability
+
Don't reinvent the wheel all the time. Reuse patches like instruments +for more than one piece by just exchanging the Caretaker-file used.
+
+

I already developed a growing number of patches that follow the RRADical +paradigm, among these are a complex pattern sequencer, some synths and +effects and more. The RRADical collection comes with a template file, +called rrad.tpl that makes deploying new RRADical patches easier and +lets developers concentrate on the algorighm instead of bookeeping. Some +utils (footils?) help with creating the sometimes needed many +commun-objects. Several usecases show example applications of the +provided abstractions.

+
+
+ + diff --git a/doc/rradicalpd.pdf b/doc/rradicalpd.pdf new file mode 100644 index 0000000..9820474 Binary files /dev/null and b/doc/rradicalpd.pdf differ diff --git a/doc/rradicalpd.png b/doc/rradicalpd.png new file mode 100644 index 0000000..bc752a9 Binary files /dev/null and b/doc/rradicalpd.png differ diff --git a/doc/rradicalpd.rst b/doc/rradicalpd.rst new file mode 100644 index 0000000..9d77090 --- /dev/null +++ b/doc/rradicalpd.rst @@ -0,0 +1,366 @@ +RRADical Pd +============ + + +:Authors: + Frank Barknecht +:Abstract: + The goal of RRADical Pd is to create a collection of patches, that make + Pd easier and faster to use for people who are more used to commercial + software like Reason(tm) or Reaktor(tm). RRAD as an acronym stands for + "Reusable and Rapid Audio Development" or "Reusable and Rapid + Application Development", if it includes non-audio patches, with Pd. It + is spelled RRAD, but pronounced Rradical. ;) + +What it takes to be a RRADical +------------------------------ + +RRAD as an acronym stands for "Reusable and Rapid Audio Development" or +"Reusable and Rapid Application Development", if it includes non-audio +patches, with Pd. It is spelled RRAD, but pronounced Rradical. ;) + +The goal of RRADical Pd is to create a collection of patches, that make Pd +easier and faster to use for people who are more used to software like Reason(tm) +or Reaktor(tm). For that I would like to create patches, that solve real-world +problems on a higher level of abstraction than the standard Pd objects do. +Where suitable these high level abstractions should have a GUIs +built in. + +So for example instead of a basic ``lop~`` low pass filter something more +complete like a recreation of the Sherman filter bank could be included in +that collection. My older sseq and angriff patches followed this idea in +general, but there are much more patches needed. Like this: + +* a sample player (adapt Gyre?) +* Various OSC/LFO with preset waveforms +* drum machine +* guitar simulator +* grain sample player +* more sequencers +* basically a lot of things like these things in Reason + +Not that I want to make Pd be Reason, no way. But pre-fabricated high-level +abstractions may not only make Pd easier to use for beginners, they also +can spare lot of tedious, repeating patching work. + +Problems and Solutions +---------------------- + +To building above system several problems are to be solved. Two key areas +already targetted are: + +**Persistence** + How to save the current state of a patch? How to save more than one + state (state sequencing)? + +**Communication** + The various modules are building blocks for a larger application. How + should they talk to each other. (In Reason this is done by patching the + back or modules with horrible looking cables. We must do better.) + +It turned out, that both tasks are possible to solve in a consistent way +using a unique abstraction. But first lets look a bit deeper at the +problems at hand. + +Persistence +............ + +Pd offers no direct way to store the current state of a patch. Here's what +Pd author Miller S. Puckette writes about this in the Pd manual in section +"2.6.2. persistence of data": + + Among the design principles of Pd is that patches should be printable, + in the sense that the appearance of a patch should fully determine its + functionality. For this reason, if messages received by an object + change its action, since the changes aren't reflected in the object's + appearance, they are not saved as part of the file which specifies the + patch and will be forgotten when the patch is reloaded. + +(I'll show an example of a float object changing "state" by a message in +its right inlet here.) + +Still, in a musician's practice some kind of persistence turns out to be an +important feature, that many Pd beginners do miss. So there are several +approaches to add it. Max/MSP has the ``preset``-object, Pd has the +``state``-object which saves the current state of (some) GUI objects inside +a patch. Both also support changing between several different states. + +Both have at least two problems: They save only the state of GUI objects, +which might not be all that a user wants to save. And they don't handle +abstractions very well, which are crucial when creating modularized +patches. + +Another approach is to (ab)use some of the Pd objects that can persist +itself to a file, especially ``textfile``, ``qlist`` and ``table``, which +works better, but isn't standardized. + +A rather new candidate for state saving is Thomas Grill's ``pool`` +external. Basically it offers something, that is standard in many +programming languages: a data structure that stores key-value-pairs. This +also is known as hash, dictonary or map. With ``pool`` those pairs also can +be stored in hierarchies and they can be saved to or loaded from disk. The +last but maybe most important feature for us is, that several pools can be +shared by giving them the same name. A ``pool MYPOOL`` in one patch will +contain the same data as a ``pool MYPOOL`` in another patch. Changes to one +pool will change the data in the other as well. + +A ``pool`` object is central to the persistence in RRADical patches, but it +is hidden behind an abstracted "API", if one could name it that. I'll +come back to haw this is done late. + +Communication +............. + +Besides persistance it also is important to create a common path through +which the RRADical modules will talk to each other. Generally the modules +will have to use, what Pd offers them, and that is either a direct +connection through patch cords or the indirect use of the send/receive +mechanism in Pd. Patch cords are fine, but tend to clutter the interface. +Sends and receives on the other hand will have to make sure, that no name +clashes occur. A name clash is, when one target receives messages not +intended for it. A patch author has to remember all used send-names, but +this gets harder, if he uses prefabricated modules, which might use their +own senders. + +So it is crucial, that senders in RRADical abstractions use local senders +only with as few exceptions as possible. This is achieved by prepending the +RRADical senders with the string "$0-". So you'd not use ``send volume``, +but instead use ``send $0-volume``. $0 makes those sends local inside their +own patch borders. This might be a bit difficult to understand to the +casual Pd user, but is a pretty standard idiom in the Pd world. + +Still we will want to control a lot of parameters and do so not only +through the GUI Pd offers, but probably also through other ways, for +example through Midi controllers, through some kind of score on disk, +through satellite navigation receivers or whatever. + +This creates a fundamental conflict: + +**We want borders** + We want to separate our abstraction so they don't conflict with each + other. +**We want border crossings** + We want to have a way to reach their many internals and control them + from the outside. + +The RRADical approach adheres to this in that it enforces a strict border +but drills a single hole in it: the **OSC inlet**. This idea is the result +of a discussion on the Pd mailing list and goes back to suggestions by +`Eric Skogen`_ and `Ben Bogart`_. Every RRADical patch has (to have) a +rightmost inlet that accepts messages formatted according to the OSC +protocol. OSC stands for `Open Sound Control`_ and is a network transparent +system to control audio applications remotely developed at CNMAT in Berkley. + +.. _`Eric Skogen`: http://www.audionerd.com +.. _`Ben Bogart`: http://www.ekran.org/ben/ +.. _`Open Sound Control`: http://www.cnmat.berkeley.edu/OpenSoundControl/ + +The nice thing about OSC is that it can control many parameters over a +single communication path. This is so, because OSC uses a URL-like scheme +to address parameters. An example would be this message:: + + /synth/fm/volume 85 + +It sends the message "85" to the "volume" control of a "fm" module below a +"synth" module. OSC allows many parameters constructs like:: + + /synth/fm/basenote 52 + /synth/virtualanalog/basenote 40 + /synth/*/playchords m7b5 M6 7b9 + +This might set the base note of two synths, `fm` and `virtualanalog` and +send a chord progression to be played by both -- indicated by the wildcard +`*` -- afterwards. + +The OSC-inlet of every RRADical patch is intended as the border crossing: +Everything the author of a certain patch intends to be controlled from the +outside can be controlled by OSC messages to the rightmost inlet. + + +Trying to remember it all: Memento +------------------------------------- + +To realize the functionality requirements developed so far I resorted to a +so called `Memento`. `"Memento"` is a very cool movie by director +Christopher Nolan where - quoting IMDB: + + A man, suffering from short-term memory loss, uses notes and tattoos to + hunt down his wife's killer. + +If you haven't already done so: Watch this movie! It's much better than +Matrix 2 and 3 and also stars Carrie-Anne "Trinity" Moss. + +Here's a scene from "Memento": + +.. image:: memento.png + +We see the film's main character Leonard who has a similar problem as Pd: he +cannot remember things. To deal with his persistence problem, his inability +to save data to his internal harddisk he resorts to taking a lot of photos. +These pictures act as what is called a Memento: a recording of the current +state of things. + +In software development Mementos are quite common as well. The computer +science literature describes them in great detail. To make the best use of +a Memento science recommends an approach where certain tasks are in the +responsibility of certain independent players. + +The Memento itself, as we have seen, is the photo, i.e. some kind of state +record. A module called the "Originator" is responsible for creating this +state and managing changes in it. In the movie, Leonard is the Originator, +he is the one taking photos of the world he is soon to forget. + +The actual persistence, that could be the saving of a state to harddisk, +but could just as well be an upload to a webserver or a CVS check-in, is +done by someone called the "Caretaker" in the literature. A Caretaker could +be a safe, where Leonard puts his photos, or could be a person, to whom +Leonard gives his photos. In the movie Leonard also makes "hard saves" by +tattooing himself with notes he took. In that case, he is not only the +Originator of the notes, but also the Caretaker in one single person. The +Caretaker only has to take care, that those photos, the Mementos, are in a +safe place and noone fiddles around with them. Btw: In the movie some +interesting problems with Caretakers, who don't always act responsible, +occur. + +Memento in Pd +............. + +I developed a set of abstractions, of patches for Pd, that follow this +design pattern. Memento for Pd includes a ``caretaker`` and an +``originator`` abstraction, plus a third one called ``commun`` which is +responsible for the **internal** communication. ``commun`` basically is +just a thin extension of ``originator`` and should be considered part of +it. There is another patch, the ``careGUI`` which I personally use instead +of the ``caretaker`` directly, because it has a simple GUI included. + +Here's how it looks: + +.. image:: caregui.png + +The ``careGUI`` is very simple: select a FILE-name to save to, then +clicking SAVE you can save the current state, with RESTORE you can restore +a state previously saved. After restore, the outlet of ``careGUI`` sends a +``bang`` message to be used as you like. + +Internally ``caretaker`` has a named ``pool`` object using the global pool +called "RRADICAL". The same ``pool RRADICAL`` also is used inside the +``originator`` object. This abstraction handles all access to this pool. A +user should not read or write the contents of ``pool RRADICAL`` directly. +The ``originator`` patch also handles the border crossing through OSC +messages by it's rightmost inlet. The patch accepts two mandatory +arguments: The first on is the name under which this patch is to be stored +inside the ``pool`` data. Each ``originator SomeName secondarg`` stores +it's data in a virtual subdirectory inside the RRADICAL-pool called like +its first argument - SomeName in the example. If the SomeName starts with a +slash like "/patch" , you can also accesse it via OSC through the rightmost inlet of +``originator`` under the tree "/patch" + +The second argument practically always will be $0. It is used to talk to +those ``commun`` objects which share the same second argument. As $0 is a +value local and unique to a patch (or to an abstraction to be correct) each +``originator`` then only can talk to ``commun``\s inside the same patch and +will not disturb other ``commun`` objects in other abstractions. + +The ``commun`` objects finally are where the contents of a state are read +and set. They, too, accept two arguments, the second of which was +discussed before and will most of the time just be $0. The first argument +will be the key under which some value will be saved. You should use a slash +as first character here as well to allow OSC control. So an example for a +usage would be ``commun /vol $0``. + +``commun`` has one inlet and one outlet. What comes in through the inlet is +send to ``originator`` who stores it inside its Memento under the key, that +is specified by the ``commun``'s first arg. Actually ``originator``. The +outlet of a ``commun`` will spit out the current value stored under its key +inside the Memento, when ``originator`` tells it to do so. So ``commun``\s +are intended to be cross-connected to some thing that can change. And +example would be a slider which can be connected as seen in the next +picture: + +.. image:: communslider.png + +In this patch, every change to the slider will be reflected inside the +Memento. The little print button in ``careGUI`` can be used to print the +contents to the console from which Pd was started. Setting the slider will +result in something like this:: + + /mypatch 0 , /volume , 38 + +Here a comma separates key and value pairs. "mypatch" is the toplevel +directory. This contains a 0, which is the default subdirectory, after that +comes the key "/volume", whose value is 38. Let's add another slider for +pan-values: + +.. image:: moresliders.png + +Moving the /pan slider will let careGUI print out:: + + /mypatch 0 , /volume , 38 + /mypatch 0 , /pan , 92 + +The ``originator`` can save several substates or presets by sending a +``substate #number`` message to its first inlet. Let's do just this and +move the sliders again as seen in the next picture: + +.. image:: substates.png + +Now careGUI prints:: + + /mypatch 0 , /volume , 38 + /mypatch 0 , /pan , 92 + /mypatch 1 , /volume , 116 + /mypatch 1 , /pan , 27 + +You see, the substate 0 is unaffected, the new state can have different +values. Exchanging the ``substate`` message with a ``setsub`` message will +autoload the selected state and "set" the sliders to the stored values +immediatly. + +OSC in Memento +............... + +The whole system now already is prepared to be used over OSC. You probably +already guess, how the message looks like. Any takers? Thank you, you're +right, the messages are built as ``/mypatch/volume #number`` and +``/mypatch/pan #number`` as shown in the next stage: + +.. image:: osccontrol.png + +Sometimes it is useful to also get OSC messages out of a patch, for example +to control other OSC software through Pd. For this the **OSC-outlet** of +``originator`` can be used, which is the rightmost outlet of the +abstraction. It will print out every change to the current state. +Connecting a ``print OSC`` debug object to it, we get to see what's coming +out of the OSC-outlet when we move a slider:: + + OSC: /mypatch/pan 92 + OSC: /mypatch/pan 91 + OSC: /mypatch/pan 90 + OSC: /mypatch/pan 89 + +Putting it all to RRADical use +--------------------------------- + +Now that the foundation for a general preset and communication system are +set, it is possible to build real patches with it that have two main +characteristics: + +**Rapidity** + Ready-to-use highlevel abstraction can save a lot of time when building + larger patches. Clear communication paths will let you think faster and + more about the really important things. + +**Reusability** + Don't reinvent the wheel all the time. Reuse patches like instruments + for more than one piece by just exchanging the Caretaker-file used. + +I already developed a growing number of patches that follow the RRADical +paradigm, among these are a complex pattern sequencer, some synths and +effects and more. The RRADical collection comes with a template file, +called ``rrad.tpl`` that makes deploying new RRADical patches easier and +lets developers concentrate on the algorighm instead of bookeeping. Some +utils (footils?) help with creating the sometimes needed many +``commun``-objects. Several usecases show example applications of the +provided abstractions. + + diff --git a/doc/rradicalpd.tex b/doc/rradicalpd.tex new file mode 100644 index 0000000..157aace --- /dev/null +++ b/doc/rradicalpd.tex @@ -0,0 +1,511 @@ +\documentclass[10pt,english]{scrartcl} +\usepackage{babel} +\usepackage{shortvrb} +\usepackage[latin1]{inputenc} +\usepackage{tabularx} +\usepackage{longtable} +\setlength{\extrarowheight}{2pt} +\usepackage{amsmath} +\usepackage{graphicx} +\usepackage{color} +\usepackage{multirow} +\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} +\usepackage[a4paper,margin=2cm,nohead]{geometry} +%% generator Docutils: http://docutils.sourceforge.net/ +\newlength{\admonitionwidth} +\setlength{\admonitionwidth}{0.9\textwidth} +\newlength{\docinfowidth} +\setlength{\docinfowidth}{0.9\textwidth} +\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} +\newenvironment{optionlist}[1] +{\begin{list}{} + {\setlength{\labelwidth}{#1} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\optionlistlabel}} +}{\end{list}} +% begin: floats for footnotes tweaking. +\setlength{\floatsep}{0.5em} +\setlength{\textfloatsep}{\fill} +\addtolength{\textfloatsep}{3em} +\renewcommand{\textfraction}{0.5} +\renewcommand{\topfraction}{0.5} +\renewcommand{\bottomfraction}{0.5} +\setcounter{totalnumber}{50} +\setcounter{topnumber}{50} +\setcounter{bottomnumber}{50} +% end floats for footnotes +% some commands, that could be overwritten in the style file. +\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} +% end of "some commands" +\title{RRADical Pd} +\author{} +\date{} +\hypersetup{ +pdftitle={RRADical Pd}, +pdfauthor={Frank Barknecht {$<$}fbar@footils.org{$>$}} +} +\raggedbottom +\begin{document} +\maketitle + +%___________________________________________________________________________ +\begin{center} +\begin{tabularx}{\docinfowidth}{lX} +\textbf{Author}: & + Frank Barknecht {$<$}fbar@footils.org{$>$} \\ +\end{tabularx} +\end{center} +\subsection*{~\hfill Abstract\hfill ~} + +The goal of RRADical Pd is to create a collection of patches, that make +Pd easier and faster to use for people who are more used to commercial +software like Reason(tm) or Reaktor(tm). RRAD as an acronym stands for +``Reusable and Rapid Audio Development'' or ``Reusable and Rapid +Application Development'', if it includes non-audio patches, with Pd. It +is spelled RRAD, but pronounced Rradical. ;) + + + +%___________________________________________________________________________ + +\hypertarget{what-it-takes-to-be-a-rradical}{} +\section*{What it takes to be a RRADical} +\pdfbookmark[0]{What it takes to be a RRADical}{what-it-takes-to-be-a-rradical} + +RRAD as an acronym stands for ``Reusable and Rapid Audio Development'' or +``Reusable and Rapid Application Development'', if it includes non-audio +patches, with Pd. It is spelled RRAD, but pronounced Rradical. ;) + +The goal of RRADical Pd is to create a collection of patches, that make Pd +easier and faster to use for people who are more used to software like Reason(tm) +or Reaktor(tm). For that I would like to create patches, that solve real-world +problems on a higher level of abstraction than the standard Pd objects do. +Where suitable these high level abstractions should have a GUIs +built in. + +So for example instead of a basic \texttt{lop{\~{ }}} low pass filter something more +complete like a recreation of the Sherman filter bank could be included in +that collection. My older sseq and angriff patches followed this idea in +general, but there are much more patches needed. Like this: +\begin{itemize} +\item +a sample player (adapt Gyre?) + +\item +Various OSC/LFO with preset waveforms + +\item +drum machine + +\item +guitar simulator + +\item +grain sample player + +\item +more sequencers + +\item +basically a lot of things like these things in Reason + +\end{itemize} + +Not that I want to make Pd be Reason, no way. But pre-fabricated high-level +abstractions may not only make Pd easier to use for beginners, they also +can spare lot of tedious, repeating patching work. + + +%___________________________________________________________________________ + +\hypertarget{problems-and-solutions}{} +\section*{Problems and Solutions} +\pdfbookmark[0]{Problems and Solutions}{problems-and-solutions} + +To building above system several problems are to be solved. Two key areas +already targetted are: +\begin{description} +%[visit_definition_list_item] +\item[\textbf{Persistence}] +%[visit_definition] + +How to save the current state of a patch? How to save more than one +state (state sequencing)? + +%[depart_definition] +%[depart_definition_list_item] +%[visit_definition_list_item] +\item[\textbf{Communication}] +%[visit_definition] + +The various modules are building blocks for a larger application. How +should they talk to each other. (In Reason this is done by patching the +back or modules with horrible looking cables. We must do better.) + +%[depart_definition] +%[depart_definition_list_item] +\end{description} + +It turned out, that both tasks are possible to solve in a consistent way +using a unique abstraction. But first lets look a bit deeper at the +problems at hand. + + +%___________________________________________________________________________ + +\hypertarget{persistence}{} +\subsection*{Persistence} +\pdfbookmark[1]{Persistence}{persistence} + +Pd offers no direct way to store the current state of a patch. Here's what +Pd author Miller S. Puckette writes about this in the Pd manual in section +``2.6.2. persistence of data'': +\begin{quote} + +Among the design principles of Pd is that patches should be printable, +in the sense that the appearance of a patch should fully determine its +functionality. For this reason, if messages received by an object +change its action, since the changes aren't reflected in the object's +appearance, they are not saved as part of the file which specifies the +patch and will be forgotten when the patch is reloaded. +\end{quote} + +(I'll show an example of a float object changing ``state'' by a message in +its right inlet here.) + +Still, in a musician's practice some kind of persistence turns out to be an +important feature, that many Pd beginners do miss. So there are several +approaches to add it. Max/MSP has the \texttt{preset}-object, Pd has the +\texttt{state}-object which saves the current state of (some) GUI objects inside +a patch. Both also support changing between several different states. + +Both have at least two problems: They save only the state of GUI objects, +which might not be all that a user wants to save. And they don't handle +abstractions very well, which are crucial when creating modularized +patches. + +Another approach is to (ab)use some of the Pd objects that can persist +itself to a file, especially \texttt{textfile}, \texttt{qlist} and \texttt{table}, which +works better, but isn't standardized. + +A rather new candidate for state saving is Thomas Grill's \texttt{pool} +external. Basically it offers something, that is standard in many +programming languages: a data structure that stores key-value-pairs. This +also is known as hash, dictonary or map. With \texttt{pool} those pairs also can +be stored in hierarchies and they can be saved to or loaded from disk. The +last but maybe most important feature for us is, that several pools can be +shared by giving them the same name. A \texttt{pool MYPOOL} in one patch will +contain the same data as a \texttt{pool MYPOOL} in another patch. Changes to one +pool will change the data in the other as well. + +A \texttt{pool} object is central to the persistence in RRADical patches, but it +is hidden behind an abstracted ``API'', if one could name it that. I'll +come back to haw this is done late. + + +%___________________________________________________________________________ + +\hypertarget{communication}{} +\subsection*{Communication} +\pdfbookmark[1]{Communication}{communication} + +Besides persistance it also is important to create a common path through +which the RRADical modules will talk to each other. Generally the modules +will have to use, what Pd offers them, and that is either a direct +connection through patch cords or the indirect use of the send/receive +mechanism in Pd. Patch cords are fine, but tend to clutter the interface. +Sends and receives on the other hand will have to make sure, that no name +clashes occur. A name clash is, when one target receives messages not +intended for it. A patch author has to remember all used send-names, but +this gets harder, if he uses prefabricated modules, which might use their +own senders. + +So it is crucial, that senders in RRADical abstractions use local senders +only with as few exceptions as possible. This is achieved by prepending the +RRADical senders with the string ``{\$}0-''. So you'd not use \texttt{send volume}, +but instead use \texttt{send {\$}0-volume}. {\$}0 makes those sends local inside their +own patch borders. This might be a bit difficult to understand to the +casual Pd user, but is a pretty standard idiom in the Pd world. + +Still we will want to control a lot of parameters and do so not only +through the GUI Pd offers, but probably also through other ways, for +example through Midi controllers, through some kind of score on disk, +through satellite navigation receivers or whatever. + +This creates a fundamental conflict: +\begin{description} +%[visit_definition_list_item] +\item[\textbf{We want borders} ] +%[visit_definition] + +We want to separate our abstraction so they don't conflict with each +other. + +%[depart_definition] +%[depart_definition_list_item] +%[visit_definition_list_item] +\item[\textbf{We want border crossings}] +%[visit_definition] + +We want to have a way to reach their many internals and control them +from the outside. + +%[depart_definition] +%[depart_definition_list_item] +\end{description} + +The RRADical approach adheres to this in that it enforces a strict border +but drills a single hole in it: the \textbf{OSC inlet}. This idea is the result +of a discussion on the Pd mailing list and goes back to suggestions by +\href{http://www.audionerd.com}{Eric Skogen} and \href{http://www.ekran.org/ben/}{Ben Bogart}. Every RRADical patch has (to have) a +rightmost inlet that accepts messages formatted according to the OSC +protocol. OSC stands for \href{http://www.cnmat.berkeley.edu/OpenSoundControl/}{Open Sound Control} and is a network transparent +system to control audio applications remotely developed at CNMAT in Berkley. + +The nice thing about OSC is that it can control many parameters over a +single communication path. This is so, because OSC uses a URL-like scheme +to address parameters. An example would be this message: +\begin{ttfamily}\begin{flushleft} +\mbox{/synth/fm/volume~85} +\end{flushleft}\end{ttfamily} + +It sends the message ``85'' to the ``volume'' control of a ``fm'' module below a +``synth'' module. OSC allows many parameters constructs like: +\begin{ttfamily}\begin{flushleft} +\mbox{/synth/fm/basenote~~~~~~~~~~~~~~52}\\ +\mbox{/synth/virtualanalog/basenote~~~40}\\ +\mbox{/synth/*/playchords~~~~~~~~~~~~~m7b5~M6~7b9} +\end{flushleft}\end{ttfamily} + +This might set the base note of two synths, fm and virtualanalog and +send a chord progression to be played by both -- indicated by the wildcard +* -- afterwards. + +The OSC-inlet of every RRADical patch is intended as the border crossing: +Everything the author of a certain patch intends to be controlled from the +outside can be controlled by OSC messages to the rightmost inlet. + + +%___________________________________________________________________________ + +\hypertarget{trying-to-remember-it-all-memento}{} +\section*{Trying to remember it all: Memento} +\pdfbookmark[0]{Trying to remember it all: Memento}{trying-to-remember-it-all-memento} + +To realize the functionality requirements developed so far I resorted to a +so called Memento. ``Memento'' is a very cool movie by director +Christopher Nolan where - quoting IMDB: +\begin{quote} + +A man, suffering from short-term memory loss, uses notes and tattoos to +hunt down his wife's killer. +\end{quote} + +If you haven't already done so: Watch this movie! It's much better than +Matrix 2 and 3 and also stars Carrie-Anne ``Trinity'' Moss. + +Here's a scene from ``Memento'': + +\includegraphics{memento.png} + +We see the film's main character Leonard who has a similar problem as Pd: he +cannot remember things. To deal with his persistence problem, his inability +to save data to his internal harddisk he resorts to taking a lot of photos. +These pictures act as what is called a Memento: a recording of the current +state of things. + +In software development Mementos are quite common as well. The computer +science literature describes them in great detail. To make the best use of +a Memento science recommends an approach where certain tasks are in the +responsibility of certain independent players. + +The Memento itself, as we have seen, is the photo, i.e. some kind of state +record. A module called the ``Originator'' is responsible for creating this +state and managing changes in it. In the movie, Leonard is the Originator, +he is the one taking photos of the world he is soon to forget. + +The actual persistence, that could be the saving of a state to harddisk, +but could just as well be an upload to a webserver or a CVS check-in, is +done by someone called the ``Caretaker'' in the literature. A Caretaker could +be a safe, where Leonard puts his photos, or could be a person, to whom +Leonard gives his photos. In the movie Leonard also makes ``hard saves'' by +tattooing himself with notes he took. In that case, he is not only the +Originator of the notes, but also the Caretaker in one single person. The +Caretaker only has to take care, that those photos, the Mementos, are in a +safe place and noone fiddles around with them. Btw: In the movie some +interesting problems with Caretakers, who don't always act responsible, +occur. + + +%___________________________________________________________________________ + +\hypertarget{memento-in-pd}{} +\subsection*{Memento in Pd} +\pdfbookmark[1]{Memento in Pd}{memento-in-pd} + +I developed a set of abstractions, of patches for Pd, that follow this +design pattern. Memento for Pd includes a \texttt{caretaker} and an +\texttt{originator} abstraction, plus a third one called \texttt{commun} which is +responsible for the \textbf{internal} communication. \texttt{commun} basically is +just a thin extension of \texttt{originator} and should be considered part of +it. There is another patch, the \texttt{careGUI} which I personally use instead +of the \texttt{caretaker} directly, because it has a simple GUI included. + +Here's how it looks: + +\includegraphics{caregui.png} + +The \texttt{careGUI} is very simple: select a FILE-name to save to, then +clicking SAVE you can save the current state, with RESTORE you can restore +a state previously saved. After restore, the outlet of \texttt{careGUI} sends a +\texttt{bang} message to be used as you like. + +Internally \texttt{caretaker} has a named \texttt{pool} object using the global pool +called ``RRADICAL''. The same \texttt{pool RRADICAL} also is used inside the +\texttt{originator} object. This abstraction handles all access to this pool. A +user should not read or write the contents of \texttt{pool RRADICAL} directly. +The \texttt{originator} patch also handles the border crossing through OSC +messages by it's rightmost inlet. The patch accepts two mandatory +arguments: The first on is the name under which this patch is to be stored +inside the \texttt{pool} data. Each \texttt{originator SomeName secondarg} stores +it's data in a virtual subdirectory inside the RRADICAL-pool called like +its first argument - SomeName in the example. If the SomeName starts with a +slash like ``/patch'' , you can also accesse it via OSC through the rightmost inlet of +\texttt{originator} under the tree ``/patch'' + +The second argument practically always will be {\$}0. It is used to talk to +those \texttt{commun} objects which share the same second argument. As {\$}0 is a +value local and unique to a patch (or to an abstraction to be correct) each +\texttt{originator} then only can talk to \texttt{commun}s inside the same patch and +will not disturb other \texttt{commun} objects in other abstractions. + +The \texttt{commun} objects finally are where the contents of a state are read +and set. They, too, accept two arguments, the second of which was +discussed before and will most of the time just be {\$}0. The first argument +will be the key under which some value will be saved. You should use a slash +as first character here as well to allow OSC control. So an example for a +usage would be \texttt{commun /vol {\$}0}. + +\texttt{commun} has one inlet and one outlet. What comes in through the inlet is +send to \texttt{originator} who stores it inside its Memento under the key, that +is specified by the \texttt{commun}'s first arg. Actually \texttt{originator}. The +outlet of a \texttt{commun} will spit out the current value stored under its key +inside the Memento, when \texttt{originator} tells it to do so. So \texttt{commun}s +are intended to be cross-connected to some thing that can change. And +example would be a slider which can be connected as seen in the next +picture: + +\includegraphics{communslider.png} + +In this patch, every change to the slider will be reflected inside the +Memento. The little print button in \texttt{careGUI} can be used to print the +contents to the console from which Pd was started. Setting the slider will +result in something like this: +\begin{ttfamily}\begin{flushleft} +\mbox{/mypatch~0~,~/volume~,~38} +\end{flushleft}\end{ttfamily} + +Here a comma separates key and value pairs. ``mypatch'' is the toplevel +directory. This contains a 0, which is the default subdirectory, after that +comes the key ``/volume'', whose value is 38. Let's add another slider for +pan-values: + +\includegraphics{moresliders.png} + +Moving the /pan slider will let careGUI print out: +\begin{ttfamily}\begin{flushleft} +\mbox{/mypatch~0~,~/volume~,~38}\\ +\mbox{/mypatch~0~,~/pan~,~92} +\end{flushleft}\end{ttfamily} + +The \texttt{originator} can save several substates or presets by sending a +\texttt{substate {\#}number} message to its first inlet. Let's do just this and +move the sliders again as seen in the next picture: + +\includegraphics{substates.png} + +Now careGUI prints: +\begin{ttfamily}\begin{flushleft} +\mbox{/mypatch~0~,~/volume~,~38}\\ +\mbox{/mypatch~0~,~/pan~,~92}\\ +\mbox{/mypatch~1~,~/volume~,~116}\\ +\mbox{/mypatch~1~,~/pan~,~27} +\end{flushleft}\end{ttfamily} + +You see, the substate 0 is unaffected, the new state can have different +values. Exchanging the \texttt{substate} message with a \texttt{setsub} message will +autoload the selected state and ``set'' the sliders to the stored values +immediatly. + + +%___________________________________________________________________________ + +\hypertarget{osc-in-memento}{} +\subsection*{OSC in Memento} +\pdfbookmark[1]{OSC in Memento}{osc-in-memento} + +The whole system now already is prepared to be used over OSC. You probably +already guess, how the message looks like. Any takers? Thank you, you're +right, the messages are built as \texttt{/mypatch/volume {\#}number} and +\texttt{/mypatch/pan {\#}number} as shown in the next stage: + +\includegraphics{osccontrol.png} + +Sometimes it is useful to also get OSC messages out of a patch, for example +to control other OSC software through Pd. For this the \textbf{OSC-outlet} of +\texttt{originator} can be used, which is the rightmost outlet of the +abstraction. It will print out every change to the current state. +Connecting a \texttt{print OSC} debug object to it, we get to see what's coming +out of the OSC-outlet when we move a slider: +\begin{ttfamily}\begin{flushleft} +\mbox{OSC:~/mypatch/pan~92}\\ +\mbox{OSC:~/mypatch/pan~91}\\ +\mbox{OSC:~/mypatch/pan~90}\\ +\mbox{OSC:~/mypatch/pan~89} +\end{flushleft}\end{ttfamily} + + +%___________________________________________________________________________ + +\hypertarget{putting-it-all-to-rradical-use}{} +\section*{Putting it all to RRADical use} +\pdfbookmark[0]{Putting it all to RRADical use}{putting-it-all-to-rradical-use} + +Now that the foundation for a general preset and communication system are +set, it is possible to build real patches with it that have two main +characteristics: +\begin{description} +%[visit_definition_list_item] +\item[\textbf{Rapidity}] +%[visit_definition] + +Ready-to-use highlevel abstraction can save a lot of time when building +larger patches. Clear communication paths will let you think faster and +more about the really important things. + +%[depart_definition] +%[depart_definition_list_item] +%[visit_definition_list_item] +\item[\textbf{Reusability}] +%[visit_definition] + +Don't reinvent the wheel all the time. Reuse patches like instruments +for more than one piece by just exchanging the Caretaker-file used. + +%[depart_definition] +%[depart_definition_list_item] +\end{description} + +I already developed a growing number of patches that follow the RRADical +paradigm, among these are a complex pattern sequencer, some synths and +effects and more. The RRADical collection comes with a template file, +called \texttt{rrad.tpl} that makes deploying new RRADical patches easier and +lets developers concentrate on the algorighm instead of bookeeping. Some +utils (footils?) help with creating the sometimes needed many +\texttt{commun}-objects. Several usecases show example applications of the +provided abstractions. + +\end{document} diff --git a/doc/substates.pd b/doc/substates.pd new file mode 100644 index 0000000..f194967 --- /dev/null +++ b/doc/substates.pd @@ -0,0 +1,17 @@ +#N canvas 186 212 462 290 10; +#X obj 35 25 vsl 15 128 0 127 0 0 empty empty empty 0 -8 0 8 -262144 +-1 -1 3800 1; +#X obj 62 108 commun /volume \$0; +#X obj 220 145 originator /mypatch \$0; +#X obj 21 174 careGUI; +#X obj 108 64 hsl 128 15 0 127 0 0 empty empty empty -2 -6 0 8 -262144 +-1 -1 9200 1; +#X obj 140 35 commun /pan \$0; +#X floatatom 220 98 5 0 0 1 substate_selector - -; +#X msg 220 121 substate \$1; +#X connect 0 0 1 0; +#X connect 1 0 0 0; +#X connect 4 0 5 0; +#X connect 5 0 4 0; +#X connect 6 0 7 0; +#X connect 7 0 2 0; diff --git a/doc/substates.png b/doc/substates.png new file mode 100644 index 0000000..0667fab Binary files /dev/null and b/doc/substates.png differ -- cgit v1.2.1