cranpose_render_wgpu/

lib.rs

#![doc = include_str!("../README.md")]

pub(crate) use cranpose_render_common::debug_toggles;
pub use debug_toggles::{
    DebugToggle, debug_toggle, debug_toggle_os, set_debug_toggle, set_debug_toggle_os,
};
pub use offscreen::COMPOSITION_BYTES_PER_PIXEL;
pub use render::presentable_root_usages;
mod ablation;
mod arc_trig_fill;
mod capture_hash;
mod collect;
mod draw_pass;
mod effect_renderer;
mod fast_cores;
mod frame;
mod geometry;
mod idle_pool;
mod layer_cache;
pub use fast_cores::pin_current_thread_to_fast_cores;
mod fixed_pipeline;
mod frame_graph;
mod frame_packet;
mod frontend;
mod glass_split;
#[cfg(test)]
#[path = "tests/gles_lowering.rs"]
mod gles_lowering;
mod glyph_run;
mod glyph_run_arena;
pub(crate) mod gpu_stats;
mod initial_present;
mod lazy_resource;
mod offscreen;
mod opaque_prefix;
mod output_conversion;
pub(crate) mod pass_timing;
mod pipeline;
mod pipeline_compiler;
#[cfg(not(target_arch = "wasm32"))]
pub mod pipeline_disk_cache;
mod pipeline_recorder;
#[cfg(not(target_arch = "wasm32"))]
mod pipeline_records;
#[cfg(not(target_arch = "wasm32"))]
mod present_runtime;
mod record_columns;
mod render;
mod rrect_shadow;
mod run_geometry;
mod run_store;
mod scene;
mod shader_cache;
mod shaders;
mod shape_pipelines;
mod shared_shader;
#[cfg(test)]
mod test_support;

use std::{rc::Rc, sync::Arc};

use cranpose_core::{MemoryApplier, NodeId};
use cranpose_render_common::{
    RenderScene, Renderer,
    graph::RenderGraph,
    software_text_raster::{
        SoftwareTextFontSet, SoftwareTextMeasurer, software_text_font_set_from_fonts_or_default,
    },
};
use cranpose_ui::{LayoutTree, TextMeasurer};
use cranpose_ui_graphics::{Rect, Size};
pub use frame_packet::PresentTimings;

/// Platform code the present thread runs around every present to a surface,
/// for what only the platform can do with its swapchain, such as asking the
/// display when earlier frames reached the screen.
#[cfg(not(target_arch = "wasm32"))]
pub trait PresentObserver: Send {
    /// Runs just before `surface` presents a frame.
    fn before_present(&mut self, surface: &wgpu::Surface<'static>);
    /// Runs just after `surface` presented it.
    fn after_present(&mut self, surface: &wgpu::Surface<'static>);

    /// Runs before `surface` is configured anew, while its current swapchain
    /// still stands. Does nothing unless the platform needs it to.
    fn before_reconfigure(&mut self, _surface: &wgpu::Surface<'static>) {}
}
use frame_packet::RenderReturns;
#[doc(hidden)]
pub use frame_packet::{CancelReason, PresentOutcome};
use frontend::{DevOverlayCache, RendererFrontend};
pub use gpu_stats::FrameStatsSnapshot as RenderStatsSnapshot;
pub use initial_present::{clear_to_background, clear_to_default_background};
pub use pass_timing::{GpuPassTimingEntry, GpuPassTimingReport};
use pipeline_compiler::PipelineCompilation;
#[cfg(not(target_arch = "wasm32"))]
use present_runtime::{
    PresentControl, PresentHandle, PresentMsg, PresentRuntimeInit, PresentState,
};
use render::{GpuRenderer, GpuRendererInit};
pub use render::{
    frame_clear_color, frames_presented, pipelines_created, pipelines_created_off_frame,
};
pub use scene::{HitRegion, Scene};

/// The optional device features the renderer exploits when the adapter
/// offers them: pipeline caching (see `pipeline_disk_cache`), the
/// timestamp queries behind `CRANPOSE_GPU_PASS_TIMING`, and, on a GPU
/// that shares the host's memory, vertex and uniform buffers the CPU
/// writes directly, so a frame's uploads need no copy. Every platform's
/// `request_device` passes this so a profiling toggle never needs a rebuilt
/// binary; intersecting with the adapter's own features keeps the request
/// valid on adapters without them.
pub fn optional_device_features(adapter: &wgpu::Adapter) -> wgpu::Features {
    let mut wanted = wgpu::Features::PIPELINE_CACHE | wgpu::Features::TIMESTAMP_QUERY;
    if matches!(
        adapter.get_info().device_type,
        wgpu::DeviceType::IntegratedGpu | wgpu::DeviceType::Cpu
    ) {
        wanted |= wgpu::Features::MAPPABLE_PRIMARY_BUFFERS;
    }
    adapter.features() & wanted
}

#[doc(hidden)]
pub fn offscreen_render_target_for_tests(
    device: &wgpu::Device,
    width: u32,
    height: u32,
    label: &str,
) -> (wgpu::Texture, wgpu::TextureView) {
    let texture = offscreen::create_2d_texture(
        device,
        wgpu::TextureFormat::Rgba8Unorm,
        width,
        height,
        wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
        Some(label),
    );
    let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
    (texture, view)
}

pub(crate) fn rect_to_quad(rect: Rect) -> [[f32; 2]; 4] {
    [
        [rect.x, rect.y],
        [rect.x + rect.width, rect.y],
        [rect.x, rect.y + rect.height],
        [rect.x + rect.width, rect.y + rect.height],
    ]
}

#[derive(Debug)]
pub enum WgpuRendererError {
    Layout(String),
    Wgpu(String),
}

/// CPU-readable RGBA frame captured from the renderer output.
#[derive(Debug, Clone)]
pub struct CapturedFrame {
    pub width: u32,
    pub height: u32,
    pub pixels: Vec<u8>,
}

#[doc(hidden)]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DebugCpuAllocationStats {
    pub scene_graph_node_count: usize,
    pub scene_graph_heap_bytes: usize,
    pub scene_hits_len: usize,
    pub scene_hits_cap: usize,
    pub scene_node_index_len: usize,
    pub scene_node_index_cap: usize,
    pub text_renderer_pool_len: usize,
    pub text_renderer_pool_cap: usize,
    pub image_texture_cache_len: usize,
    pub image_texture_cache_cap: usize,
    pub run_arena_staging_bytes: usize,
    pub run_store_bytes: usize,
    pub run_store_runs: usize,
    pub scratch_image_vertices_cap: usize,
    pub scratch_image_indices_cap: usize,
    pub scratch_image_cmds_cap: usize,
    pub scratch_glyph_instances_cap: usize,
    pub layer_cache_len: usize,
    pub layer_cache_bytes: u64,
}

/// The device a renderer draws with and the surface format it presents.
struct GpuTarget {
    device: Arc<wgpu::Device>,
    queue: Arc<wgpu::Queue>,
    surface_format: wgpu::TextureFormat,
    adapter_backend: wgpu::Backend,
    adapter_downlevel: wgpu::DownlevelFlags,
}

pub(crate) struct TextSystemState {
    measurer: SoftwareTextMeasurer,
}

impl TextSystemState {
    fn from_font_set(fonts: SoftwareTextFontSet) -> Self {
        Self {
            measurer: SoftwareTextMeasurer::from_font_set(fonts, 8192),
        }
    }

    pub(crate) fn text_cache_len(&self) -> usize {
        0
    }
}

impl pipeline::TextLayoutResolver for TextSystemState {
    fn layout_text(
        &mut self,
        text: &cranpose_ui::text::AnnotatedString,
        style: &cranpose_ui::text::TextStyle,
    ) -> cranpose_ui::text_layout_result::TextLayoutResult {
        if cranpose_ui::has_current_app_context() {
            cranpose_ui::text::layout_text(text, style)
        } else {
            self.measurer.layout(text, style)
        }
    }
}

#[derive(Clone)]
pub struct WgpuTextSystem {
    software_fonts: SoftwareTextFontSet,
}

impl WgpuTextSystem {
    pub fn from_fonts(fonts: &[&'static [u8]]) -> Self {
        Self {
            software_fonts: software_text_font_set_from_fonts_or_default(fonts),
        }
    }

    /// Adopt a font set an app already built — the path app-supplied families
    /// take, where faces were parsed once at startup rather than from static
    /// byte slices here.
    pub fn from_font_set(software_fonts: SoftwareTextFontSet) -> Self {
        Self { software_fonts }
    }

    pub(crate) fn render_state(&self) -> TextSystemState {
        TextSystemState::from_font_set(self.software_fonts.clone())
    }

    pub(crate) fn software_fonts(&self) -> SoftwareTextFontSet {
        self.software_fonts.clone()
    }
}

/// Create an accurate WGPU text measurer for headless tests without launching a window.
pub fn headless_text_measurer() -> Rc<dyn TextMeasurer> {
    headless_text_measurer_with_fonts(&[])
}

/// Create an accurate WGPU text measurer for headless tests with explicit fonts.
pub fn headless_text_measurer_with_fonts(fonts: &[&'static [u8]]) -> Rc<dyn TextMeasurer> {
    Rc::new(SoftwareTextMeasurer::from_fonts_or_default(fonts, 8192))
}

enum PresentBackend {
    None,
    Sync(Box<GpuRenderer>),
    #[cfg(not(target_arch = "wasm32"))]
    Threaded(PresentHandle),
}

/// What [`WgpuRenderer::publish_frame`] did.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PublishOutcome {
    /// No scene graph exists; nothing to lower.
    NoGraph,
    /// The depth-one slot is occupied (or the renderer is not in threaded
    /// mode): NO packet was built — backpressure lands before lowering.
    NoCredit,
    /// A packet was built and handed to the present runtime.
    Published,
}

/// WGPU-based renderer for GPU-accelerated 2D rendering.
///
/// This renderer supports:
/// - GPU-accelerated shape rendering (rectangles, rounded rectangles)
/// - Gradients (solid, linear, radial)
/// - GPU text rendering via retained raster image batches
/// - Cross-platform support (Desktop, Web, Android)
pub struct WgpuRenderer {
    frontend: RendererFrontend,
    backend: PresentBackend,
    renderer_epoch: u64,
    surface_epoch: u64,
}

impl WgpuRenderer {
    /// Create a new WGPU renderer.
    ///
    /// * `fonts` – font bytes to load, ordered by priority (first = highest priority).
    ///   Pass `&[]` to load no fonts; text will not render until fonts are provided.
    ///
    /// Call [`init_gpu`][Self::init_gpu] before rendering.
    pub fn new(fonts: &[&'static [u8]]) -> Self {
        Self::with_text_system(WgpuTextSystem::from_fonts(fonts))
    }

    /// Create a renderer over an already-parsed font set.
    ///
    /// Measurement and rasterization both take clones of this one set, so an
    /// app-supplied family resolves identically on both sides.
    pub fn with_font_set(fonts: SoftwareTextFontSet) -> Self {
        Self::with_text_system(WgpuTextSystem::from_font_set(fonts))
    }

    pub fn with_text_system(text_system: WgpuTextSystem) -> Self {
        Self {
            frontend: RendererFrontend::new(
                text_system.render_state(),
                text_system.software_fonts(),
            ),
            backend: PresentBackend::None,
            renderer_epoch: 0,
            surface_epoch: 0,
        }
    }

    fn sync_gpu_renderer(&self) -> Option<&GpuRenderer> {
        match &self.backend {
            PresentBackend::Sync(gpu_renderer) => Some(gpu_renderer.as_ref()),
            _ => None,
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    fn present_handle_mut(&mut self) -> Option<&mut PresentHandle> {
        match &mut self.backend {
            PresentBackend::Threaded(handle) => Some(handle),
            _ => None,
        }
    }

    fn retire_live_backend(&mut self) {
        #[allow(unused_mut)]
        let mut backend = std::mem::replace(&mut self.backend, PresentBackend::None);
        #[cfg(not(target_arch = "wasm32"))]
        if let PresentBackend::Threaded(handle) = &mut backend {
            while let Some(returns) = handle.try_drain() {
                self.frontend.apply_returns(returns);
            }
            handle.shutdown();
        }
        drop(backend);
    }

    /// Initialize GPU resources with a WGPU device and queue.
    ///
    /// Replacing a live renderer (Android surface recreation, device loss)
    /// bumps the renderer epoch, so a packet built against the previous
    /// renderer is cancelled instead of drawn.
    pub fn init_gpu(
        &mut self,
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        surface_format: wgpu::TextureFormat,
        adapter_backend: wgpu::Backend,
        adapter_downlevel: wgpu::DownlevelFlags,
    ) {
        let target = GpuTarget {
            device,
            queue,
            surface_format,
            adapter_backend,
            adapter_downlevel,
        };
        self.install_gpu(target, PipelineCompilation::Background);
    }

    /// [`init_gpu`][Self::init_gpu], compiling every pipeline where it is
    /// first needed instead of on the background compiler: no frame draws
    /// with a stand-in, which a reference frame in a test must not.
    #[doc(hidden)]
    pub fn init_gpu_compiling_inline_for_tests(
        &mut self,
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        surface_format: wgpu::TextureFormat,
        adapter_backend: wgpu::Backend,
        adapter_downlevel: wgpu::DownlevelFlags,
    ) {
        let target = GpuTarget {
            device,
            queue,
            surface_format,
            adapter_backend,
            adapter_downlevel,
        };
        self.install_gpu(target, PipelineCompilation::Inline);
    }

    fn install_gpu(&mut self, target: GpuTarget, pipeline_compilation: PipelineCompilation) {
        let init = self.next_gpu_init(target, pipeline_compilation);
        self.backend = PresentBackend::Sync(Box::new(GpuRenderer::new(init)));
    }

    /// Retires the live backend and bumps the renderer epoch, then describes
    /// the renderer that replaces it on `target`.
    fn next_gpu_init(
        &mut self,
        target: GpuTarget,
        pipeline_compilation: PipelineCompilation,
    ) -> GpuRendererInit {
        self.retire_live_backend();
        self.renderer_epoch = self.renderer_epoch.wrapping_add(1);
        GpuRendererInit {
            device: target.device,
            queue: target.queue,
            surface_format: target.surface_format,
            adapter_backend: target.adapter_backend,
            adapter_downlevel: target.adapter_downlevel,
            text_fonts: self.frontend.text_fonts.clone(),
            renderer_epoch: self.renderer_epoch,
            pipeline_compilation,
        }
    }

    /// [`init_gpu`][Self::init_gpu] for the threaded present runtime
    /// (Android): the same epoch bump and planner replacement hygiene, but
    /// instead of constructing a `GpuRenderer` here, everything it needs —
    /// all owned, all `Send` — crosses to a spawned present thread that
    /// constructs its own (its `Rc` caches are thread-confined). Frames
    /// then flow through [`publish_frame`][Self::publish_frame] /
    /// [`drain_present_returns`][Self::drain_present_returns] under the
    /// depth-one credit protocol instead of [`render`][Self::render].
    ///
    /// * `waker` — wakes the producer's event loop after every returns
    ///   send (the Android frame waker).
    /// * `clock` — producer's monotonic nanosecond clock, so present-side
    ///   [`PresentTimings`] share the producer telemetry's clock domain;
    ///   `None` leaves timings at zero.
    /// * `observer` — runs on the present thread around every present to the
    ///   surface.
    #[cfg(not(target_arch = "wasm32"))]
    #[expect(clippy::too_many_arguments)]
    pub fn init_gpu_threaded(
        &mut self,
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        surface_format: wgpu::TextureFormat,
        adapter_backend: wgpu::Backend,
        adapter_downlevel: wgpu::DownlevelFlags,
        waker: Arc<dyn Fn() + Send + Sync>,
        clock: Option<Arc<dyn Fn() -> i64 + Send + Sync>>,
        observer: Option<Box<dyn PresentObserver>>,
    ) -> Result<(), WgpuRendererError> {
        let target = GpuTarget {
            device,
            queue,
            surface_format,
            adapter_backend,
            adapter_downlevel,
        };
        let init = PresentRuntimeInit {
            gpu: self.next_gpu_init(target, PipelineCompilation::Background),
            clock,
            observer,
        };
        let handle = PresentHandle::spawn(init, waker).map_err(WgpuRendererError::Wgpu)?;
        self.backend = PresentBackend::Threaded(handle);
        Ok(())
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn init_gpu_inline_for_tests(
        &mut self,
        device: Arc<wgpu::Device>,
        queue: Arc<wgpu::Queue>,
        surface_format: wgpu::TextureFormat,
        adapter_backend: wgpu::Backend,
        adapter_downlevel: wgpu::DownlevelFlags,
    ) -> InlinePresentRuntime {
        let target = GpuTarget {
            device,
            queue,
            surface_format,
            adapter_backend,
            adapter_downlevel,
        };
        let init = PresentRuntimeInit {
            gpu: self.next_gpu_init(target, PipelineCompilation::Background),
            clock: None,
            observer: None,
        };
        let (handle, state, msg_rx) = PresentHandle::new_inline(init, Arc::new(|| {}));
        self.backend = PresentBackend::Threaded(handle);
        InlinePresentRuntime {
            state,
            msg_rx,
            shutdown_seen: false,
        }
    }

    /// Record that the surface was reconfigured (resize, format change,
    /// swapchain recreation): bumps the surface epoch stamped into every
    /// subsequent packet, so a packet built against the previous
    /// configuration is cancelled by the present stage instead of drawn.
    pub fn note_surface_reconfigured(&mut self) {
        self.surface_epoch = self.surface_epoch.wrapping_add(1);
    }

    /// Clears each frame to nothing instead of the framework's background,
    /// for a window whose surface composites with the desktop behind it. A
    /// renderer starts opaque; `false` puts the background back. Takes
    /// effect from the next frame, on either present backend.
    pub fn set_transparent_background(&mut self, transparent: bool) {
        self.frontend.transparent_background = transparent;
    }

    pub fn root_scale(&self) -> f32 {
        self.frontend.root_scale
    }

    /// Render the scene to a texture view.
    ///
    /// Producer first, present second: the frontend collects the frame into
    /// a `frame_packet::FramePacket` (root and dev overlay alike), the GPU
    /// renderer consumes it, and the present stage's returns fold back into
    /// the frontend afterwards.
    pub fn render(
        &mut self,
        texture: &wgpu::Texture,
        view: &wgpu::TextureView,
        width: u32,
        height: u32,
    ) -> Result<(), WgpuRendererError> {
        self.render_frame(texture, view, width, height)
    }

    /// Renders the frame into a presentable image. When the image carries the
    /// composition format and the capture usages, the scene renders into it
    /// directly and no output conversion pass runs.
    pub fn render_surface_texture(
        &mut self,
        texture: &wgpu::Texture,
        view: &wgpu::TextureView,
        width: u32,
        height: u32,
    ) -> Result<(), WgpuRendererError> {
        self.render_frame(texture, view, width, height)
    }

    /// Presents a surface image this renderer drew with
    /// [`render_surface_texture`](Self::render_surface_texture), on the queue
    /// that recorded it.
    ///
    /// Before [`init_gpu`](Self::init_gpu) there is no queue, and the image is
    /// released without being shown.
    pub fn present(&self, frame: wgpu::SurfaceTexture) {
        match self.sync_gpu_renderer() {
            Some(gpu_renderer) => gpu_renderer.queue.present(frame),
            None => log::debug!("surface image released: the renderer has no GPU queue"),
        }
    }

    fn render_frame(
        &mut self,
        texture: &wgpu::Texture,
        view: &wgpu::TextureView,
        width: u32,
        height: u32,
    ) -> Result<(), WgpuRendererError> {
        let PresentBackend::Sync(gpu_renderer) = &mut self.backend else {
            return Err(WgpuRendererError::Wgpu(
                "GPU renderer not initialized for synchronous rendering. Call init_gpu() first."
                    .to_string(),
            ));
        };
        let packet = self
            .frontend
            .build_frame_packet(width, height, self.renderer_epoch, self.surface_epoch)
            .ok_or_else(|| WgpuRendererError::Wgpu("scene graph is missing".to_string()))?;
        let mut returns = RenderReturns::default();
        let result = gpu_renderer.render(
            texture,
            view,
            width,
            height,
            packet,
            self.surface_epoch,
            &mut returns,
        );
        self.frontend.apply_returns(returns);
        result.map_err(WgpuRendererError::Wgpu)
    }

    /// Render the current scene into an RGBA pixel buffer for robot tests.
    ///
    /// Uses the renderer's configured root scale.
    pub fn capture_frame(
        &mut self,
        width: u32,
        height: u32,
    ) -> Result<CapturedFrame, WgpuRendererError> {
        self.capture_frame_with_scale(width, height, self.frontend.root_scale)
    }

    /// Render the current scene into an RGBA pixel buffer with an explicit scale.
    /// Builds every pipeline the pipeline cache file records on the
    /// background compiler, and returns whether they were all built before
    /// `timeout`, or before `stop` said to stop. An app runs it after an
    /// update, before its next launch, so that launch finds them compiled;
    /// the renderer writes the file when it is dropped, and drops the builds
    /// not started. It draws nothing, and needs a renderer initialized for
    /// synchronous rendering.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn prepare_recorded_pipelines(
        &mut self,
        timeout: std::time::Duration,
        stop: &dyn Fn() -> bool,
    ) -> bool {
        let PresentBackend::Sync(gpu_renderer) = &mut self.backend else {
            return false;
        };
        let deadline = web_time::Instant::now() + timeout;
        let mut compiling = gpu_renderer.prepare_recorded();
        while compiling {
            if web_time::Instant::now() >= deadline || stop() {
                return false;
            }
            std::thread::sleep(std::time::Duration::from_millis(10));
            compiling = gpu_renderer.compiling();
        }
        true
    }

    pub fn capture_frame_with_scale(
        &mut self,
        width: u32,
        height: u32,
        root_scale: f32,
    ) -> Result<CapturedFrame, WgpuRendererError> {
        let PresentBackend::Sync(gpu_renderer) = &mut self.backend else {
            return Err(WgpuRendererError::Wgpu(
                "GPU renderer not initialized for synchronous rendering. Call init_gpu() first."
                    .to_string(),
            ));
        };
        let packet = self
            .frontend
            .build_frame_packet_with_scale(
                width,
                height,
                root_scale,
                self.renderer_epoch,
                self.surface_epoch,
            )
            .ok_or_else(|| WgpuRendererError::Wgpu("scene graph is missing".to_string()))?;
        let mut returns = RenderReturns::default();
        let result = gpu_renderer.render_to_rgba_pixels(
            width,
            height,
            packet,
            self.surface_epoch,
            &mut returns,
        );
        self.frontend.apply_returns(returns);
        let pixels = result.map_err(WgpuRendererError::Wgpu)?;
        Ok(CapturedFrame {
            width,
            height,
            pixels,
        })
    }

    /// Threaded mode: whether the depth-one slot has room for a packet.
    /// The Android loop checks this BEFORE `shell.update()` so
    /// backpressure lands before the expensive update/lowering work.
    /// Always `true` on the sync path, which has no slot to fill.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn has_frame_credit(&self) -> bool {
        match &self.backend {
            PresentBackend::Threaded(handle) => handle.has_credit(),
            PresentBackend::Sync(_) | PresentBackend::None => true,
        }
    }

    /// Threaded mode: whether the present thread has handed back a frame
    /// that [`drain_present_returns`][Self::drain_present_returns] has not
    /// folded back yet, so draining it would free a publish credit. A loop
    /// out of credit can work on other things until this turns true.
    /// Always `false` outside threaded mode.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn frame_credit_returned(&self) -> bool {
        match &self.backend {
            PresentBackend::Threaded(handle) => handle.has_undrained_return(),
            PresentBackend::Sync(_) | PresentBackend::None => false,
        }
    }

    /// Threaded mode: lower the current scene into a packet and hand it to
    /// the present runtime. Credit is checked FIRST — a `NoCredit` return
    /// means no packet was built at all (`frame_sequence` does not
    /// advance). Returns `NoCredit` (with an error log) when the renderer
    /// is not in threaded mode.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn publish_frame(&mut self, width: u32, height: u32) -> PublishOutcome {
        let PresentBackend::Threaded(handle) = &mut self.backend else {
            log::error!("publish_frame called without a threaded present runtime");
            return PublishOutcome::NoCredit;
        };
        if !handle.has_credit() {
            return PublishOutcome::NoCredit;
        }
        let Some(packet) = self.frontend.build_frame_packet(
            width,
            height,
            self.renderer_epoch,
            self.surface_epoch,
        ) else {
            return PublishOutcome::NoGraph;
        };
        match handle.publish(packet) {
            Ok(()) => PublishOutcome::Published,
            Err(packet) => {
                let mut returns = RenderReturns::default();
                let _ = GpuRenderer::cancel_packet(
                    *packet,
                    CancelReason::SurfaceUnavailable,
                    &mut returns,
                );
                self.frontend.apply_returns(returns);
                log::error!("present runtime unavailable; frame recovered, not published");
                PublishOutcome::NoCredit
            }
        }
    }

    /// Threaded mode: fold every pending `RenderReturns` back into
    /// producer state and free the publish credit. Returns how many were
    /// drained. No-op outside threaded mode.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn drain_present_returns(&mut self) -> usize {
        self.drain_present_returns_with(&mut |_, _, _| {})
    }

    /// [`drain_present_returns`][Self::drain_present_returns], reporting
    /// each drained frame's id, outcome and present-thread timings — the
    /// Android loop feeds its frame telemetry from this.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn drain_present_returns_with(
        &mut self,
        on_return: &mut dyn FnMut(u64, PresentOutcome, PresentTimings),
    ) -> usize {
        let mut drained = 0;
        loop {
            let returns = {
                let PresentBackend::Threaded(handle) = &mut self.backend else {
                    break;
                };
                match handle.try_drain() {
                    Some(returns) => returns,
                    None => break,
                }
            };
            drained += 1;
            let frame_id = returns.frame_id;
            let outcome = returns.outcome;
            let timings = returns.timings;
            self.frontend.apply_returns(returns);
            on_return(frame_id, outcome, timings);
        }
        drained
    }

    /// Threaded mode: install a (re)created surface on the present thread.
    /// Nothing waits for the present thread to set it up: frames published
    /// afterwards queue behind it, so the caller composes its next frame
    /// while the surface is configured. The caller must have bumped the
    /// surface epoch first (`note_surface_reconfigured`
    /// [Self::note_surface_reconfigured]) when the message invalidates
    /// in-flight packets; the message carries the current epoch. Returns
    /// false when the present thread is gone.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn present_replace_surface(
        &mut self,
        surface: wgpu::Surface<'static>,
        config: wgpu::SurfaceConfiguration,
    ) -> bool {
        let surface_epoch = self.surface_epoch;
        let Some(handle) = self.present_handle_mut() else {
            log::error!("present_replace_surface called without a threaded present runtime");
            return false;
        };
        let sent = handle.send_control(PresentControl::ReplaceSurface {
            surface,
            config,
            surface_epoch,
        });
        if !sent {
            log::error!("[present-runtime] replace surface: runtime is gone");
        }
        sent
    }

    /// Threaded mode: reconfigure the present thread's surface (resize)
    /// and wait for the acknowledgement. Same epoch contract as
    /// [`present_replace_surface`][Self::present_replace_surface].
    #[cfg(not(target_arch = "wasm32"))]
    pub fn present_reconfigure(&mut self, config: wgpu::SurfaceConfiguration) -> bool {
        let surface_epoch = self.surface_epoch;
        let Some(handle) = self.present_handle_mut() else {
            log::error!("present_reconfigure called without a threaded present runtime");
            return false;
        };
        handle.send_control_and_wait(
            move |ack| PresentControl::Reconfigure {
                config,
                surface_epoch,
                ack,
            },
            "reconfigure surface",
        )
    }

    /// Threaded mode: drop the present thread's surface (the window died;
    /// the renderer survives for the next one) and wait for the
    /// acknowledgement. Bump the epoch first so in-flight packets cancel.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn present_drop_surface(&mut self) -> bool {
        let Some(handle) = self.present_handle_mut() else {
            log::error!("present_drop_surface called without a threaded present runtime");
            return false;
        };
        handle.send_control_and_wait(|ack| PresentControl::DropSurface { ack }, "drop surface")
    }

    /// Threaded mode: drain outstanding returns, stop the present thread
    /// and join it. The renderer returns to the uninitialized state.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn shutdown_present_runtime(&mut self) {
        if matches!(self.backend, PresentBackend::Threaded(_)) {
            self.retire_live_backend();
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn present_attach_offscreen_for_tests(&mut self, width: u32, height: u32) -> bool {
        let Some(handle) = self.present_handle_mut() else {
            return false;
        };
        handle.send_control_and_wait(
            move |ack| PresentControl::AttachOffscreenTargetForTests { width, height, ack },
            "attach offscreen target",
        )
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn send_attach_offscreen_unacked_for_tests(
        &mut self,
        width: u32,
        height: u32,
    ) -> Option<std::sync::mpsc::Receiver<()>> {
        let handle = self.present_handle_mut()?;
        handle.send_control_unacked(move |ack| PresentControl::AttachOffscreenTargetForTests {
            width,
            height,
            ack,
        })
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn send_reconfigure_unacked_for_tests(
        &mut self,
        config: wgpu::SurfaceConfiguration,
    ) -> Option<std::sync::mpsc::Receiver<()>> {
        let surface_epoch = self.surface_epoch;
        let handle = self.present_handle_mut()?;
        handle.send_control_unacked(move |ack| PresentControl::Reconfigure {
            config,
            surface_epoch,
            ack,
        })
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn send_drop_surface_unacked_for_tests(&mut self) -> Option<std::sync::mpsc::Receiver<()>> {
        let handle = self.present_handle_mut()?;
        handle.send_control_unacked(|ack| PresentControl::DropSurface { ack })
    }

    /// The OS id of the thread that presents frames, once that thread has
    /// started, on systems whose scheduler hints name threads by one.
    /// `None` when frames present on the calling thread.
    pub fn present_thread_id(&self) -> Option<i32> {
        match &self.backend {
            #[cfg(not(target_arch = "wasm32"))]
            PresentBackend::Threaded(handle) => {
                let id = handle
                    .status()
                    .thread_id
                    .load(std::sync::atomic::Ordering::Relaxed);
                (id != 0).then_some(id)
            }
            _ => None,
        }
    }

    /// The producer's monotone packet sequence: the `frame_id` stamped on
    /// the most recently lowered packet. After a `Published` outcome this
    /// is the published frame's id (the Android loop keys its telemetry on
    /// it); it also proves a `NoCredit` publish never lowered a frame.
    pub fn last_published_frame_id(&self) -> u64 {
        self.frontend.frame_sequence
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[doc(hidden)]
    pub fn present_status_snapshot_for_tests(&self) -> Option<(bool, u64, u64)> {
        match &self.backend {
            PresentBackend::Threaded(handle) => {
                let status = handle.status();
                Some((
                    status
                        .needs_frame_warmup
                        .load(std::sync::atomic::Ordering::Relaxed),
                    status
                        .presented_frames
                        .load(std::sync::atomic::Ordering::Relaxed),
                    status
                        .placeholder_frames
                        .load(std::sync::atomic::Ordering::Relaxed),
                ))
            }
            _ => None,
        }
    }

    pub fn last_frame_stats(&self) -> Option<RenderStatsSnapshot> {
        match &self.backend {
            PresentBackend::Sync(gpu_renderer) => gpu_renderer.last_frame_stats(),
            #[cfg(not(target_arch = "wasm32"))]
            PresentBackend::Threaded(handle) => *handle
                .status()
                .last_frame_stats
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner),
            PresentBackend::None => None,
        }
    }

    /// GPU milliseconds by pass label, aggregated since the last `[GPU-PASS]`
    /// print. Empty unless `CRANPOSE_GPU_PASS_TIMING` armed pass timing on a
    /// device with [`wgpu::Features::TIMESTAMP_QUERY`].
    pub fn gpu_pass_timings(&self) -> GpuPassTimingReport {
        self.sync_gpu_renderer()
            .map(GpuRenderer::gpu_pass_timings)
            .unwrap_or_default()
    }

    pub fn debug_cpu_allocation_stats(&self) -> DebugCpuAllocationStats {
        let mut stats = self
            .sync_gpu_renderer()
            .map(GpuRenderer::debug_cpu_allocation_stats)
            .unwrap_or_default();
        stats.scene_graph_node_count = self
            .frontend
            .scene
            .graph
            .as_ref()
            .map_or(0, RenderGraph::node_count);
        stats.scene_graph_heap_bytes = self
            .frontend
            .scene
            .graph
            .as_ref()
            .map_or(0, RenderGraph::heap_bytes);
        stats.scene_hits_len = self.frontend.scene.hits.len();
        stats.scene_hits_cap = self.frontend.scene.hits.capacity();
        stats.scene_node_index_len = self.frontend.scene.node_index.len();
        stats.scene_node_index_cap = self.frontend.scene.node_index.capacity();
        stats
    }

    /// Return the WGPU device when GPU resources are initialized.
    /// Sync backend only (desktop/web reconfigure paths); the threaded
    /// runtime owns its device on the present thread.
    pub fn try_device(&self) -> Option<&wgpu::Device> {
        self.sync_gpu_renderer().map(|r| &*r.device)
    }

    #[doc(hidden)]
    pub fn try_queue_for_tests(&self) -> Option<&wgpu::Queue> {
        self.sync_gpu_renderer().map(|r| &*r.queue)
    }

    #[doc(hidden)]
    pub fn device_error_count_for_tests(&self) -> u64 {
        self.sync_gpu_renderer()
            .map_or(0, GpuRenderer::device_error_count)
    }

    #[doc(hidden)]
    pub fn build_frame_packet_for_tests(
        &mut self,
        width: u32,
        height: u32,
    ) -> Option<HeldFramePacket> {
        self.frontend
            .build_frame_packet(width, height, self.renderer_epoch, self.surface_epoch)
            .map(HeldFramePacket)
    }

    /// Return a producer-built packet without presenting it. This exercises
    /// the same bounded scene-storage recycler used by normal present returns
    /// in offline producer benchmarks.
    ///
    /// ```
    /// use cranpose_render_wgpu::{HeldFramePacket, WgpuRenderer};
    ///
    /// fn return_without_presenting(renderer: &mut WgpuRenderer, packet: HeldFramePacket) {
    ///     renderer.return_held_packet_for_tests(packet);
    /// }
    /// ```
    #[doc(hidden)]
    pub fn return_held_packet_for_tests(&mut self, packet: HeldFramePacket) {
        let packet = packet.0;
        self.frontend.apply_returns(RenderReturns {
            scene: Some(frame_packet::FrameSceneStorage {
                root: packet.root,
                overlay: packet.overlay,
            }),
            frame_id: packet.frame_id,
            ..RenderReturns::default()
        });
    }

    #[doc(hidden)]
    pub fn render_held_packet_for_tests(
        &mut self,
        texture: &wgpu::Texture,
        view: &wgpu::TextureView,
        width: u32,
        height: u32,
        packet: HeldFramePacket,
    ) -> Result<PresentOutcome, WgpuRendererError> {
        let PresentBackend::Sync(gpu_renderer) = &mut self.backend else {
            return Err(WgpuRendererError::Wgpu(
                "GPU renderer not initialized for synchronous rendering. Call init_gpu() first."
                    .to_string(),
            ));
        };
        let mut returns = RenderReturns::default();
        let result = gpu_renderer.render(
            texture,
            view,
            width,
            height,
            packet.0,
            self.surface_epoch,
            &mut returns,
        );
        let outcome = returns.outcome;
        self.frontend.apply_returns(returns);
        result.map_err(WgpuRendererError::Wgpu)?;
        Ok(outcome)
    }
}

#[doc(hidden)]
pub struct HeldFramePacket(frame_packet::FramePacket);

#[cfg(not(target_arch = "wasm32"))]
#[doc(hidden)]
pub struct InlinePresentRuntime {
    state: PresentState,
    msg_rx: std::sync::mpsc::Receiver<PresentMsg>,
    shutdown_seen: bool,
}

#[cfg(not(target_arch = "wasm32"))]
impl InlinePresentRuntime {
    pub fn pump(&mut self) -> bool {
        if self.shutdown_seen {
            return false;
        }
        while let Ok(msg) = self.msg_rx.try_recv() {
            if !self.state.run_once(msg) {
                self.shutdown_seen = true;
                return false;
            }
        }
        self.state.consume_waiting();
        true
    }

    pub fn has_waiting_packet(&self) -> bool {
        self.state.has_waiting_packet()
    }

    pub fn step_one_message(&mut self) -> bool {
        if self.shutdown_seen {
            return false;
        }
        match self.msg_rx.try_recv() {
            Ok(msg) => {
                if !self.state.run_once(msg) {
                    self.shutdown_seen = true;
                }
                true
            }
            Err(_) => false,
        }
    }

    pub fn consume_waiting(&mut self) {
        self.state.consume_waiting();
    }
}

impl Default for WgpuRenderer {
    fn default() -> Self {
        Self::new(&[])
    }
}

impl Renderer for WgpuRenderer {
    type Scene = Scene;
    type Error = WgpuRendererError;

    fn attach_app_context_services(&mut self, app_context: &cranpose_ui::AppContext) {
        app_context.set_text_measurer(SoftwareTextMeasurer::from_font_set(
            self.frontend.text_fonts.clone(),
            8192,
        ));
        self.frontend.app_context = Some(app_context.downgrade());
    }

    fn set_root_scale(&mut self, scale: f32) {
        self.frontend.root_scale = scale;
    }

    fn scene(&self) -> &Self::Scene {
        &self.frontend.scene
    }

    fn scene_mut(&mut self) -> &mut Self::Scene {
        &mut self.frontend.scene
    }

    fn rebuild_scene(
        &mut self,
        layout_tree: &LayoutTree,
        _viewport: Size,
    ) -> Result<(), Self::Error> {
        self.frontend.scene.clear();
        self.frontend.clear_fps_overlay();
        pipeline::render_layout_tree(layout_tree.root(), &mut self.frontend.scene);
        Ok(())
    }

    fn rebuild_scene_from_applier(
        &mut self,
        applier: &mut MemoryApplier,
        root: NodeId,
        _viewport: Size,
    ) -> Result<(), Self::Error> {
        self.frontend.clear_fps_overlay();
        self.frontend.scene.rebuild_from_applier(applier, root);
        Ok(())
    }

    fn update_scene_from_applier(
        &mut self,
        applier: &mut MemoryApplier,
        root: NodeId,
        _viewport: Size,
        updates: cranpose_render_common::SceneUpdates<'_>,
    ) -> Result<(), Self::Error> {
        if updates.is_empty() {
            self.frontend.clear_fps_overlay();
        }
        self.frontend
            .scene
            .update_from_applier(applier, root, updates, true);
        Ok(())
    }

    fn update_visual_scene_from_applier(
        &mut self,
        applier: &mut MemoryApplier,
        root: NodeId,
        _viewport: Size,
        updates: cranpose_render_common::SceneUpdates<'_>,
    ) -> Result<(), Self::Error> {
        if updates.is_empty() {
            self.frontend.clear_fps_overlay();
        }
        self.frontend
            .scene
            .update_from_applier(applier, root, updates, false);
        Ok(())
    }

    fn draw_dev_overlay(&mut self, text: &str, viewport: Size) {
        const DEV_OVERLAY_NODE_ID: NodeId = NodeId::MAX;
        let key = cranpose_render_common::dev_overlay::DevOverlayKey::new(text, viewport);
        if self.frontend.dev_overlay_graph.is_some()
            && self
                .frontend
                .dev_overlay_cache
                .as_ref()
                .is_some_and(|cache| {
                    cache.text == key.text
                        && cache.viewport_width_bits == key.viewport_width_bits
                        && cache.viewport_height_bits == key.viewport_height_bits
                })
        {
            return;
        }
        self.frontend.fps_overlay_graph = Some(
            cranpose_render_common::dev_overlay::build_dev_overlay_graph(
                text,
                viewport,
                DEV_OVERLAY_NODE_ID,
            ),
        );
        self.frontend.dev_overlay_cache = Some(DevOverlayCache {
            text: key.text,
            viewport_width_bits: key.viewport_width_bits,
            viewport_height_bits: key.viewport_height_bits,
        });
        self.frontend.refresh_dev_overlay();
    }

    fn set_inspector_overlay(&mut self, graph: Option<cranpose_render_common::graph::RenderGraph>) {
        self.frontend.inspector_overlay_graph = graph;
        self.frontend.refresh_dev_overlay();
    }

    fn needs_frame_warmup(&self) -> bool {
        match &self.backend {
            PresentBackend::Sync(gpu_renderer) => gpu_renderer.needs_frame_warmup(),
            #[cfg(not(target_arch = "wasm32"))]
            PresentBackend::Threaded(handle) => handle
                .status()
                .needs_frame_warmup
                .load(std::sync::atomic::Ordering::Relaxed),
            PresentBackend::None => false,
        }
    }

    fn awaits_pipelines(&self) -> bool {
        match &self.backend {
            PresentBackend::Sync(gpu_renderer) => gpu_renderer.awaits_pipelines(),
            #[cfg(not(target_arch = "wasm32"))]
            PresentBackend::Threaded(handle) => {
                let status = handle.status();
                status
                    .drew_placeholder
                    .load(std::sync::atomic::Ordering::Relaxed)
                    && status
                        .landing
                        .get()
                        .is_some_and(|landing| landing.in_flight())
            }
            PresentBackend::None => false,
        }
    }
}

#[cfg(test)]
#[path = "tests/wgpu_tests.rs"]
mod tests;