Frontend Architecture

Frontend Architecture

References: docs/frontend.md

The frontend architecture of RustyNES is implemented in the crates/rustynes-frontend crate. The goal of the frontend is to provide windowing, rendering, audio, input, and debugger UI while keeping the core emulation logic completely isolated and deterministic.

Technology Stack

The desktop application is built with the following technologies:

• Window + Event Loop: winit (Linux X11/Wayland, macOS AppKit, Windows Win32, Web wasm-winit).
• GPU Rendering: wgpu (WebGPU API targeting Vulkan, Metal, D3D12, GLES).
• Audio Output: cpal (Cross-platform PCM stream).
• GUI Shell + Overlays: egui 0.34 + egui-wgpu for the menu bar, status bar, settings, and toggleable debugger panels.
• Gamepads: gilrs (XInput, evdev, GameController.framework).

Architecture Highlights

1. Always-On egui Shell: The application is not a bare window; it runs an egui shell every frame. The DebuggerOverlay::render_shell draws the persistent menu bar and panels. The shell never holds the emulator lock inside the egui closure, maintaining high performance and preventing UI-blocking operations.
2. Dedicated Emulation Thread: On native platforms, the emulator runs on a dedicated emu-thread communicating with the UI thread via a lock-free SharedInput queue. This guarantees deterministic behavior and smooth frame pacing regardless of UI events.
3. Menu Actions: Menu interactions return a MenuAction enum that App::dispatch_menu_action processes after the egui pass, ensuring thread safety.
4. Display Sync and Audio Resampling: The frontend handles dynamic rate control (DRC) and display-sync pacing (V-Sync, VRR, wallclock), meaning the core emulator never worries about timing. It just emits frames and samples, and the frontend scales them.

Render Pipeline

The render pipeline utilizes a single full-screen triangle shader (rustynes-gfx-shaders) to blit the core's native RGBA8 output. The pipeline supports scaling, aspect-ratio correction, and complex multi-pass shaders like the NTSC composite filter.