/[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 3213 - (show 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: 3866 byte(s)
* NKSP: ignore_event() function's argument is now optional.

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 The argument this function takes is optional. If you omit passing an
18 argument to this function, then the event ID will be used that
19 caused this current event handler to be executed
20 (which is <code>$EVENT_ID</code>).
21 </p>
22 <p>
23 Dropping events with this function only succeeds if the event just
24 "recently" occurred. That effectively means you should drop the event in
25 the respective event handler before any <code lang="nksp">wait()</code> calls, and before
26 entering any loops that may execute your script for a very long time.
27 Because in both cases the sampler may suspend your script for a certain
28 amount of time and once your script got resumed, the respective event may
29 already have entered the sampler's regular event processing chain and
30 thus can no longer be dropped.
31 </p>
32 <p>
33 There is also an <code>ignore_controller()</code> function,
34 intended for explicitly dropping control change events. With NKSP you
35 you can also use <code>ignore_event()</code> though to
36 drop control change events. So <code>ignore_controller()</code>
37 merely exists due to compatibility reasons with KSP.
38 </p>
39
40 <h3>Function Prototype</h3>
41 <p/>
42 <code>
43 ignore_event([??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 or Event ID Array</td>
54 <td>Event ID(s) of the MIDI event(s) 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 split point behavior for your sound.
65 It only plays notes starting at C5, all note-on events below C5 will be dropped.
66 </p>
67 <code>
68 on init
69 { MIDI note number for "C5" }
70 declare const $splitPoint := 60
71 end on
72
73 on note
74 if ($EVENT_NOTE &lt; $splitPoint)
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 note-on event }
79 ignore_event($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_event()</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 note number for "C5" }
91 declare const $splitPoint := 60
92 end on
93
94 on note
95 if ($EVENT_NOTE &lt; $splitPoint)
96 ignore_event()
97 end if
98 end on
99 </code>
100
101 <note>
102 Passing an array of event IDs is only supported by NKSP. If you want
103 to keep compatibility to KSP, then you should only pass a single
104 event ID to this function.<br>
105 <br>
106 Same applies to the optional argument: Dynamic, optional arguments are
107 only supported by NKSP. If you want to retain compatibility to KSP,
108 then you should always pass a parameter to this function.
109 </note>
110
111 </body>
112 </html>

  ViewVC Help
Powered by ViewVC