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

  <refnamediv>
    <refname>vco2init</refname>
    <refpurpose>
      Calculates tables for use by vco2 opcode.
      <indexterm id="IndexVco2init"><primary>vco2init</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>vco2init</emphasis> calculates tables for use by <link linkend="vco2"><citetitle>vco2</citetitle></link> opcode. Optionally, it is also possible to access these tables as standard Csound function tables. In this case, <link linkend="vco2ft"><citetitle>vco2ft</citetitle></link> can be used to find the correct table number for a given oscillator frequency.
    </para>

    <para>
      In most cases, this opcode is called from the orchestra header. Using <emphasis>vco2init</emphasis> in instruments is possible but not recommended. This is because replacing tables during performance can result in a Csound crash if other opcodes are accessing the tables at the same time.
    </para>

    <para>
        Note that <emphasis>vco2init</emphasis> is not required for vco2 to work (tables are automatically allocated by the first vco2 call, if not done yet), however it can be useful in some cases:

      <itemizedlist>
        <listitem><para>Pre-calculate tables at orchestra load time. This is useful to avoid generating the tables during performance, which could interrupt real-time processing.</para></listitem>
        <listitem><para>Share the tables as Csound ftables. By default, the tables can be accessed only by <link linkend="vco2"><citetitle>vco2</citetitle></link>.</para></listitem>
        <listitem><para>Change the default parameters of tables (e.g. size) or use an user-defined waveform specified in a function table.</para></listitem>
      </itemizedlist>
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis>ifn <command>vco2init</command> iwave [, ibasfn] [, ipmul] [, iminsiz] [, imaxsiz] [, isrcft]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifn</emphasis> -- the first free ftable number after the allocated tables. If <emphasis>ibasfn</emphasis> was not specified, -1 is returned.
    </para>

    <para>
      <emphasis>iwave</emphasis> -- sum of the following values selecting which waveforms are to be calculated:

        <itemizedlist>
          <listitem><para>16: triangle</para></listitem>
          <listitem><para>8: square wave</para></listitem>
          <listitem><para>4: pulse (not normalized)</para></listitem>
          <listitem><para>2: 4 * x * (1 - x)   (integrated sawtooth)</para></listitem>
          <listitem><para>1: sawtooth</para></listitem>
        </itemizedlist>
    </para>

    <para>
      Alternatively, <emphasis>iwave</emphasis> can be set to a negative integer that selects an user-defined waveform. This also requires the <emphasis>isrcft</emphasis> parameter to be specified. <link linkend="vco2"><citetitle>vco2</citetitle></link> can access waveform number -1. However, other user-defined waveforms are usable only with <link linkend="vco2ft"><citetitle>vco2ft</citetitle></link> or <link linkend="vco2ift"><citetitle>vco2ift</citetitle></link>.
    </para>

    <para>
      <emphasis>ibasfn</emphasis> (optional, default=-1) -- ftable number from which the table set(s) can be accessed by opcodes other than vco2. This is required by user defined waveforms, with the exception of -1. If this value is less than 1, it is not possible to access the tables calculated by <emphasis>vco2init</emphasis> as Csound function tables.
    </para>

    <para>
      <emphasis>ipmul</emphasis> (optional, default=1.05) -- multiplier value for number of harmonic partials. If one table has n partials, the next one will have n * ipmul (at least n + 1). The allowed range for <emphasis>ipmul</emphasis> is 1.01 to 2. Zero or negative values select the default (1.05).
    </para>

    <para>
      <emphasis>iminsiz</emphasis> (optional, default=-1) -- minimum table size.
    </para>

    <para>
      <emphasis>imaxsiz</emphasis> (optional, default=-1) -- maximum table size.
    </para>

    <para>
      The actual table size is calculated by multiplying the square root of the number of harmonic partials by <emphasis>iminsiz</emphasis>, rounding up the result to the next power of two, and limiting this not to be greater than <emphasis>imaxsiz</emphasis>.
    </para>

    <para>
      Both parameters, <emphasis>iminsiz</emphasis> and <emphasis>imaxsiz</emphasis>, must be power of two, and in the allowed range. The allowed range is 16 to 262144 for <emphasis>iminsiz</emphasis> to up to 16777216 for <emphasis>imaxsiz</emphasis>. Zero or negative values select the default settings:

      <itemizedlist>
        <listitem><para>The minimum size is 128 for all waveforms except pulse (iwave=4). Its minimum size is 256.</para></listitem>
        <listitem><para>The default maximum size is usually the minimum size multiplied by 64, but not more than 16384 if possible. It is always at least the minimum size.</para></listitem>
      </itemizedlist>
    </para>

    <para>
      <emphasis>isrcft</emphasis> (optional, default=-1) -- source ftable number for user-defined waveforms (if <emphasis>iwave</emphasis> < 0). <emphasis>isrcft</emphasis> should point to a function table containing the waveform to be used for generating the table array. The table size is recommended to be at least <emphasis>imaxsiz</emphasis> points. If <emphasis>iwave</emphasis> is not negative (built-in waveforms are used), <emphasis>isrcft</emphasis> is ignored.
    </para>

    <warning>
      <title>Warning</title>
      <para>
        The number and size of tables is not fixed. Orchestras should not depend on these parameters, as they are subject to changes between releases.
      </para>

      <para>
        If the selected table set already exists, it is replaced. If any opcode is accessing the tables at the same time, it is very likely that a crash will occur. This is why it is recommended to use <emphasis>vco2init</emphasis> only in the orchestra header.
      </para>

      <para>
        These tables should not be replaced/overwritten by GEN routines or the ftgen opcode. Otherwise, unpredictable behavior or a Csound crash may occur if <link linkend="vco2"><citetitle>vco2</citetitle></link> is used. The first free ftable after the table array(s) is returned in <emphasis>ifn</emphasis>.
      </para>
    </warning>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      See the example for the <link linkend="vco2"><citetitle>vco2</citetitle></link> opcode.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="vco2ft"><citetitle>vco2ft</citetitle></link>,
      <link linkend="vco2ift"><citetitle>vco2ift</citetitle></link>, and
      <link linkend="vco2"><citetitle>vco2</citetitle></link>.
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>Author: &nameistvan;</para>
    <para>New in version 4.22</para>
  </refsect1>
</refentry>
