reference/functions/nksp_same_region_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>same_region() function</title>
    <meta name="description" content="Check whether two keys are mapped to the same region.">
  </head>
  <body>
    <h1>same_region()</h1>
    <p>
      The key range (or note range if you will) of instruments is assigned to
      one or more keyboard regions. So each "region" is responsible for
      mapping audio samples and synthesis parameters for a certain key range.
      This function takes two keys on the keyboard (as MIDI note number) as
      arguments and checks the region relationship of the two keys, that is if the two
      keys have a region mapped each, and if yes how the relationship of those two
      regions exactly is. So the result value of this function depends on the
      precise regions layout of the currently loaded instrument.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
same_region(??key1??, ??key2??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??key1??</code></td>
        <td>Integer Number</td>
        <td>Note number of 1st key to be checked.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??key2??</code></td>
        <td>Integer Number</td>
        <td>Note number of 2nd key to be checked.<br>
            [required]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <table>
      <tr>
        <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td>Integer Number</td>
        <td>Relationship of the two keys:<br>
            <code>0</code>: Both keys have a region, however they are two different
               regions, which also and don't overlap each other.<br>
            <code>1</code>: Both keys have a region and it is exactly the same region.<br>
            <code>2</code>: Both keys have a region, which are two different regions, and which are overlapping each other though.<br>
            <code>3</code>: <code>??key1??</code> has a region, <code>??key2??</code> does not have any region.<br>
            <code>4</code>: <code>??key1??</code> does not have any region, <code>??key2??</code> has a region.<br>
            <code>5</code>: <code>??key1??</code> and <code>??key2??</code> both don't have any region.
        </td>
      </tr>
    </table>

    <note>
    The GigaStudio/Gigasampler format currently does not officially allow
    overlapping regions. So the designated return value <code>2</code> is
    reserved for such a potential future feature.
    </note>

    <h3>Examples</h3>
    <p>
      Note that it is also indeed valid and useful sometimes to pass the same
      note number to both arguments of this function, which allows you to check
      whether one certain key is mapped to a region.
    </p>
    <code>
on init
  declare const $NO_REGION := 5
end on

on note
  if (same_region($EVENT_NOTE, $EVENT_NOTE) = $NO_REGION)
    message("Key " &amp; $EVENT_NOTE &amp; " does not have any sample mapped. So you won't hear anything!")
  else
    message("Key " &amp; $EVENT_NOTE &amp; " is mapped to a region, and thus you should hear its sample now.")
  end if
end on
    </code>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn53.<p>

    <note class="important">
    This function is currently only available for the GigaStudio/Gigasampler
    format engine.<br>
    <br>
    Furthermore this function exists only with NKSP, it is not available with KSP.
    </note>

  </body>
</html>
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 " & $EVENT_NOTE & " does not have any sample mapped. So you won't hear anything!")
84			else
85			message("Key " & $EVENT_NOTE & " 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>