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> |