1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

#![no_std]
mod backends;

pub use backends::AymPrecise;

use core::fmt::Debug;
use num_traits::Num;

/// AY/YM Sound chip register count
pub const AY_REGISTER_COUNT: usize = 14;

/// Samples, returned by `aym` implemnt this trait; It allows to correctly convert
/// the sound sample between different types. e.g.
/// [to_f32](AySample::to_f32)/[to_f64](AySample::to_f64) will always return sample in the
/// correct range `[-1.0; 1.0]`, while for example [to_i8](AySample::to_i8)
/// will return the sound sample in range `[-128; 127]`
pub trait AySample: Num + Copy {
    // Returns sound sample in range `[i8::MIN; i8::MAX]`
    fn to_i8(self) -> i8;
    // Returns sound sample in range `[i16::MIN; i16::MAX]`
    fn to_i16(self) -> i16;
    // Returns sound sample in range `[i32::MIN; i32::MAX]`
    fn to_i32(self) -> i32;
    // Returns sound sample in range `[-1.0; 1.0]`
    fn to_f32(self) -> f32;
    // Returns sound sample in range `[-1.0; 1.0]`
    fn to_f64(self) -> f64;
}

impl AySample for f64 {
    fn to_i8(self) -> i8 {
        (i8::MAX as f64 * self).clamp(i8::MIN as f64, i8::MAX as f64) as i8
    }

    fn to_i16(self) -> i16 {
        (i16::MAX as f64 * self).clamp(i16::MIN as f64, i16::MAX as f64) as i16
    }

    fn to_i32(self) -> i32 {
        (i32::MAX as f64 * self).clamp(i32::MIN as f64, i32::MAX as f64) as i32
    }

    fn to_f32(self) -> f32 {
        self as f32
    }

    fn to_f64(self) -> f64 {
        self
    }
}

/// Represents AY stereo sample with `left` and `right` channel samples
#[derive(Debug)]
pub struct StereoSample<S>
where
    S: AySample + Debug,
{
    pub left: S,
    pub right: S,
}

/// Sound chip type
#[derive(Debug)]
pub enum SoundChip {
    /// AY-3-8910 sound chip
    AY,
    /// YM2149 sound chip
    YM,
}

/// Stereo configuration
///
/// `Both` - Played on both channels
/// `Left` - Played only on left channel
/// `Right` - Played only on right channel
///
/// | Mode | A     | B     | C     |
/// | ---- | ----- | ----- | ----- |
/// | Mono | Both  | Both  | Both  |
/// | ABC  | Left  | Both  | Right |
/// | ACB  | Left  | Right | Both  |
/// | BAC  | Both  | Left  | Right |
/// | BCA  | Right | Left  | Both  |
/// | CAB  | Both  | Right | Left  |
/// | CBA  | Right | Both  | Left  |
#[derive(Debug)]
#[allow(clippy::upper_case_acronyms)]
pub enum AyMode {
    Mono,
    ABC,
    ACB,
    BAC,
    BCA,
    CAB,
    CBA,
}

/// Sound library generation backend.
///
/// Currently is only one backend - [AymPrecise],
pub trait AymBackend: Sized {
    /// Resulting sample type
    type SoundSample: AySample + Debug;

    /// Creates new aym instance.
    ///
    /// `frequency` - frequency of the sound chip in Hz
    /// `sample_rate` - target device sound sample rate
    fn new(chip: SoundChip, mode: AyMode, frequency: usize, sample_rate: usize) -> Self;
    /// Write value to the sound chip register. `address` should be in `[0..AY_REGISTER_COUNT]`
    fn write_register(&mut self, address: u8, value: u8);
    /// Generates next sound sample
    fn next_sample(&mut self) -> StereoSample<Self::SoundSample>;
}