--- doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2017/01/05 16:18:19 3074
+++ doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2019/08/29 13:44:35 3580
@@ -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,50 +30,66 @@
Function | Description |
- dec() |
- Decrements the passed integer variable by one. |
+ abort() |
+ Stops execution of a script callback. |
- inc() |
- Increments the passed integer variable by one. |
+ abs() |
+ Calculates the absolute value of a given value. |
- message() |
- Prints text to the sampler's terminal. |
+ array_equal() |
+ Check whether two arrays are equal. |
- exit() |
- Stops execution of the current event handler instance. |
+ callback_status() |
+ Returns the current status of a callback (thread). |
- wait() |
- Pauses execution for a certain amount of time. |
+ dec() |
+ Decrements the passed integer variable by one. |
- stop_wait() |
- Resumes execution of a suspended script callback. |
+ exit() |
+ Stops execution of the current event handler instance. |
- abs() |
- Calculates the absolute value of a given value. |
+ fork() |
+ Creates new execution instances (threads). |
- random() |
- Random number generator. |
+ inc() |
+ Increments the passed integer variable by one. |
- min() |
- Calculates the minimum value of two given values. |
+ in_range() |
+ Checks whether a value is between two other values. |
max() |
Calculates the maximum value of two given values. |
+ message() |
+ Prints text to the sampler's terminal. |
+
+
+ min() |
+ Calculates the minimum value of two given values. |
+
+
num_elements() |
Returns the size of the requested array variable. |
+ random() |
+ Random number generator. |
+
+
+ search() |
+ Search for a certain value within an array. |
+
+
sh_left() |
Calculates a left bit shifted value. |
@@ -79,8 +97,20 @@
sh_right() |
Calculates a right bit shifted value. |
+
+ sort() |
+ Sort the given array. |
+
+
+ stop_wait() |
+ Resumes execution of a suspended script callback. |
+
+
+ wait() |
+ Pauses execution for a certain amount of time. |
+
-
+
Common Sampler Functions
Basic sampler related functions, independent from a particular sampler
@@ -91,75 +121,171 @@
Function | Description |
- play_note() |
- Triggers a new note. |
+ by_marks() |
+ Returns all events of an event group. |
- change_pan() |
- Changes panning of voices (stereo balance). |
+ change_amp_lfo_depth() |
+ Modifies the amplitude LFO depth. |
- change_tune() |
- Changes the tuning of voices. |
+ change_amp_lfo_freq() |
+ Modifies the amplitude LFO frequency. |
- change_vol() |
- Changes the volume of voices. |
+ change_attack() |
+ Modifies the amplitude attack time of voices. |
change_cutoff() |
Changes filter cutoff frequency of voices. |
- change_reso() |
- Changes filter resonance of voices. |
+ change_cutoff_attack() |
+ Modifies the filter cutoff attack time of voices. |
- change_attack() |
- Modifies the attack time of voices. |
+ change_cutoff_decay() |
+ Modifies the filter cutoff decay time of voices. |
+
+
+ change_cutoff_lfo_depth() |
+ Modifies the filter cutoff LFO depth. |
+
+
+ change_cutoff_lfo_freq() |
+ Modifies the filter cutoff LFO frequency. |
+
+
+ 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_note() |
+ Change MIDI note number of note. |
+
+
+ change_pan() |
+ Changes panning of voices (stereo balance). |
+
+
+ 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() |
+ Modifies the pitch LFO depth. |
+
+
+ change_pitch_lfo_freq() |
+ Modifies the pitch LFO frequency. |
+
+
+ change_play_pos() |
+ Change the sample playback position. |
change_release() |
- Modifies the release time of voices. |
+ 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. |
- set_controller() |
- Creates a MIDI control change event. |
+ fade_in() |
+ Fade the requested note in. |
- ignore_event() |
- Drops the given event. |
+ fade_out() |
+ Fade the requested note out. |
+
+
+ get_event_par() |
+ Get the current value of a specific note parameter. |
ignore_controller() |
Drops the given MIDI control change event. |
+ ignore_event() |
+ Drops the given 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
@@ -173,6 +299,10 @@
gig_set_dim_zone() |
Changes the currently active dimension zone. |
+
+ same_region() |
+ Check whether two keys are mapped to the same region. |
+
Built-In Variables
@@ -191,6 +321,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).
@@ -235,6 +381,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
@@ -319,10 +482,13 @@
|
Note IDs of all currently active notes of the current sampler part (a.k.a. sampler channel).
This may be passed to many built-in functions like note_off().
+ This array variable only contains IDs of notes which were launched due
+ to MIDI note-on events. This variable does not contain IDs of child notes
+ (i.e. notes which were launched programmatically by calling play_note()).
In contrast to KSP this variable is an integer array type, whereas KSP's
pendent of this built-in variable is an integer constant (scalar) called
- $ALL_EVENTS. Using the latter with NKSP will cause a
+ $ALL_EVENTS. Using the latter with NKSP will cause a
parser warning, the behavior will be the same though.
|
@@ -373,12 +539,51 @@
note is still "alive".
+ $EVENT_PAR_NOTE |
+ Constant value symbolizing the "note number" parameter. See
+ get_event_par() and set_event_par()
+ for details. |
+
+
+ $EVENT_PAR_TUNE |
+ Constant value symbolizing the "tune" parameter. See
+ get_event_par() and set_event_par()
+ for details. |
+
+
+ $EVENT_PAR_VELOCITY |
+ Constant value symbolizing the "note velocity" parameter. See
+ get_event_par() and set_event_par()
+ for details. |
+
+
+ $EVENT_PAR_VOLUME |
+ Constant value symbolizing the "volume" parameter. See
+ get_event_par() and set_event_par()
+ for details. |
+
+
+ $EVENT_PAR_0 to $EVENT_PAR_3 |
+ Four constant values symbolizing the 4 possible user specific
+ parameters, which i.e. might be used to pass data from one script
+ (slot) to another script (slot). See get_event_par()
+ and set_event_par() for details. |
+
+
%KEY_DOWN[] |
This can be used in any context to check whether a certain MIDI
key is currently pressed down. Use the respective MIDI note number
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
@@ -452,7 +657,7 @@
| Constant that identifies the keyboard position dimension. |
- $GIG_DIM_ROUNDROBIN" |
+ $GIG_DIM_ROUNDROBIN |
Constant that identifies the round robin dimension. |
@@ -560,6 +765,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.
+ |
+
+
+