Expand description
A NES graphics emulator with a Rust interface.
This library emulates the NTSC NES PPU (2c02), and provides a generic interface mimicking the interface that exists on actual NES hardware. In addition, the interface also contains some conveniences not available on the NES in order to make programming more ergonomic.
Features
no_std
support- Cycle-based emulation, including accurate timings for sprite processing and mapper accesses
- Emulation of all PPU registers (0x2000-0x2007)
- Support for arbitrary custom memory mappers and output formats
- Most system quirks are properly emulated:
- Garbage nametable fetches
- Different total cycle counts on even vs. odd frames
- Buggy overflow flag behavior
- Reading OAMDATA during rendering snoops on internal sprite processing state
- Incorrect color output during forced blanking when vram address indexes palette ram
- Etc.
Limitations
- PPU register accesses happen “instantaneously,” and do not cause the PPU to tick forwards
despite reads/writes taking multiple cycles on real hardware
- For truly accurate graphics, users must therefore be careful to weigh how much work is being done relative to when/how often they tick the PPU
- No support for PAL or Dendy PPUs
- No emulation of open bus behavior
- Mapper reads take 1 cycle to resolve, instead of 2 like on real hardware (the timings of when the reads start are still accurate)
Example
use nes_ppu::{Ppu, Mapper, PixelBuffer, Color, ColorEmphasis};
struct ExamplePixelBuffer {
/* ... */
}
impl ExamplePixelBuffer {
fn render_to_screen(&self) {
/* ... */
}
}
impl PixelBuffer for ExamplePixelBuffer {
fn set_color(&mut self, x: u8, y: u8, color: Color, emphasis: ColorEmphasis) {
// write color information into internal screen buffer to be rendered when the frame
// is complete
/* ... */
}
}
struct ExampleMapper {
/* ... */
}
impl Mapper for ExampleMapper {
fn read(&mut self, addr: u16) -> u8 {
/* ... */
}
fn write(&mut self, addr: u16, value: u8) {
/* ... */
}
}
fn main_loop() {
let mut ppu = Ppu::new();
let mut mapper = ExampleMapper { /* ... */ };
let mut buf = ExamplePixelBuffer { /* ... */ };
loop {
// run main game logic here
ppu.tick_to_next_sprite_0_hit(&mut mapper, &mut buf);
// add sprite 0 hit raster effect here
ppu.tick_to_next_vblank(&mut mapper, &mut buf);
buf.render_to_screen();
// modify vram and set up scroll position for next frame here
}
}
Structs
- Red, green, and/or blue color emphasis information.
- A set of colors usable by tiles and sprites.
- The NES Picture Processing Unit.
- A floating graphic is rendered separately from tiles.
Constants
- Automatic increment of VRAM addr (0: 1; 1: 32).
- EXT pin behavior (0: background read from EXT; 1: color output on EXT) - DO NOT USE.
- Interrupt when PPU enters vblank (0: off; 1: on).
- Sprite pattern table (0: 0x0000; 1: 0x1000). Ignored if sprite size is 8x16px.
- Sprite size (0: 8x8px; 1: 8x16px).
- Tile pattern table (0: 0x0000; 1: 0x1000).
- Emphasize blue color output.
- Emphasize green color output.
- Emphasize red color output.
- Greyscale color.
- Show sprites in the leftmost 8 pixels of the screen.
- Show tiles in the leftmost 8 pixels of the screen.
- Show sprites.
- Show tiles.
- Sprite dropout has occurred this frame (bugged).
- A non-transparent pixel of sprite 0 has overlapped a non-transparent pixel of a tile this frame.
- The PPU is in vblank.
- Flip sprite along the x axis.
- Flip sprite along the y axis.
- Mask for sprite palette index bits.
- Render sprite in front or behind tiles (0: in front; 1: behind).
Traits
- Memory map used by the PPU to access video memory.
- Receives pixel information from the PPU as it draws.
Type Definitions
- A number corresponding to a color.