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

    <refpurpose>
      Adds a new score event generated by a k-rate trigger.
      <indexterm id="IndexSchedkwhen"><primary>schedkwhen</primary></indexterm>
    </refpurpose>
  </refnamediv>   

  <refsect1>
    <title>Description</title>
    <para>
      Adds a new score event generated by a k-rate trigger.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>

    <synopsis><command>schedkwhen</command> ktrigger, kmintim, kmaxnum, kinsnum, kwhen, kdur [, ip4] [, ip5] [...]</synopsis>
    <synopsis><command>schedkwhen</command> ktrigger, kmintim, kmaxnum, &quot;insname&quot;, kwhen, kdur [, ip4] [, ip5] [...]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis><quote>insname</quote></emphasis> -- A string (in double-quotes) representing a named instrument.
    </para>

    <para>
      <emphasis>ip4, ip5, ...</emphasis> -- Equivalent to p4, p5, etc., in a score <link linkend="i"><citetitle>i statement</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>ktrigger</emphasis> -- triggers a new score event. If <emphasis>ktrigger</emphasis> = 0, no new event is triggered.
    </para>

    <para>
      <emphasis>kmintim</emphasis> -- minimum time between generated events, in seconds. If <emphasis>kmintim</emphasis> &lt;= 0, no time limit exists. If the <emphasis>kinsnum</emphasis> is negative (to turn off an instrument), this test is bypassed.
    </para>

    <para>
      <emphasis>kmaxnum</emphasis> -- maximum number of simultaneous instances of instrument <emphasis>kinsnum</emphasis> allowed. If the number of extant instances of <emphasis>kinsnum</emphasis> is &gt;= <emphasis>kmaxnum</emphasis>, no new event is generated. If <emphasis>kmaxnum</emphasis> is &lt;= 0, it is not used to limit event generation. If the <emphasis>kinsnum</emphasis> is negative (to turn off an instrument), this test is bypassed.
    </para>

    <para>
      <emphasis>kinsnum</emphasis> -- instrument number. Equivalent to p1 in a score <link linkend="i"><citetitle>i statement</citetitle></link>.
    </para>

    <para>
      <emphasis>kwhen</emphasis> -- start time of the new event. Equivalent to p2 in a score <link linkend="i"><citetitle>i statement</citetitle></link>. Measured from the time of the triggering event. <emphasis>kwhen</emphasis> must be &gt;= 0. If <emphasis>kwhen</emphasis> &gt; 0, the instrument will not be initialized until the actual time when it should start performing.
    </para>

    <para>
      <emphasis>kdur</emphasis> -- duration of event. Equivalent to p3 in a score <link linkend="i"><citetitle>i statement</citetitle></link>. If <emphasis>kdur</emphasis> = 0, the instrument will only do an initialization pass, with no performance. If <emphasis>kdur</emphasis> is negative, a held note is initiated. (See <link linkend="ihold"><citetitle>ihold</citetitle></link> and <link linkend="i"><citetitle>i statement</citetitle></link>.)
    </para>

    <para><emphasis>Note</emphasis>: While waiting for events to be triggered by <emphasis>schedkwhen</emphasis>, the performance must be kept going, or Csound may quit if no score events are expected. To guarantee continued performance, an <link linkend="f"><citetitle>f0 statement</citetitle></link> may be used in the score.
    </para>
  </refsect1>

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

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

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

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

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Rasmus Ekman</member>
        <member>EMS, Stockholm, Sweden</member>
      </simplelist>
    </para>
    <para>Example written by &namekevin;.</para>

    <para>New in Csound version 3.59</para>
  </refsect1> 
</refentry>
