/[svn]/doc/docbase/instrument_scripts/nksp/reference/functions/nksp_wait_function.html
ViewVC logotype

Annotation of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_wait_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3239 - (hide annotations) (download) (as text)
Sun May 28 16:50:11 2017 UTC (6 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 4027 byte(s)
- NKSP: Added description to example code of wait() function.

1 schoenebeck 2732 <html>
2     <head>
3     <meta name="author" content="Christian Schoenebeck">
4     <title>wait() function</title>
5     <meta name="description" content="Pauses execution for a certain amount of time.">
6     </head>
7     <body>
8     <h1>wait()</h1>
9     <p>
10 schoenebeck 2949 Suspends / pauses execution of the current event handler instance for the requested
11     amount of microseconds. The paused event handler instance can also be resumed before
12 schoenebeck 2950 the requested amount times elapsed by calling <code lang="nksp">stop_wait()</code> from another
13 schoenebeck 2949 event handler instance.
14 schoenebeck 2732 </p>
15 schoenebeck 2973 <p>
16     The <code>??duration-us??</code> argument must neither
17     be negative nor zero, otherwise script execution will be aborted, because this
18     is a common indication of bugs in scripts which could potentially lead to
19     real-time instability or worse scenarios otherwise.
20     </p>
21 schoenebeck 2949 <note>
22     If the even handler instance's built-in variable <code>$NKSP_IGNORE_WAIT</code>
23     reflects <code>1</code> then all calls to <code>wait()</code> will be ignored.
24     This might for example be the case when <code>stop_wait()</code> with
25     <code>1</code> being passed to the 2nd argument of that function.
26     </note>
27    
28 schoenebeck 2732 <h3>Function Prototype</h3>
29     <p/>
30 schoenebeck 2742 <code lang="nksp">
31 schoenebeck 2732 wait(??duration-us??)
32     </code>
33    
34     <h3>Arguments</h3>
35     <table>
36     <tr>
37     <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
38     </tr>
39     <tr>
40     <td><code>??duration-us??</code></td>
41     <td>Integer Number</td>
42 schoenebeck 2973 <td>Positive (non zero) amount of microseconds to pause execution.<br>
43 schoenebeck 2732 [required]</td>
44     </tr>
45     </table>
46    
47     <h3>Return Value</h3>
48     <p>None.</p>
49    
50     <h3>Examples</h3>
51 schoenebeck 3239 <p>
52     The following example resembles a simple delay effect. For each note
53     being triggered by the musician, the script launches additional notes,
54     each one of such additional successive notes with a more and more reduced
55     volume.
56     </p>
57 schoenebeck 2732 <code>
58     on init
59     { The amount of notes to play }
60     declare const $delayNotes := 4
61     { Tempo with which the new notes will follow the orignal note }
62     declare const $bpm := 90
63     { Convert BPM to microseconds (duration between the notes) }
64     declare const $delayMicroSeconds := 60 * 1000000 / $bpm
65     { Just a working variable for being used with the while loop below }
66     declare polyphonic $i
67     { For each successive note we trigger, we will reduce the velocity a bit}
68     declare polyphonic $velocity
69     end on
70    
71     on note
72     { First initialize the variable $i with 4 each time we enter this event
73     handler, because each time we executed this handler, the variable will be 0 }
74     $i := $delayNotes
75    
76     { Loop which will be executed 4 times in a row }
77     while ($i)
78     { Calculate the velocity for the next note being triggered }
79     $velocity := 127 * $i / ($delayNotes + 1)
80     { Suspend this script for a short moment ... }
81     wait($delayMicroSeconds)
82     { ... and after that short break, trigger a new note. }
83     play_note($EVENT_NOTE, $velocity)
84     { Decrement loop counter $i by one }
85     $i := $i - 1
86     end while
87     end on
88     </code>
89    
90 schoenebeck 2872 <note>
91 schoenebeck 2732 Using the <code>wait()</code> function can lead to concurrency issues with
92     regular variables, which are global variables by default. You might need
93     to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a>
94     in such cases.
95     </note>
96    
97 schoenebeck 2872 <note>
98     You need at least LinuxSampler 2.0.0.svn2 or higher for the
99     <code>wait()</code> function to fully work as expected. Versions
100     of LinuxSampler older than that will not resume the script at the
101     requested amount of time, instead those older version will resume
102     the script always at the beginning of the next audio fragment
103     cycle. So effectively a <code>wait()</code> call with a LinuxSampler
104     version older than 2.0.0.svn2 will pause your script for a few
105     miliseconds, no matter which function argument you provided.
106 schoenebeck 2732 </note>
107    
108     </body>
109     </html>

  ViewVC Help
Powered by ViewVC