reference/functions/nksp_wait_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>wait() function</title>
    <meta name="description" content="Pauses execution for a certain amount of time.">
  </head>
  <body>
    <h1>wait()</h1>
    <p>
      Suspends / pauses the current event handler instance for the requested
      amount of microseconds.
    </p>
    
    <h3>Function Prototype</h3>
    <p/>
    <code>
wait(??duration-us??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??duration-us??</code></td>
        <td>Integer Number</td>
        <td>Amount of microseconds to pause execution.<br>
            [required]</td>
      </tr>
    </table>
    
    <h3>Return Value</h3>
    <p>None.</p>
    
    <h3>Examples</h3>
    <p/>
    <code>
on init
  { The amount of notes to play }
  declare const $delayNotes := 4
  { Tempo with which the new notes will follow the orignal note }
  declare const $bpm := 90
  { Convert BPM to microseconds (duration between the notes) }
  declare const $delayMicroSeconds := 60 * 1000000 / $bpm
  { Just a working variable for being used with the while loop below }
  declare polyphonic $i
  { For each successive note we trigger, we will reduce the velocity a bit}
  declare polyphonic $velocity
end on

on note
  { First initialize the variable $i with 4 each time we enter this event
    handler, because each time we executed this handler, the variable will be 0 }
  $i := $delayNotes

  { Loop which will be executed 4 times in a row }
  while ($i)
    { Calculate the velocity for the next note being triggered }
    $velocity := 127 * $i / ($delayNotes + 1)
    { Suspend this script for a short moment ... }
    wait($delayMicroSeconds)
    { ... and after that short break, trigger a new note. }
    play_note($EVENT_NOTE, $velocity)
    { Decrement loop counter $i by one }
    $i := $i - 1
  end while
end on
    </code>
    
    <note class="important">
      Using the <code>wait()</code> function can lead to concurrency issues with
      regular variables, which are global variables by default. You might need
      to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a>
      in such cases.
    </note>
    
    <note class="important">
      The <code>wait()</code> function is not fully implemented in LinuxSampler
      yet. Currently a <code>wait()</code> function call suspends execution,
      but since the respective scheduler code is yet missing in LinuxSampler,
      the script will automatically be resumed with the next audio fragment
      cycle. So effectively a <code>wait()</code> call will pause your script
      for a few miliseconds with LinuxSampler right now, no matter which
      function argument you provided. Hopefully this will be implemented soon
      though.
    </note>

  </body>
</html>
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 the current event handler instance for the requested
11	amount of microseconds.
12	</p>
13
14	<h3>Function Prototype</h3>
15	<p/>
16	<code>
17	wait(??duration-us??)
18	</code>
19
20	<h3>Arguments</h3>
21	<table>
22	<tr>
23	<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
24	</tr>
25	<tr>
26	<td><code>??duration-us??</code></td>
27	<td>Integer Number</td>
28	<td>Amount of microseconds to pause execution.<br>
29	[required]</td>
30	</tr>
31	</table>
32
33	<h3>Return Value</h3>
34	<p>None.</p>
35
36	<h3>Examples</h3>
37	<p/>
38	<code>
39	on init
40	{ The amount of notes to play }
41	declare const $delayNotes := 4
42	{ Tempo with which the new notes will follow the orignal note }
43	declare const $bpm := 90
44	{ Convert BPM to microseconds (duration between the notes) }
45	declare const $delayMicroSeconds := 60 * 1000000 / $bpm
46	{ Just a working variable for being used with the while loop below }
47	declare polyphonic $i
48	{ For each successive note we trigger, we will reduce the velocity a bit}
49	declare polyphonic $velocity
50	end on
51
52	on note
53	{ First initialize the variable $i with 4 each time we enter this event
54	handler, because each time we executed this handler, the variable will be 0 }
55	$i := $delayNotes
56
57	{ Loop which will be executed 4 times in a row }
58	while ($i)
59	{ Calculate the velocity for the next note being triggered }
60	$velocity := 127 * $i / ($delayNotes + 1)
61	{ Suspend this script for a short moment ... }
62	wait($delayMicroSeconds)
63	{ ... and after that short break, trigger a new note. }
64	play_note($EVENT_NOTE, $velocity)
65	{ Decrement loop counter $i by one }
66	$i := $i - 1
67	end while
68	end on
69	</code>
70
71	<note class="important">
72	Using the <code>wait()</code> function can lead to concurrency issues with
73	regular variables, which are global variables by default. You might need
74	to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a>
75	in such cases.
76	</note>
77
78	<note class="important">
79	The <code>wait()</code> function is not fully implemented in LinuxSampler
80	yet. Currently a <code>wait()</code> function call suspends execution,
81	but since the respective scheduler code is yet missing in LinuxSampler,
82	the script will automatically be resumed with the next audio fragment
83	cycle. So effectively a <code>wait()</code> call will pause your script
84	for a few miliseconds with LinuxSampler right now, no matter which
85	function argument you provided. Hopefully this will be implemented soon
86	though.
87	</note>
88
89	</body>
90	</html>