<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="readk3">
  <refmeta>
    <refentrytitle>readk3</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>readk3</refname>
    <refpurpose>
      Periodically reads three orchestra control-signal values from an external file.
      <indexterm id="IndexReadk3"><primary>readk3</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Periodically reads three orchestra control-signal values from an external file.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>kr1, kr2, kr3 <command>readk3</command> ifilname, iformat, ipol [, interp]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifilname</emphasis> -- character string (in double quotes, spaces permitted) denoting the external file name. May either be a full path name with target directory specified or a simple filename to be created within the current directory
    </para>

    <para>
      <emphasis>iformat</emphasis> -- specifies the output data format:
      <itemizedlist>
        <listitem>
          <para>1 = 8-bit signed char(high order 8 bits of a 16-bit integer</para>
        </listitem>

        <listitem>
          <para>4 = 16-bit short integers</para>
        </listitem>

        <listitem>
          <para>5 = 32-bit long integers</para>
        </listitem>

        <listitem>
          <para>6 = 32-bit floats, 7=ASCII long integers</para>
        </listitem>

        <listitem>
          <para>8 = ASCII floats (2 decimal places)</para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      Note that A-law and U-law output are not available, and that all formats except the lsat two are binary. The output file contains no header information.
    </para>

    <para>
      <emphasis>iprd</emphasis> -- the period of <emphasis>ksig</emphasis> output i seconds, rounded to the nearest orchestra control period. A value of 0 implies one control period (the enforced minimum), which will create an output file sampled at the orchestra control rate.
    </para>

    <para>
      <emphasis>ipol</emphasis> -- if non-zero, and <emphasis>iprd</emphasis> implies more than one control period, interpolate the k- signals between the periodic reads from the external file. If the value is 0, repeat each signal between frames. Currently not supported.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kr1, kr2, kr3</emphasis> -- control-rate signals
    </para>

    <para>
      This opcode allows three generated control signal values to be read from a named external file. The file contains no self-defining header information. But it contains a regularly sampled time series, suitable for later input or analysis. There may be any number of <emphasis>readk3</emphasis> opcodes in an instrument or orchestra and they may read from the same or different files.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
knum    <emphasis>=</emphasis>         knum+1                                               ; at each k-period
ktemp   <emphasis>tempest</emphasis>   krms, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995   ;estimate the tempo
koct    <emphasis>specptrk</emphasis>  wsig, 6, .9, 0                                       ;and the pitch
        <emphasis>dumpk3</emphasis>    knum, ktemp, cpsoct(koct), &quot;what happened when&quot;, 8 0 ;&amp; save them
        </programlisting>
      </informalexample>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="dumpk"><citetitle>dumpk</citetitle></link>,
      <link linkend="dumpk2"><citetitle>dumpk2</citetitle></link>,
      <link linkend="dumpk3"><citetitle>dumpk3</citetitle></link>,
      <link linkend="dumpk4"><citetitle>dumpk4</citetitle></link>,
      <link linkend="readk"><citetitle>readk</citetitle></link>,
      <link linkend="readk2"><citetitle>readk2</citetitle></link>,
      <link linkend="readk4"><citetitle>readk4</citetitle></link>
    </para>
  </refsect1>
</refentry>
