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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3213 - (hide annotations) (download) (as text)
Thu May 25 13:25:43 2017 UTC (6 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 3793 byte(s)
* NKSP: ignore_event() function's argument is now optional.

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>

  ViewVC Help
Powered by ViewVC