Skip to content

ftresize

Changes a function table's size at performance time.

This opcode is experimental. Its current implementation does not maintain all the information that table-reading opcodes need. For new code, prefer creating a separate table of the required size with ftgen, then copying the wanted range with ftslice or ftslicei.

Syntax

kunused = ftresize(kfn, ksize)

kunused ftresize kfn, ksize

Performance

kfn is the number of an existing function table.

ksize is the requested size in sample points. Use a positive whole number. The negative-size convention used by ftgen does not apply here.

kunused is required by the opcode's syntax, but the current implementation does not assign it. Do not use it as a table length or a success code.

ftresize runs on every control cycle where the call executes. It has no trigger input. Put it inside a k-rate condition when you want a single resize. It does not resize during initialization. Use ftresizei for that phase.

The operation changes the existing table and keeps its table number. It does not resample or regenerate the data. Existing sample values remain at their indexes where storage is retained. Shrinking does not release the underlying storage, and growing does not initialize the added memory to zero.

Current limits

The implementation prints WARNING: EXPERIMENTAL CODE on its first use in the process. It records a length one point larger than the requested size, and it does not rebuild the table's guard point or lookup information. Do not interpret the reported length as a guarantee that all table readers can use the resized table correctly.

Growing can move the table's storage and allocate memory during performance. Active opcodes may still hold the old address or size. These limits make the opcode unsuitable for resizing tables that a live instrument is using. Input and allocation checks are also incomplete.

Examples

The shared example uses unused scratch tables to show when each form runs. It requests a smaller size and prints the recorded length. It does not use the resized tables for synthesis.

For the performance-time form, a second instrument reads the length after the resize because ftlen runs at initialization. The current implementation reports 9 after a request for 8.

It uses ftresize.csd.

Inspect initialization and performance-time resize behavior
 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
38
39
40
41
42
43
44
45
46
47
48
49
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

// These opcodes are experimental. No oscillator or table reader uses
// these scratch tables. We inspect only their recorded lengths.
instr ResizeAtInit
  iTable = ftgen(0, 0, 16, -2, 1, 2, 3, 4)
  iBefore = ftlen(iTable)

  // The output is not assigned by the current implementation.
  iUnused = ftresizei(iTable, 8)
  iAfter = ftlen(iTable)
  prints("ftresizei requested 8. Recorded length changed from %d to %d.\n", iBefore, iAfter)
  ftfree(iTable, 1)
endin

instr ResizeAtPerf
  iTable = ftgen(0, 0, 16, -2, 1, 2, 3, 4)

  // Run once, on the first control cycle.
  if timeinstk() == 1 then
    kUnused = ftresize(iTable, 8)

    // ftlen is init-rate. A new note can read the changed length.
    event("i", "ReportLength", 0, 0.01, iTable)
  endif

  // Keep the table until ReportLength has finished.
  ftfree(iTable, 1)
endin

instr ReportLength
  iLength = ftlen(p4)
  prints("ftresize requested 8. Recorded length is %d.\n", iLength)
endin
</CsInstruments>
<CsScore>
i "ResizeAtInit" 0   0.1
i "ResizeAtPerf" 0.2 0.1
e
</CsScore>
</CsoundSynthesizer>

See also

ftresizei, ftgen, ftlen, ftslice, ftslicei, ftfree, Function Table Control

Credits

Author John ffitch, 2011.