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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3887 - (hide annotations) (download) (as text)
Sun May 9 18:00:00 2021 UTC (2 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 35768 byte(s)
* Add release notes for LinuxSampler 2.2.0 release.

1 schoenebeck 2732 <html>
2     <head>
3     <meta name="author" content="Christian Schoenebeck">
4     <title>NKSP Reference</title>
5     <urlpath>Reference</urlpath>
6     <navpath>Reference Manual</navpath>
7     <meta name="description" content="Reference documentation of the NKSP real-time instrument script language.">
8 schoenebeck 3603 <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 schoenebeck 2732 </head>
11     <body>
12     <h1>NKSP Reference</h1>
13     <p>
14     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.
16 schoenebeck 3396 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 schoenebeck 2732 </p>
19    
20 schoenebeck 3887 <h2 id="functions">Built-In Functions</h2>
21 schoenebeck 2732 <p>
22 schoenebeck 3265 These are the built-in functions available with the NKSP real-time
23 schoenebeck 2732 instrument script language.
24     </p>
25    
26     <h3>Core Language Functions</h3>
27     <p>
28     Most fundamental NKSP functions, independent from any purpose of being used in a sampler.
29     </p>
30     <table>
31     <tr>
32     <th>Function</th> <th>Description</th>
33     </tr>
34     <tr>
35 schoenebeck 3278 <td><code lang="nksp">abort()</code></td>
36     <td>Stops execution of a script callback.</td>
37     </tr>
38     <tr>
39 schoenebeck 3601 <td><code lang="nksp">acos()</code></td>
40     <td>Arc cosine function.</td>
41     </tr>
42     <tr>
43 schoenebeck 3580 <td><code>abs()</code></td>
44     <td>Calculates the absolute value of a given value.</td>
45     </tr>
46     <tr>
47 schoenebeck 3223 <td><code lang="nksp">array_equal()</code></td>
48     <td>Check whether two arrays are equal.</td>
49     </tr>
50     <tr>
51 schoenebeck 3601 <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 schoenebeck 3297 <td><code>callback_status()</code></td>
60     <td>Returns the current status of a callback (thread).</td>
61     </tr>
62     <tr>
63 schoenebeck 3601 <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 schoenebeck 2946 <td><code lang="nksp">dec()</code></td>
72     <td>Decrements the passed integer variable by one.</td>
73     </tr>
74     <tr>
75 schoenebeck 3580 <td><code>exit()</code></td>
76 schoenebeck 3785 <td>Returns from current execution block.</td>
77 schoenebeck 3580 </tr>
78     <tr>
79 schoenebeck 3601 <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 schoenebeck 3580 <td><code>fork()</code></td>
88     <td>Creates new execution instances (threads).</td>
89     </tr>
90     <tr>
91 schoenebeck 2946 <td><code>inc()</code></td>
92     <td>Increments the passed integer variable by one.</td>
93     </tr>
94     <tr>
95 schoenebeck 3601 <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 schoenebeck 3077 <td><code>in_range()</code></td>
104     <td>Checks whether a value is between two other values.</td>
105     </tr>
106     <tr>
107 schoenebeck 3601 <td><code>log()</code></td>
108     <td>Calculates the natural logarithm of given number.</td>
109     </tr>
110     <tr>
111     <td><code>log10()</code></td>
112     <td>Calculates the logarithm to base 10 of given number.</td>
113     </tr>
114     <tr>
115     <td><code>log2()</code></td>
116     <td>Calculates the logarithm to base 2 of given number.</td>
117     </tr>
118     <tr>
119 schoenebeck 3679 <td><code>lsb()</code></td>
120     <td>Returns least significant byte of a 14 bit value.</td>
121     </tr>
122     <tr>
123 schoenebeck 3580 <td><code>max()</code></td>
124     <td>Calculates the maximum value of two given values.</td>
125     </tr>
126     <tr>
127 schoenebeck 2742 <td><code lang="nksp">message()</code></td>
128 schoenebeck 2732 <td>Prints text to the sampler's terminal.</td>
129     </tr>
130     <tr>
131 schoenebeck 3580 <td><code>min()</code></td>
132     <td>Calculates the minimum value of two given values.</td>
133 schoenebeck 3223 </tr>
134     <tr>
135 schoenebeck 3679 <td><code>msb()</code></td>
136     <td>Returns most significant byte of a 14-bit value.</td>
137     </tr>
138     <tr>
139 schoenebeck 3580 <td><code>num_elements()</code></td>
140     <td>Returns the size of the requested array variable.</td>
141 schoenebeck 3223 </tr>
142     <tr>
143 schoenebeck 3601 <td><code>pow()</code></td>
144     <td>Calculates given base raised by given power.</td>
145     </tr>
146     <tr>
147 schoenebeck 3580 <td><code>random()</code></td>
148     <td>Random number generator.</td>
149 schoenebeck 2732 </tr>
150     <tr>
151 schoenebeck 3601 <td><code>real()</code></td>
152     <td>Short-hand alias function for function <code>int_to_real()</code>.</td>
153     </tr>
154     <tr>
155     <td><code>real_to_int()</code></td>
156     <td>Type cast from real number to integer number.</td>
157     </tr>
158     <tr>
159     <td><code>round()</code></td>
160     <td>Rounds the given real number.</td>
161     </tr>
162     <tr>
163 schoenebeck 3580 <td><code>search()</code></td>
164     <td>Search for a certain value within an array.</td>
165 schoenebeck 2732 </tr>
166     <tr>
167 schoenebeck 3580 <td><code>sh_left()</code></td>
168     <td>Calculates a left bit shifted value.</td>
169 schoenebeck 2949 </tr>
170     <tr>
171 schoenebeck 3580 <td><code>sh_right()</code></td>
172     <td>Calculates a right bit shifted value.</td>
173 schoenebeck 2732 </tr>
174     <tr>
175 schoenebeck 3601 <td><code>sin()</code></td>
176     <td>Sine function.</td>
177     </tr>
178     <tr>
179 schoenebeck 3580 <td><code>sort()</code></td>
180     <td>Sort the given array.</td>
181 schoenebeck 2732 </tr>
182     <tr>
183 schoenebeck 3601 <td><code>sqrt()</code></td>
184     <td>Calculates the square root of given number.</td>
185     </tr>
186     <tr>
187 schoenebeck 3580 <td><code>stop_wait()</code></td>
188     <td>Resumes execution of a suspended script callback.</td>
189 schoenebeck 2971 </tr>
190     <tr>
191 schoenebeck 3601 <td><code>tan()</code></td>
192     <td>Tangens function.</td>
193     </tr>
194     <tr>
195 schoenebeck 3580 <td><code>wait()</code></td>
196     <td>Pauses execution for a certain amount of time.</td>
197 schoenebeck 2971 </tr>
198 schoenebeck 2732 </table>
199 schoenebeck 3580
200 schoenebeck 2732 <h3>Common Sampler Functions</h3>
201     <p>
202     Basic sampler related functions, independent from a particular sampler
203     format or sampler engine.
204     </p>
205     <table>
206     <tr>
207     <th>Function</th> <th>Description</th>
208     </tr>
209     <tr>
210 schoenebeck 3580 <td><code>by_marks()</code></td>
211     <td>Returns all events of an event group.</td>
212 schoenebeck 2732 </tr>
213     <tr>
214 schoenebeck 3580 <td><code>change_amp_lfo_depth()</code></td>
215     <td>Modifies the amplitude LFO depth.</td>
216 schoenebeck 3215 </tr>
217     <tr>
218 schoenebeck 3580 <td><code>change_amp_lfo_freq()</code></td>
219     <td>Modifies the amplitude LFO frequency.</td>
220 schoenebeck 2932 </tr>
221     <tr>
222 schoenebeck 3580 <td><code>change_attack()</code></td>
223     <td>Modifies the amplitude attack time of voices.</td>
224 schoenebeck 3336 </tr>
225     <tr>
226 schoenebeck 3580 <td><code>change_cutoff()</code></td>
227     <td>Changes filter cutoff frequency of voices.</td>
228 schoenebeck 3336 </tr>
229     <tr>
230 schoenebeck 3580 <td><code>change_cutoff_attack()</code></td>
231     <td>Modifies the filter cutoff attack time of voices.</td>
232 schoenebeck 3256 </tr>
233     <tr>
234 schoenebeck 3580 <td><code>change_cutoff_decay()</code></td>
235     <td>Modifies the filter cutoff decay time of voices.</td>
236 schoenebeck 2932 </tr>
237     <tr>
238 schoenebeck 3580 <td><code>change_cutoff_lfo_depth()</code></td>
239     <td>Modifies the filter cutoff LFO depth.</td>
240 schoenebeck 3189 </tr>
241     <tr>
242 schoenebeck 3580 <td><code>change_cutoff_lfo_freq()</code></td>
243     <td>Modifies the filter cutoff LFO frequency.</td>
244 schoenebeck 3247 </tr>
245     <tr>
246 schoenebeck 3580 <td><code>change_cutoff_release()</code></td>
247     <td>Modifies the filter cutoff release time of voices.</td>
248 schoenebeck 2932 </tr>
249     <tr>
250 schoenebeck 3580 <td><code>change_cutoff_sustain()</code></td>
251     <td>Modifies the filter cutoff sustain level of voices.</td>
252 schoenebeck 3189 </tr>
253     <tr>
254 schoenebeck 3580 <td><code>change_decay()</code></td>
255     <td>Modifies the amplitude decay time of voices.</td>
256 schoenebeck 3247 </tr>
257     <tr>
258 schoenebeck 3580 <td><code>change_note()</code></td>
259     <td>Change MIDI note number of note.</td>
260 schoenebeck 2936 </tr>
261     <tr>
262 schoenebeck 3580 <td><code>change_pan()</code></td>
263     <td>Changes panning of voices (stereo balance).</td>
264 schoenebeck 2936 </tr>
265     <tr>
266 schoenebeck 3580 <td><code>change_pan_curve()</code></td>
267     <td>Changes the curve type of panning (stereo balance) changes.</td>
268 schoenebeck 2954 </tr>
269     <tr>
270 schoenebeck 3580 <td><code>change_pan_time()</code></td>
271     <td>Changes the duration of panning (stereo balance) changes.</td>
272 schoenebeck 2954 </tr>
273     <tr>
274 schoenebeck 3580 <td><code>change_pitch_lfo_depth()</code></td>
275     <td>Modifies the pitch LFO depth.</td>
276 schoenebeck 3318 </tr>
277     <tr>
278 schoenebeck 3580 <td><code>change_pitch_lfo_freq()</code></td>
279     <td>Modifies the pitch LFO frequency.</td>
280     </tr>
281     <tr>
282     <td><code>change_play_pos()</code></td>
283     <td>Change the sample playback position.</td>
284     </tr>
285     <tr>
286 schoenebeck 2954 <td><code>change_release()</code></td>
287 schoenebeck 3362 <td>Modifies the amplitude release time of voices.</td>
288 schoenebeck 2954 </tr>
289     <tr>
290 schoenebeck 3580 <td><code>change_reso()</code></td>
291     <td>Changes filter resonance of voices.</td>
292 schoenebeck 3362 </tr>
293     <tr>
294 schoenebeck 3580 <td><code>change_sustain()</code></td>
295     <td>Modifies the amplitude sustain level of voices.</td>
296 schoenebeck 3362 </tr>
297     <tr>
298 schoenebeck 3580 <td><code>change_tune()</code></td>
299     <td>Changes the tuning of voices.</td>
300 schoenebeck 3362 </tr>
301     <tr>
302 schoenebeck 3580 <td><code>change_tune_curve()</code></td>
303     <td>Changes the curve type of tuning changes.</td>
304 schoenebeck 3362 </tr>
305     <tr>
306 schoenebeck 3580 <td><code>change_tune_time()</code></td>
307     <td>Changes the duration of tuning changes.</td>
308 schoenebeck 3121 </tr>
309     <tr>
310 schoenebeck 3580 <td><code>change_velo()</code></td>
311     <td>Change MIDI velocity of note.</td>
312 schoenebeck 3121 </tr>
313     <tr>
314 schoenebeck 3580 <td><code>change_vol()</code></td>
315     <td>Changes the volume of voices.</td>
316 schoenebeck 3362 </tr>
317     <tr>
318 schoenebeck 3580 <td><code>change_vol_curve()</code></td>
319     <td>Changes the curve type of volume changes.</td>
320 schoenebeck 3362 </tr>
321     <tr>
322 schoenebeck 3580 <td><code>change_vol_time()</code></td>
323     <td>Changes the duration of volume changes.</td>
324 schoenebeck 3121 </tr>
325     <tr>
326 schoenebeck 3580 <td><code>delete_event_mark()</code></td>
327     <td>Removes an event from some event group.</td>
328 schoenebeck 3121 </tr>
329     <tr>
330 schoenebeck 2936 <td><code>event_status()</code></td>
331     <td>Checks and returns whether a particular note is still alive.</td>
332     </tr>
333     <tr>
334 schoenebeck 3189 <td><code>fade_in()</code></td>
335     <td>Fade the requested note in.</td>
336     </tr>
337     <tr>
338     <td><code>fade_out()</code></td>
339     <td>Fade the requested note out.</td>
340     </tr>
341     <tr>
342 schoenebeck 3194 <td><code>get_event_par()</code></td>
343     <td>Get the current value of a specific note parameter.</td>
344     </tr>
345     <tr>
346 schoenebeck 3580 <td><code>ignore_controller()</code></td>
347     <td>Drops the given MIDI control change event.</td>
348 schoenebeck 3194 </tr>
349     <tr>
350 schoenebeck 2732 <td><code>ignore_event()</code></td>
351     <td>Drops the given event.</td>
352     </tr>
353     <tr>
354     <td><code>note_off()</code></td>
355     <td>Releases the requested note.</td>
356     </tr>
357     <tr>
358 schoenebeck 3580 <td><code>play_note()</code></td>
359     <td>Triggers a new note.</td>
360     </tr>
361     <tr>
362     <td><code>set_controller()</code></td>
363     <td>Creates a MIDI control change event.</td>
364     </tr>
365     <tr>
366 schoenebeck 2732 <td><code>set_event_mark()</code></td>
367     <td>Adds an event to an event group.</td>
368     </tr>
369     <tr>
370 schoenebeck 3580 <td><code>set_event_par()</code></td>
371     <td>Change the value of a specific note parameter.</td>
372 schoenebeck 2732 </tr>
373 schoenebeck 3692 <tr>
374     <td><code>set_nrpn()</code></td>
375     <td>Creates a MIDI NRPN event.</td>
376     </tr>
377     <tr>
378     <td><code>set_rpn()</code></td>
379     <td>Creates a MIDI RPN event.</td>
380     </tr>
381 schoenebeck 2732 </table>
382 schoenebeck 3580
383 schoenebeck 2732 <h3>GigaStudio Format Functions</h3>
384     <p>
385     Sampler format specific functions, dedicated to the individual features
386     of the GigaStudio format engine.
387     </p>
388     <table>
389     <tr>
390     <th>Function</th> <th>Description</th>
391     </tr>
392     <tr>
393     <td><code>gig_set_dim_zone()</code></td>
394     <td>Changes the currently active dimension zone.</td>
395     </tr>
396 schoenebeck 3229 <tr>
397     <td><code>same_region()</code></td>
398     <td>Check whether two keys are mapped to the same region.</td>
399     </tr>
400 schoenebeck 2732 </table>
401    
402 schoenebeck 3887 <h2 id="variables">Built-In Variables</h2>
403 schoenebeck 2732 <p>
404     These are the built-in variables and built-in constants available with the
405     NKSP realt-time instrument script language.
406     </p>
407 schoenebeck 2944
408     <h3>Core Language Variables</h3>
409     <p>
410     Most fundamental NKSP built-in variables, independent from any purpose of
411     being used in a sampler.
412     </p>
413     <table>
414     <tr>
415     <th>Variable</th> <th>Description</th>
416     </tr>
417     <tr>
418 schoenebeck 3297 <td><code>$CALLBACK_STATUS_QUEUE</code></td>
419     <td>Built-in constant reflecting the status of a callback to be
420     alive but suspended. See <code>callback_status()</code> for details.</td>
421     </tr>
422     <tr>
423     <td><code>$CALLBACK_STATUS_RUNNING</code></td>
424     <td>Built-in constant reflecting the status of a callback to be
425     alive and currently executing. See <code>callback_status()</code>
426     for details.</td>
427     </tr>
428     <tr>
429     <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
430     <td>Built-in constant reflecting the status of a callback to be
431     not alive. See <code>callback_status()</code> for details.</td>
432     </tr>
433     <tr>
434 schoenebeck 2944 <td><code>$KSP_TIMER</code></td>
435     <td>Preserved for compatiblity reasons with KSP, returns the same value
436     as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
437     Note that KSP's <code>reset_ksp_timer()</code> function is not available with
438     NKSP. However when calculating time differences between two time
439     stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
440     function is not required, because the underlying clock does not stop
441     when it reached its value limit (which happens every 71 minutes), instead the clock
442     will automatically restart from zero and the calculated time difference
443     even between such transitions will reflect correct durations.</td>
444     </tr>
445     <tr>
446     <td><code>$NKSP_PERF_TIMER</code></td>
447     <td>Returns the current performance time stamp (in microseconds) of the
448     script running. You may read this variable from time to time to take
449     time stamps which can be used to calculate the time difference
450     (in microseconds) which elapsed between them. A performance time
451     stamp is based on the script's actual CPU execution time. So the
452     internal clock which is used for generating such time stamps is only
453     running forward if the respective script is actually executed by the
454     CPU. Whenever your script is not really executed by the CPU (i.e. because
455     your script got suspended by a wait() call or got forcely suspended due to
456     real-time constraints, or when the entire sampler application got suspended
457     by the OS for other applications or OS tasks) then the underlying internal
458     clock is paused as well.
459     <note class="important">
460     You should only use this built-in variable for script development
461     purposes (i.e. for bench marking the performance of your script).
462     You should <b>not</b> use it with your final production sounds!
463     It is not appropriate for being used in a musical context, because
464     when an offline bounce is performed for instance, the musical timing
465     will be completely unrelated to the CPU execution time. Plus using
466     this variable may cause audio drop outs on some systems. In a musical
467     context you should use <code>$ENGINE_UPTIME</code> instead, which is
468     also safe for offline bounces.
469     </note>
470     <note>
471     On some systems <code>$NKSP_REAL_TIMER</code> and
472     <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
473     difference between them is not implemented for all systems at the moment.
474     </note>
475     </td>
476     </tr>
477     <tr>
478 schoenebeck 3294 <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
479     <td>
480     Reflects the callback IDs of all child threads which the current
481 schoenebeck 3295 script callback instance spawned by having called <code>fork()</code> before.
482 schoenebeck 3294 See the latter function for details about this array variable.
483     </td>
484     </tr>
485     <tr>
486     <td><code>$NKSP_CALLBACK_PARENT_ID</code></td>
487     <td>
488     If the current execution thread is a child thread spawned by a <code>fork()</code>
489     call before, then this variable reflects the callback ID of the parent
490 schoenebeck 3295 thread which created this child thread. Otherwise this variable is <code>0</code>.
491     See <code>fork()</code> for more details about this variable.
492 schoenebeck 3294 </td>
493     </tr>
494     <tr>
495 schoenebeck 2944 <td><code>$NKSP_REAL_TIMER</code></td>
496     <td>Returns the current time stamp in reality (in microseconds). You may
497     read this variable from time to time to take
498     time stamps which can be used to calculate the time difference
499     (in microseconds) which elapsed between them. A "real" time
500     stamp is based on an internal clock which constantly proceeds, so this
501     internal clock also continues counting while your script is either suspended
502     (i.e. because your script got suspended by a wait() call or got forcely
503     suspended due to real-time constraints) and it also continues counting
504     even if the entire sampler application got suspended by the OS (i.e. to
505     execute other applications for multi-tasking or to perform OS tasks).
506     <note class="important">
507     You should only use this built-in variable for script development
508     purposes (i.e. for bench marking the performance of your script).
509     You should <b>not</b> use it with your final production sounds!
510     It is not appropriate for being used in a musical context, because
511     when an offline bounce is performed for instance, the musical timing
512     will be completely unrelated to the CPU execution time. Plus using
513     this variable may cause audio drop outs on some systems. In a musical
514     context you should use <code>$ENGINE_UPTIME</code> instead, which is
515     also safe for offline bounces.
516     </note>
517     <note>
518     On some systems <code>$NKSP_REAL_TIMER</code> and
519     <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
520     difference between them is not implemented for all systems at the moment.
521     </note>
522     </td>
523     </tr>
524 schoenebeck 2949 <tr>
525     <td><code>$NI_CALLBACK_ID</code></td>
526     <td>Reflects the current event handler instance's unique callback ID.
527     For the same event type there may be more than
528     one event handler instances running. Each one of them has
529     its own callback ID. You can get the current event handler
530     instance's callback ID by reading this built-in variable.</td>
531     </tr>
532     <tr>
533     <td><code>$NI_CALLBACK_TYPE</code></td>
534     <td>Reflects the event type of the current event handler. This variable
535     may reflect one of the following built-in constants:
536     <code>$NI_CB_TYPE_INIT</code>, <code>$NI_CB_TYPE_NOTE</code>,
537     <code>$NI_CB_TYPE_RELEASE</code>, <code>$NI_CB_TYPE_CONTROLLER</code>.</td>
538     </tr>
539     <tr>
540     <td><code>$NI_CB_TYPE_INIT</code></td>
541     <td>Built-in constant reflecting an <code>init</code> event handler type.</td>
542     </tr>
543     <tr>
544     <td><code>$NI_CB_TYPE_NOTE</code></td>
545     <td>Built-in constant reflecting a <code>note</code> event handler type.</td>
546     </tr>
547     <tr>
548     <td><code>$NI_CB_TYPE_RELEASE</code></td>
549     <td>Built-in constant reflecting a <code>release</code> event handler type.</td>
550     </tr>
551     <tr>
552     <td><code>$NI_CB_TYPE_CONTROLLER</code></td>
553     <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>
554     </tr>
555     <tr>
556 schoenebeck 3692 <td><code>$NI_CB_TYPE_RPN</code></td>
557     <td>Built-in constant reflecting a <code>rpn</code> event handler type.</td>
558     </tr>
559     <tr>
560     <td><code>$NI_CB_TYPE_NRPN</code></td>
561     <td>Built-in constant reflecting a <code>nrpn</code> event handler type.</td>
562     </tr>
563     <tr>
564 schoenebeck 3601 <td><code>$NI_MATH_E</code></td>
565     <td>Base of the natural logarithm (approximately being <code>2.71828</code>)</td>
566     </tr>
567     <tr>
568     <td><code>$NI_MATH_PI</code></td>
569 schoenebeck 3604 <td>Natural constant reflecting the ratio of a circle's circumference to its diameter (approximately being <code>3.14159</code>).</td>
570 schoenebeck 3601 </tr>
571     <tr>
572 schoenebeck 2949 <td><code>$NKSP_IGNORE_WAIT</code></td>
573     <td>If this boolean built-in variable is <code>1</code> then all calls of your
574     event handler instance to function <code>wait()</code> will be ignored.
575     This may for example be the case if another event handler instance
576     resumed your paused script by calling <code>stop_wait()</code> and
577     passing <code>1</code> to the 2nd argument of that function.</td>
578     </tr>
579 schoenebeck 2944 </table>
580    
581 schoenebeck 2732 <h3>Common Sampler Variables</h3>
582     <p>
583     Basic sampler related built-in variables and constants, independent from a
584     particular sampler format or sampler engine.
585     </p>
586     <table>
587     <tr>
588     <th>Variable</th> <th>Description</th>
589     </tr>
590     <tr>
591 schoenebeck 3074 <td><code>%ALL_EVENTS</code></td>
592     <td>
593     Note IDs of all currently active notes of the current sampler part (a.k.a. sampler channel).
594     This may be passed to many built-in functions like <code>note_off()</code>.
595 schoenebeck 3077 This array variable only contains IDs of notes which were launched due
596     to MIDI note-on events. This variable does not contain IDs of child notes
597 schoenebeck 3079 (i.e. notes which were launched programmatically by calling <code>play_note()</code>).
598 schoenebeck 3074 <note>
599     In contrast to KSP this variable is an integer array type, whereas KSP's
600     pendent of this built-in variable is an integer constant (scalar) called
601 schoenebeck 3075 <code>$ALL_EVENTS</code>. Using the latter with NKSP will cause a
602 schoenebeck 3074 parser warning, the behavior will be the same though.
603     </note>
604     </td>
605     </tr>
606     <tr>
607 schoenebeck 2732 <td><code>$CC_NUM</code></td>
608     <td>MIDI controller number that caused the <code>controller</code>
609     handler to be executed (only useful in the context of a
610     <code>controller</code> handler).</td>
611     </tr>
612     <tr>
613     <td><code>%CC[]</code></td>
614     <td>Provides access to all current MIDI controller values. This can be
615     used in any context. Use the respective MIDI controller number as
616     index to this integer array variable. For instance <code>%CC[1]</code>
617     would give you the current value of the modulation wheel.
618     </td>
619     </tr>
620     <tr>
621     <td><code>$EVENT_ID</code></td>
622     <td>ID of the event that caused the current event handler to be executed. In
623     the context of a <code>note</code> handler this would be the event
624     ID of the note, within a <code>controller</code> handler it would
625     be the controller event ID, etc.</td>
626     </tr>
627     <tr>
628     <td><code>$EVENT_NOTE</code></td>
629     <td>MIDI note number that caused a note related
630     handler to be executed (only useful in the context of a
631     <code>note</code> or <code>release</code> handler).</td>
632     </tr>
633     <tr>
634     <td><code>$EVENT_VELOCITY</code></td>
635     <td>MIDI velocity value of the note that caused that note related
636     handler to be executed (only useful in the context of a
637     <code>note</code> or <code>release</code> handler).</td>
638     </tr>
639     <tr>
640 schoenebeck 2937 <td><code>$EVENT_STATUS_INACTIVE</code></td>
641     <td>Constant bit flag used as possible return value by
642     <code>event_status()</code> in case the requested
643     note is not "alive".</td>
644     </tr>
645     <tr>
646     <td><code>$EVENT_STATUS_NOTE_QUEUE</code></td>
647     <td>Constant bit flag used as possible return value by
648     <code>event_status()</code> in case the requested
649     note is still "alive".</td>
650     </tr>
651     <tr>
652 schoenebeck 3194 <td><code>$EVENT_PAR_NOTE</code></td>
653     <td>Constant value symbolizing the "note number" parameter. See
654     <code>get_event_par()</code> and <code>set_event_par()</code>
655     for details.</td>
656     </tr>
657     <tr>
658     <td><code>$EVENT_PAR_TUNE</code></td>
659     <td>Constant value symbolizing the "tune" parameter. See
660     <code>get_event_par()</code> and <code>set_event_par()</code>
661     for details.</td>
662     </tr>
663     <tr>
664     <td><code>$EVENT_PAR_VELOCITY</code></td>
665     <td>Constant value symbolizing the "note velocity" parameter. See
666     <code>get_event_par()</code> and <code>set_event_par()</code>
667     for details.</td>
668     </tr>
669     <tr>
670     <td><code>$EVENT_PAR_VOLUME</code></td>
671     <td>Constant value symbolizing the "volume" parameter. See
672     <code>get_event_par()</code> and <code>set_event_par()</code>
673     for details.</td>
674     </tr>
675     <tr>
676     <td><code>$EVENT_PAR_0</code> to <code>$EVENT_PAR_3</code></td>
677     <td>Four constant values symbolizing the 4 possible user specific
678     parameters, which i.e. might be used to pass data from one script
679     (slot) to another script (slot). See <code>get_event_par()</code>
680     and <code>set_event_par()</code> for details.</td>
681     </tr>
682     <tr>
683 schoenebeck 2732 <td><code>%KEY_DOWN[]</code></td>
684     <td>This can be used in any context to check whether a certain MIDI
685     key is currently pressed down. Use the respective MIDI note number
686 schoenebeck 2936 as index to this array variable (see also <code>event_status()</code>).</td>
687 schoenebeck 2732 </tr>
688     <tr>
689 schoenebeck 3248 <td><code>$NKSP_EASE_IN_EASE_OUT</code></td>
690     <td>Used to select a fade curve with "ease in and ease out" shape.</td>
691     </tr>
692     <tr>
693     <td><code>$NKSP_LINEAR</code></td>
694     <td>Used to select a fade curve with linear shape.</td>
695     </tr>
696     <tr>
697 schoenebeck 3692 <td><code>$RPN_ADDRESS</code></td>
698     <td>Used to get the RPN / NRPN parameter number that had been changed in a
699     <code>rpn</code> or <code>nrpn</code> event handler.</td>
700     </tr>
701     <tr>
702     <td><code>$RPN_VALUE</code></td>
703     <td>Used to get the new RPN / NRPN value in a
704     <code>rpn</code> or <code>nrpn</code> event handler.</td>
705     </tr>
706     <tr>
707 schoenebeck 2732 <td><code>$VCC_MONO_AT</code></td>
708     <td>Constant identifying the MIDI monophonic aftertouch controller (also
709     called <i title="Amount of force on held-down key.">
710     MIDI channel pressure
711     </i>). This is somewhat different than in the MIDI standard. With
712     NKSP aftertouch is handled like an additional "regular" MIDI CC controller.
713     Therefore use
714     <code>%CC[$VCC_MONO_AT]</code> to obtain the current aftertouch value
715     in the context of a <code>controller</code> event handler.
716     </td>
717     </tr>
718     <tr>
719     <td><code>$VCC_PITCH_BEND</code></td>
720     <td>Constant identifying the pitch bend wheel controller.
721     This is somewhat different than in the MIDI standard. With
722     NKSP pitch bend is handled like an additional "regular" MIDI CC controller.
723     Therefore use
724 schoenebeck 2936 <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current pitch bend wheel value
725 schoenebeck 2732 in the context of a <code>controller</code> event handler.</td>
726     </tr>
727     <tr>
728     <td><code>$MARK_1</code> to <code>$MARK_28</code></td>
729     <td>Used to select one of the available 28 event groups.
730     See <code>set_event_mark()</code> for details.</td>
731     </tr>
732 schoenebeck 2944 <tr>
733     <td><code>$ENGINE_UPTIME</code></td>
734     <td>Returns the current time stamp (in milliseconds) for being
735     used in a musical context. You may read this variable from time to time
736     to take time stamps which can be used to calculate the time difference
737     (in milliseconds) which elapsed between them. These timing values are
738     based on the internal sample rate and thus it can safely be used to
739     perform musical timing related tasks in your scripts. Especially
740     your script will also continue to behave correctly when an offline bounce
741     of a song is performed.
742     </td>
743     </tr>
744 schoenebeck 2732 </table>
745    
746     <h3>GigaStudio Format Variables</h3>
747     <p>
748     Sampler format specific built-in variables and constants, dedicated to the
749     individual features of the GigaStudio format engine.
750     </p>
751     <table>
752     <tr>
753     <th>Variable</th> <th>Description</th>
754     </tr>
755     <tr>
756     <td><code>$GIG_DIM_CHANNEL</code></td>
757     <td>Constant that identifies the <i>stereo dimension</i>.</td>
758     </tr>
759     <tr>
760     <td><code>$GIG_DIM_LAYER</code></td>
761     <td>Constant that identifies the <i>layer dimension</i>.</td>
762     </tr>
763     <tr>
764     <td><code>$GIG_DIM_VELOCITY</code></td>
765     <td>Constant that identifies the <i>velocity dimension</i>.</td>
766     </tr>
767     <tr>
768     <td><code>$GIG_DIM_AFTERTOUCH</code></td>
769     <td>Constant that identifies the <i>aftertouch dimension</i>.</td>
770     </tr>
771     <tr>
772     <td><code>$GIG_DIM_RELEASE</code></td>
773     <td>Constant that identifies the <i>release trigger dimension</i>.</td>
774     </tr>
775     <tr>
776     <td><code>$GIG_DIM_KEYBOARD</code></td>
777     <td>Constant that identifies the <i>keyboard position dimension</i>.</td>
778     </tr>
779     <tr>
780 schoenebeck 3229 <td><code>$GIG_DIM_ROUNDROBIN</code></td>
781 schoenebeck 2732 <td>Constant that identifies the <i>round robin dimension</i>.</td>
782     </tr>
783     <tr>
784     <td><code>$GIG_DIM_RANDOM</code></td>
785     <td>Constant that identifies the <i>random dimension</i>.</td>
786     </tr>
787     <tr>
788     <td><code>$GIG_DIM_SMARTMIDI</code></td>
789     <td>Constant that identifies the <i>start MIDI dimension</i> (a.k.a iMIDI rules).</td>
790     </tr>
791     <tr>
792     <td><code>$GIG_DIM_ROUNDROBINKEY</code></td>
793     <td>Constant that identifies the <i>round robin key dimension</i>.</td>
794     </tr>
795     <tr>
796     <td><code>$GIG_DIM_MODWHEEL</code></td>
797     <td>Constant that identifies the <i>modulation wheel dimension</i>.</td>
798     </tr>
799     <tr>
800     <td><code>$GIG_DIM_SUSTAIN</code></td>
801     <td>Constant that identifies the <i>sustain pedal dimension</i> (a.k.a. hold pedal).</td>
802     </tr>
803     <tr>
804     <td><code>$GIG_DIM_PORTAMENTO</code></td>
805     <td>Constant that identifies the <i>portamento MIDI controller dimension</i>.</td>
806     </tr>
807     <tr>
808     <td><code>$GIG_DIM_SOSTENUTO</code></td>
809     <td>Constant that identifies the <i>sostenuto MIDI controller dimension</i>.</td>
810     </tr>
811     <tr>
812     <td><code>$GIG_DIM_SOFT</code></td>
813     <td>Constant that identifies the <i>soft pedal dimension</i>.</td>
814     </tr>
815     <tr>
816     <td><code>$GIG_DIM_BREATH</code></td>
817     <td>Constant that identifies the <i>breath controller dimension</i>.</td>
818     </tr>
819     <tr>
820     <td><code>$GIG_DIM_FOOT</code></td>
821     <td>Constant that identifies the <i>foot pedal dimension</i>.</td>
822     </tr>
823     <tr>
824     <td><code>$GIG_DIM_PORTAMENTOTIME</code></td>
825     <td>Constant that identifies the <i>portamento time controller dimension</i>.</td>
826     </tr>
827     <tr>
828     <td><code>$GIG_DIM_EFFECT1</code></td>
829     <td>Constant that identifies the <i>effect 1 MIDI controller dimension</i>.</td>
830     </tr>
831     <tr>
832     <td><code>$GIG_DIM_EFFECT2</code></td>
833     <td>Constant that identifies the <i>effect 2 MIDI controller dimension</i>.</td>
834     </tr>
835     <tr>
836     <td><code>$GIG_DIM_EFFECT1DEPTH</code></td>
837     <td>Constant that identifies the <i>effect 1 depth MIDI controller dimension</i>.</td>
838     </tr>
839     <tr>
840     <td><code>$GIG_DIM_EFFECT2DEPTH</code></td>
841     <td>Constant that identifies the <i>effect 2 depth MIDI controller dimension</i>.</td>
842     </tr>
843     <tr>
844     <td><code>$GIG_DIM_EFFECT3DEPTH</code></td>
845     <td>Constant that identifies the <i>effect 3 depth MIDI controller dimension</i>.</td>
846     </tr>
847     <tr>
848     <td><code>$GIG_DIM_EFFECT4DEPTH</code></td>
849     <td>Constant that identifies the <i>effect 4 depth MIDI controller dimension</i>.</td>
850     </tr>
851     <tr>
852     <td><code>$GIG_DIM_EFFECT5DEPTH</code></td>
853     <td>Constant that identifies the <i>effect 5 depth MIDI controller dimension</i>.</td>
854     </tr>
855     <tr>
856     <td><code>$GIG_DIM_GENPURPOSE1</code></td>
857     <td>Constant that identifies the <i>general purpose 1 MIDI controller dimension</i>.</td>
858     </tr>
859     <tr>
860     <td><code>$GIG_DIM_GENPURPOSE2</code></td>
861     <td>Constant that identifies the <i>general purpose 2 MIDI controller dimension</i>.</td>
862     </tr>
863     <tr>
864     <td><code>$GIG_DIM_GENPURPOSE3</code></td>
865     <td>Constant that identifies the <i>general purpose 3 MIDI controller dimension</i>.</td>
866     </tr>
867     <tr>
868     <td><code>$GIG_DIM_GENPURPOSE4</code></td>
869     <td>Constant that identifies the <i>general purpose 4 MIDI controller dimension</i>.</td>
870     </tr>
871     <tr>
872     <td><code>$GIG_DIM_GENPURPOSE5</code></td>
873     <td>Constant that identifies the <i>general purpose 5 MIDI controller dimension</i>.</td>
874     </tr>
875     <tr>
876     <td><code>$GIG_DIM_GENPURPOSE6</code></td>
877     <td>Constant that identifies the <i>general purpose 6 MIDI controller dimension</i>.</td>
878     </tr>
879     <tr>
880     <td><code>$GIG_DIM_GENPURPOSE7</code></td>
881     <td>Constant that identifies the <i>general purpose 7 MIDI controller dimension</i>.</td>
882     </tr>
883     <tr>
884     <td><code>$GIG_DIM_GENPURPOSE8</code></td>
885     <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>
886     </tr>
887     </table>
888 schoenebeck 3312
889     <h2>Built-In Preprocessor Conditions</h2>
890     <p>
891     These are the built-in preprocessor conditions available with the NKSP realt-time
892     instrument script language.
893     </p>
894 schoenebeck 2732
895 schoenebeck 3312 <h3>Core Language Preprocessor Conditions</h3>
896     <p>
897     Most fundamental NKSP built-in preprocessor conditions, independent from
898     any purpose of being used in a sampler.
899     </p>
900     <table>
901     <tr>
902     <th>Condition</th> <th>Description</th>
903     </tr>
904     <tr>
905     <td><code>NKSP_NO_MESSAGE</code></td>
906     <td>
907     By default this condition is not set. By explicitly enabling this
908     condition with <code>SET_CONDITION(NKSP_NO_MESSAGE)</code> it
909     causes all subsequent <code>message()</code> calls to be ignored
910     and filtered out on preprocessor level. See function <code>message()</code>
911     for details.
912     </td>
913     </tr>
914     </table>
915    
916 schoenebeck 2732 </body>
917     </html>

  ViewVC Help
Powered by ViewVC