<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="envlpx">
  <refmeta>
    <refentrytitle>envlpx</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>envlpx</refname>
    <refpurpose>
      Applies an envelope consisting of 3 segments.
      <indexterm id="IndexEnvlpx"><primary>envlpx</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>envlpx</emphasis> -- apply an envelope consisting of 3 segments:
      <orderedlist>
        <listitem>
          <para>stored function rise shape</para>
        </listitem>

        <listitem>
          <para>modified exponential pseudo steady state</para>
        </listitem>

        <listitem>
          <para>exponential decay</para>
        </listitem>
      </orderedlist>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>ar <command>envlpx</command> xamp, irise, idur, idec, ifn, iatss, iatdec [, ixmod]</synopsis>

    <synopsis>kr <command>envlpx</command> kamp, irise, idur, idec, ifn, iatss, iatdec [, ixmod]</synopsis>
 </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>irise</emphasis> -- rise time in seconds. A zero or negative value signifies no rise modification.
    </para>

    <para>
      <emphasis>idur</emphasis> -- overall duration in seconds. A zero or negative value will cause initialization to be skipped.
    </para>

    <para>
      <emphasis>idec</emphasis> -- decay time in seconds. Zero means no decay. An <emphasis>idec</emphasis> &gt; <emphasis>idur</emphasis> will cause a truncated decay.
    </para>

    <para>
      <emphasis>ifn</emphasis> -- function table number of stored rise shape with extended guard point.
    </para>

    <para>
      <emphasis>iatss</emphasis> -- attenuation factor, by which the last value of the <emphasis>envlpx</emphasis> rise is modified during the note's pseudo steady state. A factor greater than 1 causes an exponential growth and a factor less than 1 creates an exponential decay. A factor of 1 will maintain a true steady state at the last rise value. Note that this attenuation is not by fixed rate (as in a piano), but is sensitive to a note's duration. However, if <emphasis>iatss</emphasis> is negative (or if steady state &lt; 4 k-periods) a fixed attenuation rate of <emphasis>abs</emphasis>(<emphasis>iatss</emphasis>) per second will be used. 0 is illegal.
    </para>

    <para>
      <emphasis>iatdec</emphasis> -- attenuation factor by which the closing steady state value is reduced exponentially over the decay period. This value must be positive and is normally of the order of .01. A large or excessively small value is apt to produce a cutoff which is audible. A zero or negative value is illegal.
    </para>

    <para>
      <emphasis>ixmod</emphasis> (optional, between +- .9 or so) -- exponential curve modifier, influencing the steepness of the exponential trajectory during the steady state. Values less than zero will cause an accelerated growth or decay towards the target (e.g. <emphasis>subito piano</emphasis>). Values greater than zero will cause a retarded growth or decay. The default value is zero (unmodified exponential).
    </para>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kamp, xamp</emphasis> -- input amplitude signal.
    </para>

    <para>
      Rise modifications are applied for the first <emphasis>irise</emphasis> seconds, and decay from time <emphasis>idur - idec</emphasis>. If these periods are separated in time there will be a steady state during which <emphasis>amp</emphasis> will be modified by the first exponential pattern. If the rise and decay periods overlap then that will cause a truncated decay. If the overall duration <emphasis>idur</emphasis> is exceeded in performance, the final decay will continue on in the same direction, tending asymptotically to zero.
    </para>
  </refsect1>

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

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

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

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

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="envlpxr"><citetitle>envlpxr</citetitle></link>, 
      <link linkend="linen"><citetitle>linen</citetitle></link>, 
      <link linkend="linenr"><citetitle>linenr</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Thanks goes to &nameluis; for pointing out a mistake with <emphasis>iatss</emphasis>.</para>
    <para>Example written by &namekevin;.</para>
  </refsect1>
</refentry>
