149 lines
16 KiB
HTML
149 lines
16 KiB
HTML
|
<!doctype html><html lang='en'><head><title>OSCFunc | SuperCollider 3.12.2 Help</title>
|
||
|
|
<link rel='stylesheet' href='./../scdoc.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../codemirror.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../editor.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../frontend.css' type='text/css' />
|
||
|
|
<link rel='stylesheet' href='./../custom.css' type='text/css' />
|
||
|
|
<meta name='viewport' content='width=device-width, initial-scale=1'>
|
||
|
|
<meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />
|
||
|
|
<script src='./../lib/jquery.min.js'></script>
|
||
|
|
<script src='./../lib/codemirror-5.39.2.min.js' type='text/javascript'></script>
|
||
|
|
<script src='./../lib/codemirror-addon-simple-5.39.2.min.js' type='text/javascript'></script>
|
||
|
|
<script>
|
||
|
|
var helpRoot = './..';
|
||
|
|
var scdoc_title = 'OSCFunc';
|
||
|
|
var scdoc_sc_version = '3.12.2';
|
||
|
|
</script>
|
||
|
|
<script src='./../scdoc.js' type='text/javascript'></script>
|
||
|
|
<script src='./../docmap.js' type='text/javascript'></script>
|
||
|
|
<script src='qrc:///qtwebchannel/qwebchannel.js' type='text/javascript'></script>
|
||
|
|
</head>
|
||
|
|
<body onload='fixTOC()'>
|
||
|
|
<div id='toc'>
|
||
|
|
<div id='toctitle'>OSCFunc:</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='#*defaultDispatcher'>defaultDispatcher</a> </li>
|
||
|
|
<li class='toc3'><a href='#*defaultMatchingDispatcher'>defaultMatchingDispatcher</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='#*trace'>trace</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='#-path'>path</a> </li>
|
||
|
|
<li class='toc3'><a href='#-recvPort'>recvPort</a> </li>
|
||
|
|
<li class='toc2'><a href='#Inherited%20instance%20methods'>Inherited instance methods</a></li>
|
||
|
|
<li class='toc2'><a href='#Undocumented%20instance%20methods'>Undocumented instance methods</a></li>
|
||
|
|
<ul class='toc'><li class='toc3'><a href='#-argTemplate'>argTemplate</a> </li>
|
||
|
|
</ul></ul><li class='toc1'><a href='#examples'>Examples</a></li>
|
||
|
|
<ul class='toc'></ul></ul></div><div id='menubar'></div>
|
||
|
|
<div class='contents'>
|
||
|
|
<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></span>
|
||
|
|
</div><h1>OSCFunc<span id='superclasses'> : <a href="../Classes/AbstractResponderFunc.html">AbstractResponderFunc</a> : <a href="../Classes/Object.html">Object</a></span>
|
||
|
|
</h1>
|
||
|
|
<div id='summary'>Fast Responder for incoming Open Sound Control Messages</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='subclasses'>Subclasses: <a href="../Classes/OSCdef.html">OSCdef</a></div>
|
||
|
|
<div id='related'>See also: <a href="./../Guides/OSC_communication.html">OSC Communication</a>, <a href="./../Classes/OSCdef.html">OSCdef</a>, <a href="./../Classes/NetAddr.html">NetAddr</a></div>
|
||
|
|
</div>
|
||
|
|
<h2><a class='anchor' name='description'>Description</a></h2>
|
||
|
|
|
||
|
|
<p>OSCFunc (and its subclass <a href="./../Classes/OSCdef.html">OSCdef</a>) registers one or more functions to respond to an incoming OSC message which matches a specified OSC Address. Many of its methods are inherited from its superclass <a href="./../Classes/AbstractResponderFunc.html">AbstractResponderFunc</a>. OSCFunc supports pattern matching of wildcards etc. in incoming messages. For efficiency reasons you must specify that an OSCFunc will employ pattern matching by creating it with the <a href="#*newMatching">*newMatching</a> method, or by passing a matching dispatcher to <a href="#*new">*new</a>. For details on the Open Sound Control protocol, see <a href="http://opensoundcontrol.org/spec-1_0">http://opensoundcontrol.org/spec-1_0</a><h2><a class='anchor' name='classmethods'>Class Methods</a></h2>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*defaultDispatcher' href='./../Overviews/Methods.html#defaultDispatcher'>defaultDispatcher</a></h3>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*defaultDispatcher' href='./../Overviews/Methods.html#defaultDispatcher'>defaultDispatcher</a> = value</h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get or set the default dispatcher object for OSCFuncs (this is what you get if you pass nil as the dispatcher argument to <a href="#*new">*new</a>). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>By default this will be an <a href="./../Classes/OSCMessageDispatcher.html">OSCMessageDispatcher</a>, but it can be set to any instance of an appropriate subclass of <a href="./../Classes/AbstractDispatcher.html">AbstractDispatcher</a>.</div></div><h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*defaultMatchingDispatcher' href='./../Overviews/Methods.html#defaultMatchingDispatcher'>defaultMatchingDispatcher</a></h3>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*defaultMatchingDispatcher' href='./../Overviews/Methods.html#defaultMatchingDispatcher'>defaultMatchingDispatcher</a> = value</h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get or set the default matching dispatcher object for OSCFuncs (this is what you get if when you create an OSCFunc using <a href="#*newMatching">*newMatching</a>). This object will decide if any of its registered OSCFuncs should respond to an incoming OSC message using pattern matching.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>By default this will be an <a href="./../Classes/OSCMessagePatternDispatcher.html">OSCMessagePatternDispatcher</a>, but it can be set to any instance of an appropriate subclass of <a href="./../Classes/AbstractDispatcher.html">AbstractDispatcher</a>.</div></div><h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*new' href='./../Overviews/Methods.html#new'>new</a>(<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 OSCFunc.<h4>Arguments:</h4>
|
||
|
|
<table class='arguments'>
|
||
|
|
<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>[OSC address, args1, arg2, ...]</code><tr><td>time<td>the time received (for messages) / the time sent plus the latency (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 OSCFunc 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 OSCFunc 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>A new instance of OSCFunc.</div></div><h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*newMatching' href='./../Overviews/Methods.html#newMatching'>newMatching</a>(<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 OSCFunc 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'>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> [OSCAddress, other args], 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 OSCFunc 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>A new instance of OSCFunc.</div></div><h3 class='method-code'><span class='method-prefix'>OSCFunc.</span><a class='method-name' name='*trace' href='./../Overviews/Methods.html#trace'>trace</a>(<span class='argstr'>bool: true</span>, <span class='argstr'>hideStatusMsg: false</span>)</h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>A convenience method which dumps all incoming OSC messages.<h4>Arguments:</h4>
|
||
|
|
<table class='arguments'>
|
||
|
|
<tr><td class='argumentname'>bool<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Boolean.html">Boolean</a> indicating whether dumping is on or off.<tr><td class='argumentname'>hideStatusMsg<td class='argumentdesc'>
|
||
|
|
<p>A <a href="./../Classes/Boolean.html">Boolean</a> indicating whether server status messages are excluded from the dump or not.</table></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='-path' href='./../Overviews/Methods.html#path'>path</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get the path of this OSCFunc's OSC Address.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>A <a href="./../Classes/String.html">String</a></div></div><h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-recvPort' href='./../Overviews/Methods.html#recvPort'>recvPort</a></h3>
|
||
|
|
<div class='method'>
|
||
|
|
<p>Get this OSCFunc's receiving port.<h4>Returns:</h4>
|
||
|
|
<div class='returnvalue'>
|
||
|
|
<p>An <a href="./../Classes/Integer.html">Integer</a></div></div><h3><a class='anchor' name='Inherited%20instance%20methods'>Inherited instance methods</a></h3>
|
||
|
|
<div id='inheritedinstmets'></div><h3><a class='anchor' name='Undocumented%20instance%20methods'>Undocumented instance methods</a></h3>
|
||
|
|
<h3 class='method-code'><span class='method-prefix'>.</span><a class='method-name' name='-argTemplate' href='./../Overviews/Methods.html#argTemplate'>argTemplate</a></h3>
|
||
|
|
<h2><a class='anchor' name='examples'>Examples</a></h2>
|
||
|
|
<textarea class='editor'>n = NetAddr("127.0.0.1", NetAddr.langPort); // local machine
|
||
|
|
|
||
|
|
OSCFunc.newMatching({|msg, time, addr, recvPort| \matching.postln}, '/chat', n); // path matching
|
||
|
|
OSCFunc({|msg, time, addr, recvPort| \oneShot.postln}, '/chat', n).oneShot; // once only
|
||
|
|
OSCdef(\test, {|msg, time, addr, recvPort| \unmatching.postln}, '/chat', n); // def style
|
||
|
|
|
||
|
|
m = NetAddr("127.0.0.1", NetAddr.langPort); // 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");
|
||
|
|
|
||
|
|
//////// Use an argTemplate for finer grained matching
|
||
|
|
|
||
|
|
s.boot;
|
||
|
|
x = Synth(\default);
|
||
|
|
OSCFunc({ 'ended!'.postln }, '/n_end', s.addr, nil, [x.nodeID]).oneShot;
|
||
|
|
x.release(3);</textarea>
|
||
|
|
|
||
|
|
<p><div class='doclink'>helpfile source: <a href='file:///Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/OSCFunc.schelp'>/Applications/SuperCollider.app/Contents/Resources/HelpSource/Classes/OSCFunc.schelp</a><br>link::Classes/OSCFunc::<br></div></div><script src='./../editor.js' type='text/javascript'></script>
|
||
|
|
</body></html>
|