Crate nes_ppu

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

ColorEmphasis

Red, green, and/or blue color emphasis information.

Palette

A set of colors usable by tiles and sprites.

Ppu

The NES Picture Processing Unit.

Sprite

A floating graphic is rendered separately from tiles.

Constants

PPUCTRL_ADDR_INC

Automatic increment of VRAM addr (0: 1; 1: 32).

PPUCTRL_MSS

EXT pin behavior (0: background read from EXT; 1: color output on EXT) - DO NOT USE.

PPUCTRL_NMI_ENABLE

Interrupt when PPU enters vblank (0: off; 1: on).

PPUCTRL_SPRITE_PATTERN_TABLE

Sprite pattern table (0: 0x0000; 1: 0x1000). Ignored if sprite size is 8x16px.

PPUCTRL_SPRITE_SIZE

Sprite size (0: 8x8px; 1: 8x16px).

PPUCTRL_TILE_PATTERN_TABLE

Tile pattern table (0: 0x0000; 1: 0x1000).

PPUMASK_EMPH_BLUE

Emphasize blue color output.

PPUMASK_EMPH_GREEN

Emphasize green color output.

PPUMASK_EMPH_RED

Emphasize red color output.

PPUMASK_GREYSCALE

Greyscale color.

PPUMASK_SHOW_COLUMN_0_SPRITES

Show sprites in the leftmost 8 pixels of the screen.

PPUMASK_SHOW_COLUMN_0_TILES

Show tiles in the leftmost 8 pixels of the screen.

PPUMASK_SHOW_SPRITES

Show sprites.

PPUMASK_SHOW_TILES

Show tiles.

PPUSTATUS_OVERFLOW

Sprite dropout has occurred this frame (bugged).

PPUSTATUS_SPRITE_0_HIT

A non-transparent pixel of sprite 0 has overlapped a non-transparent pixel of a tile this frame.

PPUSTATUS_VBLANK

The PPU is in vblank.

SPRITE_FLIP_X

Flip sprite along the x axis.

SPRITE_FLIP_Y

Flip sprite along the y axis.

SPRITE_PALETTE_MASK

Mask for sprite palette index bits.

SPRITE_PRIORITY

Render sprite in front or behind tiles (0: in front; 1: behind).

Traits

Mapper

Memory map used by the PPU to access video memory.

PixelBuffer

Receives pixel information from the PPU as it draws.

Type Aliases

Color

A number corresponding to a color.