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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3209 - (hide annotations) (download) (as text)
Thu May 25 12:08:04 2017 UTC (6 years, 9 months ago) by schoenebeck
File MIME type: text/html
File size: 2908 byte(s)
* NKSP: Added examples for ignore_event() and ignore_controller().

1 schoenebeck 2732 <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 schoenebeck 2881 to be triggered, or to drop certain MIDI control change events before
14     they can cause any sound to be changed.
15 schoenebeck 2732 </p>
16     <p>
17 schoenebeck 2881 Dropping events with this function only succeeds if the event just
18     "recently" occurred. That effectively means you should drop the event in
19 schoenebeck 2882 the respective event handler before any <code lang="nksp">wait()</code> calls, and before
20 schoenebeck 2881 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 schoenebeck 2732 </p>
26 schoenebeck 2881 <p>
27 schoenebeck 2882 There is also an <code>ignore_controller()</code> function,
28 schoenebeck 2881 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 schoenebeck 2732
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 schoenebeck 3209 <td>Event ID(s) of the MIDI event(s) to be dropped.<br>
49 schoenebeck 2732 [required]</td>
50     </tr>
51     </table>
52    
53     <h3>Return Value</h3>
54     <p>None.</p>
55    
56     <h3>Examples</h3>
57 schoenebeck 3209 <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 schoenebeck 2732
67 schoenebeck 3209 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    
78 schoenebeck 2732 <note>
79     Passing an array of event IDs is only supported by NKSP. If you want
80     to keep compatibility to KSP, then you should only pass a single
81     event ID to this function.
82     </note>
83    
84     </body>
85     </html>

  ViewVC Help
Powered by ViewVC