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