Skip to main content

qualia_audio/midi/mpe/
zone.rs

1//! MPE zone configuration — a master channel plus a range of member channels.
2//!
3//! MIDI Polyphonic Expression splits the 16 channels into a **zone**: one master
4//! channel carries zone-wide messages, and a contiguous block of **member**
5//! channels each host a single sounding note so per-note pitch-bend, pressure,
6//! and timbre don't collide. The **lower** zone uses master channel 1 (index 0)
7//! with members counting up from channel 2; the **upper** zone uses master
8//! channel 16 (index 15) with members counting down. Channels here are 0-indexed
9//! (`0..=15`). Allocation-free.
10
11use crate::types::AudioError;
12
13/// An MPE zone: the master channel and the inclusive member-channel range.
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub struct MpeZone {
16    /// Master channel index (0 for the lower zone, 15 for the upper zone).
17    pub master_channel: u8,
18    /// Lowest member channel index (inclusive).
19    pub member_low: u8,
20    /// Highest member channel index (inclusive).
21    pub member_high: u8,
22}
23
24impl MpeZone {
25    /// Build a **lower** zone: master = channel 1 (index 0), `member_count`
26    /// members counting up from channel 2 (index 1).
27    ///
28    /// Errors if `member_count` is 0 or would exceed the 15 available member
29    /// channels.
30    pub fn lower(member_count: u8) -> Result<Self, AudioError> {
31        if member_count == 0 || member_count > 15 {
32            return Err(AudioError::InvalidParameter);
33        }
34        Ok(Self {
35            master_channel: 0,
36            member_low: 1,
37            member_high: member_count,
38        })
39    }
40
41    /// Build an **upper** zone: master = channel 16 (index 15), `member_count`
42    /// members counting down from channel 15 (index 14).
43    ///
44    /// Errors if `member_count` is 0 or would exceed the 15 available member
45    /// channels.
46    pub fn upper(member_count: u8) -> Result<Self, AudioError> {
47        if member_count == 0 || member_count > 15 {
48            return Err(AudioError::InvalidParameter);
49        }
50        Ok(Self {
51            master_channel: 15,
52            member_low: 15 - member_count,
53            member_high: 14,
54        })
55    }
56
57    /// Number of member channels in the zone.
58    #[inline]
59    pub fn member_count(&self) -> u8 {
60        self.member_high - self.member_low + 1
61    }
62
63    /// Whether `channel` is a member (note-bearing) channel of this zone.
64    #[inline]
65    pub fn is_member(&self, channel: u8) -> bool {
66        channel >= self.member_low && channel <= self.member_high
67    }
68
69    /// Whether `channel` is this zone's master channel.
70    #[inline]
71    pub fn is_master(&self, channel: u8) -> bool {
72        channel == self.master_channel
73    }
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79
80    #[test]
81    fn lower_zone_layout() {
82        let z = MpeZone::lower(7).unwrap();
83        assert_eq!(z.master_channel, 0);
84        assert_eq!(z.member_low, 1);
85        assert_eq!(z.member_high, 7);
86        assert_eq!(z.member_count(), 7);
87        assert!(z.is_master(0));
88        assert!(z.is_member(1) && z.is_member(7));
89        assert!(!z.is_member(0) && !z.is_member(8));
90    }
91
92    #[test]
93    fn upper_zone_layout() {
94        let z = MpeZone::upper(7).unwrap();
95        assert_eq!(z.master_channel, 15);
96        assert_eq!(z.member_low, 8);
97        assert_eq!(z.member_high, 14);
98        assert_eq!(z.member_count(), 7);
99        assert!(z.is_master(15));
100        assert!(z.is_member(8) && z.is_member(14));
101        assert!(!z.is_member(15));
102    }
103
104    #[test]
105    fn rejects_bad_counts() {
106        assert!(MpeZone::lower(0).is_err());
107        assert!(MpeZone::lower(16).is_err());
108        assert!(MpeZone::upper(0).is_err());
109    }
110}