Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

MIDI documentation (still WIP, on-going)

  • Loading branch information...
commit d64b32746f7aae43fad9d74bd2af1e18370f026e 1 parent 3b739f3
Werner Almesberger authored February 13, 2012
16  src/compiler/doc/Makefile
@@ -10,7 +10,7 @@ PICS = arch msg bind stim \
10 10
        pot-0 pot-90 pot-180 pot-270 \
11 11
        enc-0 enc-90 enc-270 enc-450 enc-405 \
12 12
        dial-0 dial-90 dial-180 dial-360 \
13  
-       dial-405 dial-315
  13
+       dial-405 dial-405-idle dial-315 dial-45 dial-135 dial-315f
14 14
 
15 15
 GEN = nocvars.inc
16 16
 
@@ -18,7 +18,7 @@ GEN = nocvars.inc
18 18
 
19 19
 all:			midi.pdf
20 20
 
21  
-midi.pdf:		midi.tex $(PICS:%=%.$(PICEXT)) $(GEN)
  21
+midi.pdf:		midi.tex floats.inc $(PICS:%=%.$(PICEXT)) $(GEN)
22 22
 			pdflatex midi
23 23
 
24 24
 xpdf:			midi.pdf
@@ -102,9 +102,21 @@ dial-360.$(PICEXT):	dial.fig
102 102
 dial-405.$(PICEXT):	dial.fig
103 103
 			$(call fig2pdf, 45deg cw-slow)
104 104
 
  105
+dial-405-idle.$(PICEXT): dial.fig
  106
+			$(call fig2pdf, 45deg)
  107
+
105 108
 dial-315.$(PICEXT):	dial.fig
106 109
 			$(call fig2pdf, 315deg ccw)
107 110
 
  111
+dial-45.$(PICEXT):	dial.fig
  112
+			$(call fig2pdf, 45deg ccw-slow)
  113
+
  114
+dial-135.$(PICEXT):	dial.fig
  115
+			$(call fig2pdf, 135deg ccw-fast)
  116
+
  117
+dial-315f.$(PICEXT):	dial.fig
  118
+			$(call fig2pdf, 315deg ccw-fast)
  119
+
108 120
 nocvars.inc:		../fnp.ids
109 121
 			./mknocvars <$< >$@ || { rm -f $@; exit 1; }
110 122
 
54  src/compiler/doc/arch.fig
@@ -22,32 +22,32 @@ Single
22 22
 1 1 0 3 0 7 50 -1 -1 0.000 1 0.0000 4050 3825 675 450 4050 3825 4725 4275
23 23
 4 1 0 45 -1 18 12 0.0000 4 150 1050 4050 3915 Translation\001
24 24
 -6
25  
-6 6480 2205 8370 4995
  25
+6 6480 2655 8370 5445
26 26
 2 2 0 2 0 7 55 -1 -1 0.000 0 0 -1 0 0 5
27  
-	 6525 2250 8325 2250 8325 4950 6525 4950 6525 2250
28  
-4 0 0 45 -1 18 12 0.0000 4 195 1560 6750 2925 var = range(aux);\001
29  
-4 0 32 55 -1 18 12 0.0000 4 195 990 6750 3240 per_frame:\001
30  
-4 0 32 55 -1 18 12 0.0000 4 180 960 6975 3555 rot = time;\001
31  
-4 0 32 55 -1 18 12 0.0000 4 135 1110 6975 3870 zoom = var;\001
32  
-4 0 32 55 -1 18 12 0.0000 4 105 840 6750 2610 ...more...\001
33  
-4 0 32 55 -1 18 12 0.0000 4 105 840 6975 4185 ...more...\001
  27
+	 6525 2700 8325 2700 8325 5400 6525 5400 6525 2700
  28
+4 0 0 45 -1 18 12 0.0000 4 195 1560 6750 3375 var = range(aux);\001
  29
+4 0 32 55 -1 18 12 0.0000 4 195 990 6750 3690 per_frame:\001
  30
+4 0 32 55 -1 18 12 0.0000 4 180 960 6975 4005 rot = time;\001
  31
+4 0 32 55 -1 18 12 0.0000 4 135 1110 6975 4320 zoom = var;\001
  32
+4 0 32 55 -1 18 12 0.0000 4 105 840 6750 3060 ...more...\001
  33
+4 0 32 55 -1 18 12 0.0000 4 105 840 6975 4635 ...more...\001
34 34
 -6
35  
-6 1305 3825 1665 4185
36  
-1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1485 4005 127 127 1485 4005 1395 3915
  35
+6 1305 3915 1665 4275
  36
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1485 4095 127 127 1485 4095 1395 4005
37 37
 2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
38  
-	 1485 4005 1395 3915
  38
+	 1485 4095 1395 4005
39 39
 -6
40  
-6 1485 3285 1665 3600
41  
-5 1 0 2 0 7 50 -1 -1 0.000 0 0 0 0 1575.000 3375.000 1530 3375 1575 3330 1620 3375
42  
-5 1 0 2 0 7 50 -1 -1 0.000 0 1 0 0 1575.000 3510.000 1530 3510 1575 3555 1620 3510
43  
-1 3 0 2 0 7 47 -1 15 0.000 1 0.0000 1575 3375 45 45 1575 3375 1620 3375
  40
+6 945 3330 1260 3510
  41
+5 1 0 2 0 7 50 -1 -1 0.000 0 0 0 0 1035.000 3420.000 1035 3465 990 3420 1035 3375
  42
+5 1 0 2 0 7 50 -1 -1 0.000 0 1 0 0 1170.000 3420.000 1170 3465 1215 3420 1170 3375
  43
+1 3 0 2 0 7 47 -1 15 0.000 1 1.5708 1035 3420 45 45 1035 3420 1035 3375
44 44
 2 1 0 2 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
45  
-	 1530 3375 1530 3510
  45
+	 1035 3465 1170 3465
46 46
 2 1 0 2 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
47  
-	 1620 3375 1620 3510
  47
+	 1035 3375 1170 3375
48 48
 -6
49  
-1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1080 3420 90 90 1080 3420 1170 3420
50  
-1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1350 3420 90 90 1350 3420 1440 3420
  49
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1530 3420 90 90 1530 3420 1620 3420
  50
+1 3 0 2 0 7 50 -1 -1 0.000 1 0.0000 1530 3690 90 90 1530 3690 1620 3690
51 51
 2 1 0 2 0 7 53 -1 -1 0.000 0 0 -1 0 0 2
52 52
 	 3600 5355 4725 5355
53 53
 2 1 0 2 0 7 53 -1 -1 0.000 0 0 -1 0 0 2
@@ -71,19 +71,19 @@ Single
71 71
 	 1890 3825 3330 3825
72 72
 2 1 0 2 0 7 50 -1 -1 0.000 0 0 7 1 0 3
73 73
 	1 1 2.00 60.00 60.00
74  
-	 4770 3825 6885 3825 6885 2970
75  
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 3
76  
-	1 1 2.00 60.00 60.00
77  
-	 6705 2880 4050 2880 4050 3330
78  
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
  74
+	 4770 3825 6885 3825 6885 3420
  75
+2 1 0 2 0 7 50 -1 -1 0.000 0 1 -1 0 0 2
79 76
 	 1080 4320 1080 3645
80  
-2 1 0 4 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
  77
+2 1 0 4 0 7 50 -1 -1 0.000 0 1 -1 0 0 2
81 78
 	 990 4095 1170 4095
82 79
 2 2 0 3 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
83 80
 	 810 3150 1800 3150 1800 4500 810 4500 810 3150
  81
+2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 4
  82
+	1 1 2.00 60.00 60.00
  83
+	 7470 3195 7470 2880 4050 2880 4050 3330
84 84
 4 1 0 45 -1 18 12 0.0000 4 150 525 12330 6570 Patch\001
85  
-4 1 0 45 -1 18 12 0.0000 4 150 435 3285 5355 dev1\001
86  
-4 1 0 45 -1 18 12 0.0000 4 150 435 3285 6480 dev2\001
  85
+4 1 0 45 -1 18 12 0.0000 4 150 615 3285 5355 Gizmo\001
  86
+4 1 32 45 -1 18 12 0.0000 4 150 435 3285 6480 Frob\001
87 87
 4 0 0 45 -1 18 12 0.0000 4 150 1380 4185 4725 Characteristics\001
88 88
 4 1 0 45 -1 18 12 0.0000 4 150 630 2610 3735 Events\001
89 89
 4 1 0 45 -1 18 12 0.0000 4 150 1500 3960 7470 Device database\001
4  src/compiler/doc/bind.fig
@@ -136,7 +136,7 @@ Single
136 136
 4 1 0 50 -1 18 12 0.0000 4 150 690 5400 6255 MIDICC\001
137 137
 4 1 0 50 -1 18 12 0.0000 4 135 315 6300 6255 103\001
138 138
 4 1 0 50 -1 18 12 0.0000 4 195 300 6750 6255 pot\001
139  
-4 1 0 45 -1 18 12 0.0000 4 150 435 4185 6030 dev1\001
  139
+4 1 0 45 -1 18 12 0.0000 4 150 615 4185 6030 Gizmo\001
140 140
 4 1 0 50 -1 18 12 0.0000 4 150 1050 10350 3555 Translators\001
141 141
 4 1 0 30 -1 14 20 0.0000 4 270 3315 5625 4050 var = range(aux);\001
142 142
 4 1 0 50 -1 18 12 0.0000 4 150 525 4815 6030 Name\001
@@ -144,7 +144,7 @@ Single
144 144
 4 1 0 50 -1 18 12 0.0000 4 150 345 6750 6030 Dev\001
145 145
 4 1 0 50 -1 18 12 0.0000 4 150 330 6345 6030 Ctrl\001
146 146
 4 1 0 50 -1 18 12 0.0000 4 150 480 5895 6030 Chan\001
147  
-4 1 0 45 -1 18 12 0.0000 4 150 435 4185 7380 dev2\001
  147
+4 1 32 45 -1 18 12 0.0000 4 150 435 4185 7380 Frob\001
148 148
 4 1 0 50 -1 18 12 0.0000 4 150 1500 5490 8820 Device database\001
149 149
 4 1 0 50 -1 18 12 0.0000 4 150 330 8955 8370 Ctrl\001
150 150
 4 1 0 50 -1 18 12 0.0000 4 150 435 9450 8370 Proc\001
38  src/compiler/doc/floats.inc
... ...
@@ -0,0 +1,38 @@
  1
+\newcommand{\figarch}{
  2
+\begin{figure}[!tb]
  3
+\begin{center}
  4
+\includegraphics{arch.pdf}
  5
+\end{center}
  6
+\caption{Input event processing in Flickernoise.}
  7
+\label{arch}
  8
+\end{figure}}
  9
+
  10
+\newcommand{\figmsg}{
  11
+\begin{figure}[!tb]
  12
+\begin{center}
  13
+\includegraphics{msg.pdf}
  14
+\end{center}
  15
+\caption{Anatomy of a MIDI Control Change message.}
  16
+\label{msg}
  17
+\end{figure}}
  18
+
  19
+\newcommand{\figbind}{
  20
+\begin{figure}[!tb]
  21
+\begin{center}
  22
+\includegraphics{bind.pdf}
  23
+\end{center}
  24
+\caption{When binding a control variable, information from the device
  25
+  database, a translation map, and the table of patch variables is
  26
+  combined into a stimulus entry.}
  27
+\label{bind}
  28
+\end{figure}}
  29
+
  30
+\newcommand{\figstim}{
  31
+\begin{figure}[!tb]
  32
+\begin{center}
  33
+\includegraphics{stim.pdf}
  34
+\end{center}
  35
+\caption{When a MIDI control message is received, Flickernoise looks
  36
+  for a matching stimulus and processes the value accordingly.}
  37
+\label{stim}
  38
+\end{figure}}
249  src/compiler/doc/midi.tex
@@ -4,13 +4,14 @@
4 4
 \usepackage{fullpage}
5 5
 \usepackage{parskip}
6 6
 \usepackage{booktabs}
7  
-\usepackage{epsfig}
8 7
 \usepackage{moreverb}
9 8
 \usepackage{nicefrac}
10 9
 
11 10
 \newenvironment{expose}{\vskip3mm\qquad\begin{raggedright}}{%
12 11
 \end{raggedright}\vskip3mm}
13 12
 
  13
+\input floats.inc
  14
+
14 15
 \begin{document}
15 16
 
16 17
 \title{Using MIDI in Flickernoise Patches}
@@ -19,10 +20,6 @@
19 20
 
20 21
 \maketitle
21 22
 
22  
-\begin{abstract}
23  
-This document describes how MIDI 
24  
-\end{abstract}
25  
-
26 23
 %\setcounter{tocdepth}{1}
27 24
 \tableofcontents
28 25
 
@@ -36,7 +33,7 @@ \section{Introduction}
36 33
   \item the MIDI device specifications should not have to be part of
37 34
     patches,
38 35
   \item Flickernoise should only consider devices that are really present, and
39  
-  \item we should support other events that just MIDI control message,
  36
+  \item we should support other events than just MIDI control message,
40 37
     such as other MIDI message types, DMX, keyboard, IR remote, etc.
41 38
 \end{itemize}
42 39
 
@@ -56,6 +53,7 @@ \section{Quick start}
56 53
 	aux = pot(103);
57 54
 	but1 = button(16);
58 55
 	but2 = button(17);
  56
+	select = switch(24);
59 57
 }
60 58
 
61 59
 sensitivity = range(main);
@@ -67,15 +65,16 @@ \section{Quick start}
67 65
 
68 66
 In lines 1 through 6 we describe the controls the MIDI device called
69 67
 ``Gizmo'' provides. In this case, we have one fader, one potentiometer,
70  
-and two buttons. We assign them names that represent their role: {\tt main}
  68
+two buttons, and one switch. We assign them names that represent their
  69
+role: {\tt main}
71 70
 for the principal fader, {\tt aux} for the potentiometer, and so on.
72 71
 
73 72
 The numbers are the respective MIDI controller numbers the device uses.
74 73
 They can be found with the MIDI monitor function of the ``MIDI settings''
75 74
 dialog in Flickernoise.
76 75
 
77  
-In line 8, we bind the {\tt main} control to a variable. This variable is
78  
-then used in per-frame and per-vertex equations. As line 12 shows, one
  76
+In line 9, we bind the {\tt main} control to a variable. This variable is
  77
+then used in per-frame and per-vertex equations. As line 13 shows, one
79 78
 can also change this variable, e.g., to make the sensitivity slowly decay
80 79
 if there is no input from the MIDI device.
81 80
 
@@ -83,21 +82,37 @@ \section{Quick start}
83 82
 % -----------------------------------------------------------------------------
84 83
 
85 84
 
  85
+\figarch
  86
+
  87
+
86 88
 \section{Architecture}
87 89
 
88  
-When a MIDI device is1
89  
-\begin{figure}[!tb]
90  
-\begin{center}
91  
-\includegraphics{arch.pdf}
92  
-\end{center}
93  
-\caption{Input event processing in Flickernoise.}
94  
-\label{arch}
95  
-\end{figure}
  90
+For each MIDI device, an entry in the device database is selected.
  91
+This entry describes the characteristics of the elements of the MIDI
  92
+device, e.g., what kind of control elements they are and what
  93
+addresses they use.
  94
+
  95
+A patch using MIDI devices binds control elements to variables.
  96
+When binding, the patch specifies how it expects the element to
  97
+behave, e.g., whether it should produce continuous values between
  98
+0 and 1 or just 0 when ''off'' and 1 when ''on''.
  99
+
  100
+Event messages from the MIDI device identify the element they
  101
+belong to and carry a numeric value indicating the element's state.
  102
+This value is translated according to the element's characteristics
  103
+from the device database combined with the expected function from
  104
+the patch.
  105
+
  106
+Finally, result is stored in the control variable where it can
  107
+then be used by the equations in the patch.
96 108
 
97 109
 
98 110
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
99 111
 
100 112
 
  113
+\figmsg
  114
+
  115
+
101 116
 \subsection{MIDI control messages}
102 117
 
103 118
 A MIDI device sends a message each time one of its elements is actuated.
@@ -109,14 +124,6 @@ \subsection{MIDI control messages}
109 124
 MIDI device generates a MIDI Control Change messages, as shown in
110 125
 figure \ref{msg}.
111 126
 
112  
-\begin{figure}[!tb]
113  
-\begin{center}
114  
-\includegraphics{msg.pdf}
115  
-\end{center}
116  
-\caption{Anatomy of a MIDI Control Change message.}
117  
-\label{msg}
118  
-\end{figure}
119  
-
120 127
 Channel numbers are encoded as values from 0 to 15 in the actual
121 128
 MIDI message but are commonly presented as 1 to 16 to the user.
122 129
 Also Flickernoise follows this convention.
@@ -132,10 +139,20 @@ \subsection{MIDI control messages}
132 139
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
133 140
 
134 141
 
135  
-\subsection{@@@}
  142
+\subsection{Control variables}
136 143
 
  144
+Patches communicate with the outside world though variables. MIDI
  145
+control input is no exception. Instead of using pre-defined names
  146
+like it is the case for {\tt time}, {\tt bass}, etc., the names of
  147
+MIDI control variables can be chosen freely.
  148
+
  149
+Values from MIDI controls are usually translated to
  150
+the range 0 to 1. This can be as simple a division by 127.
  151
+Section \ref{binding} describes more ways to translate MIDI messages.
  152
+
  153
+Updates of control variables are synchronized with patch execution
  154
+such that updates never happen while the patch is running.
137 155
 
138  
-@@@
139 156
 
140 157
 % -----------------------------------------------------------------------------
141 158
 
@@ -144,6 +161,8 @@ \section{Using controls in patches}
144 161
 
145 162
 @@@
146 163
 
  164
+
  165
+
147 166
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
148 167
 
149 168
 
@@ -169,13 +188,18 @@ \subsection{Device database}
169 188
 {\em channel} is the MIDI channel number, from 1 to 16. If the channel
170 189
 is omitted, the element will match any channel.
171 190
 
  191
+{\em control\_number}
  192
+
  193
+This is the example from the quick start section with channel numbers
  194
+added:
  195
+
172 196
 \begin{listing}{1}
173  
-midi "dev1" {
  197
+midi "Gizmo" {
174 198
 	main = fader(1, 102);
175 199
 	aux = pot(1, 103);
176 200
 	but1 = button(1, 16);
177 201
 	but2 = button(1, 17);
178  
-	sw = switch(1, 24);
  202
+	select = switch(1, 24);
179 203
 }
180 204
 \end{listing}
181 205
 
@@ -184,6 +208,7 @@ \subsection{Device database}
184 208
 
185 209
 
186 210
 \subsection{Binding}
  211
+\label{binding}
187 212
 
188 213
 In order to use a control in a patch, we have to establish a connection
189 214
 between the control element (in the device database) and a patch
@@ -227,30 +252,17 @@ \subsection{Binding}
227 252
 {\em element\_name} is the name of the control element, as in the
228 253
 device database.
229 254
 
230  
-\begin{figure}[!tb]
231  
-\begin{center}
232  
-\includegraphics{bind.pdf}
233  
-\end{center}
234  
-\caption{When binding a control variable, information from the device
235  
-  database, a translation map, and the table of patch variables is
236  
-  combined into a stimulus entry.}
237  
-\label{bind}
238  
-\end{figure}
  255
+\figbind
  256
+
  257
+@@@
239 258
 
240 259
 
241 260
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
242 261
 
243 262
 
244  
-\subsection{Event processing}
  263
+\figstim
245 264
 
246  
-\begin{figure}[!tb]
247  
-\begin{center}
248  
-\includegraphics{stim.pdf}
249  
-\end{center}
250  
-\caption{When a MIDI control message is received, Flickernoise looks
251  
-  for a matching stimulus and processes the value accordingly.}
252  
-\label{stim}
253  
-\end{figure}
  265
+\subsection{Event processing}
254 266
 
255 267
 Figure \ref{stim} illustrates how events are translated into changes
256 268
 of control variables.
@@ -272,7 +284,7 @@ \subsection{Event processing}
272 284
 
273 285
 \subsection{Writing to control variables}
274 286
 
275  
-A patch can overwrite the values control variables. In the case of
  287
+A patch can overwrite the values of control variables. In the case of
276 288
 per-frame variables, they retain their modified content across
277 289
 frames until a new event arrives. The new event will always overwrite
278 290
 the previous value of the variable without regard for any changes that
@@ -309,13 +321,13 @@ \subsection{Writing to control variables}
309 321
 % -----------------------------------------------------------------------------
310 322
 
311 323
 
312  
-\section{Control devices}
  324
+\section{Control elements}
313 325
 
314  
-In the section below, we describe the various control elements, their
315  
-declaration, and their behaviour. In the example, we show the physical
316  
-state of the element, the value a MIDI control may typically send for
317  
-the element in that state, and then the resulting values for the
318  
-various translations.
  326
+In the sections below, we describe the various control elements, who
  327
+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
  330
+then the resulting values for the various translations.
319 331
 
320 332
 Since {\tt range}, {\tt unbounded}, and {\tt cycle} only differ from
321 333
 each other in one case, they are usually abbreviated as just
@@ -394,7 +406,7 @@ \subsection{Rotary potentiometers}
394 406
 in the next section.
395 407
 
396 408
 The example below shows a potentiometer that travels over an angle
397  
-of $270^{\circ}$:
  409
+of $270^\circ$:
398 410
 
399 411
 \begin{expose}
400 412
 \begin{tabular}{lccccl}
@@ -418,6 +430,7 @@ \subsection{Rotary potentiometers}
418 430
 
419 431
 
420 432
 \subsection{Rotary encoders acting as potentiometers}
  433
+\label{encpot}
421 434
 
422 435
 Rotary encoders look similar to potentiometers but differ from them
423 436
 by not having a mechanical stop. This means that they can be turned
@@ -431,8 +444,8 @@ \subsection{Rotary encoders acting as potentiometers}
431 444
 {\tt pot} and bound with {\tt range}.
432 445
 
433 446
 The example below shows a rotary encoder covering the full value range
434  
-in one $360^{\circ}$ turn that is first turned $450^{\circ}$ clockwise
435  
-and then $45^{\circ}$ counterclockwise:
  447
+in one $360^\circ$ turn that is first turned $450^\circ$ clockwise
  448
+and then $45^\circ$ counterclockwise:
436 449
 
437 450
 \begin{expose}
438 451
 \begin{tabular}{lcccccl}
@@ -452,8 +465,15 @@ \subsection{Rotary encoders acting as potentiometers}
452 465
 \end{tabular}
453 466
 \end{expose}
454 467
 
455  
-Note that it stops at MIDI value 127 at the third turn and the
456  
-remaining $90^{\circ}$ are ignored.
  468
+The encoder stops at MIDI value 127 at the third turn and the
  469
+remaining $90^\circ$ are ignored.
  470
+
  471
+Note that the the above is a bit simplified. Rotary encoders commonly
  472
+found in MIDI devices only have 20--30 positions per full turn. When
  473
+turning them slowly, it therefore takes several full turns to cross
  474
+the entire range. To permit quick changes, MIDI controllers usually
  475
+change the value in steps larger than one when the encoder is turned
  476
+rapidly.
457 477
 
458 478
 
459 479
 % - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -588,6 +608,42 @@ \subsection{One-way buttons}
588 608
 \subsection{Differential encoders}
589 609
 \label{diff}
590 610
 
  611
+The rotary encoders of some controllers send differential values
  612
+instead of the usual absolute values. Differential values allows
  613
+Flickernoise not only to translate them to absolute values, but
  614
+also enables more sophisticated translations.
  615
+
  616
+Differential values are encoded as signed 7 bit numbers. This means
  617
+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
  619
+the value. E.g., a value of 127 would mean a decrease by one.
  620
+
  621
+Differential encoders are declared with {\tt differential()}:
  622
+
  623
+\begin{listing}{1}
  624
+midi ... {
  625
+	name = differential(...);
  626
+}
  627
+\end{listing}
  628
+
  629
+There are three distinct options for binding them to continuous values:
  630
+with {\tt range()}, the
  631
+emulate potentiometers with a range from 0 to 1. With {\tt unbounded},
  632
+the control variable can also assume values below 0 or above 1. Finally,
  633
+{\tt cyclic} limits the control variable to a range from 0 to 1 but
  634
+makes it wrap from 1 to 0 when increasing, and from 0 to 1 when
  635
+decreasing.
  636
+
  637
+\begin{listing}{1}
  638
+var1 = range(name1);
  639
+var2 = unbounded(name2);
  640
+var3 = cyclic(name3);
  641
+\end{listing}
  642
+
  643
+This example illustrates the values that result for the different
  644
+translations when turning an encoder that needs one $360^\circ$ turn
  645
+for the full value range by a total of $405^\circ$:
  646
+
591 647
 \begin{expose}
592 648
 \begin{tabular}{lccccccl}
593 649
   \raisebox{6mm}{User input} &
@@ -595,20 +651,83 @@ \subsection{Differential encoders}
595 651
   \includegraphics{dial-90.pdf} &
596 652
   \includegraphics{dial-180.pdf} &
597 653
   \includegraphics{dial-360.pdf} &
  654
+  \includegraphics{dial-405.pdf} \\
  655
+  \cmidrule(r){1-6}
  656
+  MIDI value &
  657
+  & 32 & 32 & 63 & 16 \\
  658
+  \midrule
  659
+  Translation
  660
+  & 0 & 0.25 & 0.5 & 1 & 1 & \tt range \\
  661
+  & 0 & 0.25 & 0.5 & 1 & 1.125 & \tt unbounded \\
  662
+  & 0 & 0.25 & 0.5 & 0 & 0.125 & \tt cyclic \\
  663
+\end{tabular}
  664
+\end{expose}
  665
+
  666
+Continuing the example above, we turn the controller now by
  667
+$90^\circ$ in a counterclockwise direction:
  668
+
  669
+\begin{expose}
  670
+\begin{tabular}{lccl}
  671
+  \raisebox{6mm}{User input} &
  672
+  \includegraphics{dial-405-idle.pdf} &
  673
+  \includegraphics{dial-315.pdf} \\
  674
+  \cmidrule(r){1-3}
  675
+  MIDI value &
  676
+  & 96 \\
  677
+  \midrule
  678
+  Translation
  679
+  & 1 & 0.75 & \tt range \\
  680
+  & 1.125 & 0.875 & \tt unbounded \\
  681
+  & 0.125 & 0.875 & \tt cyclic \\
  682
+\end{tabular}
  683
+\end{expose}
  684
+
  685
+Starting from zero again, we now turn the controller first
  686
+$45^\circ$ clockwise and then $450^\circ$ counterclockwise:
  687
+
  688
+\begin{expose}
  689
+\begin{tabular}{lcccccl}
  690
+  \raisebox{6mm}{User input} &
  691
+  \includegraphics{dial-0.pdf} &
598 692
   \includegraphics{dial-405.pdf} &
  693
+  \includegraphics{dial-315.pdf} &
  694
+  \includegraphics{dial-135.pdf} &
  695
+  \includegraphics{dial-315f.pdf} \\
  696
+  \cmidrule(r){1-6}
  697
+  MIDI value &
  698
+  & 16 & 96 & 64 & 64 \\
  699
+  \midrule
  700
+  Translation
  701
+  & 0 & 0.125 & 0 & 0 & 0 & \tt range \\
  702
+  & 0 & 0.125 & -0.125 & -0.625 & -1.125 & \tt unbounded \\
  703
+  & 0 & 0.125 & 0.875 & 0.375 & 0.875 & \tt cyclic \\
  704
+\end{tabular}
  705
+\end{expose}
  706
+
  707
+When emulation a button or a switch, any clockwise turn will set the
  708
+control variable to 1 while any counterclockwise turn will set it to
  709
+zero:
  710
+
  711
+\begin{expose}
  712
+\begin{tabular}{lccccl}
  713
+  \raisebox{6mm}{User input} &
  714
+  \includegraphics{dial-0.pdf} &
  715
+  \includegraphics{dial-90.pdf} &
  716
+  \includegraphics{dial-45.pdf} &
599 717
   \includegraphics{dial-315.pdf} \\
600  
-  \cmidrule(r){1-7}
  718
+  \cmidrule(r){1-5}
601 719
   MIDI value &
602  
-  & 32 & 32 & 64 & 16 & 96 \\
  720
+  & 32 & 112 & 96 \\
603 721
   \midrule
604 722
   Translation
605  
-  & 0 & 0.25 & 0.5 & 1 & 1 & 0.75 & \tt range \\
606  
-  & 0 & 0.25 & 0.5 & 1 & 1.125 & 0.875 & \tt unbounded \\
607  
-  & 0 & 0.25 & 0.5 & 0 & 0.125 & 0.875 & \tt cyclic \\
608  
-%  & 0 & 1 & 1 & 0 & \tt button, switch \\
  723
+  & 0 & 1 & 0 & 0 & \tt button, switch \\
609 724
 \end{tabular}
610 725
 \end{expose}
611 726
 
  727
+Like the rotary encoders emulating potentiometers described in section
  728
+\ref{encpot}, the values a device sends for differential encoders may be
  729
+increased if turning rapidly.
  730
+
612 731
 %   The control variable can assume any value, including negative
613 732
 %   values and values greater than one. This can be used with
614 733
 %   certain rotary encoders. If the device in question has no

0 notes on commit d64b327

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