Struct Opl3Device

Source

pub struct Opl3Device { /* private fields */ }

Expand description

The Opl3Device struct provides convenience functions for fully implementing an OPL3 device on top of Nuked-OPL3. By keeping a copy of all registers written, we can implement a read_register function.

Implementations§

Source §

impl Opl3Device

Source

pub fn new(sample_rate: u32) -> Self

Create a new OPL3 device instance. Opl3Device is a convenience wrapper around the Nuked-OPL3’s direct wrapper, Opl3Chip. It provides the rest of an OPL3 implementation on top of the chip, including register tracking and a read_register function.

Source

pub fn stats(&self) -> Opl3DeviceStats

Retrieve the statistics for the OPL3 device in the form of an Opl3DeviceStats struct.

§Returns

An Opl3DeviceStats struct containing the statistics for the OPL3 device.

Source

pub fn run(&mut self, usec: f64) -> usize

Update the Opl3Device instance. This function should be called periodically to update the state of the OPL3 timers.

§Arguments

usec - The number of microseconds that have passed since the last call to run.

§Returns

The number of samples that correspond to the specified microseconds that elapsed. The Opl3Device maintains a fractional accumulator, so you can use this returned value to determine how many samples to generate.

Source

pub fn read_status(&mut self) -> u8

Read a byte from the OPL3 device’s Status register. The Nuked-OPL3 library does not natively provide emulation of the OPL3 status register. The status register contains bits that indicate the status of the OPL3’s timers. To properly emulate this timer state, it is necessary to call run() on the OPL3 device periodically.

Source

pub fn write_address( &mut self, addr: u8, file: OplRegisterFile, ) -> Result<(), OplError>

Write a byte to the OPL3 device’s Address register. This function, along with write_data, is likely the primary interface for an emulator implementing an OPL device.

§Arguments

addr - The register address to write to the OPL3 device, in the range 0..=255.
file - The register file to write to. OPL3 devices have two register files, the Primary and Secondary files. OPL2 devices only have the Primary register file.

Source

pub fn write_data( &mut self, data: u8, file: OplRegisterFile, buffered: bool, ) -> Result<(), OplError>

Write a byte to the OPL3 device’s Data register. This function, along with write_address, is likely the primary interface function for an emulator implementing an OPL device.

The actual internal register to be written should be set by writing to the OPL3 address register via write_address before calling write_data.

§Arguments

data - The byte of data to write to the OPL3 device.
buffered - Whether to write the data in buffered mode. In buffered mode, Nuked-OPL3 will store the write in a buffer and execute it after any necessary delay. This is useful for controlling the library manually, but if you are implementing an emulator the software controlling the OPL3 module will likely write registers with appropriate timings.
file - The register file to write to. OPL3 devices have two register files, the Primary and Secondary files. OPL2 devices only have the Primary register file.

Source

pub fn read_register(&self, reg: u8, file: OplRegisterFile) -> u8

Return the value of the given chip register from internal state. The OPL3 registers are not natively readable. Opl3Device keeps a copy of all registers written so that they can be queried. This internal state will become desynchronized if registers are written directly to the OPL3 chip.

§Arguments

reg - The internal register index to read.
file - The register file to write to. OPL3 devices have two register files, the Primary and Secondary files. OPL2 devices only have the Primary register file

§Returns

The u8 value of the requested register.

Source

pub fn write_register( &mut self, reg: u8, value: u8, file: OplRegisterFile, buffered: bool, )

Write to the specified register directly. This will update the internal state of the Opl3Device so that the register value can later be read.

§Arguments

reg - The internal register index to write.
value - The value to write to the register.
buffered - Whether to write the data in buffered mode. In buffered mode, Nuked-OPL3 will store the write in a buffer and execute it after any necessary delay. This is useful for controlling the library manually, but if you are implementing an emulator the software controlling the OPL3 module will likely write registers with appropriate timings.
file - The register file to write to. OPL3 devices have two register files, the Primary and Secondary files. OPL2 devices only have the Primary register file

Source

pub fn reset(&mut self, sample_rate: Option<u32>) -> Result<(), OplError>

Reset the Opl3Device. Reset the state of the OPL3 device, including the internal registers and the internal Nuked-OPL3 instance.

§Arguments

sample_rate - An option that either contains the new sample rate to reinitialize with or None to keep the current sample rate.

§Returns

A Result containing either () on success or an OplError on failure.

Source

pub fn generate(&mut self, sample: &mut [i16]) -> Result<(), OplError>

Generate a 2 channel audio sample in interleaved i16 format.

§Arguments

sample - A mutable reference to a two-element slice that will receive the audio sample. The first element will contain the left channel sample, and the second element will contain the right channel sample.