Crate rustynes_ppu

Expand description

Cycle-accurate Ricoh 2C02 PPU implementation.

See docs/ppu-2c02.md for the implementation spec and ref-docs/research-report.md §PPU for the source material.

Background rendering, sprite evaluation + rendering, sprite-zero hit, sprite overflow, and the open-bus latch are all implemented at PPU-dot resolution. PPUSTATUS / PPUDATA / PPUSCROLL / PPUADDR register quirks match the test-ROM corpus. The 2-PPU-clock PPUMASK pipeline delay between a mask write and the odd-frame dot-skip check is wired through.

Region timing (NTSC vs PAL vs Dendy) is parameterized via PpuRegion; the structural difference between them is the post- render-to-pre-render scanline span (NTSC: 241..=260; PAL: 241..=310; Dendy: 241..=290).

Re-exports§

pub use provenance::CIRAM_LEN as ATTRIB_CIRAM_LEN;
pub use provenance::OAM_LEN as ATTRIB_OAM_LEN;
pub use provenance::PALETTE_LEN as ATTRIB_PALETTE_LEN;
pub use provenance::PATTERN_ADDR_NONE;
pub use provenance::PixelLayer;
pub use provenance::PixelProvenance;
pub use provenance::PixelProvenanceFrame;
pub use provenance::ProvenanceStash;
pub use provenance::SPRITE_SLOT_NONE;
pub use provenance::WriteAttrib;
pub use provenance::WriteAttribution;

Modules§

octal_trace: Zero-cost no-op stand-in for the octal-latch tracer.
provenance: v2.3.2 “Lucid” — per-byte write attribution for PPU-visible memory.
read2007_diag: Diagnostic: capture the (frame, scanline, dot, mask) of $2007 reads to pin where the $2007 Stress test’s per-dot reads land vs the visible scanline they target. Gated; default build unaffected.

Structs§

BgSplitState: Vertical split-screen override (MMC5 $5200-$5202 and equivalents).
ExAttribute: Re-export of the mapper-side per-tile extended-attribute info.
HdSprite: One sprite covering a pixel, for the HD-pack multi-sprite conditions (spriteAtPosition / spriteNearby). Carries just the identity those conditions match on. Output-only telemetry.
HdTileSource: v1.2.0 beta.2 (Workstream C3) — per-pixel HD-pack tile-source record.
NtscPaletteParams: Tunable parameters for generate_base_palette.
Ppu: 2C02 PPU.
ProvBgAddrs: The three VRAM addresses that produced one background tile.

Enums§

PaletteInit: v2.1.7 P5 — selectable power-up palette-RAM contents.
PpuPalette: Which PPU palette is active for the running console.
PpuRegion: Region governs the size of the post-render-to-pre-render scanline span.
PpuRevision: v2.1.7 P5 — selectable 2C02 die revision, gating revision-dependent quirks.
PpuSnapshotError: Errors returned by Ppu::restore.

Constants§

ATTENUATION: Per-emphasis-bit attenuation factor (≈ −2.5 dB) applied during the phases that overlap the emphasized primary’s hue region. (Bisqwit / nesdev.)
BLACK: Black reference voltage (the composite level that normalizes to 0.0).
FRAMEBUFFER_LEN: RGBA8 framebuffer length in bytes (256 × 240 × 4).
FRAMEBUFFER_PIXELS: Visible pixel count (256 × 240) — length of the parallel Ppu::index_framebuffer (one u16 per pixel).
HD_CHR_RAM: chr_tile_index sentinel meaning “CHR is RAM” — the tile is keyed by its 16 CHR bytes (content) rather than by an absolute CHR-ROM tile index.
HD_TILE_NONE: Sentinel chr_addr for a transparent / universal-background HD-pack pixel.
LEVELS: The eight composite signal voltage levels the 2C02 emits, relative to sync.
NES_PALETTE: 64-entry RGB888 NES palette (FBX Smooth). Each entry is [R, G, B].
PHASES: The number of distinct subcarrier phases the 2C02 walks within one pixel. A full color-decode integrates over exactly these twelve samples.
PPU_SNAPSHOT_SLIM_FLAG: v2.3.3 — high bit of the version byte, marking a slim snapshot: every field except the 245,760-byte framebuffer.
PPU_SNAPSHOT_VERSION: Schema version for the PPU snapshot blob.
RAW_ENTRIES: The number of (index, emphasis) entries in a full raw-signal LUT: 64 base colors × 8 emphasis states.
SCREEN_HEIGHT: Visible screen height in pixels. Companion to SCREEN_WIDTH.
SCREEN_WIDTH: Visible screen width in pixels, and the stride of every per-pixel buffer the PPU exposes.
WHITE: White reference voltage (the composite level that normalizes to 1.0).

Statics§

MASK_WRITE_DELAY: v2.0 Phase 6 (mc-ppu-subpos): the analog $2001 PPUMASK write delay.

Traits§

PpuBus: Bus interface the PPU sees.

Functions§

build_rgba_lut: v2.8.0 Phase 4 — build the 512-entry (emphasis << 6) | color → RGBA8 lookup the PPU’s pixel-emit path uses.
build_rgba_lut_from_base: Build the 512-entry (emphasis << 6) | color → RGBA8 lookup from a custom 64-entry base palette (e.g. a loaded .pal file).
composite_voltage: Compute the raw composite voltage (relative to sync) for one subcarrier phase (0..12) of NES palette index (0..=63) under emphasis (0..=7, bit0 = red, bit1 = green, bit2 = blue).
generate_base_palette: Synthesize the 64-entry RGB888 base palette from params.
generate_raw_signal_lut: Generate the full raw-signal LUT: RAW_ENTRIES rows (index-major, index * 8 + emphasis), each the twelve normalized subcarrier samples.
in_color_phase: Return true when the chroma square wave for hue color (0..15) is in its “high” state at subcarrier phase phase (0..12).
nes_color_to_rgba: Convert a 6-bit NES color index to an RGBA8 quad.
normalize: Normalize a raw composite voltage to the shader-friendly [0.0, 1.0] range.
palette_color_to_rgba: Convert a 6-bit color index to RGBA8 under the active PPU palette, applying the palette’s emphasis model.
signal_samples: Build the twelve normalized composite samples for one (index, emphasis) pair — the per-pixel waveform a signal-decode shader convolves across neighbouring pixels.
version: Returns the crate version string.