Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

More work on the MIDI documentation

  • Loading branch information...
commit 212cb94074213a36a181efe8326e452132318074 1 parent cc6b764
Werner Almesberger authored February 14, 2012
26  src/compiler/doc/arch.fig
@@ -18,10 +18,6 @@ Single
18 18
 2 2 0 2 32 7 55 -1 -1 0.000 0 0 -1 0 0 5
19 19
 	 3600 6300 4725 6300 4725 7020 3600 7020 3600 6300
20 20
 -6
21  
-6 3330 3330 4770 4320
22  
-1 1 0 3 0 7 50 -1 -1 0.000 1 0.0000 4050 3825 675 450 4050 3825 4725 4275
23  
-4 1 0 45 -1 18 12 0.0000 4 150 1050 4050 3915 Translation\001
24  
--6
25 21
 6 6480 2655 8370 5445
26 22
 2 2 0 2 0 7 55 -1 -1 0.000 0 0 -1 0 0 5
27 23
 	 6525 2700 8325 2700 8325 5400 6525 5400 6525 2700
@@ -46,8 +42,29 @@ Single
46 42
 2 1 0 2 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
47 43
 	 1035 3375 1170 3375
48 44
 -6
  45
+6 1935 5760 2295 6120
  46
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 2115 5940 135 135 2115 5940 2250 5940
  47
+4 1 0 50 -1 18 15 0.0000 4 180 135 2115 6030 1\001
  48
+-6
  49
+6 7875 2790 8235 3150
  50
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 8055 2970 135 135 8055 2970 8190 2970
  51
+4 1 0 50 -1 18 15 0.0000 4 180 135 8055 3060 2\001
  52
+-6
  53
+6 2430 3960 2790 4320
  54
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 2610 4140 135 135 2610 4140 2745 4140
  55
+4 1 0 50 -1 18 15 0.0000 4 180 135 2610 4230 3\001
  56
+-6
  57
+6 3870 3870 4230 4230
  58
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 4050 4050 135 135 4050 4050 4185 4050
  59
+4 1 0 50 -1 18 15 0.0000 4 180 135 4050 4140 4\001
  60
+-6
  61
+6 5805 3915 6165 4275
  62
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 5985 4095 135 135 5985 4095 6120 4095
  63
+4 1 0 50 -1 18 15 0.0000 4 180 135 5985 4185 5\001
  64
+-6
49 65
 1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1530 3420 90 90 1530 3420 1620 3420
50 66
 1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1530 3690 90 90 1530 3690 1620 3690
  67
+1 1 0 3 0 7 50 -1 -1 0.000 1 0.0000 4050 3825 675 450 4050 3825 4725 4275
51 68
 2 1 0 2 0 7 53 -1 -1 0.000 0 0 -1 0 0 2
52 69
 	 3600 5355 4725 5355
53 70
 2 1 0 2 0 7 53 -1 -1 0.000 0 0 -1 0 0 2
@@ -92,3 +109,4 @@ Single
92 109
 4 1 0 45 -1 18 12 0.0000 4 195 1605 5625 3735 Variable changes\001
93 110
 4 1 0 45 -1 18 12 0.0000 4 150 525 7470 5220 Patch\001
94 111
 4 1 0 45 -1 18 12 0.0000 4 150 1080 1305 3015 MIDI device\001
  112
+4 1 0 45 -1 18 12 0.0000 4 150 1050 4050 3825 Translation\001
180  src/compiler/doc/midi.tex
@@ -21,13 +21,17 @@
21 21
 \maketitle
22 22
 
23 23
 %\setcounter{tocdepth}{1}
24  
-\tableofcontents
  24
+%\tableofcontents
25 25
 
26 26
 % -----------------------------------------------------------------------------
27 27
 
28 28
 
29 29
 \section{Introduction}
30 30
 
  31
+This document describes the mechanisms Flickernoise provides for
  32
+interacting with MIDI controls and explains how patches can make use of
  33
+this functionality.
  34
+
31 35
 Note that this work is still in progress. For example,
32 36
 \begin{itemize}
33 37
   \item the MIDI device specifications should not have to be part of
@@ -44,8 +48,8 @@ \section{Introduction}
44 48
 \section{Quick start}
45 49
 
46 50
 While the finer details of MIDI controls can get complicated, the
47  
-elements in the following example are often all that is needed to
48  
-make full use of many MIDI devices:
  51
+items in the following example are often all that is needed to
  52
+use many MIDI devices:
49 53
 
50 54
 \begin{listing}{1}
51 55
 midi "Gizmo" {
@@ -73,7 +77,9 @@ \section{Quick start}
73 77
 They can be found with the MIDI monitor function of the ``MIDI settings''
74 78
 dialog in Flickernoise.
75 79
 
76  
-In line 9, we bind the {\tt main} control to a variable. This variable is
  80
+In line 9, we bind the {\tt main} control to a variable. This variable
  81
+receives the value 0 if the fader is at its minimum and 1 at its maximum.
  82
+It is
77 83
 then used in per-frame and per-vertex equations. As line 13 shows, one
78 84
 can also change this variable, e.g., to make the sensitivity slowly decay
79 85
 if there is no input from the MIDI device.
@@ -87,32 +93,30 @@ \section{Quick start}
87 93
 
88 94
 \section{Architecture}
89 95
 
90  
-For each MIDI device, an entry in the device database is selected.
  96
+Figure \ref{arch} shows how MIDI messages are processed in Flickernoise:
  97
+For each MIDI device, an entry in the device database is selected (1).
91 98
 This entry describes the characteristics of the elements of the MIDI
92 99
 device, e.g., what kind of control elements they are and what
93 100
 addresses they use.
94 101
 
95  
-A patch using MIDI devices binds control elements to variables.
  102
+A patch using MIDI devices binds control elements to variables (2).
96 103
 When binding, the patch specifies how it expects the element to
97 104
 behave, e.g., whether it should produce continuous values between
98 105
 0 and 1 or just 0 when ''off'' and 1 when ''on''.
99 106
 
100  
-Event messages from the MIDI device identify the element they
  107
+Event messages from the MIDI device (3) identify the element they
101 108
 belong to and carry a numeric value indicating the element's state.
102  
-This value is translated according to the element's characteristics
  109
+This value is translated (4) according to the element's characteristics
103 110
 from the device database combined with the expected function from
104 111
 the patch.
105 112
 
106  
-Finally, result is stored in the control variable where it can
  113
+Finally, the result is stored in the control variable (5) where it can
107 114
 then be used by the equations in the patch.
108 115
 
109 116
 
110 117
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
111 118
 
112 119
 
113  
-\figmsg
114  
-
115  
-
116 120
 \subsection{MIDI control messages}
117 121
 
118 122
 A MIDI device sends a message each time one of its elements is actuated.
@@ -121,8 +125,8 @@ \subsection{MIDI control messages}
121 125
 and push buttons.
122 126
 
123 127
 For now, we only consider controls. When a control is actuated, the
124  
-MIDI device generates a MIDI Control Change messages, as shown in
125  
-figure \ref{msg}.
  128
+MIDI device generates a MIDI Control Change message of the structure
  129
+shown in figure \ref{msg}.
126 130
 
127 131
 Channel numbers are encoded as values from 0 to 15 in the actual
128 132
 MIDI message but are commonly presented as 1 to 16 to the user.
@@ -132,16 +136,19 @@ \subsection{MIDI control messages}
132 136
 can sometimes be set by the user. The controller numbers are typically
133 137
 fixed.
134 138
 
135  
-Flickernoise uses the message type, the channel number, and the controller
  139
+When Flickernoise receives a MIDI message, it
  140
+uses the message type, the channel number, and the controller
136 141
 number to determine where to send the value. 
137 142
 
  143
+\figmsg
  144
+
138 145
 
139 146
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
140 147
 
141 148
 
142 149
 \subsection{Control variables}
143 150
 
144  
-Patches communicate with the outside world though variables. MIDI
  151
+Patches communicate with the outside world through variables. MIDI
145 152
 control input is no exception. Instead of using pre-defined names
146 153
 like it is the case for {\tt time}, {\tt bass}, etc., the names of
147 154
 MIDI control variables can be chosen freely.
@@ -159,8 +166,8 @@ \subsection{Control variables}
159 166
 
160 167
 \section{Using controls in patches}
161 168
 
162  
-@@@
163  
-
  169
+The following sections describe the syntax and semantics of the
  170
+language constructs that give access to MIDI controls.
164 171
 
165 172
 
166 173
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -169,15 +176,18 @@ \section{Using controls in patches}
169 176
 \subsection{Device database}
170 177
 
171 178
 The device database tells Flickernoise how to identify MIDI
172  
-devices and how to 
  179
+devices and their elements and how the elements behave. It also
  180
+assigns names to the elements that are then used to refer to
  181
+them in patches.
  182
+
173 183
 Device specifications are added to the device database with 
174  
-- global section
  184
+a MIDI device entry that looks as follows:
175 185
 
176 186
 \begin{expose}
177 187
 {\tt midi} {\em identification} \verb"{" {\em element $\ldots$} \verb"}"
178 188
 \end{expose}
179 189
 
180  
-Each element has the following syntax:
  190
+Each element in the device entry has the following syntax:
181 191
 
182 192
 \begin{expose}
183 193
 {\tt {\em name} =
@@ -185,10 +195,16 @@ \subsection{Device database}
185 195
   {\em control\_number});}
186 196
 \end{expose}
187 197
 
  198
+{\em device\_type} provides a broad characterization of the control
  199
+element and can be {\tt fader}, {\tt pot}, {\tt differential},
  200
+{\tt button}, or {\tt switch}. Control elements are discussed in
  201
+detail in section \ref{controls}.
  202
+
188 203
 {\em channel} is the MIDI channel number, from 1 to 16. If the channel
189 204
 is omitted, the element will match any channel.
190 205
 
191  
-{\em control\_number}
  206
+{\em control\_number} is a number from 0 to 127 the MIDI device uses
  207
+to identify the control element.
192 208
 
193 209
 This is the example from the quick start section with channel numbers
194 210
 added:
@@ -207,6 +223,8 @@ \subsection{Device database}
207 223
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
208 224
 
209 225
 
  226
+\figbind
  227
+
210 228
 \subsection{Binding}
211 229
 \label{binding}
212 230
 
@@ -252,9 +270,18 @@ \subsection{Binding}
252 270
 {\em element\_name} is the name of the control element, as in the
253 271
 device database.
254 272
 
255  
-\figbind
256  
-
257  
-@@@
  273
+The result of binding is a stimulus entry that tells Flickernoise
  274
+how to interpret incoming messages.
  275
+Figure \ref{bind} illustrates the steps in creating the stimulus
  276
+entry: Flickernoise
  277
+selects a control element with the desired name from the available
  278
+devices (1). The information needed to identify messages from this
  279
+control element is copied to the stimulus entry (2). Using the
  280
+device type from the element record (3) and the function from the
  281
+binding instruction, a suitable translator is selected from the
  282
+translation map. Also this is recorded in the stimulus entry (4).
  283
+Finally, the variable is looked up or added to the patch (5) and
  284
+a reference to it is placed in the stimulus entry.
258 285
 
259 286
 
260 287
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -267,14 +294,14 @@ \subsection{Event processing}
267 294
 Figure \ref{stim} illustrates how events are translated into changes
268 295
 of control variables.
269 296
 
270  
-Each time a MIDI control message arrives, Flickernoise looks for a
271  
-stimulus that matches the event type, i.e., MIDI control, the channel
  297
+Each time a MIDI Control Change message arrives, Flickernoise looks for a
  298
+stimulus that matches the message type, i.e., MIDI control, the channel
272 299
 number and the controller number (1). If no matching entry exists,
273  
-the event is ignored.
  300
+the message is ignored.
274 301
 
275 302
 The stimulus tells Flickernoise which translator to use and where
276 303
 to store the result. In our example, we have a {\tt pot} to {\tt range}
277  
-translation, which is simply a division by 127 (2). The result,
  304
+translation (2), which is simply a division by 127. The result,
278 305
 $\nicefrac{28}{127}=0.220$, is stored in the location of the variable
279 306
 {\tt var} (3).
280 307
 
@@ -297,6 +324,7 @@ \subsection{Writing to control variables}
297 324
 this can be accomplished:
298 325
 
299 326
 \begin{listing}{1}
  327
+last = 0;
300 328
 cvar = range(foo);
301 329
 
302 330
 per_frame:
@@ -308,29 +336,77 @@ \subsection{Writing to control variables}
308 336
 
309 337
 Instead of writing to the control variable {\tt cvar} directly, we
310 338
 propagate any relative changes of {\tt cvar} to {\tt var} in lines
311  
-4 and 5, and only modify {\tt var} in line 7.
  339
+5 and 6, and only modify {\tt var} in line 8.
312 340
 
313 341
 Note that {\tt var} may assume values outside the range $0\ldots 1$.
314  
-If this is not desirable, it can be clipped after line 4 with
  342
+If this is not desirable, it can be clipped after line 5 with
315 343
 
316 344
 \begin{listing}{1}
317 345
 	var = max(min(var, 1), 0);
318 346
 \end{listing}
319 347
 
320 348
 
  349
+% - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  350
+
  351
+
  352
+\subsection{Multiple bindings}
  353
+
  354
+So far, we have only seen one element being bound to one control
  355
+variable at a time. A control variable can also be bound to
  356
+multiple elements and the same element can be bound to multiple
  357
+control variables.
  358
+
  359
+Binding the same element to different variables can be useful in
  360
+cases where the translation differs as well. For example, the
  361
+following code snippet would control two parameters with the same
  362
+element:
  363
+
  364
+\begin{listing}{1}
  365
+growth = range(main);
  366
+tilt = cyclic(main);
  367
+
  368
+per_vertex:
  369
+	zoom = growth*0.2;
  370
+	angle = 2*3.14159*tilt;
  371
+	wave_x = cx+0.1*cos(angle);
  372
+	wave_y = cy-0.1*sin(angle);
  373
+\end{listing}
  374
+
  375
+A situation that may be even more common is to have multiple elements
  376
+that change the same variable, e.g., when using multiple input
  377
+devices. Example:
  378
+
  379
+\begin{listing}{1}
  380
+midi "foo" {
  381
+        foo_pot = pot(12);
  382
+}
  383
+
  384
+midi "bar" {
  385
+        bar_pot = pot(34);
  386
+}
  387
+
  388
+sensitivity = range(foo_pot);
  389
+sensitivity = range(bar_pot);
  390
+
  391
+per_frame:
  392
+	wave_scale = sensitivity*20;
  393
+\end{listing}
  394
+
  395
+
321 396
 % -----------------------------------------------------------------------------
322 397
 
323 398
 
324 399
 \section{Control elements}
  400
+\label{controls}
325 401
 
326  
-In the sections below, we describe the various control elements, who
  402
+In the sections below, we describe the various control elements, how
327 403
 they are described in the device database, and their behaviour. We
328  
-give examples, that show the physical state of the element, the value
329  
-a MIDI control may typically send for the element in that state, and
  404
+give examples that show the physical state of the element, the value
  405
+a MIDI device may typically send for the element in that state, and
330 406
 then the resulting values for the various translations.
331 407
 
332 408
 Since {\tt range}, {\tt unbounded}, and {\tt cycle} only differ from
333  
-each other in one case, they are usually abbreviated as just
  409
+each other in one case, they are usually abbreviated to just
334 410
 ``{\tt range}, $\ldots$''.
335 411
 
336 412
 
@@ -380,7 +456,7 @@ \subsection{Faders}
380 456
 The mapping is quite straightforward: {\tt range}, {\tt unbounded},
381 457
 and {\tt cycle} produce a value from 0 to 1 corresponding to the
382 458
 position of the knob. {\tt button} and {\tt switch} produce 0 if
383  
-the knob is the lower half of the range, 1 if it is in the upper half.
  459
+the knob is in the lower half of the range, 1 if it is in the upper half.
384 460
 
385 461
 
386 462
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -443,8 +519,8 @@ \subsection{Rotary encoders acting as potentiometers}
443 519
 Rotary encoders acting as potentiometers are also declared with
444 520
 {\tt pot} and bound with {\tt range}.
445 521
 
446  
-The example below shows a rotary encoder covering the full value range
447  
-in one $360^\circ$ turn that is first turned $450^\circ$ clockwise
  522
+The example below shows how a rotary encoder covering the full value range
  523
+in one $360^\circ$ turn behaves when it is first turned $450^\circ$ clockwise
448 524
 and then $45^\circ$ counterclockwise:
449 525
 
450 526
 \begin{expose}
@@ -496,8 +572,8 @@ \subsection{Push buttons}
496 572
 var = button(name);
497 573
 \end{listing}
498 574
 
499  
-The alternative {\tt switch()} turns the control on when the button
500  
-is pressed the first time and then off again when pressed the second
  575
+{\tt switch()} turns the control on when the button
  576
+is pressed the first time and then off again when pressed a second
501 577
 time.
502 578
 
503 579
 Example:
@@ -609,13 +685,13 @@ \subsection{Differential encoders}
609 685
 \label{diff}
610 686
 
611 687
 The rotary encoders of some controllers send differential values
612  
-instead of the usual absolute values. Differential values allows
  688
+instead of the usual absolute values. Differential values allow
613 689
 Flickernoise not only to translate them to absolute values, but
614  
-also enables more sophisticated translations.
  690
+also enable more sophisticated translations.
615 691
 
616 692
 Differential values are encoded as signed 7 bit numbers. This means
617 693
 that values in the range 0--63 represent an increase by that amount
618  
-while values in the range 0--127 represent a decrease by 128 minus
  694
+while values in the range 64--127 represent a decrease by 128 minus
619 695
 the value. E.g., a value of 127 would mean a decrease by one.
620 696
 
621 697
 Differential encoders are declared with {\tt differential()}:
@@ -659,12 +735,12 @@ \subsection{Differential encoders}
659 735
   Translation
660 736
   & 0 & 0.25 & 0.5 & 1 & 1 & \tt range \\
661 737
   & 0 & 0.25 & 0.5 & 1 & 1.125 & \tt unbounded \\
662  
-  & 0 & 0.25 & 0.5 & 0 & 0.125 & \tt cyclic \\
  738
+  & 0 & 0.25 & 0.5 & 1 & 0.125 & \tt cyclic \\
663 739
 \end{tabular}
664 740
 \end{expose}
665 741
 
666 742
 Continuing the example above, we turn the controller now by
667  
-$90^\circ$ in a counterclockwise direction:
  743
+$90^\circ$ counterclockwise:
668 744
 
669 745
 \begin{expose}
670 746
 \begin{tabular}{lccl}
@@ -726,14 +802,8 @@ \subsection{Differential encoders}
726 802
 
727 803
 Like the rotary encoders emulating potentiometers described in section
728 804
 \ref{encpot}, the values a device sends for differential encoders may be
729  
-increased if turning rapidly.
730  
-
731  
-%   The control variable can assume any value, including negative
732  
-%   values and values greater than one. This can be used with
733  
-%   certain rotary encoders. If the device in question has no
734  
-%   meaningful way to input unbounded values, {\tt unbounded} acts
735  
-%   like {\tt range}.
736  
-%   The control variable has a value between 0 and 1, like with
737  
-%   {\tt range}, but if the control element tries to move outside the
738  
-%   range, the value wraps around. 
  805
+increased if turning rapidly. Instead of the very large values used in
  806
+the examples, one would see a sequence of smaller values as the encoder
  807
+is turned.
  808
+
739 809
 \end{document}

0 notes on commit 212cb94

Please sign in to comment.
Something went wrong with that request. Please try again.