GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! GPU document canvas: an `egui_wgpu` paint callback that draws one document view with a custom
//! WGSL shader.
//!
//! The document's composite lives on the GPU as one or more mipmapped textures (premultiplied
//! alpha, sRGB-encoded values, matching how the CPU path and egui blend): `Rgba8Unorm` for 8-bit
//! documents, `Rgba16Float` for 16- and 32-bit documents when the adapter can render to and
//! filter it (so smooth gradients don't band and 32-bit values above 1.0 survive for the 32-bit
//! preview), within [`F16_BUDGET_PX`]; larger high-bit documents fall back to `Rgba8Unorm`.
//! Uploads are either full (new document, size change, re-render) or a damage rect (brush
//! strokes); after an upload only the affected region of each mip level is regenerated by a
//! render-pass blit chain. Documents larger than the device's maximum texture size are split
//! into tiles.
//!
//! Per frame the shader draws, in *device pixels*, the document's pixels alone, premultiplied: sampled trilinearly
//! when zoomed out, bilinearly between 1× and 2×, and with an anti-aliased "sharp nearest" filter at integer scales
//! and ≥ 2×. The framework canvas's `RasterDisplay` draws the checkerboard under them and the edge around them, and
//! its pixel grid draws over them.
//!
//! GPU resources live in the renderer's `callback_resources` type map; the per-frame callback only
//! carries plain view parameters, so it is `Send + Sync` on every target (including wasm).
//!
//! The document pixels still come from the CPU compositor (`photocraft-compose`) for now; the wgpu
//! compositor (M5) will render straight into these tiles.

use std::collections::HashMap;
use std::num::NonZeroU64;
use std::sync::atomic::Ordering;

use eframe::egui_wgpu::{self, CallbackResources, CallbackTrait, RenderState, ScreenDescriptor};
use eframe::wgpu;

use crate::render_path::CpuReason;

pub use pages::{MAX_PAGE_SIDE, PageUpload};
pub use photocraft_gpu::{DeviceHealth, Fault};

mod budget;
mod callback;
mod compositor_build;
mod doc_textures;
mod pages;
mod perf;
mod residency;
mod resources;
mod setup;
mod shaders;
mod texels;

#[cfg(all(test, windows))]
use budget::detect_video_memory;
#[cfg(all(test, target_os = "linux"))]
use budget::nvidia_video_memory;
pub use budget::{
    COMPOSITOR_BUILDING, DEFER_PX, MIN_GPU_BUDGET, OVER_BUDGET, OVER_CANVAS_BUDGET, REFRESH_DEFERRED, REFRESH_OVER_BUDGET, canvas_budget, canvas_texture_bytes,
    memory_budget, physical_memory, video_memory, vram_share,
};
#[cfg(test)]
use budget::{NVIDIA_VENDOR, bounded_output, drm_video_memory, parse_nvidia_smi};
use callback::CanvasCallback;
#[cfg(test)]
use callback::{filter_mode, map_doc_px, tile_screen_aabb};
use doc_textures::init_buffer;
#[cfg(test)]
use doc_textures::{mip_count, mip_damage};
pub use perf::{GpuInfo, Perf, backend_name, now_ms};
#[cfg(all(test, windows))]
use photocraft_engine::memory::detect_physical_memory;
pub use resources::CanvasStyle;
use resources::{DocTextures, Resources, identity_lut_bytes, lut_bind_group};
#[cfg(test)]
use setup::device_limits_for;
use setup::texture_buffer;
pub use setup::{Refresh, device_descriptor, device_limits, display_texels, timing_features, use_adapter_limits, use_adapter_limits_with, wgpu_setup};
#[cfg(test)]
use shaders::{CANVAS_WGSL, ENCODE_WGSL, MIP_WGSL};
#[cfg(not(target_arch = "wasm32"))]
use texels::texel_to_f32;
pub use texels::{LayerFit, premultiply_rgba8, premultiply_rgba16f};
#[cfg(test)]
use texels::{f16_to_f32, f32_to_f16};
use texels::{texel_bytes, texels, texels_into};

/// Default tile side; documents up to this size (and the device limit) use a single texture.
pub const DEFAULT_TILE: u32 = 8192;
/// Mip levels no larger than this on either side are redrawn whole on every edit rather than
/// just their damage (see [`mip_damage`], #6418). Every corrupted level measured was at most
/// 64 px; this leaves a factor of two.
const WHOLE_MIP_SIDE: u32 = 128;
const FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
/// Canvas texture format of high-bit documents (see [`GpuCanvas::format_for`]).
const FORMAT_HIGH: wgpu::TextureFormat = wgpu::TextureFormat::Rgba16Float;
/// Largest high-bit document (in pixels) given an `Rgba16Float` canvas texture: 100 MP is
/// 800 MB at level 0, about 1.07 GB with mips (twice the `Rgba8Unorm` cost). Bigger 16/32-bit
/// documents (a 14000² one would need 2.1 GB) use `Rgba8Unorm`, so they stay on the GPU like
/// 8-bit ones. `PHOTOCRAFT_CANVAS_F16=0` turns the float canvas off, `=1` ignores this budget.
pub const F16_BUDGET_PX: u64 = 100_000_000;
const VIEW_UNIFORM_SIZE: u64 = 128;
const VIEW_FLOATS: usize = 32;
const TILE_UNIFORM_SIZE: u64 = 32;

/// Whether this view can use the GPU canvas. Flip and non-square pixel aspect correction are
/// still CPU blits (the shader's filtering assumes square pixels); rotation is a shader uniform.
pub fn gpu_view_ok(flip: bool, _rotation: f32, aspect: f32) -> bool {
    !flip && (aspect - 1.0).abs() < 1e-6
}

/// Parameters for drawing one document view. Positions are in egui points.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ViewParams {
    /// Document key used with [`GpuCanvas::upload_full`].
    pub doc: u64,
    /// Document size in pixels.
    pub doc_size: [u32; 2],
    /// Screen points per document pixel.
    pub zoom: f32,
    /// Document point shown at the centre of the canvas rect.
    pub center: [f32; 2],
    /// Camera rotation in radians, clockwise in Y-down screen space. Rotate around [`Self::center`]
    /// before sampling. Flip stays on the CPU path.
    pub rotation: f32,
    /// Distinguishes views painted in the same frame (main canvas, extra windows).
    pub view_key: u64,
    /// Display transform: 0 none, 1 the document's display LUT (document → monitor profile,
    /// Proof Colors), 2 LUT plus the gamut warning, 3 matrix/shaper (see [`GpuCanvas::set_display_lut`]).
    pub display: u8,
    /// The display the view is on (its LUT is per document and display, #569; 0 = unknown).
    pub output: u32,
    /// View › 32-bit Preview Options (exposure in stops, gamma), applied to the texture values
    /// before the display LUT; `None` when off. The display LUT must then leave it out
    /// (`ColorState::gpu_canvas_lut`).
    pub hdr: Option<[f32; 2]>,
}

/// When high-bit documents get an `Rgba16Float` canvas texture.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum HighPolicy {
    /// The adapter can't render to or filter `Rgba16Float`, or `PHOTOCRAFT_CANVAS_F16=0`.
    Off,
    /// Up to [`F16_BUDGET_PX`].
    Budget,
    /// Always (`PHOTOCRAFT_CANVAS_F16=1`).
    Always,
}

/// Uploads documents to the GPU and paints them. Cheap to clone.
///
/// Once the device is lost or reports an uncaptured error (see [`GpuCanvas::fault`]), every
/// method is a no-op or an `Err`, so nothing reaches the GPU again; the app then switches to the
/// CPU canvas (#243).
#[derive(Clone)]
pub struct GpuCanvas {
    rs: RenderState,
    tile: u32,
    high: HighPolicy,
    health: photocraft_gpu::DeviceHealth,
    /// [`video_memory`] of the adapter, detected once.
    vram: Option<u64>,
    /// [`canvas_budget`], shared with the paint callback's resources: [`GpuCanvas::format_for`]
    /// reads it while the renderer is locked.
    canvas_budget: std::sync::Arc<std::sync::atomic::AtomicU64>,
    /// Camera Raw's preview pass, built the first time the dialog asks (#6419).
    camera_raw: crate::camera_raw_gpu::Slot,
    camera_raw_started: std::sync::Arc<std::sync::atomic::AtomicBool>,
    compositor_build: compositor_build::Slot,
    compositor_completion: compositor_build::Completion,
}

/// Whether `regenerate_mips` builds each level in a scratch texture and copies it back: on
/// Intel adapters under DX12 only, where some drivers corrupt reduced previews when a pass
/// samples one mip level and renders into another of the same texture (#892, Intel UHD 620).
/// Everywhere else it renders straight into the level: on an NVIDIA DX12 adapter the scratch
/// textures, created per level on every refresh, cost about 1 ms of CPU time per brush dab
/// (#4515). `PHOTOCRAFT_SEPARATE_MIPS` (`setting`) forces it on (`1`) or off (`0`).
pub fn separate_mip_targets(backend: wgpu::Backend, vendor: u32, setting: Option<&str>) -> bool {
    const INTEL: u32 = 0x8086;
    match setting.map(str::trim) {
        Some("1") => true,
        Some("0") => false,
        _ => backend == wgpu::Backend::Dx12 && vendor == INTEL,
    }
}

/// Can `adapter` use `Rgba16Float` as a sampled, filtered, render-target and copy texture?
/// (Core WebGPU guarantees it; WebGL2 needs `EXT_color_buffer_float`, and some drivers lack it.)
pub fn supports_f16_canvas(adapter: &wgpu::Adapter) -> bool {
    let f = adapter.get_texture_format_features(FORMAT_HIGH);
    let usages = wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_DST | wgpu::TextureUsages::COPY_SRC;
    f.allowed_usages.contains(usages) && f.flags.contains(wgpu::TextureFormatFeatureFlags::FILTERABLE)
}

impl GpuCanvas {
    /// Create pipelines and register resources with the egui renderer.
    pub fn new(rs: &RenderState) -> Self {
        Self::with_tile(rs, None)
    }

    /// Like [`GpuCanvas::new`] with a preferred texture tile side (`PHOTOCRAFT_GPU_TILE` wins).
    pub fn with_tile(rs: &RenderState, tile: Option<u32>) -> Self {
        let max = rs.device.limits().max_texture_dimension_2d;
        let env_tile = std::env::var("PHOTOCRAFT_GPU_TILE").ok().and_then(|v| v.parse::<u32>().ok());
        let tile = env_tile.or(tile).unwrap_or(DEFAULT_TILE).clamp(64, max);
        let high = match std::env::var("PHOTOCRAFT_CANVAS_F16").ok().as_deref() {
            _ if !supports_f16_canvas(&rs.adapter) => HighPolicy::Off,
            Some("0") => HighPolicy::Off,
            Some("1") => HighPolicy::Always,
            _ => HighPolicy::Budget,
        };
        // Device loss and uncaptured errors mark this flag instead of panicking (#243).
        let health = photocraft_gpu::DeviceHealth::watch(&rs.device);
        let mut res = Resources::new(&rs.device, &rs.queue, rs.target_format, high != HighPolicy::Off);
        res.health = health.clone();
        let info = rs.adapter.get_info();
        res.separate_mip_targets = separate_mip_targets(info.backend, info.vendor, std::env::var("PHOTOCRAFT_SEPARATE_MIPS").ok().as_deref());
        let vram = video_memory(&info);
        res.canvas_budget.store(canvas_budget(physical_memory(), vram), Ordering::Relaxed);
        let budget = res.canvas_budget.clone();
        rs.renderer.write().callback_resources.insert(res);
        log::info!(
            "gpu canvas: target {:?}, max texture {max}, tile {tile}, 16F canvas {high:?}, video memory {}",
            rs.target_format,
            vram.map_or_else(|| "unknown".to_owned(), |b| format!("{} MB", b >> 20))
        );
        Self {
            rs: rs.clone(),
            tile,
            high,
            health,
            vram,
            canvas_budget: budget,
            camera_raw: Default::default(),
            camera_raw_started: Default::default(),
            compositor_build: Default::default(),
            compositor_completion: Default::default(),
        }
    }

    /// Start compositor compilation off the UI thread on native hardware.
    pub fn start_compositor(&self, ctx: &egui::Context) {
        #[cfg(not(target_arch = "wasm32"))]
        if self.rs.adapter.get_info().device_type != wgpu::DeviceType::Cpu && std::env::var_os("PHOTOCRAFT_CPU_COMPOSE").is_none() {
            compositor_build::start(
                &self.rs.device,
                photocraft_gpu::Compositor::preferred_acc_format(&self.rs.adapter),
                ctx,
                &self.compositor_build,
                &self.compositor_completion,
            );
        }
        #[cfg(target_arch = "wasm32")]
        let _ = ctx;
    }

    /// Key the memo to this device, application and shader compiler.
    pub fn compositor_memo_key(&self, compiler: &str) -> crate::gpu_memo::MemoKey {
        let info = self.rs.adapter.get_info();
        crate::gpu_memo::MemoKey {
            app_version: env!("CARGO_PKG_VERSION").into(),
            shader_fingerprint: photocraft_gpu::shader_fingerprint(),
            adapter_name: info.name,
            vendor: info.vendor,
            device: info.device,
            driver: info.driver,
            driver_info: info.driver_info,
            backend: format!("{:?}", info.backend),
            shader_compiler: compiler.into(),
        }
    }

    /// Use a known deterministic failure without recompiling the same shaders.
    pub fn remember_compositor_failure(&self, error: &str) {
        *self.compositor_build.lock().unwrap_or_else(std::sync::PoisonError::into_inner) =
            compositor_build::BuildState::Failed(photocraft_gpu::Unsupported(format!("remembered from an earlier launch: {error}")));
    }

    /// Take the background build result once, independently of compositor adoption.
    pub fn take_compositor_completion(&self) -> Option<Result<(), (String, bool)>> {
        self.compositor_completion.lock().unwrap_or_else(std::sync::PoisonError::into_inner).take()
    }

    /// The device's health flag (shared with the wgpu compositor and the paint callback).
    pub fn health(&self) -> &photocraft_gpu::DeviceHealth {
        &self.health
    }

    /// Camera Raw's GPU preview develop on this device; the first call starts building its
    /// pipeline. `None` on a software adapter, without `Rgba32Float` render targets, after a
    /// fault, or when the driver couldn't build the pipeline; the dialog then develops on the CPU.
    pub(crate) fn camera_raw(&self) -> Option<crate::camera_raw_gpu::CameraRawGpu> {
        if self.fault().is_some() {
            return None;
        }
        if !self.camera_raw_started.swap(true, Ordering::AcqRel) {
            crate::camera_raw_gpu::Pass::start(&self.rs.adapter, &self.rs.device, &self.camera_raw);
        }
        if matches!(self.camera_raw.get(), Some(None)) {
            return None;
        }
        Some(crate::camera_raw_gpu::CameraRawGpu::new(self.rs.device.clone(), self.rs.queue.clone(), self.health.clone(), self.camera_raw.clone()))
    }

    /// Whether [`Self::camera_raw`] started building the pass.
    #[cfg(test)]
    pub(crate) fn camera_raw_started(&self) -> bool {
        self.camera_raw_started.load(Ordering::Acquire)
    }

    /// Waits until the pass is built or refused.
    #[cfg(test)]
    pub(crate) fn wait_camera_raw_pass(&self) {
        let _ = self.camera_raw.wait();
    }

    /// Builds Camera Raw's pass even where [`Self::camera_raw`] wouldn't (egui_kittest's software
    /// adapter), so tests drive the GPU develop.
    #[cfg(test)]
    pub(crate) fn force_camera_raw_pass(&self) {
        self.camera_raw_started.store(true, Ordering::Release);
        let _ = self.camera_raw.set(crate::camera_raw_gpu::Pass::build_on(&self.rs.device));
    }

    /// Why the GPU can't be used any more (`None` while it can).
    pub fn fault(&self) -> Option<photocraft_gpu::Fault> {
        self.health.fault()
    }

    /// Free every GPU resource the canvas holds (compositor pages, document textures, LUTs) after
    /// a fault; the paint callback draws nothing from then on.
    pub fn release(&self) {
        let mut r = self.rs.renderer.write();
        if let Some(res) = r.callback_resources.get_mut::<Resources>() {
            res.compositor = None;
            res.compositor_failed = Some(photocraft_gpu::Unsupported(self.fault().map_or_else(|| "GPU canvas released".into(), |f| f.to_string())));
            res.docs.clear();
            res.luts.clear();
            res.display_lut_signatures.clear();
            res.views.clear();
        }
    }

    /// The adapter this canvas renders with.
    pub fn adapter_info(&self) -> wgpu::AdapterInfo {
        self.rs.adapter.get_info()
    }

    /// The adapter's own memory where it has one and the platform reports it (see
    /// [`video_memory`]); it caps [`memory_budget`] and [`canvas_budget`].
    pub fn video_memory(&self) -> Option<u64> {
        self.vram
    }

    /// The canvas texture format for a document of `depth` and `size`: `Rgba16Float` for 16/32-bit
    /// documents when the adapter supports it and the document fits [`F16_BUDGET_PX`], else
    /// `Rgba8Unorm`.
    /// The device's largest 2D texture side (egui textures can use it too).
    pub fn max_texture_side(&self) -> usize {
        self.rs.device.limits().max_texture_dimension_2d as usize
    }

    pub fn format_for(&self, depth: photocraft_doc::SampleType, size: [u32; 2]) -> wgpu::TextureFormat {
        let px = size[0] as u64 * size[1] as u64;
        let high = match self.high {
            HighPolicy::Off => false,
            // Within the canvas budget too: a 16-bit canvas a small card can't hold as floats
            // stays on the GPU as `Rgba8Unorm` rather than falling back to the CPU canvas.
            HighPolicy::Budget => {
                px <= F16_BUDGET_PX && canvas_texture_bytes(size, self.tile, texel_bytes(FORMAT_HIGH)) <= self.canvas_budget.load(Ordering::Relaxed)
            }
            HighPolicy::Always => true,
        };
        if high && depth != photocraft_doc::SampleType::U8 { FORMAT_HIGH } else { FORMAT }
    }

    /// Format and GPU bytes (all tiles, all mip levels) of document `key`'s canvas texture.
    pub fn texture_info(&self, key: u64) -> Option<(wgpu::TextureFormat, u64)> {
        let r = self.rs.renderer.read();
        let d = r.callback_resources.get::<Resources>()?.docs.get(&key)?;
        let bpp = texel_bytes(d.format);
        let bytes = d
            .tiles
            .iter()
            .map(|t| (0..t.levels.len() as u32).map(|l| ((t.rect[2] >> l).max(1) as u64) * ((t.rect[3] >> l).max(1) as u64) * bpp).sum::<u64>())
            .sum();
        Some((d.format, bytes))
    }

    /// Set the GPU memory the wgpu compositor may hold for layer pages and caches (see
    /// [`memory_budget`]); pages beyond it are evicted least recently used first.
    pub fn set_memory_budget(&self, bytes: u64) {
        let mut r = self.rs.renderer.write();
        if let Some(res) = r.callback_resources.get_mut::<Resources>() {
            res.compositor_budget = Some(bytes);
        }
    }

    /// The compositor's memory budget (`None` until [`GpuCanvas::set_memory_budget`]).
    pub fn memory_budget(&self) -> Option<u64> {
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>()?.compositor_budget
    }

    /// Set the GPU bytes the open documents' display textures may take together (see
    /// [`canvas_budget`] and [`GpuCanvas::show_documents`]).
    pub fn set_canvas_budget(&self, bytes: u64) {
        self.canvas_budget.store(bytes, Ordering::Relaxed);
    }

    /// Whether `doc`'s display textures fit its share of [`canvas_budget`]; when they don't,
    /// nothing is created for it and it is drawn from viewport pages or on the CPU canvas.
    pub fn fits_canvas(&self, doc: &photocraft_doc::Document) -> bool {
        self.canvas_fit(doc).is_some_and(|(bytes, budget)| bytes <= budget)
    }

    /// The bytes `doc`'s whole-document texture set would take.
    pub fn canvas_bytes(&self, doc: &photocraft_doc::Document) -> u64 {
        let size = [doc.size.width, doc.size.height];
        canvas_texture_bytes(size, self.tile, texel_bytes(self.format_for(doc.depth, size)))
    }

    /// The bytes `doc`'s display textures would take and its share of [`canvas_budget`] (`None`
    /// without a GPU canvas): the numbers of a [`CpuReason::CanvasTooLarge`]. Alone on screen a
    /// document has the whole budget; see [`GpuCanvas::show_documents`].
    pub fn canvas_fit(&self, doc: &photocraft_doc::Document) -> Option<(u64, u64)> {
        let bytes = self.canvas_bytes(doc);
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>().map(|res| (bytes, res.residency.share(res.canvas_budget.load(Ordering::Relaxed), doc.id.0, bytes)))
    }

    /// The documents the app's windows show now, with [`GpuCanvas::canvas_bytes`] of each: they
    /// split [`canvas_budget`] (see [`residency`]), and the textures of documents not among them
    /// are freed first when a shown one needs the room. Cheap when nothing changed.
    pub fn show_documents(&self, shown: &[(u64, u64)]) {
        if self.rs.renderer.read().callback_resources.get::<Resources>().is_none_or(|res| res.residency.shows(shown)) {
            return;
        }
        if let Some(res) = self.rs.renderer.write().callback_resources.get_mut::<Resources>() {
            res.residency.publish(shown);
        }
    }

    #[cfg(test)]
    pub(crate) fn simulate_compositor_build(&self) {
        *self.compositor_build.lock().unwrap() = compositor_build::BuildState::Building;
    }

    #[cfg(test)]
    pub(crate) fn simulate_compositor_completion(&self, success: bool) -> bool {
        let (state, outcome) = if success {
            let Ok(comp) = photocraft_gpu::Compositor::try_new_with_format(&self.rs.device, photocraft_gpu::Compositor::preferred_acc_format(&self.rs.adapter))
            else {
                return false;
            };
            (compositor_build::BuildState::Ready(Box::new(comp)), Ok(()))
        } else {
            let message = "simulated build failure".to_string();
            (compositor_build::BuildState::Failed(photocraft_gpu::Unsupported(message.clone())), Err((message, false)))
        };
        *self.compositor_build.lock().unwrap() = state;
        *self.compositor_completion.lock().unwrap() = Some(outcome);
        true
    }

    /// Why the compositor couldn't be built, once it couldn't (see [`GpuCanvas::composite`]).
    fn compositor_failed(&self) -> Option<String> {
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>()?.compositor_failed.as_ref().map(|e| e.0.clone())
    }

    /// A [`photocraft_gpu::Unsupported`] from [`GpuCanvas::composite`] as a typed reason, with
    /// the numbers of the budget it names.
    fn reason(&self, doc: &photocraft_doc::Document, e: photocraft_gpu::Unsupported) -> CpuReason {
        if let Some(f) = self.fault() {
            return CpuReason::from_fault(&f);
        }
        if e.0 == OVER_BUDGET {
            let fit = self.layer_fit();
            return CpuReason::OverBudget { needed: fit.map_or(0, |f| f.needed), budget: fit.map_or(0, |f| f.budget) };
        }
        if e.0 == OVER_CANVAS_BUDGET {
            let (bytes, budget) = self.canvas_fit(doc).unwrap_or_default();
            return CpuReason::CanvasTooLarge { bytes, budget };
        }
        if e.0 == COMPOSITOR_BUILDING {
            return CpuReason::CompositorBuilding;
        }
        if self.compositor_failed().is_some_and(|f| f == e.0) {
            return CpuReason::CompositorBuild(e.0);
        }
        CpuReason::Unsupported(e.0)
    }

    /// Cap lower-stack composite reuse; zero disables it for profiling the uncached path.
    pub fn set_composite_cache_budget(&self, bytes: u64) {
        let mut r = self.rs.renderer.write();
        if let Some(res) = r.callback_resources.get_mut::<Resources>() {
            res.compositor_cache_budget = Some(bytes);
            if let Some(comp) = &mut res.compositor {
                comp.set_composite_cache_budget(bytes);
            }
        }
    }

    /// The document area the view shows: full refreshes composite it last, so its layer pages
    /// are the ones still resident for the edits that follow.
    pub fn set_focus(&self, focus: Option<photocraft_geom::Rect>) {
        let mut r = self.rs.renderer.write();
        if let Some(res) = r.callback_resources.get_mut::<Resources>() {
            res.compositor_focus = focus;
        }
    }

    /// Take any GPU measurement that has landed since the last call, without compositing
    /// anything. [`Compositor::render`] carries measurements out in its stats, but a refresh is
    /// the only thing that collects them, so the last refresh before the app goes idle would
    /// never be reported. The frame loop calls this so it is.
    pub fn take_gpu_timing(&self) -> Option<photocraft_gpu::GpuTiming> {
        let mut r = self.rs.renderer.write();
        r.callback_resources.get_mut::<Resources>()?.compositor.as_mut()?.take_gpu_timing()
    }

    /// GPU bytes the wgpu compositor holds: resident layer pages and caches (effect maps and
    /// lower-stack chunks). Keep the scorecard's memory measurements inclusive of reuse.
    pub fn compositor_bytes(&self) -> Option<(u64, usize)> {
        let r = self.rs.renderer.read();
        let c = r.callback_resources.get::<Resources>()?.compositor.as_ref()?;
        Some((c.resident_bytes(), c.fx_cache_bytes().saturating_add(usize::try_from(c.composite_cache_bytes()).unwrap_or(usize::MAX))))
    }

    /// Whether `doc`'s layers fit the budget as it now stands, measured without a refresh (a GPU
    /// Memory change shows in the status bar at once). `None` before the compositor exists.
    pub fn measure_fit(&self, doc: &photocraft_doc::Document) -> Option<LayerFit> {
        let mut r = self.rs.renderer.write();
        let res = r.callback_resources.get_mut::<Resources>()?;
        let budget = res.compositor_budget;
        let comp = res.compositor.as_mut()?;
        if let Some(b) = budget {
            comp.set_memory_budget(b);
        }
        let needed = comp.working_set(doc, doc.bounds());
        let fit = LayerFit { doc: doc.id.0, needed, budget: comp.fit_layers(needed, true) };
        res.layer_fit = Some(fit);
        Some(fit)
    }

    /// Whether the layers of the last full (or large) refresh fit the GPU memory budget, and by
    /// how much (`None` before the first one).
    pub fn layer_fit(&self) -> Option<LayerFit> {
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>()?.layer_fit
    }

    /// Set the gamut warning colours.
    pub fn set_style(&self, style: CanvasStyle) {
        let mut r = self.rs.renderer.write();
        if let Some(res) = r.callback_resources.get_mut::<Resources>() {
            res.style = style;
        }
    }

    /// Whether document `doc` has been uploaded with this size.
    pub fn has(&self, doc: u64, size: [u32; 2]) -> bool {
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>().and_then(|res| res.docs.get(&doc)).is_some_and(|d| d.size == size)
    }

    /// Whether [`GpuCanvas::composite`] would draw `doc` with the wgpu compositor (rather than
    /// fall back to the CPU compositor).
    pub fn supports(&self, doc: &photocraft_doc::Document) -> bool {
        if std::env::var_os("PHOTOCRAFT_CPU_COMPOSE").is_some() || doc.size.width == 0 || doc.size.height == 0 {
            return false;
        }
        let r = self.rs.renderer.read();
        let Some(res) = r.callback_resources.get::<Resources>() else { return false };
        if res.compositor_failed.is_some() {
            return false;
        }
        match &res.compositor {
            Some(c) => c.supports(doc).is_ok(),
            // Layers larger than the texture limit are stored in pages, so any size qualifies.
            None => photocraft_gpu::plan(doc).is_ok(),
        }
    }

    /// Replace the whole document image with an `Rgba8Unorm` texture. `rgba` is premultiplied
    /// RGBA8, `size[0] * size[1] * 4` bytes (anything else is ignored).
    pub fn upload_full(&self, doc: u64, size: [u32; 2], rgba: &[u8]) {
        self.upload_full_as(doc, size, FORMAT, rgba);
    }

    /// Replace the whole document image with a `format` texture of premultiplied `texels`.
    fn upload_full_as(&self, doc: u64, size: [u32; 2], format: wgpu::TextureFormat, texels: &[u8]) {
        if size[0] == 0 || size[1] == 0 || texels.len() as u64 != size[0] as u64 * size[1] as u64 * texel_bytes(format) || !self.health.is_ok() {
            return;
        }
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return };
        if res.docs.get(&doc).is_none_or(|d| d.size != size || d.format != format) {
            let Some(tex) = DocTextures::new_for(device, res, doc, size, self.tile, format) else {
                res.docs.remove(&doc);
                return;
            };
            res.docs.insert(doc, tex);
        }
        let Some(d) = res.docs.get(&doc) else { return };
        d.write(queue, [0, 0], size, size[0], texels);
        d.regenerate_mips(device, queue, res, [0, 0, size[0], size[1]]);
    }

    /// Replace a rectangle `origin..origin+size` of an uploaded document with premultiplied texels
    /// in its texture format (`size[0] * size[1]` texels: RGBA8 or RGBA16F). Returns false if the
    /// document isn't uploaded, the rectangle doesn't fit or the buffer has the wrong size.
    pub fn upload_rect(&self, doc: u64, origin: [u32; 2], size: [u32; 2], texels: &[u8]) -> bool {
        if !self.health.is_ok() {
            return false;
        }
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return false };
        let Some(d) = res.docs.get(&doc) else { return false };
        if texels.len() as u64 != size[0] as u64 * size[1] as u64 * texel_bytes(d.format)
            || origin[0].saturating_add(size[0]) > d.size[0]
            || origin[1].saturating_add(size[1]) > d.size[1]
        {
            return false;
        }
        if size[0] == 0 || size[1] == 0 {
            return true;
        }
        d.write(queue, origin, size, size[0], texels);
        d.regenerate_mips(device, queue, res, [origin[0], origin[1], origin[0] + size[0], origin[1] + size[1]]);
        true
    }

    /// The texture format of uploaded document `doc`.
    fn format_of(&self, doc: u64) -> Option<wgpu::TextureFormat> {
        let r = self.rs.renderer.read();
        r.callback_resources.get::<Resources>().and_then(|res| res.docs.get(&doc)).map(|d| d.format)
    }

    /// Upload a CPU composite covering the whole document (a preview of a document of `depth`:
    /// see [`GpuCanvas::format_for`]).
    pub fn upload_buffer_full(&self, doc: u64, buf: &photocraft_compose::Buffer, depth: photocraft_doc::SampleType) {
        let size = [buf.rect.width(), buf.rect.height()];
        let format = self.format_for(depth, size);
        self.upload_full_as(doc, size, format, &texels(format, &buf.px));
    }

    /// Upload a CPU composite of a sub-rectangle (in document pixels, `buf.rect`).
    pub fn upload_buffer_rect(&self, doc: u64, buf: &photocraft_compose::Buffer) -> bool {
        let r = buf.rect;
        let Some(format) = self.format_of(doc) else { return false };
        if r.x0 < 0 || r.y0 < 0 {
            return false;
        }
        self.upload_rect(doc, [r.x0 as u32, r.y0 as u32], [r.width(), r.height()], &texels(format, &buf.px))
    }

    /// Composite `region` of `doc` with the wgpu compositor straight into its display texture
    /// (no CPU pixels, no upload of the composite). `encode_srgb` stores the sRGB encoding of the
    /// composite (linear documents, see `photocraft_engine::display_color`). Returns `Err` when the
    /// document uses features the GPU compositor doesn't cover yet; the caller then falls back to
    /// the CPU compositor.
    pub fn composite(
        &self,
        doc: &photocraft_doc::Document,
        region: photocraft_geom::Rect,
        encode_srgb: bool,
    ) -> Result<photocraft_gpu::Stats, photocraft_gpu::Unsupported> {
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let size = [doc.size.width, doc.size.height];
        if size[0] == 0 || size[1] == 0 {
            return Err(photocraft_gpu::Unsupported("empty document".into()));
        }
        if std::env::var_os("PHOTOCRAFT_CPU_COMPOSE").is_some() {
            return Err(photocraft_gpu::Unsupported("disabled by PHOTOCRAFT_CPU_COMPOSE".into()));
        }
        if let Some(f) = self.fault() {
            return Err(photocraft_gpu::Unsupported(f.to_string()));
        }
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return Err(photocraft_gpu::Unsupported("no GPU canvas".into())) };
        // A driver that couldn't build the pipelines once won't later: stay on the CPU compositor.
        if let Some(e) = &res.compositor_failed {
            return Err(e.clone());
        }
        {
            let mut state = self.compositor_build.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
            match std::mem::replace(&mut *state, compositor_build::BuildState::Adopted) {
                compositor_build::BuildState::Building => {
                    *state = compositor_build::BuildState::Building;
                    return Err(photocraft_gpu::Unsupported(COMPOSITOR_BUILDING.into()));
                }
                compositor_build::BuildState::Ready(comp) => res.compositor = Some(*comp),
                compositor_build::BuildState::Failed(error) => {
                    res.compositor_failed = Some(error.clone());
                    return Err(error);
                }
                compositor_build::BuildState::NotStarted => *state = compositor_build::BuildState::NotStarted,
                compositor_build::BuildState::Adopted => (),
            }
        }
        let mut comp = match res.compositor.take() {
            Some(c) => c,
            None => match photocraft_gpu::Compositor::try_new_with_format(device, photocraft_gpu::Compositor::preferred_acc_format(&self.rs.adapter)) {
                Ok(c) => c,
                Err(e) => {
                    // `render_path::note` logs it, once, as this document's reason.
                    res.compositor_failed = Some(e.clone());
                    return Err(e);
                }
            },
        };
        comp.set_health(self.health.clone());
        // Measured, not waited for: the timestamps come back a frame or two later.
        comp.measure_gpu_time(device, queue);
        if let Some(b) = res.compositor_budget {
            comp.set_memory_budget(b);
        }
        if let Some(b) = res.compositor_cache_budget {
            comp.set_composite_cache_budget(b);
        }
        comp.set_focus(res.compositor_focus);
        let key = doc.id.0;
        let format = self.format_for(doc.depth, size);
        let fresh = res.docs.get(&key).is_none_or(|d| d.size != size || d.format != format);
        let region = if fresh { doc.bounds() } else { region.intersect(&doc.bounds()) };
        // Checked before allocating a new canvas texture only: `render` plans (and refuses) itself.
        if fresh && let Err(e) = comp.supports(doc) {
            res.compositor = Some(comp);
            return Err(e);
        }
        // A full refresh whose layer pages don't fit the memory budget would re-upload the
        // evicted ones every time (no faster than the CPU, and more memory): the banded CPU
        // compositor does it (in the background on desktop). So does a large damage rect, such
        // as hiding a big layer (#4024); small edits in the view stay on the GPU.
        let large = region.width() as u64 * region.height() as u64 >= DEFER_PX;
        if region == doc.bounds() || large {
            let needed = comp.working_set(doc, region);
            let fit = LayerFit { doc: doc.id.0, needed, budget: comp.fit_layers(needed, region == doc.bounds()) };
            res.layer_fit = Some(fit);
            if !fit.fits() {
                res.compositor = Some(comp);
                return Err(photocraft_gpu::Unsupported(OVER_BUDGET.into()));
            }
        }
        if fresh {
            let Some(tex) = DocTextures::new_for(device, res, key, size, self.tile, format) else {
                res.docs.remove(&key);
                res.compositor = Some(comp);
                return Err(photocraft_gpu::Unsupported(OVER_CANVAS_BUDGET.into()));
            };
            res.docs.insert(key, tex);
        }
        let (Some(pipe), Some(d)) = (res.encode_pipeline(format), res.docs.get(&key)) else {
            res.compositor = Some(comp);
            return Err(photocraft_gpu::Unsupported(format!("no {format:?} canvas texture or pipeline")));
        };
        let bgl = &res.encode_bgl;
        // A float canvas keeps values above 1.0 (32-bit documents, for the 32-bit preview).
        let keep_hdr = i32::from(format == FORMAT_HIGH);
        // Last-resort guard: a wgpu panic (e.g. polling a device lost mid-refresh) marks the
        // device lost instead of taking the app and its documents down.
        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            comp.render(device, queue, doc, region, |enc, out| {
                for t in &d.tiles {
                    let [tx, ty, tw, th] = t.rect.map(|v| v as i32);
                    let r = out.rect.intersect(&photocraft_geom::Rect::from_xywh(tx, ty, tw as u32, th as u32));
                    if r.is_empty() {
                        continue;
                    }
                    let offset = [out.rect.x0 - tx, out.rect.y0 - ty, i32::from(encode_srgb), keep_hdr];
                    let ubuf = init_buffer(device, "pc_encode", &offset.iter().flat_map(|v| v.to_le_bytes()).collect::<Vec<u8>>(), wgpu::BufferUsages::UNIFORM);
                    let bg = device.create_bind_group(&wgpu::BindGroupDescriptor {
                        label: Some("pc_encode"),
                        layout: bgl,
                        entries: &[
                            wgpu::BindGroupEntry { binding: 0, resource: wgpu::BindingResource::TextureView(out.view) },
                            wgpu::BindGroupEntry { binding: 1, resource: ubuf.as_entire_binding() },
                        ],
                    });
                    let mut pass = enc.begin_render_pass(&wgpu::RenderPassDescriptor {
                        label: Some("pc_encode"),
                        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                            view: &t.levels[0],
                            resolve_target: None,
                            depth_slice: None,
                            ops: wgpu::Operations { load: wgpu::LoadOp::Load, store: wgpu::StoreOp::Store },
                        })],
                        depth_stencil_attachment: None,
                        timestamp_writes: None,
                        occlusion_query_set: None,
                        multiview_mask: None,
                    });
                    pass.set_pipeline(pipe);
                    pass.set_bind_group(0, &bg, &[0]);
                    pass.set_scissor_rect((r.x0 - tx) as u32, (r.y0 - ty) as u32, r.width(), r.height());
                    pass.draw(0..3, 0..1);
                }
            })
        }));
        let Ok(result) = result else {
            self.health.mark(photocraft_gpu::Fault::Lost("the GPU compositor stopped (internal error)".into()));
            res.docs.remove(&key);
            return Err(photocraft_gpu::Unsupported("GPU device lost".into()));
        };
        // Lost during the refresh: its output can't be trusted.
        let result = match self.fault() {
            Some(f) => Err(photocraft_gpu::Unsupported(f.to_string())),
            None => result,
        };
        if result.is_ok() {
            d.regenerate_mips(device, queue, res, [region.x0 as u32, region.y0 as u32, region.x1 as u32, region.y1 as u32]);
            if std::env::var_os("PHOTOCRAFT_GPU_SYNC").is_some() {
                // Benchmarking: wait for the GPU so callers can time the whole refresh.
                #[cfg(not(target_arch = "wasm32"))]
                self.health.wait(device, None);
            }
        } else if fresh {
            res.docs.remove(&key);
        }
        res.compositor = Some(comp);
        result
    }

    /// Bring document `key`'s display texture up to date with `doc`: only `damage` when given (a
    /// brush stroke on an already uploaded document), else everything. The wgpu compositor renders
    /// straight into the texture when it supports the document; otherwise the CPU compositor does.
    /// `display` is the canvas colour transform: the GPU path stores the sRGB encoding when it
    /// asks for it, and every CPU band or rect goes through its `texture_buffer`.
    pub fn refresh(
        &self,
        key: u64,
        doc: &photocraft_doc::Document,
        damage: Option<photocraft_geom::Rect>,
        display: Option<&photocraft_engine::display_color::CanvasDisplay>,
    ) -> Refresh {
        self.refresh_with(key, doc, damage, display, false)
    }

    /// [`GpuCanvas::refresh`], except that with `defer`, a refresh of at least [`DEFER_PX`] the
    /// CPU compositor would draw is left to the caller (`background_redraw`): the texture is made
    /// ready (keeping what it shows when it already fits) and the kind is [`REFRESH_DEFERRED`].
    pub fn refresh_with(
        &self,
        key: u64,
        doc: &photocraft_doc::Document,
        damage: Option<photocraft_geom::Rect>,
        display: Option<&photocraft_engine::display_color::CanvasDisplay>,
        defer: bool,
    ) -> Refresh {
        if let Some(f) = self.fault() {
            // Nothing reaches the GPU any more; the app switches to the CPU canvas.
            return Refresh { kind: "lost", fallback: Some(CpuReason::from_fault(&f)), ..Default::default() };
        }
        if !self.fits_canvas(doc) {
            // Neither compositor can fill textures that are never created: the CPU canvas draws
            // it. A set left from before the canvas grew is stale, so it goes too.
            if let Some(res) = self.rs.renderer.write().callback_resources.get_mut::<Resources>() {
                res.docs.remove(&key);
            }
            let (bytes, budget) = self.canvas_fit(doc).unwrap_or_default();
            return Refresh { kind: REFRESH_OVER_BUDGET, fallback: Some(CpuReason::CanvasTooLarge { bytes, budget }), ..Default::default() };
        }
        let bounds = doc.bounds();
        let size = [doc.size.width, doc.size.height];
        let format = self.format_for(doc.depth, size);
        let damage = damage.filter(|_| self.has(key, size) && self.format_of(key) == Some(format)).map(|r| r.intersect(&bounds));
        let t0 = now_ms();
        let mut out = Refresh::default();
        if damage.is_some_and(|r| r.is_empty()) {
            // Nothing changed on the canvas (selecting a layer, say): don't even plan.
            out.kind = "rect";
            return out;
        }
        let region = damage.unwrap_or(bounds);
        let encode_srgb = display.is_some_and(|d| d.encode_srgb);
        let gpu = if key == doc.id.0 { self.composite(doc, region, encode_srgb) } else { Err(photocraft_gpu::Unsupported("preview texture".into())) };
        match gpu {
            Ok(stats) => {
                out.kind = if damage.is_some() { "gpu-rect" } else { "gpu-full" };
                out.px = region.width() as u64 * region.height() as u64;
                // Encoding and submitting only: the GPU is still running this work.
                out.composite_ms = now_ms() - t0;
                out.uploads = stats.tiles_uploaded as u64;
                out.gpu = stats.gpu_time;
                return out;
            }
            Err(e) => {
                out.gpu_attempt_ms = now_ms() - t0;
                out.fallback = Some(self.reason(doc, e));
            }
        }
        let t0 = now_ms();
        let px = region.width() as u64 * region.height() as u64;
        if defer && px >= DEFER_PX && self.prepare_texture(key, doc).is_some() {
            out.kind = REFRESH_DEFERRED;
            out.px = px;
            return out;
        }
        if let Some(r) = damage {
            if r.is_empty() {
                out.kind = "rect";
                return out;
            }
            let buf = photocraft_compose::render(doc, r);
            let t1 = now_ms();
            if self.upload_buffer_rect(key, &texture_buffer(display, &buf)) {
                out.kind = "rect";
                out.px = r.width() as u64 * r.height() as u64;
                out.composite_ms = t1 - t0;
                out.upload_ms = now_ms() - t1;
                return out;
            }
        }
        self.upload_composite(key, doc, display);
        out.kind = "full";
        out.px = bounds.width() as u64 * bounds.height() as u64;
        out.composite_ms = now_ms() - t0;
        out
    }

    /// Composite the whole of `doc` with the CPU compositor into document `key`'s texture, band by
    /// band (each band converted and uploaded before the next is rendered), so a huge document
    /// never needs a full-size float composite or texture-format copy in memory.
    pub fn upload_composite(&self, key: u64, doc: &photocraft_doc::Document, display: Option<&photocraft_engine::display_color::CanvasDisplay>) {
        let size = [doc.size.width, doc.size.height];
        let Some(format) = self.prepare_texture(key, doc) else { return };
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let mut rgba = Vec::new();
        let _ = photocraft_compose::render_bands(doc, doc.bounds(), 0, |band| -> Result<(), ()> {
            if !self.health.is_ok() {
                return Err(());
            }
            texels_into(format, &texture_buffer(display, &band).px, &mut rgba);
            let renderer = self.rs.renderer.read();
            let d = renderer.callback_resources.get::<Resources>().and_then(|r| r.docs.get(&key)).ok_or(())?;
            d.write(queue, [0, band.rect.y0 as u32], [size[0], band.rect.height()], size[0], &rgba);
            drop(renderer);
            // Flush the staged band so its staging memory is reclaimed while the next renders.
            queue.submit(std::iter::empty::<wgpu::CommandBuffer>());
            self.health.poll(device);
            Ok(())
        });
        if !self.health.is_ok() {
            return;
        }
        let mut renderer = self.rs.renderer.write();
        if let Some(res) = renderer.callback_resources.get_mut::<Resources>()
            && let Some(d) = res.docs.get(&key)
        {
            d.regenerate_mips(device, queue, res, [0, 0, size[0], size[1]]);
        }
    }

    /// Make sure document `key` has a display texture of `doc`'s size and format, keeping the one
    /// it has when that fits. Returns its format, or `None` when it can't be created.
    pub fn prepare_texture(&self, key: u64, doc: &photocraft_doc::Document) -> Option<wgpu::TextureFormat> {
        let size = [doc.size.width, doc.size.height];
        if size[0] == 0 || size[1] == 0 || !self.health.is_ok() {
            return None;
        }
        let format = self.format_for(doc.depth, size);
        let mut renderer = self.rs.renderer.write();
        let res = renderer.callback_resources.get_mut::<Resources>()?;
        if res.docs.get(&key).is_none_or(|d| d.size != size || d.format != format) {
            let Some(tex) = DocTextures::new_for(&self.rs.device, res, key, size, self.tile, format) else {
                res.docs.remove(&key);
                return None;
            };
            res.docs.insert(key, tex);
        }
        Some(format)
    }

    /// Free textures, display LUTs and their signatures for documents not in `live`.
    pub fn retain(&self, live: &[u64]) {
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return };
        if res.docs.keys().any(|k| !live.contains(k)) {
            res.docs.retain(|k, _| live.contains(k));
        }
        // Everything the compositor holds for documents that aren't open, also when their
        // texture entry was dropped earlier (over budget, a failed render), which used to leave
        // their pages and effect maps resident after closing (#4529).
        if let Some(c) = res.compositor.as_mut() {
            c.retain_docs(|d| live.contains(&d.0));
        }
        // LUTs and identity-transform signatures can outlive document textures. Prune both,
        // or a preserved-ID reopen can skip rebuilding a missing LUT.
        res.luts.retain(|k, _| live.contains(&k.0));
        res.residency.retain(|d| live.contains(&d));
        res.display_lut_signatures.retain(|k, _| live.contains(&k.0));
    }

    pub(crate) fn display_lut_signature(&self, doc: u64, output: u32) -> Option<(u64, u8)> {
        let renderer = self.rs.renderer.read();
        renderer.callback_resources.get::<Resources>()?.display_lut_signatures.get(&(doc, output)).copied()
    }

    /// Whether document `doc` has a display LUT for display `output` (tests).
    #[cfg(test)]
    pub(crate) fn has_display_lut(&self, doc: u64, output: u32) -> bool {
        let renderer = self.rs.renderer.read();
        renderer.callback_resources.get::<Resources>().is_some_and(|r| r.luts.contains_key(&(doc, output)))
    }

    pub(crate) fn cache_display_lut_signature(&self, doc: u64, output: u32, signature: u64, mode: u8) {
        let mut renderer = self.rs.renderer.write();
        if let Some(res) = renderer.callback_resources.get_mut::<Resources>() {
            res.display_lut_signatures.insert((doc, output), (signature, mode));
        }
    }

    /// Set (or clear with `None`) the display LUT of document `doc` on display `output`:
    /// `size`³ RGBA8 texels, red fastest. RGB is the display colour for each lattice input;
    /// alpha 255 marks out-of-gamut colours for the gamut warning.
    pub fn set_display_lut(&self, doc: u64, output: u32, size: u32, rgba: Option<&[u8]>) {
        if !self.health.is_ok() {
            return;
        }
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return };
        res.display_lut_signatures.remove(&(doc, output));
        match rgba {
            None => {
                res.luts.remove(&(doc, output));
            }
            Some(bytes) => {
                if size < 2 || bytes.len() as u64 != (size as u64).pow(3) * 4 {
                    log::warn!("set_display_lut: {} bytes for a {size}³ LUT; ignored", bytes.len());
                    return;
                }
                let bg = lut_bind_group(device, queue, &res.lut_bgl, size, bytes, None);
                res.luts.insert((doc, output), bg);
            }
        }
    }

    /// Set a separately sampled curve/matrix/curve display transform. CMS validates this
    /// representation and provides bounded tables; no profile interpretation lives in the UI.
    pub fn set_display_matrix_shaper(&self, doc: u64, output: u32, shaper: &craft::cms::GpuMatrixShaper) {
        if !self.health.is_ok() {
            return;
        }
        let mut renderer = self.rs.renderer.write();
        let Some(res) = renderer.callback_resources.get_mut::<Resources>() else { return };
        let bg = lut_bind_group(&self.rs.device, &self.rs.queue, &res.lut_bgl, 2, &identity_lut_bytes(), Some(shaper));
        res.display_lut_signatures.remove(&(doc, output));
        res.luts.insert((doc, output), bg);
    }

    /// Read back level 0 of document `key`'s canvas texture: its format, size and the stored
    /// (premultiplied) texels as `f32` RGBA, row-major. Waits for the GPU; for tests, benchmarks
    /// and debugging.
    #[cfg(not(target_arch = "wasm32"))]
    pub fn read_texels(&self, key: u64) -> Option<(wgpu::TextureFormat, [u32; 2], Vec<[f32; 4]>)> {
        if !self.health.is_ok() {
            return None;
        }
        let (device, queue) = (&self.rs.device, &self.rs.queue);
        let renderer = self.rs.renderer.read();
        let d = renderer.callback_resources.get::<Resources>()?.docs.get(&key)?;
        let bpp = texel_bytes(d.format);
        let (w, h) = (d.size[0] as usize, d.size[1] as usize);
        let mut out = vec![[0.0f32; 4]; w.checked_mul(h)?];
        for t in &d.tiles {
            let [tx, ty, tw, th] = t.rect;
            let row = (tw as u64 * bpp).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT as u64);
            let buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("pc_canvas_readback"),
                size: row * th as u64,
                usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
                mapped_at_creation: false,
            });
            let mut enc = device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some("pc_canvas_readback") });
            enc.copy_texture_to_buffer(
                t.texture.as_image_copy(),
                wgpu::TexelCopyBufferInfo {
                    buffer: &buf,
                    layout: wgpu::TexelCopyBufferLayout { offset: 0, bytes_per_row: Some(row as u32), rows_per_image: Some(th) },
                },
                wgpu::Extent3d { width: tw, height: th, depth_or_array_layers: 1 },
            );
            queue.submit([enc.finish()]);
            let slice = buf.slice(..);
            slice.map_async(wgpu::MapMode::Read, |_| {});
            if !self.health.wait(device, None) {
                return None;
            }
            let data = slice.get_mapped_range().ok()?;
            for y in 0..th as usize {
                let src = data.get(y * row as usize..)?;
                for x in 0..tw as usize {
                    let o = out.get_mut((ty as usize + y) * w + tx as usize + x)?;
                    *o = texel_to_f32(d.format, src.get(x * bpp as usize..(x + 1) * bpp as usize)?);
                }
            }
        }
        Some((d.format, d.size, out))
    }

    /// Add the paint callback drawing `params` into `rect` (clipped by the painter's clip rect).
    pub fn paint(painter: &egui::Painter, rect: egui::Rect, params: ViewParams) {
        painter.add(egui_wgpu::Callback::new_paint_callback(rect, CanvasCallback { rect, params }));
    }
}

#[cfg(test)]
mod mip_gpu_tests;

#[cfg(test)]
mod sharp_gpu_tests;

#[cfg(test)]
mod tests;