As a recent addition to the orchestra syntax, instruments can be defined with string names. Such named instruments are callable from the score, and are supported by a number of opcodes.
A named instrument is declared as shown below:
instr Name[, Name2[, Name3[, ...]]] [...] endin
A single instrument can have any number of names, and any of these names can be used to call the instrument. Additionally, it is possible to use numbers as name, denoting a standard numbered instrument, so the following declaration is also valid:
instr 100, Name1, 99, Name2, 1, 2, 3
An instrument name may consist of any number of letters, digits, and the underscore (_) character, however, the first character must not be a digit. Optionally, the instrument name may be prefixed with the '+' character (see below), for example:
instr +Reverb
For all instrument names, a number is automatically assigned (note: if the message level (-m) is not zero, these numbers are printed to the console during orchestra compilation), following these rules:
any unused instrument numbers are taken up in ascending order, starting from 1
the numbers are assigned in the order of instrument name definition, so named instruments that are defined later will always have a higher number (except if the '+' modifier is used)
if the instrument name was prefixed with '+', the assigned number will be higher than that of any of the (both numbered and named) other instruments without '+'. If there are multiple '+' instruments, the numbering of these will follow the order of definition, according to the above rule.
Using '+' is mainly useful for global output or effect instruments, that must be performed after the other instruments.
An example for instrument numbers:
instr 1, 2 endin instr Instr1 endin instr +Effect1, Instr2 endin instr 100, Instr3, +Effect2, Instr4, 5 endin
In this example, the instrument numbers are assigned as follows:
Instr1: 3 Effect1: 101 Instr2: 4 Instr3: 6 Effect2: 102 Instr4: 7
Named instruments can be called by using the name in double quotes as the instrument number (note: the '+' character should be omitted). Currently (as of Csound 4.22.4), named instruments are supported by:
'i' and 'q' score events
Notes | |
---|---|
|
real-time line events (-L)
event, schedkwhen, subinstr, and subinstrinit opcodes
massign, pgmassign, prealloc, and mute opcodes
Additionaly, there is a new opcode (nstrnum) that returns the number of a named instrument:
insno nstrnum "name"
With the above example, nstrnum "Effect1" would return 101. If an instrument with the specified name does not exist, an init error occurs, and -1 is returned.
; ---- orchestra ---- sr = 44100 ksmps = 10 nchnls = 1 prealloc "SineWave", 20 prealloc "MIDISineWave", 20 massign 1, "MIDISineWave" gaOutSend init 0 instr +OutputInstr out gaOutSend clear gaOutSend endin instr SineWave a1 oscils p4, p5, 0 vincr gaOutSend, a1 endin instr MIDISineWave iamp veloc inote notnum icps = cpsoct(inote / 12 + 3) a1 oscils iamp * 100, icps, 0 vincr gaOutSend, a1 endin ; ---- score ---- i "SineWave" 0 2 12000 440 i "OutputInstr" 0 3 e