vco2init

vco2init — Calculates tables for use by vco2 opcode.

Description

vco2init calculates tables for use by vco2 opcode. Optionally, it is 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. This is 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.

Syntax

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

Initialization

ifn -- the first free ftable number after the allocated tables. If ibasfn 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 the isrcft parameter to be specified. vco2 can access waveform number -1. However, other user-defined waveforms are usable only with vco2ft or vco2ift.

ibasfn (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 vco2init as Csound function tables.

ipmul (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 ipmul is 1.01 to 2. Zero or negative values select the default (1.05).

iminsiz (optional, default=-1) -- minimum table size.

imaxsiz (optional, default=-1) -- 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, iminsiz and imaxsiz, must be power of two, and in the allowed range. The allowed range is 16 to 262144 for iminsiz to up to 16777216 for imaxsiz. Zero or negative values select the default settings:

  • The minimum size is 128 for all waveforms except pulse (iwave=4). Its minimum size is 256.

  • 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.

isrcft (optional, default=-1) -- source ftable number for user-defined waveforms (if iwave < 0). isrcft 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 imaxsiz points. If iwave is not negative (built-in waveforms are used), isrcft is ignored.

[Warning] Warning

The number and size of tables is not fixed. Orchestras should not depend on these parameters, as they are subject to changes between releases.

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.

These tables should not be replaced/overwritten by GEN routines or the 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.

Examples

See the example for the vco2 opcode.

See Also

vco2ft, vco2ift, and vco2.

Credits

Author: Istvan Varga

New in version 4.22