--- doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2017/05/28 15:22:55 3229
+++ doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2019/09/16 16:03:36 3601
@@ -11,11 +11,13 @@
This document gives you an overview of all built-in functions and built-in
variables provided by the NKSP real-time instrument script language.
+ If you are new to NKSP, then you may want to read the
+ NKSP language tour first.
Built-In Functions
- These are the built-in functions available with the NKSP realt-time
+ These are the built-in functions available with the NKSP real-time
instrument script language.
@@ -28,64 +30,128 @@
Function | Description |
+ abort() |
+ Stops execution of a script callback. |
+
+
+ acos() |
+ Arc cosine function. |
+
+
+ abs() |
+ Calculates the absolute value of a given value. |
+
+
array_equal() |
Check whether two arrays are equal. |
+ asin() |
+ Arc sine function. |
+
+
+ atan() |
+ Arc tangens function. |
+
+
+ callback_status() |
+ Returns the current status of a callback (thread). |
+
+
+ ceil() |
+ Rounds the given real number up. |
+
+
+ cos() |
+ Cosine function. |
+
+
dec() |
Decrements the passed integer variable by one. |
+ exit() |
+ Stops execution of the current event handler instance. |
+
+
+ exp() |
+ Calculates e raised by given power. |
+
+
+ floor() |
+ Rounds the given real number down. |
+
+
+ fork() |
+ Creates new execution instances (threads). |
+
+
inc() |
Increments the passed integer variable by one. |
+ int() |
+ Short-hand alias function for function real_to_int() . |
+
+
+ int_to_real() |
+ Type cast from integer number to real number. |
+
+
in_range() |
Checks whether a value is between two other values. |
- message() |
- Prints text to the sampler's terminal. |
+ log() |
+ Calculates the natural logarithm of given number. |
- search() |
- Search for a certain value within an array. |
+ log10() |
+ Calculates the logarithm to base 10 of given number. |
- sort() |
- Sort the given array. |
+ log2() |
+ Calculates the logarithm to base 2 of given number. |
- exit() |
- Stops execution of the current event handler instance. |
+ max() |
+ Calculates the maximum value of two given values. |
- wait() |
- Pauses execution for a certain amount of time. |
+ message() |
+ Prints text to the sampler's terminal. |
- stop_wait() |
- Resumes execution of a suspended script callback. |
+ min() |
+ Calculates the minimum value of two given values. |
- abs() |
- Calculates the absolute value of a given value. |
+ num_elements() |
+ Returns the size of the requested array variable. |
+
+
+ pow() |
+ Calculates given base raised by given power. |
random() |
Random number generator. |
- min() |
- Calculates the minimum value of two given values. |
+ real() |
+ Short-hand alias function for function int_to_real() . |
- max() |
- Calculates the maximum value of two given values. |
+ real_to_int() |
+ Type cast from real number to integer number. |
- num_elements() |
- Returns the size of the requested array variable. |
+ round() |
+ Rounds the given real number. |
+
+
+ search() |
+ Search for a certain value within an array. |
sh_left() |
@@ -95,8 +161,32 @@
sh_right() |
Calculates a right bit shifted value. |
+
+ sin() |
+ Sine function. |
+
+
+ sort() |
+ Sort the given array. |
+
+
+ sqrt() |
+ Calculates the square root of given number. |
+
+
+ stop_wait() |
+ Resumes execution of a suspended script callback. |
+
+
+ tan() |
+ Tangens function. |
+
+
+ wait() |
+ Pauses execution for a certain amount of time. |
+
-
+
Common Sampler Functions
Basic sampler related functions, independent from a particular sampler
@@ -107,60 +197,68 @@
Function | Description |
- play_note() |
- Triggers a new note. |
+ by_marks() |
+ Returns all events of an event group. |
- change_note() |
- Change MIDI note number of note. |
+ change_amp_lfo_depth() |
+ Modifies the amplitude LFO depth. |
- change_pan() |
- Changes panning of voices (stereo balance). |
+ change_amp_lfo_freq() |
+ Modifies the amplitude LFO frequency. |
- change_tune() |
- Changes the tuning of voices. |
+ change_attack() |
+ Modifies the amplitude attack time of voices. |
- change_tune_time() |
- Changes the duration of tuning changes. |
+ change_cutoff() |
+ Changes filter cutoff frequency of voices. |
- change_vol() |
- Changes the volume of voices. |
+ change_cutoff_attack() |
+ Modifies the filter cutoff attack time of voices. |
- change_vol_time() |
- Changes the duration of volume changes. |
+ change_cutoff_decay() |
+ Modifies the filter cutoff decay time of voices. |
- change_cutoff() |
- Changes filter cutoff frequency of voices. |
+ change_cutoff_lfo_depth() |
+ Modifies the filter cutoff LFO depth. |
- change_reso() |
- Changes filter resonance of voices. |
+ change_cutoff_lfo_freq() |
+ Modifies the filter cutoff LFO frequency. |
- change_attack() |
- Modifies the attack time of voices. |
+ change_cutoff_release() |
+ Modifies the filter cutoff release time of voices. |
+
+
+ change_cutoff_sustain() |
+ Modifies the filter cutoff sustain level of voices. |
change_decay() |
- Modifies the decay time of voices. |
+ Modifies the amplitude decay time of voices. |
- change_release() |
- Modifies the release time of voices. |
+ change_note() |
+ Change MIDI note number of note. |
- change_amp_lfo_depth() |
- Modifies the amplitude LFO depth. |
+ change_pan() |
+ Changes panning of voices (stereo balance). |
- change_amp_lfo_freq() |
- Modifies the amplitude LFO frequency. |
+ change_pan_curve() |
+ Changes the curve type of panning (stereo balance) changes. |
+
+
+ change_pan_time() |
+ Changes the duration of panning (stereo balance) changes. |
change_pitch_lfo_depth() |
@@ -171,10 +269,54 @@
Modifies the pitch LFO frequency. |
+ change_play_pos() |
+ Change the sample playback position. |
+
+
+ change_release() |
+ Modifies the amplitude release time of voices. |
+
+
+ change_reso() |
+ Changes filter resonance of voices. |
+
+
+ change_sustain() |
+ Modifies the amplitude sustain level of voices. |
+
+
+ change_tune() |
+ Changes the tuning of voices. |
+
+
+ change_tune_curve() |
+ Changes the curve type of tuning changes. |
+
+
+ change_tune_time() |
+ Changes the duration of tuning changes. |
+
+
change_velo() |
Change MIDI velocity of note. |
+ change_vol() |
+ Changes the volume of voices. |
+
+
+ change_vol_curve() |
+ Changes the curve type of volume changes. |
+
+
+ change_vol_time() |
+ Changes the duration of volume changes. |
+
+
+ delete_event_mark() |
+ Removes an event from some event group. |
+
+
event_status() |
Checks and returns whether a particular note is still alive. |
@@ -191,39 +333,35 @@
Get the current value of a specific note parameter. |
- set_event_par() |
- Change the value of a specific note parameter. |
-
-
- set_controller() |
- Creates a MIDI control change event. |
+ ignore_controller() |
+ Drops the given MIDI control change event. |
ignore_event() |
Drops the given event. |
- ignore_controller() |
- Drops the given MIDI control change event. |
-
-
note_off() |
Releases the requested note. |
- set_event_mark() |
- Adds an event to an event group. |
+ play_note() |
+ Triggers a new note. |
- delete_event_mark() |
- Removes an event from some event group. |
+ set_controller() |
+ Creates a MIDI control change event. |
- by_marks() |
- Returns all events of an event group. |
+ set_event_mark() |
+ Adds an event to an event group. |
+
+
+ set_event_par() |
+ Change the value of a specific note parameter. |
-
+
GigaStudio Format Functions
Sampler format specific functions, dedicated to the individual features
@@ -259,6 +397,22 @@
Variable | Description |
+ $CALLBACK_STATUS_QUEUE |
+ Built-in constant reflecting the status of a callback to be
+ alive but suspended. See callback_status() for details. |
+
+
+ $CALLBACK_STATUS_RUNNING |
+ Built-in constant reflecting the status of a callback to be
+ alive and currently executing. See callback_status()
+ for details. |
+
+
+ $CALLBACK_STATUS_TERMINATED |
+ Built-in constant reflecting the status of a callback to be
+ not alive. See callback_status() for details. |
+
+
$KSP_TIMER |
Preserved for compatiblity reasons with KSP, returns the same value
as $NKSP_REAL_TIMER (refer to the latter for details).
@@ -303,6 +457,23 @@
|
+ %NKSP_CALLBACK_CHILD_ID[] |
+
+ Reflects the callback IDs of all child threads which the current
+ script callback instance spawned by having called fork() before.
+ See the latter function for details about this array variable.
+ |
+
+
+ $NKSP_CALLBACK_PARENT_ID |
+
+ If the current execution thread is a child thread spawned by a fork()
+ call before, then this variable reflects the callback ID of the parent
+ thread which created this child thread. Otherwise this variable is 0 .
+ See fork() for more details about this variable.
+ |
+
+
$NKSP_REAL_TIMER |
Returns the current time stamp in reality (in microseconds). You may
read this variable from time to time to take
@@ -364,6 +535,14 @@
| Built-in constant reflecting a controller event handler type. |
+ $NI_MATH_E |
+ Base of the natural logarithm (approximately being 2.71828 ) |
+
+
+ $NI_MATH_PI |
+ Natural constant relfecting the ratio of a circle's circumference to its diameter (approximately being 3.14159 ). |
+
+
$NKSP_IGNORE_WAIT |
If this boolean built-in variable is 1 then all calls of your
event handler instance to function wait() will be ignored.
@@ -481,6 +660,14 @@
as index to this array variable (see also event_status() ). |
+ $NKSP_EASE_IN_EASE_OUT |
+ Used to select a fade curve with "ease in and ease out" shape. |
+
+
+ $NKSP_LINEAR |
+ Used to select a fade curve with linear shape. |
+
+
$VCC_MONO_AT |
Constant identifying the MIDI monophonic aftertouch controller (also
called
@@ -662,6 +849,33 @@
| Constant that identifies the general purpose 8 MIDI controller dimension. |
+
+ Built-In Preprocessor Conditions
+
+ These are the built-in preprocessor conditions available with the NKSP realt-time
+ instrument script language.
+
+ Core Language Preprocessor Conditions
+
+ Most fundamental NKSP built-in preprocessor conditions, independent from
+ any purpose of being used in a sampler.
+
+
+
+ Condition | Description |
+
+
+ NKSP_NO_MESSAGE |
+
+ By default this condition is not set. By explicitly enabling this
+ condition with SET_CONDITION(NKSP_NO_MESSAGE) it
+ causes all subsequent message() calls to be ignored
+ and filtered out on preprocessor level. See function message()
+ for details.
+ |
+
+
+