Struct tune::scala::KbmRoot

pub struct KbmRoot {
    pub ref_key: PianoKey,
    pub ref_pitch: Pitch,
    pub root_offset: 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

ref_key: PianoKey

The PianoKey that maps to degree 0 of the keyboard mapping. If a Kbm surrounding is used with the first entry being n, ref_key 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.

root_offset: i32

The amount by which the scale’s root is displaced wrt. to ref_key.

Implementations

impl KbmRoot

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

Shifts the ref_key of a scale by num_degrees correcting the scale’s vertical location.

Examples

let kbm_root =  KbmRoot {
    ref_key: PianoKey::from_midi_number(67),
    ref_pitch: Pitch::from_hz(432.0),
    root_offset: -2,
};

let shifted = kbm_root.shift_ref_key_by(-7);

assert_eq!(shifted.ref_key, PianoKey::from_midi_number(60));
assert_approx_eq!(shifted.ref_pitch.as_hz(), 288.325409);
assert_eq!(shifted.root_offset, -2);

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.

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

Performs copy-assignment from source.

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

Converts to this type from the input type.

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 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: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for KbmRoot

impl StructuralPartialEq for KbmRoot