160 lines
15 KiB
HTML
160 lines
15 KiB
HTML
|
<!doctype html><html lang='en'><head><title>OSCdef | SuperCollider 3.9.3 Help</title>
|
||
|
|
<link rel='stylesheet' href='./../scdoc.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../frontend.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../custom.css' type='text/css' />
|
||
|
|
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />
|
||
|
|
<script>
|
||
|
|
var helpRoot = './..';
|
||
|
|
var scdoc_title = 'OSCdef';
|
||
|
|
var scdoc_sc_version = '3.9.3';
|
||
|
|
</script>
|
||
|
|
<script src='./../scdoc.js' type='text/javascript'></script>
|
||
|
|
<script src='./../docmap.js' type='text/javascript'></script>
|
||
|
|
<script src='./../prettify.js' type='text/javascript'></script>
|
||
|
|
<script src='./../lang-sc.js' type='text/javascript'></script>
|
||
|
|
</head>
|
||
|
|
<body onload='fixTOC();prettyPrint()'>
|
||
|
|
<div id='toc'>
|
||
|
|
<div id='toctitle'>OSCdef:</div>
|
||
|
|
<span class='toc_search'>Filter: <input id='toc_search'></span><ul class='toc'><li class='toc1'><a href='#description'>Description</a></li>
|
||
|
|
<ul class='toc'></ul><li class='toc1'><a href='#classmethods'>Class methods</a></li>
|
||
|
|
<ul class='toc'><li class='toc3'><a href='#*all'>all</a> </li>
|
||
|
|
<li class='toc3'><a href='#*new'>new</a> </li>
|
||
|
|
<li class='toc3'><a href='#*newMatching'>newMatching</a> </li>
|
||
|
|
<li class='toc3'><a href='#*freeAll'>freeAll</a> </li>
|
||
|
|
<li class='toc2'><a href='#Inherited%20class%20methods'>Inherited class methods</a></li>
|
||
|
|
</ul><li class='toc1'><a href='#instancemethods'>Instance methods</a></li>
|
||
|
|
<ul class='toc'><li class='toc3'><a href='#-key'>key</a> </li>
|
||
|
|
<li class='toc3'><a href='#-free'>free</a> </li>
|
||
|
|
<li class='toc2'><a href='#Inherited%20instance%20methods'>Inherited instance methods</a></li>
|
||
|
|
</ul><li class='toc1'><a href='#examples'>Examples</a></li>
|
||
|
|
<ul class='toc'></ul><li class='toc1'><a href='#Timing%20in%20incoming%20bundles'>Timing in incoming bundles</a></li>
|
||
|
|
<ul class='toc'></ul></ul></div><div class='contents'>
|
||
|
|
<div id='menubar'></div>
|
||
|
|
<div class='header'>
|
||
|
|
<div id='label'>
|
||
|
|
<span id='folder'>Classes</span>
|
||
|
|
| <span id='categories'><a href='./../Browse.html#External Control'>External Control</a> > <a href='./../Browse.html#External Control>OSC'>OSC</a> > <a href='./../Browse.html#External Control>OSC>Dispatchers'>Dispatchers</a></span>
|
||
|
|
</div><h1>OSCdef<span id='superclasses'> : <a href="../Classes/OSCFunc.html">OSCFunc</a> : <a href="../Classes/AbstractResponderFunc.html">AbstractResponderFunc</a> : <a href="../Classes/Object.html">Object</a></span>
|
||
|
|
</h1>
|
||
|
|
<div id='summary'>OSC response reference definition</div>
|
||
|
|
</div>
|
||
|
|
<div class='subheader'>
|
||
|
|
<div id='filename'>Source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Control/ResponseDefs.sc' title='/Applications/SuperCollider.app/Contents/Resources/SCClassLibrary/Common/Control/ResponseDefs.sc'>ResponseDefs.sc</a></div><div id='related'>See also: <a href="./../Guides/OSC_communication.html">OSC Communication</a>, <a href="./../Classes/OSCFunc.html">OSCFunc</a>, <a href="./../Classes/NetAddr.html">NetAddr</a></div>
|
||
|
|
</div>
|
||
|
|
<h2><a class='anchor' name='description'>Description</a></h2>
|
||
|
|
|
||
|
|
<p>OSCdef provides a global reference to the functionality of its superclass <a href="./../Classes/OSCFunc.html">OSCFunc</a>. Essentially it stores itself at a key within a global dictionary, allowing replacement at any time. Most methods are inherited from its superclass.<h2><a class='anchor' name='classmethods'>Class Methods</a></h2>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>OSCdef.</span><a class='method-name' name='*all' href='./../Overviews/Methods.html#all'>all</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get the global dictionary of all OSCdefs.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>An <a href="./../Classes/IdentityDictionary.html">IdentityDictionary</a>.</div></div><h3 class='method-code'><span class='method-prefix'>OSCdef.</span><a class='method-name' name='*new' href='./../Overviews/Methods.html#new'>new</a>(<span class='argstr'>key</span>, <span class='argstr'>func</span>, <span class='argstr'>path</span>, <span class='argstr'>srcID</span>, <span class='argstr'>recvPort</span>, <span class='argstr'>argTemplate</span>, <span class='argstr'>dispatcher</span>)</h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Create a new, enabled OSCdef. If an OSCdef already exists at this key, its parameters will be replaced with the ones provided (args for which nil is passed will use the old values).<h4>Arguments:</h4>
|
||
|
|
<table class='arguments'>
|
||
|
|
<tr><td class='argumentname'>key<td class='argumentdesc'>
|
||
|
|
<p>The key at which to store this OSCdef in the global collection. Generally this will be a <a href="./../Classes/Symbol.html">Symbol</a>.<tr><td class='argumentname'>func<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Function.html">Function</a> or similar object which will respond to the incoming message. When evaluated it will be passed the following arguments:<table>
|
||
|
|
<tr><td>msg<td>message as an <a href="./../Classes/Array.html">Array</a> in the form <code class='code prettyprint lang-sc'>[OSC address, args1, arg2, ...]</code><tr><td>time<td>the time received (for messages) / the OSC bundle's timestamp (if the message was in a bundle)<tr><td>addr<td>a <a href="./../Classes/NetAddr.html">NetAddr</a> corresponding to the IP address of the <strong>sender</strong><tr><td>recvPort<td><a href="./../Classes/Integer.html">Integer</a> corresponding to the port on which the message was <strong>received</strong>.</table>
|
||
|
|
<tr><td class='argumentname'>path<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Symbol.html">Symbol</a> indicating the path of the OSC address of this object. Note that OSCdef demands OSC compliant addresses. If the path does not begin with a / one will be added automatically.<tr><td class='argumentname'>srcID<td class='argumentdesc'>
|
||
|
|
<p>An optional instance of <a href="./../Classes/NetAddr.html">NetAddr</a> indicating the IP address of the sender. If set this object will only respond to messages from that source.<tr><td class='argumentname'>recvPort<td class='argumentdesc'>
|
||
|
|
<p>An optional <a href="./../Classes/Integer.html">Integer</a> indicating the port on which messages will be received. If set this object will only respond to message received on that port. This method calls <a href="./../Classes/Main.html#-openUDPPort">Main: -openUDPPort</a> to ensure that the port is opened.<tr><td class='argumentname'>argTemplate<td class='argumentdesc'>
|
||
|
|
<p>An optional <a href="./../Classes/Array.html">Array</a> composed of instances of <a href="./../Classes/Integer.html">Integer</a> or <a href="./../Classes/Function.html">Function</a> (or objects which respond to the method <a href="./../Overviews/Methods.html#matchItem">Methods: matchItem</a>) used to match the arguments of an incoming OSC message. If a Function, it will be evaluated with the corresponding message arg as an argument, and should return a <a href="./../Classes/Boolean.html">Boolean</a> indicating whether the argument matches and this OSCdef should respond (providing all other arguments match). Template values of nil will match any incoming argument value.<tr><td class='argumentname'>dispatcher<td class='argumentdesc'>
|
||
|
|
<p>An optional instance of an appropriate subclass of <a href="./../Classes/AbstractDispatcher.html">AbstractDispatcher</a>. This can be used to allow for customised dispatching. Normally this should not be needed.</table><h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>An instance of OSCdef.</div></div><h3 class='method-code'><span class='method-prefix'>OSCdef.</span><a class='method-name' name='*newMatching' href='./../Overviews/Methods.html#newMatching'>newMatching</a>(<span class='argstr'>key</span>, <span class='argstr'>func</span>, <span class='argstr'>path</span>, <span class='argstr'>srcID</span>, <span class='argstr'>recvPort</span>, <span class='argstr'>argTemplate</span>)</h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>A convenience method to create a new, enabled OSCdef whose dispatcher will perform pattern matching on incoming OSC messages to see if their address patterns match this object's path.<h4>Arguments:</h4>
|
||
|
|
<table class='arguments'>
|
||
|
|
<tr><td class='argumentname'>key<td class='argumentdesc'>
|
||
|
|
<p>The key at which to store this OSCdef in the global collection. Generally this will be a <a href="./../Classes/Symbol.html">Symbol</a>.<tr><td class='argumentname'>func<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Function.html">Function</a> or similar object which will respond to the incoming message. When evaluated it will be passed the arguments msg, time, addr, and recvPort, corresponding to the message as an <a href="./../Classes/Array.html">Array</a> [OSC address, args1, arg2, ...], the time that the message was sent, a <a href="./../Classes/NetAddr.html">NetAddr</a> corresponding to the IP address of the sender, and an <a href="./../Classes/Integer.html">Integer</a> corresponding to the port on which the message was received.<tr><td class='argumentname'>path<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Symbol.html">Symbol</a> indicating the path of the OSC address of this object. Note that OSCdef demands OSC compliant addresses. If the path does not begin with a / one will be added automatically. Pattern matching will be applied to any incoming messages to see if they match this address. Note that according to the OSC spec, regular expression wildcards are only permitted in the incoming message's address pattern. Thus path should not contain wildcards. For more details on OSC pattern matching, see <a href="http://opensoundcontrol.org/spec-1_0">http://opensoundcontrol.org/spec-1_0</a><tr><td class='argumentname'>srcID<td class='argumentdesc'>
|
||
|
|
<p>An optional instance of <a href="./../Classes/NetAddr.html">NetAddr</a> indicating the IP address of the sender. If set this object will only respond to messages from that source.<tr><td class='argumentname'>recvPort<td class='argumentdesc'>
|
||
|
|
<p>An optional <a href="./../Classes/Integer.html">Integer</a> indicating the port on which messages will be received.<tr><td class='argumentname'>argTemplate<td class='argumentdesc'>
|
||
|
|
<p>An optional <a href="./../Classes/Array.html">Array</a> composed of instances of <a href="./../Classes/Integer.html">Integer</a> or <a href="./../Classes/Function.html">Function</a> (or objects which respond to the method <a href="./../Overviews/Methods.html#matchItem">Methods: matchItem</a>) used to match the arguments of an incoming OSC message. If a Function, it will be evaluated with the corresponding message arg as an argument, and should return a <a href="./../Classes/Boolean.html">Boolean</a> indicating whether the argument matches and this OSCFunc should respond (providing all other arguments match). Template values of nil will match any incoming argument value.</table><h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>An instance of OSCdef.</div></div><h3 class='method-code'><span class='method-prefix'>OSCdef.</span><a class='method-name' name='*freeAll' href='./../Overviews/Methods.html#freeAll'>freeAll</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Clears and deactivates all OSCdefs from the global collection.</div><h3><a class='anchor' name='Inherited%20class%20methods'>Inherited class methods</a></h3>
|
||
|
|
<div id='inheritedclassmets'></div><h2><a class='anchor' name='instancemethods'>Instance Methods</a></h2>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-key' href='./../Overviews/Methods.html#key'>key</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get this OSCdef's key.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>Usually a <a href="./../Classes/Symbol.html">Symbol</a>.</div></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-free' href='./../Overviews/Methods.html#free'>free</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Clears this OSCdef from the global collection and deactivates it.</div><h3><a class='anchor' name='Inherited%20instance%20methods'>Inherited instance methods</a></h3>
|
||
|
|
<div id='inheritedinstmets'></div><h2><a class='anchor' name='examples'>Examples</a></h2>
|
||
|
|
<pre class='code prettyprint lang-sc'>n = NetAddr("127.0.0.1", 57120); // local machine
|
||
|
|
|
||
|
|
OSCdef(\test, {|msg, time, addr, recvPort| \unmatching.postln}, '/chat', n); // def style
|
||
|
|
OSCdef.newMatching(\test2, {|msg, time, addr, recvPort| \matching.postln}, '/chat', n); // path matching
|
||
|
|
OSCdef(\test3, {|msg, time, addr, recvPort| \oneShot.postln}, '/chat', n).oneShot; // once only
|
||
|
|
|
||
|
|
|
||
|
|
m = NetAddr("127.0.0.1", 57120); // loopback
|
||
|
|
|
||
|
|
m.sendMsg("/chat", "Hello App 1");
|
||
|
|
m.sendMsg("/chat", "Hello App 1"); // oneshot gone
|
||
|
|
m.sendMsg("/ch?t", "Hello App 1");
|
||
|
|
m.sendMsg("/*", "Hello App 1");
|
||
|
|
m.sendMsg("/chit", "Hello App 1"); // nothing
|
||
|
|
|
||
|
|
// Introspection
|
||
|
|
|
||
|
|
AbstractResponderFunc.allFuncProxies
|
||
|
|
AbstractResponderFunc.allEnabled
|
||
|
|
OSCdef(\test).disable;
|
||
|
|
AbstractResponderFunc.allDisabled
|
||
|
|
|
||
|
|
// change funcs
|
||
|
|
OSCdef(\test).enable;
|
||
|
|
OSCdef(\test, {|msg, time, addr, recvPort| 'Changed Unmatching'.postln}, '/chat', n); // replace at key \test
|
||
|
|
m.sendMsg("/chat", "Hello App 1");
|
||
|
|
OSCdef(\test).add(f = {\foo.postln}); // add another func
|
||
|
|
m.sendMsg("/chat", "Hello App 1");
|
||
|
|
OSCdef(\test).clear; // remove all functions
|
||
|
|
m.sendMsg("/chat", "Hello App 1");
|
||
|
|
OSCdef(\test).free; // unregister OSCdef
|
||
|
|
|
||
|
|
|
||
|
|
//////// Use an argTemplate for finer grained matching
|
||
|
|
|
||
|
|
s.boot;
|
||
|
|
x = Synth(\default);
|
||
|
|
OSCdef(\watchForXEnd, { 'ended!'.postln }, '/n_end', s.addr, nil, [x.nodeID]).oneShot;
|
||
|
|
x.release(3);
|
||
|
|
|
||
|
|
// Args for which nil is passed will use the old values. While this facilitates swapping only parts of an OSCdef, such as the function, it also means you will have to free and recreate an OSCdef to remove parts.
|
||
|
|
|
||
|
|
OSCdef(\argtest, {|msg ... args| msg[1].postln}, '/hey', argTemplate: ['you']);
|
||
|
|
m.sendMsg("/hey", "you"); // oscdef will respond
|
||
|
|
m.sendMsg("/hey", "there"); // oscdef will not respond, filtered out by argTemplate
|
||
|
|
|
||
|
|
OSCdef(\argtest, argTemplate: nil); // this has no effect
|
||
|
|
m.sendMsg("/hey", "you"); // oscdef will respond
|
||
|
|
m.sendMsg("/hey", "there"); // oscdef will not respond, still filtered out by argTemplate
|
||
|
|
|
||
|
|
OSCdef(\argtest).free; // in order to get rid of the argTemplate, free the def...
|
||
|
|
OSCdef(\argtest, {|msg ... args| msg[1].postln}, '/hey'); // ... and recreate it.
|
||
|
|
m.sendMsg("/hey", "you"); // oscdef will respond
|
||
|
|
m.sendMsg("/hey", "there"); // oscdef will respond</pre>
|
||
|
|
|
||
|
|
<p><h2><a class='anchor' name='Timing%20in%20incoming%20bundles'>Timing in incoming bundles</a></h2>
|
||
|
|
|
||
|
|
<p>The time argument indicates the time the message was sent plus, if given, the latency added to the bundle:<pre class='code prettyprint lang-sc'>(
|
||
|
|
OSCdef(\x, { |msg, time|
|
||
|
|
"reception time: %\nscheduling time: %\ndelta: %\n\n".postf(Main.elapsedTime, time, time - Main.elapsedTime)
|
||
|
|
}, \time);
|
||
|
|
|
||
|
|
n = NetAddr("127.0.0.1", 57120);
|
||
|
|
)
|
||
|
|
|
||
|
|
(
|
||
|
|
n.sendBundle(0.0, [\time]);
|
||
|
|
n.sendBundle(1.0, [\time]);
|
||
|
|
)</pre>
|
||
|
|
<div class='doclink'>helpfile source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/OSCdef.schelp'>/Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/OSCdef.schelp</a><br>link::Classes/OSCdef::<br></div></div></body></html>
|