Skip to content

getinstance

Returns a reference to the current instrument instance.

Syntax

self:Instr = getinstance()

self:Instr getinstance

Initialization

self refers to the instrument instance containing the call. No new instance is created. Within an instrument, the built-in read-only variable this refers to the same instance.

Use the reference with operations such as isactive, isreleasing or splice. It refers to this particular note, even if other notes use the same instrument definition.

The reference does not extend the note's lifetime. Keep its use within that lifetime, and let Csound manage the current note's cleanup. For the instrument definition, use the built-in read-only variable this_instr, which has type InstrDef.

Examples

The controller obtains its own reference with getinstance and checks its state before starting performance. It uses instance-controls.csd.

Get the controller instance
 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
50
51
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr Tone
  aTone poscil p4, p5
  out aTone
endin

instr 1
  voice:Instr = play(Tone, 0.1, 440)
  self:Instr = getinstance()
  running:b = isactive(self)
  if running then
    prints "Controller is active\n"
  endif

  kTime timeinsts
  ; Pause from half a second to one second, then resume.
  kPause = (kTime >= 0.5 && kTime < 1) ? 1 : 0
  pause(voice, kPause)

  activeNow:B = isactive(voice)
  if activeNow then
    kActive = 1
  else
    kActive = 0
  endif
  printk2 kActive

  ; The instance reads its frequency from p5 during performance.
  kFrequency line 440, p3, 660
  setp(voice, 5, kFrequency)
  kAmplitude linseg 0, 0.01, 0.1, p3 - 0.02, 0.1, 0.01, 0
  setp(voice, 4, kAmplitude)

  ; play has no duration argument. The controller owns its cleanup.
  delete(voice)
endin
</CsInstruments>
<CsScore>
i 1 0 1.5
e
</CsScore>
</CsoundSynthesizer>

See also

isactive, isreleasing, splice, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini.

New in Csound 7.