<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="f">
  <refmeta>
    <refentrytitle>f Statement (or Function Table Statement)</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>f Statement (or Function Table Statement)</refname>
    <refpurpose>
      Causes a GEN subroutine to place values in a stored function table.
      <indexterm id="IndexFStatement"><primary>f statement</primary></indexterm>
      <indexterm id="IndexFunctionTableStatement"><primary>function table statement</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      This causes a GEN subroutine to place values in a stored function table for use by instruments.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis><command>f</command> p1  p2  p3  p4 ...</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
       <emphasis>p1</emphasis> -- Table number by which the stored function will be known. A negative number requests that the table be destroyed.   
    </para>

    <para>
       <emphasis>p2</emphasis> -- Action time of function generation (or destruction) in beats. 
    </para>

    <para>
       <emphasis>p3</emphasis> -- Size of function table (i.e.  number of points) Must be a power of 2, or a power-of-2 plus 1 (see below). Maximum table size is 16777216 (2**24) points. 
    </para>

    <para>
       <emphasis>p4</emphasis> -- Number of the GEN routine to be called (see <link linkend="ScoreSineGen"><citetitle>GEN ROUTINES</citetitle></link>). A negative value will cause rescaling to be omitted. 
    </para>

    <para>
       <emphasis>p5</emphasis>
    </para>

    <para>
       <emphasis>p6 ...</emphasis> -- Parameters whose meaning is determined by the particular GEN routine.
    </para>

    <refsect2>
      <title>Special Considerations</title>

      <para>
        Function tables are arrays of floating-point values. Arrays can be of any length in powers of 2; space allocation always provides for 2<superscript>n</superscript> points plus an additional <emphasis>guard point</emphasis>. The guard point value, used during interpolated lookup, can be automatically set to reflect the table's purpose: If <emphasis>size</emphasis> is an exact power of 2, the guard point will be a copy of the first point; this is appropriate for <emphasis>interpolated wrap-around lookup</emphasis> as in <emphasis>oscili</emphasis>, etc., and should even be used for non-interpolating <emphasis>oscil</emphasis> for safe consistency. If <emphasis>size</emphasis> is set to 2 <superscript>n</superscript> + 1, the guard point value automatically extends the contour of table values; this is appropriate for single-scan functions such in <emphasis>envplx</emphasis>, <emphasis>oscil1</emphasis>, <emphasis>oscil1i</emphasis>, etc.
      </para>

      <para>
        Table space is allocated in primary memory, along with instrument data space. The maximum table number used to be 200. This has been changed to be limited by memory only. (Currently there is an internal soft limit of 300, this is automatically extended as required.)
      </para>

      <para>
        An existing function table can be removed by an <emphasis>f statement</emphasis> containing a negative p1 and an appropriate action time. A function table can also be removed by the generation of another table with the same p1. Functions are not automatically erased at the end of a score section.
      </para>

      <para>
        p2 action time is treated in the same way as in <emphasis>i statement</emphasis>s with respect to sorting and modification by <emphasis>t statement</emphasis>s. If an <emphasis>f statement</emphasis> and an <emphasis>i statement</emphasis> have the same p2, the sorter gives the <emphasis>f statement</emphasis> precedence so that the function table will be available during note initialization.
      </para>

      <para>
        An <emphasis>f 0 statement</emphasis> (zero p1, positive p2) may be used to create an action time with no associated action. Such time markers are useful for padding out a score section (see <link linkend="s"><citetitle>s statement</citetitle></link>).
      </para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      Updated August 2002 thanks to a note from &namerasmus;. There is no longer a hard limit of 200 function tables.
    </para>
  </refsect1>
</refentry>
