<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="GEN01">
  <refmeta>
    <refentrytitle>GEN01</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>GEN01</refname>
    <refpurpose>
      Transfers data from a soundfile into a function table.
      <indexterm id="IndexGEN01"><primary>GEN01</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      This subroutine transfers data from a soundfile into a function table.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis><command>f</command>#  time  size  1  filcod  skiptime  format  channel</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>size</emphasis> -- number of points in the table. Ordinarily a power of 2 or a power-of-2 plus 1 (see <link linkend="f"><citetitle>f statement</citetitle></link>); the maximum tablesize is 16777216 (2<superscript>24</superscript>) points. The allocation of table memory can be <emphasis>deferred</emphasis> by setting this parameter to 0; the size allocated is then the number of points in the file (probably not a power-of-2), and the table is not usable by normal oscillators, but it is usable by a <link linkend="loscil"><citetitle>loscil</citetitle></link> unit. The soundfile can also be mono or stereo.
    </para>

    <para>
      <emphasis>filcod</emphasis> -- integer or character-string denoting the source soundfile name. An integer denotes the file <emphasis>soundin</emphasis>.<emphasis>filcod</emphasis> ; a character-string (in double quotes, spaces permitted) gives the filename itself, optionally a full pathname. If not a full path, the file is sought first in the current directory, then in that given by the environment variable SSDIR (if defined) then by SFDIR. See also <link linkend="soundin"><citetitle>soundin</citetitle></link>.
    </para>

    <para>
      <emphasis>skiptime</emphasis> -- begin reading at <emphasis>skiptime</emphasis> seconds into the file.
    </para>

    <para>
      <emphasis>channel</emphasis> -- channel number to read in. 0 denotes read all channels.
    </para>

    <para>
      <emphasis>format</emphasis> -- specifies the audio data-file format:
        <literallayout>
1 - 8-bit signed character    4 - 16-bit short integers 
2 - 8-bit A-law bytes         5 - 32-bit long integers 
3 - 8-bit U-law bytes         6 - 32-bit floats
        </literallayout>
    </para>

    <para>
      If <emphasis>format</emphasis> = 0 the sample format is taken from the soundfile header, or by default from the CSound <link linkend="FlagsMinusLowerO"><citetitle>-o</citetitle></link> command-line flag.
    </para>

    <note>
      <title>Note</title>
      <para>
        <itemizedlist>
          <listitem>
            <para>
              Reading stops at end-of-file or when the table is full. Table locations not filled will contain zeros.
            </para>
          </listitem>

          <listitem>
            <para>
              If p4 is positive, the table will be post-normalized (rescaled to a maximum absolute value of 1 after generation). A negative p4 will cause rescaling to be skipped.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </note>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      Here is a simple example of the GEN01 routine. It uses the files <ulink url="examples/gen01.orc"><citetitle>gen01.orc</citetitle></ulink>, <ulink url="examples/gen01.sco"><citetitle>gen01.sco</citetitle></ulink>, and <ulink url="examples/beats.wav"><citetitle>beats.wav</citetitle></ulink>. It uses the audio file <quote>beats.wav</quote>, here is its diagram:
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/gen01.png" format="PNG">
        </imageobject>

        <textobject>
          <phrase>Diagram of the waveform generated by GEN01.</phrase>
        </textobject>

        <caption>
          <para>Diagram of the waveform generated by GEN01.</para>
        </caption>
      </mediaobject>

      <example>
        <title>A simple example of the GEN01 routine.</title>

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

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

    <para>
      Here is another example of the GEN01 routine. Csound will automatically compute the tablesize because we have set it to 0. This example uses the files <ulink url="examples/gen01computed.orc"><citetitle>gen01computed.orc</citetitle></ulink>, <ulink url="examples/gen01computed.sco"><citetitle>gen01computed.sco</citetitle></ulink>, and <ulink url="examples/beats.wav"><citetitle>beats.wav</citetitle></ulink>.

      <example>
        <title>An example of the GEN01 routine with a computed tablesize.</title>

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

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

  <refsect1>
    <title>Credits</title>
    <para>Examples written by &namekevin;</para>
    <para>December 2002. Thanks goes to Kanata Motohashi for fixing mistakes in the examples.</para>
    <para>September 2003. Thanks goes to Dr. Richard Boulanger for pointing out the references to the AIFF file format. GEN01 also works with WAV files.</para>
  </refsect1>
</refentry>
