noesis_wgpu 0.3.0

//! [`WgpuRenderDevice`], [`BatchTextures`] and [`PatternLod`].
//!
//! Each `begin_*_render` opens a command encoder that the matching
//! `end_*_render` submits. Inside the offscreen phase, draws go to the render
//! target chosen by `set_render_target`; inside the onscreen phase they go to
//! the view passed to [`WgpuRenderDevice::set_onscreen_target`]. Per-batch
//! uniforms and geometry are appended to per-phase buffers, so every draw
//! recorded in a phase reads its own data when the encoder is submitted.

use std::collections::{HashMap, HashSet};
use std::num::NonZeroU64;

use log::warn;

#[cfg(feature = "shim")]
use noesis_runtime::render_device::RenderDevice;
use noesis_runtime::render_device::types::{
    Batch, DeviceCaps, SIZE_FOR_FORMAT, SamplerState, Shader, TextureFormat, Tile,
};
use noesis_runtime::render_device::{
    RenderTargetBinding, RenderTargetDesc, RenderTargetHandle, TextureBinding, TextureDesc,
    TextureHandle, TextureRect,
};

use crate::custom_shader::{
    BatchShader, MAX_SHADER_CONSTANTS, MAX_SHADER_TEXTURES, PixelShaderDesc, PixelShaderError,
    PixelShaderHandle,
};
use crate::pipeline::{PipelineCache, PipelineKey, STENCIL_FORMAT};

const DYNAMIC_VB_SIZE: u64 = 512 * 1024;
const DYNAMIC_IB_SIZE: u64 = 128 * 1024;

// cbuffer0_vs (mat4, 64B) + cbuffer1_vs (glyph-atlas size padded to vec4,
// 16B); matches `VsUniforms` in noesis.wgsl.
const VS_UNIFORM_SIZE: u64 = 80;
/// Byte offset of `cbuffer1_vs` within the VS uniform slot.
const VS_GLYPH_SIZE_OFFSET: usize = 64;

// cbuffer0_ps: 8 floats.
const PS_UNIFORM0_SIZE: u64 = 32;

// cbuffer1_ps, sized for a custom shader's largest `Constants`. The built-in
// shaders read at most its first 8 floats (SHADOW 7, BLUR 1), so their draws
// upload only those.
const PS_UNIFORM1_SIZE: u64 = MAX_SHADER_CONSTANTS as u64;
const PS_UNIFORM1_BUILTIN_SIZE: usize = 32;

// `PatternLod` in noesis.wgsl: bias, max level, two pad floats.
const PATTERN_LOD_SIZE: u64 = 16;

// Initial `draw_batch_with` calls per render phase; the rings double past it.
const UNIFORM_RING_SLOTS: u32 = 1024;

/// Color format every RT allocates with, and the format the pipeline cache
/// compiles all pipelines against. Onscreen views handed to
/// [`WgpuRenderDevice::set_onscreen_target`] must also be this format.
const RT_COLOR_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;

const RT_STENCIL_FORMAT: wgpu::TextureFormat = STENCIL_FORMAT;

#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum FramePhase {
    /// No encoder live.
    Idle,
    /// Inside `begin_offscreen_render` / `end_offscreen_render`. Draws target
    /// the currently-selected render target.
    Offscreen,
    /// Inside `begin_onscreen_render` / `end_onscreen_render`. Draws target
    /// `target_view`.
    Onscreen,
}

/// A Noesis render device that draws with wgpu.
///
/// Noesis calls it with textures, render targets and per-batch geometry, and
/// it turns each call into wgpu work: uploads, pipelines from its pipeline
/// cache, and draws recorded into the active encoder.
///
/// Create one with [`WgpuRenderDevice::new`], then drive it one of two ways:
///
/// - Register it with `noesis_runtime`'s shim through
///   `noesis_runtime::render_device::register` (`shim` feature). Noesis then
///   calls the [`RenderDevice`](noesis_runtime::render_device::RenderDevice)
///   methods itself; reach the device between frames with
///   `Registered::device_mut`.
/// - Call the protocol methods yourself, from a host that receives Noesis's
///   device calls some other way. Pass each batch to
///   [`draw_batch_with`](Self::draw_batch_with) with its textures resolved to
///   handles.
///
/// Either way, point it at an `Rgba8Unorm` target with
/// [`set_onscreen_target`](Self::set_onscreen_target) before the onscreen
/// phase, and use it from the thread that drives the Noesis view and renderer.
///
/// A call that breaks the protocol, such as an unknown handle or a draw
/// outside a phase, logs a warning and is skipped instead of panicking;
/// [`stats`](Self::stats) counts the skipped batches. If a call does panic
/// partway through a phase (`noesis_runtime`'s trampoline catches the panic),
/// the next `begin_*_render` logs a warning and starts a clean phase.
pub struct WgpuRenderDevice {
    device: wgpu::Device,
    queue: wgpu::Queue,

    vertex_stream: GeometryStream,
    index_stream: GeometryStream,

    uniforms: UniformRings,

    // The texture bind groups: group(2) paint, or paint and extra textures
    // for a custom shader, and group(3) image, shadow and glyphs. Unused slots
    // get the dummy texture.
    paint_layout: wgpu::BindGroupLayout,
    custom_paint_layout: wgpu::BindGroupLayout,
    image_layout: wgpu::BindGroupLayout,
    samplers: HashMap<SamplerState, wgpu::Sampler>,
    texture_groups: HashMap<TextureGroupKey, wgpu::BindGroup>,

    // 1x1 white; fills unused texture slots.
    #[allow(dead_code)] // owns the allocation behind `dummy_view`
    dummy_texture: wgpu::Texture,
    dummy_view: wgpu::TextureView,
    dummy_sampler: wgpu::Sampler,

    pipelines: PipelineCache,
    // Shaders already reported as unsupported.
    warned_shaders: HashSet<u8>,
    warned_custom_shaders: HashSet<PixelShaderHandle>,
    // `pipelines` is filled in by `stats()`.
    stats: DeviceStats,

    // Entries removed by `drop_texture` / `drop_render_target`.
    textures: HashMap<TextureHandle, GpuTexture>,
    render_targets: HashMap<RenderTargetHandle, GpuRenderTarget>,

    target_view: Option<wgpu::TextureView>,
    // Onscreen draws clip with the stencil too (e.g. ScrollViewer viewports).
    onscreen_stencil: Option<GpuStencil>,
    // Noesis assumes a zeroed stencil, so the first draw into a target after
    // `begin_onscreen_render` / `set_render_target` clears it.
    onscreen_stencil_cleared: bool,
    current_rt_stencil_cleared: bool,

    phase: FramePhase,
    // Declared before `encoder`: the pass locks the encoder until it drops.
    pass: Option<OpenPass>,
    encoder: Option<wgpu::CommandEncoder>,
    current_rt: Option<RenderTargetHandle>,
    current_tile: Option<Tile>,

    next_handle: u64,
}

/// The attachments a render pass draws into.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum PassTarget {
    Onscreen,
    Offscreen(RenderTargetHandle),
}

/// The render pass the last draw recorded into. Draws into the same target
/// share it, so a phase records one pass per run of draws into one target
/// instead of one per draw.
struct OpenPass {
    pass: wgpu::RenderPass<'static>,
    target: PassTarget,
    /// The scissor rect last set in the pass; `None` while it covers the
    /// whole target.
    scissor: Option<(u32, u32, u32, u32)>,
}

/// Why [`WgpuRenderDevice::draw_batch_with`] skipped a batch.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum SkippedDraw {
    /// The call broke the render-device protocol or named an unknown handle.
    Protocol,
    /// The batch's shader has no `noesis.wgsl` variant.
    UnsupportedShader,
}

/// A texture and the sampler state to read it with, or `None` for the dummy.
type TextureSlot = Option<(TextureHandle, SamplerState)>;

/// The most texture slots in one bind group: a custom shader's paint and
/// extra textures.
const MAX_GROUP_SLOTS: usize = 1 + MAX_SHADER_TEXTURES;

/// A texture bind group's layout and slots. Slots past the layout's count
/// are `None`.
type TextureGroupKey = (TextureGroup, [TextureSlot; MAX_GROUP_SLOTS]);

/// The texture bind group layouts. Slot `i` takes bindings `2i` (texture) and
/// `2i + 1` (sampler).
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
enum TextureGroup {
    /// group(2): the paint.
    Paint,
    /// group(2) of a custom shader: the paint, then the extra textures.
    CustomPaint,
    /// group(3): image, shadow, glyphs.
    Image,
}

impl TextureGroup {
    const fn slots(self) -> usize {
        match self {
            Self::Paint => 1,
            Self::CustomPaint => MAX_GROUP_SLOTS,
            Self::Image => 3,
        }
    }
}

struct GpuTexture {
    texture: wgpu::Texture,
    view: wgpu::TextureView,
    // `None` for a texture from `import_texture`, which `update_texture` skips.
    noesis_format: Option<TextureFormat>,
    width: u32,
    height: u32,
    num_levels: u32,
}

struct GpuStencil {
    #[allow(dead_code)] // keeps the allocation alive behind `view`
    texture: wgpu::Texture,
    view: wgpu::TextureView,
    width: u32,
    height: u32,
}

/// The resolve texture is a separate `textures` entry, which Noesis releases
/// through its own `drop_texture`.
struct GpuRenderTarget {
    // The view draws render into: the MSAA texture's, or the resolve
    // texture's when the target is single-sampled.
    color_view: wgpu::TextureView,
    // The resolve texture's view, for `resolve_render_target`.
    resolve_view: wgpu::TextureView,
    #[allow(dead_code)] // keeps the allocation alive behind `color_view`
    msaa: Option<wgpu::Texture>,
    stencil: Option<(wgpu::Texture, wgpu::TextureView)>,
    sample_count: u32,
    width: u32,
    height: u32,
}

/// The sample count of every MSAA render target: the one count above 1 that
/// wgpu supports for `Rgba8Unorm` and `Stencil8` on every adapter.
const MSAA_SAMPLE_COUNT: u32 = 4;

/// How pattern textures pick their mip level, set with
/// [`WgpuRenderDevice::set_pattern_lod`].
///
/// It applies to everything Noesis paints from a pattern, that is through an
/// `ImageBrush`: images, opacity masks, pattern-filled text, and a brush
/// shader's `sample_image`. wgpu samplers have no LOD bias, so the shaders
/// apply it by scaling the texture coordinate derivatives; it costs no wgpu
/// feature.
#[derive(Copy, Clone, Debug, PartialEq)]
pub struct PatternLod {
    /// Added to the mip level the hardware would pick. Negative values pick
    /// sharper, larger levels when an image is drawn smaller than its size.
    pub bias: f32,
    /// The highest (smallest) mip level sampled after the bias.
    pub max_level: f32,
}

impl Default for PatternLod {
    /// No bias and no limit: the levels the hardware picks.
    fn default() -> Self {
        Self {
            bias: 0.0,
            max_level: f32::MAX,
        }
    }
}

impl PatternLod {
    fn to_bytes(self) -> [u8; PATTERN_LOD_SIZE as usize] {
        // Past any real mip level, and finite for the shader.
        let max_level = self.max_level.min(64.0);
        let mut bytes = [0u8; PATTERN_LOD_SIZE as usize];
        bytes[..4].copy_from_slice(&self.bias.to_le_bytes());
        bytes[4..8].copy_from_slice(&max_level.to_le_bytes());
        bytes
    }
}

impl WgpuRenderDevice {
    /// Creates a device that renders with `device` and submits to `queue`.
    /// Call [`Self::set_onscreen_target`] before the first onscreen render.
    ///
    /// Every pipeline targets `Rgba8Unorm`, so onscreen views must use that
    /// format.
    #[must_use]
    #[allow(clippy::too_many_lines)] // wgpu setup is linear and hard to split usefully
    pub fn new(device: wgpu::Device, queue: wgpu::Queue) -> Self {
        let vertex_stream = GeometryStream::new(
            &device,
            "noesis_wgpu vertex stream",
            DYNAMIC_VB_SIZE,
            wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        );
        let index_stream = GeometryStream::new(
            &device,
            "noesis_wgpu index stream",
            DYNAMIC_IB_SIZE,
            wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
        );

        let uniforms = UniformRings::new(&device, &queue);

        let paint_layout = texture_group_layout(&device, TextureGroup::Paint);
        let custom_paint_layout = texture_group_layout(&device, TextureGroup::CustomPaint);
        let image_layout = texture_group_layout(&device, TextureGroup::Image);

        // 1x1 white, bound to every texture slot a draw leaves empty.
        let dummy_texture = device.create_texture(&wgpu::TextureDescriptor {
            label: Some("noesis_wgpu dummy texture"),
            size: wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu::TextureFormat::Rgba8Unorm,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });
        queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &dummy_texture,
                mip_level: 0,
                origin: wgpu::Origin3d::ZERO,
                aspect: wgpu::TextureAspect::All,
            },
            &[0xFF_u8; 4],
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(4),
                rows_per_image: Some(1),
            },
            wgpu::Extent3d {
                width: 1,
                height: 1,
                depth_or_array_layers: 1,
            },
        );
        let dummy_view = dummy_texture.create_view(&wgpu::TextureViewDescriptor::default());
        let dummy_sampler = device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("noesis_wgpu dummy sampler"),
            ..Default::default()
        });

        let pipeline_layout = |label, paint_layout| {
            device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
                label: Some(label),
                bind_group_layouts: &[
                    Some(&uniforms.vs_layout),
                    Some(&uniforms.ps_layout),
                    Some(paint_layout),
                    Some(&image_layout),
                ],
                immediate_size: 0,
            })
        };
        let pipelines = PipelineCache::new(
            device.clone(),
            pipeline_layout("noesis_wgpu pipeline layout", &paint_layout),
            pipeline_layout("noesis_wgpu custom pipeline layout", &custom_paint_layout),
            RT_COLOR_FORMAT,
        );

        Self {
            device,
            queue,
            vertex_stream,
            index_stream,
            uniforms,
            paint_layout,
            custom_paint_layout,
            image_layout,
            samplers: HashMap::new(),
            texture_groups: HashMap::new(),
            dummy_texture,
            dummy_view,
            dummy_sampler,
            pipelines,
            warned_shaders: HashSet::new(),
            warned_custom_shaders: HashSet::new(),
            stats: DeviceStats::default(),
            textures: HashMap::new(),
            render_targets: HashMap::new(),
            target_view: None,
            onscreen_stencil: None,
            onscreen_stencil_cleared: false,
            current_rt_stencil_cleared: false,
            phase: FramePhase::Idle,
            pass: None,
            encoder: None,
            current_rt: None,
            current_tile: None,
            next_handle: 1,
        }
    }

    /// Caches the bind group for `key`. `false` when a slot names an unknown
    /// texture. `drop_texture` evicts the groups that sample a texture.
    fn ensure_texture_group(&mut self, key: TextureGroupKey) -> bool {
        if self.texture_groups.contains_key(&key) {
            return true;
        }
        let (group, slots) = key;
        let slots = &slots[..group.slots()];
        for (_, state) in slots.iter().flatten() {
            self.samplers
                .entry(*state)
                .or_insert_with(|| build_sampler(&self.device, *state));
        }

        let mut resources = Vec::with_capacity(slots.len());
        for slot in slots {
            resources.push(match slot {
                Some((handle, state)) => {
                    let Some(texture) = self.textures.get(handle) else {
                        return false;
                    };
                    (&texture.view, &self.samplers[state])
                }
                None => (&self.dummy_view, &self.dummy_sampler),
            });
        }
        let entries: Vec<_> = (0u32..)
            .zip(&resources)
            .flat_map(|(i, (view, sampler))| {
                [
                    wgpu::BindGroupEntry {
                        binding: 2 * i,
                        resource: wgpu::BindingResource::TextureView(view),
                    },
                    wgpu::BindGroupEntry {
                        binding: 2 * i + 1,
                        resource: wgpu::BindingResource::Sampler(sampler),
                    },
                ]
            })
            .collect();
        let layout = match group {
            TextureGroup::Paint => &self.paint_layout,
            TextureGroup::CustomPaint => &self.custom_paint_layout,
            TextureGroup::Image => &self.image_layout,
        };
        let bind_group = self.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("noesis_wgpu textures"),
            layout,
            entries: &entries,
        });
        self.texture_groups.insert(key, bind_group);
        true
    }

    /// Sets the view that onscreen draws render into. Call it before an
    /// onscreen phase whenever the target changes, such as after a resize; a
    /// host with one fixed target calls it once.
    ///
    /// `view` must be an `Rgba8Unorm` texture of `width` x `height` pixels
    /// (the format isn't checked). The device keeps a matching stencil buffer
    /// for onscreen clipping and reallocates it only when the size changes.
    ///
    /// Call it between `end_*_render` and the next `begin_*_render`. Called
    /// inside a phase, it logs a warning and the draws that follow use the new
    /// target. A zero-sized target logs a warning and is ignored.
    pub fn set_onscreen_target(&mut self, view: wgpu::TextureView, width: u32, height: u32) {
        if width == 0 || height == 0 {
            warn!("set_onscreen_target: {width}x{height} target ignored");
            return;
        }
        if self.phase != FramePhase::Idle {
            warn!(
                "set_onscreen_target called inside the {:?} phase",
                self.phase
            );
        }
        let need_alloc = self
            .onscreen_stencil
            .as_ref()
            .is_none_or(|s| s.width != width || s.height != height);
        if need_alloc {
            let texture = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some("noesis_wgpu onscreen stencil"),
                size: wgpu::Extent3d {
                    width,
                    height,
                    depth_or_array_layers: 1,
                },
                mip_level_count: 1,
                sample_count: 1,
                dimension: wgpu::TextureDimension::D2,
                format: RT_STENCIL_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
            let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
            self.onscreen_stencil = Some(GpuStencil {
                texture,
                view,
                width,
                height,
            });
            self.onscreen_stencil_cleared = false;
        }
        self.pass = None;
        self.target_view = Some(view);
    }

    /// The `wgpu::Texture` behind `handle`, including a render target's
    /// resolve texture. `None` once Noesis has dropped it or for an unknown
    /// handle.
    #[must_use]
    pub fn texture(&self, handle: TextureHandle) -> Option<&wgpu::Texture> {
        self.textures.get(&handle).map(|t| &t.texture)
    }

    /// Counts of the batches drawn and skipped since the device was created,
    /// and the pipelines compiled so far.
    #[must_use]
    pub fn stats(&self) -> DeviceStats {
        DeviceStats {
            pipelines: self.pipelines.len(),
            ..self.stats
        }
    }

    /// Pixel size the render target `handle` was created with. `None` once
    /// it has been dropped.
    #[must_use]
    pub fn render_target_size(&self, handle: RenderTargetHandle) -> Option<(u32, u32)> {
        self.render_targets
            .get(&handle)
            .map(|rt| (rt.width, rt.height))
    }

    /// Sets how pattern textures pick their mip level, for the draws of every
    /// phase submitted afterwards. Call it between frames: the draws of a
    /// phase in progress all see the last value set before it ends.
    pub fn set_pattern_lod(&mut self, lod: PatternLod) {
        self.queue
            .write_buffer(&self.uniforms.pattern_lod, 0, &lod.to_bytes());
    }

    /// Compiles a custom pixel shader and returns its handle, for the batches
    /// whose `pixel_shader` stands for it. See [`PixelShaderDesc`] for what
    /// the WGSL can use and [`draw_custom_batch`](Self::draw_custom_batch)
    /// for drawing with it.
    ///
    /// The shader is checked by building its pipeline for one representative
    /// batch; other batch shaders and render states compile on first use. A
    /// description out of range or WGSL that fails wgpu's validation returns
    /// the error and registers nothing.
    pub fn create_pixel_shader(
        &mut self,
        desc: PixelShaderDesc<'_>,
    ) -> Result<PixelShaderHandle, PixelShaderError> {
        let handle = PixelShaderHandle(self.alloc_handle());
        self.pipelines.register_custom(handle, &desc)?;
        Ok(handle)
    }

    /// Releases a custom pixel shader and its pipelines. Batches that still
    /// name it are skipped with a warning.
    pub fn drop_pixel_shader(&mut self, handle: PixelShaderHandle) {
        self.pipelines.remove_custom(handle);
        self.warned_custom_shaders.remove(&handle);
    }

    fn alloc_handle(&mut self) -> NonZeroU64 {
        let h = self.next_handle;
        self.next_handle += 1;
        NonZeroU64::new(h).expect("alloc_handle starts at 1")
    }

    /// Uploads `batch`'s uniforms, with `ps1` in place of its `cbuffer1_ps`,
    /// and returns the `(vs, ps0, ps1)` dynamic offsets.
    fn upload_uniforms(&mut self, batch: &Batch, ps1: (&[u8], usize)) -> (u32, u32, u32) {
        let cbuf0 = batch.vertex_uniforms[0].as_bytes();
        let cbuf1 = batch.vertex_uniforms[1].as_bytes();
        let mut vs_buf = [0u8; VS_UNIFORM_SIZE as usize];
        let cbuf0_len = cbuf0.len().min(VS_GLYPH_SIZE_OFFSET);
        vs_buf[..cbuf0_len].copy_from_slice(&cbuf0[..cbuf0_len]);
        let cbuf1_len = cbuf1
            .len()
            .min(VS_UNIFORM_SIZE as usize - VS_GLYPH_SIZE_OFFSET);
        vs_buf[VS_GLYPH_SIZE_OFFSET..VS_GLYPH_SIZE_OFFSET + cbuf1_len]
            .copy_from_slice(&cbuf1[..cbuf1_len]);
        self.uniforms.write(
            &self.device,
            &self.queue,
            &vs_buf,
            batch.pixel_uniforms[0].as_bytes(),
            ps1,
        )
    }
}

/// `tile` (bottom-left origin) as a top-left scissor rect, clipped to the
/// target: wgpu rejects a scissor that leaves it.
fn tile_scissor(tile: Tile, width: u32, height: u32) -> (u32, u32, u32, u32) {
    let x = tile.x.min(width);
    let w = tile.width.min(width - x);
    let bottom = tile.y.min(height);
    let h = tile.height.min(height - bottom);
    (x, height - bottom - h, w, h)
}

const fn round_up_to_4(n: usize) -> usize {
    (n + 3) & !3
}

const fn align_up_u64(n: u64, align: u64) -> u64 {
    (n + align - 1) & !(align - 1)
}

/// One uniform buffer split into slots, one per draw. The bind group covers
/// one slot at offset 0 and the dynamic offset selects the slot.
/// The upload lands before the phase's submit, so a shared slot would leave
/// every draw reading the last batch's values. Draws write their slots into a
/// CPU copy, and `flush` uploads the slots written since the last flush in one
/// `write_buffer`. Reset at each `begin_*_render`.
struct UniformRing {
    buffer: wgpu::Buffer,
    label: &'static str,
    /// Bytes the bind group exposes from each slot.
    struct_size: u64,
    /// Distance between slot starts: `struct_size` rounded up to
    /// `min_uniform_buffer_offset_alignment`.
    slot_stride: u64,
    slot_capacity: u32,
    next_slot: u32,
    /// The first slot `flush` has not uploaded.
    flushed_slot: u32,
    /// The CPU copy of the buffer's slots.
    staged: Vec<u8>,
}

impl UniformRing {
    fn new(
        device: &wgpu::Device,
        label: &'static str,
        struct_size: u64,
        slot_capacity: u32,
    ) -> Self {
        let alignment = u64::from(device.limits().min_uniform_buffer_offset_alignment);
        let slot_stride = align_up_u64(struct_size, alignment);
        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(label),
            size: slot_stride * u64::from(slot_capacity),
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        Self {
            buffer,
            label,
            struct_size,
            slot_stride,
            slot_capacity,
            next_slot: 0,
            flushed_slot: 0,
            staged: vec![0u8; (slot_stride * u64::from(slot_capacity)) as usize],
        }
    }

    fn is_full(&self) -> bool {
        self.next_slot == self.slot_capacity
    }

    /// Replaces the buffer with an empty one of twice the slots. Draws already
    /// recorded keep the old buffer alive through the encoder, so nothing is
    /// copied. Flush first, or the old buffer misses its last writes.
    fn grow(&mut self, device: &wgpu::Device) {
        *self = Self::new(device, self.label, self.struct_size, self.slot_capacity * 2);
    }

    fn reset(&mut self) {
        self.next_slot = 0;
        self.flushed_slot = 0;
    }

    /// Uploads the slots written since the last flush.
    fn flush(&mut self, queue: &wgpu::Queue) {
        if self.next_slot == self.flushed_slot {
            return;
        }
        let start = u64::from(self.flushed_slot) * self.slot_stride;
        let end = u64::from(self.next_slot) * self.slot_stride;
        queue.write_buffer(
            &self.buffer,
            start,
            &self.staged[start as usize..end as usize],
        );
        self.flushed_slot = self.next_slot;
    }

    /// Stages `bytes`, truncated or zero-padded to `len` bytes (a multiple of
    /// 4, at most `struct_size`), at the start of the next slot and returns
    /// its dynamic offset; `flush` uploads it. The rest of the slot keeps
    /// stale data, so `len` must cover what the shader reads. The caller grows
    /// a full ring first.
    fn write(&mut self, bytes: &[u8], len: usize) -> u32 {
        let slot = self.next_slot;
        self.next_slot += 1;
        let offset = u64::from(slot) * self.slot_stride;

        let start = offset as usize;
        let copied = bytes.len().min(len);
        self.staged[start..start + copied].copy_from_slice(&bytes[..copied]);
        self.staged[start + copied..start + len].fill(0);

        u32::try_from(offset).expect("uniform ring offset overflowed u32")
    }
}

/// The per-draw uniform rings and the bind groups that window them: group(0)
/// holds the vertex uniforms, group(1) `cbuffer0_ps` at binding 0,
/// `cbuffer1_ps` at binding 1, and the [`PatternLod`] at binding 2, which
/// isn't per draw. The three rings fill in step, one slot per draw, and grow
/// together.
struct UniformRings {
    vs: UniformRing,
    ps0: UniformRing,
    ps1: UniformRing,
    pattern_lod: wgpu::Buffer,
    vs_layout: wgpu::BindGroupLayout,
    ps_layout: wgpu::BindGroupLayout,
    vs_bind_group: wgpu::BindGroup,
    ps_bind_group: wgpu::BindGroup,
}

impl UniformRings {
    fn new(device: &wgpu::Device, queue: &wgpu::Queue) -> Self {
        let vs = UniformRing::new(
            device,
            "noesis_wgpu vs_uniforms ring (mat4 projection)",
            VS_UNIFORM_SIZE,
            UNIFORM_RING_SLOTS,
        );
        let ps0 = UniformRing::new(
            device,
            "noesis_wgpu ps_uniforms0 ring (cbuffer0_ps[8])",
            PS_UNIFORM0_SIZE,
            UNIFORM_RING_SLOTS,
        );
        let ps1 = UniformRing::new(
            device,
            "noesis_wgpu ps_uniforms1 ring (cbuffer1_ps)",
            PS_UNIFORM1_SIZE,
            UNIFORM_RING_SLOTS,
        );
        let pattern_lod = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some("noesis_wgpu pattern lod"),
            size: PATTERN_LOD_SIZE,
            usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        queue.write_buffer(&pattern_lod, 0, &PatternLod::default().to_bytes());

        let uniform_entry = |binding, visibility, size| wgpu::BindGroupLayoutEntry {
            binding,
            visibility,
            ty: wgpu::BindingType::Buffer {
                ty: wgpu::BufferBindingType::Uniform,
                has_dynamic_offset: true,
                min_binding_size: NonZeroU64::new(size),
            },
            count: None,
        };
        let vs_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("noesis_wgpu vs_uniforms layout"),
            entries: &[uniform_entry(
                0,
                wgpu::ShaderStages::VERTEX,
                VS_UNIFORM_SIZE,
            )],
        });
        // cbuffer1_ps and the pattern LOD: only some shaders read them, but the
        // shared layout always declares them so every pipeline matches.
        let ps_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("noesis_wgpu ps_uniforms layout"),
            entries: &[
                uniform_entry(0, wgpu::ShaderStages::FRAGMENT, PS_UNIFORM0_SIZE),
                uniform_entry(1, wgpu::ShaderStages::FRAGMENT, PS_UNIFORM1_SIZE),
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: NonZeroU64::new(PATTERN_LOD_SIZE),
                    },
                    count: None,
                },
            ],
        });

        let vs_bind_group = vs_bind_group(device, &vs_layout, &vs);
        let ps_bind_group = ps_bind_group(device, &ps_layout, &ps0, &ps1, &pattern_lod);
        Self {
            vs,
            ps0,
            ps1,
            pattern_lod,
            vs_layout,
            ps_layout,
            vs_bind_group,
            ps_bind_group,
        }
    }

    fn reset(&mut self) {
        self.vs.reset();
        self.ps0.reset();
        self.ps1.reset();
    }

    /// Uploads the draws' uniforms written since the last flush. Call it
    /// before the phase's encoder is submitted.
    fn flush(&mut self, queue: &wgpu::Queue) {
        self.vs.flush(queue);
        self.ps0.flush(queue);
        self.ps1.flush(queue);
    }

    /// Stages one draw's uniforms and returns the `(vs, ps0, ps1)` dynamic
    /// offsets, doubling the rings first when they are full. `ps1` is the
    /// data and the length to stage. `flush` uploads them.
    fn write(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        vs: &[u8],
        ps0: &[u8],
        ps1: (&[u8], usize),
    ) -> (u32, u32, u32) {
        if self.vs.is_full() {
            self.flush(queue);
            self.vs.grow(device);
            self.ps0.grow(device);
            self.ps1.grow(device);
            self.vs_bind_group = vs_bind_group(device, &self.vs_layout, &self.vs);
            self.ps_bind_group = ps_bind_group(
                device,
                &self.ps_layout,
                &self.ps0,
                &self.ps1,
                &self.pattern_lod,
            );
        }
        (
            self.vs.write(vs, VS_UNIFORM_SIZE as usize),
            self.ps0.write(ps0, PS_UNIFORM0_SIZE as usize),
            self.ps1.write(ps1.0, ps1.1),
        )
    }
}

/// A bind group exposing one struct-sized window into each ring buffer. The
/// dynamic offset passed to `set_bind_group` slides it to the draw's slot.
fn ring_binding(ring: &UniformRing) -> wgpu::BindingResource<'_> {
    wgpu::BindingResource::Buffer(wgpu::BufferBinding {
        buffer: &ring.buffer,
        offset: 0,
        size: NonZeroU64::new(ring.struct_size),
    })
}

fn vs_bind_group(
    device: &wgpu::Device,
    layout: &wgpu::BindGroupLayout,
    vs: &UniformRing,
) -> wgpu::BindGroup {
    device.create_bind_group(&wgpu::BindGroupDescriptor {
        label: Some("noesis_wgpu vs_uniforms"),
        layout,
        entries: &[wgpu::BindGroupEntry {
            binding: 0,
            resource: ring_binding(vs),
        }],
    })
}

fn ps_bind_group(
    device: &wgpu::Device,
    layout: &wgpu::BindGroupLayout,
    ps0: &UniformRing,
    ps1: &UniformRing,
    pattern_lod: &wgpu::Buffer,
) -> wgpu::BindGroup {
    device.create_bind_group(&wgpu::BindGroupDescriptor {
        label: Some("noesis_wgpu ps_uniforms"),
        layout,
        entries: &[
            wgpu::BindGroupEntry {
                binding: 0,
                resource: ring_binding(ps0),
            },
            wgpu::BindGroupEntry {
                binding: 1,
                resource: ring_binding(ps1),
            },
            wgpu::BindGroupEntry {
                binding: 2,
                resource: pattern_lod.as_entire_binding(),
            },
        ],
    })
}

fn texture_group_layout(device: &wgpu::Device, group: TextureGroup) -> wgpu::BindGroupLayout {
    let entries: Vec<_> = (0u32..)
        .take(group.slots())
        .flat_map(|i| {
            [
                wgpu::BindGroupLayoutEntry {
                    binding: 2 * i,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Texture {
                        sample_type: wgpu::TextureSampleType::Float { filterable: true },
                        view_dimension: wgpu::TextureViewDimension::D2,
                        multisampled: false,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2 * i + 1,
                    visibility: wgpu::ShaderStages::FRAGMENT,
                    ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering),
                    count: None,
                },
            ]
        })
        .collect();
    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
        label: Some(&format!("noesis_wgpu {group:?} textures")),
        entries: &entries,
    })
}

/// Growable vertex or index buffer for one render phase. Noesis maps and
/// unmaps it several times per phase; each `unmap` appends at `cursor` rather
/// than offset 0, for the same reason as [`UniformRing`]. Batch offsets are
/// relative to the latest segment, so `draw_batch` adds `segment_base`.
struct GeometryStream {
    buffer: wgpu::Buffer,
    label: &'static str,
    usage: wgpu::BufferUsages,
    /// Handed to Noesis by `map`, uploaded at `cursor` by `unmap`.
    staging: Vec<u8>,
    /// Bytes claimed by the in-flight `map`; `None` outside a map/unmap pair.
    mapped_bytes: Option<u32>,
    cursor: u64,
    /// Start of the segment the latest `unmap` wrote.
    segment_base: u64,
}

impl GeometryStream {
    fn new(
        device: &wgpu::Device,
        label: &'static str,
        size: u64,
        usage: wgpu::BufferUsages,
    ) -> Self {
        let buffer = device.create_buffer(&wgpu::BufferDescriptor {
            label: Some(label),
            size,
            usage,
            mapped_at_creation: false,
        });
        Self {
            buffer,
            label,
            usage,
            staging: vec![0u8; size as usize],
            mapped_bytes: None,
            cursor: 0,
            segment_base: 0,
        }
    }

    fn buffer(&self) -> &wgpu::Buffer {
        &self.buffer
    }

    fn segment_base(&self) -> u64 {
        self.segment_base
    }

    /// End of the data uploaded this phase.
    fn written_end(&self) -> u64 {
        self.cursor
    }

    fn reset(&mut self) {
        self.cursor = 0;
    }

    fn map(&mut self, bytes: u32) -> &mut [u8] {
        if self.mapped_bytes.is_some() {
            warn!(
                "{}: map without unmap; the earlier map is discarded",
                self.label
            );
        }
        let len = bytes as usize;
        // `unmap` uploads a 4-byte-padded length, so keep the padding in range.
        let padded = round_up_to_4(len);
        if padded > self.staging.len() {
            self.staging.resize(padded, 0);
        }
        self.mapped_bytes = Some(bytes);
        &mut self.staging[..len]
    }

    fn unmap(&mut self, device: &wgpu::Device, queue: &wgpu::Queue) {
        let Some(bytes) = self.mapped_bytes.take() else {
            warn!("{}: unmap without map", self.label);
            return;
        };
        let padded = round_up_to_4(bytes as usize) as u64;
        // No copy on growth: earlier draws hold the old buffer through the
        // encoder and never read past their own segment.
        if self.cursor + padded > self.buffer.size() {
            let new_size = (self.cursor + padded).max(self.buffer.size() * 2);
            self.buffer = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some(self.label),
                size: new_size,
                usage: self.usage,
                mapped_at_creation: false,
            });
        }
        self.segment_base = self.cursor;
        queue.write_buffer(&self.buffer, self.cursor, &self.staging[..padded as usize]);
        self.cursor += padded;
    }
}

const fn wgpu_format_for(format: TextureFormat) -> wgpu::TextureFormat {
    match format {
        // No wgpu Rgbx8; `has_alpha: false` on the binding tells Noesis.
        TextureFormat::Rgba8 | TextureFormat::Rgbx8 => wgpu::TextureFormat::Rgba8Unorm,
        TextureFormat::R8 => wgpu::TextureFormat::R8Unorm,
        // Non-exhaustive SDK enum: default rather than panic.
        _ => wgpu::TextureFormat::Rgba8Unorm,
    }
}

const fn bytes_per_pixel(format: TextureFormat) -> u32 {
    match format {
        TextureFormat::Rgba8 | TextureFormat::Rgbx8 => 4,
        TextureFormat::R8 => 1,
        // See `wgpu_format_for`.
        _ => 4,
    }
}

/// True when `shader` reads the group(2) paint texture. Must list exactly the
/// shaders [`defines_for_shader`] gives `HAS_PAINT_TEXTURE`, as must
/// [`batch_paint_texture`].
///
/// [`defines_for_shader`]: crate::shader_defines::defines_for_shader
const fn shader_uses_paint_texture(shader: u8) -> bool {
    shader == Shader::PATH_PATTERN.0
        || shader == Shader::PATH_AA_PATTERN.0
        || shader == Shader::PATH_PATTERN_CLAMP.0
        || shader == Shader::PATH_AA_PATTERN_CLAMP.0
        || shader == Shader::PATH_PATTERN_REPEAT.0
        || shader == Shader::PATH_AA_PATTERN_REPEAT.0
        || shader == Shader::PATH_PATTERN_MIRROR_U.0
        || shader == Shader::PATH_AA_PATTERN_MIRROR_U.0
        || shader == Shader::PATH_PATTERN_MIRROR_V.0
        || shader == Shader::PATH_AA_PATTERN_MIRROR_V.0
        || shader == Shader::PATH_PATTERN_MIRROR.0
        || shader == Shader::PATH_AA_PATTERN_MIRROR.0
        || shader == Shader::PATH_LINEAR.0
        || shader == Shader::PATH_AA_LINEAR.0
        || shader == Shader::PATH_RADIAL.0
        || shader == Shader::PATH_AA_RADIAL.0
        || shader == Shader::SDF_LINEAR.0
        || shader == Shader::SDF_RADIAL.0
        || shader == Shader::SDF_PATTERN.0
        || shader == Shader::SDF_PATTERN_CLAMP.0
        || shader == Shader::SDF_PATTERN_REPEAT.0
        || shader == Shader::SDF_PATTERN_MIRROR_U.0
        || shader == Shader::SDF_PATTERN_MIRROR_V.0
        || shader == Shader::SDF_PATTERN_MIRROR.0
        || shader == Shader::OPACITY_LINEAR.0
        || shader == Shader::OPACITY_RADIAL.0
        || shader == Shader::OPACITY_PATTERN.0
        || shader == Shader::OPACITY_PATTERN_CLAMP.0
        || shader == Shader::OPACITY_PATTERN_REPEAT.0
        || shader == Shader::OPACITY_PATTERN_MIRROR_U.0
        || shader == Shader::OPACITY_PATTERN_MIRROR_V.0
        || shader == Shader::OPACITY_PATTERN_MIRROR.0
        // DOWNSAMPLE/UPSAMPLE read the source image at group(2) `pattern`, as
        // a custom effect reads its input.
        || shader == Shader::DOWNSAMPLE.0
        || shader == Shader::UPSAMPLE.0
        || shader == Shader::CUSTOM_EFFECT.0
}

/// The batch slot (pattern or ramps) bound at group(2) for `batch`'s shader.
/// `None` for shaders without a paint texture, or when Noesis left the slot
/// empty.
fn batch_paint_texture(
    batch: &Batch,
    textures: BatchTextures,
) -> Option<(TextureHandle, SamplerState)> {
    match batch.shader.0 {
        s if s == Shader::PATH_PATTERN.0
            || s == Shader::PATH_AA_PATTERN.0
            || s == Shader::PATH_PATTERN_CLAMP.0
            || s == Shader::PATH_AA_PATTERN_CLAMP.0
            || s == Shader::PATH_PATTERN_REPEAT.0
            || s == Shader::PATH_AA_PATTERN_REPEAT.0
            || s == Shader::PATH_PATTERN_MIRROR_U.0
            || s == Shader::PATH_AA_PATTERN_MIRROR_U.0
            || s == Shader::PATH_PATTERN_MIRROR_V.0
            || s == Shader::PATH_AA_PATTERN_MIRROR_V.0
            || s == Shader::PATH_PATTERN_MIRROR.0
            || s == Shader::PATH_AA_PATTERN_MIRROR.0
            || s == Shader::SDF_PATTERN.0
            || s == Shader::SDF_PATTERN_CLAMP.0
            || s == Shader::SDF_PATTERN_REPEAT.0
            || s == Shader::SDF_PATTERN_MIRROR_U.0
            || s == Shader::SDF_PATTERN_MIRROR_V.0
            || s == Shader::SDF_PATTERN_MIRROR.0
            || s == Shader::OPACITY_PATTERN.0
            || s == Shader::OPACITY_PATTERN_CLAMP.0
            || s == Shader::OPACITY_PATTERN_REPEAT.0
            || s == Shader::OPACITY_PATTERN_MIRROR_U.0
            || s == Shader::OPACITY_PATTERN_MIRROR_V.0
            || s == Shader::OPACITY_PATTERN_MIRROR.0 =>
        {
            textures.pattern.map(|h| (h, batch.pattern_sampler))
        }
        s if s == Shader::PATH_LINEAR.0
            || s == Shader::PATH_AA_LINEAR.0
            || s == Shader::PATH_RADIAL.0
            || s == Shader::PATH_AA_RADIAL.0
            || s == Shader::SDF_LINEAR.0
            || s == Shader::SDF_RADIAL.0
            || s == Shader::OPACITY_LINEAR.0
            || s == Shader::OPACITY_RADIAL.0 =>
        {
            textures.ramps.map(|h| (h, batch.ramps_sampler))
        }
        s if s == Shader::DOWNSAMPLE.0
            || s == Shader::UPSAMPLE.0
            || s == Shader::CUSTOM_EFFECT.0 =>
        {
            textures.pattern.map(|h| (h, batch.pattern_sampler))
        }
        _ => None,
    }
}

/// True when `shader` reads the group(3) `image` texture. Must match
/// `HAS_IMAGE_TEXTURE` in `defines_for_shader`.
const fn shader_uses_image_texture(shader: u8) -> bool {
    shader == Shader::OPACITY_SOLID.0
        || shader == Shader::OPACITY_LINEAR.0
        || shader == Shader::OPACITY_RADIAL.0
        || shader == Shader::OPACITY_PATTERN.0
        || shader == Shader::OPACITY_PATTERN_CLAMP.0
        || shader == Shader::OPACITY_PATTERN_REPEAT.0
        || shader == Shader::OPACITY_PATTERN_MIRROR_U.0
        || shader == Shader::OPACITY_PATTERN_MIRROR_V.0
        || shader == Shader::OPACITY_PATTERN_MIRROR.0
        || shader == Shader::UPSAMPLE.0
        || shader == Shader::SHADOW.0
        || shader == Shader::BLUR.0
}

/// True when `shader` also reads the group(3) `shadow` texture.
const fn shader_uses_shadow_texture(shader: u8) -> bool {
    shader == Shader::SHADOW.0 || shader == Shader::BLUR.0
}

/// True when `shader` reads the group(3) `glyphs` texture: the SDF shaders
/// `noesis.wgsl` implements. Must match `HAS_GLYPHS_TEXTURE`.
const fn shader_uses_glyphs_texture(shader: u8) -> bool {
    shader >= Shader::SDF_SOLID.0 && shader <= Shader::SDF_LCD_SOLID.0
}

fn wgpu_wrap_mode(wrap_raw: u8) -> wgpu::AddressMode {
    // ClampToZero (1) needs a border color, which downlevel wgpu lacks;
    // CLAMP_PATTERN masks out-of-rect samples in the shader anyway. The
    // caller applies one mode to every axis, so MirrorU/MirrorV mirror both.
    match wrap_raw {
        0 | 1 => wgpu::AddressMode::ClampToEdge,
        2 => wgpu::AddressMode::Repeat,
        3..=5 => wgpu::AddressMode::MirrorRepeat,
        // See `wgpu_format_for`.
        other => {
            warn_once!("unknown Noesis WrapMode raw value {other}; using ClampToEdge");
            wgpu::AddressMode::ClampToEdge
        }
    }
}

fn build_sampler(device: &wgpu::Device, state: SamplerState) -> wgpu::Sampler {
    let wrap = wgpu_wrap_mode(state.wrap_mode_raw());
    let filter = match state.minmag_filter_raw() {
        0 => wgpu::FilterMode::Nearest,
        _ => wgpu::FilterMode::Linear,
    };
    let mipmap_filter = match state.mip_filter_raw() {
        0 | 1 => wgpu::MipmapFilterMode::Nearest,
        _ => wgpu::MipmapFilterMode::Linear,
    };
    let lod_max = match state.mip_filter_raw() {
        0 => 0.25, // mips disabled: mip 0 only
        _ => 32.0,
    };

    device.create_sampler(&wgpu::SamplerDescriptor {
        label: Some("noesis_wgpu sampler"),
        address_mode_u: wrap,
        address_mode_v: wrap,
        address_mode_w: wrap,
        mag_filter: filter,
        min_filter: filter,
        mipmap_filter,
        lod_min_clamp: 0.0,
        lod_max_clamp: lod_max,
        compare: None,
        anisotropy_clamp: 1,
        border_color: None,
    })
}

impl WgpuRenderDevice {
    /// The capabilities Noesis queries once during setup: no linear
    /// rendering, no subpixel text, zero-to-one depth range, and clip space
    /// with y up.
    pub fn caps(&self) -> DeviceCaps {
        DeviceCaps {
            linear_rendering: false,
            // SDF_LCD_SOLID exists, but turning this on makes Noesis emit the
            // whole SDF_LCD_* family: most variants are unported, all need
            // DUAL_SOURCE_BLENDING (not in downlevel defaults), and the SDK has
            // no LCD reference to validate against. tests/wgpu_suite/wgpu_sdf_lcd.rs
            // drives the solid variant directly.
            subpixel_rendering: false,
            depth_range_zero_to_one: true,
            clip_space_y_inverted: false,
        }
    }

    /// Creates a texture and uploads its initial mip levels, if `desc` has
    /// any. `Rgbx8` is stored as `Rgba8Unorm` and reported without alpha.
    /// Extra data levels are ignored, and a level with too little data is left
    /// unwritten, each with a warning.
    pub fn create_texture(&mut self, desc: TextureDesc<'_>) -> TextureBinding {
        let handle = TextureHandle(self.alloc_handle());
        let wgpu_format = wgpu_format_for(desc.format);

        let texture = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some(desc.label),
            size: wgpu::Extent3d {
                width: desc.width,
                height: desc.height,
                depth_or_array_layers: 1,
            },
            mip_level_count: desc.num_levels,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: wgpu_format,
            usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
            view_formats: &[],
        });

        if let Some(levels) = desc.data {
            if levels.len() != desc.num_levels as usize {
                warn!(
                    "create_texture '{}': {} data levels for {} mip levels",
                    desc.label,
                    levels.len(),
                    desc.num_levels,
                );
            }
            let bpp = bytes_per_pixel(desc.format);
            for (level, bytes) in levels.iter().take(desc.num_levels as usize).enumerate() {
                let level_u32 = level as u32;
                let w = (desc.width >> level_u32).max(1);
                let h = (desc.height >> level_u32).max(1);
                let needed = u64::from(w) * u64::from(h) * u64::from(bpp);
                if (bytes.len() as u64) < needed {
                    warn!(
                        "create_texture '{}': level {level} has {} bytes, needs {needed}; \
                         leaving it unwritten",
                        desc.label,
                        bytes.len(),
                    );
                    continue;
                }
                self.queue.write_texture(
                    wgpu::TexelCopyTextureInfo {
                        texture: &texture,
                        mip_level: level_u32,
                        origin: wgpu::Origin3d::ZERO,
                        aspect: wgpu::TextureAspect::All,
                    },
                    bytes,
                    wgpu::TexelCopyBufferLayout {
                        offset: 0,
                        bytes_per_row: Some(w * bpp),
                        rows_per_image: Some(h),
                    },
                    wgpu::Extent3d {
                        width: w,
                        height: h,
                        depth_or_array_layers: 1,
                    },
                );
            }
        }

        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
        let has_alpha = !matches!(desc.format, TextureFormat::Rgbx8);
        self.textures.insert(
            handle,
            GpuTexture {
                texture,
                view,
                noesis_format: Some(desc.format),
                width: desc.width,
                height: desc.height,
                num_levels: desc.num_levels,
            },
        );

        TextureBinding {
            handle,
            width: desc.width,
            height: desc.height,
            has_mipmaps: desc.num_levels > 1,
            inverted: false,
            has_alpha,
        }
    }

    /// Writes `data` into `rect` of mip `level`. `data` is tightly packed,
    /// with no row padding.
    /// An unknown or imported texture, a level the texture doesn't have, a
    /// rect outside the level, or too little data logs a warning and writes
    /// nothing.
    pub fn update_texture(
        &mut self,
        handle: TextureHandle,
        level: u32,
        rect: TextureRect,
        data: &[u8],
    ) {
        let Some(tex) = self.textures.get(&handle) else {
            warn!("update_texture: unknown texture {handle:?}");
            return;
        };
        let Some(format) = tex.noesis_format else {
            warn!("update_texture: {handle:?} is imported; the host writes it");
            return;
        };
        if level >= tex.num_levels {
            warn!(
                "update_texture: level {level} of a texture with {} levels",
                tex.num_levels
            );
            return;
        }
        let level_w = (tex.width >> level).max(1);
        let level_h = (tex.height >> level).max(1);
        if rect.x.saturating_add(rect.width) > level_w
            || rect.y.saturating_add(rect.height) > level_h
        {
            warn!("update_texture: rect {rect:?} outside level {level} ({level_w}x{level_h})");
            return;
        }
        let bpp = bytes_per_pixel(format);
        let needed = u64::from(rect.width) * u64::from(rect.height) * u64::from(bpp);
        if (data.len() as u64) < needed {
            warn!(
                "update_texture: {} bytes for a {}x{} rect that needs {needed}",
                data.len(),
                rect.width,
                rect.height,
            );
            return;
        }
        self.queue.write_texture(
            wgpu::TexelCopyTextureInfo {
                texture: &tex.texture,
                mip_level: level,
                origin: wgpu::Origin3d {
                    x: rect.x,
                    y: rect.y,
                    z: 0,
                },
                aspect: wgpu::TextureAspect::All,
            },
            data,
            wgpu::TexelCopyBufferLayout {
                offset: 0,
                bytes_per_row: Some(rect.width * bpp),
                rows_per_image: Some(rect.height),
            },
            wgpu::Extent3d {
                width: rect.width,
                height: rect.height,
                depth_or_array_layers: 1,
            },
        );
    }

    /// Ends a block of [`update_texture`](Self::update_texture) calls. A no-op:
    /// wgpu orders the uploads before later passes on its own.
    pub fn end_updating_textures(&mut self, _textures: &[TextureHandle]) {}

    /// Releases a texture and the bind groups that sample it. For an
    /// imported texture, this releases the device's reference; the host's
    /// stays valid.
    pub fn drop_texture(&mut self, handle: TextureHandle) {
        self.textures.remove(&handle);
        self.texture_groups.retain(|(_, slots), _| {
            !slots
                .iter()
                .flatten()
                .any(|(texture, _)| *texture == handle)
        });
    }

    /// Wraps a texture the host owns, such as a render target it draws into
    /// every frame, as a [`TextureHandle`] Noesis can sample. Nothing is
    /// copied: draws sample whatever the texture holds when the phase that
    /// draws them is submitted.
    ///
    /// The host wraps the returned binding in a Noesis texture object of its
    /// own, as for [`create_texture`](Self::create_texture). Then:
    ///
    /// - Submit writes to the texture on this device's queue before the
    ///   `end_*_render` whose draws should see them. Writes submitted later
    ///   show from the next frame.
    /// - The device holds its own reference until
    ///   [`drop_texture`](Self::drop_texture), so the texture stays valid
    ///   while Noesis uses it even if the host drops its copy. Don't call
    ///   `wgpu::Texture::destroy` on it before then.
    /// - [`update_texture`](Self::update_texture) skips it: the host writes it.
    ///
    /// The texture must be a single-layer, single-sampled 2D texture with
    /// `TEXTURE_BINDING` usage and a filterable float format, such as
    /// `Rgba8Unorm`. Its color is read as premultiplied alpha, like every
    /// Noesis texture. Any other texture logs a warning and returns `None`.
    pub fn import_texture(&mut self, texture: &wgpu::Texture) -> Option<TextureBinding> {
        let filterable = matches!(
            texture
                .format()
                .sample_type(None, Some(self.device.features())),
            Some(wgpu::TextureSampleType::Float { filterable: true })
        );
        if texture.dimension() != wgpu::TextureDimension::D2
            || texture.depth_or_array_layers() != 1
            || texture.sample_count() != 1
            || !texture
                .usage()
                .contains(wgpu::TextureUsages::TEXTURE_BINDING)
            || !filterable
        {
            warn!(
                "import_texture: a {:?} {:?} texture with {} layers, {} samples and {:?} \
                 can't be sampled by Noesis",
                texture.format(),
                texture.dimension(),
                texture.depth_or_array_layers(),
                texture.sample_count(),
                texture.usage(),
            );
            return None;
        }

        let handle = TextureHandle(self.alloc_handle());
        let (width, height, num_levels) =
            (texture.width(), texture.height(), texture.mip_level_count());
        self.textures.insert(
            handle,
            GpuTexture {
                texture: texture.clone(),
                view: texture.create_view(&wgpu::TextureViewDescriptor::default()),
                noesis_format: None,
                width,
                height,
                num_levels,
            },
        );
        Some(TextureBinding {
            handle,
            width,
            height,
            has_mipmaps: num_levels > 1,
            inverted: false,
            has_alpha: true,
        })
    }

    /// Creates an `Rgba8Unorm` render target, with a `Stencil8` buffer when
    /// `desc.needs_stencil` is set.
    ///
    /// A `desc.sample_count` above 1 gets a 4x MSAA target, the one count
    /// every wgpu adapter supports, with a one-time warning when the request
    /// was another count. Its draws render into a multisampled texture that
    /// [`resolve_render_target`](Self::resolve_render_target) resolves into
    /// the texture Noesis samples. A single-sampled target draws straight
    /// into that texture.
    pub fn create_render_target(&mut self, desc: RenderTargetDesc<'_>) -> RenderTargetBinding {
        let sample_count = if desc.sample_count > 1 {
            MSAA_SAMPLE_COUNT
        } else {
            1
        };
        if desc.sample_count > 1 && desc.sample_count != MSAA_SAMPLE_COUNT {
            warn_once!(
                "create_render_target: {} samples requested; MSAA targets use {MSAA_SAMPLE_COUNT}",
                desc.sample_count,
            );
        }

        let rt_handle = RenderTargetHandle(self.alloc_handle());
        let resolve_handle = TextureHandle(self.alloc_handle());
        let size = wgpu::Extent3d {
            width: desc.width,
            height: desc.height,
            depth_or_array_layers: 1,
        };

        let color_texture = self.device.create_texture(&wgpu::TextureDescriptor {
            label: Some(desc.label),
            size: wgpu::Extent3d {
                width: desc.width,
                height: desc.height,
                depth_or_array_layers: 1,
            },
            mip_level_count: 1,
            sample_count: 1,
            dimension: wgpu::TextureDimension::D2,
            format: RT_COLOR_FORMAT,
            usage: wgpu::TextureUsages::RENDER_ATTACHMENT
                | wgpu::TextureUsages::TEXTURE_BINDING
                | wgpu::TextureUsages::COPY_SRC,
            view_formats: &[],
        });
        let resolve_view = color_texture.create_view(&wgpu::TextureViewDescriptor::default());
        let msaa = (sample_count > 1).then(|| {
            self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some(&format!("{} msaa", desc.label)),
                size,
                mip_level_count: 1,
                sample_count,
                dimension: wgpu::TextureDimension::D2,
                format: RT_COLOR_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            })
        });
        let color_view = msaa.as_ref().map_or_else(
            || resolve_view.clone(),
            |msaa| msaa.create_view(&wgpu::TextureViewDescriptor::default()),
        );

        let stencil = desc.needs_stencil.then(|| {
            let tex = self.device.create_texture(&wgpu::TextureDescriptor {
                label: Some(&format!("{} stencil", desc.label)),
                size,
                mip_level_count: 1,
                sample_count,
                dimension: wgpu::TextureDimension::D2,
                format: RT_STENCIL_FORMAT,
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                view_formats: &[],
            });
            let view = tex.create_view(&wgpu::TextureViewDescriptor::default());
            (tex, view)
        });

        self.textures.insert(
            resolve_handle,
            GpuTexture {
                texture: color_texture,
                view: resolve_view.clone(),
                noesis_format: Some(TextureFormat::Rgba8),
                width: desc.width,
                height: desc.height,
                num_levels: 1,
            },
        );
        self.render_targets.insert(
            rt_handle,
            GpuRenderTarget {
                color_view,
                resolve_view,
                msaa,
                stencil,
                sample_count,
                width: desc.width,
                height: desc.height,
            },
        );

        RenderTargetBinding {
            handle: rt_handle,
            resolve_texture: TextureBinding {
                handle: resolve_handle,
                width: desc.width,
                height: desc.height,
                has_mipmaps: false,
                inverted: false,
                has_alpha: true,
            },
        }
    }

    /// Creates a render target with the size, stencil and sample count of
    /// `src`. Noesis allows the two to share transient buffers; this device
    /// doesn't. An unknown `src` logs a warning and gets a 1x1 target.
    pub fn clone_render_target(
        &mut self,
        label: &str,
        src: RenderTargetHandle,
    ) -> RenderTargetBinding {
        // Noesis allows the clone to share src's transient buffers; a fresh RT
        // of the same size and stencil is a valid, unshared implementation.
        let (width, height, sample_count, needs_stencil) = match self.render_targets.get(&src) {
            Some(rt) => (rt.width, rt.height, rt.sample_count, rt.stencil.is_some()),
            None => {
                warn!(
                    "clone_render_target '{label}': unknown source {src:?}; creating a 1x1 target"
                );
                (1, 1, 1, false)
            }
        };
        self.create_render_target(RenderTargetDesc {
            label,
            width,
            height,
            sample_count,
            needs_stencil,
        })
    }

    /// Releases a render target. Noesis releases its resolve texture
    /// separately through [`drop_texture`](Self::drop_texture).
    pub fn drop_render_target(&mut self, handle: RenderTargetHandle) {
        // The resolve texture is released separately through `drop_texture`.
        self.render_targets.remove(&handle);
    }

    /// Starts the offscreen phase and opens its command encoder.
    pub fn begin_offscreen_render(&mut self) {
        // A panic caught by the FFI trampoline in an earlier callback can leave
        // the phase open. Asserting would re-trip every frame; re-sync instead
        // (replacing `encoder` drops the stale one).
        if self.phase != FramePhase::Idle {
            warn!(
                "begin_offscreen_render found phase {:?} (previous frame aborted \
                 mid-callback); resetting",
                self.phase,
            );
        }
        self.pass = None;
        self.uniforms.reset();
        self.vertex_stream.reset();
        self.index_stream.reset();
        self.encoder = Some(
            self.device
                .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                    label: Some("noesis_wgpu offscreen frame"),
                }),
        );
        self.phase = FramePhase::Offscreen;
        self.current_rt = None;
        self.current_tile = None;
    }

    /// Ends the offscreen phase and submits its command encoder.
    pub fn end_offscreen_render(&mut self) {
        // Warn, don't assert: see `begin_offscreen_render`.
        if self.phase != FramePhase::Offscreen {
            warn!(
                "end_offscreen_render found phase {:?}, expected Offscreen",
                self.phase,
            );
        }
        self.pass = None;
        self.uniforms.flush(&self.queue);
        if let Some(encoder) = self.encoder.take() {
            self.queue.submit(Some(encoder.finish()));
        }
        self.phase = FramePhase::Idle;
        self.current_rt = None;
        self.current_tile = None;
    }

    /// Starts the onscreen phase and opens its command encoder. Draws go to
    /// the view set by [`set_onscreen_target`](Self::set_onscreen_target).
    pub fn begin_onscreen_render(&mut self) {
        // See `begin_offscreen_render`.
        if self.phase != FramePhase::Idle {
            warn!(
                "begin_onscreen_render found phase {:?} (previous frame aborted \
                 mid-callback); resetting",
                self.phase,
            );
        }
        self.pass = None;
        self.uniforms.reset();
        self.vertex_stream.reset();
        self.index_stream.reset();
        self.encoder = Some(
            self.device
                .create_command_encoder(&wgpu::CommandEncoderDescriptor {
                    label: Some("noesis_wgpu onscreen frame"),
                }),
        );
        self.phase = FramePhase::Onscreen;
        self.onscreen_stencil_cleared = false;
    }

    /// Ends the onscreen phase and submits its command encoder.
    pub fn end_onscreen_render(&mut self) {
        // See `begin_offscreen_render`.
        if self.phase != FramePhase::Onscreen {
            warn!(
                "end_onscreen_render found phase {:?}, expected Onscreen",
                self.phase,
            );
        }
        self.pass = None;
        self.uniforms.flush(&self.queue);
        if let Some(encoder) = self.encoder.take() {
            self.queue.submit(Some(encoder.finish()));
        }
        self.phase = FramePhase::Idle;
    }

    /// Makes `handle` the target of the offscreen draws that follow. Its
    /// stencil is cleared before the next draw.
    /// An unknown handle logs a warning, and offscreen draws skip until the
    /// next call.
    pub fn set_render_target(&mut self, handle: RenderTargetHandle) {
        self.pass = None;
        if self.phase != FramePhase::Offscreen {
            warn!("set_render_target called in the {:?} phase", self.phase);
        }
        if self.render_targets.contains_key(&handle) {
            self.current_rt = Some(handle);
        } else {
            warn!(
                "set_render_target: unknown render target {handle:?}; draws skip until the next one"
            );
            self.current_rt = None;
        }
        self.current_tile = None;
        // The protocol discards the RT's contents here, so re-clear its stencil.
        self.current_rt_stencil_cleared = false;
    }

    /// Limits the draws that follow to `tile`, given with a bottom-left
    /// origin, until [`end_tile`](Self::end_tile).
    pub fn begin_tile(&mut self, handle: RenderTargetHandle, tile: Tile) {
        if self.current_rt != Some(handle) {
            warn!("begin_tile for {handle:?}, which isn't the current render target");
        }
        self.current_tile = Some(tile);
    }

    /// Ends the tile started by [`begin_tile`](Self::begin_tile).
    pub fn end_tile(&mut self, handle: RenderTargetHandle) {
        if self.current_rt != Some(handle) {
            warn!("end_tile for {handle:?}, which isn't the current render target");
        }
        self.current_tile = None;
    }

    /// Resolves an MSAA render target into the texture Noesis samples. wgpu
    /// resolves whole textures, so this resolves all of it, not just `tiles`;
    /// Noesis only samples the tiles it drew. A no-op for a single-sampled
    /// target, which draws straight into that texture.
    pub fn resolve_render_target(&mut self, handle: RenderTargetHandle, _tiles: &[Tile]) {
        let Some(rt) = self.render_targets.get(&handle) else {
            warn!("resolve_render_target: unknown render target {handle:?}");
            return;
        };
        if rt.sample_count == 1 {
            return;
        }
        self.pass = None;
        let Some(encoder) = self.encoder.as_mut() else {
            warn!("resolve_render_target outside begin/end_offscreen_render; skipping");
            return;
        };
        encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
            label: Some("noesis_wgpu resolve"),
            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                view: &rt.color_view,
                depth_slice: None,
                resolve_target: Some(&rt.resolve_view),
                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,
        });
    }

    /// Returns `bytes` bytes of vertex storage for Noesis to fill. The data
    /// reaches the GPU at [`unmap_vertices`](Self::unmap_vertices).
    pub fn map_vertices(&mut self, bytes: u32) -> &mut [u8] {
        self.vertex_stream.map(bytes)
    }
    /// Uploads the vertices written since [`map_vertices`](Self::map_vertices).
    pub fn unmap_vertices(&mut self) {
        self.vertex_stream.unmap(&self.device, &self.queue);
    }
    /// Like [`map_vertices`](Self::map_vertices), for 16-bit indices.
    pub fn map_indices(&mut self, bytes: u32) -> &mut [u8] {
        self.index_stream.map(bytes)
    }
    /// Uploads the indices written since [`map_indices`](Self::map_indices).
    pub fn unmap_indices(&mut self) {
        self.index_stream.unmap(&self.device, &self.queue);
    }

    /// Draws `batch`, sampling the textures in `textures`.
    ///
    /// The batch's own texture pointers are ignored; its samplers, uniforms,
    /// shader and render state are used as given. A draw goes to the current
    /// render target and tile in the offscreen phase, and to the onscreen
    /// target in the onscreen phase. Consecutive draws into one target share a
    /// render pass.
    ///
    /// A batch that can't be drawn is skipped with a warning (logged once per
    /// cause) rather than a panic: one outside a phase or without a target,
    /// one whose shader needs a texture that `textures` leaves empty or names
    /// an unknown handle, one whose geometry runs past the mapped buffers, and
    /// one whose shader this device doesn't implement (`CUSTOM_EFFECT` and
    /// most `SDF_LCD_*` variants). So is a batch with a custom pixel shader:
    /// draw those with [`draw_custom_batch`](Self::draw_custom_batch).
    ///
    /// [`stats`](Self::stats) counts what was drawn and what was skipped.
    pub fn draw_batch_with(&mut self, batch: &Batch, textures: BatchTextures) {
        if batch.pixel_shader.is_null() {
            self.count_draw(batch, textures, None);
        } else {
            warn_once!("batch has a custom pixel shader; draw it with draw_custom_batch");
            self.stats.unsupported_shader_draws += 1;
        }
    }

    /// Draws `batch`, which has a custom pixel shader, with `shader`'s WGSL
    /// in place of part of the batch's shader: the paint of a pattern shader
    /// for a brush, the whole effect for `CUSTOM_EFFECT`. Everything else is
    /// as in [`draw_batch_with`](Self::draw_batch_with), which ignores
    /// `batch.pixel_shader` the way it ignores the texture pointers.
    ///
    /// Besides `draw_batch_with`'s reasons, the batch is skipped with a
    /// warning when `shader.shader` is unknown, when the shader's kind can't
    /// draw as the batch's shader or its WGSL fails there, or when
    /// `shader.textures` lacks a texture the shader declared.
    pub fn draw_custom_batch(
        &mut self,
        batch: &Batch,
        textures: BatchTextures,
        shader: BatchShader<'_>,
    ) {
        self.count_draw(batch, textures, Some(shader));
    }

    fn count_draw(&mut self, batch: &Batch, textures: BatchTextures, shader: Option<BatchShader>) {
        match self.record_draw(batch, textures, shader) {
            Ok(()) => self.stats.draws += 1,
            Err(SkippedDraw::Protocol) => self.stats.dropped_draws += 1,
            Err(SkippedDraw::UnsupportedShader) => self.stats.unsupported_shader_draws += 1,
        }
    }

    #[allow(clippy::too_many_lines)] // one pass of checks, then one render pass
    fn record_draw(
        &mut self,
        batch: &Batch,
        textures: BatchTextures,
        custom: Option<BatchShader>,
    ) -> Result<(), SkippedDraw> {
        let (has_stencil, clear_stencil, sample_count) = match self.phase {
            FramePhase::Onscreen => {
                if self.target_view.is_none() {
                    warn_once!("onscreen draw without set_onscreen_target; skipping");
                    return Err(SkippedDraw::Protocol);
                }
                let has = self.onscreen_stencil.is_some();
                (has, has && !self.onscreen_stencil_cleared, 1)
            }
            FramePhase::Offscreen => {
                let Some(rt) = self.current_rt.and_then(|h| self.render_targets.get(&h)) else {
                    warn_once!("offscreen draw without a live render target; skipping");
                    return Err(SkippedDraw::Protocol);
                };
                let has = rt.stencil.is_some();
                (
                    has,
                    has && !self.current_rt_stencil_cleared,
                    rt.sample_count,
                )
            }
            FramePhase::Idle => {
                warn_once!("draw outside begin/end_*_render; skipping");
                return Err(SkippedDraw::Protocol);
            }
        };

        // `(extra textures, constants size)` the custom shader declared.
        let declared = match custom {
            Some(custom) => {
                let Some(shader) = self.pipelines.custom(custom.shader) else {
                    self.warn_custom_shader(custom.shader, "isn't registered");
                    return Err(SkippedDraw::UnsupportedShader);
                };
                Some((shader.textures as usize, shader.constants as usize))
            }
            // CUSTOM_EFFECT only draws through a custom shader.
            None if batch.shader == Shader::CUSTOM_EFFECT => {
                self.warn_unsupported_shader(batch.shader.0);
                return Err(SkippedDraw::UnsupportedShader);
            }
            None => None,
        };

        let pixel_shader = custom.map(|custom| custom.shader);
        let Some(key) = PipelineKey::from_batch(batch, has_stencil, sample_count, pixel_shader)
        else {
            self.warn_unsupported_shader(batch.shader.0);
            return Err(SkippedDraw::UnsupportedShader);
        };

        // Build bind groups before borrowing `encoder` mutably.
        let shader = batch.shader.0;
        let paint = if shader_uses_paint_texture(shader) {
            let Some(slot) = batch_paint_texture(batch, textures) else {
                warn_once!("batch's shader samples a paint texture it wasn't given; skipping");
                return Err(SkippedDraw::Protocol);
            };
            Some(slot)
        } else {
            None
        };
        let mut paint_slots = [None; MAX_GROUP_SLOTS];
        paint_slots[0] = paint;
        let paint_key = match (custom, declared) {
            (Some(custom), Some((declared_textures, _))) => {
                if custom.textures[..declared_textures].contains(&None) {
                    warn_once!("custom shader draw lacks an extra texture it declared; skipping");
                    return Err(SkippedDraw::Protocol);
                }
                paint_slots[1..].copy_from_slice(&custom.textures);
                (TextureGroup::CustomPaint, paint_slots)
            }
            _ => (TextureGroup::Paint, paint_slots),
        };

        let image_slot = |uses: bool, texture: Option<TextureHandle>, sampler| {
            if !uses {
                return Ok(None);
            }
            texture
                .map(|t| Some((t, sampler)))
                .ok_or(SkippedDraw::Protocol)
        };
        let (Ok(image), Ok(shadow), Ok(glyphs)) = (
            image_slot(
                shader_uses_image_texture(shader),
                textures.image,
                batch.image_sampler,
            ),
            image_slot(
                shader_uses_shadow_texture(shader),
                textures.shadow,
                batch.shadow_sampler,
            ),
            image_slot(
                shader_uses_glyphs_texture(shader),
                textures.glyphs,
                batch.glyphs_sampler,
            ),
        ) else {
            warn_once!(
                "batch's shader samples an image, shadow or glyph texture it wasn't given; \
                 skipping"
            );
            return Err(SkippedDraw::Protocol);
        };
        let image_key = (TextureGroup::Image, [image, shadow, glyphs, None, None]);

        if !self.ensure_texture_group(paint_key) || !self.ensure_texture_group(image_key) {
            warn_once!("batch names an unknown texture; skipping");
            return Err(SkippedDraw::Protocol);
        }

        if !self.pipelines.ensure(key) {
            match pixel_shader {
                Some(handle) => self
                    .warn_custom_shader(handle, &format!("can't draw as Noesis shader {shader}")),
                None => self.warn_unsupported_shader(shader),
            }
            return Err(SkippedDraw::UnsupportedShader);
        }

        // Batch offsets are relative to the latest unmapped segment.
        let stride = u64::from(SIZE_FOR_FORMAT[key.vertex_format as usize]);
        let vertex_offset = self.vertex_stream.segment_base() + u64::from(batch.vertex_offset);
        let vertex_byte_count = u64::from(batch.num_vertices) * stride;
        let index_byte_offset = self.index_stream.segment_base() + u64::from(batch.start_index) * 2;
        let index_byte_count = u64::from(batch.num_indices) * 2;
        if vertex_offset + vertex_byte_count > self.vertex_stream.written_end()
            || index_byte_offset + index_byte_count > self.index_stream.written_end()
        {
            warn_once!("batch geometry runs past the mapped buffers; skipping");
            return Err(SkippedDraw::Protocol);
        }

        let ps1 = match (custom, declared) {
            (Some(custom), Some((_, constants))) => (
                custom
                    .constants
                    .unwrap_or_else(|| batch.pixel_uniforms[1].as_bytes()),
                constants.next_multiple_of(16),
            ),
            _ => (batch.pixel_uniforms[1].as_bytes(), PS_UNIFORM1_BUILTIN_SIZE),
        };
        let (vs_offset, ps_offset, ps1_offset) = self.upload_uniforms(batch, ps1);

        let (target, target_view, scissor, full, stencil_view) =
            if self.phase == FramePhase::Offscreen {
                let Some(handle) = self.current_rt else {
                    return Err(SkippedDraw::Protocol);
                };
                let Some(rt) = self.render_targets.get(&handle) else {
                    return Err(SkippedDraw::Protocol);
                };
                self.current_rt_stencil_cleared = true;
                let scissor = self
                    .current_tile
                    .map(|t| tile_scissor(t, rt.width, rt.height));
                let stencil = rt.stencil.as_ref().map(|(_, view)| view);
                (
                    PassTarget::Offscreen(handle),
                    &rt.color_view,
                    scissor,
                    (0, 0, rt.width, rt.height),
                    stencil,
                )
            } else {
                self.onscreen_stencil_cleared = true;
                let Some(view) = self.target_view.as_ref() else {
                    return Err(SkippedDraw::Protocol);
                };
                let stencil = self.onscreen_stencil.as_ref().map(|s| &s.view);
                // Onscreen draws never set a scissor, so the full rect is not needed.
                (PassTarget::Onscreen, view, None, (0, 0, 0, 0), stencil)
            };

        let pipeline = self.pipelines.get(key);
        let vertex_buffer = self.vertex_stream.buffer();
        let index_buffer = self.index_stream.buffer();
        let vs_bg = &self.uniforms.vs_bind_group;
        let ps_bg = &self.uniforms.ps_bind_group;
        let paint_bg = &self.texture_groups[&paint_key];
        let image_bg = &self.texture_groups[&image_key];
        let reuse = !clear_stencil && self.pass.as_ref().is_some_and(|open| open.target == target);
        if !reuse {
            self.pass = None;
            let Some(encoder) = self.encoder.as_mut() else {
                warn_once!("draw with no open command encoder; skipping");
                return Err(SkippedDraw::Protocol);
            };

            // Later draws load the stencil so the clip stack accumulates.
            let depth_stencil_attachment =
                stencil_view.map(|view| wgpu::RenderPassDepthStencilAttachment {
                    view,
                    depth_ops: None,
                    stencil_ops: Some(wgpu::Operations {
                        load: if clear_stencil {
                            wgpu::LoadOp::Clear(0)
                        } else {
                            wgpu::LoadOp::Load
                        },
                        store: wgpu::StoreOp::Store,
                    }),
                });

            let pass = encoder
                .begin_render_pass(&wgpu::RenderPassDescriptor {
                    label: Some("noesis_wgpu draw_batch"),
                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
                        view: target_view,
                        depth_slice: None,
                        resolve_target: None,
                        ops: wgpu::Operations {
                            load: wgpu::LoadOp::Load,
                            store: wgpu::StoreOp::Store,
                        },
                    })],
                    depth_stencil_attachment,
                    timestamp_writes: None,
                    occlusion_query_set: None,
                    multiview_mask: None,
                })
                .forget_lifetime();
            self.pass = Some(OpenPass {
                pass,
                target,
                scissor: None,
            });
        }
        let Some(open) = self.pass.as_mut() else {
            return Err(SkippedDraw::Protocol);
        };
        if open.scissor != scissor {
            let (x, y, w, h) = scissor.unwrap_or(full);
            open.pass.set_scissor_rect(x, y, w, h);
            open.scissor = scissor;
        }
        let rpass = &mut open.pass;
        rpass.set_pipeline(pipeline);
        if has_stencil {
            rpass.set_stencil_reference(u32::from(batch.stencil_ref));
        }
        rpass.set_bind_group(0, vs_bg, &[vs_offset]);
        rpass.set_bind_group(1, ps_bg, &[ps_offset, ps1_offset]);
        rpass.set_bind_group(2, paint_bg, &[]);
        rpass.set_bind_group(3, image_bg, &[]);
        rpass.set_vertex_buffer(
            0,
            vertex_buffer.slice(vertex_offset..vertex_offset + vertex_byte_count),
        );
        rpass.set_index_buffer(
            index_buffer.slice(index_byte_offset..index_byte_offset + index_byte_count),
            wgpu::IndexFormat::Uint16,
        );
        rpass.draw_indexed(0..batch.num_indices, 0, 0..1);
        Ok(())
    }

    /// Warns once per shader that this device can't draw it.
    fn warn_unsupported_shader(&mut self, shader: u8) {
        if self.warned_shaders.insert(shader) {
            warn!("Noesis shader {shader} isn't implemented; skipping its batches");
        }
    }

    /// Warns once per custom shader that its batches are skipped.
    fn warn_custom_shader(&mut self, handle: PixelShaderHandle, why: &str) {
        if self.warned_custom_shaders.insert(handle) {
            warn!("custom shader {handle:?} {why}; skipping its batches");
        }
    }
}

/// What a [`WgpuRenderDevice`] has drawn, from [`WgpuRenderDevice::stats`].
///
/// The batch counts add up over the device's life; subtract an earlier
/// snapshot to get one frame's figures. Each skipped batch also logs a warning,
/// once per cause.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash)]
pub struct DeviceStats {
    /// Batches drawn.
    pub draws: u64,
    /// Batches skipped because a call broke the render-device protocol: a draw
    /// outside a phase or without a target, a texture the batch's shader
    /// (or custom shader) needs but didn't get, an unknown texture handle, or
    /// geometry past the mapped buffers.
    pub dropped_draws: u64,
    /// Batches skipped because the device can't draw their shader: one it has
    /// no variant of, a custom shader that is unknown or can't draw as the
    /// batch's shader, or a custom batch passed to `draw_batch_with`.
    pub unsupported_shader_draws: u64,
    /// Render pipelines compiled so far, one per shader, custom shader, render
    /// state, and target stencil and sample count drawn.
    pub pipelines: usize,
}

impl std::ops::Sub for DeviceStats {
    type Output = Self;

    /// The batch counts between `rhs`, an earlier snapshot, and `self`.
    /// `pipelines` is `self`'s.
    fn sub(self, rhs: Self) -> Self {
        Self {
            draws: self.draws.saturating_sub(rhs.draws),
            dropped_draws: self.dropped_draws.saturating_sub(rhs.dropped_draws),
            unsupported_shader_draws: self
                .unsupported_shader_draws
                .saturating_sub(rhs.unsupported_shader_draws),
            pipelines: self.pipelines,
        }
    }
}

/// The textures a [`Batch`] samples, as device handles.
///
/// Noesis hands a batch its textures as pointers to its own texture objects.
/// [`WgpuRenderDevice::draw_batch_with`] takes handles instead, so a host that
/// creates Noesis's textures itself (and so knows which handle each pointer
/// stands for) can resolve them and pass them in. A field is `None` when the
/// batch leaves that slot empty. Samplers still come from the batch.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Hash)]
pub struct BatchTextures {
    /// Pattern (brush) texture, sampled with `batch.pattern_sampler`.
    pub pattern: Option<TextureHandle>,
    /// Gradient ramps, sampled with `batch.ramps_sampler`.
    pub ramps: Option<TextureHandle>,
    /// Offscreen image or effect input, sampled with `batch.image_sampler`.
    pub image: Option<TextureHandle>,
    /// SDF glyph atlas, sampled with `batch.glyphs_sampler`.
    pub glyphs: Option<TextureHandle>,
    /// Shadow intermediate, sampled with `batch.shadow_sampler`.
    pub shadow: Option<TextureHandle>,
}

impl BatchTextures {
    /// Reads the handles out of `batch`'s texture pointers through
    /// `noesis_runtime`'s shim. Only valid when every texture in the batch was
    /// created through a device registered with
    /// [`noesis_runtime::render_device::register`].
    #[cfg(feature = "shim")]
    #[must_use]
    pub fn from_batch(batch: &Batch) -> Self {
        Self {
            pattern: batch.pattern_handle(),
            ramps: batch.ramps_handle(),
            image: batch.image_handle(),
            glyphs: batch.glyphs_handle(),
            shadow: batch.shadow_handle(),
        }
    }
}

/// Lets `noesis_runtime`'s shim drive the device: pass it to
/// [`noesis_runtime::render_device::register`]. Each method forwards to the
/// inherent method of the same name, and `draw_batch` reads the batch's
/// textures with [`BatchTextures::from_batch`] and its custom shader, if any,
/// with [`BatchShader::from_batch`].
#[cfg(feature = "shim")]
impl RenderDevice for WgpuRenderDevice {
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
        self
    }

    fn caps(&self) -> DeviceCaps {
        Self::caps(self)
    }

    fn create_texture(&mut self, desc: TextureDesc<'_>) -> TextureBinding {
        Self::create_texture(self, desc)
    }

    fn update_texture(
        &mut self,
        handle: TextureHandle,
        level: u32,
        rect: TextureRect,
        data: &[u8],
    ) {
        Self::update_texture(self, handle, level, rect, data);
    }

    fn end_updating_textures(&mut self, textures: &[TextureHandle]) {
        Self::end_updating_textures(self, textures);
    }

    fn drop_texture(&mut self, handle: TextureHandle) {
        Self::drop_texture(self, handle);
    }

    fn create_render_target(&mut self, desc: RenderTargetDesc<'_>) -> RenderTargetBinding {
        Self::create_render_target(self, desc)
    }

    fn clone_render_target(&mut self, label: &str, src: RenderTargetHandle) -> RenderTargetBinding {
        Self::clone_render_target(self, label, src)
    }

    fn drop_render_target(&mut self, handle: RenderTargetHandle) {
        Self::drop_render_target(self, handle);
    }

    fn begin_offscreen_render(&mut self) {
        Self::begin_offscreen_render(self);
    }

    fn end_offscreen_render(&mut self) {
        Self::end_offscreen_render(self);
    }

    fn begin_onscreen_render(&mut self) {
        Self::begin_onscreen_render(self);
    }

    fn end_onscreen_render(&mut self) {
        Self::end_onscreen_render(self);
    }

    fn set_render_target(&mut self, handle: RenderTargetHandle) {
        Self::set_render_target(self, handle);
    }

    fn begin_tile(&mut self, handle: RenderTargetHandle, tile: Tile) {
        Self::begin_tile(self, handle, tile);
    }

    fn end_tile(&mut self, handle: RenderTargetHandle) {
        Self::end_tile(self, handle);
    }

    fn resolve_render_target(&mut self, handle: RenderTargetHandle, tiles: &[Tile]) {
        Self::resolve_render_target(self, handle, tiles);
    }

    fn map_vertices(&mut self, bytes: u32) -> &mut [u8] {
        Self::map_vertices(self, bytes)
    }

    fn unmap_vertices(&mut self) {
        Self::unmap_vertices(self);
    }

    fn map_indices(&mut self, bytes: u32) -> &mut [u8] {
        Self::map_indices(self, bytes)
    }

    fn unmap_indices(&mut self) {
        Self::unmap_indices(self);
    }

    fn draw_batch(&mut self, batch: &Batch) {
        let textures = BatchTextures::from_batch(batch);
        match BatchShader::from_batch(batch) {
            Some(shader) => self.draw_custom_batch(batch, textures, shader),
            None => self.draw_batch_with(batch, textures),
        }
    }
}