Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

50.7 KB
Raw Blame
use super::glyphcache::GlyphCache;
use super::quad::*;
use super::utilsprites::{RenderMetrics, UtilSprites};
use crate::termwindow::webgpu::{adapter_info_to_gpu_info, WebGpuState, WebGpuTexture};
use ::window::bitmaps::atlas::OutOfTextureSpace;
use ::window::bitmaps::Texture2d;
use ::window::glium::backend::Context as GliumContext;
use ::window::glium::buffer::{BufferMutSlice, Mapping};
use ::window::glium::texture::SrgbTexture2d;
use ::window::glium::{
    CapabilitiesSource, IndexBuffer as GliumIndexBuffer, VertexBuffer as GliumVertexBuffer,
};
use ::window::*;
use anyhow::Context;
use std::cell::{Cell, Ref, RefCell, RefMut};
use std::collections::HashMap;
use std::convert::TryInto;
use std::rc::Rc;
use wezterm_font::FontConfiguration;
use wgpu::util::DeviceExt;

const INDICES_PER_CELL: usize = 6;

fn gpu_debug_enabled() -> bool {
    std::env::var_os("THINKTERM_GPU_DEBUG").is_some()
}

fn gpu_debug(message: impl AsRef<str>) {
    if gpu_debug_enabled() {
        log::info!("[gpu-resource] {}", message.as_ref());
    }
}

pub(crate) struct LoggedSrgbTexture2d {
    inner: SrgbTexture2d,
    label: &'static str,
}

impl LoggedSrgbTexture2d {
    pub(crate) fn new(inner: SrgbTexture2d, label: &'static str) -> Self {
        Self { inner, label }
    }

    pub(crate) fn inner(&self) -> &SrgbTexture2d {
        &self.inner
    }
}

impl Texture2d for LoggedSrgbTexture2d {
    fn write(&self, rect: Rect, im: &dyn BitmapImage) {
        let (im_width, im_height) = im.image_dimensions();

        let source = glium::texture::RawImage2d {
            data: std::borrow::Cow::Borrowed(im.pixels()),
            width: im_width as u32,
            height: im_height as u32,
            format: glium::texture::ClientFormat::U8U8U8U8,
        };

        self.inner.write(
            glium::Rect {
                left: rect.min_x() as u32,
                bottom: rect.min_y() as u32,
                width: rect.size.width as u32,
                height: rect.size.height as u32,
            },
            source,
        )
    }

    fn read(&self, _rect: Rect, _im: &mut dyn BitmapImage) {
        unimplemented!();
    }

    fn width(&self) -> usize {
        self.inner.width() as usize
    }

    fn height(&self) -> usize {
        self.inner.height() as usize
    }
}

impl Drop for LoggedSrgbTexture2d {
    fn drop(&mut self) {
        gpu_debug(format!(
            "drop OpenGL texture label={} size={}x{} bytes={}",
            self.label,
            self.width(),
            self.height(),
            self.width() * self.height() * 4
        ));
    }
}

#[derive(Clone)]
pub enum RenderContext {
    Glium(Rc<GliumContext>),
    WebGpu(Rc<WebGpuState>),
}

pub enum RenderFrame<'a> {
    /// Created by the draw: a paint that gives up never makes one, so
    /// nothing is swapped and the previous frame stays on screen.
    Glium(&'a mut Option<glium::Frame>),
    WebGpu,
}

impl RenderContext {
    pub fn allocate_index_buffer(&self, indices: &[u32]) -> anyhow::Result<IndexBuffer> {
        match self {
            Self::Glium(context) => Ok(IndexBuffer::Glium(GliumIndexBuffer::new(
                context,
                glium::index::PrimitiveType::TrianglesList,
                indices,
            )?)),
            Self::WebGpu(state) => Ok(IndexBuffer::WebGpu(WebGpuIndexBuffer::new(indices, state))),
        }
    }

    pub fn allocate_vertex_buffer_initializer(&self, num_quads: usize) -> Vec<Vertex> {
        match self {
            Self::Glium(_) => {
                vec![Vertex::default(); num_quads * VERTICES_PER_CELL]
            }
            Self::WebGpu(_) => vec![],
        }
    }

    pub fn allocate_vertex_buffer(
        &self,
        num_quads: usize,
        initializer: &[Vertex],
    ) -> anyhow::Result<VertexBuffer> {
        let bytes = num_quads * VERTICES_PER_CELL * std::mem::size_of::<Vertex>();
        match self {
            Self::Glium(context) => {
                gpu_debug(format!(
                    "create OpenGL vertex_buffer quads={num_quads} bytes={bytes}"
                ));
                Ok(VertexBuffer::Glium(GliumVertexBuffer::dynamic(
                    context,
                    initializer,
                )?))
            }
            Self::WebGpu(state) => {
                gpu_debug(format!(
                    "create WebGpu vertex_buffer quads={num_quads} bytes={bytes}"
                ));
                Ok(VertexBuffer::WebGpu(WebGpuVertexBuffer::new(
                    num_quads * VERTICES_PER_CELL,
                    state,
                )))
            }
        }
    }

    pub fn allocate_texture_atlas(&self, size: usize) -> anyhow::Result<Rc<dyn Texture2d>> {
        let bytes = size * size * 4;
        match self {
            Self::Glium(context) => {
                gpu_debug(format!(
                    "create OpenGL texture_atlas size={size}x{size} bytes={bytes}"
                ));
                let caps = context.get_capabilities();
                // You'd hope that allocating a texture would automatically
                // include this check, but it doesn't, and instead, the texture
                // silently fails to bind when attempting to render into it later.
                // So! We check and raise here for ourselves!
                let max_texture_size: usize = caps
                    .max_texture_size
                    .try_into()
                    .context("represent Capabilities.max_texture_size as usize")?;
                if size > max_texture_size {
                    anyhow::bail!(
                        "Cannot use a texture of size {} as it is larger \
                         than the max {} supported by your GPU",
                        size,
                        caps.max_texture_size
                    );
                }
                let surface = SrgbTexture2d::empty_with_format(
                    context,
                    glium::texture::SrgbFormat::U8U8U8U8,
                    glium::texture::MipmapsOption::NoMipmap,
                    size as u32,
                    size as u32,
                )?;
                let surface: Rc<dyn Texture2d> =
                    Rc::new(LoggedSrgbTexture2d::new(surface, "Texture Atlas"));
                Ok(surface)
            }
            Self::WebGpu(state) => {
                gpu_debug(format!(
                    "create WebGpu texture_atlas size={size}x{size} bytes={bytes}"
                ));
                let texture: Rc<dyn Texture2d> =
                    Rc::new(WebGpuTexture::new(size as u32, size as u32, state)?);
                Ok(texture)
            }
        }
    }

    pub fn renderer_info(&self) -> String {
        match self {
            Self::Glium(ctx) => format!(
                "OpenGL: {} {}",
                ctx.get_opengl_renderer_string(),
                ctx.get_opengl_version_string()
            ),
            Self::WebGpu(state) => {
                let info = adapter_info_to_gpu_info(state.adapter_info.clone());
                format!("WebGPU: {}", info.to_string())
            }
        }
    }
}

pub enum IndexBuffer {
    Glium(GliumIndexBuffer<u32>),
    WebGpu(WebGpuIndexBuffer),
}

impl IndexBuffer {
    pub fn glium(&self) -> &GliumIndexBuffer<u32> {
        match self {
            Self::Glium(g) => g,
            _ => unreachable!(),
        }
    }
    pub fn webgpu(&self) -> &WebGpuIndexBuffer {
        match self {
            Self::WebGpu(g) => g,
            _ => unreachable!(),
        }
    }
}

pub enum VertexBuffer {
    Glium(GliumVertexBuffer<Vertex>),
    WebGpu(WebGpuVertexBuffer),
}

impl Drop for VertexBuffer {
    fn drop(&mut self) {
        if !gpu_debug_enabled() {
            return;
        }
        match self {
            Self::Glium(_) => gpu_debug("drop OpenGL vertex_buffer"),
            Self::WebGpu(vb) => gpu_debug(format!(
                "drop WebGpu vertex_buffer vertices={} bytes={}",
                vb.num_vertices,
                vb.num_vertices * std::mem::size_of::<Vertex>()
            )),
        }
    }
}

impl VertexBuffer {
    pub fn glium(&self) -> &GliumVertexBuffer<Vertex> {
        match self {
            Self::Glium(g) => g,
            _ => unreachable!(),
        }
    }
    pub fn webgpu(&self) -> &WebGpuVertexBuffer {
        match self {
            Self::WebGpu(g) => g,
            _ => unreachable!(),
        }
    }
    pub fn webgpu_mut(&mut self) -> &mut WebGpuVertexBuffer {
        match self {
            Self::WebGpu(g) => g,
            _ => unreachable!(),
        }
    }
}

enum MappedVertexBuffer {
    Glium(GliumMappedVertexBuffer),
    WebGpu(WebGpuMappedVertexBuffer),
}

impl MappedVertexBuffer {
    fn slice_mut(&mut self, range: std::ops::Range<usize>) -> &mut [Vertex] {
        match self {
            Self::Glium(g) => &mut g.mapping[range],
            Self::WebGpu(g) => &mut g.mapping[range],
        }
    }
}

pub struct MappedQuads<'a> {
    mapping: MappedVertexBuffer,
    next: RefMut<'a, usize>,
    capacity: usize,
}

pub struct WebGpuMappedVertexBuffer {
    mapping: RefMut<'static, Vec<Vertex>>,
}

pub struct WebGpuVertexBuffer {
    buf: wgpu::Buffer,
    /// CPU-side quad staging. Quads are written here during layout and the
    /// used range is uploaded with `queue.write_buffer` at draw time. The
    /// GPU buffer is persistent: the old scheme allocated a fresh
    /// `mapped_at_creation` buffer every frame, and wgpu zero-fills those --
    /// megabytes of allocation and memset per layer per frame.
    staging: Vec<Vertex>,
    num_vertices: usize,
    state: Rc<WebGpuState>,
}

impl std::ops::Deref for WebGpuVertexBuffer {
    type Target = wgpu::Buffer;
    fn deref(&self) -> &Self::Target {
        &self.buf
    }
}

impl WebGpuVertexBuffer {
    pub fn new(num_vertices: usize, state: &Rc<WebGpuState>) -> Self {
        Self {
            buf: state.device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("Vertex Buffer"),
                size: (num_vertices * std::mem::size_of::<Vertex>()) as wgpu::BufferAddress,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            }),
            staging: vec![Vertex::default(); num_vertices],
            num_vertices,
            state: Rc::clone(state),
        }
    }

    /// Size of the persistent buffer, which is the capacity high-water
    /// mark rather than what the frame actually uses.
    pub fn capacity_bytes(&self) -> usize {
        self.num_vertices * std::mem::size_of::<Vertex>()
    }

    /// Upload the used prefix of the staging quads into the persistent
    /// GPU buffer.
    pub fn upload(&self, vertex_count: usize) {
        let count = vertex_count.min(self.staging.len());
        if count > 0 {
            self.state
                .queue
                .write_buffer(&self.buf, 0, bytemuck::cast_slice(&self.staging[..count]));
        }
    }
}

pub struct WebGpuIndexBuffer {
    buf: wgpu::Buffer,
}

impl std::ops::Deref for WebGpuIndexBuffer {
    type Target = wgpu::Buffer;
    fn deref(&self) -> &Self::Target {
        &self.buf
    }
}

impl WebGpuIndexBuffer {
    pub fn new(indices: &[u32], state: &WebGpuState) -> Self {
        Self {
            buf: state
                .device
                .create_buffer_init(&wgpu::util::BufferInitDescriptor {
                    label: Some("Index Buffer"),
                    usage: wgpu::BufferUsages::INDEX,
                    contents: bytemuck::cast_slice(indices),
                }),
        }
    }
}

/// This is a self-referential struct, but since those are not possible
/// to create safely in unstable rust, we transmute the lifetimes away
/// to static and store the owner (RefMut) and the derived Mapping object
/// in this struct
pub struct GliumMappedVertexBuffer {
    mapping: Mapping<'static, [Vertex]>,
    // Drop the owner after the mapping
    _owner: RefMut<'static, VertexBuffer>,
}

impl<'a> QuadAllocator for MappedQuads<'a> {
    fn allocate<'b>(&'b mut self) -> anyhow::Result<QuadImpl<'b>> {
        let idx = *self.next;
        *self.next += 1;
        let idx = if idx >= self.capacity {
            // We don't have enough quads, so we'll keep re-using
            // the first quad until we reach the end of the render
            // pass, at which point we'll detect this condition
            // and re-allocate the quads.
            0
        } else {
            idx
        };

        let idx = idx * VERTICES_PER_CELL;
        let mut quad = Quad {
            vert: self.mapping.slice_mut(idx..idx + VERTICES_PER_CELL),
        };

        quad.set_has_color(false);

        Ok(QuadImpl::Vert(quad))
    }

    fn extend_with(&mut self, vertices: &[Vertex]) {
        let idx = *self.next;
        let len = vertices.len();

        // idx and next are number of quads, so divide by number of vertices
        *self.next += len / VERTICES_PER_CELL;
        // Only copy in if there is enough room.
        // We'll detect the out of space condition at the end of
        // the render pass.
        let idx = idx * VERTICES_PER_CELL;
        let capacity = self.capacity * VERTICES_PER_CELL;
        if idx + len <= capacity {
            self.mapping
                .slice_mut(idx..idx + len)
                .copy_from_slice(vertices);
        }
    }
}

/// The quad count no shrink goes below; shared by the idle observation
/// shrink (shrink_target) and the occlusion shrink (shrink_quads_now) so
/// both express the same floor policy.
const MIN_QUADS: usize = 32;

pub struct TripleVertexBuffer {
    pub index: RefCell<usize>,
    /// One buffer for WebGPU, three rotating buffers for Glium. Glium maps
    /// buffer memory directly, so it rotates to avoid writing into a buffer
    /// the GPU is still reading; WebGPU uploads go through
    /// `queue.write_buffer`, which is ordered on the queue timeline, so a
    /// single buffer is safe and costs a third of the memory.
    pub bufs: RefCell<Vec<VertexBuffer>>,
    pub indices: IndexBuffer,
    pub capacity: usize,
    pub next_quad: RefCell<usize>,
    /// Peak quad usage seen in the current shrink observation window.
    high_water: Cell<usize>,
    /// Frames observed so far in the current shrink window.
    frames_observed: Cell<u32>,
}

/// A trait to avoid broadly-scoped transmutes; we only want to
/// transmute to extend a lifetime to static, and not to change
/// the underlying type.
/// These ExtendStatic trait impls constrain the transmutes in that way,
/// so that the type checker can still catch issues.
unsafe trait ExtendStatic {
    type T;
    unsafe fn extend_lifetime(self) -> Self::T;
}

unsafe impl<'a, T: 'static> ExtendStatic for Ref<'a, T> {
    type T = Ref<'static, T>;
    unsafe fn extend_lifetime(self) -> Self::T {
        std::mem::transmute(self)
    }
}

unsafe impl<'a, T: 'static> ExtendStatic for RefMut<'a, T> {
    type T = RefMut<'static, T>;
    unsafe fn extend_lifetime(self) -> Self::T {
        std::mem::transmute(self)
    }
}

unsafe impl<'a> ExtendStatic for wgpu::BufferSlice<'a> {
    type T = wgpu::BufferSlice<'static>;
    unsafe fn extend_lifetime(self) -> Self::T {
        std::mem::transmute(self)
    }
}

unsafe impl<'a> ExtendStatic for MappedQuads<'a> {
    type T = MappedQuads<'static>;
    unsafe fn extend_lifetime(self) -> Self::T {
        std::mem::transmute(self)
    }
}

unsafe impl<'a, T: ?Sized + ::window::glium::buffer::Content + 'static> ExtendStatic
    for BufferMutSlice<'a, T>
{
    type T = BufferMutSlice<'static, T>;
    unsafe fn extend_lifetime(self) -> Self::T {
        std::mem::transmute(self)
    }
}

impl TripleVertexBuffer {
    pub fn clear_quad_allocation(&self) {
        *self.next_quad.borrow_mut() = 0;
    }

    pub fn need_more_quads(&self) -> Option<usize> {
        let next = *self.next_quad.borrow();
        if next > self.capacity {
            Some(next)
        } else {
            None
        }
    }

    pub fn vertex_index_count(&self) -> (usize, usize) {
        let next = *self.next_quad.borrow();
        // A pass that gave up before allocated_more_quads could grow the
        // buffers leaves the count past their end. Such frames are not
        // drawn; should one get here anyway, draw only what the buffers
        // hold, and count it.
        if next > self.capacity {
            crate::perf::log_counter("draw_quads_clamped", next - self.capacity);
        }
        let num_quads = next.min(self.capacity);
        (num_quads * VERTICES_PER_CELL, num_quads * INDICES_PER_CELL)
    }

    pub fn map(&self) -> MappedQuads<'_> {
        let mut bufs = self.current_vb_mut();

        // To map the vertex buffer, we need to hold a mutable reference to
        // the buffer and hold the mapping object alive for the duration
        // of the access.  Rust doesn't allow us to create a struct that
        // holds both of those things, because one references the other
        // and it doesn't permit self-referential structs.
        // We use the very blunt instrument "transmute" to force Rust to
        // treat the lifetimes of both of these things as static, which
        // we can then store in the same struct.
        // This is "safe" because we carry them around together and ensure
        // that the owner is dropped after the derived data.
        let mapping = if matches!(&*bufs, VertexBuffer::Glium(_)) {
            let buf_slice = {
                let vb = match &mut *bufs {
                    VertexBuffer::Glium(vb) => vb,
                    _ => unreachable!(),
                };
                unsafe {
                    vb.slice_mut(..)
                        .expect("to map vertex buffer")
                        .extend_lifetime()
                }
            };
            let mapping = buf_slice.map();

            MappedVertexBuffer::Glium(GliumMappedVertexBuffer {
                _owner: bufs,
                mapping,
            })
        } else {
            // The WebGpu "mapping" is the CPU staging Vec; the RefMut keeps
            // the owning VertexBuffer borrowed for the mapping's lifetime.
            let staging = RefMut::map(bufs, |vb| match vb {
                VertexBuffer::WebGpu(vb) => &mut vb.staging,
                _ => unreachable!(),
            });
            MappedVertexBuffer::WebGpu(WebGpuMappedVertexBuffer { mapping: staging })
        };

        MappedQuads {
            mapping,
            next: self.next_quad.borrow_mut(),
            capacity: self.capacity,
        }
    }

    pub fn current_vb_mut(&self) -> RefMut<'static, VertexBuffer> {
        let index = *self.index.borrow();
        let bufs = self.bufs.borrow_mut();
        unsafe {
            RefMut::map(bufs, |bufs| {
                let len = bufs.len();
                &mut bufs[index % len]
            })
            .extend_lifetime()
        }
    }

    pub fn next_index(&self) {
        let mut index = self.index.borrow_mut();
        *index += 1;
        if *index >= 3 {
            *index = 0;
        }
    }

    /// Record this frame's quad usage; once usage has stayed well below
    /// capacity for a whole observation window, return the capacity to
    /// shrink to. Vertex buffers only ever grew before this, so a single
    /// spike (opening the overview on a wall of busy panes) pinned tens of
    /// megabytes of staging + GPU memory forever.
    fn shrink_target(&self) -> Option<usize> {
        const OBSERVE_FRAMES: u32 = 120;
        let used = *self.next_quad.borrow();
        self.high_water.set(self.high_water.get().max(used));
        let frames = self.frames_observed.get() + 1;
        self.frames_observed.set(frames);
        if frames < OBSERVE_FRAMES {
            return None;
        }
        let high_water = self.high_water.get();
        self.frames_observed.set(0);
        self.high_water.set(0);
        let target = (high_water.max(MIN_QUADS) * 5 / 4).next_power_of_two();
        (self.capacity > target * 2).then_some(target)
    }
}

pub struct RenderLayer {
    pub vb: RefCell<[TripleVertexBuffer; 3]>,
    context: RenderContext,
    zindex: i8,
}

impl RenderLayer {
    pub fn zindex(&self) -> i8 {
        self.zindex
    }

    pub fn new(context: &RenderContext, num_quads: usize, zindex: i8) -> anyhow::Result<Self> {
        let vb = [
            Self::compute_vertices(context, 32)?,
            Self::compute_vertices(context, num_quads)?,
            Self::compute_vertices(context, 32)?,
        ];

        Ok(Self {
            context: context.clone(),
            vb: RefCell::new(vb),
            zindex,
        })
    }

    pub fn clear_quad_allocation(&self) {
        for vb in self.vb.borrow().iter() {
            vb.clear_quad_allocation();
        }
    }

    pub fn quad_allocator(&self) -> TripleLayerQuadAllocator<'_> {
        // We're creating a self-referential struct here to manage the lifetimes
        // of these related items.  The transmutes are safe because we're only
        // transmuting the lifetimes (not the types), and we're keeping hold
        // of the owner in the returned struct.
        unsafe {
            let vbs = self.vb.borrow().extend_lifetime();
            let layer0 = vbs[0].map().extend_lifetime();
            let layer1 = vbs[1].map().extend_lifetime();
            let layer2 = vbs[2].map().extend_lifetime();
            TripleLayerQuadAllocator::Gpu(BorrowedLayers {
                layers: [layer0, layer1, layer2],
                _owner: vbs,
            })
        }
    }

    pub fn tee_quad_allocator<'a>(
        &'a self,
        heap: &'a mut HeapQuadAllocator,
    ) -> TripleLayerQuadAllocator<'a> {
        match self.quad_allocator() {
            TripleLayerQuadAllocator::Gpu(gpu) => TripleLayerQuadAllocator::Tee { gpu, heap },
            _ => unreachable!("render layers always allocate GPU quads"),
        }
    }

    pub fn need_more_quads(&self, vb_idx: usize) -> Option<usize> {
        self.vb.borrow()[vb_idx].need_more_quads()
    }

    pub fn reallocate_quads(&self, idx: usize, num_quads: usize) -> anyhow::Result<()> {
        let old_capacity = self.vb.borrow()[idx].capacity;
        gpu_debug(format!(
            "reallocate layer zindex={} vb_idx={idx} old_quads={old_capacity} new_quads={num_quads}",
            self.zindex
        ));
        let vb = Self::compute_vertices(&self.context, num_quads)?;
        self.vb.borrow_mut()[idx] = vb;
        Ok(())
    }

    fn total_quad_capacity(&self) -> usize {
        self.vb.borrow().iter().map(|vb| vb.capacity).sum()
    }

    /// Compute a vertex buffer to hold the quads that comprise the visible
    /// portion of the screen.   We recreate this when the screen is resized.
    /// The idea is that we want to minimize any heavy lifting and computation
    /// and instead just poke some attributes into the offset that corresponds
    /// to a changed cell when we need to repaint the screen, and then just
    /// let the GPU figure out the rest.
    fn compute_vertices(
        context: &RenderContext,
        num_quads: usize,
    ) -> anyhow::Result<TripleVertexBuffer> {
        let verts = context.allocate_vertex_buffer_initializer(num_quads);
        log::trace!(
            "compute_vertices num_quads={}, allocated {} bytes",
            num_quads,
            verts.len() * std::mem::size_of::<Vertex>()
        );
        let mut indices = vec![];
        indices.reserve(num_quads * INDICES_PER_CELL);

        for q in 0..num_quads {
            let idx = (q * VERTICES_PER_CELL) as u32;

            // Emit two triangles to form the glyph quad
            indices.push(idx + V_TOP_LEFT as u32);
            indices.push(idx + V_TOP_RIGHT as u32);
            indices.push(idx + V_BOT_LEFT as u32);

            indices.push(idx + V_TOP_RIGHT as u32);
            indices.push(idx + V_BOT_LEFT as u32);
            indices.push(idx + V_BOT_RIGHT as u32);
        }

        let copies = match context {
            RenderContext::Glium(_) => 3,
            RenderContext::WebGpu(_) => 1,
        };
        let mut bufs = Vec::with_capacity(copies);
        for _ in 0..copies {
            bufs.push(context.allocate_vertex_buffer(num_quads, &verts)?);
        }

        let buffer = TripleVertexBuffer {
            index: RefCell::new(0),
            bufs: RefCell::new(bufs),
            capacity: num_quads,
            indices: context.allocate_index_buffer(&indices)?,
            next_quad: RefCell::new(0),
            high_water: Cell::new(0),
            frames_observed: Cell::new(0),
        };

        Ok(buffer)
    }
}

pub struct BorrowedLayers {
    pub layers: [MappedQuads<'static>; 3],

    // layers references _owner, so it must be dropped after layers.
    _owner: Ref<'static, [TripleVertexBuffer; 3]>,
}

impl TripleLayerQuadAllocatorTrait for BorrowedLayers {
    fn allocate(&mut self, layer_num: usize) -> anyhow::Result<QuadImpl<'_>> {
        self.layers[layer_num].allocate()
    }

    fn extend_with(&mut self, layer_num: usize, vertices: &[Vertex]) {
        self.layers[layer_num].extend_with(vertices)
    }
}

pub struct RenderState {
    pub context: RenderContext,
    pub glyph_cache: RefCell<GlyphCache>,
    pub util_sprites: UtilSprites,
    pub glyph_prog: Option<glium::Program>,
    pub layers: RefCell<Vec<Rc<RenderLayer>>>,
    /// Large images drawn from their own textures instead of the atlas
    /// (WebGpu only; glium keeps packing everything into the atlas). Lives
    /// here rather than in the glyph cache so an atlas recreation does not
    /// throw the textures away.
    pub dedicated_images: RefCell<DedicatedImageCache<crate::termwindow::webgpu::ImageTexture>>,
}

/// Images at or above this many RGBA bytes bypass the glyph atlas for a
/// dedicated texture. Absolute rather than relative to the atlas: the atlas
/// settles near 512 at startup, where a fraction of its area would send
/// ordinary small pictures off-atlas too, and a threshold that moved with
/// the atlas would flip the same picture between paths (and samplers) as
/// the atlas grew.
pub const DEDICATED_IMAGE_MIN_BYTES: usize = 1024 * 1024;

/// Resident budget for dedicated image textures, live and pooled together,
/// across all sizes -- a per-size pool has no bound on the number of sizes
/// a drag-resize mints. Two 1632x1026 streams need about 27MiB: two live
/// frames and two spares.
pub const DEDICATED_IMAGE_BUDGET_BYTES: usize = 32 * 1024 * 1024;

/// Whether an image can be drawn from a dedicated texture at all. Two
/// gates: the GPU's per-side texture limit (queried from the adapter --
/// 16384 on Apple GPUs -- because a 20000x1 kitty image is valid yet
/// cannot be one texture), and the cache's own byte budget (an 8000x6000
/// photo is 192MiB as one texture; while displayed it could never be
/// evicted, so the budget would mean nothing). Either way the picture
/// takes the atlas path, which knows how to downscale; failing the paint
/// instead would keep the previous frame on screen for as long as the
/// picture is placed.
pub fn image_fits_dedicated_texture(width: u32, height: u32, max_side: u32) -> bool {
    let bytes = width as usize * height as usize * 4;
    width > 0
        && height > 0
        && width <= max_side
        && height <= max_side
        && bytes <= DEDICATED_IMAGE_BUDGET_BYTES
}

/// Whether an image should be drawn from a dedicated texture. Besides the
/// size threshold, anything the atlas could never place -- a side longer
/// than the atlas once its padding is added -- goes dedicated too, since
/// packing it would only drive atlas growth. Callers gate this on
/// `image_fits_dedicated_texture` first.
pub fn image_wants_dedicated_texture(
    width: u32,
    height: u32,
    padding: usize,
    atlas_side: usize,
) -> bool {
    let bytes = width as usize * height as usize * 4;
    // Atlas::allocate_with_padding reserves the caller's padding plus one
    // texel of its own on each side.
    let reserve = |dim: u32| dim as usize + padding + 2;
    bytes >= DEDICATED_IMAGE_MIN_BYTES
        || reserve(width) > atlas_side
        || reserve(height) > atlas_side
}

/// What the cache needs to know about a texture; abstract so the eviction
/// policy can be tested without a GPU.
pub trait DedicatedTexture {
    fn width(&self) -> u32;
    fn height(&self) -> u32;
    fn byte_size(&self) -> usize {
        self.width() as usize * self.height() as usize * 4
    }
}

impl DedicatedTexture for crate::termwindow::webgpu::ImageTexture {
    fn width(&self) -> u32 {
        self.width
    }
    fn height(&self) -> u32 {
        self.height
    }
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DedicatedImageStats {
    pub live: usize,
    pub pooled: usize,
    pub bytes: usize,
}

struct DedicatedImageEntry<T> {
    texture: Rc<T>,
    last_used: u64,
}

/// Dedicated textures keyed by image hash, with spares pooled by size so a
/// stream of same-sized frames reuses one texture per frame instead of
/// allocating. Bounded by a single byte budget across all sizes.
pub struct DedicatedImageCache<T> {
    entries: HashMap<[u8; 32], DedicatedImageEntry<T>>,
    /// Retired textures, oldest first.
    pool: Vec<Rc<T>>,
    /// Advanced once per presented frame by `end_frame`, so the retry
    /// passes of one frame all see the same value and a second pass hits
    /// the entry the first pass uploaded.
    frame: u64,
    budget: usize,
}

impl<T: DedicatedTexture> DedicatedImageCache<T> {
    pub fn new(budget: usize) -> Self {
        Self {
            entries: HashMap::new(),
            pool: Vec::new(),
            frame: 0,
            budget,
        }
    }

    /// The texture holding `hash`, uploading it via `upload` into a pooled
    /// or freshly `create`d texture on a miss.
    pub fn get_or_upload(
        &mut self,
        hash: [u8; 32],
        width: u32,
        height: u32,
        create: impl FnOnce() -> anyhow::Result<T>,
        upload: impl FnOnce(&T),
    ) -> anyhow::Result<Rc<T>> {
        if let Some(entry) = self.entries.get_mut(&hash) {
            entry.last_used = self.frame;
            return Ok(Rc::clone(&entry.texture));
        }
        let texture = match self
            .pool
            .iter()
            .position(|t| t.width() == width && t.height() == height)
        {
            Some(idx) => self.pool.remove(idx),
            None => Rc::new(create()?),
        };
        upload(&texture);
        self.entries.insert(
            hash,
            DedicatedImageEntry {
                texture: Rc::clone(&texture),
                last_used: self.frame,
            },
        );
        self.enforce_budget();
        Ok(texture)
    }

    /// Call once per paint. Entries not drawn for two frames retire to
    /// the pool; the budget is then re-applied.
    pub fn end_frame(&mut self) {
        // Budget first, while `frame` still marks what this paint drew:
        // after the bump every entry looks idle, and an over-budget frame
        // would destroy the very textures its composites are encoding,
        // re-uploading them all next frame.
        self.enforce_budget();
        self.frame += 1;
        let frame = self.frame;
        let mut retired: Vec<(u64, Rc<T>)> = Vec::new();
        self.entries.retain(|_, entry| {
            if entry.last_used + 2 <= frame {
                retired.push((entry.last_used, Rc::clone(&entry.texture)));
                false
            } else {
                true
            }
        });
        retired.sort_by_key(|(last_used, _)| *last_used);
        self.pool.extend(retired.into_iter().map(|(_, t)| t));
        // Spares only: the live set was already trimmed above, and what
        // just retired may simply exceed the pool's share.
        while self.resident_bytes() > self.budget && !self.pool.is_empty() {
            self.pool.remove(0);
        }
    }

    fn resident_bytes(&self) -> usize {
        self.entries
            .values()
            .map(|e| e.texture.byte_size())
            .chain(self.pool.iter().map(|t| t.byte_size()))
            .sum()
    }

    /// Spares go first, oldest first; then the least recently drawn live
    /// entries, never one drawn this frame (its composite is about to be
    /// encoded).
    fn enforce_budget(&mut self) {
        while self.resident_bytes() > self.budget && !self.pool.is_empty() {
            self.pool.remove(0);
        }
        while self.resident_bytes() > self.budget {
            let victim = self
                .entries
                .iter()
                .filter(|(_, e)| e.last_used < self.frame)
                .min_by_key(|(_, e)| e.last_used)
                .map(|(hash, _)| *hash);
            match victim {
                Some(hash) => {
                    self.entries.remove(&hash);
                }
                None => break,
            }
        }
    }

    pub fn clear(&mut self) {
        self.entries.clear();
        self.pool.clear();
    }

    pub fn stats(&self) -> DedicatedImageStats {
        DedicatedImageStats {
            live: self.entries.len(),
            pooled: self.pool.len(),
            bytes: self.resident_bytes(),
        }
    }
}

#[derive(Debug, Clone)]
pub struct RenderStateStats {
    pub backend: &'static str,
    pub atlas_size: usize,
    pub atlas_usage: ::window::bitmaps::atlas::AtlasUsage,
    /// Newest first.
    pub recent_image_allocs: Vec<String>,
    pub glyphs: usize,
    pub decoded_images: usize,
    pub image_frames: usize,
    pub line_glyphs: usize,
    pub block_glyphs: usize,
    pub svg_icons: usize,
    pub rotated_svg_icons: usize,
    pub cursor_glyphs: usize,
    pub color_sprites: usize,
    pub layers: usize,
    pub layer_quads: usize,
    pub vertex_buffers: usize,
    pub dedicated_images: DedicatedImageStats,
}

impl RenderState {
    pub fn new(
        context: RenderContext,
        fonts: &Rc<FontConfiguration>,
        metrics: &RenderMetrics,
        mut atlas_size: usize,
    ) -> anyhow::Result<Self> {
        loop {
            let glyph_cache = RefCell::new(GlyphCache::new_gl(&context, fonts, atlas_size)?);
            let result = UtilSprites::new(&mut *glyph_cache.borrow_mut(), metrics);
            match result {
                Ok(util_sprites) => {
                    let glyph_prog = match &context {
                        RenderContext::Glium(context) => {
                            Some(Self::compile_prog(&context, Self::glyph_shader)?)
                        }
                        RenderContext::WebGpu(_) => None,
                    };

                    let main_layer = Rc::new(RenderLayer::new(&context, 1024, 0)?);

                    return Ok(Self {
                        context,
                        glyph_cache,
                        util_sprites,
                        glyph_prog,
                        layers: RefCell::new(vec![main_layer]),
                        dedicated_images: RefCell::new(DedicatedImageCache::new(
                            DEDICATED_IMAGE_BUDGET_BYTES,
                        )),
                    });
                }
                Err(OutOfTextureSpace {
                    size: Some(size), ..
                }) => {
                    atlas_size = size;
                }
                Err(OutOfTextureSpace { size: None, .. }) => {
                    anyhow::bail!("requested texture size is impossible!?")
                }
            };
        }
    }

    pub fn layer_for_zindex(&self, zindex: i8) -> anyhow::Result<Rc<RenderLayer>> {
        if let Some(layer) = self
            .layers
            .borrow()
            .iter()
            .find(|l| l.zindex == zindex)
            .map(Rc::clone)
        {
            return Ok(layer);
        }

        let layer = Rc::new(RenderLayer::new(&self.context, 128, zindex)?);
        let mut layers = self.layers.borrow_mut();
        layers.push(Rc::clone(&layer));

        // Keep the layers sorted by zindex so that they are rendered in
        // the correct order when the layers array is iterated.
        layers.sort_by(|a, b| a.zindex.cmp(&b.zindex));

        Ok(layer)
    }

    /// Returns true if any of the layers needed more quads to be allocated,
    /// and if we successfully allocated them.
    /// Returns false if the quads were sufficient.
    /// Returns Err if we needed to allocate but failed.
    pub fn allocated_more_quads(&mut self) -> anyhow::Result<bool> {
        let mut allocated = false;

        for layer in self.layers.borrow().iter() {
            for vb_idx in 0..3 {
                if let Some(need_quads) = layer.need_more_quads(vb_idx) {
                    // Round up to next multiple of 128 that is >=
                    // the number of needed quads for this frame
                    let num_quads = (need_quads + 127) & !127;
                    layer.reallocate_quads(vb_idx, num_quads).with_context(|| {
                        format!(
                            "Failed to allocate {} quads (needed {})",
                            num_quads, need_quads,
                        )
                    })?;
                    log::trace!("Allocated {} quads (needed {})", num_quads, need_quads);
                    allocated = true;
                }
            }
        }

        Ok(allocated)
    }

    /// Give back vertex buffer memory once a usage spike has passed. Called
    /// after the frame's draw has been submitted, while `next_quad` still
    /// holds this frame's usage. WebGPU only: dropping the old wgpu buffer is
    /// deferred until the GPU is done with it, whereas glium's rotating
    /// buffers are persistently mapped and are left alone.
    pub fn maybe_shrink_quads(&self) {
        self.shrink_layers(|vb| vb.shrink_target());
    }

    fn shrink_layers(&self, target_for: impl Fn(&TripleVertexBuffer) -> Option<usize>) {
        if matches!(self.context, RenderContext::Glium(_)) {
            return;
        }
        for layer in self.layers.borrow().iter() {
            for vb_idx in 0..3 {
                let target = target_for(&layer.vb.borrow()[vb_idx]);
                if let Some(target) = target {
                    if let Err(err) = layer.reallocate_quads(vb_idx, target) {
                        log::error!("failed to shrink vertex buffer: {err:#}");
                    }
                }
            }
        }
    }

    /// Shrink every vertex buffer to its floor right now, regardless of
    /// the usage-observation window. Meant for a window that has gone
    /// fully occluded: it paints no frames, so `shrink_target`'s
    /// observation counter never advances and `high_water` is stale.
    /// Regrowth on reveal is bounded: `allocated_more_quads` reallocates
    /// once, sized to the exact need. WebGPU only, as maybe_shrink_quads.
    pub fn shrink_quads_now(&self) {
        // The same value shrink_target lands on for an idle buffer.
        let floor = (MIN_QUADS * 5 / 4).next_power_of_two();
        self.shrink_layers(move |vb| (vb.capacity > floor).then_some(floor));
    }

    fn compile_prog(
        context: &Rc<GliumContext>,
        fragment_shader: fn(&str) -> (String, String),
    ) -> anyhow::Result<glium::Program> {
        let mut errors = vec![];

        let caps = context.get_capabilities();
        log::trace!("Compiling shader. context.capabilities.srgb={}", caps.srgb);

        for version in &["330 core", "330", "320 es", "300 es"] {
            let (vertex_shader, fragment_shader) = fragment_shader(version);
            let source = glium::program::ProgramCreationInput::SourceCode {
                vertex_shader: &vertex_shader,
                fragment_shader: &fragment_shader,
                outputs_srgb: true,
                tessellation_control_shader: None,
                tessellation_evaluation_shader: None,
                transform_feedback_varyings: None,
                uses_point_size: false,
                geometry_shader: None,
            };
            match glium::Program::new(context, source) {
                Ok(prog) => {
                    return Ok(prog);
                }
                Err(err) => errors.push(format!("shader version: {}: {:#}", version, err)),
            };
        }

        anyhow::bail!("Failed to compile shaders: {}", errors.join("\n"))
    }

    fn glyph_shader(version: &str) -> (String, String) {
        (
            format!(
                "#version {}\n{}",
                version,
                include_str!("glyph-vertex.glsl")
            ),
            format!("#version {}\n{}", version, include_str!("glyph-frag.glsl")),
        )
    }

    pub fn config_changed(&mut self) {
        self.glyph_cache.borrow_mut().config_changed();
    }

    /// See [`GlyphCache::evict_scaled_frames`].
    pub fn evict_scaled_image_frames(&self) -> usize {
        self.glyph_cache.borrow_mut().evict_scaled_frames()
    }

    pub fn stats(&self) -> RenderStateStats {
        let glyph = self.glyph_cache.borrow().stats();
        let layers = self.layers.borrow();
        let layer_quads = layers
            .iter()
            .map(|layer| layer.total_quad_capacity())
            .sum::<usize>();
        RenderStateStats {
            backend: match &self.context {
                RenderContext::Glium(_) => "OpenGL",
                RenderContext::WebGpu(_) => "WebGpu",
            },
            atlas_size: glyph.atlas_size,
            atlas_usage: glyph.atlas_usage,
            recent_image_allocs: glyph.recent_image_allocs,
            glyphs: glyph.glyphs,
            decoded_images: glyph.decoded_images,
            image_frames: glyph.image_frames,
            line_glyphs: glyph.line_glyphs,
            block_glyphs: glyph.block_glyphs,
            svg_icons: glyph.svg_icons,
            rotated_svg_icons: glyph.rotated_svg_icons,
            cursor_glyphs: glyph.cursor_glyphs,
            color_sprites: glyph.color_sprites,
            layers: layers.len(),
            dedicated_images: self.dedicated_images.borrow().stats(),
            layer_quads,
            vertex_buffers: layers.len() * 3,
        }
    }

    pub fn recreate_texture_atlas(
        &mut self,
        fonts: &Rc<FontConfiguration>,
        metrics: &RenderMetrics,
        size: Option<usize>,
    ) -> anyhow::Result<()> {
        // We make a a couple of passes at resizing; if the user has selected a large
        // font size (or a large scaling factor) then the `size==None` case will not
        // be able to fit the initial utility glyphs and apply_scale_change won't
        // be able to deal with that error situation.  Rather than make every
        // caller know how to deal with OutOfTextureSpace we try to absorb
        // and accomodate that here.
        let mut size = size;
        let mut attempt = 10;
        loop {
            match self.recreate_texture_atlas_impl(fonts, metrics, size) {
                Ok(_) => return Ok(()),
                Err(err) => {
                    attempt -= 1;
                    if attempt == 0 {
                        return Err(err);
                    }

                    if let Some(&OutOfTextureSpace {
                        size: Some(needed_size),
                        ..
                    }) = err.downcast_ref::<OutOfTextureSpace>()
                    {
                        // This loop only has to fit the utility sprites; it
                        // must not become a back door past the cap the
                        // paint loop enforces.
                        if needed_size > crate::termwindow::MAX_ATLAS_SIZE {
                            anyhow::bail!(
                                "texture atlas would need {needed_size} texels per side \
                                 for the utility sprites, past the {} cap",
                                crate::termwindow::MAX_ATLAS_SIZE
                            );
                        }
                        size.replace(needed_size);
                        continue;
                    }

                    return Err(err);
                }
            }
        }
    }

    fn recreate_texture_atlas_impl(
        &mut self,
        fonts: &Rc<FontConfiguration>,
        metrics: &RenderMetrics,
        size: Option<usize>,
    ) -> anyhow::Result<()> {
        let size = size.unwrap_or_else(|| self.glyph_cache.borrow().atlas.size());
        gpu_debug(format!("recreate texture_atlas requested_size={size}"));
        let mut new_glyph_cache = GlyphCache::new_gl(&self.context, fonts, size)?;
        self.util_sprites = UtilSprites::new(&mut new_glyph_cache, metrics)?;

        let mut glyph_cache = self.glyph_cache.borrow_mut();

        // Steal the decoded image cache; without this, any animating gifs
        // would reset back to frame 0 each time we filled the texture
        std::mem::swap(
            &mut glyph_cache.image_cache,
            &mut new_glyph_cache.image_cache,
        );
        // The upload log is diagnostics for exactly this moment: keep the
        // pictures that forced the recreation visible in the report.
        std::mem::swap(
            &mut glyph_cache.image_alloc_log,
            &mut new_glyph_cache.image_alloc_log,
        );

        *glyph_cache = new_glyph_cache;
        Ok(())
    }
}

#[cfg(test)]
mod dedicated_image_tests {
    use super::{
        image_wants_dedicated_texture, DedicatedImageCache, DedicatedTexture,
        DEDICATED_IMAGE_MIN_BYTES,
    };
    use std::cell::Cell;
    use std::rc::Rc;

    struct FakeTex(u32, u32);
    impl DedicatedTexture for FakeTex {
        fn width(&self) -> u32 {
            self.0
        }
        fn height(&self) -> u32 {
            self.1
        }
    }

    fn hash(n: u8) -> [u8; 32] {
        [n; 32]
    }

    // 512x512x4 = 1MiB per fake texture; a 3MiB budget holds three.
    const SIDE: u32 = 512;
    const MIB: usize = 1024 * 1024;

    fn get(cache: &mut DedicatedImageCache<FakeTex>, n: u8, uploads: &Cell<usize>) -> Rc<FakeTex> {
        cache
            .get_or_upload(
                hash(n),
                SIDE,
                SIDE,
                || Ok(FakeTex(SIDE, SIDE)),
                |_| uploads.set(uploads.get() + 1),
            )
            .unwrap()
    }

    #[test]
    fn a_second_pass_in_the_same_frame_does_not_upload_again() {
        let mut cache = DedicatedImageCache::new(3 * MIB);
        let uploads = Cell::new(0);
        let a = get(&mut cache, 1, &uploads);
        let b = get(&mut cache, 1, &uploads);
        assert!(Rc::ptr_eq(&a, &b));
        assert_eq!(uploads.get(), 1);
    }

    #[test]
    fn a_stream_reuses_one_pooled_texture_per_frame() {
        let mut cache = DedicatedImageCache::new(3 * MIB);
        let uploads = Cell::new(0);
        let first = get(&mut cache, 1, &uploads);
        cache.end_frame();
        let second = get(&mut cache, 2, &uploads);
        cache.end_frame();
        // Frame 1 was last drawn two frames ago: retired to the pool.
        assert_eq!(cache.stats().live, 1);
        assert_eq!(cache.stats().pooled, 1);
        let third = get(&mut cache, 3, &uploads);
        // The retired texture is the one handed out, not a fresh one.
        assert!(Rc::ptr_eq(&first, &third));
        assert!(!Rc::ptr_eq(&second, &third));
        assert_eq!(uploads.get(), 3);
        assert_eq!(cache.stats().bytes, 2 * MIB);
    }

    #[test]
    fn the_budget_drops_spares_first_then_the_least_recently_drawn() {
        let mut cache = DedicatedImageCache::new(3 * MIB);
        let uploads = Cell::new(0);
        get(&mut cache, 1, &uploads);
        cache.end_frame();
        get(&mut cache, 2, &uploads);
        cache.end_frame();
        get(&mut cache, 3, &uploads);
        cache.end_frame();
        // Frame 3 took frame 1's retired texture, so only two textures
        // exist: 3 live, 2's retired to the pool.
        assert_eq!((cache.stats().live, cache.stats().pooled), (1, 1));
        assert_eq!(cache.stats().bytes, 2 * MIB);

        // A second live picture this frame takes the spare...
        get(&mut cache, 4, &uploads);
        assert_eq!((cache.stats().live, cache.stats().pooled), (2, 0));
        // ...a third allocates, landing exactly on the budget...
        get(&mut cache, 5, &uploads);
        assert_eq!((cache.stats().live, cache.stats().pooled), (3, 0));
        assert_eq!(cache.stats().bytes, 3 * MIB);
        // ...and a fourth goes over: with no spares left, the least recently
        // drawn live entry (3, drawn last frame) is evicted, never 4/5/6.
        get(&mut cache, 6, &uploads);
        assert_eq!(cache.stats().live, 3);
        assert_eq!(cache.stats().bytes, 3 * MIB);
        let before = uploads.get();
        get(&mut cache, 4, &uploads);
        get(&mut cache, 5, &uploads);
        get(&mut cache, 6, &uploads);
        assert_eq!(uploads.get(), before, "4/5/6 must still be resident");
        get(&mut cache, 3, &uploads);
        assert_eq!(uploads.get(), before + 1, "3 was evicted and re-uploads");
    }

    #[test]
    fn entries_drawn_this_frame_are_never_evicted() {
        let mut cache = DedicatedImageCache::new(MIB);
        let uploads = Cell::new(0);
        get(&mut cache, 1, &uploads);
        get(&mut cache, 2, &uploads);
        // Over budget, but both were drawn this frame: both stay.
        assert_eq!(cache.stats().live, 2);
        cache.end_frame();
        cache.end_frame();
        // Retired and trimmed back under budget.
        assert!(cache.stats().bytes <= MIB);
    }

    #[test]
    fn threshold_is_absolute_and_catches_unpackable_sides() {
        assert!(image_wants_dedicated_texture(SIDE, SIDE, 16, 4096));
        assert!(!image_wants_dedicated_texture(300, 300, 16, 4096));
        assert_eq!(DEDICATED_IMAGE_MIN_BYTES, 512 * 512 * 4);
        // Small in bytes but wider than the atlas once padded.
        assert!(image_wants_dedicated_texture(500, 8, 16, 512));
        assert!(!image_wants_dedicated_texture(490, 8, 16, 512));
    }

    #[test]
    fn a_side_past_the_gpu_limit_cannot_be_dedicated() {
        use super::image_fits_dedicated_texture;
        assert!(image_fits_dedicated_texture(8192, 1, 8192));
        assert!(!image_fits_dedicated_texture(8193, 1, 8192));
        assert!(!image_fits_dedicated_texture(1, 20000, 8192));
        assert!(!image_fits_dedicated_texture(0, 10, 8192));
    }

    #[test]
    fn a_picture_bigger_than_the_whole_budget_cannot_be_dedicated() {
        use super::{image_fits_dedicated_texture, DEDICATED_IMAGE_BUDGET_BYTES};
        // 8000x6000 RGBA = 192MiB: six times the budget, unevictable while
        // displayed. The atlas path downscales it instead.
        assert!(!image_fits_dedicated_texture(8000, 6000, 16384));
        let side = ((DEDICATED_IMAGE_BUDGET_BYTES / 4) as f64).sqrt() as u32;
        assert!(image_fits_dedicated_texture(side, side, 16384));
    }

    #[test]
    fn an_over_budget_frame_keeps_what_it_is_drawing() {
        // Two live pictures against a one-picture budget: end_frame runs
        // while their composites are still waiting to be encoded, so
        // neither may be destroyed this frame. The next frame, with
        // neither redrawn, trims back to the budget.
        let mut cache = DedicatedImageCache::new(MIB);
        let uploads = Cell::new(0);
        get(&mut cache, 1, &uploads);
        get(&mut cache, 2, &uploads);
        cache.end_frame();
        assert_eq!(cache.stats().live, 2, "hot textures survive the frame");
        cache.end_frame();
        assert!(cache.stats().bytes <= MIB, "idle textures trim next frame");
    }
}