<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="randh">
  <refmeta>
    <refentrytitle>randh</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>randh</refname>
    <refpurpose>
      Generates random numbers and holds them for a period of time.
      <indexterm id="IndexRandh"><primary>randh</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Generates random numbers and holds them for a period of time.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>randh</command> xamp, xcps [, iseed] [, isize] [, ioffset]</synopsis>

    <synopsis>kr <command>randh</command> kamp, kcps [, iseed] [, isize] [, ioffset]</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>iseed</emphasis> (optional, default=0.5) -- seed value for the recursive pseudo-random formula. A value between 0 and +1 will produce an initial output of <emphasis>kamp * iseed.</emphasis> A value greater than 1 will be used directly, without scaling. A negative value will cause seed re-initialization to be skipped. The default seed value is .5.
    </para>

    <para>
      <emphasis>isize</emphasis> (optional, default=0) -- if zero, a 16 bit number is generated. If non-zero, a 31-bit random number is generated. Default is 0.
    </para>

    <para>
      <emphasis>ioffset</emphasis> (optional, default=0) -- a base value added to the random result. New in Csound version 4.03.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kamp, xamp</emphasis> -- range over which random numbers are distributed.
    </para>

    <para>
      <emphasis>kcps, xcps</emphasis> -- the frequency which new random numbers are generated.
    </para>

    <para>
      The internal pseudo-random formula produces values which are uniformly distributed over the range -<emphasis>kamp</emphasis> to +<emphasis>kamp</emphasis>. <emphasis>rand</emphasis> will thus generate uniform white noise with an R.M.S value of <emphasis>kamp / root 2</emphasis>.
    </para>

    <para>
      The remaining units produce band-limited noise: the <emphasis>kcps</emphasis> and <emphasis>xcps</emphasis> parameters permit the user to specify that new random numbers are to be generated at a rate less than the sampling or control frequencies. <emphasis>randh</emphasis> will hold each new number for the period of the specified cycle.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      Here is an example of the randh opcode. It uses the files <ulink url="examples/randh.orc"><citetitle>randh.orc</citetitle></ulink> and <ulink url="examples/randh.sco"><citetitle>randh.sco</citetitle></ulink>.

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="rand"><citetitle>rand</citetitle></link>,
      <link linkend="randi"><citetitle>randi</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Example written by &namekevin;.</para>
  </refsect1>
</refentry>
