1 |
schoenebeck |
2732 |
<html> |
2 |
|
|
<head> |
3 |
|
|
<meta name="author" content="Christian Schoenebeck"> |
4 |
|
|
<title>ignore_controller() function</title> |
5 |
|
|
<meta name="description" content="Drops the given MIDI control change event."> |
6 |
|
|
</head> |
7 |
|
|
<body> |
8 |
|
|
<h1>ignore_controller()</h1> |
9 |
|
|
<p> |
10 |
|
|
Drops the given MIDI control change event and thus prevents the supplied |
11 |
|
|
event to be further processed by the sampler. You can use this function |
12 |
|
|
i.e. to filter out MIDI control change events, before they are causing |
13 |
schoenebeck |
2881 |
any sound to be changed. |
14 |
schoenebeck |
2732 |
</p> |
15 |
|
|
<p> |
16 |
|
|
The argument this function takes is optional. If you omit passing an |
17 |
|
|
argument to this function, then the controller event ID will be used that |
18 |
schoenebeck |
3213 |
caused this current <code lang="nksp">controller</code> event handler to be executed |
19 |
|
|
(which is <code>$EVENT_ID</code>). |
20 |
schoenebeck |
2732 |
</p> |
21 |
|
|
<p> |
22 |
schoenebeck |
2881 |
Dropping control change events with this function only succeeds if the |
23 |
|
|
event just "recently" occurred. That effectively means you should drop |
24 |
|
|
the control change event in the <code>controller</code> event handler |
25 |
schoenebeck |
2882 |
before any <code>wait()</code> calls, and before entering any loops that may |
26 |
schoenebeck |
2881 |
execute your script for a very long time. Because in both cases the |
27 |
|
|
sampler may suspend your script for a certain amount of time and once |
28 |
|
|
your script got resumed, the respective control change event may already |
29 |
|
|
have entered the sampler's regular event processing chain and thus can no |
30 |
|
|
longer be dropped. |
31 |
schoenebeck |
2732 |
</p> |
32 |
schoenebeck |
2881 |
<p> |
33 |
|
|
With NKSP you can also use <code>ignore_event()</code> to drop control |
34 |
|
|
change events. So <code>ignore_controller()</code> merely exists due to |
35 |
|
|
compatibility reasons with KSP. However when you already know that the |
36 |
|
|
event to be dropped is a control change event, then it is recommended to |
37 |
|
|
actually call <code>ignore_controller()</code> instead of |
38 |
|
|
<code>ignore_event()</code>. |
39 |
|
|
</p> |
40 |
schoenebeck |
2732 |
|
41 |
|
|
<h3>Function Prototype</h3> |
42 |
|
|
<p/> |
43 |
|
|
<code> |
44 |
|
|
ignore_controller([??event-id??]) |
45 |
|
|
</code> |
46 |
|
|
|
47 |
|
|
<h3>Arguments</h3> |
48 |
|
|
<table> |
49 |
|
|
<tr> |
50 |
|
|
<th>Argument Name</th> <th>Data Type</th> <th>Description</th> |
51 |
|
|
</tr> |
52 |
|
|
<tr> |
53 |
|
|
<td><code>??event-id??</code></td> |
54 |
|
|
<td>Event ID Number</td> |
55 |
schoenebeck |
3209 |
<td>Event ID of the MIDI control change event to be dropped.<br> |
56 |
schoenebeck |
2732 |
[optional, default: ID of the event handler's event]</td> |
57 |
|
|
</tr> |
58 |
|
|
</table> |
59 |
|
|
|
60 |
|
|
<h3>Return Value</h3> |
61 |
|
|
<p>None.</p> |
62 |
|
|
|
63 |
|
|
<h3>Examples</h3> |
64 |
schoenebeck |
3209 |
<p> |
65 |
|
|
The following example implements a simple MIDI controller filter. |
66 |
|
|
It causes all MIDI volume control change events (MIDI CC#7) to be dropped. |
67 |
schoenebeck |
3211 |
</p> |
68 |
schoenebeck |
3209 |
<code> |
69 |
|
|
on init |
70 |
|
|
{ MIDI controller number for MIDI "volume change" events } |
71 |
|
|
declare const $volumeCC := 7 |
72 |
|
|
end on |
73 |
schoenebeck |
2732 |
|
74 |
schoenebeck |
3209 |
on controller |
75 |
|
|
if ($CC_NUM = $volumeCC) |
76 |
|
|
{ $EVENT_ID is a built-in variable which always reflects |
77 |
|
|
the ID of the event which caused the execution of this |
78 |
|
|
specific event handler instance, i.e. here it reflects |
79 |
|
|
the respective MIDI control change event } |
80 |
schoenebeck |
3210 |
ignore_controller($EVENT_ID) |
81 |
schoenebeck |
3209 |
end if |
82 |
|
|
end on |
83 |
|
|
</code> |
84 |
schoenebeck |
3211 |
<p> |
85 |
|
|
Since you are almost always passing <code>$EVENT_ID</code> to <code>ignore_controller()</code>, |
86 |
|
|
you can also omit that optional argument with NKSP. So the following |
87 |
|
|
would behave identical with the example above. |
88 |
|
|
</p> |
89 |
|
|
<code> |
90 |
|
|
on init |
91 |
|
|
{ MIDI controller number for MIDI "volume change" events } |
92 |
|
|
declare const $volumeCC := 7 |
93 |
|
|
end on |
94 |
schoenebeck |
3209 |
|
95 |
schoenebeck |
3211 |
on controller |
96 |
|
|
if ($CC_NUM = $volumeCC) |
97 |
|
|
ignore_controller() |
98 |
|
|
end if |
99 |
|
|
end on |
100 |
|
|
</code> |
101 |
|
|
|
102 |
schoenebeck |
2732 |
<note> |
103 |
|
|
Dynamic, optional arguments are only supported by NKSP. If you want to |
104 |
|
|
retain compatibility to KSP, then you should always pass a parameter |
105 |
|
|
to this function. |
106 |
|
|
</note> |
107 |
|
|
|
108 |
|
|
</body> |
109 |
|
|
</html> |