Struct tune::scala::KbmRoot

pub struct KbmRoot {
    pub origin: PianoKey,
    pub ref_pitch: Pitch,
    pub ref_degree: i32,
}

Defines an absolute horizontal and vertical location of a scale.

KbmRoot is intended to be used in combination with Scl to form a Tuning. The interesting thing about a Tuning is that it offers a bidirectional key-to-pitch mapping. This means it is possible to find the best matching PianoKey for a given Pitch input. The pitch input can be a continuous value, e.g. the location of a mouse pointer.

In order to enable invertibility the mapping described by KbmRoot is linear. In other words, the keyboard mapping degree and the scale degree are the same number. If the mapping is required to be non-linear KbmRoot needs to be surrounded by the more general Kbm struct.

Fields

origin: PianoKey

The PianoKey that maps to degree 0 of the keyboard mapping. If a Kbm surrounding is used with the first entry being n, origin maps to scale degree n.

ref_pitch: Pitch

A Pitch that is guaranteed to be present in a Tuning but which might be skipped in the KeyboardMapping spanned by the Kbm surrounding.

ref_degree: i32

The scale degree for which ref_pitch is given as a reference.

Implementations

impl KbmRoot

pub fn shift_origin_by(self, num_degrees: i32) -> Self

Shifts the origin of a scale by num_degrees conserving the scale’s vertical location.

Examples

let kbm_root =  KbmRoot {
    origin: PianoKey::from_midi_number(67),
    ref_pitch: Pitch::from_hz(432.0),
    ref_degree: 2,
};

assert_eq!(
    kbm_root.shift_origin_by(-7),
    KbmRoot {
        origin: PianoKey::from_midi_number(60),
        ref_pitch: Pitch::from_hz(432.0),
        ref_degree: 9,
    }
);

pub fn to_kbm(self) -> Kbm

Creates a quasi-equivalent Kbm surrounding which can be exported.

Examples

let kbm_root = KbmRoot::from(Note::from_midi_number(62));
let kbm = kbm_root.to_kbm();

assert_eq!(kbm.kbm_root(), kbm_root);
assert_eq!(kbm.range(), PianoKey::from_midi_number(0)..PianoKey::from_midi_number(128));
assert_eq!(kbm.formal_octave(), 1);
assert_eq!(kbm.num_items(), 1);
assert_eq!(kbm.scale_degree_of(PianoKey::from_midi_number(61)), Some(-1));
assert_eq!(kbm.scale_degree_of(PianoKey::from_midi_number(62)), Some(0));
assert_eq!(kbm.scale_degree_of(PianoKey::from_midi_number(63)), Some(1));

let exported = kbm.export();

Trait Implementations

impl Clone for KbmRoot

fn clone(&self) -> KbmRoot

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for KbmRoot

impl Debug for KbmRoot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<N: PitchedNote> From<N> for KbmRoot

fn from(note: N) -> Self

Performs the conversion.

impl FromStr for KbmRoot

type Err = String

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq<KbmRoot> for KbmRoot

fn eq(&self, other: &KbmRoot) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &KbmRoot) -> bool

This method tests for !=.

impl StructuralPartialEq for KbmRoot