7 |
<body> |
<body> |
8 |
<h1>wait()</h1> |
<h1>wait()</h1> |
9 |
<p> |
<p> |
10 |
Suspends / pauses the current event handler instance for the requested |
Suspends / pauses execution of the current event handler instance for the requested |
11 |
amount of microseconds. |
amount of microseconds. The paused event handler instance can also be resumed before |
12 |
|
the requested amount times elapsed by calling <code lang="nksp">stop_wait()</code> from another |
13 |
|
event handler instance. |
14 |
</p> |
</p> |
15 |
|
<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 |
|
<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 |
<h3>Function Prototype</h3> |
<h3>Function Prototype</h3> |
29 |
<p/> |
<p/> |
30 |
<code> |
<code lang="nksp"> |
31 |
wait(??duration-us??) |
wait(??duration-us??) |
32 |
</code> |
</code> |
33 |
|
|
39 |
<tr> |
<tr> |
40 |
<td><code>??duration-us??</code></td> |
<td><code>??duration-us??</code></td> |
41 |
<td>Integer Number</td> |
<td>Integer Number</td> |
42 |
<td>Amount of microseconds to pause execution.<br> |
<td>Positive (non zero) amount of microseconds to pause execution.<br> |
43 |
[required]</td> |
[required]</td> |
44 |
</tr> |
</tr> |
45 |
</table> |
</table> |
48 |
<p>None.</p> |
<p>None.</p> |
49 |
|
|
50 |
<h3>Examples</h3> |
<h3>Examples</h3> |
51 |
<p/> |
<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 |
<code> |
<code> |
58 |
on init |
on init |
59 |
{ The amount of notes to play } |
{ The amount of notes to play } |
87 |
end on |
end on |
88 |
</code> |
</code> |
89 |
|
|
90 |
<note class="important"> |
<note> |
91 |
Using the <code>wait()</code> function can lead to concurrency issues with |
Using the <code>wait()</code> function can lead to concurrency issues with |
92 |
regular variables, which are global variables by default. You might need |
regular variables, which are global variables by default. You might need |
93 |
to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a> |
to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a> |
94 |
in such cases. |
in such cases. |
95 |
</note> |
</note> |
96 |
|
|
97 |
<note class="important"> |
<note> |
98 |
The <code>wait()</code> function is not fully implemented in LinuxSampler |
You need at least LinuxSampler 2.0.0.svn2 or higher for the |
99 |
yet. Currently a <code>wait()</code> function call suspends execution, |
<code>wait()</code> function to fully work as expected. Versions |
100 |
but since the respective scheduler code is yet missing in LinuxSampler, |
of LinuxSampler older than that will not resume the script at the |
101 |
the script will automatically be resumed with the next audio fragment |
requested amount of time, instead those older version will resume |
102 |
cycle. So effectively a <code>wait()</code> call will pause your script |
the script always at the beginning of the next audio fragment |
103 |
for a few miliseconds with LinuxSampler right now, no matter which |
cycle. So effectively a <code>wait()</code> call with a LinuxSampler |
104 |
function argument you provided. Hopefully this will be implemented soon |
version older than 2.0.0.svn2 will pause your script for a few |
105 |
though. |
miliseconds, no matter which function argument you provided. |
106 |
</note> |
</note> |
107 |
|
|
108 |
</body> |
</body> |