modmatrix

modmatrix — Modulation matrix opcode with optimizations for sparse matrices.

Description

The opcode can be used to let a large number of k-rate modulator variables modulate a large number of k-rate parameter variables, with arbitrary scaling of each modulator-to-parameter connection. Csound ftables are used to hold both the input (parameter) variables, the modulator variables, and the scaling coefficients. Output variables are written to another Csound ftable.

Syntax

modmatrix iresfn, isrcmodfn, isrcparmfn, imodscale, inum_mod, \\
inum_parm, kupdate

Initialization

iresfn -- ftable number for the parameter output variables

isrcmodfn -- ftable number for the modulation source variables

isrcparmfn -- ftable number for the parameter input variables

imodscale -- scaling/routing coefficient matrix. This is also a csound ftable, used as a matrix of inum_mod rows and inum_parm columns.

inum_mod -- number of modulation variables

inum_parm -- number of parmeter (input and output) variables.

The arguments inum_mod and inum_parm do not have to be set to power-of-two values.

Performance

kupdate -- flag to update the scaling coefficients. When the flag is set to a nonzero value, the scaling coefficients are read directly from the imodscale ftable. When the flag is set to zero, the scaling coefficients are scanned, and an optimized scaling matrix stored internally in the opcode.

For each modulator in isrcmodfn, scale it with the coefficient (in imodscale) determining to what degree it should influence each parameter. Then sum all modulators for each parameter and add the resulting modulator value to the input parameter value read from iscparmfn. Finally, write the output parameter values to table iresfn.

The following tables give insight into the processing performed by the modmatrix opcode, for a simplified example using 3 parameter and 2 modulators. Let’s call the parameters "cps1", "cps2", and "cutoff", and the modulators "lfo1" and "lfo2".

The input variables may at a given point in time have these values:

Table 12. 

  cps1 cps2 cutoff
isrcparmfn 400 800 3


... while the modulator variables have these values:

Table 13. 

  lfo1 lfo2
isrcmodfn 0.5 -0.2


The scaling/routing coefficients used:

Table 14. 

imodscale cps1 cps2 cutoff
lfo1 40 0 -2
lfo2 -50 100 3


... and the resulting output values:

Table 15. 

  cps1 cps2 cutoff
iresfn 430 780 1.4
lfo2 -50 100 3


The output value for "cps1" is calculated as 400+(0.5*40)+(-0.2*-50), similarly for "cps2" 800+(0.5*0)+(-0.2*100), and for cutoff: 3+(0.5*-2)+(-0.2*3)

The imodscale ftable may be specified in the score like this:

f1  0  8  -2  200 0 2 50 300 -1.5

Or more conveniently using ftgen in the orchestra:

gimodscale ftgen 0, 0, 8, -2, 200, 0, 2, 50, 300, -1.5

Obviously, the parameter and modulator variables need not be static values, and similarly, the scaling routing coefficient table may be continuously rewritten using opcodes like tablew.

Examples

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

Example 627. Example of the modmatrix opcode.

See the sections Real-time Audio and Command Line Flags for more information on using command line flags.

<CsoundSynthesizer>
<CsOptions>
; Select audio flags here according to platform
; Audio out   Audio in
;-odac           -iadc    ;;;RT audio I/O
; For Non-realtime ouput leave only the line below:
 -o modmatrix.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>

	sr	=	44100
	kr	=	441
	ksmps	=	100
	nchnls	=	2
	0dbfs	= 	1

; basic waveforms
giSine	ftgen	0, 0, 65537, 10, 1	; sine wave
giSaw 	ftgen	0, 0, 4097, 7, 1, 4096, -1	; saw (linear)
giSoftSaw ftgen	0, 0, 65537, 30, giSaw, 1, 10	; soft saw (only 10 first harmonics)

; modmatrix tables
giMaxNumParam	= 128
giMaxNumMod	= 32
giParam_In ftgen 0, 0, giMaxNumParam, 2, 0	; input parameters table
; output parameters table (parameter values with added modulators)
giParam_Out ftgen 0, 0, giMaxNumParam, 2, 0	
giModulators ftgen 0, 0, giMaxNumMod, 2, 0	 ; modulators table
; modulation scaling and routing (mod matrix) table, start with empty table
giModScale ftgen 0, 0, giMaxNumParam*giMaxNumMod, -2, 0		

;********************************************
; generate the modulator signals
;********************************************
	instr 1

; LFO1, 1.5 Hz, normalized range (0.0 to 1.0)
kLFO1	oscil	0.5, 1.5, giSine		; generate LFO signal
kLFO1	= kLFO1+0.5				; offset

; LFO2, 0.4 Hz, normalized range (0.0 to 1.0)
kLFO2	oscil	0.5, 0.4, giSine		; generate LFO signal
kLFO2	= kLFO2+0.5				; offset


; write modulators to table
	tablew	kLFO1, 0, giModulators
	tablew	kLFO2, 1, giModulators

	endin

;********************************************
; set parameter values
;********************************************
	instr 2

; Here we can set the parameter values
icps1	= p4
icps2	= p5
icutoff	= p6
	
; write parameters to table
	tableiw	icps1, 0, giParam_In
	tableiw	icps2, 1, giParam_In
	tableiw	icutoff, 2, giParam_In

	endin

;********************************************
; mod matrix edit
;********************************************
	instr 3

; Here we can write to the modmatrix table by using tablew or tableiw

iLfo1ToCps1	= p4
iLfo1ToCps2	= p5
iLfo1ToCutoff	= p6
iLfo2ToCps1	= p7
iLfo2ToCps2	= p8
iLfo2ToCutoff	= p9

	tableiw	iLfo1ToCps1, 0, giModScale
	tableiw	iLfo1ToCps2, 1, giModScale
	tableiw	iLfo1ToCutoff, 2, giModScale
	tableiw	iLfo2ToCps1, 3, giModScale
	tableiw	iLfo2ToCps2, 4, giModScale
	tableiw	iLfo2ToCutoff, 5, giModScale
	
; and set the update flag for modulator matrix 
; ***(must update to enable changes)
ktrig	init 1
	chnset	ktrig, "modulatorUpdateFlag"
ktrig	= 0

	endin

;********************************************
; mod matrix
;********************************************
	instr 4

; get the update flag
kupdate	chnget	"modulatorUpdateFlag"		

; run the mod matrix 
inum_mod	= 2
inum_parm	= 3
	modmatrix giParam_Out, giModulators, giParam_In, \
	giModScale, inum_mod, inum_parm, kupdate

; and reset the update flag
	chnset	0, "modulatorUpdateFlag"  ; reset the update flag

	endin

;********************************************
; audio generator to test values
;********************************************
	instr 5

; basic parameters
	iamp	= ampdbfs(-5)

; read modulated parameters from table
	kcps1	table	0, giParam_Out
	kcps2	table	1, giParam_Out
	kcutoff	table	2, giParam_Out

; set filter parameters
	kCF_freq1	= kcps1*kcutoff
	kCF_freq2	= kcps2*kcutoff
	kReso		= 0.7
	kDist		= 0.3

; oscillators and filters
	a1	oscili	iamp, kcps1, giSoftSaw
	a1	lpf18	a1, kCF_freq1, kReso, kDist

	a2	oscili	iamp, kcps2, giSoftSaw
	a2	lpf18	a2, kCF_freq2, kReso, kDist
	
		outs 	a1, a2

	endin

</CsInstruments>
<CsScore>

;********************************************
; set initial parameters
;	cps1	cps2	cutoff
i2 0 1	400	800	3

;********************************************
; set modmatrix values
;	lfo1ToCps1 lfo1ToCps2 lfo1ToCut lfo2ToCps1 lfo2ToCps2 lfo2ToCut
i3 0 1 	40         0          -2        -50        100        3

;********************************************
; start "always on" instruments
#define SCORELEN # 20 #	 ; set length of score

i1 0 $SCORELEN			; start modulators
i4 0 $SCORELEN			; start mod matrix
i5 0 $SCORELEN			; start audio oscillator

e	

</CsScore>
</CsoundSynthesizer>


See Also

Linear Algebra Opcodes, Vectorial Opcodes, tablew.

Credits

By:

Oeyvind Brandtsegg and Thom Johansen

New in version 5.12