<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="fog">
  <refmeta>
    <refentrytitle>fog</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>fog</refname>
    <refpurpose>
      Audio output is a succession of grains derived from data in a stored function table
      <indexterm id="IndexFog"><primary>fog</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Audio output is a succession of grains derived from data in a stored function table <emphasis>ifna</emphasis>. The local envelope of these grains and their timing is based on the model of <emphasis>fof</emphasis> synthesis and permits detailed control of the granular synthesis.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>fog</command> xamp, xdens, xtrans, aspd, koct, kband, kris, kdur, kdec, iolaps, ifna, ifnb, itotdur [, iphs] [, itmode] [, iskip]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>iolaps</emphasis> -- number of pre-located spaces needed to hold overlapping grain data. Overlaps are density dependent, and the space required depends on the maximum value of <emphasis>xdens</emphasis> * <emphasis>kdur</emphasis>. Can be over-estimated at no computation cost. Uses less than 50 bytes of memory per <emphasis>iolaps</emphasis>.
    </para>

    <para>
      <emphasis>ifna</emphasis>, <emphasis>ifnb</emphasis> -- table numbers of two stored functions. The first is the data used for granulation, usually from a soundfile (<link linkend="GEN01"><citetitle>GEN01</citetitle></link>). The second is a rise shape, used forwards and backwards to shape the grain rise and decay; this is normally a sigmoid (<link linkend="GEN19"><citetitle>GEN19</citetitle></link>) but may be linear (<link linkend="GEN05"><citetitle>GEN05</citetitle></link>).
    </para>

    <para>
      <emphasis>itotdur</emphasis> -- total time during which this <emphasis>fog</emphasis> will be active. Normally set to p3. No new grain is created if it cannot complete its <emphasis>kdur</emphasis> within the remaining <emphasis>itotdur</emphasis>.
    </para>

    <para>
      <emphasis>iphs</emphasis> (optional) -- initial phase of the fundamental, expressed as a fraction of a cycle (0 to 1). The default value is 0.
    </para>

    <para>
      <emphasis>itmode</emphasis> (optional) -- transposition mode. If zero, each grain keeps the <emphasis>xtrans</emphasis> value it was launched with. if non-zero, each is influenced by <emphasis>xtrans</emphasis> continuously. The default value is 0.
    </para>

    <para>
      <emphasis>iskip</emphasis> (optional, default=0) -- If non-zero, skip initialization (allows legato use).
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>xamp</emphasis> -- amplitude factor. Amplitude is also dependent on the number of overlapping grains, the interaction of the rise shape (<emphasis>ifnb</emphasis>) and the exponential decay (<emphasis>kband</emphasis>), and the scaling of the grain waveform (<emphasis>ifna</emphasis>). The actual amplitude may therefore exceed <emphasis>xamp</emphasis>.
    </para>

    <para>
      <emphasis>xdens</emphasis> -- density. The frequency of grains per second.
    </para>

    <para>
      <emphasis>xtrans</emphasis> -- transposition factor. The rate at which data from the stored function table <emphasis>ifna</emphasis> is read within each grain. This has the effect of transposing the original material. A value of 1 produces the original pitch. Higher values transpose upwards, lower values downwards. Negative values result in the function table being read backwards.
    </para>

    <para>
      <emphasis>aspd</emphasis> -- speed. The rate at which successive grains advance through the stored function table <emphasis>ifna</emphasis>. <emphasis>aspd</emphasis> is in the form of an index (0 to 1) to <emphasis>ifna</emphasis>. This determines the movement of a pointer used as the starting point for reading data within each grain. (<emphasis>xtrans</emphasis> determines the rate at which data is read starting from this pointer.)
    </para>

    <para>
      <emphasis>koct</emphasis> -- octaviation index. The operation of this parameter is identical to that in <emphasis>fof</emphasis>.
    </para>

    <para>
      <emphasis>kband</emphasis>, <emphasis>kris</emphasis>, <emphasis>kdur</emphasis>, <emphasis>kdec</emphasis> -- grain envelope shape. These parameters determine the exponential decay (<emphasis>kband</emphasis>), and the rise (<emphasis>kris</emphasis>), overall duration (<emphasis>kdur</emphasis>,) and decay (<emphasis>kdec</emphasis> ) times of the grain envelope. Their operation is identical to that of the local envelope parameters in <emphasis>fof</emphasis>.
    </para>

    <para>
      The Csound <emphasis>fog</emphasis> generator is by Michael Clarke, extending his earlier work based on IRCAM's fof algorithm.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
;p4 = transposition factor
;p5 = speed factor
;p6 = function table for grain data
i1  = sr/ftlen(p6) ;scaling to reflect sample rate and table length
a1 <emphasis>phasor</emphasis> i1*p5 ;index for speed
a2 <emphasis>fog</emphasis>    5000, 100, p4, a1, 0, 0, , .01, .02, .01, 2, p6, 1, p3, 0, 1
        </programlisting>
      </informalexample>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Michael Clark</member>
        <member>Huddersfield</member>
        <member>May 1997</member>
      </simplelist>
    </para>

    <para>New in version 3.46</para>
    <para>
      The Csound fog generator is by Michael Clarke, extending his earlier work based on IRCAM's fof algorithm.
    </para>
    <para>Added notes by &namerasmus; on September 2002.</para>
  </refsect1>
</refentry>
