reference/functions/nksp_ignore_event_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>ignore_event() function</title>
    <meta name="description" content="Drops the given event.">
  </head>
  <body>
    <h1>ignore_event()</h1>
    <p>
      Drops the given event and thus prevents the supplied event to be further
      processed by the sampler. You can use this function i.e. to filter out
      MIDI note on and MIDI note off events, before they are causing new notes
      to be triggered, or to drop certain MIDI control change events before
      they can cause any sound to be changed.
    </p>
    <p>
      Dropping events with this function only succeeds if the event just
      "recently" occurred. That effectively means you should drop the event in
      the respective event handler before any <code lang="nksp">wait()</code> calls, and before
      entering any loops that may execute your script for a very long time.
      Because in both cases the sampler may suspend your script for a certain
      amount of time and once your script got resumed, the respective event may
      already have entered the sampler's regular event processing chain and
      thus can no longer be dropped.
    </p>
    <p>
      There is also an <code>ignore_controller()</code> function,
      intended for explicitly dropping control change events. With NKSP you
      you can also use <code>ignore_event()</code> though to
      drop control change events. So <code>ignore_controller()</code>
      merely exists due to compatibility reasons with KSP.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code>
ignore_event(??event-id??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??event-id??</code></td>
        <td>Event ID Number or Event ID Array</td>
        <td>Event ID(s) of the MIDI event(s) to be dropped.<br>
            [required]</td>
      </tr>
    </table>
    
    <h3>Return Value</h3>
    <p>None.</p>
    
    <h3>Examples</h3>
    <p>
      The following example implements a simple split point behavior for your sound.
      It only plays notes starting at C5, all note-on events below C5 will be dropped.
    <p>
    <code>
on init
  { MIDI note number for "C5" }
  declare const $splitPoint := 60
end on

on note
  if ($EVENT_NOTE &lt; $splitPoint)
    { $EVENT_ID is a built-in variable which always reflects
      the ID of the event which caused the execution of this
      specific event handler instance, i.e. here it reflects
      the respective MIDI note-on event }
    ignore_event($EVENT_ID)
  end if
end on
    </code>

    <note>
      Passing an array of event IDs is only supported by NKSP. If you want
      to keep compatibility to KSP, then you should only pass a single
      event ID to this function.
    </note>

  </body>
</html>
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 < $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	<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>