/[svn]/doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html
ViewVC logotype

Diff of /doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html

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

revision 2946 by schoenebeck, Thu Jul 14 00:44:04 2016 UTC revision 3396 by schoenebeck, Wed Dec 6 18:53:32 2017 UTC
# Line 11  Line 11 
11      <p>      <p>
12        This document gives you an overview of all built-in functions and built-in        This document gives you an overview of all built-in functions and built-in
13        variables provided by the NKSP real-time instrument script language.        variables provided by the NKSP real-time instrument script language.
14          If you are new to NKSP, then you may want to read the
15          <a href="01_nksp.html">NKSP language tour</a> first.
16      </p>      </p>
17    
18      <h2>Built-In Functions</h2>      <h2>Built-In Functions</h2>
19      <p>      <p>
20        These are the built-in functions available with the NKSP realt-time        These are the built-in functions available with the NKSP real-time
21        instrument script language.        instrument script language.
22      </p>      </p>
23    
# Line 28  Line 30 
30          <th>Function</th> <th>Description</th>          <th>Function</th> <th>Description</th>
31        </tr>        </tr>
32        <tr>        <tr>
33            <td><code lang="nksp">abort()</code></td>
34            <td>Stops execution of a script callback.</td>
35          </tr>
36          <tr>
37            <td><code lang="nksp">array_equal()</code></td>
38            <td>Check whether two arrays are equal.</td>
39          </tr>
40          <tr>
41            <td><code>fork()</code></td>
42            <td>Creates new execution instances (threads).</td>
43          </tr>
44          <tr>
45            <td><code>callback_status()</code></td>
46            <td>Returns the current status of a callback (thread).</td>
47          </tr>
48          <tr>
49          <td><code lang="nksp">dec()</code></td>          <td><code lang="nksp">dec()</code></td>
50          <td>Decrements the passed integer variable by one.</td>          <td>Decrements the passed integer variable by one.</td>
51        </tr>        </tr>
# Line 36  Line 54 
54          <td>Increments the passed integer variable by one.</td>          <td>Increments the passed integer variable by one.</td>
55        </tr>        </tr>
56        <tr>        <tr>
57            <td><code>in_range()</code></td>
58            <td>Checks whether a value is between two other values.</td>
59          </tr>
60          <tr>
61          <td><code lang="nksp">message()</code></td>          <td><code lang="nksp">message()</code></td>
62          <td>Prints text to the sampler's terminal.</td>          <td>Prints text to the sampler's terminal.</td>
63        </tr>        </tr>
64        <tr>        <tr>
65            <td><code>search()</code></td>
66            <td>Search for a certain value within an array.</td>
67          </tr>
68          <tr>
69            <td><code>sort()</code></td>
70            <td>Sort the given array.</td>
71          </tr>
72          <tr>
73          <td><code>exit()</code></td>          <td><code>exit()</code></td>
74          <td>Stops execution of the current event handler instance.</td>          <td>Stops execution of the current event handler instance.</td>
75        </tr>        </tr>
# Line 48  Line 78 
78          <td>Pauses execution for a certain amount of time.</td>          <td>Pauses execution for a certain amount of time.</td>
79        </tr>        </tr>
80        <tr>        <tr>
81            <td><code>stop_wait()</code></td>
82            <td>Resumes execution of a suspended script callback.</td>
83          </tr>
84          <tr>
85          <td><code>abs()</code></td>          <td><code>abs()</code></td>
86          <td>Calculates the absolute value of a given value.</td>          <td>Calculates the absolute value of a given value.</td>
87        </tr>        </tr>
# Line 56  Line 90 
90          <td>Random number generator.</td>          <td>Random number generator.</td>
91        </tr>        </tr>
92        <tr>        <tr>
93            <td><code>min()</code></td>
94            <td>Calculates the minimum value of two given values.</td>
95          </tr>
96          <tr>
97            <td><code>max()</code></td>
98            <td>Calculates the maximum value of two given values.</td>
99          </tr>
100          <tr>
101          <td><code>num_elements()</code></td>          <td><code>num_elements()</code></td>
102          <td>Returns the size of the requested array variable.</td>          <td>Returns the size of the requested array variable.</td>
103        </tr>        </tr>
104          <tr>
105            <td><code>sh_left()</code></td>
106            <td>Calculates a left bit shifted value.</td>
107          </tr>
108          <tr>
109            <td><code>sh_right()</code></td>
110            <td>Calculates a right bit shifted value.</td>
111          </tr>
112      </table>      </table>
113            
114      <h3>Common Sampler Functions</h3>      <h3>Common Sampler Functions</h3>
# Line 75  Line 125 
125          <td>Triggers a new note.</td>          <td>Triggers a new note.</td>
126        </tr>        </tr>
127        <tr>        <tr>
128            <td><code>change_note()</code></td>
129            <td>Change MIDI note number of note.</td>
130          </tr>
131          <tr>
132          <td><code>change_pan()</code></td>          <td><code>change_pan()</code></td>
133          <td>Changes panning of voices (stereo balance).</td>          <td>Changes panning of voices (stereo balance).</td>
134        </tr>        </tr>
135        <tr>        <tr>
136            <td><code>change_pan_time()</code></td>
137            <td>Changes the duration of panning (stereo balance) changes.</td>
138          </tr>
139          <tr>
140            <td><code>change_pan_curve()</code></td>
141            <td>Changes the curve type of panning (stereo balance) changes.</td>
142          </tr>
143          <tr>
144            <td><code>change_play_pos()</code></td>
145            <td>Change the sample playback position.</td>
146          </tr>
147          <tr>
148          <td><code>change_tune()</code></td>          <td><code>change_tune()</code></td>
149          <td>Changes the tuning of voices.</td>          <td>Changes the tuning of voices.</td>
150        </tr>        </tr>
151        <tr>        <tr>
152            <td><code>change_tune_time()</code></td>
153            <td>Changes the duration of tuning changes.</td>
154          </tr>
155          <tr>
156            <td><code>change_tune_curve()</code></td>
157            <td>Changes the curve type of tuning changes.</td>
158          </tr>
159          <tr>
160          <td><code>change_vol()</code></td>          <td><code>change_vol()</code></td>
161          <td>Changes the volume of voices.</td>          <td>Changes the volume of voices.</td>
162        </tr>        </tr>
163        <tr>        <tr>
164            <td><code>change_vol_time()</code></td>
165            <td>Changes the duration of volume changes.</td>
166          </tr>
167          <tr>
168            <td><code>change_vol_curve()</code></td>
169            <td>Changes the curve type of volume changes.</td>
170          </tr>
171          <tr>
172          <td><code>change_cutoff()</code></td>          <td><code>change_cutoff()</code></td>
173          <td>Changes filter cutoff frequency of voices.</td>          <td>Changes filter cutoff frequency of voices.</td>
174        </tr>        </tr>
# Line 95  Line 177 
177          <td>Changes filter resonance of voices.</td>          <td>Changes filter resonance of voices.</td>
178        </tr>        </tr>
179        <tr>        <tr>
180            <td><code>change_attack()</code></td>
181            <td>Modifies the amplitude attack time of voices.</td>
182          </tr>
183          <tr>
184            <td><code>change_decay()</code></td>
185            <td>Modifies the amplitude decay time of voices.</td>
186          </tr>
187          <tr>
188            <td><code>change_sustain()</code></td>
189            <td>Modifies the amplitude sustain level of voices.</td>
190          </tr>
191          <tr>
192            <td><code>change_release()</code></td>
193            <td>Modifies the amplitude release time of voices.</td>
194          </tr>
195    
196          <tr>
197            <td><code>change_cutoff_attack()</code></td>
198            <td>Modifies the filter cutoff attack time of voices.</td>
199          </tr>
200          <tr>
201            <td><code>change_cutoff_decay()</code></td>
202            <td>Modifies the filter cutoff decay time of voices.</td>
203          </tr>
204          <tr>
205            <td><code>change_cutoff_sustain()</code></td>
206            <td>Modifies the filter cutoff sustain level of voices.</td>
207          </tr>
208          <tr>
209            <td><code>change_cutoff_release()</code></td>
210            <td>Modifies the filter cutoff release time of voices.</td>
211          </tr>
212    
213          <tr>
214            <td><code>change_amp_lfo_depth()</code></td>
215            <td>Modifies the amplitude LFO depth.</td>
216          </tr>
217          <tr>
218            <td><code>change_amp_lfo_freq()</code></td>
219            <td>Modifies the amplitude LFO frequency.</td>
220          </tr>
221    
222          <tr>
223            <td><code>change_cutoff_lfo_depth()</code></td>
224            <td>Modifies the filter cutoff LFO depth.</td>
225          </tr>
226          <tr>
227            <td><code>change_cutoff_lfo_freq()</code></td>
228            <td>Modifies the filter cutoff LFO frequency.</td>
229          </tr>
230    
231          <tr>
232            <td><code>change_pitch_lfo_depth()</code></td>
233            <td>Modifies the pitch LFO depth.</td>
234          </tr>
235          <tr>
236            <td><code>change_pitch_lfo_freq()</code></td>
237            <td>Modifies the pitch LFO frequency.</td>
238          </tr>
239          <tr>
240            <td><code>change_velo()</code></td>
241            <td>Change MIDI velocity of note.</td>
242          </tr>
243          <tr>
244          <td><code>event_status()</code></td>          <td><code>event_status()</code></td>
245          <td>Checks and returns whether a particular note is still alive.</td>          <td>Checks and returns whether a particular note is still alive.</td>
246        </tr>        </tr>
247        <tr>        <tr>
248            <td><code>fade_in()</code></td>
249            <td>Fade the requested note in.</td>
250          </tr>
251          <tr>
252            <td><code>fade_out()</code></td>
253            <td>Fade the requested note out.</td>
254          </tr>
255          <tr>
256            <td><code>get_event_par()</code></td>
257            <td>Get the current value of a specific note parameter.</td>
258          </tr>
259          <tr>
260            <td><code>set_event_par()</code></td>
261            <td>Change the value of a specific note parameter.</td>
262          </tr>
263          <tr>
264          <td><code>set_controller()</code></td>          <td><code>set_controller()</code></td>
265          <td>Creates a MIDI control change event.</td>          <td>Creates a MIDI control change event.</td>
266        </tr>        </tr>
# Line 141  Line 303 
303          <td><code>gig_set_dim_zone()</code></td>          <td><code>gig_set_dim_zone()</code></td>
304          <td>Changes the currently active dimension zone.</td>          <td>Changes the currently active dimension zone.</td>
305        </tr>        </tr>
306          <tr>
307            <td><code>same_region()</code></td>
308            <td>Check whether two keys are mapped to the same region.</td>
309          </tr>
310      </table>      </table>
311    
312      <h2>Built-In Variables</h2>      <h2>Built-In Variables</h2>
# Line 159  Line 325 
325          <th>Variable</th> <th>Description</th>          <th>Variable</th> <th>Description</th>
326        </tr>        </tr>
327        <tr>        <tr>
328            <td><code>$CALLBACK_STATUS_QUEUE</code></td>
329            <td>Built-in constant reflecting the status of a callback to be
330                alive but suspended. See <code>callback_status()</code> for details.</td>
331          </tr>
332          <tr>
333            <td><code>$CALLBACK_STATUS_RUNNING</code></td>
334            <td>Built-in constant reflecting the status of a callback to be
335                alive and currently executing. See <code>callback_status()</code>
336                for details.</td>
337          </tr>
338          <tr>
339            <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
340            <td>Built-in constant reflecting the status of a callback to be
341                not alive. See <code>callback_status()</code> for details.</td>
342          </tr>
343          <tr>
344          <td><code>$KSP_TIMER</code></td>          <td><code>$KSP_TIMER</code></td>
345          <td>Preserved for compatiblity reasons with KSP, returns the same value          <td>Preserved for compatiblity reasons with KSP, returns the same value
346             as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).             as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
# Line 203  Line 385 
385          </td>          </td>
386        </tr>        </tr>
387        <tr>        <tr>
388            <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
389            <td>
390              Reflects the callback IDs of all child threads which the current
391              script callback instance spawned by having called <code>fork()</code> before.
392              See the latter function for details about this array variable.
393            </td>
394          </tr>
395          <tr>
396            <td><code>$NKSP_CALLBACK_PARENT_ID</code></td>
397            <td>
398              If the current execution thread is a child thread spawned by a <code>fork()</code>
399              call before, then this variable reflects the callback ID of the parent
400              thread which created this child thread. Otherwise this variable is <code>0</code>.
401              See <code>fork()</code> for more details about this variable.
402            </td>
403          </tr>
404          <tr>
405          <td><code>$NKSP_REAL_TIMER</code></td>          <td><code>$NKSP_REAL_TIMER</code></td>
406          <td>Returns the current time stamp in reality (in microseconds). You may          <td>Returns the current time stamp in reality (in microseconds). You may
407              read this variable from time to time to take              read this variable from time to time to take
# Line 232  Line 431 
431              </note>              </note>
432          </td>          </td>
433        </tr>        </tr>
434          <tr>
435            <td><code>$NI_CALLBACK_ID</code></td>
436            <td>Reflects the current event handler instance's unique callback ID.
437                For the same event type there may be more than
438                one event handler instances running. Each one of them has
439                its own callback ID. You can get the current event handler
440                instance's callback ID by reading this built-in variable.</td>
441          </tr>
442          <tr>
443            <td><code>$NI_CALLBACK_TYPE</code></td>
444            <td>Reflects the event type of the current event handler. This variable
445                may reflect one of the following built-in constants:
446                <code>$NI_CB_TYPE_INIT</code>, <code>$NI_CB_TYPE_NOTE</code>,
447                <code>$NI_CB_TYPE_RELEASE</code>, <code>$NI_CB_TYPE_CONTROLLER</code>.</td>
448          </tr>
449          <tr>
450            <td><code>$NI_CB_TYPE_INIT</code></td>
451            <td>Built-in constant reflecting an <code>init</code> event handler type.</td>
452          </tr>
453          <tr>
454            <td><code>$NI_CB_TYPE_NOTE</code></td>
455            <td>Built-in constant reflecting a <code>note</code> event handler type.</td>
456          </tr>
457          <tr>
458            <td><code>$NI_CB_TYPE_RELEASE</code></td>
459            <td>Built-in constant reflecting a <code>release</code> event handler type.</td>
460          </tr>
461          <tr>
462            <td><code>$NI_CB_TYPE_CONTROLLER</code></td>
463            <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>
464          </tr>
465          <tr>
466            <td><code>$NKSP_IGNORE_WAIT</code></td>
467            <td>If this boolean built-in variable is <code>1</code> then all calls of your
468                event handler instance to function <code>wait()</code> will be ignored.
469                This may for example be the case if another event handler instance
470                resumed your paused script by calling <code>stop_wait()</code> and
471                passing <code>1</code> to the 2nd argument of that function.</td>
472          </tr>
473      </table>      </table>
474    
475      <h3>Common Sampler Variables</h3>      <h3>Common Sampler Variables</h3>
# Line 244  Line 482 
482          <th>Variable</th> <th>Description</th>          <th>Variable</th> <th>Description</th>
483        </tr>        </tr>
484        <tr>        <tr>
485            <td><code>%ALL_EVENTS</code></td>
486            <td>
487              Note IDs of all currently active notes of the current sampler part (a.k.a. sampler channel).
488              This may be passed to many built-in functions like <code>note_off()</code>.
489              This array variable only contains IDs of notes which were launched due
490              to MIDI note-on events. This variable does not contain IDs of child notes
491              (i.e. notes which were launched programmatically by calling <code>play_note()</code>).
492              <note>
493                In contrast to KSP this variable is an integer array type, whereas KSP's
494                pendent of this built-in variable is an integer constant (scalar) called
495                <code>$ALL_EVENTS</code>. Using the latter with NKSP will cause a
496                parser warning, the behavior will be the same though.
497              </note>
498            </td>
499          </tr>
500          <tr>
501          <td><code>$CC_NUM</code></td>          <td><code>$CC_NUM</code></td>
502          <td>MIDI controller number that caused the <code>controller</code>          <td>MIDI controller number that caused the <code>controller</code>
503              handler to be executed (only useful in the context of a              handler to be executed (only useful in the context of a
# Line 289  Line 543 
543              note is still "alive".</td>              note is still "alive".</td>
544        </tr>        </tr>
545        <tr>        <tr>
546            <td><code>$EVENT_PAR_NOTE</code></td>
547            <td>Constant value symbolizing the "note number" parameter. See
548                <code>get_event_par()</code> and <code>set_event_par()</code>
549                for details.</td>
550          </tr>
551          <tr>
552            <td><code>$EVENT_PAR_TUNE</code></td>
553            <td>Constant value symbolizing the "tune" parameter. See
554                <code>get_event_par()</code> and <code>set_event_par()</code>
555                for details.</td>
556          </tr>
557          <tr>
558            <td><code>$EVENT_PAR_VELOCITY</code></td>
559            <td>Constant value symbolizing the "note velocity" parameter. See
560                <code>get_event_par()</code> and <code>set_event_par()</code>
561                for details.</td>
562          </tr>
563          <tr>
564            <td><code>$EVENT_PAR_VOLUME</code></td>
565            <td>Constant value symbolizing the "volume" parameter. See
566                <code>get_event_par()</code> and <code>set_event_par()</code>
567                for details.</td>
568          </tr>
569          <tr>
570            <td><code>$EVENT_PAR_0</code> to <code>$EVENT_PAR_3</code></td>
571            <td>Four constant values symbolizing the 4 possible user specific
572                parameters, which i.e. might be used to pass data from one script
573                (slot) to another script (slot). See  <code>get_event_par()</code>
574                and <code>set_event_par()</code> for details.</td>
575          </tr>
576          <tr>
577          <td><code>%KEY_DOWN[]</code></td>          <td><code>%KEY_DOWN[]</code></td>
578          <td>This can be used in any context to check whether a certain MIDI          <td>This can be used in any context to check whether a certain MIDI
579              key is currently pressed down. Use the respective MIDI note number              key is currently pressed down. Use the respective MIDI note number
580              as index to this array variable (see also <code>event_status()</code>).</td>              as index to this array variable (see also <code>event_status()</code>).</td>
581        </tr>        </tr>
582        <tr>        <tr>
583            <td><code>$NKSP_EASE_IN_EASE_OUT</code></td>
584            <td>Used to select a fade curve with "ease in and ease out" shape.</td>
585          </tr>
586          <tr>
587            <td><code>$NKSP_LINEAR</code></td>
588            <td>Used to select a fade curve with linear shape.</td>
589          </tr>
590          <tr>
591          <td><code>$VCC_MONO_AT</code></td>          <td><code>$VCC_MONO_AT</code></td>
592          <td>Constant identifying the MIDI monophonic aftertouch controller (also          <td>Constant identifying the MIDI monophonic aftertouch controller (also
593              called <i title="Amount of force on held-down key.">              called <i title="Amount of force on held-down key.">
# Line 368  Line 661 
661          <td>Constant that identifies the <i>keyboard position dimension</i>.</td>          <td>Constant that identifies the <i>keyboard position dimension</i>.</td>
662        </tr>        </tr>
663        <tr>        <tr>
664          <td><code>$GIG_DIM_ROUNDROBIN"</code></td>          <td><code>$GIG_DIM_ROUNDROBIN</code></td>
665          <td>Constant that identifies the <i>round robin dimension</i>.</td>          <td>Constant that identifies the <i>round robin dimension</i>.</td>
666        </tr>        </tr>
667        <tr>        <tr>
# Line 476  Line 769 
769          <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>          <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>
770        </tr>        </tr>
771      </table>      </table>
772    
773            <h2>Built-In Preprocessor Conditions</h2>
774        <p>
775          These are the built-in preprocessor conditions available with the NKSP realt-time
776          instrument script language.
777        </p>
778            
779        <h3>Core Language Preprocessor Conditions</h3>
780        <p>
781          Most fundamental NKSP built-in preprocessor conditions, independent from
782          any purpose of being used in a sampler.
783        </p>
784        <table>
785          <tr>
786            <th>Condition</th> <th>Description</th>
787          </tr>
788          <tr>
789            <td><code>NKSP_NO_MESSAGE</code></td>
790            <td>
791              By default this condition is not set. By explicitly enabling this
792              condition with <code>SET_CONDITION(NKSP_NO_MESSAGE)</code> it
793              causes all subsequent <code>message()</code> calls to be ignored
794              and filtered out on preprocessor level. See function <code>message()</code>
795              for details.
796            </td>
797          </tr>
798        </table>
799    
800    </body>    </body>
801  </html>  </html>
Legend:
Removed from v.2946  
changed lines
  Added in v.3396
  ViewVC Help
Powered by ViewVC