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>
    <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	schoenebeck	2732	<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	schoenebeck	2881	any sound to be changed.
14	schoenebeck	2732	</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	schoenebeck	2742	caused this current <code lang="nksp">controller</code> event handler to be executed.
19	schoenebeck	2732	</p>
20			<p>
21	schoenebeck	2881	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	schoenebeck	2882	before any <code>wait()</code> calls, and before entering any loops that may
25	schoenebeck	2881	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	schoenebeck	2732	</p>
31	schoenebeck	2881	<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	schoenebeck	2732
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	schoenebeck	3209	<td>Event ID of the MIDI control change event to be dropped.<br>
55	schoenebeck	2732	[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	schoenebeck	3209	<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	schoenebeck	3211	</p>
67	schoenebeck	3209	<code>
68			on init
69			{ MIDI controller number for MIDI "volume change" events }
70			declare const $volumeCC := 7
71			end on
72	schoenebeck	2732
73	schoenebeck	3209	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	schoenebeck	3210	ignore_controller($EVENT_ID)
80	schoenebeck	3209	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_controller()</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 controller number for MIDI "volume change" events }
91			declare const $volumeCC := 7
92			end on
93	schoenebeck	3209
94	schoenebeck	3211	on controller
95			if ($CC_NUM = $volumeCC)
96			ignore_controller()
97			end if
98			end on
99			</code>
100
101	schoenebeck	2732	<note>
102			Dynamic, optional arguments are only supported by NKSP. If you want to
103			retain compatibility to KSP, then you should always pass a parameter
104			to this function.
105			</note>
106
107			</body>
108			</html>