/[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 3396 - (hide annotations) (download) (as text)
Wed Dec 6 18:53:32 2017 UTC (6 years, 3 months ago) by schoenebeck
File MIME type: text/html
File size: 31868 byte(s)
- NKSP reference: Just added link to NKSP language tour.

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     </head>
9     <body>
10     <h1>NKSP Reference</h1>
11     <p>
12     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.
14 schoenebeck 3396 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 schoenebeck 2732 </p>
17    
18     <h2>Built-In Functions</h2>
19     <p>
20 schoenebeck 3265 These are the built-in functions available with the NKSP real-time
21 schoenebeck 2732 instrument script language.
22     </p>
23    
24     <h3>Core Language Functions</h3>
25     <p>
26     Most fundamental NKSP functions, independent from any purpose of being used in a sampler.
27     </p>
28     <table>
29     <tr>
30     <th>Function</th> <th>Description</th>
31     </tr>
32     <tr>
33 schoenebeck 3278 <td><code lang="nksp">abort()</code></td>
34     <td>Stops execution of a script callback.</td>
35     </tr>
36     <tr>
37 schoenebeck 3223 <td><code lang="nksp">array_equal()</code></td>
38     <td>Check whether two arrays are equal.</td>
39     </tr>
40     <tr>
41 schoenebeck 3294 <td><code>fork()</code></td>
42 schoenebeck 3295 <td>Creates new execution instances (threads).</td>
43 schoenebeck 3294 </tr>
44     <tr>
45 schoenebeck 3297 <td><code>callback_status()</code></td>
46     <td>Returns the current status of a callback (thread).</td>
47     </tr>
48     <tr>
49 schoenebeck 2946 <td><code lang="nksp">dec()</code></td>
50     <td>Decrements the passed integer variable by one.</td>
51     </tr>
52     <tr>
53     <td><code>inc()</code></td>
54     <td>Increments the passed integer variable by one.</td>
55     </tr>
56     <tr>
57 schoenebeck 3077 <td><code>in_range()</code></td>
58     <td>Checks whether a value is between two other values.</td>
59     </tr>
60     <tr>
61 schoenebeck 2742 <td><code lang="nksp">message()</code></td>
62 schoenebeck 2732 <td>Prints text to the sampler's terminal.</td>
63     </tr>
64     <tr>
65 schoenebeck 3223 <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 schoenebeck 2732 <td><code>exit()</code></td>
74     <td>Stops execution of the current event handler instance.</td>
75     </tr>
76     <tr>
77     <td><code>wait()</code></td>
78     <td>Pauses execution for a certain amount of time.</td>
79     </tr>
80     <tr>
81 schoenebeck 2949 <td><code>stop_wait()</code></td>
82     <td>Resumes execution of a suspended script callback.</td>
83     </tr>
84     <tr>
85 schoenebeck 2732 <td><code>abs()</code></td>
86     <td>Calculates the absolute value of a given value.</td>
87     </tr>
88     <tr>
89     <td><code>random()</code></td>
90     <td>Random number generator.</td>
91     </tr>
92     <tr>
93 schoenebeck 2971 <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 schoenebeck 2732 <td><code>num_elements()</code></td>
102     <td>Returns the size of the requested array variable.</td>
103     </tr>
104 schoenebeck 2966 <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 schoenebeck 2732 </table>
113    
114     <h3>Common Sampler Functions</h3>
115     <p>
116     Basic sampler related functions, independent from a particular sampler
117     format or sampler engine.
118     </p>
119     <table>
120     <tr>
121     <th>Function</th> <th>Description</th>
122     </tr>
123     <tr>
124     <td><code>play_note()</code></td>
125     <td>Triggers a new note.</td>
126     </tr>
127     <tr>
128 schoenebeck 3215 <td><code>change_note()</code></td>
129     <td>Change MIDI note number of note.</td>
130     </tr>
131     <tr>
132 schoenebeck 2932 <td><code>change_pan()</code></td>
133     <td>Changes panning of voices (stereo balance).</td>
134     </tr>
135     <tr>
136 schoenebeck 3336 <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 schoenebeck 3256 <td><code>change_play_pos()</code></td>
145     <td>Change the sample playback position.</td>
146     </tr>
147     <tr>
148 schoenebeck 2932 <td><code>change_tune()</code></td>
149     <td>Changes the tuning of voices.</td>
150     </tr>
151     <tr>
152 schoenebeck 3189 <td><code>change_tune_time()</code></td>
153     <td>Changes the duration of tuning changes.</td>
154     </tr>
155     <tr>
156 schoenebeck 3247 <td><code>change_tune_curve()</code></td>
157     <td>Changes the curve type of tuning changes.</td>
158     </tr>
159     <tr>
160 schoenebeck 2932 <td><code>change_vol()</code></td>
161     <td>Changes the volume of voices.</td>
162     </tr>
163     <tr>
164 schoenebeck 3189 <td><code>change_vol_time()</code></td>
165     <td>Changes the duration of volume changes.</td>
166     </tr>
167     <tr>
168 schoenebeck 3247 <td><code>change_vol_curve()</code></td>
169     <td>Changes the curve type of volume changes.</td>
170     </tr>
171     <tr>
172 schoenebeck 2936 <td><code>change_cutoff()</code></td>
173     <td>Changes filter cutoff frequency of voices.</td>
174     </tr>
175     <tr>
176     <td><code>change_reso()</code></td>
177     <td>Changes filter resonance of voices.</td>
178     </tr>
179     <tr>
180 schoenebeck 2954 <td><code>change_attack()</code></td>
181 schoenebeck 3362 <td>Modifies the amplitude attack time of voices.</td>
182 schoenebeck 2954 </tr>
183     <tr>
184     <td><code>change_decay()</code></td>
185 schoenebeck 3362 <td>Modifies the amplitude decay time of voices.</td>
186 schoenebeck 2954 </tr>
187     <tr>
188 schoenebeck 3318 <td><code>change_sustain()</code></td>
189 schoenebeck 3362 <td>Modifies the amplitude sustain level of voices.</td>
190 schoenebeck 3318 </tr>
191     <tr>
192 schoenebeck 2954 <td><code>change_release()</code></td>
193 schoenebeck 3362 <td>Modifies the amplitude release time of voices.</td>
194 schoenebeck 2954 </tr>
195 schoenebeck 3362
196 schoenebeck 2954 <tr>
197 schoenebeck 3362 <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 schoenebeck 3121 <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 schoenebeck 3362
222 schoenebeck 3121 <tr>
223 schoenebeck 3362 <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 schoenebeck 3121 <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 schoenebeck 3215 <td><code>change_velo()</code></td>
241     <td>Change MIDI velocity of note.</td>
242     </tr>
243     <tr>
244 schoenebeck 2936 <td><code>event_status()</code></td>
245     <td>Checks and returns whether a particular note is still alive.</td>
246     </tr>
247     <tr>
248 schoenebeck 3189 <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 schoenebeck 3194 <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 schoenebeck 2732 <td><code>set_controller()</code></td>
265     <td>Creates a MIDI control change event.</td>
266     </tr>
267     <tr>
268     <td><code>ignore_event()</code></td>
269     <td>Drops the given event.</td>
270     </tr>
271     <tr>
272     <td><code>ignore_controller()</code></td>
273     <td>Drops the given MIDI control change event.</td>
274     </tr>
275     <tr>
276     <td><code>note_off()</code></td>
277     <td>Releases the requested note.</td>
278     </tr>
279     <tr>
280     <td><code>set_event_mark()</code></td>
281     <td>Adds an event to an event group.</td>
282     </tr>
283     <tr>
284     <td><code>delete_event_mark()</code></td>
285     <td>Removes an event from some event group.</td>
286     </tr>
287     <tr>
288     <td><code>by_marks()</code></td>
289     <td>Returns all events of an event group.</td>
290     </tr>
291     </table>
292    
293     <h3>GigaStudio Format Functions</h3>
294     <p>
295     Sampler format specific functions, dedicated to the individual features
296     of the GigaStudio format engine.
297     </p>
298     <table>
299     <tr>
300     <th>Function</th> <th>Description</th>
301     </tr>
302     <tr>
303     <td><code>gig_set_dim_zone()</code></td>
304     <td>Changes the currently active dimension zone.</td>
305     </tr>
306 schoenebeck 3229 <tr>
307     <td><code>same_region()</code></td>
308     <td>Check whether two keys are mapped to the same region.</td>
309     </tr>
310 schoenebeck 2732 </table>
311    
312     <h2>Built-In Variables</h2>
313     <p>
314     These are the built-in variables and built-in constants available with the
315     NKSP realt-time instrument script language.
316     </p>
317 schoenebeck 2944
318     <h3>Core Language Variables</h3>
319     <p>
320     Most fundamental NKSP built-in variables, independent from any purpose of
321     being used in a sampler.
322     </p>
323     <table>
324     <tr>
325     <th>Variable</th> <th>Description</th>
326     </tr>
327     <tr>
328 schoenebeck 3297 <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 schoenebeck 2944 <td><code>$KSP_TIMER</code></td>
345     <td>Preserved for compatiblity reasons with KSP, returns the same value
346     as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
347     Note that KSP's <code>reset_ksp_timer()</code> function is not available with
348     NKSP. However when calculating time differences between two time
349     stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
350     function is not required, because the underlying clock does not stop
351     when it reached its value limit (which happens every 71 minutes), instead the clock
352     will automatically restart from zero and the calculated time difference
353     even between such transitions will reflect correct durations.</td>
354     </tr>
355     <tr>
356     <td><code>$NKSP_PERF_TIMER</code></td>
357     <td>Returns the current performance time stamp (in microseconds) of the
358     script running. You may read this variable from time to time to take
359     time stamps which can be used to calculate the time difference
360     (in microseconds) which elapsed between them. A performance time
361     stamp is based on the script's actual CPU execution time. So the
362     internal clock which is used for generating such time stamps is only
363     running forward if the respective script is actually executed by the
364     CPU. Whenever your script is not really executed by the CPU (i.e. because
365     your script got suspended by a wait() call or got forcely suspended due to
366     real-time constraints, or when the entire sampler application got suspended
367     by the OS for other applications or OS tasks) then the underlying internal
368     clock is paused as well.
369     <note class="important">
370     You should only use this built-in variable for script development
371     purposes (i.e. for bench marking the performance of your script).
372     You should <b>not</b> use it with your final production sounds!
373     It is not appropriate for being used in a musical context, because
374     when an offline bounce is performed for instance, the musical timing
375     will be completely unrelated to the CPU execution time. Plus using
376     this variable may cause audio drop outs on some systems. In a musical
377     context you should use <code>$ENGINE_UPTIME</code> instead, which is
378     also safe for offline bounces.
379     </note>
380     <note>
381     On some systems <code>$NKSP_REAL_TIMER</code> and
382     <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
383     difference between them is not implemented for all systems at the moment.
384     </note>
385     </td>
386     </tr>
387     <tr>
388 schoenebeck 3294 <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
389     <td>
390     Reflects the callback IDs of all child threads which the current
391 schoenebeck 3295 script callback instance spawned by having called <code>fork()</code> before.
392 schoenebeck 3294 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 schoenebeck 3295 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 schoenebeck 3294 </td>
403     </tr>
404     <tr>
405 schoenebeck 2944 <td><code>$NKSP_REAL_TIMER</code></td>
406     <td>Returns the current time stamp in reality (in microseconds). You may
407     read this variable from time to time to take
408     time stamps which can be used to calculate the time difference
409     (in microseconds) which elapsed between them. A "real" time
410     stamp is based on an internal clock which constantly proceeds, so this
411     internal clock also continues counting while your script is either suspended
412     (i.e. because your script got suspended by a wait() call or got forcely
413     suspended due to real-time constraints) and it also continues counting
414     even if the entire sampler application got suspended by the OS (i.e. to
415     execute other applications for multi-tasking or to perform OS tasks).
416     <note class="important">
417     You should only use this built-in variable for script development
418     purposes (i.e. for bench marking the performance of your script).
419     You should <b>not</b> use it with your final production sounds!
420     It is not appropriate for being used in a musical context, because
421     when an offline bounce is performed for instance, the musical timing
422     will be completely unrelated to the CPU execution time. Plus using
423     this variable may cause audio drop outs on some systems. In a musical
424     context you should use <code>$ENGINE_UPTIME</code> instead, which is
425     also safe for offline bounces.
426     </note>
427     <note>
428     On some systems <code>$NKSP_REAL_TIMER</code> and
429     <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
430     difference between them is not implemented for all systems at the moment.
431     </note>
432     </td>
433     </tr>
434 schoenebeck 2949 <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 schoenebeck 2944 </table>
474    
475 schoenebeck 2732 <h3>Common Sampler Variables</h3>
476     <p>
477     Basic sampler related built-in variables and constants, independent from a
478     particular sampler format or sampler engine.
479     </p>
480     <table>
481     <tr>
482     <th>Variable</th> <th>Description</th>
483     </tr>
484     <tr>
485 schoenebeck 3074 <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 schoenebeck 3077 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 schoenebeck 3079 (i.e. notes which were launched programmatically by calling <code>play_note()</code>).
492 schoenebeck 3074 <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 schoenebeck 3075 <code>$ALL_EVENTS</code>. Using the latter with NKSP will cause a
496 schoenebeck 3074 parser warning, the behavior will be the same though.
497     </note>
498     </td>
499     </tr>
500     <tr>
501 schoenebeck 2732 <td><code>$CC_NUM</code></td>
502     <td>MIDI controller number that caused the <code>controller</code>
503     handler to be executed (only useful in the context of a
504     <code>controller</code> handler).</td>
505     </tr>
506     <tr>
507     <td><code>%CC[]</code></td>
508     <td>Provides access to all current MIDI controller values. This can be
509     used in any context. Use the respective MIDI controller number as
510     index to this integer array variable. For instance <code>%CC[1]</code>
511     would give you the current value of the modulation wheel.
512     </td>
513     </tr>
514     <tr>
515     <td><code>$EVENT_ID</code></td>
516     <td>ID of the event that caused the current event handler to be executed. In
517     the context of a <code>note</code> handler this would be the event
518     ID of the note, within a <code>controller</code> handler it would
519     be the controller event ID, etc.</td>
520     </tr>
521     <tr>
522     <td><code>$EVENT_NOTE</code></td>
523     <td>MIDI note number that caused a note related
524     handler to be executed (only useful in the context of a
525     <code>note</code> or <code>release</code> handler).</td>
526     </tr>
527     <tr>
528     <td><code>$EVENT_VELOCITY</code></td>
529     <td>MIDI velocity value of the note that caused that note related
530     handler to be executed (only useful in the context of a
531     <code>note</code> or <code>release</code> handler).</td>
532     </tr>
533     <tr>
534 schoenebeck 2937 <td><code>$EVENT_STATUS_INACTIVE</code></td>
535     <td>Constant bit flag used as possible return value by
536     <code>event_status()</code> in case the requested
537     note is not "alive".</td>
538     </tr>
539     <tr>
540     <td><code>$EVENT_STATUS_NOTE_QUEUE</code></td>
541     <td>Constant bit flag used as possible return value by
542     <code>event_status()</code> in case the requested
543     note is still "alive".</td>
544     </tr>
545     <tr>
546 schoenebeck 3194 <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 schoenebeck 2732 <td><code>%KEY_DOWN[]</code></td>
578     <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
580 schoenebeck 2936 as index to this array variable (see also <code>event_status()</code>).</td>
581 schoenebeck 2732 </tr>
582     <tr>
583 schoenebeck 3248 <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 schoenebeck 2732 <td><code>$VCC_MONO_AT</code></td>
592     <td>Constant identifying the MIDI monophonic aftertouch controller (also
593     called <i title="Amount of force on held-down key.">
594     MIDI channel pressure
595     </i>). This is somewhat different than in the MIDI standard. With
596     NKSP aftertouch is handled like an additional "regular" MIDI CC controller.
597     Therefore use
598     <code>%CC[$VCC_MONO_AT]</code> to obtain the current aftertouch value
599     in the context of a <code>controller</code> event handler.
600     </td>
601     </tr>
602     <tr>
603     <td><code>$VCC_PITCH_BEND</code></td>
604     <td>Constant identifying the pitch bend wheel controller.
605     This is somewhat different than in the MIDI standard. With
606     NKSP pitch bend is handled like an additional "regular" MIDI CC controller.
607     Therefore use
608 schoenebeck 2936 <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current pitch bend wheel value
609 schoenebeck 2732 in the context of a <code>controller</code> event handler.</td>
610     </tr>
611     <tr>
612     <td><code>$MARK_1</code> to <code>$MARK_28</code></td>
613     <td>Used to select one of the available 28 event groups.
614     See <code>set_event_mark()</code> for details.</td>
615     </tr>
616 schoenebeck 2944 <tr>
617     <td><code>$ENGINE_UPTIME</code></td>
618     <td>Returns the current time stamp (in milliseconds) for being
619     used in a musical context. You may read this variable from time to time
620     to take time stamps which can be used to calculate the time difference
621     (in milliseconds) which elapsed between them. These timing values are
622     based on the internal sample rate and thus it can safely be used to
623     perform musical timing related tasks in your scripts. Especially
624     your script will also continue to behave correctly when an offline bounce
625     of a song is performed.
626     </td>
627     </tr>
628 schoenebeck 2732 </table>
629    
630     <h3>GigaStudio Format Variables</h3>
631     <p>
632     Sampler format specific built-in variables and constants, dedicated to the
633     individual features of the GigaStudio format engine.
634     </p>
635     <table>
636     <tr>
637     <th>Variable</th> <th>Description</th>
638     </tr>
639     <tr>
640     <td><code>$GIG_DIM_CHANNEL</code></td>
641     <td>Constant that identifies the <i>stereo dimension</i>.</td>
642     </tr>
643     <tr>
644     <td><code>$GIG_DIM_LAYER</code></td>
645     <td>Constant that identifies the <i>layer dimension</i>.</td>
646     </tr>
647     <tr>
648     <td><code>$GIG_DIM_VELOCITY</code></td>
649     <td>Constant that identifies the <i>velocity dimension</i>.</td>
650     </tr>
651     <tr>
652     <td><code>$GIG_DIM_AFTERTOUCH</code></td>
653     <td>Constant that identifies the <i>aftertouch dimension</i>.</td>
654     </tr>
655     <tr>
656     <td><code>$GIG_DIM_RELEASE</code></td>
657     <td>Constant that identifies the <i>release trigger dimension</i>.</td>
658     </tr>
659     <tr>
660     <td><code>$GIG_DIM_KEYBOARD</code></td>
661     <td>Constant that identifies the <i>keyboard position dimension</i>.</td>
662     </tr>
663     <tr>
664 schoenebeck 3229 <td><code>$GIG_DIM_ROUNDROBIN</code></td>
665 schoenebeck 2732 <td>Constant that identifies the <i>round robin dimension</i>.</td>
666     </tr>
667     <tr>
668     <td><code>$GIG_DIM_RANDOM</code></td>
669     <td>Constant that identifies the <i>random dimension</i>.</td>
670     </tr>
671     <tr>
672     <td><code>$GIG_DIM_SMARTMIDI</code></td>
673     <td>Constant that identifies the <i>start MIDI dimension</i> (a.k.a iMIDI rules).</td>
674     </tr>
675     <tr>
676     <td><code>$GIG_DIM_ROUNDROBINKEY</code></td>
677     <td>Constant that identifies the <i>round robin key dimension</i>.</td>
678     </tr>
679     <tr>
680     <td><code>$GIG_DIM_MODWHEEL</code></td>
681     <td>Constant that identifies the <i>modulation wheel dimension</i>.</td>
682     </tr>
683     <tr>
684     <td><code>$GIG_DIM_SUSTAIN</code></td>
685     <td>Constant that identifies the <i>sustain pedal dimension</i> (a.k.a. hold pedal).</td>
686     </tr>
687     <tr>
688     <td><code>$GIG_DIM_PORTAMENTO</code></td>
689     <td>Constant that identifies the <i>portamento MIDI controller dimension</i>.</td>
690     </tr>
691     <tr>
692     <td><code>$GIG_DIM_SOSTENUTO</code></td>
693     <td>Constant that identifies the <i>sostenuto MIDI controller dimension</i>.</td>
694     </tr>
695     <tr>
696     <td><code>$GIG_DIM_SOFT</code></td>
697     <td>Constant that identifies the <i>soft pedal dimension</i>.</td>
698     </tr>
699     <tr>
700     <td><code>$GIG_DIM_BREATH</code></td>
701     <td>Constant that identifies the <i>breath controller dimension</i>.</td>
702     </tr>
703     <tr>
704     <td><code>$GIG_DIM_FOOT</code></td>
705     <td>Constant that identifies the <i>foot pedal dimension</i>.</td>
706     </tr>
707     <tr>
708     <td><code>$GIG_DIM_PORTAMENTOTIME</code></td>
709     <td>Constant that identifies the <i>portamento time controller dimension</i>.</td>
710     </tr>
711     <tr>
712     <td><code>$GIG_DIM_EFFECT1</code></td>
713     <td>Constant that identifies the <i>effect 1 MIDI controller dimension</i>.</td>
714     </tr>
715     <tr>
716     <td><code>$GIG_DIM_EFFECT2</code></td>
717     <td>Constant that identifies the <i>effect 2 MIDI controller dimension</i>.</td>
718     </tr>
719     <tr>
720     <td><code>$GIG_DIM_EFFECT1DEPTH</code></td>
721     <td>Constant that identifies the <i>effect 1 depth MIDI controller dimension</i>.</td>
722     </tr>
723     <tr>
724     <td><code>$GIG_DIM_EFFECT2DEPTH</code></td>
725     <td>Constant that identifies the <i>effect 2 depth MIDI controller dimension</i>.</td>
726     </tr>
727     <tr>
728     <td><code>$GIG_DIM_EFFECT3DEPTH</code></td>
729     <td>Constant that identifies the <i>effect 3 depth MIDI controller dimension</i>.</td>
730     </tr>
731     <tr>
732     <td><code>$GIG_DIM_EFFECT4DEPTH</code></td>
733     <td>Constant that identifies the <i>effect 4 depth MIDI controller dimension</i>.</td>
734     </tr>
735     <tr>
736     <td><code>$GIG_DIM_EFFECT5DEPTH</code></td>
737     <td>Constant that identifies the <i>effect 5 depth MIDI controller dimension</i>.</td>
738     </tr>
739     <tr>
740     <td><code>$GIG_DIM_GENPURPOSE1</code></td>
741     <td>Constant that identifies the <i>general purpose 1 MIDI controller dimension</i>.</td>
742     </tr>
743     <tr>
744     <td><code>$GIG_DIM_GENPURPOSE2</code></td>
745     <td>Constant that identifies the <i>general purpose 2 MIDI controller dimension</i>.</td>
746     </tr>
747     <tr>
748     <td><code>$GIG_DIM_GENPURPOSE3</code></td>
749     <td>Constant that identifies the <i>general purpose 3 MIDI controller dimension</i>.</td>
750     </tr>
751     <tr>
752     <td><code>$GIG_DIM_GENPURPOSE4</code></td>
753     <td>Constant that identifies the <i>general purpose 4 MIDI controller dimension</i>.</td>
754     </tr>
755     <tr>
756     <td><code>$GIG_DIM_GENPURPOSE5</code></td>
757     <td>Constant that identifies the <i>general purpose 5 MIDI controller dimension</i>.</td>
758     </tr>
759     <tr>
760     <td><code>$GIG_DIM_GENPURPOSE6</code></td>
761     <td>Constant that identifies the <i>general purpose 6 MIDI controller dimension</i>.</td>
762     </tr>
763     <tr>
764     <td><code>$GIG_DIM_GENPURPOSE7</code></td>
765     <td>Constant that identifies the <i>general purpose 7 MIDI controller dimension</i>.</td>
766     </tr>
767     <tr>
768     <td><code>$GIG_DIM_GENPURPOSE8</code></td>
769     <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>
770     </tr>
771     </table>
772 schoenebeck 3312
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 schoenebeck 2732
779 schoenebeck 3312 <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 schoenebeck 2732 </body>
801     </html>

  ViewVC Help
Powered by ViewVC