/[svn]/doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html
ViewVC logotype

Diff of /doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3294 by schoenebeck, Tue Jun 27 23:29:31 2017 UTC revision 3580 by schoenebeck, Thu Aug 29 13:44:35 2019 UTC
# Line 11  Line 11 
11      <p>      <p>
12        This document gives you an overview of all built-in functions and built-in        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.        variables provided by the NKSP real-time instrument script language.
14          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      </p>      </p>
17    
18      <h2>Built-In Functions</h2>      <h2>Built-In Functions</h2>
# Line 32  Line 34 
34          <td>Stops execution of a script callback.</td>          <td>Stops execution of a script callback.</td>
35        </tr>        </tr>
36        <tr>        <tr>
37            <td><code>abs()</code></td>
38            <td>Calculates the absolute value of a given value.</td>
39          </tr>
40          <tr>
41          <td><code lang="nksp">array_equal()</code></td>          <td><code lang="nksp">array_equal()</code></td>
42          <td>Check whether two arrays are equal.</td>          <td>Check whether two arrays are equal.</td>
43        </tr>        </tr>
44        <tr>        <tr>
45          <td><code>fork()</code></td>          <td><code>callback_status()</code></td>
46          <td>Creates new execution instances.</td>          <td>Returns the current status of a callback (thread).</td>
47        </tr>        </tr>
48        <tr>        <tr>
49          <td><code lang="nksp">dec()</code></td>          <td><code lang="nksp">dec()</code></td>
50          <td>Decrements the passed integer variable by one.</td>          <td>Decrements the passed integer variable by one.</td>
51        </tr>        </tr>
52        <tr>        <tr>
53            <td><code>exit()</code></td>
54            <td>Stops execution of the current event handler instance.</td>
55          </tr>
56          <tr>
57            <td><code>fork()</code></td>
58            <td>Creates new execution instances (threads).</td>
59          </tr>
60          <tr>
61          <td><code>inc()</code></td>          <td><code>inc()</code></td>
62          <td>Increments the passed integer variable by one.</td>          <td>Increments the passed integer variable by one.</td>
63        </tr>        </tr>
# Line 52  Line 66 
66          <td>Checks whether a value is between two other values.</td>          <td>Checks whether a value is between two other values.</td>
67        </tr>        </tr>
68        <tr>        <tr>
69            <td><code>max()</code></td>
70            <td>Calculates the maximum value of two given values.</td>
71          </tr>
72          <tr>
73          <td><code lang="nksp">message()</code></td>          <td><code lang="nksp">message()</code></td>
74          <td>Prints text to the sampler's terminal.</td>          <td>Prints text to the sampler's terminal.</td>
75        </tr>        </tr>
76        <tr>        <tr>
77            <td><code>min()</code></td>
78            <td>Calculates the minimum value of two given values.</td>
79          </tr>
80          <tr>
81            <td><code>num_elements()</code></td>
82            <td>Returns the size of the requested array variable.</td>
83          </tr>
84          <tr>
85            <td><code>random()</code></td>
86            <td>Random number generator.</td>
87          </tr>
88          <tr>
89          <td><code>search()</code></td>          <td><code>search()</code></td>
90          <td>Search for a certain value within an array.</td>          <td>Search for a certain value within an array.</td>
91        </tr>        </tr>
92        <tr>        <tr>
93            <td><code>sh_left()</code></td>
94            <td>Calculates a left bit shifted value.</td>
95          </tr>
96          <tr>
97            <td><code>sh_right()</code></td>
98            <td>Calculates a right bit shifted value.</td>
99          </tr>
100          <tr>
101          <td><code>sort()</code></td>          <td><code>sort()</code></td>
102          <td>Sort the given array.</td>          <td>Sort the given array.</td>
103        </tr>        </tr>
104        <tr>        <tr>
105          <td><code>exit()</code></td>          <td><code>stop_wait()</code></td>
106          <td>Stops execution of the current event handler instance.</td>          <td>Resumes execution of a suspended script callback.</td>
107        </tr>        </tr>
108        <tr>        <tr>
109          <td><code>wait()</code></td>          <td><code>wait()</code></td>
110          <td>Pauses execution for a certain amount of time.</td>          <td>Pauses execution for a certain amount of time.</td>
111        </tr>        </tr>
112        </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>        <tr>
121          <td><code>stop_wait()</code></td>          <th>Function</th> <th>Description</th>
         <td>Resumes execution of a suspended script callback.</td>  
122        </tr>        </tr>
123        <tr>        <tr>
124          <td><code>abs()</code></td>          <td><code>by_marks()</code></td>
125          <td>Calculates the absolute value of a given value.</td>          <td>Returns all events of an event group.</td>
126        </tr>        </tr>
127        <tr>        <tr>
128          <td><code>random()</code></td>          <td><code>change_amp_lfo_depth()</code></td>
129          <td>Random number generator.</td>          <td>Modifies the amplitude LFO depth.</td>
130        </tr>        </tr>
131        <tr>        <tr>
132          <td><code>min()</code></td>          <td><code>change_amp_lfo_freq()</code></td>
133          <td>Calculates the minimum value of two given values.</td>          <td>Modifies the amplitude LFO frequency.</td>
134        </tr>        </tr>
135        <tr>        <tr>
136          <td><code>max()</code></td>          <td><code>change_attack()</code></td>
137          <td>Calculates the maximum value of two given values.</td>          <td>Modifies the amplitude attack time of voices.</td>
138        </tr>        </tr>
139        <tr>        <tr>
140          <td><code>num_elements()</code></td>          <td><code>change_cutoff()</code></td>
141          <td>Returns the size of the requested array variable.</td>          <td>Changes filter cutoff frequency of voices.</td>
142        </tr>        </tr>
143        <tr>        <tr>
144          <td><code>sh_left()</code></td>          <td><code>change_cutoff_attack()</code></td>
145          <td>Calculates a left bit shifted value.</td>          <td>Modifies the filter cutoff attack time of voices.</td>
146        </tr>        </tr>
147        <tr>        <tr>
148          <td><code>sh_right()</code></td>          <td><code>change_cutoff_decay()</code></td>
149          <td>Calculates a right bit shifted value.</td>          <td>Modifies the filter cutoff decay time of voices.</td>
150        </tr>        </tr>
     </table>  
       
     <h3>Common Sampler Functions</h3>  
     <p>  
       Basic sampler related functions, independent from a particular sampler  
       format or sampler engine.  
     </p>  
     <table>  
151        <tr>        <tr>
152          <th>Function</th> <th>Description</th>          <td><code>change_cutoff_lfo_depth()</code></td>
153            <td>Modifies the filter cutoff LFO depth.</td>
154        </tr>        </tr>
155        <tr>        <tr>
156          <td><code>play_note()</code></td>          <td><code>change_cutoff_lfo_freq()</code></td>
157          <td>Triggers a new note.</td>          <td>Modifies the filter cutoff LFO frequency.</td>
158        </tr>        </tr>
159        <tr>        <tr>
160          <td><code>change_note()</code></td>          <td><code>change_cutoff_release()</code></td>
161          <td>Change MIDI note number of note.</td>          <td>Modifies the filter cutoff release time of voices.</td>
162        </tr>        </tr>
163        <tr>        <tr>
164          <td><code>change_pan()</code></td>          <td><code>change_cutoff_sustain()</code></td>
165          <td>Changes panning of voices (stereo balance).</td>          <td>Modifies the filter cutoff sustain level of voices.</td>
166        </tr>        </tr>
167        <tr>        <tr>
168          <td><code>change_play_pos()</code></td>          <td><code>change_decay()</code></td>
169          <td>Change the sample playback position.</td>          <td>Modifies the amplitude decay time of voices.</td>
170        </tr>        </tr>
171        <tr>        <tr>
172          <td><code>change_tune()</code></td>          <td><code>change_note()</code></td>
173          <td>Changes the tuning of voices.</td>          <td>Change MIDI note number of note.</td>
174        </tr>        </tr>
175        <tr>        <tr>
176          <td><code>change_tune_time()</code></td>          <td><code>change_pan()</code></td>
177          <td>Changes the duration of tuning changes.</td>          <td>Changes panning of voices (stereo balance).</td>
178        </tr>        </tr>
179        <tr>        <tr>
180          <td><code>change_tune_curve()</code></td>          <td><code>change_pan_curve()</code></td>
181          <td>Changes the curve type of tuning changes.</td>          <td>Changes the curve type of panning (stereo balance) changes.</td>
182        </tr>        </tr>
183        <tr>        <tr>
184          <td><code>change_vol()</code></td>          <td><code>change_pan_time()</code></td>
185          <td>Changes the volume of voices.</td>          <td>Changes the duration of panning (stereo balance) changes.</td>
186        </tr>        </tr>
187        <tr>        <tr>
188          <td><code>change_vol_time()</code></td>          <td><code>change_pitch_lfo_depth()</code></td>
189          <td>Changes the duration of volume changes.</td>          <td>Modifies the pitch LFO depth.</td>
190        </tr>        </tr>
191        <tr>        <tr>
192          <td><code>change_vol_curve()</code></td>          <td><code>change_pitch_lfo_freq()</code></td>
193          <td>Changes the curve type of volume changes.</td>          <td>Modifies the pitch LFO frequency.</td>
194        </tr>        </tr>
195        <tr>        <tr>
196          <td><code>change_cutoff()</code></td>          <td><code>change_play_pos()</code></td>
197          <td>Changes filter cutoff frequency of voices.</td>          <td>Change the sample playback position.</td>
198          </tr>
199          <tr>
200            <td><code>change_release()</code></td>
201            <td>Modifies the amplitude release time of voices.</td>
202        </tr>        </tr>
203        <tr>        <tr>
204          <td><code>change_reso()</code></td>          <td><code>change_reso()</code></td>
205          <td>Changes filter resonance of voices.</td>          <td>Changes filter resonance of voices.</td>
206        </tr>        </tr>
207        <tr>        <tr>
208          <td><code>change_attack()</code></td>          <td><code>change_sustain()</code></td>
209          <td>Modifies the attack time of voices.</td>          <td>Modifies the amplitude sustain level of voices.</td>
210        </tr>        </tr>
211        <tr>        <tr>
212          <td><code>change_decay()</code></td>          <td><code>change_tune()</code></td>
213          <td>Modifies the decay time of voices.</td>          <td>Changes the tuning of voices.</td>
214        </tr>        </tr>
215        <tr>        <tr>
216          <td><code>change_release()</code></td>          <td><code>change_tune_curve()</code></td>
217          <td>Modifies the release time of voices.</td>          <td>Changes the curve type of tuning changes.</td>
218        </tr>        </tr>
219        <tr>        <tr>
220          <td><code>change_amp_lfo_depth()</code></td>          <td><code>change_tune_time()</code></td>
221          <td>Modifies the amplitude LFO depth.</td>          <td>Changes the duration of tuning changes.</td>
222        </tr>        </tr>
223        <tr>        <tr>
224          <td><code>change_amp_lfo_freq()</code></td>          <td><code>change_velo()</code></td>
225          <td>Modifies the amplitude LFO frequency.</td>          <td>Change MIDI velocity of note.</td>
226        </tr>        </tr>
227        <tr>        <tr>
228          <td><code>change_pitch_lfo_depth()</code></td>          <td><code>change_vol()</code></td>
229          <td>Modifies the pitch LFO depth.</td>          <td>Changes the volume of voices.</td>
230        </tr>        </tr>
231        <tr>        <tr>
232          <td><code>change_pitch_lfo_freq()</code></td>          <td><code>change_vol_curve()</code></td>
233          <td>Modifies the pitch LFO frequency.</td>          <td>Changes the curve type of volume changes.</td>
234        </tr>        </tr>
235        <tr>        <tr>
236          <td><code>change_velo()</code></td>          <td><code>change_vol_time()</code></td>
237          <td>Change MIDI velocity of note.</td>          <td>Changes the duration of volume changes.</td>
238          </tr>
239          <tr>
240            <td><code>delete_event_mark()</code></td>
241            <td>Removes an event from some event group.</td>
242        </tr>        </tr>
243        <tr>        <tr>
244          <td><code>event_status()</code></td>          <td><code>event_status()</code></td>
# Line 211  Line 257 
257          <td>Get the current value of a specific note parameter.</td>          <td>Get the current value of a specific note parameter.</td>
258        </tr>        </tr>
259        <tr>        <tr>
260          <td><code>set_event_par()</code></td>          <td><code>ignore_controller()</code></td>
261          <td>Change the value of a specific note parameter.</td>          <td>Drops the given MIDI control change event.</td>
       </tr>  
       <tr>  
         <td><code>set_controller()</code></td>  
         <td>Creates a MIDI control change event.</td>  
262        </tr>        </tr>
263        <tr>        <tr>
264          <td><code>ignore_event()</code></td>          <td><code>ignore_event()</code></td>
265          <td>Drops the given event.</td>          <td>Drops the given event.</td>
266        </tr>        </tr>
267        <tr>        <tr>
         <td><code>ignore_controller()</code></td>  
         <td>Drops the given MIDI control change event.</td>  
       </tr>  
       <tr>  
268          <td><code>note_off()</code></td>          <td><code>note_off()</code></td>
269          <td>Releases the requested note.</td>          <td>Releases the requested note.</td>
270        </tr>        </tr>
271        <tr>        <tr>
272          <td><code>set_event_mark()</code></td>          <td><code>play_note()</code></td>
273          <td>Adds an event to an event group.</td>          <td>Triggers a new note.</td>
274        </tr>        </tr>
275        <tr>        <tr>
276          <td><code>delete_event_mark()</code></td>          <td><code>set_controller()</code></td>
277          <td>Removes an event from some event group.</td>          <td>Creates a MIDI control change event.</td>
278        </tr>        </tr>
279        <tr>        <tr>
280          <td><code>by_marks()</code></td>          <td><code>set_event_mark()</code></td>
281          <td>Returns all events of an event group.</td>          <td>Adds an event to an event group.</td>
282          </tr>
283          <tr>
284            <td><code>set_event_par()</code></td>
285            <td>Change the value of a specific note parameter.</td>
286        </tr>        </tr>
287      </table>      </table>
288        
289      <h3>GigaStudio Format Functions</h3>      <h3>GigaStudio Format Functions</h3>
290      <p>      <p>
291        Sampler format specific functions, dedicated to the individual features        Sampler format specific functions, dedicated to the individual features
# Line 279  Line 321 
321          <th>Variable</th> <th>Description</th>          <th>Variable</th> <th>Description</th>
322        </tr>        </tr>
323        <tr>        <tr>
324            <td><code>$CALLBACK_STATUS_QUEUE</code></td>
325            <td>Built-in constant reflecting the status of a callback to be
326                alive but suspended. See <code>callback_status()</code> for details.</td>
327          </tr>
328          <tr>
329            <td><code>$CALLBACK_STATUS_RUNNING</code></td>
330            <td>Built-in constant reflecting the status of a callback to be
331                alive and currently executing. See <code>callback_status()</code>
332                for details.</td>
333          </tr>
334          <tr>
335            <td><code>$CALLBACK_STATUS_TERMINATED</code></td>
336            <td>Built-in constant reflecting the status of a callback to be
337                not alive. See <code>callback_status()</code> for details.</td>
338          </tr>
339          <tr>
340          <td><code>$KSP_TIMER</code></td>          <td><code>$KSP_TIMER</code></td>
341          <td>Preserved for compatiblity reasons with KSP, returns the same value          <td>Preserved for compatiblity reasons with KSP, returns the same value
342             as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).             as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
# Line 326  Line 384 
384          <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>          <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
385          <td>          <td>
386            Reflects the callback IDs of all child threads which the current            Reflects the callback IDs of all child threads which the current
387            script callback instance spawned by calling function <code>fork()</code>.            script callback instance spawned by having called <code>fork()</code> before.
388            See the latter function for details about this array variable.            See the latter function for details about this array variable.
389          </td>          </td>
390        </tr>        </tr>
# Line 335  Line 393 
393          <td>          <td>
394            If the current execution thread is a child thread spawned by a <code>fork()</code>            If the current execution thread is a child thread spawned by a <code>fork()</code>
395            call before, then this variable reflects the callback ID of the parent            call before, then this variable reflects the callback ID of the parent
396            thread which created this child thread. Otherwise this variable is zero.            thread which created this child thread. Otherwise this variable is <code>0</code>.
397            See function <code>fork()</code> for more details about this variable.            See <code>fork()</code> for more details about this variable.
398          </td>          </td>
399        </tr>        </tr>
400        <tr>        <tr>
# Line 707  Line 765 
765          <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>          <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>
766        </tr>        </tr>
767      </table>      </table>
768    
769            <h2>Built-In Preprocessor Conditions</h2>
770        <p>
771          These are the built-in preprocessor conditions available with the NKSP realt-time
772          instrument script language.
773        </p>
774            
775        <h3>Core Language Preprocessor Conditions</h3>
776        <p>
777          Most fundamental NKSP built-in preprocessor conditions, independent from
778          any purpose of being used in a sampler.
779        </p>
780        <table>
781          <tr>
782            <th>Condition</th> <th>Description</th>
783          </tr>
784          <tr>
785            <td><code>NKSP_NO_MESSAGE</code></td>
786            <td>
787              By default this condition is not set. By explicitly enabling this
788              condition with <code>SET_CONDITION(NKSP_NO_MESSAGE)</code> it
789              causes all subsequent <code>message()</code> calls to be ignored
790              and filtered out on preprocessor level. See function <code>message()</code>
791              for details.
792            </td>
793          </tr>
794        </table>
795    
796    </body>    </body>
797  </html>  </html>
Legend:
Removed from v.3294  
changed lines
  Added in v.3580
  ViewVC Help
Powered by ViewVC