Skip to content

opcoderef

Gets an opcode definition by name.

Use opcoderef when an opcode name comes from a string, such as a score parameter or a configuration choice. It returns an OpcodeDef that you can pass to create.

Syntax

definition:OpcodeDef = opcoderef(Sname)

definition:OpcodeDef opcoderef Sname

Initialization

Sname is the name of an available opcode, such as "oscili". Names are case-sensitive. A user-defined opcode can also be looked up once its definition has been compiled. An unknown name causes an initialization error.

definition holds the opcode definition and its available overloads. The lookup runs at initialization. Changing Sname during performance does not change the result.

opcoderef does not create or run an opcode object. Pass the definition to create to make an Opcode, then use run or separate init and perf calls to execute it. Arrange delete for the created object when its containing instrument ends.

An overload is a version of an opcode with a particular set of input and output types. Use opcodeinfo to list the definition's overloads, then choose one with the zero-based overload argument to create. The default is 0.

A suffix after a dot does not select an overload in this lookup. For example, opcoderef("oscili.kk") returns the same set of overloads as opcoderef("oscili").

When the name is fixed in the orchestra, you can use its OpcodeDef directly, as in create(oscili). Initializing an OpcodeDef from a string also uses the same lookup.

 definition:OpcodeDef init "oscili"

Examples

This example chooses an oscillator from a name in score field p4. The same instrument plays a sine wave with oscili, then a sawtooth wave with vco2. Both use overload 0 with amplitude and frequency inputs. Other opcode choices may need different arguments or an explicit overload number.

It uses opcoderef.csd.

Choose an oscillator by its name
 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
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

instr NamedOscillator
  // The score chooses which oscillator this note uses.
  SName = strget(p4)
  definition:OpcodeDef = opcoderef(SName)
  oscillator:Opcode = create(definition)

  // Overload 0 of both choices accepts amplitude and frequency.
  aTone = run(oscillator, 0.15, 220)
  aEnvelope = linen(1, 0.01, p3, 0.05)
  out(aTone * aEnvelope)

  // Release this note's oscillator when the instrument ends.
  delete(oscillator)
endin
</CsInstruments>
<CsScore>
// A sine wave, followed by a sawtooth at the same pitch.
i "NamedOscillator" 0   1.5 "oscili"
i "NamedOscillator" 1.8 1.5 "vco2"
e
</CsScore>
</CsoundSynthesizer>

See also

opcodeinfo, create, init, perf, delete, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini, 2024.

New in Csound 7.