A GameCube/Wii emulator and debugger written in Rust.
opt in writeback
Layle2cc51f4924ec
diff --git a/crates/backend-wgpu/Cargo.toml b/crates/backend-wgpu/Cargo.tomlindex 9c13a3b..9cd68e7 100644--- a/crates/backend-wgpu/Cargo.toml+++ b/crates/backend-wgpu/Cargo.toml@@ -3,6 +3,9 @@ name = "backend-wgpu"version = "0.1.0"edition = "2024"+[features]+efb-writeback = ["gecko/efb-writeback"]+[dependencies]wgpu = "28.0.0"bytemuck = { version = "1.25.0", features = ["derive"] }diff --git a/crates/backend-wgpu/src/action.rs b/crates/backend-wgpu/src/action.rsindex c79530c..9e36a3d 100644--- a/crates/backend-wgpu/src/action.rs+++ b/crates/backend-wgpu/src/action.rs@@ -230,13 +230,13 @@ impl GxRenderer {}GxAction::CopyEfbToTexture {- dest_addr,+ dest_addr: _dest_addr,src_x,src_y,src_w,src_h,- copy_format,- mipmap,+ copy_format: _copy_format,+ mipmap: _mipmap,stride: _,clear,clear_color,@@ -253,20 +253,47 @@ impl GxRenderer {// variants and gate on each mask independently.let effective_clear = *clear && *color_update;self.flush_pending_draws(device, queue);++ // With `efb-writeback`: read the EFB back, encode it in+ // `copy_format`, ship the bytes to the emu thread so they+ // land in `Mmio::ram` at `dest_addr`. Expensive (GPU stall).+ #[cfg(feature = "efb-writeback")]self.execute_copy_efb_to_texture(device,queue,- *dest_addr,+ *_dest_addr,*src_x,*src_y,*src_w,*src_h,- *copy_format,- *mipmap,+ *_copy_format,+ *_mipmap,effective_clear,*clear_color,*clear_z,);++ // Default path: no readback, no encode, no RAM touch. Texture+ // invalidation happens on the emu side via a `texture_hashes`+ // drop. We only need to honor the post-copy clear here.+ #[cfg(not(feature = "efb-writeback"))]+ if effective_clear {+ self.efb_clear.clear_region(+ device,+ queue,+ &self.efb_msaa_view,+ &self.efb_view,+ &self.efb_depth_view,+ crate::EFB_WIDTH,+ crate::EFB_HEIGHT,+ *src_x,+ *src_y,+ *src_w,+ *src_h,+ *clear_color,+ *clear_z,+ );+ }}}}diff --git a/crates/backend-wgpu/src/lib.rs b/crates/backend-wgpu/src/lib.rsindex 9737a6a..b25e0ec 100644--- a/crates/backend-wgpu/src/lib.rs+++ b/crates/backend-wgpu/src/lib.rs@@ -9,6 +9,7 @@ use encase::ShaderType as _;use gecko::common::Address;use gecko::flipper::gx::draw::{Scissor, Viewport};use gecko::flipper::gx::regs::{AlphaCompare, BlendMode, CompareFunc, CullMode, MagFilter, MinFilter, WrapMode, ZMode};+#[cfg(feature = "efb-writeback")]use gecko::host::EfbWriteback;use glam::Mat4;use pipeline::PipelineKey;@@ -138,12 +139,15 @@ pub struct GxRenderer {pub(crate) xfb_copies: HashMap<u32, (wgpu::Texture, wgpu::TextureView)>,// Region-scoped EFB clear.pub(crate) efb_clear: clear::EfbClear,- // EFB-to-texture readback.+ // EFB-to-texture readback. Only allocated with `efb-writeback`.+ #[cfg(feature = "efb-writeback")]pub(crate) efb_readback_staging: Option<wgpu::Buffer>,+ #[cfg(feature = "efb-writeback")]pub(crate) efb_readback_capacity: u64,// Sender used to ship encoded EFB-to-texture bytes back to the emu// thread. Installed by `sink::Renderer::new` via// [`GxRenderer::set_efb_writeback_tx`].+ #[cfg(feature = "efb-writeback")]pub(crate) efb_writeback_tx: Option<crossbeam_channel::Sender<EfbWriteback>>,}@@ -410,14 +414,18 @@ impl GxRenderer {xfb_has_content: false,xfb_copies: HashMap::new(),efb_clear,+ #[cfg(feature = "efb-writeback")]efb_readback_staging: None,+ #[cfg(feature = "efb-writeback")]efb_readback_capacity: 0,+ #[cfg(feature = "efb-writeback")]efb_writeback_tx: None,}}/// Install the sender used to ship encoded EFB-to-texture bytes back/// to the emulator thread. Called by `sink::Renderer` during setup.+ #[cfg(feature = "efb-writeback")]pub fn set_efb_writeback_tx(&mut self, tx: crossbeam_channel::Sender<EfbWriteback>) {self.efb_writeback_tx = Some(tx);}diff --git a/crates/backend-wgpu/src/render.rs b/crates/backend-wgpu/src/render.rsindex 5522383..396020d 100644--- a/crates/backend-wgpu/src/render.rs+++ b/crates/backend-wgpu/src/render.rs@@ -1,9 +1,13 @@use crate::{FrameUniforms, GxRenderer};use crate::{GpuVertex, align_up};use encase::ShaderType as _;+#[cfg(feature = "efb-writeback")]use gecko::common::Address;+#[cfg(feature = "efb-writeback")]use gecko::flipper::gx::texture;-use gecko::host::{EfbWriteback, XfbPart};+#[cfg(feature = "efb-writeback")]+use gecko::host::EfbWriteback;+use gecko::host::XfbPart;impl GxRenderer {pub(crate) fn upload_buffers(&mut self, device: &wgpu::Device, queue: &wgpu::Queue, frame_uniform_bytes: &[u8]) {@@ -242,6 +246,10 @@ impl GxRenderer {/// `effective_clear` is the already-gated clear flag (see the/// `CopyEfbToTexture` arm in `action.rs`); this function does not look/// at the per-channel write masks itself.+ ///+ /// Only compiled with `efb-writeback`. The default no-feature path+ /// handles CopyEfbToTexture inline in `action.rs` with just a clear.+ #[cfg(feature = "efb-writeback")]pub(crate) fn execute_copy_efb_to_texture(&mut self,device: &wgpu::Device,diff --git a/crates/backend-wgpu/src/sink.rs b/crates/backend-wgpu/src/sink.rsindex 773bd28..aa2c9c4 100644--- a/crates/backend-wgpu/src/sink.rs+++ b/crates/backend-wgpu/src/sink.rs@@ -1,6 +1,8 @@use crate::GxRenderer;use crossbeam_channel::{Receiver, Sender, bounded};-use gecko::host::{EfbWriteback, GxAction, RenderSink};+#[cfg(feature = "efb-writeback")]+use gecko::host::EfbWriteback;+use gecko::host::{GxAction, RenderSink};use std::sync::{Arc, Mutex};const CHANNEL_CAPACITY: usize = 8192;@@ -35,7 +37,9 @@ pub struct Renderer {/// Receiver end of the EFB-to-texture writeback channel. Taken by the/// emulator setup code (via [`Renderer::take_writeback_rx`]) and/// installed into `GraphicsProcessor::efb_writeback_rx`. Wrapped in- /// `Arc<Mutex<Option<_>>>` so `Renderer` stays `Clone`.+ /// `Arc<Mutex<Option<_>>>` so `Renderer` stays `Clone`. Only built when+ /// `efb-writeback` is enabled.+ #[cfg(feature = "efb-writeback")]writeback_rx: Arc<Mutex<Option<Receiver<EfbWriteback>>>>,}@@ -43,12 +47,20 @@ impl Renderer {/// Create the renderer, spawning the worker thread. The caller must/// provide a wgpu device and queue.pub fn new(device: wgpu::Device, queue: wgpu::Queue, surface_format: wgpu::TextureFormat) -> Self {+ #[cfg(feature = "efb-writeback")]let mut gx = GxRenderer::new(&device, &queue, surface_format);+ #[cfg(not(feature = "efb-writeback"))]+ let gx = GxRenderer::new(&device, &queue, surface_format);// Writeback channel: GxRenderer sends encoded EFB-to-texture bytes,// GraphicsProcessor consumes them synchronously on the emu thread.- let (writeback_tx, writeback_rx) = bounded::<EfbWriteback>(CHANNEL_CAPACITY);- gx.set_efb_writeback_tx(writeback_tx);+ // Only created with `efb-writeback`.+ #[cfg(feature = "efb-writeback")]+ let writeback_rx = {+ let (writeback_tx, writeback_rx) = bounded::<EfbWriteback>(CHANNEL_CAPACITY);+ gx.set_efb_writeback_tx(writeback_tx);+ writeback_rx+ };// Initial shared output: the XFB view (black until first PresentXfb).let shared = Arc::new(Shared {@@ -139,13 +151,16 @@ impl Renderer {blit_pipeline,blit_bind_group_layout,blit_sampler,+ #[cfg(feature = "efb-writeback")]writeback_rx: Arc::new(Mutex::new(Some(writeback_rx))),}}/// Take the writeback receiver once. Returns `Some` on the first call,/// `None` thereafter. The caller installs it into- /// `GraphicsProcessor::efb_writeback_rx`.+ /// `GraphicsProcessor::efb_writeback_rx`. Only available when the+ /// `efb-writeback` feature is enabled.+ #[cfg(feature = "efb-writeback")]pub fn take_writeback_rx(&self) -> Option<Receiver<EfbWriteback>> {self.writeback_rx.lock().ok()?.take()}diff --git a/crates/debugger/Cargo.toml b/crates/debugger/Cargo.tomlindex 009c71d..4564f86 100644--- a/crates/debugger/Cargo.toml+++ b/crates/debugger/Cargo.toml@@ -6,6 +6,7 @@ edition = "2024"[features]idle-skip = ["gecko/idle-skip"]hooks-mut-traps = ["gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]+efb-writeback = ["backend-wgpu/efb-writeback", "gecko/efb-writeback"][dependencies]gecko = { path = "../gecko", features = ["hooks"] }diff --git a/crates/debugger/src/main.rs b/crates/debugger/src/main.rsindex fd6d883..eb460a8 100644--- a/crates/debugger/src/main.rs+++ b/crates/debugger/src/main.rs@@ -237,8 +237,11 @@ fn main() {// Install the renderer as the emulator's render sink.emulator.render_sink = Box::new(renderer.clone());- // Install the EFB-to-texture writeback receiver.- emulator.gx.efb_writeback_rx = renderer.take_writeback_rx();+ // Install the EFB-to-texture writeback receiver. Feature-gated.+ #[cfg(feature = "efb-writeback")]+ {+ emulator.gx.efb_writeback_rx = renderer.take_writeback_rx();+ }let ui = DebuggerUi {symbols,diff --git a/crates/gecko/Cargo.toml b/crates/gecko/Cargo.tomlindex 86c0ba8..4409777 100644--- a/crates/gecko/Cargo.toml+++ b/crates/gecko/Cargo.toml@@ -7,6 +7,11 @@ edition = "2024"idle-skip = []hooks = []hooks-mut-traps = ["hooks"]+# Full EFB-to-texture writeback: the renderer reads the EFB back, encodes+# it in the GX copy format, and ships the bytes over a channel to the emu+# thread which copies them into `Mmio::ram` synchronously. Expensive (GPU+# stall, encode, RAM copy).+efb-writeback = ["dep:crossbeam-channel"][build-dependencies]chipi-build = "0.8.2"@@ -18,4 +23,4 @@ image = { path = "../image", default-features = false }glam = { version = "0.32.1", features = ["bytemuck"] }bytemuck = { version = "1.25.0", features = ["derive"] }twox-hash = "2.1.2"-crossbeam-channel = "0.5.15"+crossbeam-channel = { version = "0.5.15", optional = true }diff --git a/crates/gecko/src/flipper/gx.rs b/crates/gecko/src/flipper/gx.rsindex e5fd927..72535e2 100644--- a/crates/gecko/src/flipper/gx.rs+++ b/crates/gecko/src/flipper/gx.rs@@ -14,7 +14,9 @@ use crate::flipper::gx::constants::{BP_REG_SIZE, CP_REG_SIZE, XF_MEM_SIZE};use crate::flipper::gx::draw::Matrix4;use crate::flipper::gx::regs::{AlphaCompare, BlendMode, TevAlphaEnv, TevColorEnv, TevRegisterH, TevRegisterL, ZMode};use crate::gamecube::GameCube;-use crate::host::{EfbWriteback, GxAction, RenderSink, XfbPart};+#[cfg(feature = "efb-writeback")]+use crate::host::EfbWriteback;+use crate::host::{GxAction, RenderSink, XfbPart};use crate::mmio::Mmio;use fifo::FifoCmd;use std::collections::HashMap;@@ -61,7 +63,8 @@ pub struct GraphicsProcessor {// renderer worker. `efb_copy` drains this synchronously right after// emitting the copy action, so the next FIFO command in the same burst// (usually a `TX_SETIMAGE3` that samples the just-written region)- // sees fresh RAM.+ // sees fresh RAM. Only present when the `efb-writeback` feature is on.+ #[cfg(feature = "efb-writeback")]pub efb_writeback_rx: Option<crossbeam_channel::Receiver<EfbWriteback>>,}@@ -103,6 +106,7 @@ impl GraphicsProcessor {cur_scissor_offset_y: 0,xfb_copies: Vec::new(),texture_hashes: HashMap::new(),+ #[cfg(feature = "efb-writeback")]efb_writeback_rx: None,}}diff --git a/crates/gecko/src/flipper/gx/bp.rs b/crates/gecko/src/flipper/gx/bp.rsindex 35799a0..7540046 100644--- a/crates/gecko/src/flipper/gx/bp.rs+++ b/crates/gecko/src/flipper/gx/bp.rs@@ -14,6 +14,7 @@ use super::regs::{use super::{GraphicsProcessor, draw, texture};use crate::common::Address;use crate::host::{GxAction, RenderSink};+#[cfg(feature = "efb-writeback")]use std::time::Duration;impl GraphicsProcessor {@@ -357,11 +358,21 @@ impl GraphicsProcessor {z_update,});- // Block until the renderer finishes the readback + encode and- // ships the encoded bytes back. This preserves ordering with- // subsequent FIFO commands (e.g. a TX_SETIMAGE3 at `dest_addr`- // immediately after this copy): by the time efb_copy returns,- // RAM is up to date and the next texture load re-hashes.+ // Default path (feature off): the renderer doesn't do a readback+ // and RAM at `dest_addr` is not modified, so "invalidating" the+ // texture at that address means dropping the hash so the next+ // `TX_SETIMAGE3` forces a fresh re-decode + re-upload. That+ // evicts any stale GPU texture / bind groups tied to the old+ // cache entry.+ self.texture_hashes.remove(&dest_addr);+ let _ = ram;++ // With `efb-writeback`: block until the renderer finishes the+ // readback + encode and ships the encoded bytes back. This+ // preserves ordering with subsequent FIFO commands (a+ // `TX_SETIMAGE3` at `dest_addr` immediately after this copy+ // sees up-to-date RAM + a freshly re-hashable texture).+ #[cfg(feature = "efb-writeback")]if let Some(rx) = &self.efb_writeback_rx {match rx.recv_timeout(Duration::from_secs(2)) {Ok(wb) => {@@ -369,7 +380,6 @@ impl GraphicsProcessor {let end = start + wb.bytes.len();if end <= ram.len() {ram[start..end].copy_from_slice(&wb.bytes);- self.texture_hashes.remove(&wb.dest_addr);} else {tracing::warn!(addr = format!("{:#010X}", wb.dest_addr),diff --git a/crates/gecko/src/host.rs b/crates/gecko/src/host.rsindex d951065..6d7df6d 100644--- a/crates/gecko/src/host.rs+++ b/crates/gecko/src/host.rs@@ -98,6 +98,9 @@ pub enum GxAction {/// an EFB-to-texture copy completes. The emu thread copies `bytes` into/// `Mmio::ram` at `dest_addr` and invalidates the texture-hash cache so the/// next `TX_SETIMAGE3` at that address re-decodes.+///+/// Only compiled when the `efb-writeback` feature is enabled.+#[cfg(feature = "efb-writeback")]#[derive(Debug)]pub struct EfbWriteback {pub dest_addr: Address,diff --git a/crates/tinyapp/Cargo.toml b/crates/tinyapp/Cargo.tomlindex 0b59b21..432cb23 100644--- a/crates/tinyapp/Cargo.toml+++ b/crates/tinyapp/Cargo.toml@@ -7,6 +7,7 @@ edition = "2024"idle-skip = ["gecko/idle-skip"]scripting = ["gecko/hooks", "dep:scripting"]scripting-mut-traps = ["scripting", "gecko/hooks-mut-traps", "scripting/hooks-mut-traps"]+efb-writeback = ["backend-wgpu/efb-writeback", "gecko/efb-writeback"][dependencies]gecko = { path = "../gecko" }diff --git a/crates/tinyapp/src/main.rs b/crates/tinyapp/src/main.rsindex c64bc92..06be611 100644--- a/crates/tinyapp/src/main.rs+++ b/crates/tinyapp/src/main.rs@@ -140,7 +140,11 @@ fn main() {// Install the EFB-to-texture writeback receiver so the emu thread// can copy encoded texture bytes back into RAM after each readback.- emulator.gx.efb_writeback_rx = renderer.take_writeback_rx();+ // Only present with the `efb-writeback` feature.+ #[cfg(feature = "efb-writeback")]+ {+ emulator.gx.efb_writeback_rx = renderer.take_writeback_rx();+ }let input = Arc::new(Mutex::new(*emulator.primary_controller_mut()));