/[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 2732 by schoenebeck, Sun Apr 26 20:54:00 2015 UTC revision 2954 by schoenebeck, Sat Jul 16 11:44:04 2016 UTC
# Line 28  Line 28 
28          <th>Function</th> <th>Description</th>          <th>Function</th> <th>Description</th>
29        </tr>        </tr>
30        <tr>        <tr>
31          <td><code>message()</code></td>          <td><code lang="nksp">dec()</code></td>
32            <td>Decrements the passed integer variable by one.</td>
33          </tr>
34          <tr>
35            <td><code>inc()</code></td>
36            <td>Increments the passed integer variable by one.</td>
37          </tr>
38          <tr>
39            <td><code lang="nksp">message()</code></td>
40          <td>Prints text to the sampler's terminal.</td>          <td>Prints text to the sampler's terminal.</td>
41        </tr>        </tr>
42        <tr>        <tr>
# Line 40  Line 48 
48          <td>Pauses execution for a certain amount of time.</td>          <td>Pauses execution for a certain amount of time.</td>
49        </tr>        </tr>
50        <tr>        <tr>
51            <td><code>stop_wait()</code></td>
52            <td>Resumes execution of a suspended script callback.</td>
53          </tr>
54          <tr>
55          <td><code>abs()</code></td>          <td><code>abs()</code></td>
56          <td>Calculates the absolute value of a given value.</td>          <td>Calculates the absolute value of a given value.</td>
57        </tr>        </tr>
# Line 67  Line 79 
79          <td>Triggers a new note.</td>          <td>Triggers a new note.</td>
80        </tr>        </tr>
81        <tr>        <tr>
82            <td><code>change_pan()</code></td>
83            <td>Changes panning of voices (stereo balance).</td>
84          </tr>
85          <tr>
86            <td><code>change_tune()</code></td>
87            <td>Changes the tuning of voices.</td>
88          </tr>
89          <tr>
90            <td><code>change_vol()</code></td>
91            <td>Changes the volume of voices.</td>
92          </tr>
93          <tr>
94            <td><code>change_cutoff()</code></td>
95            <td>Changes filter cutoff frequency of voices.</td>
96          </tr>
97          <tr>
98            <td><code>change_reso()</code></td>
99            <td>Changes filter resonance of voices.</td>
100          </tr>
101          <tr>
102            <td><code>change_attack()</code></td>
103            <td>Modifies the attack time of voices.</td>
104          </tr>
105          <tr>
106            <td><code>change_decay()</code></td>
107            <td>Modifies the decay time of voices.</td>
108          </tr>
109          <tr>
110            <td><code>change_release()</code></td>
111            <td>Modifies the release time of voices.</td>
112          </tr>
113          <tr>
114            <td><code>event_status()</code></td>
115            <td>Checks and returns whether a particular note is still alive.</td>
116          </tr>
117          <tr>
118          <td><code>set_controller()</code></td>          <td><code>set_controller()</code></td>
119          <td>Creates a MIDI control change event.</td>          <td>Creates a MIDI control change event.</td>
120        </tr>        </tr>
# Line 116  Line 164 
164        These are the built-in variables and built-in constants available with the        These are the built-in variables and built-in constants available with the
165        NKSP realt-time instrument script language.        NKSP realt-time instrument script language.
166      </p>      </p>
167        
168        <h3>Core Language Variables</h3>
169        <p>
170          Most fundamental NKSP built-in variables, independent from any purpose of
171          being used in a sampler.
172        </p>
173        <table>
174          <tr>
175            <th>Variable</th> <th>Description</th>
176          </tr>
177          <tr>
178            <td><code>$KSP_TIMER</code></td>
179            <td>Preserved for compatiblity reasons with KSP, returns the same value
180               as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
181               Note that KSP's <code>reset_ksp_timer()</code> function is not available with
182               NKSP. However when calculating time differences between two time
183               stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
184               function is not required, because the underlying clock does not stop
185               when it reached its value limit (which happens every 71 minutes), instead the clock
186               will automatically restart from zero and the calculated time difference
187               even between such transitions will reflect correct durations.</td>
188          </tr>
189          <tr>
190            <td><code>$NKSP_PERF_TIMER</code></td>
191            <td>Returns the current performance time stamp (in microseconds) of the
192                script running. You may read this variable from time to time to take
193                time stamps which can be used to calculate the time difference
194                (in microseconds) which elapsed between them. A performance time
195                stamp is based on the script's actual CPU execution time. So the
196                internal clock which is used for generating such time stamps is only
197                running forward if the respective script is actually executed by the
198                CPU. Whenever your script is not really executed by the CPU (i.e. because
199                your script got suspended by a wait() call or got forcely suspended due to
200                real-time constraints, or when the entire sampler application got suspended
201                by the OS for other applications or OS tasks) then the underlying internal
202                clock is paused as well.
203                <note class="important">
204                  You should only use this built-in variable for script development
205                  purposes (i.e. for bench marking the performance of your script).
206                  You should <b>not</b> use it with your final production sounds!
207                  It is not appropriate for being used in a musical context, because
208                  when an offline bounce is performed for instance, the musical timing
209                  will be completely unrelated to the CPU execution time. Plus using
210                  this variable may cause audio drop outs on some systems. In a musical
211                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
212                  also safe for offline bounces.
213                </note>
214                <note>
215                  On some systems <code>$NKSP_REAL_TIMER</code> and
216                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
217                  difference between them is not implemented for all systems at the moment.
218                </note>
219            </td>
220          </tr>
221          <tr>
222            <td><code>$NKSP_REAL_TIMER</code></td>
223            <td>Returns the current time stamp in reality (in microseconds). You may
224                read this variable from time to time to take
225                time stamps which can be used to calculate the time difference
226                (in microseconds) which elapsed between them. A "real" time
227                stamp is based on an internal clock which constantly proceeds, so this
228                internal clock also continues counting while your script is either suspended
229                (i.e. because your script got suspended by a wait() call or got forcely
230                suspended due to real-time constraints) and it also continues counting
231                even if the entire sampler application got suspended by the OS (i.e. to
232                execute other applications for multi-tasking or to perform OS tasks).
233                <note class="important">
234                  You should only use this built-in variable for script development
235                  purposes (i.e. for bench marking the performance of your script).
236                  You should <b>not</b> use it with your final production sounds!
237                  It is not appropriate for being used in a musical context, because
238                  when an offline bounce is performed for instance, the musical timing
239                  will be completely unrelated to the CPU execution time. Plus using
240                  this variable may cause audio drop outs on some systems. In a musical
241                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
242                  also safe for offline bounces.
243                </note>
244                <note>
245                  On some systems <code>$NKSP_REAL_TIMER</code> and
246                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
247                  difference between them is not implemented for all systems at the moment.
248                </note>
249            </td>
250          </tr>
251          <tr>
252            <td><code>$NI_CALLBACK_ID</code></td>
253            <td>Reflects the current event handler instance's unique callback ID.
254                For the same event type there may be more than
255                one event handler instances running. Each one of them has
256                its own callback ID. You can get the current event handler
257                instance's callback ID by reading this built-in variable.</td>
258          </tr>
259          <tr>
260            <td><code>$NI_CALLBACK_TYPE</code></td>
261            <td>Reflects the event type of the current event handler. This variable
262                may reflect one of the following built-in constants:
263                <code>$NI_CB_TYPE_INIT</code>, <code>$NI_CB_TYPE_NOTE</code>,
264                <code>$NI_CB_TYPE_RELEASE</code>, <code>$NI_CB_TYPE_CONTROLLER</code>.</td>
265          </tr>
266          <tr>
267            <td><code>$NI_CB_TYPE_INIT</code></td>
268            <td>Built-in constant reflecting an <code>init</code> event handler type.</td>
269          </tr>
270          <tr>
271            <td><code>$NI_CB_TYPE_NOTE</code></td>
272            <td>Built-in constant reflecting a <code>note</code> event handler type.</td>
273          </tr>
274          <tr>
275            <td><code>$NI_CB_TYPE_RELEASE</code></td>
276            <td>Built-in constant reflecting a <code>release</code> event handler type.</td>
277          </tr>
278          <tr>
279            <td><code>$NI_CB_TYPE_CONTROLLER</code></td>
280            <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>
281          </tr>
282          <tr>
283            <td><code>$NKSP_IGNORE_WAIT</code></td>
284            <td>If this boolean built-in variable is <code>1</code> then all calls of your
285                event handler instance to function <code>wait()</code> will be ignored.
286                This may for example be the case if another event handler instance
287                resumed your paused script by calling <code>stop_wait()</code> and
288                passing <code>1</code> to the 2nd argument of that function.</td>
289          </tr>
290        </table>
291    
292      <h3>Common Sampler Variables</h3>      <h3>Common Sampler Variables</h3>
293      <p>      <p>
294        Basic sampler related built-in variables and constants, independent from a        Basic sampler related built-in variables and constants, independent from a
# Line 160  Line 332 
332              <code>note</code> or <code>release</code> handler).</td>              <code>note</code> or <code>release</code> handler).</td>
333        </tr>        </tr>
334        <tr>        <tr>
335            <td><code>$EVENT_STATUS_INACTIVE</code></td>
336            <td>Constant bit flag used as possible return value by
337                <code>event_status()</code> in case the requested
338                note is not "alive".</td>
339          </tr>
340          <tr>
341            <td><code>$EVENT_STATUS_NOTE_QUEUE</code></td>
342            <td>Constant bit flag used as possible return value by
343                <code>event_status()</code> in case the requested
344                note is still "alive".</td>
345          </tr>
346          <tr>
347          <td><code>%KEY_DOWN[]</code></td>          <td><code>%KEY_DOWN[]</code></td>
348          <td>This can be used in any context to check whether a certain MIDI          <td>This can be used in any context to check whether a certain MIDI
349              key is currently pressed down. Use the respective MIDI note number              key is currently pressed down. Use the respective MIDI note number
350              as index to this array variable.</td>              as index to this array variable (see also <code>event_status()</code>).</td>
351        </tr>        </tr>
352        <tr>        <tr>
353          <td><code>$VCC_MONO_AT</code></td>          <td><code>$VCC_MONO_AT</code></td>
# Line 183  Line 367 
367              This is somewhat different than in the MIDI standard. With              This is somewhat different than in the MIDI standard. With
368              NKSP pitch bend is handled like an additional "regular" MIDI CC controller.              NKSP pitch bend is handled like an additional "regular" MIDI CC controller.
369              Therefore use              Therefore use
370              <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current aftertouch value              <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current pitch bend wheel value
371              in the context of a <code>controller</code> event handler.</td>              in the context of a <code>controller</code> event handler.</td>
372        </tr>        </tr>
373        <tr>        <tr>
# Line 191  Line 375 
375          <td>Used to select one of the available 28 event groups.          <td>Used to select one of the available 28 event groups.
376          See <code>set_event_mark()</code> for details.</td>          See <code>set_event_mark()</code> for details.</td>
377        </tr>        </tr>
378          <tr>
379            <td><code>$ENGINE_UPTIME</code></td>
380            <td>Returns the current time stamp (in milliseconds) for being
381                used in a musical context. You may read this variable from time to time
382                to take time stamps which can be used to calculate the time difference
383                (in milliseconds) which elapsed between them. These timing values are
384                based on the internal sample rate and thus it can safely be used to
385                perform musical timing related tasks in your scripts. Especially
386                your script will also continue to behave correctly when an offline bounce
387                of a song is performed.
388            </td>
389          </tr>
390      </table>      </table>
391    
392      <h3>GigaStudio Format Variables</h3>      <h3>GigaStudio Format Variables</h3>
Legend:
Removed from v.2732  
changed lines
  Added in v.2954
  ViewVC Help
Powered by ViewVC