/[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 3278 by schoenebeck, Mon Jun 5 19:02:59 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>callback_status()</code></td>
46            <td>Returns the current status of a callback (thread).</td>
47          </tr>
48          <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 48  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 207  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 275  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 319  Line 381 
381          </td>          </td>
382        </tr>        </tr>
383        <tr>        <tr>
384            <td><code>%NKSP_CALLBACK_CHILD_ID[]</code></td>
385            <td>
386              Reflects the callback IDs of all child threads which the current
387              script callback instance spawned by having called <code>fork()</code> before.
388              See the latter function for details about this array variable.
389            </td>
390          </tr>
391          <tr>
392            <td><code>$NKSP_CALLBACK_PARENT_ID</code></td>
393            <td>
394              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
396              thread which created this child thread. Otherwise this variable is <code>0</code>.
397              See <code>fork()</code> for more details about this variable.
398            </td>
399          </tr>
400          <tr>
401          <td><code>$NKSP_REAL_TIMER</code></td>          <td><code>$NKSP_REAL_TIMER</code></td>
402          <td>Returns the current time stamp in reality (in microseconds). You may          <td>Returns the current time stamp in reality (in microseconds). You may
403              read this variable from time to time to take              read this variable from time to time to take
# Line 686  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.3278  
changed lines
  Added in v.3580
  ViewVC Help
Powered by ViewVC