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

  <refnamediv>
    <refname>cpstun</refname>
    <refpurpose>
      Returns micro-tuning values at k-rate.
      <indexterm id="IndexCpstun"><primary>cpstun</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Returns micro-tuning values at k-rate.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>kcps <command>cpstun</command> ktrig, kindex, kfn</synopsis>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kcps</emphasis> -- Return value in cycles per second.
    </para>

    <para>
      <emphasis>ktrig</emphasis> -- A trigger signal used to trigger the evaluation.
    </para>

    <para>
      <emphasis>kindex</emphasis> -- An integer number denoting an index of scale.
    </para>

    <para>
      <emphasis>kfn</emphasis> --  Function table containing the parameters (numgrades, interval, basefreq, basekeymidi) and the tuning ratios.
    </para>

    <para>
      These opcodes are similar to cpstmid, but work without necessity of MIDI.
    </para>

    <para>
      <emphasis>cpstun</emphasis> works at k-rate. It allows fully customized micro-tuning scales. It requires a function table number containing the tuning ratios, and some other parameters stored in the function table itself.
    </para>

    <para>
      <emphasis>kindex</emphasis> arguments should be filled with integer numbers expressing the grade of given scale to be converted in cps. In <emphasis>cpstun</emphasis>, a new value is evaluated only when <emphasis>ktrig</emphasis> contains a non-zero value.  The function table <emphasis>kfn</emphasis> should be generated by <link linkend="GEN02"><citetitle>GEN02</citetitle></link> and the first four values stored in this function are parameters that express:
      <itemizedlist>
        <listitem><para>numgrades -- The number of grades of the micro-tuning scale.</para></listitem>

        <listitem><para>interval -- The frequency range covered before repeating the grade ratios, for example 2 for one octave, 1.5 for a fifth etcetera.</para></listitem>

        <listitem><para>basefreq -- The base frequency of the scale in cycles per second.</para></listitem>

        <listitem><para>basekey -- The integer index of the scale to which to assign basefreq unmodified.</para></listitem>
      </itemizedlist>
    </para>

    <para>
      After these four values, the user can begin to insert the tuning ratios.  For example, for a standard 12-grade scale with the base-frequency of 261 cps assigned to the key-number 60, the corresponding f-statement in the score to generate the table should be:

      <informalexample>
        <programlisting>
;           numgrades    basefreq     tuning-ratios (eq.temp) .......
;                  interval    basekey
f1 0 64 -2  12     2     261   60     1   1.059463 1.12246 1.18920 ..etc...
        </programlisting>
      </informalexample>
    </para>

    <para>
Another example with a 24-grade scale with a base frequency of 440 assigned
to the key-number 48, and a repetition interval of 1.5:

      <informalexample>
        <programlisting>
                  numgrades       basefreq      tuning-ratios .......
                          interval       basekey
f1 0 64 -2         24      1.5     440    48     1   1.01  1.02  1.03   ..etc...
        </programlisting>
      </informalexample>
    </para>
  </refsect1>

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

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

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

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

      Its output should include lines like this:
      <screen>
 i1   440.11044
      </screen>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="cpstmid"><citetitle>cpstmid</citetitle></link>,
      <link linkend="cpstuni"><citetitle>cpstuni</citetitle></link>,
      <link linkend="GEN02"><citetitle>GEN02</citetitle></link>
    </para>
  </refsect1>

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