Skip to content

table3kt

Reads a function table with cubic interpolation and a table number that can change at control rate.

Use table3kt to switch waveforms or lookup curves while an instrument runs. It works like table3, with a k-rate table number.

Syntax

ares = table3kt(andx, kfn [, ixmode] [, ixoff] [, iwrap])
kres = table3kt(kndx, kfn [, ixmode] [, ixoff] [, iwrap])

ares table3kt andx, kfn [, ixmode] [, ixoff] [, iwrap]
kres table3kt kndx, kfn [, ixmode] [, ixoff] [, iwrap]

Initialization

ixmode chooses the units for the index and offset. The default is 0, for positions measured in table elements. A nonzero value uses normalized positions, where 0 is the start and 1 is one full table length.

ixoff adds an offset to the index before lookup. It uses the same units as the index and defaults to 0. For example, 0.5 in normalized mode shifts the read position by half the table length.

iwrap selects boundary handling. Use 0 for limit mode or 1 for wrap mode. The default is 0.

Performance

andx or kndx gives the read position. Use an audio-rate index for audio output and a control-rate index for control output. Fractional positions read between table elements. There is no initialization-only output form.

kfn selects the function table. Use an integer table number. The opcode looks up the table each control cycle, including for audio output, so changing kfn takes effect on the next lookup. Select an existing table with a valid length. A lookup failure reports an error and stops the instrument. Csound 7 also accepts 0 or -1 for its built-in sine table.

The selected tables can have different lengths, including lengths that are not powers of two. In normalized mode, the index and offset scale to the current table's length each control cycle. In raw mode, they stay in units of table elements.

Changing kfn switches tables directly. Cubic interpolation works between values within the selected table, not between table numbers. A switch can click if the two tables give different values at that position. Fade the output around the switch or crossfade two separate readers when you need a smooth change.

Interpolation and boundaries

The opcode uses four neighboring values for cubic interpolation in the interior of a table. It uses linear interpolation in the first and last intervals, and throughout tables with fewer than four elements. Cubic interpolation can produce values beyond the range of the stored values.

The table's guard point supplies the value after the last element. For a repeating waveform, it should match the first element. GEN10 creates this guard point, and tablegpw can update it after table writes.

In wrap mode, positions wrap by the table length. Negative positions wrap too. A normalized position of 1 returns to the start.

In limit mode, the integer part of an out-of-range position stops at the first or last element, but the fractional part still affects interpolation. This is not a strict clamp to an endpoint value. Keep the total index within the intended range when using limit mode. A normalized position of exactly 1 reads the last ordinary element, rather than the guard point.

Examples

The example uses a 220 Hz phasor to read two waveforms. It starts with a sine wave and switches after two seconds to a table with three harmonics. The tables have different lengths, so normalized indexing keeps the pitch the same.

A short fade reaches zero at the switch. Wrap mode makes the phasor's repeating 0 to 1 range loop through each table.

It uses table3kt.csd.

Switch waveforms while keeping the same pitch
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<CsoundSynthesizer>
<CsOptions>
-d -o dac
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

giSine ftgen 0, 0, 1024, 10, 1
giHarmonics ftgen 0, 0, 2048, 10, 1, 0.5, 0.25

instr ChangeWaveform
  // Switch tables halfway through the four-second note.
  kTime = timeinsts()
  if kTime < 2 then
    kTable = giSine
  else
    kTable = giHarmonics
  endif

  // The same normalized phase works with both table lengths.
  aPhase = phasor(220)
  aWave = table3kt(aPhase, kTable, 1, 0, 1)

  // Fade out at two seconds, then fade in with the new waveform.
  aEnvelope = linseg(0, 0.05, 0.2, 1.9, 0.2, 0.05, 0, \
                    0.05, 0.2, 1.9, 0.2, 0.05, 0)
  out(aWave * aEnvelope)
endin
</CsInstruments>
<CsScore>
i "ChangeWaveform" 0 4
e
</CsScore>
</CsoundSynthesizer>

See also

table3, tablekt, tableikt, tablexkt, phasor, Table reading with dynamic selection

Credits

Author Victor Lazzarini, 2013.