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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3578 - (hide annotations) (download) (as text)
Thu Aug 29 12:13:17 2019 UTC (10 months, 1 week ago) by schoenebeck
File MIME type: text/html
File size: 3620 byte(s)
* NKSP reference: Minor cosmetical corrections.

1 schoenebeck 3229 <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 schoenebeck 3230 one or more keyboard regions. So each "region" is responsible for
12 schoenebeck 3229 mapping audio samples and synthesis parameters for a certain key range.
13 schoenebeck 3230 This function takes two keys on the keyboard (as MIDI note number) as
14 schoenebeck 3229 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 schoenebeck 3230 <td>Note number of 1st key to be checked.<br>
35 schoenebeck 3229 [required]</td>
36     </tr>
37     <tr>
38     <td><code>??key2??</code></td>
39     <td>Integer Number</td>
40 schoenebeck 3230 <td>Note number of 2nd key to be checked.<br>
41 schoenebeck 3229 [required]</td>
42     </tr>
43     </table>
44    
45     <h3>Return Value</h3>
46     <table>
47     <tr>
48 schoenebeck 3578 <th>Data Type</th> <th>Description</th>
49 schoenebeck 3229 </tr>
50     <tr>
51 schoenebeck 3578 <td>Integer Number</td>
52 schoenebeck 3229 <td>Relationship of the two keys:<br>
53 schoenebeck 3230 <code>0</code>: Both keys have a region, however they are two different
54 schoenebeck 3229 regions, which also and don't overlap each other.<br>
55 schoenebeck 3230 <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 schoenebeck 3229 </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 schoenebeck 3264 <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 schoenebeck 3229
81 schoenebeck 3264 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 schoenebeck 3229 <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 schoenebeck 3233 format engine.<br>
96     <br>
97 schoenebeck 3232 Furthermore this function exists only with NKSP, it is not available with KSP.
98 schoenebeck 3229 </note>
99    
100     </body>
101     </html>

  ViewVC Help
Powered by ViewVC