/[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 2937 by schoenebeck, Mon Jul 11 10:29:16 2016 UTC revision 2944 by schoenebeck, Wed Jul 13 16:52:58 2016 UTC
# Line 140  Line 140 
140        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
141        NKSP realt-time instrument script language.        NKSP realt-time instrument script language.
142      </p>      </p>
143        
144        <h3>Core Language Variables</h3>
145        <p>
146          Most fundamental NKSP built-in variables, independent from any purpose of
147          being used in a sampler.
148        </p>
149        <table>
150          <tr>
151            <th>Variable</th> <th>Description</th>
152          </tr>
153          <tr>
154            <td><code>$KSP_TIMER</code></td>
155            <td>Preserved for compatiblity reasons with KSP, returns the same value
156               as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
157               Note that KSP's <code>reset_ksp_timer()</code> function is not available with
158               NKSP. However when calculating time differences between two time
159               stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
160               function is not required, because the underlying clock does not stop
161               when it reached its value limit (which happens every 71 minutes), instead the clock
162               will automatically restart from zero and the calculated time difference
163               even between such transitions will reflect correct durations.</td>
164          </tr>
165          <tr>
166            <td><code>$NKSP_PERF_TIMER</code></td>
167            <td>Returns the current performance time stamp (in microseconds) of the
168                script running. You may read this variable from time to time to take
169                time stamps which can be used to calculate the time difference
170                (in microseconds) which elapsed between them. A performance time
171                stamp is based on the script's actual CPU execution time. So the
172                internal clock which is used for generating such time stamps is only
173                running forward if the respective script is actually executed by the
174                CPU. Whenever your script is not really executed by the CPU (i.e. because
175                your script got suspended by a wait() call or got forcely suspended due to
176                real-time constraints, or when the entire sampler application got suspended
177                by the OS for other applications or OS tasks) then the underlying internal
178                clock is paused as well.
179                <note class="important">
180                  You should only use this built-in variable for script development
181                  purposes (i.e. for bench marking the performance of your script).
182                  You should <b>not</b> use it with your final production sounds!
183                  It is not appropriate for being used in a musical context, because
184                  when an offline bounce is performed for instance, the musical timing
185                  will be completely unrelated to the CPU execution time. Plus using
186                  this variable may cause audio drop outs on some systems. In a musical
187                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
188                  also safe for offline bounces.
189                </note>
190                <note>
191                  On some systems <code>$NKSP_REAL_TIMER</code> and
192                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
193                  difference between them is not implemented for all systems at the moment.
194                </note>
195            </td>
196          </tr>
197          <tr>
198            <td><code>$NKSP_REAL_TIMER</code></td>
199            <td>Returns the current time stamp in reality (in microseconds). You may
200                read this variable from time to time to take
201                time stamps which can be used to calculate the time difference
202                (in microseconds) which elapsed between them. A "real" time
203                stamp is based on an internal clock which constantly proceeds, so this
204                internal clock also continues counting while your script is either suspended
205                (i.e. because your script got suspended by a wait() call or got forcely
206                suspended due to real-time constraints) and it also continues counting
207                even if the entire sampler application got suspended by the OS (i.e. to
208                execute other applications for multi-tasking or to perform OS tasks).
209                <note class="important">
210                  You should only use this built-in variable for script development
211                  purposes (i.e. for bench marking the performance of your script).
212                  You should <b>not</b> use it with your final production sounds!
213                  It is not appropriate for being used in a musical context, because
214                  when an offline bounce is performed for instance, the musical timing
215                  will be completely unrelated to the CPU execution time. Plus using
216                  this variable may cause audio drop outs on some systems. In a musical
217                  context you should use <code>$ENGINE_UPTIME</code> instead, which is
218                  also safe for offline bounces.
219                </note>
220                <note>
221                  On some systems <code>$NKSP_REAL_TIMER</code> and
222                  <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
223                  difference between them is not implemented for all systems at the moment.
224                </note>
225            </td>
226          </tr>
227        </table>
228    
229      <h3>Common Sampler Variables</h3>      <h3>Common Sampler Variables</h3>
230      <p>      <p>
231        Basic sampler related built-in variables and constants, independent from a        Basic sampler related built-in variables and constants, independent from a
# Line 227  Line 312 
312          <td>Used to select one of the available 28 event groups.          <td>Used to select one of the available 28 event groups.
313          See <code>set_event_mark()</code> for details.</td>          See <code>set_event_mark()</code> for details.</td>
314        </tr>        </tr>
315          <tr>
316            <td><code>$ENGINE_UPTIME</code></td>
317            <td>Returns the current time stamp (in milliseconds) for being
318                used in a musical context. You may read this variable from time to time
319                to take time stamps which can be used to calculate the time difference
320                (in milliseconds) which elapsed between them. These timing values are
321                based on the internal sample rate and thus it can safely be used to
322                perform musical timing related tasks in your scripts. Especially
323                your script will also continue to behave correctly when an offline bounce
324                of a song is performed.
325            </td>
326          </tr>
327      </table>      </table>
328    
329      <h3>GigaStudio Format Variables</h3>      <h3>GigaStudio Format Variables</h3>

Legend:
Removed from v.2937  
changed lines
  Added in v.2944

  ViewVC Help
Powered by ViewVC