3
<refentry id="modmatrix">
4
<indexterm id="IndexModmatrix"><primary>modmatrix</primary></indexterm>
5
<refentryinfo><title>Miscellaneous</title></refentryinfo>
7
<refentrytitle>modmatrix</refentrytitle>
11
<refname>modmatrix</refname>
13
Modulation matrix opcode with optimizations for sparse matrices.
18
<title>Description</title>
20
The opcode can be used to let a large number of k-rate modulator
21
variables modulate a large number of k-rate parameter variables,
22
with arbitrary scaling of each modulator-to-parameter
23
connection. Csound ftables are used to hold both the input
24
(parameter) variables, the modulator variables, and the scaling
25
coefficients. Output variables are written to another Csound ftable.
31
<synopsis><command>modmatrix</command> iresfn, isrcmodfn, isrcparmfn, imodscale, inum_mod, \\
32
inum_parm, kupdate</synopsis>
36
<title>Initialization</title>
38
<emphasis>iresfn</emphasis> -- ftable number for the parameter output variables
41
<emphasis>isrcmodfn</emphasis> -- ftable number for the modulation source variables
44
<emphasis>isrcparmfn</emphasis> -- ftable number for the parameter input variables
47
<emphasis>imodscale</emphasis> -- scaling/routing coefficient
48
matrix. This is also a csound ftable, used as a matrix of
49
inum_mod rows and inum_parm columns.
52
<emphasis>inum_mod</emphasis> -- number of modulation variables
55
<emphasis>inum_parm</emphasis> -- number of parmeter (input and
59
The arguments <emphasis>inum_mod</emphasis>
60
and <emphasis>inum_parm</emphasis> do not have to be set to
66
<title>Performance</title>
68
<emphasis>kupdate</emphasis> -- flag to update the scaling
69
coefficients. When the flag is set to a nonzero value, the
70
scaling coefficients are read directly from the imodscale
71
ftable. When the flag is set to zero, the scaling coefficients
72
are scanned, and an optimized scaling matrix stored internally
76
For each modulator in <emphasis>isrcmodfn</emphasis>, scale it
77
with the coefficient (in <emphasis>imodscale</emphasis>)
78
determining to what degree it should influence each
79
parameter. Then sum all modulators for each parameter and add
80
the resulting modulator value to the input parameter value read from
81
<emphasis>iscparmfn</emphasis>. Finally, write the output
82
parameter values to table <emphasis>iresfn</emphasis>.
85
The following tables give insight into the processing performed
86
by the modmatrix opcode, for a simplified example using 3
87
parameter and 2 modulators. Let’s call the parameters
88
"cps1", "cps2", and "cutoff", and
89
the modulators "lfo1" and "lfo2".
92
The input variables may at a given point in time have these
94
<table id="modmatrix-table1" frame="all" colsep="1">
101
<entry>cutoff</entry> </row>
106
<entry><emphasis>isrcparmfn</emphasis></entry>
118
... while the modulator variables have these values:
119
<table id="modmatrix-table2" frame="all" colsep="1">
131
<entry><emphasis>isrcmodfn</emphasis></entry>
140
The scaling/routing coefficients used:
141
<table id="modmatrix-table3" frame="all" colsep="1">
145
<entry><emphasis>imodscale</emphasis></entry>
148
<entry>cutoff</entry>
154
<entry><emphasis>lfo1</emphasis></entry>
160
<entry><emphasis>lfo2</emphasis></entry>
170
... and the resulting output values:
171
<table id="modmatrix-table4" frame="all" colsep="1">
178
<entry>cutoff</entry>
184
<entry><emphasis>iresfn</emphasis></entry>
190
<entry><emphasis>lfo2</emphasis></entry>
200
The output value for "cps1" is calculated as
201
400+(0.5*40)+(-0.2*-50), similarly for "cps2"
202
800+(0.5*0)+(-0.2*100), and for cutoff: 3+(0.5*-2)+(-0.2*3)
205
The imodscale ftable may be specified in the score like this:
206
<programlisting>f1 0 8 -2 200 0 2 50 300 -1.5</programlisting>
209
Or more conveniently using <link linkend="ftgen"><citetitle>ftgen</citetitle></link> in the orchestra:
210
<programlisting>gimodscale ftgen 0, 0, 8, -2, 200, 0, 2, 50, 300, -1.5</programlisting>
215
Obviously, the parameter and modulator variables need not be
216
static values, and similarly, the scaling routing coefficient
217
table may be continuously rewritten using opcodes
218
like <link linkend="tablew"><citetitle>tablew</citetitle></link>.
225
<title>Examples</title>
228
Here is an example of the modmatrix opcode. It uses the file <ulink url="examples/modmatrix.csd"><citetitle>modmatrix.csd</citetitle></ulink>.
230
<title>Example of the modmatrix opcode.</title>
231
<para>See the sections <link linkend="UsingRealTime"><citetitle>Real-time Audio</citetitle></link> and <link linkend="CommandFlags"><citetitle>Command Line Flags</citetitle></link> for more information on using command line flags.</para>
232
<xi:include href="examples-xml/modmatrix.csd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
238
<title>See Also</title>
240
<link linkend="linearalgebraopcodes"><citetitle>Linear Algebra
241
Opcodes</citetitle></link>,
242
<link linkend="vectorial"><citetitle>Vectorial
243
Opcodes</citetitle></link>,
244
<link linkend="tablew"><citetitle>tablew</citetitle></link>.
249
<title>Credits</title>
251
<para>Oeyvind Brandtsegg and Thom Johansen</para>
252
<para>New in version 5.12</para>
added
removed
opcodes/modmatrix.xml
