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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3607 - (show annotations) (download) (as text)
Wed Sep 18 13:15:21 2019 UTC (13 months, 1 week ago) by schoenebeck
File MIME type: text/html
File size: 3700 byte(s)
- NKSP reference: minor updates and removal of old issues.

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&nbsp;Number&nbsp;or<br>
42 Real&nbsp;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 <h3>See also</h3>
105 <p><code>stop_wait()</code><p>
106
107 </body>
108 </html>

  ViewVC Help
Powered by ViewVC