<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="fout">
  <refmeta>
    <refentrytitle>fout</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>fout</refname>
    <refpurpose>
      Outputs a-rate signals to an arbitrary number of channels.
      <indexterm id="IndexFout"><primary>fout</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>fout</emphasis> outputs <emphasis>N</emphasis> a-rate signals to a specified file of <emphasis>N</emphasis> channels.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis><command>fout</command> ifilename, iformat, aout1 [, aout2, aout3,...,aoutN]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifilename</emphasis> -- the output file's name (in double-quotes).
    </para>

    <para>
      <emphasis>iformat</emphasis> -- a flag to choose output file format:
      <itemizedlist>
        <listitem>
          <para>0 - 32-bit floating point samples without header (binary PCM multichannel file)</para>
        </listitem>

        <listitem>
          <para>1 - 16-bit integers without header (binary PCM multichannel file)</para>
        </listitem>

        <listitem>
          <para>2 - 16-bit integers with a header. The header type depends on the render format. The default header type is the IRCAM format. If the user chooses the AIFF format (using the <link linkend="FlagsMinusUpperA"><citetitle>-A flag</citetitle></link>), the header format will be a AIFF type. If the user chooses the WAV format (using the <link linkend="FlagsMinusUpperW"><citetitle>-W flag</citetitle></link>), the header format will be a WAV type.</para>
        </listitem>
      </itemizedlist>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>aout1,... aoutN</emphasis> -- signals to be written to the file
    </para>

    <para>
      <emphasis>fout</emphasis> (file output) writes samples of audio signals to a file with any number of channels. Channel number depends by the number of <emphasis>aoutN</emphasis> variables (i.e. a mono signal with only an a-rate argument, a stereo signal with two a-rate arguments etc.) Maximum number of channels is fixed to 64. Multiple <emphasis>fout</emphasis> opcodes can be present in the same instrument, referring to different files.
    </para>

    <para>
      Notice that, unlike <link linkend="out"><citetitle>out</citetitle></link>, <link linkend="outs"><citetitle>outs</citetitle></link> and <link linkend="outq"><citetitle>outq</citetitle></link>, <emphasis>fout</emphasis> does not zero the audio variable so you must zero it after calling it. If polyphony is to be used, you can use <link linkend="vincr"><citetitle>vincr</citetitle></link> and <link linkend="clear"><citetitle>clear</citetitle></link> opcodes for this task.
    </para>

    <para>
      Notice that <emphasis>fout</emphasis> and <link linkend="foutk"><citetitle>foutk</citetitle></link> can use either a string containing a file pathname, or a handle-number generated by <link linkend="fiopen"><citetitle>fiopen</citetitle></link>. Whereas, with <link linkend="fouti"><citetitle>fouti</citetitle></link> and <link linkend="foutir"><citetitle>foutir</citetitle></link>, the target file can be only specified by means of a handle-number.
    </para>
  </refsect1>

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

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

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

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

    <para>
      Here is an example of the fout opcode with a polyphonic score. It uses the files <ulink url="examples/fout_poly.orc"><citetitle>fout_poly.orc</citetitle></ulink>, <ulink url="examples/fout_poly.sco"><citetitle>fout_poly.sco</citetitle></ulink> and <ulink url="examples/beats.wav"><citetitle>beats.wav</citetitle></ulink>.

      <example>
        <title>Example of the fout opcode with a polyphonic score.</title>

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="fiopen"><citetitle>fiopen</citetitle></link>,
      <link linkend="fouti"><citetitle>fouti</citetitle></link>,
      <link linkend="foutir"><citetitle>foutir</citetitle></link>,
      <link linkend="foutk"><citetitle>foutk</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &namegabriel;</member>
        <member>Italy</member>
        <member>1999</member>
      </simplelist>
    </para>
    <para>The simple example was written by &namekevin;.</para>

    <para>New in Csound version 3.56</para>
    <para>October 2002. Added a note from Richard Dobson.</para>
  </refsect1>
</refentry>
