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>
      The argument this function takes is optional. If you omit passing an
      argument to this function, then the event ID will be used that
      caused this current event handler to be executed
      (which is <code>$EVENT_ID</code>).
    </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>
            [optional, default: ID of the event handler's event]</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>
    <p>
      Since you are almost always passing <code>$EVENT_ID</code> to <code>ignore_event()</code>,
      you can also omit that optional argument with NKSP. So the following
      would behave identical with the example above.
    </p>
    <code>
on init
  { MIDI note number for "C5" }
  declare const $splitPoint := 60
end on

on note
  if ($EVENT_NOTE &lt; $splitPoint)
    ignore_event()
  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.<br>
      <br>
      Same applies to the optional argument: Dynamic, optional arguments are
      only supported by NKSP. If you want to retain compatibility to KSP,
      then you should always pass a parameter to this function.
    </note>

  </body>
</html>
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	3213	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	schoenebeck	2881	Dropping events with this function only succeeds if the event just
24			"recently" occurred. That effectively means you should drop the event in
25	schoenebeck	2882	the respective event handler before any <code lang="nksp">wait()</code> calls, and before
26	schoenebeck	2881	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	schoenebeck	2732	</p>
32	schoenebeck	2881	<p>
33	schoenebeck	2882	There is also an <code>ignore_controller()</code> function,
34	schoenebeck	2881	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	schoenebeck	2732
40			<h3>Function Prototype</h3>
41			<p/>
42			<code>
43	schoenebeck	3213	ignore_event([??event-id??])
44	schoenebeck	2732	</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	schoenebeck	3209	<td>Event ID(s) of the MIDI event(s) to be dropped.<br>
55	schoenebeck	3213	[optional, default: ID of the event handler's event]</td>
56	schoenebeck	2732	</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 split point behavior for your sound.
65			It only plays notes starting at C5, all note-on events below C5 will be dropped.
66	schoenebeck	3211	</p>
67	schoenebeck	3209	<code>
68			on init
69			{ MIDI note number for "C5" }
70			declare const $splitPoint := 60
71			end on
72	schoenebeck	2732
73	schoenebeck	3209	on note
74			if ($EVENT_NOTE < $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	schoenebeck	3211	<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	schoenebeck	3209
94	schoenebeck	3211	on note
95			if ($EVENT_NOTE < $splitPoint)
96			ignore_event()
97			end if
98			end on
99			</code>
100
101	schoenebeck	2732	<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	schoenebeck	3213	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	schoenebeck	2732	</note>
110
111			</body>
112			</html>