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.
    </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>

    <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	</p>
20	<p>
21	Dropping control change events with this function only succeeds if the
22	event just "recently" occurred. That effectively means you should drop
23	the control change event in the <code>controller</code> event handler
24	before any <code>wait()</code> calls, and before entering any loops that may
25	execute your script for a very long time. Because in both cases the
26	sampler may suspend your script for a certain amount of time and once
27	your script got resumed, the respective control change event may already
28	have entered the sampler's regular event processing chain and thus can no
29	longer be dropped.
30	</p>
31	<p>
32	With NKSP you can also use <code>ignore_event()</code> to drop control
33	change events. So <code>ignore_controller()</code> merely exists due to
34	compatibility reasons with KSP. However when you already know that the
35	event to be dropped is a control change event, then it is recommended to
36	actually call <code>ignore_controller()</code> instead of
37	<code>ignore_event()</code>.
38	</p>
39
40	<h3>Function Prototype</h3>
41	<p/>
42	<code>
43	ignore_controller([??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</td>
54	<td>Event ID of the MIDI control change event 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 MIDI controller filter.
65	It causes all MIDI volume control change events (MIDI CC#7) to be dropped.
66	<p>
67	<code>
68	on init
69	{ MIDI controller number for MIDI "volume change" events }
70	declare const $volumeCC := 7
71	end on
72
73	on controller
74	if ($CC_NUM = $volumeCC)
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 control change event }
79	ignore_controller($EVENT_ID)
80	end if
81	end on
82	</code>
83
84	<note>
85	Dynamic, optional arguments are only supported by NKSP. If you want to
86	retain compatibility to KSP, then you should always pass a parameter
87	to this function.
88	</note>
89
90	</body>
91	</html>