Skip to content

chncleararray

Sets the contents of one or more array channels to zero.

Use chncleararray after reading an array channel when its contents should not carry over to the next control cycle. The older spelling chnclear_array calls the same implementation. Use chncleararray in new code.

Syntax

chncleararray(Sname1[, Sname2, ...])

chncleararray Sname1[, Sname2, ...]

Initialization

Sname1, Sname2, ... are the names of array channels to clear. Each argument is a string. The opcode has no output.

The channel names resolve at initialization. Changing a name string during performance does not redirect the call to another channel. A name that belongs to a different channel type causes an initialization error.

The call enables output access for each channel, preserving any existing input access. Declare the element type and dimensions with chnarray, or write an array with chnset, before using the channel. chncleararray alone does not allocate an array of a particular shape.

Performance

On each control cycle where it runs, chncleararray sets every element to zero. For an audio array, it clears every sample in each element's audio block. It works with multidimensional arrays too.

Clearing preserves the channel, its element type, dimensions and allocated storage. It does not clear the data during initialization.

Numeric and audio arrays are supported. String arrays and arrays of user-defined structures cause an error because their contents need type-specific cleanup. This opcode does not turn strings into empty strings or reset structure fields.

Call it after the last reader has used the channel in that control cycle. If readers and writers are in separate instruments, their performance order matters. A writer that runs after the clear can put new data into the channel immediately.

For a single audio channel, use chnclear. Here each name identifies a channel whose value is an array. Pass channel names as separate string arguments.

Examples

Instrument 1 writes two audio signals into an array channel. Instrument 2 reads them as a stereo signal, then clears the channel. It runs after instrument 1 and stays active between notes, so the cleared channel supplies silence while no writer is playing.

It uses chncleararray.csd.

Read and clear an audio array channel
 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
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 2
0dbfs = 1

// One channel holds two audio signals. Mode 3 allows input and output.
giShape[] fillarray 2
chnarray("voices", 3, "a", giShape)

instr 1
  aEnvelope = linen(0.15, 0.01, p3, 0.05)
  aLeft = oscili(aEnvelope, 330)
  aRight = oscili(aEnvelope, 440)
  aSignals[] = [aLeft, aRight]
  chnset(aSignals, "voices")
endin

instr 2
  // Instrument 2 reads after instrument 1 has written this cycle.
  aSignals[] = chnget("voices")
  outs(aSignals[0], aSignals[1])

  // Leave silence for the next cycle if no instrument writes new audio.
  chncleararray("voices")
endin
</CsInstruments>
<CsScore>
// Two short notes, with a gap between them.
i 1 0   0.8
i 1 1.4 0.8
// The reader stays active throughout, including the gap and final silence.
i 2 0   2.8
e
</CsScore>
</CsoundSynthesizer>

See also

chnclear_array, chnclear, chnarray, chnget, chnset, Software Bus

Credits

Author Victor Lazzarini, 2024.

New in Csound 7.