/[svn]/doc/docbase/instrument_scripts/nksp/reference/functions/nksp_ignore_controller_function.html
ViewVC logotype

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_ignore_controller_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3211 - (show annotations) (download) (as text)
Thu May 25 13:02:03 2017 UTC (3 years, 8 months ago) by schoenebeck
File MIME type: text/html
File size: 3753 byte(s)
- NKSP: Minor additions to ignore_event() and ignore_controller().

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

  ViewVC Help
Powered by ViewVC