<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>chn</title> <link rel="stylesheet" type="text/css" href="csound.css" /> <link rel="stylesheet" type="text/css" href="syntax-highlighting.css" /> <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /> <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" /> <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" /> <link rel="prev" href="checkbox.html" title="checkbox" /> <link rel="next" href="chnclear.html" title="chnclear" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">chn</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="checkbox.html">Prev</a> </td> <th width="60%" align="center">Orchestra Opcodes and Operators</th> <td width="20%" align="right"> <a accesskey="n" href="chnclear.html">Next</a></td> </tr> </table> <hr /> </div> <div class="refentry"> <a id="chn"></a> <div class="titlepage"></div> <a id="Indexchn" class="indexterm"></a> <div class="refnamediv"> <h2> <span class="refentrytitle">chn</span> </h2> <p>chn — Declare a channel of the named software bus. </p> </div> <div class="refsect1"> <a id="idm281472947277960"></a> <h2>Description</h2> <p> Declare a channel of the named software bus, with setting optional parameters in the case of a control channel. If the channel does not exist yet, it is created, with an inital value of zero or empty string. Otherwise, the type (control, audio, or string) of the existing channel must match the declaration, or an init error occurs. The input/output mode of an existing channel is updated so that it becomes the bitwise OR of the previous and the newly specified value. </p> </div> <div class="refsect1"> <a id="idm281472947276248"></a> <h2>Syntax</h2> <pre class="synopsis"> <span class="command"><strong>chn_k</strong></span> Sname, imode[, itype, idflt, imin, ima, ix, iy, iwidth, iheight, Sattributes]</pre> <pre class="synopsis"> <span class="command"><strong>chn_a</strong></span> Sname, imode</pre> <pre class="synopsis"> <span class="command"><strong>chn_S</strong></span> Sname, imode</pre> </div> <div class="refsect1"> <a id="idm281472947208904"></a> <h2>Initialization</h2> <p> <span class="emphasis"><em>imode</em></span> -- sum of at least one of 1 for input and 2 for output. </p> <p> <span class="emphasis"><em>itype</em></span> (optional, defaults to 0) -- channel subtype for control channels only. Possible values are: </p> <div class="itemizedlist"> <ul class="itemizedlist" style="list-style-type: disc; "> <li class="listitem"> <p> 0: default/unspecified (<span class="emphasis"><em>idflt</em></span>, <span class="emphasis"><em>imin</em></span>, and <span class="emphasis"><em>imax</em></span> are ignored) </p> </li> <li class="listitem"> <p> 1: integer values only </p> </li> <li class="listitem"> <p> 2: linear scale </p> </li> <li class="listitem"> <p> 3: exponential scale </p> </li> </ul> </div> <p> </p> <p> <span class="emphasis"><em>idflt</em></span> (optional, defaults to 0) -- default value, for control channels with non-zero <span class="emphasis"><em>itype</em></span> only. Must be greater than or equal to <span class="emphasis"><em>imin</em></span>, and less than or equal to <span class="emphasis"><em>imax</em></span>. </p> <p> <span class="emphasis"><em>imin</em></span> (optional, defaults to 0) -- minimum value, for control channels with non-zero <span class="emphasis"><em>itype</em></span> only. Must be non-zero for exponential scale (<span class="emphasis"><em>itype</em></span> = 3). </p> <p> <span class="emphasis"><em>imax</em></span> (optional, defaults to 0) -- maximum value, for control channels with non-zero <span class="emphasis"><em>itype</em></span> only. Must be greater than <span class="emphasis"><em>imin</em></span>. In the case of exponential scale, it should also match the sign of <span class="emphasis"><em>imin</em></span>. </p> <p> <span class="emphasis"><em>ix</em></span> -- suggested x position for controller. </p> <p> <span class="emphasis"><em>iy</em></span> -- suggested y position for controller. </p> <p> <span class="emphasis"><em>iwidth</em></span> -- suggested width position for controller. </p> <p> <span class="emphasis"><em>iheight</em></span> -- suggested height position for controller. </p> <p> <span class="emphasis"><em>Sattributes</em></span> -- attributes for controller. </p> </div> <div class="refsect1"> <a id="idm281472947190520"></a> <h2>Notes</h2> <p> The channel parameters (<span class="emphasis"><em>imode</em></span>, <span class="emphasis"><em>itype</em></span>, <span class="emphasis"><em>idflt</em></span>, <span class="emphasis"><em>imin</em></span>, and <span class="emphasis"><em>imax</em></span>) are only hints for the host application or external software accessing the bus through the API, and do not actually restrict reading from or writing to the channel in any way. Also, the initial value of a newly created control channel is zero, regardless of the setting of <span class="emphasis"><em>idflt</em></span>. </p> <p> For communication with external software, using <a class="link" href="chnexport.html" title="chnexport"><em class="citetitle">chnexport</em></a> may be preferred, as it allows direct access to orchestra variables exported as channels of the bus, eliminating the need for using <a class="link" href="chnset.html" title="chnset"><em class="citetitle">chnset</em></a> and <a class="link" href="chnget.html" title="chnget"><em class="citetitle">chnget</em></a> to send or receive data. </p> </div> <div class="refsect1"> <a id="idm281472947182888"></a> <h2>Performance</h2> <p> <span class="command"><strong>chn_k</strong></span>, <span class="command"><strong>chn_a</strong></span>, and <span class="command"><strong>chn_S</strong></span> declare a control, audio, or string channel, respectively. </p> </div> <div class="refsect1"> <a id="idm281472947179528"></a> <h2>Example</h2> <p> The example shows the software bus being used as an asynchronous control signal to select a filter cutoff. It assumes that an external program that has access to the API is feeding the values. </p> <div class="informalexample"> <pre class="programlisting"> <span class="ohdr">sr</span> <span class="op">=</span> 44100 <span class="ohdr">kr</span> <span class="op">=</span> 100 <span class="ohdr">ksmps</span> <span class="op">=</span> 1 <span class="opc">chn_k</span> "cutoff", 1, 3, 1000, 500, 2000 <span class="oblock">instr</span> 1 kc <span class="opc">chnget</span> "cutoff" a1 <span class="opc">oscil</span> p4, p5, 100 a2 <span class="opc">lowpass2</span> a1, kc, 200 <span class="opc">out</span> a2 <span class="oblock">endin</span> </pre> </div> </div> <div class="refsect1"> <a id="idm281472947168200"></a> <h2>Credits</h2> <p> </p> <table border="0" summary="Simple list" class="simplelist"> <tr> <td>Author: Istvan Varga</td> </tr> <tr> <td>2005</td> </tr> </table> <p> </p> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="checkbox.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="OpcodesTop.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="chnclear.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">checkbox </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> chnclear</td> </tr> </table> </div> </body> </html>