reference/functions/nksp_event_status_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>event_status() function</title>
    <meta name="description" content="Returns the current status of a note.">
  </head>
  <body>
    <h1>event_status()</h1>
    <p>
      Checks and returns the current status of the requested note. You can use
      this function to check if a note is still "alive". A note is considered
      "alive" as long as there are still active voices associated with it, which
      might for example still be the case even long time after the respective
      note's key had been released by the musician (i.e. because the voice uses
      a very long release envelope stage).
    </p>
    <p>
      If you are rather just interested whether a certain note key is currently
      pressed down, then you can read the built-in array variable
      <code lang="nksp">%KEY_DOWN[]</code> instead.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
event_status(??note??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??note??</code></td>
        <td>Note ID Number</td>
        <td>Status of this note will be checked.<br>
            [required]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <p>
      Returns either <code>$EVENT_STATUS_INACTIVE</code> if the requested note
      is already dead and gone, or <code>$EVENT_STATUS_NOTE_QUEUE</code> if
      the note is still alive.
    </p>
    <note>
      Even though there are currently just two possible return values,
      <code>$EVENT_STATUS_NOTE_QUEUE</code> is defined as bit flag though, and since
      other bit flags might be added in future you should only compare bitwise with
      <code>$EVENT_STATUS_NOTE_QUEUE</code>. See example below.
    </note>

    <h3>Examples</h3>
    <p>
      The following example shows a simple stuttering effect. The script
      runs in an endless loop and turns down and up the volume all 200ms.
      To stop the endless loop once the respective note died, the return
      value of <code>event_status()</code> is compared with built-in constant
      bit flag <code>$EVENT_STATUS_INACTIVE</code>.
    </p>
    <code>
on note
  while (1)
    wait(200000)
    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }

    wait(200000)
    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
  end while
end on
    </code>
    <p>
      Note: since the built-in constants returned by this function are actually bit flags,
      and since further bit flags might be added in future for this function, the actual
      long-term safe and correct way to check the return value of <code>event_status()</code>
      is a bitwise comparison. So the recommended "correct" way for the example above would
      actually be:
    </p>
    <code>
on note
  while (1)
    wait(200000)
    if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }

    wait(200000)
    if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
  end while
end on
    </code>
    <p>
      In practice however, the first version of this example is much easier to
      read (and write) though, and new bit flags will probably not be added to
      this function in near future. But that's up to you to decide!
    </p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn12.<p>

    <h3>See also</h3>
    <p><code>callback_status()</code><p>

    <note>
      LinuxSampler does currently not support KSP's <code>$EVENT_STATUS_MIDI_QUEUE</code> flag as return value.
    </note>

  </body>
</html>
1	schoenebeck	2936	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>event_status() function</title>
5			<meta name="description" content="Returns the current status of a note.">
6			</head>
7			<body>
8			<h1>event_status()</h1>
9			<p>
10			Checks and returns the current status of the requested note. You can use
11			this function to check if a note is still "alive". A note is considered
12			"alive" as long as there are still active voices associated with it, which
13			might for example still be the case even long time after the respective
14			note's key had been released by the musician (i.e. because the voice uses
15			a very long release envelope stage).
16			</p>
17			<p>
18			If you are rather just interested whether a certain note key is currently
19			pressed down, then you can read the built-in array variable
20			<code lang="nksp">%KEY_DOWN[]</code> instead.
21			</p>
22
23			<h3>Function Prototype</h3>
24			<p/>
25			<code lang="nksp">
26			event_status(??note??)
27			</code>
28
29			<h3>Arguments</h3>
30			<table>
31			<tr>
32			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
33			</tr>
34			<tr>
35			<td><code>??note??</code></td>
36			<td>Note ID Number</td>
37			<td>Status of this note will be checked.<br>
38			[required]</td>
39			</tr>
40			</table>
41
42			<h3>Return Value</h3>
43			<p>
44			Returns either <code>$EVENT_STATUS_INACTIVE</code> if the requested note
45			is already dead and gone, or <code>$EVENT_STATUS_NOTE_QUEUE</code> if
46			the note is still alive.
47			</p>
48			<note>
49			Even though there are currently just two possible return values,
50			<code>$EVENT_STATUS_NOTE_QUEUE</code> is defined as bit flag though, and since
51			other bit flags might be added in future you should only compare bitwise with
52			<code>$EVENT_STATUS_NOTE_QUEUE</code>. See example below.
53			</note>
54
55			<h3>Examples</h3>
56			<p>
57			The following example shows a simple stuttering effect. The script
58			runs in an endless loop and turns down and up the volume all 200ms.
59			To stop the endless loop once the respective note died, the return
60	schoenebeck	3194	value of <code>event_status()</code> is compared with built-in constant
61			bit flag <code>$EVENT_STATUS_INACTIVE</code>.
62	schoenebeck	2936	</p>
63			<code>
64			on note
65			while (1)
66			wait(200000)
67	schoenebeck	3194	if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
68			exit() { note is no longer alive, so stop script here }
69			end if
70			change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
71
72			wait(200000)
73			if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
74			exit() { note is no longer alive, so stop script here }
75			end if
76			change_vol($EVENT_ID, 0) { Increase volume to 0 dB. }
77			end while
78			end on
79			</code>
80			<p>
81			Note: since the built-in constants returned by this function are actually bit flags,
82			and since further bit flags might be added in future for this function, the actual
83			long-term safe and correct way to check the return value of <code>event_status()</code>
84			is a bitwise comparison. So the recommended "correct" way for the example above would
85			actually be:
86			</p>
87			<code>
88			on note
89			while (1)
90			wait(200000)
91	schoenebeck	2936	if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
92	schoenebeck	3194	exit() { note is no longer alive, so stop script here }
93	schoenebeck	2936	end if
94			change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
95
96			wait(200000)
97			if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
98	schoenebeck	3194	exit() { note is no longer alive, so stop script here }
99	schoenebeck	2936	end if
100			change_vol($EVENT_ID, 0) { Increase volume to 0 dB. }
101			end while
102			end on
103			</code>
104	schoenebeck	3194	<p>
105			In practice however, the first version of this example is much easier to
106			read (and write) though, and new bit flags will probably not be added to
107			this function in near future. But that's up to you to decide!
108			</p>
109	schoenebeck	2936
110	schoenebeck	3196	<h3>Availability</h3>
111	schoenebeck	2936	<p>Since LinuxSampler 2.0.0.svn12.<p>
112
113	schoenebeck	3297	<h3>See also</h3>
114			<p><code>callback_status()</code><p>
115
116	schoenebeck	2936	<note>
117			LinuxSampler does currently not support KSP's <code>$EVENT_STATUS_MIDI_QUEUE</code> flag as return value.
118			</note>
119
120			</body>
121			</html>