Skip to content

init

Initializes variables, arrays, user-defined structs and object instances.

init runs at initialization. It does not update its outputs during performance.

Syntax

var:{a,k,i,S,OpcodeDef}[,...] = init(arg:{i,S}[,...])
array:T[] = init(size1:i[,size2:i,...])
array:T[] = init(source:T[])
value:Type = init()
value:Type = init(member1[,member2,...])
value:Type = init(source:Type)
err:i = init(inst:Instr[,p4:i,...])
[var:*,... =] init(op:Opcode[,arg1:*,...])

ares[,...] init iarg[,...] 
ires[,...] init iarg[,...] 
kres[,...]  init iarg[,...] 
ares[] init size1[,size2, ...]
kres[] init size1[,size2, ...]
ires[] init size1[,size2, ...]
Sres[] init size1[,size2, ...]
array:Type[] init size1[,size2, ...]
array:T[] init source:T[]
value:Type init
value:Type init member1[,member2,...]
value:Type init source:Type
ierr init inst:Instr[,p4:i,...]
[xvar,...] init op:Opcode[,arg1:*,...]

Initialization

Variables

The scalar form stores an init-time value in a variable. For a k-rate variable, that value remains until another statement changes it. For an a-rate variable, init fills its audio block with the value. A string input initializes a string variable. To initialize an OpcodeDef, pass the name of an existing opcode as a string.

The numeric form can initialize up to 24 variables of the same type in one statement. If there are fewer inputs than outputs, it repeats the last input for the remaining outputs. More inputs than outputs is an error.

Arrays

T is the element type, such as i, k, a, S or a user-defined struct type. Array initialization takes one i-rate size for each dimension. One size creates a one-dimensional array. Two sizes create a two-dimensional array, and so on. The arguments give sizes rather than element values.

vector:i[] = init(2)    ; two elements
grid:i[] = init(2, 3)   ; two rows of three elements
names:S[] = init(2)     ; two strings

iVector[] init 2
iGrid[][] init 2, 3
SNames[] init 2

The number of size arguments determines the number of dimensions. In classic syntax, repeated brackets can also show the dimensions in the variable declaration. iGrid[] init 2, 3 allocates the same shape as iGrid[][] init 2, 3.

New numeric elements start at zero and new strings start empty. A 2 by 3 array contains six elements. Its first element is grid[0][0] and its last is grid[1][2]. Use lenarray to read the number of dimensions and their sizes. To supply element values instead of sizes, use fillarray.

Passing an existing array of the same element type to init copies its shape and contents at initialization.

User-defined types and structs

In Csound 7, struct defines a user-defined type (UDT) with named members. Type in the syntax above stands for that type's name. Declare the type in the orchestra header and give each member a type.

struct Point x:i, y:i

instr 1
  origin:Point = init()
  point:Point = init(3, 4)
  copied:Point = init(point)
  print(copied.x, copied.y)
endin

With no arguments, a new struct keeps its default member values. Numeric members start at zero and string members start empty. This form does not reset members that already hold values.

To set members, supply one argument for each member, in declaration order and with matching types. A struct can contain another struct or an array. Pass those values as arguments too. You must supply all members or none. Unlike the numeric scalar form, struct initialization does not repeat the last argument to fill missing members.

Passing a struct of the same type initializes the output from its member values. Use a dot to read or write a member, such as point.x.

For an array of structs, the arguments are array sizes. For example, points:Point[] = init(2) creates two points with default member values. An array member inside a struct starts without elements. Initialize that array before indexing it, or pass an initialized array to the struct's member-based init form.

Instrument and opcode objects

For an Instr instance, init runs its initialization pass and returns 0 on success or an error code. The optional numeric arguments supply p4, p5 and the following p-fields. It sets p2 to 0 and p3 to -1. This does not add the instance to Csound's performance list. Use perf to perform it manually after initialization.

For opcode objects, the code runs the initialisation routine (if it exists) defined for the opcode. The input arguments and outputs should match the opcode signature for the object being initialised.

Examples

Here is an example of the init opcode. It uses the file init.csd.

Example of the init opcode.
 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
<CsoundSynthesizer> 
<CsOptions>
; Select audio/midi flags here according to platform
-n  ;no sound output
</CsOptions>
<CsInstruments> 

sr     = 44100
ksmps  = 32
nchnls = 2
0dbfs  = 1

instr 1 ;shows what init does
        kinit init 0 
        kinit = kinit + 1 
        printk .1, kinit 
endin 

instr 2 ;shows what an assignment does
        knoinit = 0 
        knoinit = knoinit + 1 
        printk .1, knoinit 
endin 
</CsInstruments> 
<CsScore> 
;play one second each
i1 0 1 
i2 2 1 
e
</CsScore> 
</CsoundSynthesizer>

Its output should include lines like these:

i   1 time     0.00073:     1.00000
i   1 time     0.10014:   138.00000
i   1 time     0.20027:   276.00000
i   1 time     0.30041:   414.00000
i   1 time     0.40054:   552.00000
i   1 time     0.50068:   690.00000
i   1 time     0.60009:   827.00000
i   1 time     0.70023:   965.00000
i   1 time     0.80036:  1103.00000
i   1 time     0.90050:  1241.00000

i   2 time     2.00054:     1.00000
i   2 time     2.09995:     1.00000
i   2 time     2.20009:     1.00000
i   2 time     2.30023:     1.00000
i   2 time     2.40036:     1.00000
i   2 time     2.50050:     1.00000
i   2 time     2.59991:     1.00000
i   2 time     2.70005:     1.00000
i   2 time     2.80018:     1.00000
i   2 time     2.90032:     1.00000

Arrays

These examples allocate numeric and string arrays, then read and change individual elements.

init-arrays-modern.csd

Initializing arrays
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr 1
  ; Each argument gives the size of one dimension.
  vector:i[] = init(2)
  grid:i[] = init(2, 3)
  names:S[] = init(2)
  controls:k[] = init(3)
  signals:a[] = init(2)

  prints("Vector length = %d\n", lenarray(vector))
  prints("Grid dimensions = %d, sizes = %d x %d\n", \
         lenarray(grid, 0), lenarray(grid, 1), lenarray(grid, 2))
  prints("Initial grid value = %.0f\n", grid[1][2])
  prints("Initial string = '%s'\n", names[0])

  grid[1][2] = 7
  names[0] = "first"
  prints("Assigned grid value = %.0f, string = '%s'\n", grid[1][2], names[0])
endin
</CsInstruments>
<CsScore>
i 1 0 0.1
e
</CsScore>
</CsoundSynthesizer>

init-arrays.csd

Initializing arrays
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr 1
  ; Each argument gives the size of one dimension.
  iVector[] init 2
  iGrid[][] init 2, 3
  SNames[] init 2
  kControls[] init 3
  aSignals[] init 2

  prints "Vector length = %d\n", lenarray(iVector)
  prints "Grid dimensions = %d, sizes = %d x %d\n", \
         lenarray(iGrid, 0), lenarray(iGrid, 1), lenarray(iGrid, 2)
  prints "Initial grid value = %.0f\n", iGrid[1][2]
  prints "Initial string = '%s'\n", SNames[0]

  iGrid[1][2] = 7
  SNames[0] = "first"
  prints "Assigned grid value = %.0f, string = '%s'\n", iGrid[1][2], SNames[0]
endin
</CsInstruments>
<CsScore>
i 1 0 0.1
e
</CsScore>
</CsoundSynthesizer>

Both examples print these values.

Vector length = 2
Grid dimensions = 2, sizes = 2 x 3
Initial grid value = 0
Initial string = ''
Assigned grid value = 7, string = 'first'

Structs

init-structs.csd shows default members, member-based initialization, a struct copy, nested structs and an array of structs.

Initializing structs
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

struct Point x:i, y:i
struct NamedPoint name:S, position:Point
struct Curve points:Point[], label:S

instr 1
  ; No arguments leave a new struct's members at their defaults.
  origin:Point = init()
  prints("Default point = %.0f, %.0f\n", origin.x, origin.y)

  ; Supply one value per member, in declaration order.
  point:Point = init(3, 4)
  named:NamedPoint = init("start", point)
  prints("%s = %.0f, %.0f\n", named.name, named.position.x, named.position.y)

  ; Copy the values of a struct of the same type at initialization.
  copied:Point = init(point)
  prints("Copied point = %.0f, %.0f\n", copied.x, copied.y)

  ; Array init takes sizes even when the elements are structs.
  points:Point[] = init(2)
  points[0] = origin
  points[1] = point
  curve:Curve = init(points, "path")
  prints("%s has %d points, last x = %.0f\n", \
         curve.label, lenarray(curve.points), curve.points[1].x)
endin
</CsInstruments>
<CsScore>
i 1 0 0.1
e
</CsScore>
</CsoundSynthesizer>

Instrument and opcode objects

The following example shows the init opcode in the context of instrument and opcode initialisation.

Examples of the instrument definition, instance and opcode init.
 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
<CsoundSynthesizer>
<CsOptions>
-o dac
</CsOptions>
<CsInstruments>
0dbfs = 1

opcode Osci(a:k,f:k):a
  xout oscili(a,f)
endop

instr One

 // run at i-time
  myInstr:InstrDef = create({{ out Osci(p4,p5) }})
  myInstance:Instr = create(myInstr)
  err1:i = init(myInstance)

  // env, gliss
  env:k = linen(0.5,0.1,p3,0.1)
  slid:k = expon(440, p3, 880)

  // set p5
  setp(myInstance, 5, slid)
  // run at perf-time, set p4
  err2:k = perf(myInstance,env)

  // run at deinit time
  delete(myInstance) 
  delete(myInstr)

  // schedule instr def
  schedule(Two,0,2,0.5,1000)

endin

instr Two
 obj:Opcode = create(oscili)
 sig:a = init(obj, p4, p5)
 sig:a = perf(obj, p4, p5)
   out(sig*adsr(0.1,0.1,0.5,0.1))
 event_i("e", 0, 3)
endin

schedule(One,0,1)

</CsInstruments>
<CsScore>
</CsScore>
</CsoundSynthesizer>

See also

create, run, perf, delete, Instrument definitions, instances and opcode objects

Initialization and Reinitialization

Array opcodes, User-defined types

Credits

Init first appeared in the original Csound, but the extension to multiple values is by

Author: John ffitch
University of Bath, and Codemist Ltd.
Bath, UK
February 2010

Multiple form new in version 5.13.

User-defined types by Steven Yi. Available in Csound 7.