--- doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2017/05/19 14:26:05 3189 +++ doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html 2019/09/17 17:21:13 3603 @@ -5,17 +5,21 @@ Reference Reference Manual + +

NKSP Reference

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,52 +32,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. - exit() - Stops execution of the current event handler instance. + log10() + Calculates the logarithm to base 10 of given number. - wait() - Pauses execution for a certain amount of time. + log2() + Calculates the logarithm to base 2 of given number. - stop_wait() - Resumes execution of a suspended script callback. + max() + Calculates the maximum value of two given values. - abs() - Calculates the absolute value of a given value. + 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. + + + 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() @@ -83,8 +163,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 @@ -95,56 +199,68 @@ 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_tune_time() - Changes the duration of tuning changes. + change_attack() + Modifies the amplitude attack time of voices. - change_vol() - Changes the volume of voices. + change_cutoff() + Changes filter cutoff frequency of voices. - change_vol_time() - Changes the duration of volume changes. + change_cutoff_attack() + Modifies the filter cutoff attack time of voices. - change_cutoff() - Changes filter cutoff frequency of voices. + change_cutoff_decay() + Modifies the filter cutoff decay time of voices. - change_reso() - Changes filter resonance of voices. + change_cutoff_lfo_depth() + Modifies the filter cutoff LFO depth. - change_attack() - Modifies the attack time of voices. + 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_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() @@ -155,6 +271,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. @@ -167,35 +331,39 @@ Fade the requested note out. - set_controller() - Creates a MIDI control change event. - - - ignore_event() - Drops the given event. + 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 @@ -209,6 +377,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

@@ -227,6 +399,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). @@ -271,6 +459,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 @@ -332,6 +537,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. @@ -412,12 +625,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 @@ -491,7 +743,7 @@ Constant that identifies the keyboard position dimension. - $GIG_DIM_ROUNDROBIN" + $GIG_DIM_ROUNDROBIN Constant that identifies the round robin dimension. @@ -599,6 +851,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. +
+