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

Annotation of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_event_status_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3297 - (hide annotations) (download) (as text)
Wed Jun 28 10:48:30 2017 UTC (4 years, 1 month ago) by schoenebeck
File MIME type: text/html
File size: 4196 byte(s)
* NKSP: Added function callback_status().
* NKSP: Added built-in constant $CALLBACK_STATUS_QUEUE.
* NKSP: Added built-in constant $CALLBACK_STATUS_RUNNING.
* NKSP: Added built-in constant $CALLBACK_STATUS_TERMINATED.

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>

  ViewVC Help
Powered by ViewVC