Trait Ym2149Backend 

pub trait Ym2149Backend: Send {
    // Required methods
    fn new() -> Self
       where Self: Sized;
    fn with_clocks(master_clock: u32, sample_rate: u32) -> Self
       where Self: Sized;
    fn reset(&mut self);
    fn write_register(&mut self, addr: u8, value: u8);
    fn read_register(&self, addr: u8) -> u8;
    fn load_registers(&mut self, regs: &[u8; 16]);
    fn dump_registers(&self) -> [u8; 16];
    fn clock(&mut self);
    fn get_sample(&self) -> f32;
    fn get_channel_outputs(&self) -> (f32, f32, f32);
    fn set_channel_mute(&mut self, channel: usize, mute: bool);
    fn is_channel_muted(&self, channel: usize) -> bool;
    fn set_color_filter(&mut self, enabled: bool);

    // Provided methods
    fn generate_samples(&mut self, count: usize) -> Vec<f32> { ... }
    fn generate_samples_into(&mut self, buffer: &mut [f32]) { ... }
    fn generate_samples_with_channels(
        &mut self,
        buffer: &mut [f32],
        channel_outputs: &mut [[f32; 3]],
    ) { ... }
    fn trigger_envelope(&mut self) { ... }
    fn set_drum_sample_override(
        &mut self,
        _channel: usize,
        _sample: Option<f32>,
    ) { ... }
    fn set_mixer_overrides(
        &mut self,
        _force_tone: [bool; 3],
        _force_noise_mute: [bool; 3],
    ) { ... }
}

Common interface for YM2149 chip backends

This trait allows different implementations to be used interchangeably:

• Hardware-accurate emulation (cycle-exact, bit-perfect)
• Experimental software synthesizers (musical, non-accurate)
• Future implementations (FPGA cores, etc.)

Example

use ym2149_common::Ym2149Backend;

fn play_note<B: Ym2149Backend>(chip: &mut B) {
    chip.write_register(0x00, 0xF0); // Channel A period low
    chip.write_register(0x01, 0x01); // Channel A period high
    chip.write_register(0x08, 0x0F); // Channel A volume
    chip.write_register(0x07, 0x3E); // Mixer: enable tone A

    chip.clock();
    let sample = chip.get_sample();
}

Required Methods

fn new() -> Self

where Self: Sized,

Create a new backend instance with default clocks

Default clocks:

• Master clock: 2,000,000 Hz (Atari ST frequency)
• Sample rate: 44,100 Hz

fn with_clocks(master_clock: u32, sample_rate: u32) -> Self

where Self: Sized,

Create a backend with custom master clock and sample rate

Arguments

• master_clock - YM2149 master clock frequency in Hz
• sample_rate - Audio output sample rate in Hz

fn reset(&mut self)

Reset the backend to initial state

Clears all registers, resets generators, and stops all audio output.

fn write_register(&mut self, addr: u8, value: u8)

Write to a YM2149 register

Arguments

• addr - Register address (0x00-0x0F)
• value - Register value (0x00-0xFF)

Registers outside the valid range are ignored.

fn read_register(&self, addr: u8) -> u8

Read from a YM2149 register

Arguments

• addr - Register address (0x00-0x0F)

Returns

Current register value, or 0x00 for invalid addresses

fn load_registers(&mut self, regs: &[u8; 16])

Load all 16 YM2149 registers at once

More efficient than 16 individual write_register calls.

Arguments

• regs - Array of 16 register values (R0-R15)

fn dump_registers(&self) -> [u8; 16]

Dump all 16 YM2149 registers

Returns

Current state of all registers (R0-R15)

fn clock(&mut self)

Advance the chip by one clock cycle

Updates all internal generators (tone, noise, envelope) and produces a new audio sample. Call this at the backend’s sample rate.

fn get_sample(&self) -> f32

Get the last generated audio sample

Returns

Normalized audio sample in range [-1.0, 1.0]

fn get_channel_outputs(&self) -> (f32, f32, f32)

Get individual channel outputs

Returns

Tuple of (channel_a, channel_b, channel_c) samples in range [-1.0, 1.0]

fn set_channel_mute(&mut self, channel: usize, mute: bool)

Mute or unmute a channel

Arguments

• channel - Channel index (0=A, 1=B, 2=C)
• mute - true to mute, false to unmute

fn is_channel_muted(&self, channel: usize) -> bool

Check if a channel is muted

Arguments

• channel - Channel index (0=A, 1=B, 2=C)

Returns

true if channel is muted, false otherwise

fn set_color_filter(&mut self, enabled: bool)

Enable or disable post-processing color filter

Arguments

• enabled - true to enable filter, false to disable

Provided Methods

fn generate_samples(&mut self, count: usize) -> Vec<f32>

Generate multiple audio samples

Arguments

• count - Number of samples to generate

Returns

Vector of normalized audio samples in range [-1.0, 1.0]

fn generate_samples_into(&mut self, buffer: &mut [f32])

Generate multiple audio samples into a caller-provided buffer

This avoids per-call allocations; prefer this in hot paths.

Arguments

• buffer - Output slice to fill with normalized audio samples in range [-1.0, 1.0]

fn generate_samples_with_channels( &mut self, buffer: &mut [f32], channel_outputs: &mut [[f32; 3]], )

Generate samples with synchronized per-sample channel outputs

This method generates mono samples and captures per-channel outputs at the same time, ensuring that the channel data is perfectly synchronized with the audio. This is essential for accurate visualization (oscilloscope, spectrum analyzer).

Arguments

• buffer - Output slice for mono samples in range [-1.0, 1.0]
• channel_outputs - Output slice for per-sample channel outputs [A, B, C]

Panics

Panics if buffer and channel_outputs have different lengths.

fn trigger_envelope(&mut self)

Trigger envelope restart (used by YM6 Sync Buzzer effect)

This is a hardware-specific feature. Default implementation is a no-op. Only Ym2149 provides full implementation.

fn set_drum_sample_override(&mut self, _channel: usize, _sample: Option<f32>)

Override drum sample for a channel (used by YM6 DigiDrum effect)

This is a hardware-specific feature. Default implementation is a no-op. Only Ym2149 provides full implementation.

Arguments

• channel - Channel index (0=A, 1=B, 2=C)
• sample - Optional sample value to inject, None to disable override

fn set_mixer_overrides( &mut self, _force_tone: [bool; 3], _force_noise_mute: [bool; 3], )

Set mixer tone/noise overrides (used by YM6 DigiDrum effect)

This is a hardware-specific feature. Default implementation is a no-op. Only Ym2149 provides full implementation.

Arguments

• force_tone - Per-channel flags to force tone enable
• force_noise_mute - Per-channel flags to force noise mute

Implementors