unlit_wgpu/

ui.rs

//! An [egui](https://egui.rs) backend built on the built-in lit pipeline.
//!
//! [`EguiIntegration`] takes what egui produces each frame — tessellated, clipped
//! meshes plus a set of texture updates — and draws it with the built-in
//! pipeline as ordinary screen-space geometry. Nothing in the shader knows
//! about egui: the UI is premultiplied, textured, screen-space vertices, and
//! egui's clip rectangles become scissor rectangles.
//!
//! ```rust
//! # use unlit_wgpu::globals::Globals;
//! # use unlit_wgpu::pipeline::{CAMERA_BINDING, FRAME_BINDING, VIEW_BINDING};
//! # use unlit_wgpu::resources::ResourceGraph;
//! # use unlit_wgpu::specialize::{SpecializedPipeline, SurfaceKey};
//! # use unlit_wgpu::ui::{
//! #     EguiIntegration, ScreenDescriptor, screen_view, screen_viewport, ui_variant,
//! # };
//! # use zerocopy::IntoBytes;
//! # fn frame(device: &wgpu::Device, queue: &wgpu::Queue, ctx: &egui::Context,
//! #          surface: SurfaceKey) {
//! // The caller owns the globals: a camera uniform (written every frame with
//! // `screen_view`), a frame-globals uniform, the view `screen_viewport`
//! // derives from the same points, and the bind group binding all three.
//! let variant = ui_variant(/* the target encodes sRGB: */ true, surface);
//! let pipeline = SpecializedPipeline::create(device, variant);
//! let camera = uniform_buffer(device, "ui::camera");
//! let globals = uniform_buffer(device, "ui::globals");
//! let view = uniform_buffer(device, "ui::view");
//! let global_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
//!     label: Some("ui::globals"),
//!     layout: &pipeline.descriptor().bind_group_layouts(device).global,
//!     entries: &[
//!         wgpu::BindGroupEntry {
//!             binding: CAMERA_BINDING,
//!             resource: camera.as_entire_binding(),
//!         },
//!         wgpu::BindGroupEntry {
//!             binding: FRAME_BINDING,
//!             resource: globals.as_entire_binding(),
//!         },
//!         wgpu::BindGroupEntry {
//!             binding: VIEW_BINDING,
//!             resource: view.as_entire_binding(),
//!         },
//!     ],
//! });
//!
//! // The camera and the view are written every frame; the UI reads no clock,
//! // so its frame globals stay at their default.
//! queue.write_buffer(&camera, 0, screen_view([256.0, 192.0]).as_bytes());
//! queue.write_buffer(&view, 0, screen_viewport([256.0, 192.0]).as_bytes());
//! queue.write_buffer(&globals, 0, Globals::default().as_bytes());
//!
//! // The UI's per-texture resources join the caller's ledger.
//! let mut graph = ResourceGraph::new();
//! let camera_id = graph.insert(camera, None);
//! let globals_id = graph.insert(globals, None);
//! let view_id = graph.insert(view, None);
//! let group_id = graph.insert(global_group, None);
//! graph.add_dependency(&group_id, &camera_id);
//! graph.add_dependency(&group_id, &globals_id);
//! graph.add_dependency(&group_id, &view_id);
//!
//! let mut ui = EguiIntegration::new(device, pipeline);
//! let mut input = egui::RawInput::default();
//! input.screen_rect = Some(egui::Rect::from_min_size(
//!     egui::Pos2::ZERO,
//!     egui::Vec2::new(256.0, 192.0),
//! ));
//! let output = ctx.run_ui(input, |ui| {
//!     ui.label("hello world");
//! });
//! // The frame's encoder carries both the UI's staged vertex and index
//! // uploads and the pass that reads them; `scene` is recorded into it
//! // after this call.
//! let mut encoder = device.create_command_encoder(&Default::default());
//! // The target's physical size and its density, which the clip rectangles
//! // are scaled by.
//! let screen = ScreenDescriptor {
//!     size_in_pixels: [256, 192],
//!     pixels_per_point: 1.0,
//! };
//! ui.update(&mut graph, queue, &mut encoder, ctx, output, screen);
//! let scene = ui.scene(&graph, &graph.get(&group_id).expect("the group exists"));
//! # }
//! # fn uniform_buffer(device: &wgpu::Device, label: &str) -> wgpu::Buffer {
//! #     device.create_buffer(&wgpu::BufferDescriptor {
//! #         label: Some(label),
//! #         size: 256,
//! #         usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
//! #         mapped_at_creation: false,
//! #     })
//! # }
//! ```

use crate::globals::{Camera, View};
use crate::mesh::{ChannelEncoding, MeshInstance, PositionStreamChannels, SecondaryFlags};
use crate::pipeline::{
    BASE_COLOR_SAMPLER_BINDING, BASE_COLOR_TEXTURE_BINDING, GLOBAL_GROUP, INSTANCE_SLOT,
    LitOptions, LitVariant, LitVertexChannels, MATERIAL_GROUP, PRIMARY_SLOT, SECONDARY_SLOT,
    SpecializedLitPipeline,
};
use crate::resources::{Rebuild, ResHandle, Resource, ResourceGraph, TextureExt, TextureView};
use crate::scene::{DrawEntry, DrawOrder, DrawRange, Scene, ScissorRect};
use crate::specialize::SurfaceKey;
use crate::staging::StagingBuffer;
use crate::util::Hashed;
use core::ops::Range;
use hashbrown::HashMap;
use zerocopy::IntoBytes;

/// egui's own texture format: gamma-space RGBA, never sRGB-aware.
///
/// egui's vertex colors and its font atlas are already gamma-encoded, so a
/// texture is sampled without conversion and the pipeline's own output
/// conversion deals with the target instead.
const TEXTURE_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;

/// Bytes one planar-position vertex occupies.
///
/// The UI writes positions at full precision and in the plane, so this is
/// [`ChannelEncoding::PlanarPosition`]'s format: two components, with the
/// zero third supplied by the shader rather than stored.
const POSITION_STRIDE: usize = wgpu::VertexFormat::Float32x2.size() as usize;

/// Bytes one secondary vertex occupies: `Float32x2` then `Unorm8x4`.
const SECONDARY_STRIDE: usize =
    wgpu::VertexFormat::Float32x2.size() as usize + wgpu::VertexFormat::Unorm8x4.size() as usize;

/// The target a UI frame is drawn into and the density it is drawn at.
///
/// The two are needed together and in opposite units, which is the easiest
/// thing to get wrong here: egui tessellates in **logical points**, so the
/// projection takes the point size, while a scissor rectangle is in **physical
/// pixels**, so the clip rectangles are scaled by [`Self::pixels_per_point`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ScreenDescriptor {
    /// The target's size in physical pixels.
    pub size_in_pixels: [u32; 2],
    /// How many physical pixels one logical point covers.
    pub pixels_per_point: f32,
}

impl ScreenDescriptor {
    /// The target's size in logical points, which is what the UI's projection
    /// and its `RawInput::screen_rect` are expressed in.
    pub fn size_in_points(self) -> [f32; 2] {
        [
            self.size_in_pixels[0] as f32 / self.pixels_per_point,
            self.size_in_pixels[1] as f32 / self.pixels_per_point,
        ]
    }
}

/// A world-to-clip matrix taking egui's tessellated points to clip space.
///
/// egui positions its vertices in logical points with the origin at the top
/// left and Y growing downwards, so the Y coefficient is negated; Z collapses
/// to zero, since everything the UI draws sits at one depth. The physical
/// density never enters: the target's format already encodes its pixels.
///
/// The caller writes this into their camera uniform, since the camera buffer
/// is theirs; [`screen_viewport`] is the view to bind beside it.
pub fn screen_view(viewport_points: [f32; 2]) -> Camera {
    let [width, height] = viewport_points;
    Camera::from_clip_from_world(
        glam::Mat4::from_cols_array(&[
            2.0 / width,
            0.0,
            0.0,
            0.0,
            0.0,
            -2.0 / height,
            0.0,
            0.0,
            0.0,
            0.0,
            0.0,
            0.0,
            -1.0,
            1.0,
            0.0,
            1.0,
        ]),
        glam::Vec3::ZERO,
    )
}

/// The view to bind beside [`screen_view`].
///
/// The clipping is in points, so the size a shader measures against is the point
/// size too: that is what keeps the two in one unit.
pub fn screen_viewport(viewport_points: [f32; 2]) -> View {
    View::new(viewport_points[0], viewport_points[1])
}

/// The pipeline variant a UI is drawn with.
///
/// `srgb_to_linear_output` is the caller's call, not this function's: it
/// depends on the target's format, which this function never sees. Set it
/// when the target encodes sRGB.
///
/// Every UI draw has the same shape: full-precision screen-space vertices
/// carrying a premultiplied color and a texture coordinate, no skinning and no
/// morph target, and a base-color texture sampled through a material group.
/// What changes with the target is the surface the variant carries, so this is
/// the only place a UI variant is built.
pub fn ui_variant(srgb_to_linear_output: bool, surface: SurfaceKey) -> LitVariant {
    let mut options = LitOptions::standard();
    apply_ui_settings(&mut options, srgb_to_linear_output);
    LitVariant {
        options: Hashed::new(options),
        surface,
        channels: ui_channels(),
        base_color_texture: true,
        morph: false,
        strip_index_format: None,
    }
}

/// The per-vertex channels a UI mesh is packed with.
///
/// The UI writes positions at full precision and in the plane — two components,
/// with the shader supplying the zero third — and needs no skinning, and every
/// vertex carries a texture coordinate and a premultiplied color. A caller
/// packing a UI mesh builds its streams to match this.
pub fn ui_channels() -> LitVertexChannels {
    LitVertexChannels {
        position: PositionStreamChannels {
            position: Some(ChannelEncoding::PlanarPosition),
            joints: false,
        },
        secondary: SecondaryFlags::UV | SecondaryFlags::UNCOMPRESSED_UV | SecondaryFlags::COLOR,
    }
}

/// Apply the UI's device-independent policy — the output conversion, culling,
/// blending and the overlaid depth behavior — to a standard options set.
///
/// The geometry the UI draws with is not policy and lives in
/// [`ui_channels`] and the variant: an encoding, a skin or a morph target is
/// a property of the mesh, not of what the caller picked.
fn apply_ui_settings(options: &mut LitOptions, srgb_to_linear_output: bool) {
    options.srgb_to_linear_output = srgb_to_linear_output;
    // A UI fragment composites what egui tessellated and shades nothing: the
    // overlay is drawn after the scene, so a light would tint text.
    options.unlit = true;
    // No culling: egui does not guarantee a consistent winding order across
    // the primitives it emits, so neither face can be discarded safely.
    // (`LitOptions::standard` culls back faces for closed meshes; the UI is
    // flat, overlay geometry with no inside to hide.)
    options.primitive.cull_mode = None;
    // egui tessellates premultiplied colors, so the source's RGB is added to
    // the destination scaled by the alpha it leaves behind.
    options.blend = Some(wgpu::BlendState {
        color: wgpu::BlendComponent {
            src_factor: wgpu::BlendFactor::One,
            dst_factor: wgpu::BlendFactor::OneMinusSrcAlpha,
            operation: wgpu::BlendOperation::Add,
        },
        alpha: wgpu::BlendComponent {
            src_factor: wgpu::BlendFactor::OneMinusDstAlpha,
            dst_factor: wgpu::BlendFactor::One,
            operation: wgpu::BlendOperation::Add,
        },
    });
    // The UI overlays whatever the pass holds, so it neither tests nor writes
    // depth. Whether the target has a depth attachment at all is decided by
    // the surface the variant carries; the policy only says what a target
    // with one would run.
    options.depth_stencil.depth_write_enabled = false;
    options.depth_stencil.depth_compare = wgpu::CompareFunction::Always;
}

/// How much geometry a frame holds: the two numbers the packing and the draw
/// ranges both need, and which must agree between them.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct GeometryCounts {
    vertices: usize,
    indices: usize,
}

/// Count the vertices and indices every tessellated primitive in
/// `primitives` contributes.
fn measure<'a>(
    primitives: impl IntoIterator<Item = (Source, &'a egui::ClippedPrimitive)>,
) -> GeometryCounts {
    let mut counts = GeometryCounts {
        vertices: 0,
        indices: 0,
    };
    for (_, primitive) in primitives {
        if let Some(mesh) = mesh_of(primitive) {
            counts.vertices += mesh.vertices.len();
            counts.indices += mesh.indices.len();
        }
    }
    counts
}

/// Pack `primitives` into `vertices` and `indices`, and fill `draws` with where
/// each one landed.
///
/// Both byte buffers are cleared and resized rather than reallocated, so a
/// caller that keeps them across frames reuses the allocation. The vertex
/// buffer holds the primary stream first and the interleaved secondary
/// stream second: wgpu binds one stride per slot and the two differ.
///
/// `counts` must be what [`measure`] returned for `primitives`: it is both how
/// much is written and where the two vertex streams meet.
fn pack_geometry<'a>(
    primitives: impl IntoIterator<Item = (Source, &'a egui::ClippedPrimitive)>,
    screen: ScreenDescriptor,
    texture_options: &HashMap<TextureKey, egui::TextureOptions>,
    counts: GeometryCounts,
    vertices: &mut Vec<u8>,
    indices: &mut Vec<u8>,
    draws: &mut Vec<UiDraw>,
) {
    // The split between the two streams is the frame's own vertex count, which
    // is what `scene` reads back. It is *not* the buffer's capacity: that is
    // usually larger, and splitting on it would write the UVs and colors
    // somewhere the draws do not look for them.
    let secondary_start = counts.vertices * POSITION_STRIDE;
    let vertex_count = counts.vertices;
    let index_count = counts.indices;

    vertices.clear();
    vertices.resize(secondary_start + vertex_count * SECONDARY_STRIDE, 0);
    indices.clear();
    indices.resize(index_count * size_of::<u32>(), 0);
    draws.clear();

    let mut vertex_cursor = 0usize;
    let mut index_cursor = 0usize;
    for (source, primitive) in primitives {
        // A paint callback draws its own way; this renderer handles tessellated
        // meshes only.
        let Some(mesh) = mesh_of(primitive) else {
            continue;
        };
        if mesh.vertices.is_empty() || mesh.indices.is_empty() {
            continue;
        }

        let first_vertex = vertex_cursor as u32;
        let first_index = index_cursor as u32;

        for vertex in &mesh.vertices {
            let position = vertex_cursor * POSITION_STRIDE;
            // The UI is flat: two components, the shader supplies the zero
            // third.
            vertices[position..position + POSITION_STRIDE]
                .copy_from_slice([vertex.pos.x, vertex.pos.y].as_bytes());
            let secondary = secondary_start + vertex_cursor * SECONDARY_STRIDE;
            vertices[secondary..secondary + size_of::<egui::Vec2>()]
                .copy_from_slice([vertex.uv.x, vertex.uv.y].as_bytes());
            // egui's colors are premultiplied already, straight to Unorm8.
            vertices[secondary + size_of::<egui::Vec2>()..secondary + SECONDARY_STRIDE]
                .copy_from_slice(&vertex.color.to_array());
            vertex_cursor += 1;
        }

        let index_start = index_cursor * size_of::<u32>();
        for (slot, &index) in indices[index_start..]
            .as_chunks_mut::<{ size_of::<u32>() }>()
            .0
            .iter_mut()
            .zip(&mesh.indices)
        {
            // The primitive's indices are local to its own vertices, and the
            // draw addresses both streams by a pool-global ordinal, so the
            // primitive's first vertex is added here. Baking it into the
            // indices rather than passing it as the draw's `base_vertex` costs
            // nothing — the indices are rewritten every frame either way — and
            // it is the only form a device without `base_vertex` (WebGL2)
            // accepts.
            slot.copy_from_slice((index + first_vertex).as_bytes());
        }
        index_cursor += mesh.indices.len();

        let texture = TextureKey {
            source,
            id: mesh.texture_id,
        };
        draws.push(UiDraw {
            indices: first_index..index_cursor as u32,
            texture,
            // The texture's own sampling options, not a default: a texture egui
            // asked to sample nearest or to tile would otherwise be sampled
            // linearly and clamped, and the sampler that matches `options` is
            // the one the material binds.
            options: texture_options.get(&texture).copied().unwrap_or_default(),
            scissor: scissor_rect(primitive.clip_rect, screen),
        });
    }
}

/// One uploaded primitive: where its indices sit, what it samples and how it
/// is clipped.
struct UiDraw {
    /// Index range into the index buffer, counting indices.
    ///
    /// The indices themselves already name the primitive's vertices in the
    /// pool, so a draw needs no `base_vertex` to address them; see
    /// [`pack_geometry`].
    indices: Range<u32>,
    /// The texture this primitive samples, and the context it came from.
    texture: TextureKey,
    options: egui::TextureOptions,
    scissor: ScissorRect,
}

/// The graph nodes backing one egui texture slot.
///
/// A slot needs both: the texture, because egui patches its own atlases with
/// partial updates and a patch is written into the texture, and the view,
/// because a material bind group samples the view. They are two nodes with an
/// edge between them, so a patched texture and everything built from it stay
/// the same resources.
#[derive(Clone)]
struct TextureSlot {
    /// The texture egui's deltas are written into.
    texture: ResHandle<wgpu::Texture>,
    /// The default view over it, which the material samples.
    view: ResHandle<TextureView>,
}

/// Draws tessellated egui output with the built-in lit pipeline.
///
/// The UI's GPU resources are registered in a [`ResourceGraph`] the caller
/// supplies — normally the one kept alongside the
/// [`RenderAttachments`](crate::render_attachments::RenderAttachments) — so
/// the whole frame shares one ledger. Every method that touches the graph
/// takes it as an argument: the renderer holds only the bookkeeping (ids,
/// keys) that maps egui's world onto graph nodes.
pub struct EguiIntegration {
    /// Kept to build the resources a frame turns out to need.
    device: wgpu::Device,
    pipeline: SpecializedLitPipeline,
    /// Graph nodes of every allocated texture slot, keyed by origin and id.
    textures: HashMap<TextureKey, TextureSlot>,
    /// The sampling options egui last stated for each texture.
    ///
    /// Kept separately from the texture itself because every [`ImageDelta`]
    /// carries the options that apply to the whole texture, and the draw that
    /// samples it has to name the matching sampler:
    /// [`Self::sampler`] keys its cache on exactly these options, so a texture
    /// uploaded as nearest samples nearest.
    ///
    /// [`ImageDelta`]: egui::epaint::ImageDelta
    texture_options: HashMap<TextureKey, egui::TextureOptions>,
    /// One sampler per distinct set of egui sampling options seen, with its
    /// graph node.
    samplers: Vec<(egui::TextureOptions, ResHandle<wgpu::Sampler>)>,
    /// One material bind group per (texture, options) pair, with its graph
    /// node; the node depends on the texture's view and the sampler.
    materials: Vec<(MaterialKey, ResHandle<wgpu::BindGroup>)>,
    /// Positions, then interleaved UVs and colors.
    vertices: Option<wgpu::Buffer>,
    /// `Uint32` indices.
    indices: Option<wgpu::Buffer>,
    /// Graph node of the vertex buffer, replaced in place when it grows.
    vertex_node: Option<ResHandle<wgpu::Buffer>>,
    /// Graph node of the index buffer, replaced in place when it grows.
    index_node: Option<ResHandle<wgpu::Buffer>>,
    /// One default [`MeshInstance`], bound at [`INSTANCE_SLOT`] by every
    /// draw.
    ///
    /// The built-in pipeline always declares the instance stream, and a UI
    /// draw reads no instance state, so one identity record serves every draw.
    /// It never changes, so it needs no graph node.
    instance: wgpu::Buffer,
    /// Vertices the vertex buffer holds room for.
    vertex_capacity: usize,
    /// Indices the index buffer holds room for.
    index_capacity: usize,
    /// Vertices the most recently uploaded frame holds. This is where its two
    /// vertex streams meet, so [`Self::scene`] has to split at the same point
    /// [`Self::upload_geometry`] packed at — which is not the capacity whenever
    /// the buffer has room to spare.
    frame_vertices: usize,
    /// Staging buffer for the per-frame vertex uploads, reused across frames.
    vertex_staging: StagingBuffer,
    /// Staging buffer for the per-frame index uploads, reused across frames.
    index_staging: StagingBuffer,
    /// Layout of the frame most recently uploaded.
    draws: Vec<UiDraw>,
    /// Packing scratch for the vertex stream — positions then interleaved UVs
    /// and colors — kept so a steady UI reuses one allocation instead of taking
    /// a fresh one every frame.
    packed_vertices: Vec<u8>,
    /// Packing scratch for the index stream, reused the same way.
    packed_indices: Vec<u8>,
}

/// Which context a texture belongs to.
///
/// Every egui context allocates its texture ids from zero, so one id names
/// different images in different contexts. A UI drawn from several contexts —
/// the world's own panels plus a frame laid out in another world — therefore
/// keys its textures by this pair rather than by the id alone, which is what
/// keeps two contexts' atlases apart without rewriting the ids a frame
/// carries.
///
/// The origin of the world's own panels is [`Source::LOCAL`]; every other
/// publisher picks its own, and the numbers are that publisher's to allocate.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
pub struct Source(pub u32);

impl Source {
    /// The context of the world doing the drawing.
    pub const LOCAL: Self = Self(0);

    /// The context of the world publishing into `slot`.
    ///
    /// The number is the slot's plus one, so no publisher collides with the
    /// drawing world's own panels and each slot has a namespace of its own.
    #[must_use]
    pub const fn published(slot: usize) -> Self {
        Self(slot as u32 + 1)
    }
}

/// One texture of one source.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
struct TextureKey {
    source: Source,
    id: egui::TextureId,
}

/// One source's contribution to a frame: what to upload and what it owns.
///
/// The textures are consumed — a delta is applied once, and egui panics when
/// one is dropped unapplied — while the primitives are borrowed: a frame laid
/// out in another world is drawn again on every drawn frame until that world
/// publishes a newer one, so its tessellation has to outlive the upload.
pub struct UiFrame<'a> {
    /// Which context this contribution came from.
    pub source: Source,
    /// The context's texture updates for this frame.
    pub textures: egui::TexturesDelta,
    /// The context's tessellated geometry.
    pub primitives: &'a [egui::ClippedPrimitive],
}

/// What one material bind group was built from.
#[derive(Clone, Copy, PartialEq, Eq)]
struct MaterialKey {
    texture: TextureKey,
    options: egui::TextureOptions,
}

/// A one-element buffer holding the identity [`MeshInstance`].
///
/// The built-in lit pipeline declares the instance stream for every variant,
/// so a draw that binds nothing at [`INSTANCE_SLOT`] is rejected. A UI draw
/// reads no instance state — its vertices are already in screen space — so one
/// default record satisfies the slot for every draw the integration records.
fn default_instance(device: &wgpu::Device) -> wgpu::Buffer {
    let instance = MeshInstance::default();
    let buffer = device.create_buffer(&wgpu::BufferDescriptor {
        label: Some("ui::instance"),
        size: size_of::<MeshInstance>() as u64,
        usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
        mapped_at_creation: true,
    });
    buffer
        .slice(..)
        .get_mapped_range_mut()
        .expect("mapped at creation")
        .copy_from_slice(instance.as_bytes());
    buffer.unmap();
    buffer
}

impl EguiIntegration {
    /// Build the UI integration around a caller-supplied `pipeline`,
    /// registering the UI's per-texture resources in `graph`.
    ///
    /// `pipeline` is the built-in lit pipeline the UI draws with, configured
    /// for the target the pass renders into — its color format, sample count
    /// and blend state. The caller builds it up front, so the UI does not
    /// compile a pipeline of its own.
    ///
    /// The global bind group — the camera, the frame globals and the view —
    /// is the caller's, and it is handed to [`Self::scene`] rather than kept
    /// here: the frame owns the uniforms and builds one group per camera and
    /// viewport its draws name, so a source can draw the same UI through two
    /// cameras without owning either group. Everything else the UI overlays is
    /// the caller's too: the integration owns only egui's textures and the
    /// geometry they are drawn with. Sharing the caller's graph — usually the
    /// one kept alongside the
    /// [`crate::render_attachments::RenderAttachments`] — means those
    /// resources live in the same ledger as the rest of the frame's, with the
    /// same dependency tracking.
    pub fn new(device: &wgpu::Device, pipeline: SpecializedLitPipeline) -> Self {
        Self {
            device: device.clone(),
            pipeline,
            textures: HashMap::new(),
            texture_options: HashMap::new(),
            samplers: Vec::new(),
            materials: Vec::new(),
            vertices: None,
            indices: None,
            vertex_node: None,
            index_node: None,
            instance: default_instance(device),
            vertex_capacity: 0,
            index_capacity: 0,
            frame_vertices: 0,
            vertex_staging: StagingBuffer::new(),
            index_staging: StagingBuffer::new(),
            draws: Vec::new(),
            packed_vertices: Vec::new(),
            packed_indices: Vec::new(),
        }
    }

    /// Apply `output`'s texture updates and upload its tessellated shapes,
    /// ready for [`Self::scene`].
    ///
    /// The vertex and index bytes change every frame, so they are staged
    /// through `encoder`: `scene`'s pass is recorded into the same encoder
    /// afterwards, and one submission carries the upload and the draw that
    /// reads it. Texture updates still go through `queue`.
    ///
    /// `screen` tells egui how to rasterise text and scales the tessellated points
    /// and their clip rectangles; see [`ScreenDescriptor`].
    ///
    /// This tessellates `output` with `ctx`, which is right when the context
    /// and the drawing share a world. A caller whose shapes were laid out
    /// elsewhere — in another world, by another context — uses
    /// [`Self::update_with`] and tessellates where the context lives.
    pub fn update(
        &mut self,
        graph: &mut ResourceGraph,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        ctx: &egui::Context,
        mut output: egui::FullOutput,
        screen: ScreenDescriptor,
    ) {
        let primitives = ctx.tessellate(output.shapes, screen.pixels_per_point);
        let textures = core::mem::take(&mut output.textures_delta);
        let mut sources = [UiFrame {
            source: Source::LOCAL,
            textures,
            primitives: &primitives,
        }];
        self.update_with(graph, queue, encoder, &mut sources, screen);
    }

    /// Apply texture updates and upload primitives from every source, ready
    /// for [`Self::scene`].
    ///
    /// Tessellation needs the [`egui::Context`] that produced the shapes — its
    /// font atlas and tessellation options — so a UI laid out in one world and
    /// drawn in another cannot be tessellated by the drawing side. Such a
    /// caller tessellates where each context lives and hands each result over
    /// with the [`Source`] it came from.
    ///
    /// A source is a namespace, not an identity: every context allocates its
    /// texture ids from zero, so the same id names different images in
    /// different sources. Keys carry the pair, and the ids a frame arrived
    /// with are the ids it is drawn by — nothing rewrites them.
    ///
    /// One call per frame: the integration packs one vertex and index buffer,
    /// and the two vertex streams meet at a single split point, so a second
    /// call would overwrite the first.
    ///
    /// Each `textures` delta is applied and then cleared, so the caller may
    /// drop it afterwards: egui panics when a delta is dropped unapplied.
    pub fn update_with(
        &mut self,
        graph: &mut ResourceGraph,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        sources: &mut [UiFrame<'_>],
        screen: ScreenDescriptor,
    ) {
        for frame in sources.iter_mut() {
            self.apply_textures(graph, queue, frame.source, &frame.textures);
            // egui panics if a delta is dropped unapplied, so mark it handled.
            frame.textures.clear();
        }

        // The primitives of every source, flattened in place: the sources
        // keep their own tessellation and this walks it without collecting a
        // list of borrows first.
        let primitives = sources.iter().flat_map(|frame| {
            frame
                .primitives
                .iter()
                .map(move |primitive| (frame.source, primitive))
        });

        let counts = measure(primitives);
        if counts.vertices == 0 {
            self.draws.clear();
            return;
        }
        self.reserve(graph, counts);
        self.frame_vertices = counts.vertices;
        let primitives = sources.iter().flat_map(|frame| {
            frame
                .primitives
                .iter()
                .map(move |primitive| (frame.source, primitive))
        });
        self.upload_geometry(encoder, primitives, screen, counts);

        // Build every material the frame needs here, while the graph is still
        // mutably available: `scene` only reads it, so a material that does
        // not exist yet by then is one this frame cannot draw.
        //
        // The draws are walked by index because `build_material` needs `&mut
        // self`: collecting the keys first would allocate a `Vec` every frame
        // for a list that is already `self.draws`.
        for index in 0..self.draws.len() {
            let (texture, options) = {
                let draw = &self.draws[index];
                (draw.texture, draw.options)
            };
            self.build_material(graph, texture, options);
        }
    }

    /// Forget every graph node the integration registered, and its bookkeeping.
    ///
    /// The ids this drops are the last references the graph holds to the two
    /// geometry buffers, every texture, view, sampler and material, so the next
    /// [`ResourceGraph::maintain`] collects them — and, once the material nodes
    /// go, the views and textures they were the last holders of. No graph is
    /// needed here: giving a resource up is dropping its id.
    ///
    /// After this the integration is back to its freshly built state and may be
    /// reused against the same graph.
    pub fn release(&mut self) {
        self.textures.clear();
        self.texture_options.clear();
        self.materials.clear();
        self.samplers.clear();
        self.vertex_node = None;
        self.index_node = None;
        self.vertices = None;
        self.indices = None;
        self.instance = default_instance(&self.device);
        self.vertex_capacity = 0;
        self.index_capacity = 0;
        self.frame_vertices = 0;
        self.draws.clear();
    }

    /// Pack `primitives` into the vertex and index buffers, staging the bytes
    /// through `encoder`, and fill [`Self::draws`] with where each one landed.
    ///
    /// The primary and secondary streams go into two regions of the one buffer:
    /// wgpu binds one stride per slot, and the two streams differ.
    fn upload_geometry<'a>(
        &mut self,
        encoder: &mut wgpu::CommandEncoder,
        primitives: impl IntoIterator<Item = (Source, &'a egui::ClippedPrimitive)>,
        screen: ScreenDescriptor,
        counts: GeometryCounts,
    ) {
        // The scratch buffers are taken out of `self` for the duration, so the
        // draw list can be filled while they are written, then put back: a
        // steady UI reuses one allocation per stream rather than taking fresh
        // ones every frame.
        let mut vertices = core::mem::take(&mut self.packed_vertices);
        let mut indices = core::mem::take(&mut self.packed_indices);
        pack_geometry(
            primitives,
            screen,
            &self.texture_options,
            counts,
            &mut vertices,
            &mut indices,
            &mut self.draws,
        );

        let device = &self.device;
        let vertex_buffer = self.vertices.as_ref().expect("just reserved");
        let index_buffer = self.indices.as_ref().expect("just reserved");
        self.vertex_staging
            .write(device, encoder, vertex_buffer, 0, &vertices);
        self.index_staging
            .write(device, encoder, index_buffer, 0, &indices);
        self.packed_vertices = vertices;
        self.packed_indices = indices;
    }

    /// The frame most recently uploaded, as a scene.
    ///
    /// Every draw sets a scissor rectangle, and a scissor stays set for the
    /// rest of the pass, so record this after the draws it overlays.
    ///
    /// The materials the frame needs were built by [`Self::update`], so this
    /// only reads the graph — a scene can therefore be taken while the graph is
    /// shared with whatever else the frame is drawing.
    ///
    /// `global` is the caller's global bind group for the camera, the frame
    /// globals and the view this frame draws through; the UI binds it at
    /// [`GLOBAL_GROUP`] for every draw.
    pub fn scene(&self, graph: &ResourceGraph, global: &wgpu::BindGroup) -> Scene {
        if self.vertices.is_none() || self.indices.is_none() || self.draws.is_empty() {
            return Scene::new();
        }
        let mut scene = Scene::new();

        let (vertices, indices) = (
            self.vertices.as_ref().expect("checked"),
            self.indices.as_ref().expect("checked"),
        );
        // The position stream is the first half of the buffer, the interleaved
        // UVs and colors the second, and the two meet at the *frame's* vertex
        // count — the point `upload_geometry` packed at. The buffer usually has
        // room to spare, so splitting at `vertex_capacity` instead would bind
        // the second stream to bytes no vertex was written to.
        let positions_size = (self.frame_vertices * POSITION_STRIDE) as u64;
        let secondary_size = (self.frame_vertices * SECONDARY_STRIDE) as u64;
        let pipeline = &self.pipeline.pipeline;
        for draw in &self.draws {
            // Each draw carries its own scissor rectangle, so consecutive
            // draws sharing one are what the recorder's deduplication is for.
            let Some(material) = self.material(graph, draw.texture, draw.options) else {
                // A primitive whose texture was freed this frame has nothing
                // to sample, so it is skipped rather than bound to a stale view.
                continue;
            };
            // Both slots cover their whole stream, and the primitive's indices
            // already name its vertices pool-globally, so the draw needs no
            // base vertex: one range addresses the position, the UV and the
            // color together.
            // The trailing tier of the composite: the UI sits above the
            // depth-sorted pool whatever its depth, and a clipped draw here
            // is followed by nothing its rectangle could leak into.
            let entry = DrawEntry::new(pipeline, DrawRange::indexed(draw.indices.clone()))
                .with_order(DrawOrder::After)
                .with_bind_group(GLOBAL_GROUP, global)
                .with_bind_group(MATERIAL_GROUP, material)
                .with_vertex_buffer(INSTANCE_SLOT, &self.instance)
                .with_vertex_buffer_range(PRIMARY_SLOT, vertices, 0..positions_size)
                .with_vertex_buffer_range(
                    SECONDARY_SLOT,
                    vertices,
                    positions_size..positions_size + secondary_size,
                )
                .with_index_buffer(indices, wgpu::IndexFormat::Uint32)
                .with_scissor(draw.scissor);
            scene.draws.push(entry);
        }
        scene
    }

    /// Reallocate the buffers when they cannot hold `counts`, registering any
    /// new buffer in `graph`.
    fn reserve(&mut self, graph: &mut ResourceGraph, counts: GeometryCounts) {
        let GeometryCounts { vertices, indices } = counts;
        // Grow geometrically so a UI that grows over a few frames does not
        // reallocate every frame.
        if self.vertices.is_none() || self.vertex_capacity < vertices {
            self.vertex_capacity = vertices
                .max(self.vertex_capacity + self.vertex_capacity / 2)
                .max(1);
            let buffer = self.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("ui::vertices"),
                size: (self.vertex_capacity * (POSITION_STRIDE + SECONDARY_STRIDE)) as u64,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            self.vertex_node = Some(match self.vertex_node.take() {
                // A grow replaces the buffer in its existing node, so no stale
                // node is left strongly holding the old buffer.
                Some(node) => {
                    graph
                        .replace(&node, buffer.clone())
                        .expect("the vertex node is still registered");
                    node
                }
                None => graph.insert(buffer.clone(), None),
            });
            self.vertices = Some(buffer);
        }
        if self.indices.is_none() || self.index_capacity < indices {
            self.index_capacity = indices
                .max(self.index_capacity + self.index_capacity / 2)
                .max(1);
            let buffer = self.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("ui::indices"),
                size: (self.index_capacity * size_of::<u32>()) as u64,
                usage: wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            self.index_node = Some(match self.index_node.take() {
                Some(node) => {
                    graph
                        .replace(&node, buffer.clone())
                        .expect("the index node is still registered");
                    node
                }
                None => graph.insert(buffer.clone(), None),
            });
            self.indices = Some(buffer);
        }
    }

    /// The material bind group for (`id`, `options`), if it exists.
    fn material<'a>(
        &self,
        graph: &'a ResourceGraph,
        texture: TextureKey,
        options: egui::TextureOptions,
    ) -> Option<&'a wgpu::BindGroup> {
        let key = MaterialKey { texture, options };
        let index = self.materials.iter().position(|(seen, _)| *seen == key)?;
        graph.get(&self.materials[index].1)
    }

    /// Build the material bind group for (`id`, `options`) if it does not
    /// exist, registered in the graph as a dependent of its texture's view
    /// and its sampler.
    ///
    /// The group is built once here and rebuilt by
    /// [`ResourceGraph::maintain`] whenever the view or the sampler is
    /// replaced: the recipe reads both back out of the graph by id, so a
    /// texture which patches itself into a new handle is picked up without
    /// the material being rebuilt by hand.
    fn build_material(
        &mut self,
        graph: &mut ResourceGraph,
        texture: TextureKey,
        options: egui::TextureOptions,
    ) {
        let key = MaterialKey { texture, options };
        if self.materials.iter().any(|(seen, _)| *seen == key) {
            return;
        }
        let Some(slot) = self.textures.get(&texture).cloned() else {
            return;
        };
        let sampler_id = self.sampler(graph, options);
        let layout = self
            .pipeline
            .descriptor()
            .bind_group_layouts(&self.device)
            .material
            .expect("the UI variant always samples a base-color texture");
        let device = self.device.clone();
        let view_id = slot.view.clone();
        let sampler_for_build = sampler_id.clone();
        let build = move |graph: &ResourceGraph| {
            let view = graph
                .get(&view_id)
                .expect("the texture view is in the graph")
                .view()
                .clone();
            let sampler = graph
                .get(&sampler_for_build)
                .expect("the sampler is in the graph")
                .clone();
            device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("ui::material"),
                layout: &layout,
                entries: &[
                    wgpu::BindGroupEntry {
                        binding: BASE_COLOR_TEXTURE_BINDING,
                        resource: wgpu::BindingResource::TextureView(&view),
                    },
                    wgpu::BindGroupEntry {
                        binding: BASE_COLOR_SAMPLER_BINDING,
                        resource: wgpu::BindingResource::Sampler(&sampler),
                    },
                ],
            })
        };
        let group = build(graph);
        let rebuild = Rebuild::new(move |graph| Resource::BindGroup(build(graph)));
        let id = graph.insert(group, Some(rebuild));
        graph.add_dependency(&id, &slot.view);
        graph.add_dependency(&id, &sampler_id);
        self.materials.push((key, id));
    }

    /// The sampler for `options`, created and registered on first use.
    fn sampler(
        &mut self,
        graph: &mut ResourceGraph,
        options: egui::TextureOptions,
    ) -> ResHandle<wgpu::Sampler> {
        if let Some((_, id)) = self.samplers.iter().find(|(seen, _)| *seen == options) {
            return id.clone();
        }
        let sampler = self.device.create_sampler(&wgpu::SamplerDescriptor {
            label: Some("ui::sampler"),
            address_mode_u: address_mode(options.wrap_mode),
            address_mode_v: address_mode(options.wrap_mode),
            mag_filter: texture_filter(options.magnification),
            min_filter: texture_filter(options.minification),
            ..Default::default()
        });
        let id = graph.insert(sampler, None);
        self.samplers.push((options, id.clone()));
        id
    }

    fn apply_textures(
        &mut self,
        graph: &mut ResourceGraph,
        queue: &wgpu::Queue,
        source: Source,
        delta: &egui::TexturesDelta,
    ) {
        for (&id, deltas) in &delta.set {
            let key = TextureKey { source, id };
            for image in deltas {
                // Every delta for a texture states its sampling options, and
                // the last one wins: they describe the texture as a whole, not
                // the patch being written.
                self.texture_options.insert(key, image.options);
                self.upload_texture(graph, queue, key, image);
            }
        }
        for &id in &delta.free {
            // Dropping the slot drops the ids to the texture and its view, so
            // the next [`ResourceGraph::maintain`] collects them — and the
            // materials that were built from the view, since the view's
            // reference count reaches zero with the slot's. The materials'
            // own entries go here, before that pass, so egui reusing the
            // (texture, options) pair rebuilds a material rather than finding
            // a stale one.
            //
            // The key carries the source: two contexts both free id zero at
            // some point, and the other context's texture is not this one's to
            // drop.
            let key = TextureKey { source, id };
            self.textures.remove(&key);
            self.texture_options.remove(&key);
            self.materials.retain(|(seen, _)| seen.texture != key);
        }
    }

    fn upload_texture(
        &mut self,
        graph: &mut ResourceGraph,
        queue: &wgpu::Queue,
        key: TextureKey,
        delta: &egui::epaint::ImageDelta,
    ) {
        let [width, height] = delta.image.size();
        // The image's own bytes, borrowed rather than copied into a fresh
        // `Vec`: a font atlas can be megabytes, and this is the whole of it.
        let pixels: &[u8] = match &delta.image {
            egui::ImageData::Color(image) => image.as_raw(),
        };
        let layout = wgpu::TexelCopyBufferLayout {
            offset: 0,
            bytes_per_row: Some(width as u32 * texture_bytes()),
            rows_per_image: Some(height as u32),
        };
        let size = wgpu::Extent3d {
            width: width as u32,
            height: height as u32,
            depth_or_array_layers: 1,
        };

        match delta.pos {
            // A patch written into the texture already there.
            Some([x, y]) => {
                let Some(slot) = self.textures.get(&key) else {
                    return;
                };
                let Some(texture) = graph.get(&slot.texture) else {
                    return;
                };
                queue.write_texture(
                    wgpu::TexelCopyTextureInfo {
                        texture,
                        mip_level: 0,
                        origin: wgpu::Origin3d {
                            x: x as u32,
                            y: y as u32,
                            z: 0,
                        },
                        aspect: wgpu::TextureAspect::All,
                    },
                    pixels,
                    layout,
                    size,
                );
            }
            None => {
                let texture = self.device.create_texture(&wgpu::TextureDescriptor {
                    label: Some("ui::texture"),
                    size,
                    mip_level_count: 1,
                    sample_count: 1,
                    dimension: wgpu::TextureDimension::D2,
                    format: TEXTURE_FORMAT,
                    usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
                    view_formats: &[],
                });
                queue.write_texture(texture.as_image_copy(), pixels, layout, size);
                let view =
                    TextureExt::create_view(&texture, &wgpu::TextureViewDescriptor::default());
                let texture_id = graph.insert(texture, None);
                let view_id = graph.insert(view, None);
                graph.add_dependency(&view_id, &texture_id);
                self.textures.insert(
                    key,
                    TextureSlot {
                        texture: texture_id,
                        view: view_id,
                    },
                );
            }
        }
    }
}

/// Bytes per texel of [`TEXTURE_FORMAT`], derived from the format.
fn texture_bytes() -> u32 {
    TEXTURE_FORMAT
        .block_copy_size(None)
        .expect("rgba8 has a known texel size")
}

fn address_mode(mode: egui::TextureWrapMode) -> wgpu::AddressMode {
    match mode {
        egui::TextureWrapMode::ClampToEdge => wgpu::AddressMode::ClampToEdge,
        egui::TextureWrapMode::Repeat => wgpu::AddressMode::Repeat,
        egui::TextureWrapMode::MirroredRepeat => wgpu::AddressMode::MirrorRepeat,
    }
}

fn texture_filter(filter: egui::TextureFilter) -> wgpu::FilterMode {
    match filter {
        egui::TextureFilter::Nearest => wgpu::FilterMode::Nearest,
        egui::TextureFilter::Linear => wgpu::FilterMode::Linear,
    }
}

/// The mesh of `primitive`, or `None` for a paint callback.
fn mesh_of(primitive: &egui::ClippedPrimitive) -> Option<&egui::epaint::Mesh> {
    match &primitive.primitive {
        egui::epaint::Primitive::Mesh(mesh) => Some(mesh),
        egui::epaint::Primitive::Callback(_) => None,
    }
}

/// egui's clip rectangle as a scissor rectangle, in whole pixels.
///
/// egui states a clip rectangle in logical points, while a scissor rectangle is
/// in physical pixels, so the rectangle is scaled by the density and rounded to
/// whole pixels — the same conversion `egui-wgpu` performs. Both edges are then
/// clamped to the target: a clip rectangle may extend past it (a panel scrolled
/// out of view, or a widget larger than the surface), and a scissor rectangle
/// outside the attachment is a validation error rather than a no-op.
fn scissor_rect(clip_rect: egui::Rect, screen: ScreenDescriptor) -> ScissorRect {
    let ppp = screen.pixels_per_point;
    let [width, height] = screen.size_in_pixels;

    let min_x = (ppp * clip_rect.min.x).round().clamp(0.0, width as f32) as u32;
    let min_y = (ppp * clip_rect.min.y).round().clamp(0.0, height as f32) as u32;
    let max_x = (ppp * clip_rect.max.x)
        .round()
        .clamp(min_x as f32, width as f32) as u32;
    let max_y = (ppp * clip_rect.max.y)
        .round()
        .clamp(min_y as f32, height as f32) as u32;

    ScissorRect {
        x: min_x,
        y: min_y,
        width: max_x - min_x,
        height: max_y - min_y,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The UI options for a device-free test. Only the policy these tests
    /// assert on matters, so the depth-stencil format is the
    /// device-independent placeholder.
    fn ui_options_for_tests(srgb_to_linear_output: bool) -> LitOptions {
        let mut options = LitOptions::standard();
        apply_ui_settings(&mut options, srgb_to_linear_output);
        options
    }

    /// A UI variant over the device-free options, for tests that assert on
    /// what a variant derives rather than on a compiled pipeline.
    fn ui_variant_for_tests(srgb_to_linear_output: bool) -> LitVariant {
        LitVariant {
            options: Hashed::new(ui_options_for_tests(srgb_to_linear_output)),
            surface: SurfaceKey {
                color_format: wgpu::TextureFormat::Rgba8UnormSrgb,
                depth_stencil_format: None,
                sample_count: 1,
            },
            channels: ui_channels(),
            base_color_texture: true,
            morph: false,
            strip_index_format: None,
        }
    }

    #[test]
    fn ui_variant_is_screen_space_and_uncompressed() {
        let variant = ui_variant_for_tests(false);
        let channels = variant.channels;
        assert_eq!(
            channels.position.position,
            Some(ChannelEncoding::PlanarPosition),
            "screen-space vertices are written at full precision and in the plane"
        );
        assert!(!channels.position.joints, "a UI mesh is never skinned");
        assert_eq!(
            channels.secondary,
            SecondaryFlags::UV | SecondaryFlags::UNCOMPRESSED_UV | SecondaryFlags::COLOR
        );
        assert!(variant.base_color_texture);
        // Nothing is compressed, so no draw decodes through a metadata index:
        // the instance stream carries no per-mesh state the UI would read.
        assert!(!variant.needs_metadata());
        assert!(!variant.needs_joints());
        assert!(!variant.needs_morphs());
        // The instance stream is declared for every unlit variant, so a UI
        // draw binds the default record.
        assert!(variant.vertex_buffer_layouts()[INSTANCE_SLOT as usize].is_some());
        let options = &variant.options;
        // Overlaid rather than depth-tested: the policy says what a target
        // with an attachment would run, and the surface says whether it has
        // one.
        assert!(!options.depth_stencil.depth_write_enabled);
        assert_eq!(
            options.depth_stencil.depth_compare,
            wgpu::CompareFunction::Always
        );
        // egui's colors premultiply their own alpha.
        let blend = options.blend.expect("the UI variant blends");
        assert_eq!(blend.color.src_factor, wgpu::BlendFactor::One);
        assert_eq!(blend.color.dst_factor, wgpu::BlendFactor::OneMinusSrcAlpha);
    }

    /// The conversion flag follows the parameter, since it depends on the
    /// target's format, not the UI.
    #[test]
    fn srgb_flag_follows_the_parameter() {
        assert!(!ui_options_for_tests(false).srgb_to_linear_output);
        assert!(ui_options_for_tests(true).srgb_to_linear_output);
    }

    /// The projection maps the viewport's corners onto clip space, with Y
    /// flipped: egui's origin is the top left, clip space's the bottom left.
    #[test]
    fn screen_view_maps_the_viewport_corners() {
        let camera = screen_view([256.0, 192.0]);
        for (point, expected) in [([0.0, 0.0], [-1.0, 1.0]), ([256.0, 192.0], [1.0, -1.0])] {
            let clip = camera.clip_from_world * glam::Vec4::new(point[0], point[1], 0.0, 1.0);
            let got = [clip.x / clip.w, clip.y / clip.w];
            assert!(
                (got[0] - expected[0]).abs() < 1e-5 && (got[1] - expected[1]).abs() < 1e-5,
                "point {point:?} projected to {got:?}, expected {expected:?}"
            );
        }
        // The viewport the same points describe is the view bound beside it.
        assert_eq!(screen_viewport([256.0, 192.0]), View::new(256.0, 192.0));
    }

    /// A clip rectangle reaching off the target is clamped rather than wrapping
    /// into a huge `u32`, and its far edge never falls below its near edge.
    #[test]
    fn scissor_rect_clamps_to_the_target() {
        let screen = ScreenDescriptor {
            size_in_pixels: [64, 48],
            pixels_per_point: 1.0,
        };
        let rect = scissor_rect(
            egui::Rect::from_two_pos(egui::Pos2::new(-20.0, -8.0), egui::Pos2::new(200.0, 200.0)),
            screen,
        );
        assert_eq!(rect.x, 0);
        assert_eq!(rect.y, 0);
        // Both edges are clamped to the target, so a clip rectangle larger
        // than it covers exactly the target rather than overrunning it.
        assert_eq!(rect.width, 64);
        assert_eq!(rect.height, 48);

        // A rectangle entirely off the target collapses to nothing instead of
        // producing a negative width.
        let off = scissor_rect(
            egui::Rect::from_two_pos(egui::Pos2::new(-40.0, -40.0), egui::Pos2::new(-10.0, -10.0)),
            screen,
        );
        assert_eq!((off.x, off.y, off.width, off.height), (0, 0, 0, 0));
    }

    /// A clip rectangle is stated in logical points, so at a density above one
    /// it must cover that many physical pixels — the conversion egui-wgpu
    /// performs. Getting it wrong clips the UI short of its own bounds.
    #[test]
    fn scissor_rect_scales_points_to_physical_pixels() {
        let screen = ScreenDescriptor {
            size_in_pixels: [256, 192],
            pixels_per_point: 2.0,
        };
        // A 16x8-point clip at (8, 4) is 32x16 physical pixels at (16, 8).
        let clip = egui::Rect::from_min_size(egui::Pos2::new(8.0, 4.0), egui::Vec2::new(16.0, 8.0));
        let rect = scissor_rect(clip, screen);
        assert_eq!(
            rect,
            ScissorRect {
                x: 16,
                y: 8,
                width: 32,
                height: 16
            }
        );

        // Where an unscaled conversion would have ended, in pixels: egui's own
        // point coordinates taken as pixels. The scaled rectangle extends
        // beyond it, so an unscaled clip would have cut that strip away.
        let unscaled_end = clip.max.x as u32;
        assert!(
            unscaled_end < rect.x + rect.width,
            "the scaled rectangle must reach past where an unscaled one would \
             have ended ({unscaled_end} px), but it ends at {} px",
            rect.x + rect.width
        );
    }

    /// Fractional points round to whole pixels rather than truncating, so a
    /// clip edge does not drift by up to a pixel.
    #[test]
    fn scissor_rect_rounds_fractional_points() {
        let screen = ScreenDescriptor {
            size_in_pixels: [64, 64],
            pixels_per_point: 1.0,
        };
        let rect = scissor_rect(
            egui::Rect::from_min_size(egui::Pos2::new(1.4, 2.6), egui::Vec2::new(4.0, 4.0)),
            screen,
        );
        assert_eq!((rect.x, rect.y), (1, 3));

        let rounded_up = scissor_rect(
            egui::Rect::from_min_size(egui::Pos2::new(1.6, 2.4), egui::Vec2::new(4.0, 4.0)),
            screen,
        );
        assert_eq!((rounded_up.x, rounded_up.y), (2, 2));
    }

    /// The point size the projection takes is the physical size divided by the
    /// density — the opposite conversion from the scissor rectangle's.
    #[test]
    fn size_in_points_divides_by_the_density() {
        let screen = ScreenDescriptor {
            size_in_pixels: [256, 192],
            pixels_per_point: 2.0,
        };
        assert_eq!(screen.size_in_points(), [128.0, 96.0]);
    }

    /// A screen descriptor matching the default test target.
    fn test_screen() -> ScreenDescriptor {
        ScreenDescriptor {
            size_in_pixels: [256, 192],
            pixels_per_point: 1.0,
        }
    }

    /// Tag `primitives` with the local source: these tests exercise packing,
    /// not the namespaces a frame arrives from.
    fn local(primitives: &[egui::ClippedPrimitive]) -> Vec<(Source, &egui::ClippedPrimitive)> {
        primitives
            .iter()
            .map(|primitive| (Source::LOCAL, primitive))
            .collect()
    }

    /// One tessellated primitive carrying `vertices` points, clipped to the
    /// whole screen.
    fn primitive(texture: egui::TextureId, vertices: usize) -> egui::ClippedPrimitive {
        let mut mesh = egui::epaint::Mesh::with_texture(texture);
        for index in 0..vertices {
            mesh.vertices.push(egui::epaint::Vertex {
                pos: egui::pos2(index as f32, index as f32 * 2.0),
                uv: egui::pos2(0.25, 0.75),
                color: egui::Color32::from_rgba_premultiplied(1, 2, 3, 4),
            });
        }
        // A degenerate triangle per vertex, enough to exercise the index path.
        for index in 0..vertices.saturating_sub(2) {
            mesh.indices
                .extend([index as u32, index as u32 + 1, index as u32 + 2]);
        }
        egui::ClippedPrimitive {
            clip_rect: egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(256.0, 192.0)),
            primitive: egui::epaint::Primitive::Mesh(mesh),
        }
    }

    /// The packing lands each primitive's bytes where its draw says, and the
    /// two vertex streams hold the values egui put in.
    #[test]
    fn packing_places_each_primitive_where_its_draw_says() {
        let primitives = [primitive(egui::TextureId::default(), 4)];
        let mut vertices = Vec::new();
        let mut indices = Vec::new();
        let mut draws = Vec::new();
        let tagged = local(&primitives);
        let counts = measure(tagged.iter().copied());
        pack_geometry(
            tagged.iter().copied(),
            test_screen(),
            &HashMap::new(),
            counts,
            &mut vertices,
            &mut indices,
            &mut draws,
        );

        assert_eq!(draws.len(), 1, "one mesh is one draw");
        let draw = &draws[0];
        assert_eq!(draw.indices, 0..6, "four vertices make two triangles");
        // This primitive starts at the pool's first vertex, so baking its
        // offset in leaves the indices as egui wrote them.
        assert_eq!(
            packed_indices(&indices),
            vec![0, 1, 2, 1, 2, 3],
            "the indices address the pool without an offset"
        );

        // The vertex buffer holds the primary stream then the interleaved
        // secondary stream, each entry one stride wide.
        let secondary_start = 4 * POSITION_STRIDE;
        assert_eq!(vertices.len(), secondary_start + 4 * SECONDARY_STRIDE);
        let positions: Vec<f32> = vertices[..secondary_start]
            .as_chunks::<{ size_of::<f32>() }>()
            .0
            .iter()
            .map(|word| f32::from_le_bytes(*word))
            .collect();
        assert_eq!(
            positions,
            vec![0.0, 0.0, 1.0, 2.0, 2.0, 4.0, 3.0, 6.0],
            "each position is x and y; the shader supplies the zero z"
        );

        // The colors are egui's premultiplied bytes, unchanged.
        let first_color = secondary_start + size_of::<egui::Vec2>();
        assert_eq!(
            &vertices[first_color..first_color + size_of::<egui::Color32>()],
            &[1, 2, 3, 4]
        );

        // The indices are this primitive's, starting at zero for the first.
        let indices: Vec<u32> = indices
            .as_chunks::<{ size_of::<u32>() }>()
            .0
            .iter()
            .map(|word| u32::from_le_bytes(*word))
            .collect();
        assert_eq!(indices, vec![0, 1, 2, 1, 2, 3]);
    }

    /// A second primitive's indices are offset by the first's vertex count, so
    /// one base vertex addresses both streams.
    #[test]
    fn a_later_primitive_is_offset_by_the_earlier_one() {
        let primitives = [
            primitive(egui::TextureId::default(), 3),
            primitive(egui::TextureId::default(), 3),
        ];
        let mut vertices = Vec::new();
        let mut indices = Vec::new();
        let mut draws = Vec::new();
        let tagged = local(&primitives);
        let counts = measure(tagged.iter().copied());
        pack_geometry(
            tagged.iter().copied(),
            test_screen(),
            &HashMap::new(),
            counts,
            &mut vertices,
            &mut indices,
            &mut draws,
        );

        assert_eq!(draws.len(), 2);
        assert_eq!(draws[0].indices, 0..3);
        assert_eq!(draws[1].indices, 3..6);
        // The second primitive's vertices start at ordinal 3, so its local
        // indices are shifted by 3 — the offset a device without `base_vertex`
        // could not take from the draw.
        assert_eq!(
            packed_indices(&indices),
            vec![0, 1, 2, 3, 4, 5],
            "the second primitive's indices are offset to the pool"
        );
    }

    /// The indices `pack_geometry` wrote, as `u32`s.
    fn packed_indices(bytes: &[u8]) -> Vec<u32> {
        bytes
            .as_chunks::<{ size_of::<u32>() }>()
            .0
            .iter()
            .map(|word| u32::from_le_bytes(*word))
            .collect()
    }

    /// The byte buffers are cleared and refilled, not reallocated, so a caller
    /// that keeps them uploads without allocating.
    #[test]
    fn packing_reuses_the_vertex_and_index_buffers() {
        let big = [primitive(egui::TextureId::default(), 8)];
        let small = [primitive(egui::TextureId::default(), 3)];

        let mut vertices = Vec::new();
        let mut indices = Vec::new();
        let mut draws = Vec::new();
        let big_tagged = local(&big);
        let big_counts = measure(big_tagged.iter().copied());
        pack_geometry(
            big_tagged.iter().copied(),
            test_screen(),
            &HashMap::new(),
            big_counts,
            &mut vertices,
            &mut indices,
            &mut draws,
        );
        let vertex_capacity = vertices.capacity();
        let index_capacity = indices.capacity();

        // A later, smaller frame keeps both allocations rather than taking new
        // ones; a fresh `Vec` per frame would have exactly its own length.
        let small_tagged = local(&small);
        let small_counts = measure(small_tagged.iter().copied());
        pack_geometry(
            small_tagged.iter().copied(),
            test_screen(),
            &HashMap::new(),
            small_counts,
            &mut vertices,
            &mut indices,
            &mut draws,
        );
        assert_eq!(
            vertices.capacity(),
            vertex_capacity,
            "the vertex scratch buffer is reused"
        );
        assert_eq!(
            indices.capacity(),
            index_capacity,
            "the index scratch buffer is reused"
        );
        assert_eq!(draws.len(), 1, "and the stale second draw is gone");
    }
}