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

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_same_region_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: 3620 byte(s)
* NKSP reference: Minor cosmetical corrections.

1 <html>
2 <head>
3 <meta name="author" content="Christian Schoenebeck">
4 <title>same_region() function</title>
5 <meta name="description" content="Check whether two keys are mapped to the same region.">
6 </head>
7 <body>
8 <h1>same_region()</h1>
9 <p>
10 The key range (or note range if you will) of instruments is assigned to
11 one or more keyboard regions. So each "region" is responsible for
12 mapping audio samples and synthesis parameters for a certain key range.
13 This function takes two keys on the keyboard (as MIDI note number) as
14 arguments and checks the region relationship of the two keys, that is if the two
15 keys have a region mapped each, and if yes how the relationship of those two
16 regions exactly is. So the result value of this function depends on the
17 precise regions layout of the currently loaded instrument.
18 </p>
19
20 <h3>Function Prototype</h3>
21 <p/>
22 <code lang="nksp">
23 same_region(??key1??, ??key2??)
24 </code>
25
26 <h3>Arguments</h3>
27 <table>
28 <tr>
29 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
30 </tr>
31 <tr>
32 <td><code>??key1??</code></td>
33 <td>Integer Number</td>
34 <td>Note number of 1st key to be checked.<br>
35 [required]</td>
36 </tr>
37 <tr>
38 <td><code>??key2??</code></td>
39 <td>Integer Number</td>
40 <td>Note number of 2nd key to be checked.<br>
41 [required]</td>
42 </tr>
43 </table>
44
45 <h3>Return Value</h3>
46 <table>
47 <tr>
48 <th>Data Type</th> <th>Description</th>
49 </tr>
50 <tr>
51 <td>Integer Number</td>
52 <td>Relationship of the two keys:<br>
53 <code>0</code>: Both keys have a region, however they are two different
54 regions, which also and don't overlap each other.<br>
55 <code>1</code>: Both keys have a region and it is exactly the same region.<br>
56 <code>2</code>: Both keys have a region, which are two different regions, and which are overlapping each other though.<br>
57 <code>3</code>: <code>??key1??</code> has a region, <code>??key2??</code> does not have any region.<br>
58 <code>4</code>: <code>??key1??</code> does not have any region, <code>??key2??</code> has a region.<br>
59 <code>5</code>: <code>??key1??</code> and <code>??key2??</code> both don't have any region.
60 </td>
61 </tr>
62 </table>
63
64 <note>
65 The GigaStudio/Gigasampler format currently does not officially allow
66 overlapping regions. So the designated return value <code>2</code> is
67 reserved for such a potential future feature.
68 </note>
69
70 <h3>Examples</h3>
71 <p>
72 Note that it is also indeed valid and useful sometimes to pass the same
73 note number to both arguments of this function, which allows you to check
74 whether one certain key is mapped to a region.
75 </p>
76 <code>
77 on init
78 declare const $NO_REGION := 5
79 end on
80
81 on note
82 if (same_region($EVENT_NOTE, $EVENT_NOTE) = $NO_REGION)
83 message("Key " &amp; $EVENT_NOTE &amp; " does not have any sample mapped. So you won't hear anything!")
84 else
85 message("Key " &amp; $EVENT_NOTE &amp; " is mapped to a region, and thus you should hear its sample now.")
86 end if
87 end on
88 </code>
89
90 <h3>Availability</h3>
91 <p>Since LinuxSampler 2.0.0.svn53.<p>
92
93 <note class="important">
94 This function is currently only available for the GigaStudio/Gigasampler
95 format engine.<br>
96 <br>
97 Furthermore this function exists only with NKSP, it is not available with KSP.
98 </note>
99
100 </body>
101 </html>

  ViewVC Help
Powered by ViewVC