
NAMED INSTRUMENTS
-----------------

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.

SYNTAX
------

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

USING NAMED INSTRUMENTS
-----------------------

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:
     1. in score files, unmatched quotes, and spaces or other invalid
        characters in the strings should be avoided, otherwise (at
        least with current version) unpredictable behavior may occur
        (this problem does not exist for -L line events).
        However, there is checking for undefined instruments, and in
        such cases, the event is simply ignored with a warning.
     2. Stand-alone utilities (score sort and extract) do not support
        named instruments. It is still possible to sort such scores
        by using the -t0 option of the main Csound executable)
  * 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.

EXAMPLE
-------

; ---- 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

AUTHOR
------

Istvan Varga
2002

