Skip to main content

qualia_audio/midi/ump/
scale.rs

1//! MIDI 2.0 default resolution scaling (Min-Center-Max) between bit widths.
2//!
3//! MIDI 1.0 carries 7-bit / 14-bit values; MIDI 2.0 carries 16-bit / 32-bit
4//! values. Up-scaling uses the "bit-repeat" expansion from the MIDI 2.0 UMP
5//! specification so that minimum, center, and maximum map exactly (e.g. 7-bit
6//! `0x40` center scales to the 16-bit center). Down-scaling is a right shift.
7
8/// Scale `value` from `src_bits` up to `dst_bits` using the MIDI 2.0
9/// Min-Center-Max bit-repeat algorithm. `src_bits <= dst_bits <= 32`.
10///
11/// Behaviour matches the MIDI Association reference: 0 maps to 0; values at or
12/// below the source center are a plain left shift; values above center repeat
13/// their low bits into the freed low bits so the maximum saturates.
14pub fn scale_up(value: u32, src_bits: u32, dst_bits: u32) -> u32 {
15    if value == 0 {
16        return 0;
17    }
18    if src_bits >= dst_bits {
19        return value;
20    }
21    if src_bits == 1 {
22        // A single bit set expands to all-ones of the destination width.
23        return (1u32 << dst_bits).wrapping_sub(1);
24    }
25    let scale_bits = dst_bits - src_bits;
26    let mut bit_shifted = value << scale_bits;
27    let src_center = 1u32 << (src_bits - 1);
28    if value <= src_center {
29        return bit_shifted;
30    }
31    // Expanded bit-repeat for the upper half.
32    let repeat_bits = src_bits - 1;
33    let repeat_mask = (1u32 << repeat_bits) - 1;
34    let mut repeat_value = value & repeat_mask;
35    if scale_bits > repeat_bits {
36        repeat_value <<= scale_bits - repeat_bits;
37    } else {
38        repeat_value >>= repeat_bits - scale_bits;
39    }
40    while repeat_value != 0 {
41        bit_shifted |= repeat_value;
42        repeat_value >>= repeat_bits;
43    }
44    bit_shifted
45}
46
47/// Scale `value` from `src_bits` down to `dst_bits` (a right shift by the width
48/// difference). `dst_bits <= src_bits`.
49#[inline]
50pub fn scale_down(value: u32, src_bits: u32, dst_bits: u32) -> u32 {
51    if dst_bits >= src_bits {
52        return value;
53    }
54    value >> (src_bits - dst_bits)
55}
56
57#[cfg(test)]
58mod tests {
59    use super::*;
60
61    #[test]
62    fn velocity_7_to_16_reference_value() {
63        // MIDI 1.0 velocity 100 (0x64) -> 16-bit 0xC924 per the reference algo.
64        assert_eq!(scale_up(100, 7, 16), 0xC924);
65        // ... and back to 100.
66        assert_eq!(scale_down(0xC924, 16, 7), 100);
67    }
68
69    #[test]
70    fn endpoints_and_center() {
71        assert_eq!(scale_up(0, 7, 16), 0);
72        assert_eq!(scale_up(127, 7, 16), 0xFFFF); // max saturates
73        assert_eq!(scale_up(0x40, 7, 16), 0x8000); // center -> center
74    }
75
76    #[test]
77    fn pitch_bend_14_to_32() {
78        // 14-bit center 8192 (0x2000) -> 32-bit center 0x80000000.
79        assert_eq!(scale_up(8192, 14, 32), 0x8000_0000);
80        assert_eq!(scale_down(0x8000_0000, 32, 14), 8192);
81        assert_eq!(scale_up(0, 14, 32), 0);
82        assert_eq!(scale_up(0x3FFF, 14, 32), 0xFFFF_FFFF); // max
83    }
84
85    #[test]
86    fn roundtrip_all_7bit() {
87        for v in 0u32..=127 {
88            let up = scale_up(v, 7, 16);
89            assert_eq!(scale_down(up, 16, 7), v, "roundtrip failed for {v}");
90        }
91    }
92}