/[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 2932 by schoenebeck, Sat Jul 9 14:41:00 2016 UTC revision 2946 by schoenebeck, Thu Jul 14 00: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 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>          <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>
# Line 79  Line 87 
87          <td>Changes the volume of voices.</td>          <td>Changes the volume of voices.</td>
88        </tr>        </tr>
89        <tr>        <tr>
90            <td><code>change_cutoff()</code></td>
91            <td>Changes filter cutoff frequency of voices.</td>
92          </tr>
93          <tr>
94            <td><code>change_reso()</code></td>
95            <td>Changes filter resonance of voices.</td>
96          </tr>
97          <tr>
98            <td><code>event_status()</code></td>
99            <td>Checks and returns whether a particular note is still alive.</td>
100          </tr>
101          <tr>
102          <td><code>set_controller()</code></td>          <td><code>set_controller()</code></td>
103          <td>Creates a MIDI control change event.</td>          <td>Creates a MIDI control change event.</td>
104        </tr>        </tr>
# Line 128  Line 148 
148        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
149        NKSP realt-time instrument script language.        NKSP realt-time instrument script language.
150      </p>      </p>
151        
152        <h3>Core Language Variables</h3>
153        <p>
154          Most fundamental NKSP built-in variables, independent from any purpose of
155          being used in a sampler.
156        </p>
157        <table>
158          <tr>
159            <th>Variable</th> <th>Description</th>
160          </tr>
161          <tr>
162            <td><code>$KSP_TIMER</code></td>
163            <td>Preserved for compatiblity reasons with KSP, returns the same value
164               as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
165               Note that KSP's <code>reset_ksp_timer()</code> function is not available with
166               NKSP. However when calculating time differences between two time
167               stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
168               function is not required, because the underlying clock does not stop
169               when it reached its value limit (which happens every 71 minutes), instead the clock
170               will automatically restart from zero and the calculated time difference
171               even between such transitions will reflect correct durations.</td>
172          </tr>
173          <tr>
174            <td><code>$NKSP_PERF_TIMER</code></td>
175            <td>Returns the current performance time stamp (in microseconds) of the
176                script running. You may read this variable from time to time to take
177                time stamps which can be used to calculate the time difference
178                (in microseconds) which elapsed between them. A performance time
179                stamp is based on the script's actual CPU execution time. So the
180                internal clock which is used for generating such time stamps is only
181                running forward if the respective script is actually executed by the
182                CPU. Whenever your script is not really executed by the CPU (i.e. because
183                your script got suspended by a wait() call or got forcely suspended due to
184                real-time constraints, or when the entire sampler application got suspended
185                by the OS for other applications or OS tasks) then the underlying internal
186                clock is paused as well.
187                <note class="important">
188                  You should only use this built-in variable for script development
189                  purposes (i.e. for bench marking the performance of your script).
190                  You should <b>not</b> use it with your final production sounds!
191                  It is not appropriate for being used in a musical context, because
192                  when an offline bounce is performed for instance, the musical timing
193                  will be completely unrelated to the CPU execution time. Plus using
194                  this variable may cause audio drop outs on some systems. In a musical
195                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
196                  also safe for offline bounces.
197                </note>
198                <note>
199                  On some systems <code>$NKSP_REAL_TIMER</code> and
200                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
201                  difference between them is not implemented for all systems at the moment.
202                </note>
203            </td>
204          </tr>
205          <tr>
206            <td><code>$NKSP_REAL_TIMER</code></td>
207            <td>Returns the current time stamp in reality (in microseconds). You may
208                read this variable from time to time to take
209                time stamps which can be used to calculate the time difference
210                (in microseconds) which elapsed between them. A "real" time
211                stamp is based on an internal clock which constantly proceeds, so this
212                internal clock also continues counting while your script is either suspended
213                (i.e. because your script got suspended by a wait() call or got forcely
214                suspended due to real-time constraints) and it also continues counting
215                even if the entire sampler application got suspended by the OS (i.e. to
216                execute other applications for multi-tasking or to perform OS tasks).
217                <note class="important">
218                  You should only use this built-in variable for script development
219                  purposes (i.e. for bench marking the performance of your script).
220                  You should <b>not</b> use it with your final production sounds!
221                  It is not appropriate for being used in a musical context, because
222                  when an offline bounce is performed for instance, the musical timing
223                  will be completely unrelated to the CPU execution time. Plus using
224                  this variable may cause audio drop outs on some systems. In a musical
225                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
226                  also safe for offline bounces.
227                </note>
228                <note>
229                  On some systems <code>$NKSP_REAL_TIMER</code> and
230                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
231                  difference between them is not implemented for all systems at the moment.
232                </note>
233            </td>
234          </tr>
235        </table>
236    
237      <h3>Common Sampler Variables</h3>      <h3>Common Sampler Variables</h3>
238      <p>      <p>
239        Basic sampler related built-in variables and constants, independent from a        Basic sampler related built-in variables and constants, independent from a
# Line 172  Line 277 
277              <code>note</code> or <code>release</code> handler).</td>              <code>note</code> or <code>release</code> handler).</td>
278        </tr>        </tr>
279        <tr>        <tr>
280            <td><code>$EVENT_STATUS_INACTIVE</code></td>
281            <td>Constant bit flag used as possible return value by
282                <code>event_status()</code> in case the requested
283                note is not "alive".</td>
284          </tr>
285          <tr>
286            <td><code>$EVENT_STATUS_NOTE_QUEUE</code></td>
287            <td>Constant bit flag used as possible return value by
288                <code>event_status()</code> in case the requested
289                note is still "alive".</td>
290          </tr>
291          <tr>
292          <td><code>%KEY_DOWN[]</code></td>          <td><code>%KEY_DOWN[]</code></td>
293          <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
294              key is currently pressed down. Use the respective MIDI note number              key is currently pressed down. Use the respective MIDI note number
295              as index to this array variable.</td>              as index to this array variable (see also <code>event_status()</code>).</td>
296        </tr>        </tr>
297        <tr>        <tr>
298          <td><code>$VCC_MONO_AT</code></td>          <td><code>$VCC_MONO_AT</code></td>
# Line 195  Line 312 
312              This is somewhat different than in the MIDI standard. With              This is somewhat different than in the MIDI standard. With
313              NKSP pitch bend is handled like an additional "regular" MIDI CC controller.              NKSP pitch bend is handled like an additional "regular" MIDI CC controller.
314              Therefore use              Therefore use
315              <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
316              in the context of a <code>controller</code> event handler.</td>              in the context of a <code>controller</code> event handler.</td>
317        </tr>        </tr>
318        <tr>        <tr>
# Line 203  Line 320 
320          <td>Used to select one of the available 28 event groups.          <td>Used to select one of the available 28 event groups.
321          See <code>set_event_mark()</code> for details.</td>          See <code>set_event_mark()</code> for details.</td>
322        </tr>        </tr>
323          <tr>
324            <td><code>$ENGINE_UPTIME</code></td>
325            <td>Returns the current time stamp (in milliseconds) for being
326                used in a musical context. You may read this variable from time to time
327                to take time stamps which can be used to calculate the time difference
328                (in milliseconds) which elapsed between them. These timing values are
329                based on the internal sample rate and thus it can safely be used to
330                perform musical timing related tasks in your scripts. Especially
331                your script will also continue to behave correctly when an offline bounce
332                of a song is performed.
333            </td>
334          </tr>
335      </table>      </table>
336    
337      <h3>GigaStudio Format Variables</h3>      <h3>GigaStudio Format Variables</h3>
Legend:
Removed from v.2932  
changed lines
  Added in v.2946
  ViewVC Help
Powered by ViewVC