<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="grain2">
  <refmeta>
    <refentrytitle>grain2</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>grain2</refname>
    <refpurpose>
      Easy-to-use granular synthesis texture generator.
      <indexterm id="IndexGrain2"><primary>grain2</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Generate granular synthesis textures. <emphasis>grain2</emphasis> is simpler to use, but <emphasis>grain3</emphasis> offers more control.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>grain2</command> kcps, kfmd, kgdur, iovrlp, kfn, iwfn [, irpow] [, iseed] [, imode]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>iovrlp</emphasis> -- (fixed) number of overlapping grains.
    </para>

    <para>
      <emphasis>iwfn</emphasis> -- function table containing window waveform (Use <link linkend="GEN20">GEN20</link> to calculate iwfn).
    </para>

    <para>
      <emphasis>irpow</emphasis> (optional, default=0) -- this value controls the distribution of grain frequency variation.  If irpow is positive, the random distribution (x is in the range -1 to 1) is <literallayout>abs(x) &circ; ((1 / irpow) - 1)</literallayout>; for negative irpow values, it is <literallayout>(1 - abs(x)) &circ; ((-1 / irpow) - 1)</literallayout>. Setting irpow to -1, 0, or 1 will result in uniform distribution (this is also faster to calculate). The image below shows some examples for irpow. The default value of irpow is 0.
    </para>

    <para>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/grain2_rand-448x289.png" format="PNG">
        </imageobject>

        <textobject>
          <phrase>[A graph of distributions for different values of irpow.]</phrase>
        </textobject>

        <caption>
          <para>A graph of distributions for different values of irpow.</para>
        </caption>
      </mediaobject>
    </para>

    <para>
      <emphasis>iseed</emphasis> (optional, default=0) -- seed value for random number generator (positive integer in the range 1 to 2147483646 (2 &circ; 31 - 2)). Zero or negative value seeds from current time (this is also the default).
    </para>

    <para>
      <emphasis>imode</emphasis> (optional default=0) -- sum of the following values:
      <itemizedlist>
        <listitem><para><emphasis>8:</emphasis> interpolate window waveform (slower).</para></listitem>
        <listitem><para><emphasis>4:</emphasis> do not interpolate grain waveform (fast, but lower quality).</para></listitem>
        <listitem><para><emphasis>2:</emphasis> grain frequency is continuously modified by <emphasis>kcps</emphasis> and <emphasis>kfmd</emphasis> (by default, each grain keeps the frequency it was launched with). This may be slower at high control rates.</para></listitem>
        <listitem><para><emphasis>1:</emphasis> skip initialization.</para></listitem>
      </itemizedlist>
    </para>

    <para>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/grain3_2.png" format="PNG">
        </imageobject>

        <textobject>
          <phrase>[A diagram showing grains with a start time less than zero in red.]</phrase>
        </textobject>

        <caption>
          <para>A diagram showing grains with a start time less than zero in red.</para>
        </caption>
      </mediaobject>
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>ar</emphasis> -- output signal.
    </para>

    <para>
      <emphasis>kcps</emphasis> -- grain frequency in Hz.
    </para>

    <para>
      <emphasis>kfmd</emphasis> -- random variation (bipolar) in grain frequency in Hz.
    </para>

    <para>
      <emphasis>kgdur</emphasis> -- grain duration in seconds. <emphasis>kgdur</emphasis> also controls the duration of already active grains (actually the speed at which the window function is read). This behavior does not depend on the <emphasis>imode</emphasis> flags.
    </para>

    <para>
      <emphasis>kfn</emphasis> -- function table containing grain waveform. Table number can be changed at k-rate (this is useful to select from a set of band-limited tables generated by <link linkend="GEN30">GEN30</link>, to avoid aliasing).
    </para>

    <note>
      <title>Note</title>
      <para>
        <emphasis>grain2</emphasis> internally uses the same random number generator as <emphasis>rnd31</emphasis>. So reading <link linkend="rnd31"><citetitle>its documentation</citetitle></link> is also recommended.
      </para>
    </note>
  </refsect1>

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

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="grain3"><citetitle>grain3</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &nameistvan;</member>
      </simplelist>
    </para>

    <para>New in version 4.15</para>
    <para>Updated April 2002 by &nameistvan;</para>
  </refsect1>
</refentry>
