Legato Base¶
Legato Base
Import¶
import "_IVLS/std-library/nodes/voice-logics/legato/legato-base.ksp"Node: Stl.LegatoBase¶
Uses: Init, PathCancellation
Overview¶
Legato Base
Shared legato voice-tracking data and utilities used by mono and poly legato implementations.
LIBRARY: std-library/nodes/voice-logics/legato
Registers per-voice legato members (vo_src, vo_dest, is_current, registered) via the Voice member extension system and exposes accessor functions and predicates for querying and manipulating legato link state between source and destination voices.
Legato base is included by Stl.Legato and provides the foundation that both Stl.MonoLegato and Stl.PolyLegato build upon.
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.LegatoBase |
Injects legato member fields and initialization data into the Voice data structu... |
Defines¶
| Name | Description |
|---|---|
define legato.check_current(#vo#) |
Returns TRUE if the destination voice of the given voice's legato link is the cu... |
define legato.found(#vo#) |
Returns TRUE if the given voice has an active legato link (both vo_src and vo_de... |
define Stl.Legato += Stl.LegatoBase |
Adds Stl.LegatoBase to the Stl.Legato composition chain. |
define Stl.LegatoInfo.MEMBERS |
Declares the four per-voice legato state members: vo_src, vo_dest, is_current, a... |
define Voice.ADD_INIT += Stl.LegatoInfo.INIT |
Registers per-voice legato initialization values into the Voice ADD_INIT extensi... |
define Voice.ADD_MEMBERS += Stl.LegatoInfo.MEMBERS |
Registers per-voice legato member fields into the Voice ADD_MEMBERS extension po... |
define Voice.validate.legato.is_current(#v#) |
Validates that an is_current value is a valid boolean (FALSE or TRUE). |
define Voice.validate.legato.registered(#v#) |
Validates that a registered value is a valid boolean (FALSE or TRUE). |
define Voice.validate.legato.vo_dest(#v#) |
Validates that a vo_dest value is within the legal range (>= -1). |
define Voice.validate.legato.vo_src(#v#) |
Validates that a vo_src value is within the legal range (>= -1). |
Functions¶
| Name | Description |
|---|---|
legato.get_dest_vo(vo) -> dest |
Returns the destination voice index linked to the given voice. |
legato.get_interval(vo) -> interval |
Returns the semitone interval between the source and destination notes of a lega... |
legato.get_src_vo(vo) -> src |
Returns the source voice index linked to the given voice. |
legato.unlink(vo) |
Clears the vo_src field for the given voice, removing its legato source link. |
Nodes¶
node Stl.LegatoBase¶
Callbacks: Init, PathCancellation
Injects legato member fields and initialization data into the Voice data structure.
Defines¶
define legato.check_current(#vo#)¶
Returns TRUE if the destination voice of the given voice's legato link is the current active legato voice.
| Parameter | Description |
|---|---|
#vo# |
voice index to check |
Post: (boolean) return - TRUE if the destination voice has is_current set to TRUE
define legato.found(#vo#)¶
Returns TRUE if the given voice has an active legato link (both vo_src and vo_dest are set).
| Parameter | Description |
|---|---|
#vo# |
voice index to check |
Post: (boolean) return - TRUE if both vo_src and vo_dest are populated (not -1)
define Stl.Legato += Stl.LegatoBase¶
Adds Stl.LegatoBase to the Stl.Legato composition chain.
define Stl.LegatoInfo.MEMBERS¶
Declares the four per-voice legato state members: vo_src, vo_dest, is_current, and registered.
define Voice.ADD_INIT += Stl.LegatoInfo.INIT¶
Registers per-voice legato initialization values into the Voice ADD_INIT extension point.
define Voice.ADD_MEMBERS += Stl.LegatoInfo.MEMBERS¶
Registers per-voice legato member fields into the Voice ADD_MEMBERS extension point.
define Voice.validate.legato.is_current(#v#)¶
Validates that an is_current value is a valid boolean (FALSE or TRUE).
| Parameter | Description |
|---|---|
#v# |
the value to validate |
Post: (boolean) return - TRUE if the value is valid
define Voice.validate.legato.registered(#v#)¶
Validates that a registered value is a valid boolean (FALSE or TRUE).
| Parameter | Description |
|---|---|
#v# |
the value to validate |
Post: (boolean) return - TRUE if the value is valid
define Voice.validate.legato.vo_dest(#v#)¶
Validates that a vo_dest value is within the legal range (>= -1).
| Parameter | Description |
|---|---|
#v# |
the value to validate |
Post: (boolean) return - TRUE if the value is valid
define Voice.validate.legato.vo_src(#v#)¶
Validates that a vo_src value is within the legal range (>= -1).
| Parameter | Description |
|---|---|
#v# |
the value to validate |
Post: (boolean) return - TRUE if the value is valid
Functions¶
legato.get_dest_vo(vo) -> dest¶
Returns the destination voice index linked to the given voice.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | the voice index whose legato destination is queried |
Returns: dest — the vo_dest value for the given voice, or -1 if no destination is linked
legato.get_interval(vo) -> interval¶
Returns the semitone interval between the source and destination notes of a legato pair.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | the voice index whose legato interval is queried |
Returns: interval — the signed difference (dest note - src note) in semitones
legato.get_src_vo(vo) -> src¶
Returns the source voice index linked to the given voice.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | the voice index whose legato source is queried |
Returns: src — the vo_src value for the given voice, or -1 if no source is linked
legato.unlink(vo)¶
Clears the vo_src field for the given voice, removing its legato source link.
| Parameter | Type | Description |
|---|---|---|
vo |
integer | the voice index to unlink |
Side effects: | Name | Type | Purpose | |------|------|---------| | Voice[vo].legato.vo_src | integer | Set to -1 to remove the legato source reference |
Example¶
// TODO: Add usage example