1 |
<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 |
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 |
the requested amount times elapsed by calling <code lang="nksp">stop_wait()</code> from another |
13 |
event handler instance. |
14 |
</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 event 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> |
29 |
<p/> |
30 |
<code lang="nksp"> |
31 |
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 or<br> |
42 |
Real Number</td> |
43 |
<td>Positive (non zero) amount of microseconds to pause execution.<br> |
44 |
[required]</td> |
45 |
</tr> |
46 |
</table> |
47 |
|
48 |
<h3>Return Value</h3> |
49 |
<p>None.</p> |
50 |
|
51 |
<h3>Remarks</h3> |
52 |
<p> |
53 |
This functions optionally accepts <code>s</code> as standard unit |
54 |
for its argument <code>??duration-us??</code>. |
55 |
</p> |
56 |
|
57 |
<h3>Examples</h3> |
58 |
<p> |
59 |
The following example resembles a simple delay effect. For each note |
60 |
being triggered by the musician, the script launches additional notes, |
61 |
each one of such additional successive notes with a more and more reduced |
62 |
volume. |
63 |
</p> |
64 |
<code> |
65 |
on init |
66 |
{ The amount of notes to play } |
67 |
declare const $delayNotes := 4 |
68 |
{ Tempo with which the new notes will follow the orignal note } |
69 |
declare const $bpm := 90 |
70 |
{ Convert BPM to microseconds (duration between the notes) } |
71 |
declare const $delayMicroSeconds := 60 * 1000000 / $bpm |
72 |
{ Just a working variable for being used with the while loop below } |
73 |
declare polyphonic $i |
74 |
{ For each successive note we trigger, we will reduce the velocity a bit} |
75 |
declare polyphonic $velocity |
76 |
end on |
77 |
|
78 |
on note |
79 |
{ First initialize the variable $i with 4 each time we enter this event |
80 |
handler, because each time we executed this handler, the variable will be 0 } |
81 |
$i := $delayNotes |
82 |
|
83 |
{ Loop which will be executed 4 times in a row } |
84 |
while ($i) |
85 |
{ Calculate the velocity for the next note being triggered } |
86 |
$velocity := 127 * $i / ($delayNotes + 1) |
87 |
{ Suspend this script for a short moment ... } |
88 |
wait($delayMicroSeconds) |
89 |
{ ... and after that short break, trigger a new note. } |
90 |
play_note($EVENT_NOTE, $velocity) |
91 |
{ Decrement loop counter $i by one } |
92 |
$i := $i - 1 |
93 |
end while |
94 |
end on |
95 |
</code> |
96 |
|
97 |
<note> |
98 |
Using the <code>wait()</code> function can lead to concurrency issues with |
99 |
regular variables, which are global variables by default. You might need |
100 |
to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a> |
101 |
in such cases. |
102 |
</note> |
103 |
|
104 |
<note> |
105 |
You need at least LinuxSampler 2.0.0.svn2 or higher for the |
106 |
<code>wait()</code> function to fully work as expected. Versions |
107 |
of LinuxSampler older than that will not resume the script at the |
108 |
requested amount of time, instead those older version will resume |
109 |
the script always at the beginning of the next audio fragment |
110 |
cycle. So effectively a <code>wait()</code> call with a LinuxSampler |
111 |
version older than 2.0.0.svn2 will pause your script for a few |
112 |
miliseconds, no matter which function argument you provided. |
113 |
</note> |
114 |
|
115 |
<h3>See also</h3> |
116 |
<p><code>stop_wait()</code><p> |
117 |
|
118 |
</body> |
119 |
</html> |