Skip to content

armgit / gecko

Public Imported from GitHub
0

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.toml
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.toml
index 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.rs
index 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.toml
index 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.rs
index 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.rs
index 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.rs
index 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.toml
index 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.rs
index 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()));