--- 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. +
+