same_region()

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.

Function Prototype

same_region(??key1??, ??key2??)

Arguments

Argument Name	Data Type	Description
`??key1??`	Integer Number	Note number of 1st key to be checked. [required]
`??key2??`	Integer Number	Note number of 2nd key to be checked. [required]

Return Value

Data Type Description

Integer Number Relationship of the two keys:
0: Both keys have a region, however they are two different regions, which also and don't overlap each other.
1: Both keys have a region and it is exactly the same region.
2: Both keys have a region, which are two different regions, and which are overlapping each other though.
3: ??key1?? has a region, ??key2?? does not have any region.
4: ??key1?? does not have any region, ??key2?? has a region.
5: ??key1?? and ??key2?? both don't have any region.

Data Type	Description
Integer Number	Relationship of the two keys: `0`: Both keys have a region, however they are two different regions, which also and don't overlap each other. `1`: Both keys have a region and it is exactly the same region. `2`: Both keys have a region, which are two different regions, and which are overlapping each other though. `3`: `??key1??` has a region, `??key2??` does not have any region. `4`: `??key1??` does not have any region, `??key2??` has a region. `5`: `??key1??` and `??key2??` both don't have any region.

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

Examples

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.


on init
  declare const $NO_REGION := 5
end on

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

Availability

Since LinuxSampler 2.0.0.svn53.

This function is currently only available for the GigaStudio/Gigasampler format engine.

Furthermore this function exists only with NKSP, it is not available with KSP.