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

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_ignore_event_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: 3335 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_event() function</title>
5 <meta name="description" content="Drops the given event.">
6 </head>
7 <body>
8 <h1>ignore_event()</h1>
9 <p>
10 Drops the given event and thus prevents the supplied event to be further
11 processed by the sampler. You can use this function i.e. to filter out
12 MIDI note on and MIDI note off events, before they are causing new notes
13 to be triggered, or to drop certain MIDI control change events before
14 they can cause any sound to be changed.
15 </p>
16 <p>
17 Dropping events with this function only succeeds if the event just
18 "recently" occurred. That effectively means you should drop the event in
19 the respective event handler before any <code lang="nksp">wait()</code> calls, and before
20 entering any loops that may execute your script for a very long time.
21 Because in both cases the sampler may suspend your script for a certain
22 amount of time and once your script got resumed, the respective event may
23 already have entered the sampler's regular event processing chain and
24 thus can no longer be dropped.
25 </p>
26 <p>
27 There is also an <code>ignore_controller()</code> function,
28 intended for explicitly dropping control change events. With NKSP you
29 you can also use <code>ignore_event()</code> though to
30 drop control change events. So <code>ignore_controller()</code>
31 merely exists due to compatibility reasons with KSP.
32 </p>
33
34 <h3>Function Prototype</h3>
35 <p/>
36 <code>
37 ignore_event(??event-id??)
38 </code>
39
40 <h3>Arguments</h3>
41 <table>
42 <tr>
43 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
44 </tr>
45 <tr>
46 <td><code>??event-id??</code></td>
47 <td>Event ID Number or Event ID Array</td>
48 <td>Event ID(s) of the MIDI event(s) to be dropped.<br>
49 [required]</td>
50 </tr>
51 </table>
52
53 <h3>Return Value</h3>
54 <p>None.</p>
55
56 <h3>Examples</h3>
57 <p>
58 The following example implements a simple split point behavior for your sound.
59 It only plays notes starting at C5, all note-on events below C5 will be dropped.
60 </p>
61 <code>
62 on init
63 { MIDI note number for "C5" }
64 declare const $splitPoint := 60
65 end on
66
67 on note
68 if ($EVENT_NOTE &lt; $splitPoint)
69 { $EVENT_ID is a built-in variable which always reflects
70 the ID of the event which caused the execution of this
71 specific event handler instance, i.e. here it reflects
72 the respective MIDI note-on event }
73 ignore_event($EVENT_ID)
74 end if
75 end on
76 </code>
77 <p>
78 Since you are almost always passing <code>$EVENT_ID</code> to <code>ignore_event()</code>,
79 you can also omit that optional argument with NKSP. So the following
80 would behave identical with the example above.
81 </p>
82 <code>
83 on init
84 { MIDI note number for "C5" }
85 declare const $splitPoint := 60
86 end on
87
88 on note
89 if ($EVENT_NOTE &lt; $splitPoint)
90 ignore_event()
91 end if
92 end on
93 </code>
94
95 <note>
96 Passing an array of event IDs is only supported by NKSP. If you want
97 to keep compatibility to KSP, then you should only pass a single
98 event ID to this function.
99 </note>
100
101 </body>
102 </html>

  ViewVC Help
Powered by ViewVC