/[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 3211 - (hide annotations) (download) (as text)
Thu May 25 13:02:03 2017 UTC (5 years, 6 months ago) by schoenebeck
File MIME type: text/html
File size: 3753 byte(s)
- NKSP: Minor additions to ignore_event() and ignore_controller().

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 2742 caused this current <code lang="nksp">controller</code> event handler to be executed.
19 schoenebeck 2732 </p>
20     <p>
21 schoenebeck 2881 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 schoenebeck 2882 before any <code>wait()</code> calls, and before entering any loops that may
25 schoenebeck 2881 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 schoenebeck 2732 </p>
31 schoenebeck 2881 <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 schoenebeck 2732
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 schoenebeck 3209 <td>Event ID of the MIDI control change event to be dropped.<br>
55 schoenebeck 2732 [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 schoenebeck 3209 <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 schoenebeck 3211 </p>
67 schoenebeck 3209 <code>
68     on init
69     { MIDI controller number for MIDI "volume change" events }
70     declare const $volumeCC := 7
71     end on
72 schoenebeck 2732
73 schoenebeck 3209 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 schoenebeck 3210 ignore_controller($EVENT_ID)
80 schoenebeck 3209 end if
81     end on
82     </code>
83 schoenebeck 3211 <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 schoenebeck 3209
94 schoenebeck 3211 on controller
95     if ($CC_NUM = $volumeCC)
96     ignore_controller()
97     end if
98     end on
99     </code>
100    
101 schoenebeck 2732 <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