ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 3240 - (hide annotations) (download) (as text)
Sun May 28 16:58:53 2017 UTC (6 years, 9 months ago) by schoenebeck
File MIME type: text/html
File size: 2897 byte(s)
- NKSP: Added description for example code of by_marks() function.

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>
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>
52     <h3>Return Value</h3>
53     <p>None.</p>
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>
77     </body>
78     </html>

  ViewVC Help
Powered by ViewVC