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 execution of the current event handler instance for the requested
      amount of microseconds. The paused event handler instance can also be resumed before
      the requested amount times elapsed by calling <code lang="nksp">stop_wait()</code> from another
      event handler instance.
    </p>
    <note>
      If the even handler instance's built-in variable <code>$NKSP_IGNORE_WAIT</code>
      reflects <code>1</code> then all calls to <code>wait()</code> will be ignored.
      This might for example be the case when <code>stop_wait()</code> with
      <code>1</code> being passed to the 2nd argument of that function.
    </note>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
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>
      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>
      You need at least LinuxSampler 2.0.0.svn2 or higher for the
      <code>wait()</code> function to fully work as expected. Versions
      of LinuxSampler older than that will not resume the script at the
      requested amount of time, instead those older version will resume
      the script always at the beginning of the next audio fragment
      cycle. So effectively a <code>wait()</code> call with a LinuxSampler
      version older than 2.0.0.svn2 will pause your script for a few
      miliseconds, no matter which function argument you provided.
    </note>

  </body>
</html>
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	2949	<note>
16			If the even handler instance's built-in variable <code>$NKSP_IGNORE_WAIT</code>
17			reflects <code>1</code> then all calls to <code>wait()</code> will be ignored.
18			This might for example be the case when <code>stop_wait()</code> with
19			<code>1</code> being passed to the 2nd argument of that function.
20			</note>
21
22	schoenebeck	2732	<h3>Function Prototype</h3>
23			<p/>
24	schoenebeck	2742	<code lang="nksp">
25	schoenebeck	2732	wait(??duration-us??)
26			</code>
27
28			<h3>Arguments</h3>
29			<table>
30			<tr>
31			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
32			</tr>
33			<tr>
34			<td><code>??duration-us??</code></td>
35			<td>Integer Number</td>
36			<td>Amount of microseconds to pause execution.<br>
37			[required]</td>
38			</tr>
39			</table>
40
41			<h3>Return Value</h3>
42			<p>None.</p>
43
44			<h3>Examples</h3>
45			<p/>
46			<code>
47			on init
48			{ The amount of notes to play }
49			declare const $delayNotes := 4
50			{ Tempo with which the new notes will follow the orignal note }
51			declare const $bpm := 90
52			{ Convert BPM to microseconds (duration between the notes) }
53			declare const $delayMicroSeconds := 60 * 1000000 / $bpm
54			{ Just a working variable for being used with the while loop below }
55			declare polyphonic $i
56			{ For each successive note we trigger, we will reduce the velocity a bit}
57			declare polyphonic $velocity
58			end on
59
60			on note
61			{ First initialize the variable $i with 4 each time we enter this event
62			handler, because each time we executed this handler, the variable will be 0 }
63			$i := $delayNotes
64
65			{ Loop which will be executed 4 times in a row }
66			while ($i)
67			{ Calculate the velocity for the next note being triggered }
68			$velocity := 127 * $i / ($delayNotes + 1)
69			{ Suspend this script for a short moment ... }
70			wait($delayMicroSeconds)
71			{ ... and after that short break, trigger a new note. }
72			play_note($EVENT_NOTE, $velocity)
73			{ Decrement loop counter $i by one }
74			$i := $i - 1
75			end while
76			end on
77			</code>
78
79	schoenebeck	2872	<note>
80	schoenebeck	2732	Using the <code>wait()</code> function can lead to concurrency issues with
81			regular variables, which are global variables by default. You might need
82			to use <a href="nksp.html#polyphonic_variables">polyphonic variables</a>
83			in such cases.
84			</note>
85
86	schoenebeck	2872	<note>
87			You need at least LinuxSampler 2.0.0.svn2 or higher for the
88			<code>wait()</code> function to fully work as expected. Versions
89			of LinuxSampler older than that will not resume the script at the
90			requested amount of time, instead those older version will resume
91			the script always at the beginning of the next audio fragment
92			cycle. So effectively a <code>wait()</code> call with a LinuxSampler
93			version older than 2.0.0.svn2 will pause your script for a few
94			miliseconds, no matter which function argument you provided.
95	schoenebeck	2732	</note>
96
97			</body>
98			</html>