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 |
<p>None.</p> |
54 |
|
55 |
<h3>Examples</h3> |
56 |
<p> |
57 |
The following example implements two "exclusive" keyboard zones with a |
58 |
split point at key <code>36</code>. The script enforces that only |
59 |
notes of either one of the two keyboard zones may play at the same time. |
60 |
So for example if you start playing notes left of the split point, all |
61 |
sounds play as usual. Now however, as soon as you hit a note on the |
62 |
right side of the split point, it will cause all notes left of the split |
63 |
point to be released immediately. |
64 |
</p> |
65 |
<code> |
66 |
on note |
67 |
if ($EVENT_NOTE < 36) |
68 |
set_event_mark($EVENT_ID, $MARK_1) |
69 |
note_off(by_marks($MARK_2)) |
70 |
else |
71 |
set_event_mark($EVENT_ID, $MARK_2) |
72 |
note_off(by_marks($MARK_1)) |
73 |
end if |
74 |
end on |
75 |
</code> |
76 |
|
77 |
</body> |
78 |
</html> |