Struct ControlDeck

pub struct ControlDeck { /* private fields */ }

Represents an NES Control Deck. Encapsulates the entire emulation state.

Implementations

impl ControlDeck

pub fn new() -> Self

Create a NES ControlDeck with the default configuration.

pub fn with_config(cfg: Config) -> Self

Create a NES ControlDeck with a configuration.

pub fn sram_dir(&self, name: &str) -> PathBuf

Returns the path to the SRAM save file for a given ROM name which is used to store battery-backed Cart RAM. Returns None when the current platform doesn’t have a data directory and no custom data_dir was configured.

pub fn load_rom<S: ToString, F: Read>( &mut self, name: S, rom: &mut F, ) -> Result<LoadedRom>

Loads a ROM cartridge into memory

Errors

If there is any issue loading the ROM, then an error is returned.

pub fn load_rom_path(&mut self, path: impl AsRef<Path>) -> Result<LoadedRom>

Loads a ROM cartridge into memory from a path.

Errors

If there is any issue loading the ROM, then an error is returned.

pub fn unload_rom(&mut self) -> Result<()>

Unloads the currently loaded ROM and saves SRAM to disk if the Cart is battery-backed.

Errors

If the loaded Cart is battery-backed and saving fails, then an error is returned.

pub fn load_cpu(&mut self, cpu: Cpu)

Load a previously saved CPU state.

pub const fn set_mapper_revision(&mut self, rev: MapperRevision)

Set the MapperRevision to emulate for the any ROM loaded that uses this mapper.

pub const fn set_mapper_revisions(&mut self, revs: MapperRevisionsConfig)

Set the set of MapperRevisionsConfig to emulate for the any ROM loaded that uses this mapper.

pub fn set_concurrent_dpad(&mut self, enabled: bool)

Set whether concurrent D-Pad input is enabled which wasn’t possible on the original NES.

pub const fn set_cycle_accurate(&mut self, enabled: bool)

Set whether emulation should be cycle accurate or not. Disabling this can increase performance.

pub const fn set_ram_state(&mut self, ram_state: RamState)

Set emulation RAM initialization state.

pub const fn set_headless_mode(&mut self, mode: HeadlessMode)

Set the headless mode which can increase performance when the frame and audio outputs are not needed.

pub const fn set_emulate_ppu_warmup(&mut self, enabled: bool)

Set whether to emulate PPU warmup where writes to certain registers are ignored. Can result in some games not working correctly.

See: https://www.nesdev.org/wiki/PPU_power_up_state

pub fn add_debugger(&mut self, debugger: Debugger)

Adds a debugger callback to be executed any time the debugger conditions match.

pub fn remove_debugger(&mut self, debugger: Debugger)

Removes a debugger callback.

pub const fn loaded_rom(&self) -> Option<&LoadedRom>

Returns the name of the currently loaded ROM Cart. Returns None if no ROM is loaded.

pub fn cart_region(&self) -> Option<NesRegion>

Returns the auto-detected NesRegion for the loaded ROM. Returns None if no ROM is loaded.

pub fn cart_battery_backed(&self) -> Option<bool>

Returns whether the loaded ROM is battery-backed. Returns None if no ROM is loaded.

pub fn wram(&self) -> &[u8]

Returns the NES Work RAM.

pub fn sram(&self) -> &[u8]

Returns the battery-backed Save RAM.

pub fn save_sram(&self, path: impl AsRef<Path>) -> Result<()>

Save battery-backed Save RAM to a file (if cartridge supports it)

Errors

If the file path is invalid or fails to save, then an error is returned.

pub fn load_sram(&mut self, path: impl AsRef<Path>) -> Result<()>

Load battery-backed Save RAM from a file (if cartridge supports it)

Errors

If the file path is invalid or fails to load, then an error is returned.

pub fn save_state(&mut self, path: impl AsRef<Path>) -> Result<()>

Save the current state of the console into a save file.

Errors

If there is an issue saving the state, then an error is returned.

pub fn load_state(&mut self, path: impl AsRef<Path>) -> Result<()>

Load the console with data saved from a save state, if it exists.

Errors

If there is an issue loading the save state, then an error is returned.

pub fn frame_buffer_raw(&mut self) -> &[u16]

Load the raw underlying frame buffer from the PPU for further processing.

pub fn frame_buffer(&mut self) -> &[u8]

Load a frame worth of pixels.

pub fn frame_buffer_into(&self, buffer: &mut [u8])

Load a frame worth of pixels into the given buffer.

pub const fn frame_number(&self) -> u32

Get the current frame number.

pub fn audio_samples(&self) -> &[f32]

Get audio samples.

pub fn clear_audio_samples(&mut self)

Clear audio samples.

pub const fn clock_rate(&self) -> f32

CPU clock rate based on currently configured NES region.

pub fn clock_instr(&mut self) -> Result<u64>

Steps the control deck one CPU clock.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_seconds(&mut self, seconds: f32) -> Result<u64>

Steps the control deck the number of seconds.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_frame(&mut self) -> Result<u64>

Steps the control deck an entire frame.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_frame_output<T>( &mut self, handle_output: impl FnOnce(u64, &[u8], &[f32]) -> T, ) -> Result<T>

Steps the control deck an entire frame, calling handle_output with the cycles, frame_buffer and audio_samples for that frame.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_frame_into( &mut self, frame_buffer: &mut [u8], audio_samples: &mut [f32], ) -> Result<u64>

Steps the control deck an entire frame, copying the frame_buffer and audio_samples for that frame into the provided buffers.

Errors

If CPU encounteres an invalid opcode, an error is returned.

pub fn clock_frame_ahead<T>( &mut self, run_ahead: usize, handle_output: impl FnOnce(u64, &[u8], &[f32]) -> T, ) -> Result<T>

Steps the control deck an entire frame with run-ahead frames to reduce input lag.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_frame_ahead_into( &mut self, run_ahead: usize, frame_buffer: &mut [u8], audio_samples: &mut [f32], ) -> Result<u64>

Steps the control deck an entire frame with run-ahead frames to reduce input lag.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub fn clock_scanline(&mut self) -> Result<u64>

Steps the control deck a single scanline.

Errors

If CPU encounters an invalid opcode, then an error is returned.

pub const fn cpu_corrupted(&self) -> bool

Returns whether the CPU is corrupted or not which means it encounted an invalid/unhandled opcode and can’t proceed executing the current ROM.

pub const fn cpu(&self) -> &Cpu

Returns the current Cpu state.

pub const fn cpu_mut(&mut self) -> &mut Cpu

Returns a mutable reference to the current Cpu state.

pub const fn ppu(&self) -> &Ppu

Returns the current Ppu state.

pub const fn ppu_mut(&mut self) -> &mut Ppu

Returns a mutable reference to the current Ppu state.

pub const fn bus(&self) -> &Bus

Retu[ns the current Bus state.

pub const fn bus_mut(&mut self) -> &mut Bus

Returns a mutable reference to the current Bus state.

pub const fn apu(&self) -> &Apu

Returns the current Apu state.

pub const fn apu_mut(&mut self) -> &Apu

Returns a mutable reference to the current Apu state.

pub const fn mapper(&self) -> &Mapper

Returns the current Mapper state.

pub const fn mapper_mut(&mut self) -> &mut Mapper

Returns a mutable reference to the current Mapper state.

pub const fn four_player(&self) -> FourPlayer

Returns the current four player mode.

pub fn set_four_player(&mut self, four_player: FourPlayer)

Enable/Disable Four Score for 4-player controllers.

pub const fn joypad(&mut self, slot: Player) -> &Joypad

Returns the current Joypad state for a given controller slot.

pub const fn joypad_mut(&mut self, slot: Player) -> &mut Joypad

Returns a mutable reference to the current Joypad state for a given controller slot.

pub const fn zapper_connected(&self) -> bool

Returns whether the Zapper gun is connected.

pub const fn connect_zapper(&mut self, enabled: bool)

Enable Zapper gun.

pub const fn zapper_pos(&self) -> (u32, u32)

Returns the current Zapper aim position.

pub fn trigger_zapper(&mut self)

Trigger Zapper gun.

pub fn aim_zapper(&mut self, x: u32, y: u32)

Aim Zapper gun.

pub const fn set_filter(&mut self, filter: VideoFilter)

Set the video filter for frame buffer output when calling ControlDeck::frame_buffer.

pub fn set_sample_rate(&mut self, sample_rate: f32)

Set the Apu sample rate.

pub fn set_frame_speed(&mut self, speed: f32)

Set the emulation speed.

pub fn add_genie_code(&mut self, genie_code: String) -> Result<()>

Add a NES Game Genie code.

Errors

If the genie code is invalid, an error is returned.

pub fn remove_genie_code(&mut self, genie_code: &str)

Remove a NES Game Genie code.

pub fn clear_genie_codes(&mut self)

Remove all NES Game Genie codes.

pub const fn channel_enabled(&self, channel: Channel) -> bool

Returns whether a given Apu Channel is enabled.

pub const fn set_apu_channel_enabled(&mut self, channel: Channel, enabled: bool)

Enable or disable a given Apu Channel.

pub const fn toggle_apu_channel(&mut self, channel: Channel)

Toggle a given Apu Channel.

pub const fn is_running(&self) -> bool

Returns whether the control deck is currently running.

Trait Implementations

impl Clock for ControlDeck

fn clock(&mut self) -> u64

Steps the control deck a single clock cycle.

impl Clone for ControlDeck

fn clone(&self) -> ControlDeck

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ControlDeck

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ControlDeck

fn default() -> Self

Returns the “default value” for a type.

impl Regional for ControlDeck

fn region(&self) -> NesRegion

Get the NES format for the emulation.

fn set_region(&mut self, region: NesRegion)

Set the NES format for the emulation.

impl Reset for ControlDeck

fn reset(&mut self, kind: ResetKind)

Resets the console.