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

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_by_marks_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3578 - (show annotations) (download) (as text)
Thu Aug 29 12:13:17 2019 UTC (4 years, 7 months ago) by schoenebeck
File MIME type: text/html
File size: 3078 byte(s)
* NKSP reference: Minor cosmetical corrections.

1 <html>
2 <head>
3 <meta name="author" content="Christian Schoenebeck">
4 <title>by_marks() function</title>
5 <meta name="description" content="Returns all events of an event group.">
6 </head>
7 <body>
8 <h1>by_marks()</h1>
9 <p>
10 Returns an array of event IDs of all events being members of the requested event group.
11 These are events which had previously been added to that event group
12 by calling the <code lang="nksp">set_event_mark()</code> function.
13 The <code>by_marks()</code> function acts as placeholder for all event
14 IDs of the particular group and allows to manipulate a set of events
15 this way with only one call.
16 </p>
17 <p>
18 After notes died, this function may still return those recently died
19 notes' IDs for a certain while, that means for example that
20 <code lang="nksp">num_elements(by_marks($MARK_1))</code> may return a higher
21 value than the actual amount of currently active notes. This does not
22 mean that you have to remove dead notes from their groups by calling
23 <code lang="nksp">delete_event_mark()</code>. The sampler automatically
24 removes dead notes from their groups automatically after a certain
25 amount of time, and in practice this lag does not have any negative impact
26 on using this function, since all built-in functions automatically
27 detect invalid IDs and are automatically ignoring IDs of dead notes.
28 </p>
29
30 <h3>Function Prototype</h3>
31 <p/>
32 <code>
33 by_marks(??group-id??)
34 </code>
35
36 <h3>Arguments</h3>
37 <table>
38 <tr>
39 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
40 </tr>
41 <tr>
42 <td><code>??group-id??</code></td>
43 <td>Event Group ID Number</td>
44 <td>Event group that shall be referenced. You should pass one
45 of the built-in constant variables <code>$MARK_1</code> to
46 <code>$MARK_28</code> for this argument to select one of the
47 28 available groups.<br>
48 [required]</td>
49 </tr>
50 </table>
51
52 <h3>Return Value</h3>
53 <table>
54 <tr>
55 <th>Data Type</th> <th>Description</th>
56 </tr>
57 <tr>
58 <td>Event ID Array</td>
59 <td>Event IDs of requested group.</td>
60 </tr>
61 </table>
62
63 <h3>Examples</h3>
64 <p>
65 The following example implements two "exclusive" keyboard zones with a
66 split point at key <code>36</code>. The script enforces that only
67 notes of either one of the two keyboard zones may play at the same time.
68 So for example if you start playing notes left of the split point, all
69 sounds play as usual. Now however, as soon as you hit a note on the
70 right side of the split point, it will cause all notes left of the split
71 point to be released immediately.
72 </p>
73 <code>
74 on note
75 if ($EVENT_NOTE < 36)
76 set_event_mark($EVENT_ID, $MARK_1)
77 note_off(by_marks($MARK_2))
78 else
79 set_event_mark($EVENT_ID, $MARK_2)
80 note_off(by_marks($MARK_1))
81 end if
82 end on
83 </code>
84
85 </body>
86 </html>

  ViewVC Help
Powered by ViewVC