
ifn     vco2init iwave[, ibasfn[, ipmul[, iminsiz[, imaxsiz[, isrcft]]]]]

DESCRIPTION
-----------

vco2init calculates tables for use by vco2 opcode. It is optionally
also possible to access these tables as standard Csound function
tables (in this case, vco2ft can be used to find the correct table
number for a given oscillator frequency).
In most cases, this opcode is called from the orchestra header (using
vco2init in instruments is possible, but not recommended, because
replacing tables during performance can result in a Csound crash if
other opcodes are accessing the tables at the same time).
Note that vco2init 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:
  - pre-calculate tables at orchestra load time (this is useful to
    avoid generating the tables during performance, which could
    interrupt real-time processing)
  - share the tables as Csound ftables (by default, the tables can be
    accessed only by vco2)
  - change the default parameters of tables (e.g. size), or use an
    user defined waveform specified in a function table

INITIALIZATION
--------------

ifn - the first free ftable number after the allocated tables.
  If ibasfn (see below) was not specified, -1 is returned.

iwave - sum of the following values selecting which waveforms are to
  be calculated:
    16: triangle
     8: square wave
     4: pulse (not normalized)
     2: 4 * x * (1 - x)   (integrated sawtooth)
     1: sawtooth
  Alternatively, iwave can be set to a negative integer that selects
  an user defined waveform (this also requires isrcft to be
  specified); vco2 can access waveform number -1, however, other user
  defined waveforms are usable only with vco2ft, or vco2ift.
  WARNING: 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 vco2init only in the orchestra header.

ibasfn (optional, defaults to -1) - ftable number from which the
  table set(s) can be accessed by opcodes other than vco2 (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 calclulated by vco2init as Csound function tables.
  Note: the number, and size of tables is not fixed, and orchestras
  should not depend on these parameters, as they are subject to
  changes between releases.
  WARNING: these tables should not be replaced / overwritten by GEN
  routines or ftgen opcode, otherwise unpredictable behavior or a
  Csound crash may occur if vco2 is used. The first free ftable after
  the table array(s) is returned in ifn.

ipmul (optional, defaults to -1) - multiplier value for number of
  harmonic partials (i.e. if one table has n partials, the next
  one will have n * ipmul, but at least n + 1). The allowed range for
  this parameter is 1.01 to 2, and zero or negative values select the
  default (1.05).
  ipmul controls how many tables are generated; the number of tables
  is about
    1 + (1 / (ipmul - 1)) + log(maxpnum * (ipmul - 1)) / log(ipmul)
  where "maxpnum" is the maximum number of partials (4096, or maximum
  table size (see below) / 2, depending on which one is less). Thus,
  with the default settings, about 130 tables are created.

iminsiz (optional, defaults to -1),
imaxsiz (optional, defaults to -1) - minimum and maximum table size.
  The actual table size is calculated by multiplying the square root
  of the number of harmonic partials by "iminsiz", rounding up the
  result to the next power of two, and limiting this not to be
  greater than "imaxsiz".
  Both parameters must be power of two, and the allowed range is 16
  to 262144 for iminsiz, and "iminsiz" to 16777216 for imaxsiz.
  Zero, or negative values select the default settings:
    - minimum size is 128 for all waveforms except pulse (iwave=4),
      for which it is 256
    - the default maximum size is the minimum size multiplied by 64,
      but not more than 16384 if possible, and always at least the
      minimum size

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

---------------------------------------------------------------------

ifn     vco2ift icps, iwave[, inyx]
kfn     vco2ft kcps, iwave[, inyx]

DESCRIPTION
-----------

vco2ft returns the function table number to be used for generating
the specified waveform at a given frequency, by any Csound opcode
that generates a signal by reading function tables (e.g. oscilikt).
The tables must be calculated by vco2init before vco2ft is called,
and shared as Csound ftables (ibasfn).
vco2ift is the same as vco2ft, but works at i-time, and is suitable
for use with opcodes that expect an i-rate table number (for example,
oscili).

INITIALIZATION
--------------

ifn - the ftable number returned by vco2ift.

icps - frequency in Hz. Zero and negative values are allowed,
  however, if the absolute value exceeds sr/2 (or sr*inyx), the
  selected table will contain silence.

iwave - the waveform for which table number is to be selected.
  Allowed values are:
    0: sawtooth
    1: 4 * x * (1 - x)   (integrated sawtooth)
    2: pulse (not normalized)
    3: square wave
    4: triangle
  Additionally, negative values select user defined waveforms (see
  also vco2init).

inyx (optional, defaults to 0.5) - bandwidth of the generated
  waveform, as percentage (0 to 1) of the sample rate. The expected
  range is 0 to 0.5 (i.e. up to sr/2), other values are limited to
  the allowed range.
  Setting this parameter to 0.25 (sr/4), or 0.3333 (sr/3) can produce
  a "fatter" sound in some cases, although it is more likely to
  reduce quality.

PERFORMANCE
-----------

kfn - same as ifn, but k-rate.

kcps - same as icps, but k-rate.

---------------------------------------------------------------------

ar      vco2 kamp, kcps[, imode[, kpw[, kphs[, inyx]]]]

DESCRIPTION
-----------

vco2 is similar to vco, but the implementation uses pre-calculated
tables of band-limited waveforms (see also GEN30), rather than
integrating impulses. This opcode can be faster than vco (espacially
if a low control rate is used), and also allows better sound quality.
Additionally, there are more waveforms, and oscillator phase can be
modulated at k-rate. The disadvantage is increased memory usage.
For more details about vco2 tables, see also vco2init and vco2ft.

INITIALIZATION
--------------

imode (optional, defaults to 0) - sum of any of the following values,
    16: enable k-rate phase control (if set, kphs is a required
        k-rate parameter that allows phase modulation)
     1: skip initialization
  and exactly one of these to select the waveform to be generated:
    14: user defined waveform -1 (requires vco2init)
    12: triangle (no ramp, faster)
    10: square wave (no PWM, faster)
     8: 4 * x * (1 - x) (i.e. integrated sawtooth)
     6: pulse (not normalized)
     4: sawtooth / triangle / ramp
     2: square / PWM
     0: sawtooth
  The default is zero, which means a sawtooth wave with no k-rate
  phase control.

inyx (optional, defaults to 0.5) - bandwidth of the generated
  waveform, as percentage (0 to 1) of the sample rate. The expected
  range is 0 to 0.5 (i.e. up to sr/2), other values are limited to
  the allowed range.
  Setting this parameter to 0.25 (sr/4), or 0.3333 (sr/3) can produce
  a "fatter" sound in some cases, although it is more likely to
  reduce quality.

PERFORMANCE
-----------

ar - the output signal.

kamp - amplitude scale (in the case of waveform 6 (pulse), the actual
  output level can be a lot higher than this value).

kcps - frequency in Hz (should be in the range -sr/2 to sr/2).

kpw - pulse width of the square wave (type 2), or ramp
  characteristics of the triangle wave (type 4); it is required only
  by these waveforms, and ignored in all other cases. The expected
  range is 0 to 1, any other value is wrapped to the allowed range.
  WARNING: kpw must not be an exact integer value (e.g. 0 or 1) if
  a sawtooth / triangle ramp (waveform 4) is generated (in this
  case, the recommended range is about 0.01 to 0.99); there is no
  such limitation for square / PWM.

kphs - oscillator phase (depending on imode, this can be either an
  optional i-rate parameter that defaults to zero, or required
  k-rate). Similarly to kpw, the expected range is 0 to 1.

NOTE: pulse width (kpw) and phase (kphs) modulation is internally
converted to frequency modulation for faster processing, and reduced
artifacts when a low control rate is used. However, in the case of
very long notes, and continuous fast changes in kpw or kphs, the phase
may drift away from the requested value; in most cases, the phase
error is at most 0.037 per hour, assuming a sample rate of 44100 Hz.
This is a problem mainly in the case of pulse width (kpw), where it
may result in various artifacts. While future releases of vco2 may
fix such errors, the following work-arounds may also be of some help:

 - use kpw values only in the range 0.05 to 0.95 (there are more
   artifacts around integer values)
 - try to avoid modulating kpw by asymmetrical waveforms like a
   sawtooth wave. Relatively slow (<= 20 Hz), symmetrical modulation
   (e.g. sine or triangle), or (also slow) random splines, or a fixed
   pulse width is a lot less likely to cause synchronization problems.
 - in some cases, adding random jitter (for example random splines
   with an amplitude of about 0.01) to kpw may also fix the problem

EXAMPLE
-------

/* ---- orchestra ---- */

sr      =  44100
ksmps   =  10
nchnls  =  1

; user defined waveform -1: trapezoid wave with default parameters (can be
; accessed at ftables starting from 10000)
itmp    ftgen 1, 0, 16384, 7, 0, 2048, 1, 4096, 1, 4096, -1, 4096, -1, 2048, 0
ift     vco2init -1, 10000, 0, 0, 0, 1
; user defined waveform -2: fixed table size (4096), number of partials
; multiplier is 1.02 (~238 tables)
itmp    ftgen 2, 0, 16384, 7, 1, 4095, 1, 1, -1, 4095, -1, 1, 0, 8192, 0
ift     vco2init -2, ift, 1.02, 4096, 4096, 2

        instr 1
kcps    expon p4, p3, p5                ; instr 1: basic vco2 example
a1      vco2 12000, kcps                ; (sawtooth wave with default
        out a1                          ; parameters)
        endin

        instr 2
kcps    expon p4, p3, p5                        ; instr 2:
kpw     linseg 0.1, p3/2, 0.9, p3/2, 0.1        ; PWM example
a1      vco2 10000, kcps, 2, kpw
        out a1
        endin

        instr 3
kcps    expon p4, p3, p5                ; instr 3: vco2 with user
a1      vco2 14000, kcps, 14            ; defined waveform (-1)
aenv    linseg 1, p3 - 0.1, 1, 0.1, 0   ; de-click envelope
        out a1 * aenv
        endin

        instr 4
kcps    expon p4, p3, p5                ; instr 4: vco2ft example,
kfn     vco2ft kcps, -2, 0.25           ; with user defined waveform
a1      oscilikt 12000, kcps, kfn       ; (-2), and sr/4 bandwidth
        out a1
        endin

/* ---- score ---- */

i 1  0 3 20 2000
i 2  4 2 200 400
i 3  7 3 400 20
i 4 11 2 100 200

f 0 14

e

AUTHOR
------

Istvan Varga
Sep 2002

