/[svn]/doc/docbase/instrument_scripts/nksp/reference/functions/nksp_ignore_controller_function.html
ViewVC logotype

Diff of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_ignore_controller_function.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2732 by schoenebeck, Sun Apr 26 20:54:00 2015 UTC revision 3213 by schoenebeck, Thu May 25 13:25:43 2017 UTC
# Line 10  Line 10 
10        Drops the given MIDI control change event and thus prevents the supplied        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        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        i.e. to filter out MIDI control change events, before they are causing
13        the sound to be changed.        any sound to be changed.
14      </p>      </p>
15      <p>      <p>
16        The argument this function takes is optional. If you omit passing an        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        argument to this function, then the controller event ID will be used that
18        caused this current <code>controller</code> event handler to be executed.        caused this current <code lang="nksp">controller</code> event handler to be executed
19          (which is <code>$EVENT_ID</code>).
20      </p>      </p>
21      <p>      <p>
22        There is also an <code>ignore_event()</code> function. With        Dropping control change events with this function only succeeds if the
23        NKSP the two functions are both doing the same thing though.        event just "recently" occurred. That effectively means you should drop
24        The two exist merely due to compatibility reasons with KSP.        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>      </p>
40    
41      <h3>Function Prototype</h3>      <h3>Function Prototype</h3>
# Line 37  ignore_controller([??event-id??]) Line 52  ignore_controller([??event-id??])
52        <tr>        <tr>
53          <td><code>??event-id??</code></td>          <td><code>??event-id??</code></td>
54          <td>Event ID Number</td>          <td>Event ID Number</td>
55          <td>MIDI control change event to be dropped.<br>          <td>Event ID of the MIDI control change event to be dropped.<br>
56              [optional, default: ID of the event handler's event]</td>              [optional, default: ID of the event handler's event]</td>
57        </tr>        </tr>
58      </table>      </table>
# Line 46  ignore_controller([??event-id??]) Line 61  ignore_controller([??event-id??])
61      <p>None.</p>      <p>None.</p>
62            
63      <h3>Examples</h3>      <h3>Examples</h3>
64      <p>None yet.<p>      <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>      <note>
103        Dynamic, optional arguments are only supported by NKSP. If you want to        Dynamic, optional arguments are only supported by NKSP. If you want to
Legend:
Removed from v.2732  
changed lines
  Added in v.3213
  ViewVC Help
Powered by ViewVC