reference/functions/nksp_by_marks_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>by_marks() function</title>
    <meta name="description" content="Returns all events of an event group.">
  </head>
  <body>
    <h1>by_marks()</h1>
    <p>
      Returns an array of event IDs of all events being members of the requested event group.
      These are events which had previously been added to that event group 
      by calling the <code lang="nksp">set_event_mark()</code> function.
      The <code>by_marks()</code> function acts as placeholder for all event
      IDs of the particular group and allows to manipulate a set of events
      this way with only one call.
    </p>
    <p>
      After notes died, this function may still return those recently died
      notes' IDs for a certain while, that means for example that
      <code lang="nksp">num_elements(by_marks($MARK_1))</code> may return a higher
      value than the actual amount of currently active notes. This does not
      mean that you have to remove dead notes from their groups by calling
      <code lang="nksp">delete_event_mark()</code>. The sampler automatically
      removes dead notes from their groups automatically after a certain
      amount of time, and in practice this lag does not have any negative impact
      on using this function, since all built-in functions automatically 
      detect invalid IDs and are automatically ignoring IDs of dead notes.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code>
by_marks(??group-id??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??group-id??</code></td>
        <td>Event Group ID Number</td>
        <td>Event group that shall be referenced. You should pass one
            of the built-in constant variables <code>$MARK_1</code> to
            <code>$MARK_28</code> for this argument to select one of the
            28 available groups.<br>
            [required]</td>
      </tr>
    </table>
    
    <h3>Return Value</h3>
    <p>None.</p>
    
    <h3>Examples</h3>
    <p>
      The following example implements two "exclusive" keyboard zones with a
      split point at key <code>36</code>. The script enforces that only
      notes of either one of the two keyboard zones may play at the same time.
      So for example if you start playing notes left of the split point, all
      sounds play as usual. Now however, as soon as you hit a note on the
      right side of the split point, it will cause all notes left of the split
      point to be released immediately.
    </p>
    <code>
on note
  if ($EVENT_NOTE < 36)
    set_event_mark($EVENT_ID, $MARK_1)
    note_off(by_marks($MARK_2))
  else
    set_event_mark($EVENT_ID, $MARK_2)
    note_off(by_marks($MARK_1))
  end if
end on
    </code>

  </body>
</html>
1	schoenebeck	2732	<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	schoenebeck	2742	by calling the <code lang="nksp">set_event_mark()</code> function.
13	schoenebeck	2732	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	schoenebeck	3059	<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	schoenebeck	2732
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	schoenebeck	3240	<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	schoenebeck	2732	<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>