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

  <refnamediv>
    <refname>seqtime</refname>
    <refpurpose>
      Generates a trigger signal according to the values stored in a table.
      <indexterm id="IndexSeqtime"><primary>seqtime</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      Generates a trigger signal according to the values stored in a table.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>ktrig_out <command>seqtime</command> ktime_unit, kstart, kloop, kinitndx, kfn_times</synopsis>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>ktrig_out</emphasis> -- output trigger signal
    </para>

    <para>
      <emphasis>ktime_unit</emphasis> -- unit of measure of time, related to seconds.
    </para>

    <para>
      <emphasis>kstart</emphasis> -- start index of looped section
    </para>

    <para>
      <emphasis>kloop</emphasis> -- end index of looped section
    </para>

    <para>
      <emphasis>kinitndx</emphasis> -- initial index
    </para>

    <note>
      <title>Note</title>
      <para>
        Although <emphasis>kinitndx</emphasis> is listed as k-rate, it is in fact accessed only at init-time. So if you are using a k-rate argument, it must be assigned with <link linkend="init"><citetitle>init</citetitle></link>.
      </para>
    </note>

    <para>
      <emphasis>kfn_times</emphasis> -- number of table containing a sequence of times
    </para>

    <para>
      This opcode handles timed-sequences of groups of values stored into a table.
    </para>

    <para>
      <emphasis>seqtime</emphasis> generates a trigger signal (a sequence of impulses, see also <link linkend="trigger"><citetitle>trigger</citetitle></link> opcode), according to the values stored in the <emphasis>kfn_times</emphasis> table. This table should contain a series of delta-times (i.e. times beetween to adjacent events). The time units stored into table are expressed in seconds, but can be rescaled by means of ktime_unit argument. The table can be filled with <link linkend="GEN02"><citetitle>GEN02</citetitle></link> or by means of an external text-file containing numbers, with <link linkend="GEN23"><citetitle>GEN23</citetitle></link>. 
    </para>

    <para>
      It is possible to start the sequence from a value different than the first, by assigning to <emphasis>initndx</emphasis> an index different than zero (which corresponds to the first value of the table). Normally the sequence is looped, and the start and end of loop can be adjusted by modifying <emphasis>kstart</emphasis> and <emphasis>kloop</emphasis> arguments. User must be sure that values of these arguments (as well as <emphasis>initndx</emphasis>) correspond to valid table numbers, otherwise Csound will crash (because no range-checking is implementeted). 
    </para>

    <para>
      It is possible to disable loop (one-shot mode) by assigning the same value both to <emphasis>kstart</emphasis> and <emphasis>kloop</emphasis> arguments. In this case, the last read element will be the one corresponding to the value of such arguments.  Table can be read backward by assigning a negative <emphasis>kloop</emphasis> value. It is possible to trigger two events almost at the same time (actually separated by a k-cycle) by giving a zero value to the corresponding delta-time.  First element contained in the table should be zero, if the user intends to send a trigger impulse, it should come immediately after the orchestra instrument containing <emphasis>seqtime</emphasis> opcode.
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      <example>
        <title>Example of the seqtime opcode.</title>

        <programlisting>
        instr   1
icps    cpsmidi
iamp    ampmidi 5000
ktrig   seqtime 1,       1,          10,      0,   1
trigseq ktrig, 0, 10, 0, 2, kdur, kampratio, kfreqratio
        schedkwhen      ktrig, -1, -1, 2, 0, kdur, kampratio*iamp, kfreqratio*icps
        endin


        instr  2
**** put here your intrument code *******
        out     a1
        endin
        </programlisting>
      </example>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="GEN02"><citetitle>GEN02</citetitle></link>,
      <link linkend="GEN23"><citetitle>GEN23</citetitle></link>,
      <link linkend="trigseq"><citetitle>trigseq</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Author: &namegabriel;</para>
    <para>November 2002. Added a note about the <emphasis>kinitndx</emphasis> parameter, thanks to &namerasmus;.</para>
    <para>New in version 4.06</para>
  </refsect1>
</refentry>
