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 bitwise with built-in constant bit flag
      <code>$EVENT_STATUS_NOTE_QUEUE</code>.
    </p>
    <code>
on note
  while (1)
    wait(200000)
    if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
      exit()
    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()
    end if
    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
  end while
end on
    </code>

    <h3>Availabilty</h3>
    <p>Since LinuxSampler 2.0.0.svn12.<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			value of <code>event_status()</code> is compared bitwise with built-in constant bit flag
61			<code>$EVENT_STATUS_NOTE_QUEUE</code>.
62			</p>
63			<code>
64			on note
65			while (1)
66			wait(200000)
67			if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
68			exit()
69			end if
70			change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
71
72			wait(200000)
73			if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
74			exit()
75			end if
76			change_vol($EVENT_ID, 0) { Increase volume to 0 dB. }
77			end while
78			end on
79			</code>
80
81			<h3>Availabilty</h3>
82			<p>Since LinuxSampler 2.0.0.svn12.<p>
83
84			<note>
85			LinuxSampler does currently not support KSP's <code>$EVENT_STATUS_MIDI_QUEUE</code> flag as return value.
86			</note>
87
88			</body>
89			</html>