reference/functions/nksp_ignore_controller_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>ignore_controller() function</title>
    <meta name="description" content="Drops the given MIDI control change event.">
  </head>
  <body>
    <h1>ignore_controller()</h1>
    <p>
      Drops the given MIDI control change 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 control change events, before they are causing
      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 controller event ID will be used that
      caused this current <code lang="nksp">controller</code> event handler to be executed
      (which is <code>$EVENT_ID</code>).
    </p>
    <p>
      Dropping control change events with this function only succeeds if the
      event just "recently" occurred. That effectively means you should drop
      the control change event in the <code>controller</code> event handler
      before any <code>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 control change event may already
      have entered the sampler's regular event processing chain and thus can no
      longer be dropped.
    </p>
    <p>
      With NKSP you can also use <code>ignore_event()</code> to drop control
      change events. So <code>ignore_controller()</code> merely exists due to
      compatibility reasons with KSP. However when you already know that the
      event to be dropped is a control change event, then it is recommended to
      actually call <code>ignore_controller()</code> instead of
      <code>ignore_event()</code>.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code>
ignore_controller([??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</td>
        <td>Event ID of the MIDI control change event 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 MIDI controller filter.
      It causes all MIDI volume control change events (MIDI CC#7) to be dropped.
    </p>
    <code>
on init
  { MIDI controller number for MIDI "volume change" events }
  declare const $volumeCC := 7
end on

on controller
  if ($CC_NUM = $volumeCC)
    { $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 control change event }
    ignore_controller($EVENT_ID)
  end if
end on
    </code>
    <p>
      Since you are almost always passing <code>$EVENT_ID</code> to <code>ignore_controller()</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 controller number for MIDI "volume change" events }
  declare const $volumeCC := 7
end on

on controller
  if ($CC_NUM = $volumeCC)
    ignore_controller()
  end if
end on
    </code>

    <note>
      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	<html>
2	<head>
3	<meta name="author" content="Christian Schoenebeck">
4	<title>ignore_controller() function</title>
5	<meta name="description" content="Drops the given MIDI control change event.">
6	</head>
7	<body>
8	<h1>ignore_controller()</h1>
9	<p>
10	Drops the given MIDI control change event and thus prevents the supplied
11	event to be further processed by the sampler. You can use this function
12	i.e. to filter out MIDI control change events, before they are causing
13	any sound to be changed.
14	</p>
15	<p>
16	The argument this function takes is optional. If you omit passing an
17	argument to this function, then the controller event ID will be used that
18	caused this current <code lang="nksp">controller</code> event handler to be executed
19	(which is <code>$EVENT_ID</code>).
20	</p>
21	<p>
22	Dropping control change events with this function only succeeds if the
23	event just "recently" occurred. That effectively means you should drop
24	the control change event in the <code>controller</code> event handler
25	before any <code>wait()</code> calls, and before entering any loops that may
26	execute your script for a very long time. Because in both cases the
27	sampler may suspend your script for a certain amount of time and once
28	your script got resumed, the respective control change event may already
29	have entered the sampler's regular event processing chain and thus can no
30	longer be dropped.
31	</p>
32	<p>
33	With NKSP you can also use <code>ignore_event()</code> to drop control
34	change events. So <code>ignore_controller()</code> merely exists due to
35	compatibility reasons with KSP. However when you already know that the
36	event to be dropped is a control change event, then it is recommended to
37	actually call <code>ignore_controller()</code> instead of
38	<code>ignore_event()</code>.
39	</p>
40
41	<h3>Function Prototype</h3>
42	<p/>
43	<code>
44	ignore_controller([??event-id??])
45	</code>
46
47	<h3>Arguments</h3>
48	<table>
49	<tr>
50	<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
51	</tr>
52	<tr>
53	<td><code>??event-id??</code></td>
54	<td>Event ID Number</td>
55	<td>Event ID of the MIDI control change event to be dropped.<br>
56	[optional, default: ID of the event handler's event]</td>
57	</tr>
58	</table>
59
60	<h3>Return Value</h3>
61	<p>None.</p>
62
63	<h3>Examples</h3>
64	<p>
65	The following example implements a simple MIDI controller filter.
66	It causes all MIDI volume control change events (MIDI CC#7) to be dropped.
67	</p>
68	<code>
69	on init
70	{ MIDI controller number for MIDI "volume change" events }
71	declare const $volumeCC := 7
72	end on
73
74	on controller
75	if ($CC_NUM = $volumeCC)
76	{ $EVENT_ID is a built-in variable which always reflects
77	the ID of the event which caused the execution of this
78	specific event handler instance, i.e. here it reflects
79	the respective MIDI control change event }
80	ignore_controller($EVENT_ID)
81	end if
82	end on
83	</code>
84	<p>
85	Since you are almost always passing <code>$EVENT_ID</code> to <code>ignore_controller()</code>,
86	you can also omit that optional argument with NKSP. So the following
87	would behave identical with the example above.
88	</p>
89	<code>
90	on init
91	{ MIDI controller number for MIDI "volume change" events }
92	declare const $volumeCC := 7
93	end on
94
95	on controller
96	if ($CC_NUM = $volumeCC)
97	ignore_controller()
98	end if
99	end on
100	</code>
101
102	<note>
103	Dynamic, optional arguments are only supported by NKSP. If you want to
104	retain compatibility to KSP, then you should always pass a parameter
105	to this function.
106	</note>
107
108	</body>
109	</html>