<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="instr">
  <refmeta>
    <refentrytitle>instr</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>instr</refname>

    <refpurpose>
      Starts an instrument block.
      <indexterm id="IndexInstr"><primary>instr</primary></indexterm>
    </refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>
    <para>
      Starts an instrument block.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis><command>instr</command> i, j, ...</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para> 
      Starts an instrument block defining instruments <emphasis>i, j</emphasis>, ...
    </para>

    <para>
      <emphasis>i, j</emphasis>, ... must be numbers, not expressions. Any positive integer is legal, and in any order, but excessively high numbers are best avoided.
    </para>

    <note>
      <title>Note</title>
      <para>
        There may be any number of instrument blocks in an orchestra.
      </para>
    </note>

     <para>
       Instruments can be defined in any order (but they will always be both initialized and performed in ascending instrument number order).  Instrument blocks cannot be nested (i.e. one block cannot contain another).
     </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <refsect2 id="InstrSubinstrument">
      <title>Calling an Instrument within an Instrument</title>
      <para>
        You can call an instrument within an instrument as if it were an opcode either with the <link linkend="subinstr"><citetitle>subinstr</citetitle></link> opcode or by specifying an instrument with a text name:

        <informalexample>
          <programlisting>
instr MyOscil
...
endin
          </programlisting>
        </informalexample>
      </para>


      <para>
        If an instrument is defined with a name, you simply call it directly like an opcode:

        <informalexample>
          <programlisting>
asig MyOscil iamp, ipitch, iftable
          </programlisting>
        </informalexample>
      </para>


      <para>
        By default, all output parameters correspond to the called instrument's output with the <link linkend="SigioOutput"><citetitle>signal output</citetitle></link> opcodes.  All input parameters are mapped to the called instrument's p-fields starting with the fourth one, p4.  The values of the called instrument's second and third p-fields, p2 and p3, are automatically set to those of the calling instrument's.
      </para>

      <para>
        A named instrument must be defined before any instrument that calls it.
      </para>

      <refsect3 id="InstrSubinstrumentAdvanced">
        <title>Advanced Options</title>
        <para>
          You can optionally define an instrument's interface if you need to pass k-rate values, audio input, or greater than 8 audio output channels.  The output and input types are specified after the instrument name, as a list of characters (0, a, i, k, or p):

          <informalexample>
            <programlisting>
instr name, outputlist, inputlist
            </programlisting>
          </informalexample>
        </para>

        <para>
          For example, this instrument:

          <informalexample>
            <programlisting>
instr MyFilter, aak, aaki
...
endin
            </programlisting>
          </informalexample>

          Specifies an instrument that outputs 2 a-rate signals and 1 k-rate signal. It takes 2 a-rate signals as input followed by a k-rate signal and an i-rate signal.
        </para>

        <para>
          A call to this instrument would something like like:

          <informalexample>
            <programlisting>
asig1, asig2, k1 MyFilter aleft, aright, kfreq, ibw
            </programlisting>
          </informalexample>
        </para>

        <para>
          The allowable character types are:

          <table frame="none" colsep="0">
            <title>Allowable Character Types</title>

            <tgroup cols="3">
              <thead>
                <row>
                  <entry>Character</entry>
                  <entry>Signal</entry>
                  <entry>Context</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>0</entry>
                  <entry>Specifies no signal passed.</entry>
                  <entry>Allowed with input and output. Cannot occur with other types.</entry>
                </row>

                <row>
                  <entry>a</entry>
                  <entry>a-rate signal.</entry>
                  <entry>Allowed with input and output. Accessed with the <link linkend="SigioInput"><citetitle>signal input</citetitle></link> and <link linkend="SigioOutput"><citetitle>signal output</citetitle></link> opcodes.</entry>
                </row>

                <row>
                  <entry>i</entry>
                  <entry>i-rate signal mapped to a p-field.</entry>
                  <entry>Input only.</entry>
                </row>

                <row>
                  <entry>k</entry>
                  <entry>k-rate signal.</entry>
                  <entry>Allowed with input and output. Accessed with the <link linkend="ink"><citetitle>ink</citetitle></link> and <link linkend="outk"><citetitle>outk</citetitle></link> opcodes.</entry>
                </row>

                <row>
                  <entry>p</entry>
                  <entry>k-rate signal mapped to a p-field.</entry>
                  <entry>Input only.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          The <emphasis>i</emphasis> and <emphasis>p</emphasis> character types are mapped to p-fields as they occur in order starting with the fourth p-field, p4. The <emphasis>a</emphasis> and <emphasis>k</emphasis> character types are mapped in order of channels to be accessed with the <link linkend="SigioInput"><citetitle>signal input</citetitle></link> and <link linkend="SigioOutput"><citetitle>signal output</citetitle></link> opcodes.
        </para>

        <para>
          For example:

          <informalexample>
            <programlisting>
instr MyProcess 0, apaki
            </programlisting>
          </informalexample>

          Defines an instrument with no output, 2 a-rate signal inputs (the first and third input parameters).  The second input (&quot;p&quot;) is mapped to p4, which potentially changes every k-pass.  The fourth input parameter is mapped to be retrieved with the <link linkend="ink"><citetitle>ink</citetitle></link> opcode.  The last input signal is mapped to p5, and will stay the same value during the instrument instance's performance.
        </para>

        <para>
          A call to this instrument would look something like:

          <informalexample>
            <programlisting>
MyProcess asig, kfreq, arefsig, kamp, imode
            </programlisting>
          </informalexample>
        </para>

        <para>
          Accessing the data passed to the instrument would look something like:

          <informalexample>
            <programlisting>
instr MyProcess 0, apaki
    imode = p5

    asig, arefsig ins
    kamp ink

    ; p4 can change during performance
    printk .1, p4  
endin
            </programlisting>
          </informalexample>
        </para>

        <para>
          See <link linkend="ink"><citetitle>ink</citetitle></link>/<link linkend="outk"><citetitle>outk</citetitle></link> documentation for another example.
        </para>

        <note>
          <title>Hint</title>
          <para>
            If you use the <link linkend="inch"><citetitle>inch</citetitle></link>, <link linkend="outc"><citetitle>outc</citetitle></link>, <link linkend="outch"><citetitle>outch</citetitle></link>, etc. opcodes, you can create an instrument that will compile and function in any orchestra of any number of channels.
          </para>

          <para>
            A nice feature to use with named instruments is the <link linkend="include"><citetitle>&num;include</citetitle></link> feature.  You can then define your named instruments in separate files, using &num;include when you need to use one.
          </para>
        </note>
      </refsect3>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the instr opcode. It uses the files <ulink url="examples/instr.orc"><citetitle>instr.orc</citetitle></ulink> and <ulink url="examples/instr.sco"><citetitle>instr.sco</citetitle></ulink>.

      <example>
        <title>Example of the instr opcode.</title>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/instr.orc" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>

        <programlisting>
<inlinemediaobject>
            <imageobject>
              <imagedata fileref="examples/instr.sco" format="linespecific">
            </imageobject>
          </inlinemediaobject>
        </programlisting>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="endin"><citetitle>endin</citetitle></link>, 
      <link linkend="ink"><citetitle>ink</citetitle></link>, 
      <link linkend="in"><citetitle>in</citetitle></link>, 
      <link linkend="outk"><citetitle>outk</citetitle></link>, 
      <link linkend="out"><citetitle>out</citetitle></link>, 
      <link linkend="subinstr"><citetitle>subinstr</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Example written by &namekevin;.</para>
  </refsect1>
</refentry>
