/[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 3229 by schoenebeck, Sun May 28 15:22:55 2017 UTC revision 3601 by schoenebeck, Mon Sep 16 16:03:36 2019 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">acos()</code></td>
38            <td>Arc cosine function.</td>
39          </tr>
40          <tr>
41            <td><code>abs()</code></td>
42            <td>Calculates the absolute value of a given value.</td>
43          </tr>
44          <tr>
45          <td><code lang="nksp">array_equal()</code></td>          <td><code lang="nksp">array_equal()</code></td>
46          <td>Check whether two arrays are equal.</td>          <td>Check whether two arrays are equal.</td>
47        </tr>        </tr>
48        <tr>        <tr>
49            <td><code>asin()</code></td>
50            <td>Arc sine function.</td>
51          </tr>
52          <tr>
53            <td><code>atan()</code></td>
54            <td>Arc tangens function.</td>
55          </tr>
56          <tr>
57            <td><code>callback_status()</code></td>
58            <td>Returns the current status of a callback (thread).</td>
59          </tr>
60          <tr>
61            <td><code>ceil()</code></td>
62            <td>Rounds the given real number up.</td>
63          </tr>
64          <tr>
65            <td><code>cos()</code></td>
66            <td>Cosine function.</td>
67          </tr>
68          <tr>
69          <td><code lang="nksp">dec()</code></td>          <td><code lang="nksp">dec()</code></td>
70          <td>Decrements the passed integer variable by one.</td>          <td>Decrements the passed integer variable by one.</td>
71        </tr>        </tr>
72        <tr>        <tr>
73            <td><code>exit()</code></td>
74            <td>Stops execution of the current event handler instance.</td>
75          </tr>
76          <tr>
77            <td><code>exp()</code></td>
78            <td>Calculates e raised by given power.</td>
79          </tr>
80          <tr>
81            <td><code>floor()</code></td>
82            <td>Rounds the given real number down.</td>
83          </tr>
84          <tr>
85            <td><code>fork()</code></td>
86            <td>Creates new execution instances (threads).</td>
87          </tr>
88          <tr>
89          <td><code>inc()</code></td>          <td><code>inc()</code></td>
90          <td>Increments the passed integer variable by one.</td>          <td>Increments the passed integer variable by one.</td>
91        </tr>        </tr>
92        <tr>        <tr>
93            <td><code>int()</code></td>
94            <td>Short-hand alias function for function <code>real_to_int()</code>.</td>
95          </tr>
96          <tr>
97            <td><code>int_to_real()</code></td>
98            <td>Type cast from integer number to real number.</td>
99          </tr>
100          <tr>
101          <td><code>in_range()</code></td>          <td><code>in_range()</code></td>
102          <td>Checks whether a value is between two other values.</td>          <td>Checks whether a value is between two other values.</td>
103        </tr>        </tr>
104        <tr>        <tr>
105          <td><code lang="nksp">message()</code></td>          <td><code>log()</code></td>
106          <td>Prints text to the sampler's terminal.</td>          <td>Calculates the natural logarithm of given number.</td>
107        </tr>        </tr>
108        <tr>        <tr>
109          <td><code>search()</code></td>          <td><code>log10()</code></td>
110          <td>Search for a certain value within an array.</td>          <td>Calculates the logarithm to base 10 of given number.</td>
111        </tr>        </tr>
112        <tr>        <tr>
113          <td><code>sort()</code></td>          <td><code>log2()</code></td>
114          <td>Sort the given array.</td>          <td>Calculates the logarithm to base 2 of given number.</td>
115        </tr>        </tr>
116        <tr>        <tr>
117          <td><code>exit()</code></td>          <td><code>max()</code></td>
118          <td>Stops execution of the current event handler instance.</td>          <td>Calculates the maximum value of two given values.</td>
119        </tr>        </tr>
120        <tr>        <tr>
121          <td><code>wait()</code></td>          <td><code lang="nksp">message()</code></td>
122          <td>Pauses execution for a certain amount of time.</td>          <td>Prints text to the sampler's terminal.</td>
123        </tr>        </tr>
124        <tr>        <tr>
125          <td><code>stop_wait()</code></td>          <td><code>min()</code></td>
126          <td>Resumes execution of a suspended script callback.</td>          <td>Calculates the minimum value of two given values.</td>
127        </tr>        </tr>
128        <tr>        <tr>
129          <td><code>abs()</code></td>          <td><code>num_elements()</code></td>
130          <td>Calculates the absolute value of a given value.</td>          <td>Returns the size of the requested array variable.</td>
131          </tr>
132          <tr>
133            <td><code>pow()</code></td>
134            <td>Calculates given base raised by given power.</td>
135        </tr>        </tr>
136        <tr>        <tr>
137          <td><code>random()</code></td>          <td><code>random()</code></td>
138          <td>Random number generator.</td>          <td>Random number generator.</td>
139        </tr>        </tr>
140        <tr>        <tr>
141          <td><code>min()</code></td>          <td><code>real()</code></td>
142          <td>Calculates the minimum value of two given values.</td>          <td>Short-hand alias function for function <code>int_to_real()</code>.</td>
143        </tr>        </tr>
144        <tr>        <tr>
145          <td><code>max()</code></td>          <td><code>real_to_int()</code></td>
146          <td>Calculates the maximum value of two given values.</td>          <td>Type cast from real number to integer number.</td>
147        </tr>        </tr>
148        <tr>        <tr>
149          <td><code>num_elements()</code></td>          <td><code>round()</code></td>
150          <td>Returns the size of the requested array variable.</td>          <td>Rounds the given real number.</td>
151          </tr>
152          <tr>
153            <td><code>search()</code></td>
154            <td>Search for a certain value within an array.</td>
155        </tr>        </tr>
156        <tr>        <tr>
157          <td><code>sh_left()</code></td>          <td><code>sh_left()</code></td>
# Line 95  Line 161 
161          <td><code>sh_right()</code></td>          <td><code>sh_right()</code></td>
162          <td>Calculates a right bit shifted value.</td>          <td>Calculates a right bit shifted value.</td>
163        </tr>        </tr>
164          <tr>
165            <td><code>sin()</code></td>
166            <td>Sine function.</td>
167          </tr>
168          <tr>
169            <td><code>sort()</code></td>
170            <td>Sort the given array.</td>
171          </tr>
172          <tr>
173            <td><code>sqrt()</code></td>
174            <td>Calculates the square root of given number.</td>
175          </tr>
176          <tr>
177            <td><code>stop_wait()</code></td>
178            <td>Resumes execution of a suspended script callback.</td>
179          </tr>
180          <tr>
181            <td><code>tan()</code></td>
182            <td>Tangens function.</td>
183          </tr>
184          <tr>
185            <td><code>wait()</code></td>
186            <td>Pauses execution for a certain amount of time.</td>
187          </tr>
188      </table>      </table>
189        
190      <h3>Common Sampler Functions</h3>      <h3>Common Sampler Functions</h3>
191      <p>      <p>
192        Basic sampler related functions, independent from a particular sampler        Basic sampler related functions, independent from a particular sampler
# Line 107  Line 197 
197          <th>Function</th> <th>Description</th>          <th>Function</th> <th>Description</th>
198        </tr>        </tr>
199        <tr>        <tr>
200          <td><code>play_note()</code></td>          <td><code>by_marks()</code></td>
201          <td>Triggers a new note.</td>          <td>Returns all events of an event group.</td>
202        </tr>        </tr>
203        <tr>        <tr>
204          <td><code>change_note()</code></td>          <td><code>change_amp_lfo_depth()</code></td>
205          <td>Change MIDI note number of note.</td>          <td>Modifies the amplitude LFO depth.</td>
206        </tr>        </tr>
207        <tr>        <tr>
208          <td><code>change_pan()</code></td>          <td><code>change_amp_lfo_freq()</code></td>
209          <td>Changes panning of voices (stereo balance).</td>          <td>Modifies the amplitude LFO frequency.</td>
210        </tr>        </tr>
211        <tr>        <tr>
212          <td><code>change_tune()</code></td>          <td><code>change_attack()</code></td>
213          <td>Changes the tuning of voices.</td>          <td>Modifies the amplitude attack time of voices.</td>
214        </tr>        </tr>
215        <tr>        <tr>
216          <td><code>change_tune_time()</code></td>          <td><code>change_cutoff()</code></td>
217          <td>Changes the duration of tuning changes.</td>          <td>Changes filter cutoff frequency of voices.</td>
218        </tr>        </tr>
219        <tr>        <tr>
220          <td><code>change_vol()</code></td>          <td><code>change_cutoff_attack()</code></td>
221          <td>Changes the volume of voices.</td>          <td>Modifies the filter cutoff attack time of voices.</td>
222        </tr>        </tr>
223        <tr>        <tr>
224          <td><code>change_vol_time()</code></td>          <td><code>change_cutoff_decay()</code></td>
225          <td>Changes the duration of volume changes.</td>          <td>Modifies the filter cutoff decay time of voices.</td>
226        </tr>        </tr>
227        <tr>        <tr>
228          <td><code>change_cutoff()</code></td>          <td><code>change_cutoff_lfo_depth()</code></td>
229          <td>Changes filter cutoff frequency of voices.</td>          <td>Modifies the filter cutoff LFO depth.</td>
230        </tr>        </tr>
231        <tr>        <tr>
232          <td><code>change_reso()</code></td>          <td><code>change_cutoff_lfo_freq()</code></td>
233          <td>Changes filter resonance of voices.</td>          <td>Modifies the filter cutoff LFO frequency.</td>
234        </tr>        </tr>
235        <tr>        <tr>
236          <td><code>change_attack()</code></td>          <td><code>change_cutoff_release()</code></td>
237          <td>Modifies the attack time of voices.</td>          <td>Modifies the filter cutoff release time of voices.</td>
238          </tr>
239          <tr>
240            <td><code>change_cutoff_sustain()</code></td>
241            <td>Modifies the filter cutoff sustain level of voices.</td>
242        </tr>        </tr>
243        <tr>        <tr>
244          <td><code>change_decay()</code></td>          <td><code>change_decay()</code></td>
245          <td>Modifies the decay time of voices.</td>          <td>Modifies the amplitude decay time of voices.</td>
246        </tr>        </tr>
247        <tr>        <tr>
248          <td><code>change_release()</code></td>          <td><code>change_note()</code></td>
249          <td>Modifies the release time of voices.</td>          <td>Change MIDI note number of note.</td>
250        </tr>        </tr>
251        <tr>        <tr>
252          <td><code>change_amp_lfo_depth()</code></td>          <td><code>change_pan()</code></td>
253          <td>Modifies the amplitude LFO depth.</td>          <td>Changes panning of voices (stereo balance).</td>
254        </tr>        </tr>
255        <tr>        <tr>
256          <td><code>change_amp_lfo_freq()</code></td>          <td><code>change_pan_curve()</code></td>
257          <td>Modifies the amplitude LFO frequency.</td>          <td>Changes the curve type of panning (stereo balance) changes.</td>
258          </tr>
259          <tr>
260            <td><code>change_pan_time()</code></td>
261            <td>Changes the duration of panning (stereo balance) changes.</td>
262        </tr>        </tr>
263        <tr>        <tr>
264          <td><code>change_pitch_lfo_depth()</code></td>          <td><code>change_pitch_lfo_depth()</code></td>
# Line 171  Line 269 
269          <td>Modifies the pitch LFO frequency.</td>          <td>Modifies the pitch LFO frequency.</td>
270        </tr>        </tr>
271        <tr>        <tr>
272            <td><code>change_play_pos()</code></td>
273            <td>Change the sample playback position.</td>
274          </tr>
275          <tr>
276            <td><code>change_release()</code></td>
277            <td>Modifies the amplitude release time of voices.</td>
278          </tr>
279          <tr>
280            <td><code>change_reso()</code></td>
281            <td>Changes filter resonance of voices.</td>
282          </tr>
283          <tr>
284            <td><code>change_sustain()</code></td>
285            <td>Modifies the amplitude sustain level of voices.</td>
286          </tr>
287          <tr>
288            <td><code>change_tune()</code></td>
289            <td>Changes the tuning of voices.</td>
290          </tr>
291          <tr>
292            <td><code>change_tune_curve()</code></td>
293            <td>Changes the curve type of tuning changes.</td>
294          </tr>
295          <tr>
296            <td><code>change_tune_time()</code></td>
297            <td>Changes the duration of tuning changes.</td>
298          </tr>
299          <tr>
300          <td><code>change_velo()</code></td>          <td><code>change_velo()</code></td>
301          <td>Change MIDI velocity of note.</td>          <td>Change MIDI velocity of note.</td>
302        </tr>        </tr>
303        <tr>        <tr>
304            <td><code>change_vol()</code></td>
305            <td>Changes the volume of voices.</td>
306          </tr>
307          <tr>
308            <td><code>change_vol_curve()</code></td>
309            <td>Changes the curve type of volume changes.</td>
310          </tr>
311          <tr>
312            <td><code>change_vol_time()</code></td>
313            <td>Changes the duration of volume changes.</td>
314          </tr>
315          <tr>
316            <td><code>delete_event_mark()</code></td>
317            <td>Removes an event from some event group.</td>
318          </tr>
319          <tr>
320          <td><code>event_status()</code></td>          <td><code>event_status()</code></td>
321          <td>Checks and returns whether a particular note is still alive.</td>          <td>Checks and returns whether a particular note is still alive.</td>
322        </tr>        </tr>
# Line 191  Line 333 
333          <td>Get the current value of a specific note parameter.</td>          <td>Get the current value of a specific note parameter.</td>
334        </tr>        </tr>
335        <tr>        <tr>
336          <td><code>set_event_par()</code></td>          <td><code>ignore_controller()</code></td>
337          <td>Change the value of a specific note parameter.</td>          <td>Drops the given MIDI control change event.</td>
       </tr>  
       <tr>  
         <td><code>set_controller()</code></td>  
         <td>Creates a MIDI control change event.</td>  
338        </tr>        </tr>
339        <tr>        <tr>
340          <td><code>ignore_event()</code></td>          <td><code>ignore_event()</code></td>
341          <td>Drops the given event.</td>          <td>Drops the given event.</td>
342        </tr>        </tr>
343        <tr>        <tr>
         <td><code>ignore_controller()</code></td>  
         <td>Drops the given MIDI control change event.</td>  
       </tr>  
       <tr>  
344          <td><code>note_off()</code></td>          <td><code>note_off()</code></td>
345          <td>Releases the requested note.</td>          <td>Releases the requested note.</td>
346        </tr>        </tr>
347        <tr>        <tr>
348          <td><code>set_event_mark()</code></td>          <td><code>play_note()</code></td>
349          <td>Adds an event to an event group.</td>          <td>Triggers a new note.</td>
350        </tr>        </tr>
351        <tr>        <tr>
352          <td><code>delete_event_mark()</code></td>          <td><code>set_controller()</code></td>
353          <td>Removes an event from some event group.</td>          <td>Creates a MIDI control change event.</td>
354        </tr>        </tr>
355        <tr>        <tr>
356          <td><code>by_marks()</code></td>          <td><code>set_event_mark()</code></td>
357          <td>Returns all events of an event group.</td>          <td>Adds an event to an event group.</td>
358          </tr>
359          <tr>
360            <td><code>set_event_par()</code></td>
361            <td>Change the value of a specific note parameter.</td>
362        </tr>        </tr>
363      </table>      </table>
364        
365      <h3>GigaStudio Format Functions</h3>      <h3>GigaStudio Format Functions</h3>
366      <p>      <p>
367        Sampler format specific functions, dedicated to the individual features        Sampler format specific functions, dedicated to the individual features
# Line 259  Line 397 
397          <th>Variable</th> <th>Description</th>          <th>Variable</th> <th>Description</th>
398        </tr>        </tr>
399        <tr>        <tr>
400            <td><code>$CALLBACK_STATUS_QUEUE</code></td>
401            <td>Built-in constant reflecting the status of a callback to be
402                alive but suspended. See <code>callback_status()</code> for details.</td>
403          </tr>
404          <tr>
405            <td><code>$CALLBACK_STATUS_RUNNING</code></td>
406            <td>Built-in constant reflecting the status of a callback to be
407                alive and currently executing. See <code>callback_status()</code>
408                for details.</td>
409          </tr>
410          <tr>
411            <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
412            <td>Built-in constant reflecting the status of a callback to be
413                not alive. See <code>callback_status()</code> for details.</td>
414          </tr>
415          <tr>
416          <td><code>$KSP_TIMER</code></td>          <td><code>$KSP_TIMER</code></td>
417          <td>Preserved for compatiblity reasons with KSP, returns the same value          <td>Preserved for compatiblity reasons with KSP, returns the same value
418             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 303  Line 457 
457          </td>          </td>
458        </tr>        </tr>
459        <tr>        <tr>
460            <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
461            <td>
462              Reflects the callback IDs of all child threads which the current
463              script callback instance spawned by having called <code>fork()</code> before.
464              See the latter function for details about this array variable.
465            </td>
466          </tr>
467          <tr>
468            <td><code>$NKSP_CALLBACK_PARENT_ID</code></td>
469            <td>
470              If the current execution thread is a child thread spawned by a <code>fork()</code>
471              call before, then this variable reflects the callback ID of the parent
472              thread which created this child thread. Otherwise this variable is <code>0</code>.
473              See <code>fork()</code> for more details about this variable.
474            </td>
475          </tr>
476          <tr>
477          <td><code>$NKSP_REAL_TIMER</code></td>          <td><code>$NKSP_REAL_TIMER</code></td>
478          <td>Returns the current time stamp in reality (in microseconds). You may          <td>Returns the current time stamp in reality (in microseconds). You may
479              read this variable from time to time to take              read this variable from time to time to take
# Line 364  Line 535 
535          <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>          <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>
536        </tr>        </tr>
537        <tr>        <tr>
538            <td><code>$NI_MATH_E</code></td>
539            <td>Base of the natural logarithm (approximately being <code>2.71828</code>)</td>
540          </tr>
541          <tr>
542            <td><code>$NI_MATH_PI</code></td>
543            <td>Natural constant relfecting the ratio of a circle's circumference to its diameter (approximately being <code>3.14159</code>).</td>
544          </tr>
545          <tr>
546          <td><code>$NKSP_IGNORE_WAIT</code></td>          <td><code>$NKSP_IGNORE_WAIT</code></td>
547          <td>If this boolean built-in variable is <code>1</code> then all calls of your          <td>If this boolean built-in variable is <code>1</code> then all calls of your
548              event handler instance to function <code>wait()</code> will be ignored.              event handler instance to function <code>wait()</code> will be ignored.
# Line 481  Line 660 
660              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>
661        </tr>        </tr>
662        <tr>        <tr>
663            <td><code>$NKSP_EASE_IN_EASE_OUT</code></td>
664            <td>Used to select a fade curve with "ease in and ease out" shape.</td>
665          </tr>
666          <tr>
667            <td><code>$NKSP_LINEAR</code></td>
668            <td>Used to select a fade curve with linear shape.</td>
669          </tr>
670          <tr>
671          <td><code>$VCC_MONO_AT</code></td>          <td><code>$VCC_MONO_AT</code></td>
672          <td>Constant identifying the MIDI monophonic aftertouch controller (also          <td>Constant identifying the MIDI monophonic aftertouch controller (also
673              called <i title="Amount of force on held-down key.">              called <i title="Amount of force on held-down key.">
# Line 662  Line 849 
849          <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>
850        </tr>        </tr>
851      </table>      </table>
852    
853            <h2>Built-In Preprocessor Conditions</h2>
854        <p>
855          These are the built-in preprocessor conditions available with the NKSP realt-time
856          instrument script language.
857        </p>
858            
859        <h3>Core Language Preprocessor Conditions</h3>
860        <p>
861          Most fundamental NKSP built-in preprocessor conditions, independent from
862          any purpose of being used in a sampler.
863        </p>
864        <table>
865          <tr>
866            <th>Condition</th> <th>Description</th>
867          </tr>
868          <tr>
869            <td><code>NKSP_NO_MESSAGE</code></td>
870            <td>
871              By default this condition is not set. By explicitly enabling this
872              condition with <code>SET_CONDITION(NKSP_NO_MESSAGE)</code> it
873              causes all subsequent <code>message()</code> calls to be ignored
874              and filtered out on preprocessor level. See function <code>message()</code>
875              for details.
876            </td>
877          </tr>
878        </table>
879    
880    </body>    </body>
881  </html>  </html>
Legend:
Removed from v.3229  
changed lines
  Added in v.3601
  ViewVC Help
Powered by ViewVC