GPU culling

lib/examples/demo.rs

@@ -61,6 +61,8 @@ fn stripes_rgba() -> Vec<u8> {
 struct Demo {
     camera: CameraController,
     angle: f32,
+    /// Phase 3 black-window investigation: number of debug_dump calls already made.
+    dbg: u32,
 }
 
 /// Horizontal radius at which the primitives sit around the origin.
@@ -222,13 +224,40 @@ impl AppHandler for Demo {
         tf.rotation = Quat::from_rotation_y(self.angle) * Quat::from_rotation_x(self.angle * 0.4);
         app.scene.set_entity_transform("cube_e", tf);
     }
+
+    fn render(&mut self, app: &mut wsg_lib::App, frame: &wsg_lib::core::Frame) {
+        app.render_scene(frame.view());
+        // Opt-in GPU readback (black-window investigation tooling): WSG_DEBUG_DUMP=N dumps the
+        // first 8 slots of the transform/matrix/draw-args/bbox buffers for N frames (unset = silent,
+        // non-numeric value = 3 frames). Note: orbiting/zooming this camera
+        // can never cull the entity ring — the camera always looks at the origin, so each
+        // entity's angular offset from the view axis is bounded by atan(1.7/6.1) ≈ 15.5°, under
+        // the ~22° vertical half-FOV (verified 2026-09-22: 600 frames swept, GPU==CPU on all
+        // 6000 cull verdicts, zero flips on the ring). Counts only flip to 0 for entities far
+        // off-axis (e.g. behind the near plane) — see docs/user/gpu-driven.md.
+        // Unset → 0 (the showcase stays silent); set but non-numeric (e.g. `WSG_DEBUG_DUMP=on`) → 3.
+        let frames = match std::env::var("WSG_DEBUG_DUMP") {
+            Ok(v) => v.parse::<u32>().ok().filter(|&n| n > 0).unwrap_or(3),
+            Err(_) => 0,
+        };
+        if self.dbg < frames {
+            self.dbg += 1;
+            app.renderer().debug_dump(8);
+        }
+    }
 }
 
 #[pollster::main]
 async fn main() -> Result<(), WsgError> {
-    let app = AppBuilder::new().title("WSG Demo").build().await?;
+    // Culling enabled here (Step 15, D8) to exercise the GPU path; it is OFF by default elsewhere.
+    let app = AppBuilder::new()
+        .title("WSG Demo")
+        .with_culling(true)
+        .build()
+        .await?;
     app.run(Demo {
         camera: CameraController::default(),
         angle: 0.0,
+        dbg: 0,
     })
 }