edgefirst-image 0.38.0

// SPDX-FileCopyrightText: Copyright 2025 Au-Zone Technologies
// SPDX-License-Identifier: Apache-2.0

use edgefirst_tensor::{
    DType, PixelFormat, PixelLayout, Tensor, TensorMapTrait, TensorMemory, TensorTrait,
};
use edgefirst_tensor::{DetectBox, ProtoData, ProtoLayout, Segmentation};
use std::collections::BTreeSet;
use std::ffi::{c_char, c_void, CStr};
use std::time::Instant;

use super::EglDisplayKind;

use super::cache::{BufferImportKey, CacheKind, GlCacheStats, ImportCache};
use super::platform::{GlPlatform, Platform};

/// The platform display/context owned by this processor — `GlContext` on
/// Linux, `AngleDisplay` (per-processor ANGLE context) on macOS.
type PlatformDisplay = <Platform as GlPlatform>::Display;
/// The owned platform import the caches hold (`EglImage` / `IoSurfacePbuffer`).
type PlatformImport = <Platform as GlPlatform>::Import;
/// The `Copy` import handle (`egl::Image` / `egl::Surface`).
type PlatformHandle = <Platform as GlPlatform>::ImportHandle;
use super::resources::{Buffer, FrameBuffer, GlProgram, Texture, UploadSource};
use super::shaders::{
    check_gl_error, generate_color_shader, generate_float_nhwc_packed_shader,
    generate_float_rgba_shader, generate_instanced_segmentation_shader,
    generate_nv_to_rgba_bilinear_int8_shader_2d, generate_nv_to_rgba_bilinear_shader_2d,
    generate_nv_to_rgba_hw_bilinear_int8_shader_2d, generate_nv_to_rgba_hw_bilinear_shader_2d,
    generate_nv_to_rgba_int8_shader_2d, generate_nv_to_rgba_shader_2d,
    generate_nv_to_rgba_y2y_int8_shader, generate_nv_to_rgba_y2y_shader,
    generate_packed_f32_nhwc_shader, generate_packed_rgba8_int8_shader_2d,
    generate_packed_rgba8_shader_2d, generate_planar_rgb_f16_packed_shader,
    generate_planar_rgb_int8_shader, generate_planar_rgb_int8_shader_2d,
    generate_planar_rgb_shader, generate_planar_rgb_shader_2d, generate_proto_dequant_shader_int8,
    generate_proto_repack_compute_shader, generate_proto_segmentation_shader,
    generate_proto_segmentation_shader_f32, generate_proto_segmentation_shader_int8_bilinear,
    generate_proto_segmentation_shader_int8_nearest, generate_segmentation_shader,
    generate_texture_fragment_shader, generate_texture_fragment_shader_yuv,
    generate_texture_int8_shader, generate_texture_int8_shader_yuv, generate_vertex_shader,
    quant_mapped,
};
use super::{Int8InterpolationMode, RegionOfInterest, TransferBackend};
use crate::{Error, Flip, ImageProcessorTrait, ResolvedCrop, Rotation, DEFAULT_COLORS};
use edgefirst_tensor::TensorDyn;

/// Linux GL float (F16/F32) preprocessing paths. Declared as a child of
/// `processor` so its `impl GLProcessorST` block can reach this module's
/// private fields (the float programs, EGLImage caches, capability flags, …)
/// without promoting them to `pub(super)`.
mod float;
// Re-export the float classifier/support items at the `processor` module path
// so the dispatch in `convert()` and the `gl::tests` unit tests keep using
// `processor::{...}` paths unchanged.
pub(super) use float::{classify_float_render, float_render_support, FloatRenderPath};
// `packed_planar_layout` is only reached through this re-export by the
// `gl::tests` unit tests (via `processor::packed_planar_layout`); the lib body
// itself does not reference it, so the unused-import lint can't see the use.
#[allow(unused_imports)]
pub(super) use float::packed_planar_layout;

/// Which GPU/CPU path was taken for the most recent NV* convert call.
///
/// Recorded by `draw_nv_texture_2d` / `draw_camera_texture_eglimage` / CPU
/// fallback so that tests and the profiler can assert that DMA NV* inputs never
/// silently fall back to CPU. Only meaningful immediately after a convert whose
/// source is `Nv12`/`Nv16`/`Nv24`; it is not reset for non-NV* converts (a
/// reader observing it after, say, an RGBA convert sees the prior NV* value).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum NvConvertPath {
    /// Driver-decoded YUV via `samplerExternalOES` EGLImage. The GPU driver
    /// performs YUV→RGB (matrix + chroma upsampling); colorimetry is only as
    /// correct as the driver's EGL hint support. Required for true-multiplane
    /// NV12 (separate Y/UV fds). Was "Path A".
    ExternalSampler,
    /// R8 `texelFetch` shader applying the exact per-tensor YUV→RGB matrix in
    /// the shader (ES 3.0, no extension). Portable and identical across GPUs;
    /// no width constraint (uses the 64-aligned stride). Was "Path B".
    ShaderR8,
    /// CPU fallback (EGLImage creation failed or format not DMA-backed).
    Cpu,
    /// Not yet set (initial state, or non-NV* convert).
    None,
}

/// Client preference for the NV* GPU conversion path, set via
/// `EDGEFIRST_NV_CONVERT_PATH` (`sampler` | `shader` | `auto`).
///
/// `Auto` prefers [`NvConvertPath::ShaderR8`] (portable, colorimetry-exact)
/// wherever possible, using [`NvConvertPath::ExternalSampler`] only when the
/// shader path is impossible (true-multiplane NV12). The forced variants are
/// for benchmarking and platform bring-up; an impossible force logs a warning
/// and falls back rather than failing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum NvPathPref {
    Auto,
    ForceSampler,
    ForceShader,
}

/// Bound destination render target for one convert, produced by
/// [`GLProcessorST::bind_dst`]. The GL counterpart of
/// [`super::render::DstLowering`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DstTarget {
    /// The destination buffer itself is the FBO colour attachment (EGLImage
    /// renderbuffer or texture): the render writes it directly, no readback.
    ZeroCopyImage,
    /// Offscreen texture render target; `readback` copies the result out.
    Texture { readback: DstReadback },
}

/// How a [`DstTarget::Texture`] render reaches the destination tensor.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DstReadback {
    /// `glReadPixels` straight into the mapped Mem tensor.
    Mem,
    /// `glReadPixels` into this destination PBO's PACK binding.
    Pbo(u32),
}

impl DstTarget {
    /// The `dst_feed` value for this target: how the convert's OUTPUT reached
    /// the destination tensor.
    ///
    /// Recorded for every target, so the field's absence never has to be
    /// interpreted. `zero_copy` is the render writing the destination buffer
    /// itself; `mapped_texture` is a render into an offscreen texture read
    /// back through the tensor's `map()`, whether the destination was always
    /// host memory or the driver refused its import; `pbo` is the same render
    /// read back into the destination PBO's PACK binding, with no CPU visit.
    fn feed(self) -> &'static str {
        match self {
            DstTarget::ZeroCopyImage => "zero_copy",
            DstTarget::Texture {
                readback: DstReadback::Mem,
            } => "mapped_texture",
            DstTarget::Texture {
                readback: DstReadback::Pbo(_),
            } => "pbo",
        }
    }
}

impl DstReadback {
    /// The PBO id in the `Option` shape `readback_rendered` consumes.
    fn pbo_id(self) -> Option<u32> {
        match self {
            DstReadback::Mem => None,
            DstReadback::Pbo(id) => Some(id),
        }
    }
}

/// Borrowed proto data for the layered-float render plans: the
/// dispatcher's dtype arm keeps the `TensorMap` alive and hands the typed
/// view down to `render_proto_layers`, which matches it against
/// `ProtoPlan::upload`.
enum ProtoLayersData<'a> {
    F32(ndarray::ArrayView3<'a, f32>),
    F16(ndarray::ArrayView3<'a, half::f16>),
}

/// Uniform locations for one `nv_r8` program variant, resolved once at link
/// time — `glGetUniformLocation` is a per-call string lookup in the driver
/// and the NV draw previously issued 12 per frame.
#[derive(Clone, Copy)]
struct NvUniformLocs {
    img_size: i32,
    tex_width: i32,
    chroma_shift: i32,
    chroma_lines: i32,
    src_rect: i32,
    luma_scale: i32,
    luma_clamp: i32,
    chroma_scale: i32,
    chroma_clamp: i32,
    src_extent: i32,
    y_offset: i32,
    y_scale: i32,
    c_vr: i32,
    c_ug: i32,
    c_vg: i32,
    c_ub: i32,
}

/// Uniform locations for one float-path program, resolved once per program
/// — previously up to five `GetUniformLocation` string lookups per float
/// draw (`draw_float_quad`). Same pattern as [`NvUniformLocs`]. A location
/// of `-1` (uniform absent in that program variant) is harmless: GL ignores
/// `Uniform*` calls with location `-1` by specification.
#[derive(Clone, Copy)]
pub(super) struct FloatQuadLocs {
    pub(super) sampler: i32,
    pub(super) src_rect_uv: i32,
    pub(super) src_extent: i32,
    pub(super) dst_rect_px: i32,
    pub(super) pad_color: i32,
    pub(super) dst_image_size: i32,
    pub(super) norm_scale: i32,
    pub(super) norm_offset: i32,
}

/// Per-channel output mapping for the float render paths, in sampler units
/// (`output = sample * scale + offset`), plus the letterbox pad as written.
/// Identity outside a convert that asks for normalization.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(super) struct FloatNorm {
    pub(super) scale: [f32; 4],
    pub(super) offset: [f32; 4],
    pub(super) pad: Option<[f32; 4]>,
}

impl FloatNorm {
    pub(super) const IDENTITY: Self = Self {
        scale: [1.0; 4],
        offset: [0.0; 4],
        pad: None,
    };
}

/// The `quantize()` uniforms of the int8 programs, in sampler units for the
/// RGB channels: `clamp(floor(v * scale + offset + 0.5) + zero, lo, hi)`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(super) struct IntQuant {
    pub(super) scale: [f32; 3],
    pub(super) offset: [f32; 3],
    pub(super) zero: [f32; 3],
    pub(super) lo: [f32; 3],
    pub(super) hi: [f32; 3],
}

impl IntQuant {
    /// From an integer output map in RGB order.
    pub(super) fn from_map(map: &crate::options::OutputMap) -> Self {
        let b = map.bounds.unwrap_or([(0.0, 255.0); 4]);
        Self {
            scale: std::array::from_fn(|c| map.scale[c] * 255.0),
            offset: std::array::from_fn(|c| map.offset[c]),
            zero: std::array::from_fn(|c| map.zero_point[c]),
            lo: std::array::from_fn(|c| b[c].0),
            hi: std::array::from_fn(|c| b[c].1),
        }
    }
}

/// One build of every int8 program, with the link-time state its draws read.
/// The processor's int8 fields hold the active build and `int8_alt` the
/// other; [`GLProcessorST::use_int8_set`] swaps them.
struct Int8Set {
    texture: GlProgram,
    texture_yuv: Option<GlProgram>,
    planar: Option<GlProgram>,
    planar_2d: GlProgram,
    yuyv_2d: GlProgram,
    yuyv_2d_locs: [i32; 8],
    packed_rgba8_2d: GlProgram,
    /// In [`NvSampling::program`] order, int8 entries only.
    nv_r8: [GlProgram; 3],
    nv_r8_uniforms: [NvUniformState; 3],
    nv_y2y: Option<(GlProgram, NvUniformState)>,
    texture_src_extent_loc: i32,
    yuv_src_extent_loc: i32,
    planar_src_extent_loc: i32,
}

impl Int8Set {
    /// Link the int8 programs: `quantize()` as uniforms when `mapped`, else
    /// the plain bias in literals. The Y2Y program is built only with `y2y`,
    /// and is `None` if the driver refuses it.
    fn new(mapped: bool, y2y: bool) -> Result<Self, Error> {
        let build = |src: &str| {
            if mapped {
                GlProgram::new(generate_vertex_shader(), &quant_mapped(src))
            } else {
                GlProgram::new(generate_vertex_shader(), src)
            }
        };
        let external = |src: &str| Platform::EXTERNAL_OES.then(|| build(src)).transpose();
        let texture = build(generate_texture_int8_shader())?;
        let texture_yuv = external(generate_texture_int8_shader_yuv())?;
        let planar = external(generate_planar_rgb_int8_shader())?;
        let planar_2d = build(generate_planar_rgb_int8_shader_2d())?;
        planar_2d.load_uniform_1i(c"tex", 0)?;
        let yuyv_2d = build(super::shaders_common::YUYV_RGBA_2D_INT8_FRAGMENT)?;
        let yuyv_2d_locs = yuyv_2d_locs(&yuyv_2d);
        let packed_rgba8_2d = build(generate_packed_rgba8_int8_shader_2d())?;
        packed_rgba8_2d.load_uniform_1i(c"tex", 1)?;
        let nv_r8 = [
            build(generate_nv_to_rgba_int8_shader_2d())?,
            build(generate_nv_to_rgba_bilinear_int8_shader_2d())?,
            build(generate_nv_to_rgba_hw_bilinear_int8_shader_2d())?,
        ];
        let nv_r8_uniforms = nv_r8.each_ref().map(NvUniformState::resolve);
        let nv_y2y = if y2y {
            match build(generate_nv_to_rgba_y2y_int8_shader()) {
                Ok(p) => {
                    let u = NvUniformState::resolve(&p);
                    Some((p, u))
                }
                Err(e) => {
                    log::info!("the int8 Y2Y NV program did not build: {e:?}");
                    None
                }
            }
        } else {
            None
        };
        let src_extent = |p: Option<&GlProgram>| {
            p.map_or(-1, |p| {
                // SAFETY: `p` was linked above on this thread's current
                // context and the name is a `c"..."` literal.
                unsafe { edgefirst_gl::gl::GetUniformLocation(p.id, c"src_extent".as_ptr()) }
            })
        };
        Ok(Self {
            texture_src_extent_loc: src_extent(Some(&texture)),
            yuv_src_extent_loc: src_extent(texture_yuv.as_ref()),
            planar_src_extent_loc: src_extent(planar.as_ref()),
            texture,
            texture_yuv,
            planar,
            planar_2d,
            yuyv_2d,
            yuyv_2d_locs,
            packed_rgba8_2d,
            nv_r8,
            nv_r8_uniforms,
            nv_y2y,
        })
    }
}

/// Bind `tex` to unit 0 and resolve the YUYV program's uniforms, in the
/// order `(src_size, y_offset, y_scale, c_vr, c_ug, c_vg, c_ub, src_extent)`.
fn yuyv_2d_locs(p: &GlProgram) -> [i32; 8] {
    // SAFETY: `p` is linked on this thread's current context; each name is a
    // `c"..."` literal, a live NUL-terminated string for the call.
    unsafe {
        edgefirst_gl::gl::UseProgram(p.id);
        let tex = edgefirst_gl::gl::GetUniformLocation(p.id, c"tex".as_ptr());
        edgefirst_gl::gl::Uniform1i(tex, 0);
        [
            c"src_size",
            c"y_offset",
            c"y_scale",
            c"c_vr",
            c"c_ug",
            c"c_vg",
            c"c_ub",
            c"src_extent",
        ]
        .map(|name| edgefirst_gl::gl::GetUniformLocation(p.id, name.as_ptr()))
    }
}

/// Per-program uniform state for one `nv_r8` variant. Uniform values are
/// per-program GL state and persist across draws, so the constant sampler
/// binding (`src` = unit 0) is uploaded once at resolve time and
/// `last_colorimetry` lets the draw skip re-uploading the six YUV-matrix
/// floats while the source's (encoding, range) is unchanged.
struct NvUniformState {
    locs: NvUniformLocs,
    last_colorimetry: Option<(
        edgefirst_tensor::ColorEncoding,
        edgefirst_tensor::ColorRange,
    )>,
}

impl NvUniformState {
    fn resolve(program: &GlProgram) -> Self {
        unsafe {
            edgefirst_gl::gl::UseProgram(program.id);
            let loc = |name: &std::ffi::CStr| {
                edgefirst_gl::gl::GetUniformLocation(program.id, name.as_ptr())
            };
            // Constant: the NV shaders always sample `src` from unit 0, and
            // the hardware-filtered program its chroma view from unit 1.
            edgefirst_gl::gl::Uniform1i(loc(c"src"), 0);
            edgefirst_gl::gl::Uniform1i(loc(c"uv_tex"), 1);
            NvUniformState {
                locs: NvUniformLocs {
                    img_size: loc(c"img_size"),
                    tex_width: loc(c"tex_width"),
                    chroma_shift: loc(c"chroma_shift"),
                    chroma_lines: loc(c"chroma_lines"),
                    src_rect: loc(c"src_rect"),
                    luma_scale: loc(c"luma_scale"),
                    luma_clamp: loc(c"luma_clamp"),
                    chroma_scale: loc(c"chroma_scale"),
                    chroma_clamp: loc(c"chroma_clamp"),
                    src_extent: loc(c"src_extent"),
                    y_offset: loc(c"y_offset"),
                    y_scale: loc(c"y_scale"),
                    c_vr: loc(c"c_vr"),
                    c_ug: loc(c"c_ug"),
                    c_vg: loc(c"c_vg"),
                    c_ub: loc(c"c_ub"),
                },
                last_colorimetry: None,
            }
        }
    }
}

/// The source pixels an `nv_r8` draw samples: the crop rectangle in source
/// pixels (`right`/`bottom` exclusive) and whether the draw rescales it.
/// Built from the convert's geometry rather than from the half-texel-inset
/// [`RegionOfInterest`] the filtered-sampler paths use, because the NV shader
/// computes texel positions itself and needs the crop's true edges.
#[derive(Clone, Copy, Debug)]
struct NvSampleRect {
    left: usize,
    top: usize,
    right: usize,
    bottom: usize,
    resample: bool,
    /// Pixels the draw covers on the destination.
    dst_pixels: usize,
}

impl NvSampleRect {
    /// `src_crop` and `dst_crop` default to the whole source and destination.
    /// A quarter-turn rotation swaps the crop's axes on the destination.
    fn new(
        src_crop: Option<crate::Rect>,
        dst_crop: Option<crate::Rect>,
        (src_w, src_h): (usize, usize),
        (dst_w, dst_h): (usize, usize),
        rotation: crate::Rotation,
    ) -> Self {
        let src = src_crop.unwrap_or(crate::Rect::new(0, 0, src_w, src_h));
        let dst = dst_crop.unwrap_or(crate::Rect::new(0, 0, dst_w, dst_h));
        let (w, h) = match rotation {
            crate::Rotation::Clockwise90 | crate::Rotation::CounterClockwise90 => {
                (src.height, src.width)
            }
            _ => (src.width, src.height),
        };
        NvSampleRect {
            left: src.left,
            top: src.top,
            right: src.left + src.width,
            bottom: src.top + src.height,
            resample: (w, h) != (dst.width, dst.height),
            dst_pixels: dst.width * dst.height,
        }
    }

    /// The rectangle as the [`RegionOfInterest`] of a `src_w`x`src_h` source,
    /// for the draws that sample through a filtered sampler.
    fn roi(&self, src_w: usize, src_h: usize) -> RegionOfInterest {
        let crop = crate::Rect::new(
            self.left,
            self.top,
            self.right - self.left,
            self.bottom - self.top,
        );
        RegionOfInterest::from_crop(&crop, src_w, src_h)
    }
}

/// The (encoding, range) an NV draw's in-shader matrix applies: the source's
/// own colorimetry, with missing axes filled by the SD/HD height heuristic.
fn nv_colorimetry(
    colorimetry: Option<edgefirst_tensor::Colorimetry>,
    height: Option<usize>,
) -> (
    edgefirst_tensor::ColorEncoding,
    edgefirst_tensor::ColorRange,
) {
    let cm = crate::colorimetry::resolve_colorimetry(colorimetry, height);
    (
        cm.encoding
            .unwrap_or(edgefirst_tensor::ColorEncoding::Bt709),
        cm.range.unwrap_or(edgefirst_tensor::ColorRange::Limited),
    )
}

/// Largest source-to-output pixel ratio at which a bilinear NV resize takes
/// [`NvSampling::HardwareYuv`]. Sampling an external YUV import costs in
/// proportion to the whole source on Mali-G310 (about 0.3 ms per megapixel at
/// i.MX 95 clocks), while the shader-filtered program costs in proportion to
/// the output, so a strong downscale is cheaper in the shader. Measured there
/// into 640x640: 720p 1.0 ms vs 2.2 ms, 1080p 1.4 vs 2.1, 4K 3.2 vs 1.8,
/// crossing near ten source pixels per output pixel.
const Y2Y_MAX_SOURCE_PER_OUTPUT_PIXEL: usize = 10;

/// Whether a bilinear resize of a `src_pixels` source into `dst_pixels`
/// output pixels is cheaper through [`NvSampling::HardwareYuv`].
fn y2y_pays_off(src_pixels: usize, dst_pixels: usize) -> bool {
    src_pixels <= Y2Y_MAX_SOURCE_PER_OUTPUT_PIXEL * dst_pixels
}

/// How an `nv_r8` draw samples the source, which selects its program.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(super) enum NvSampling {
    /// One texel per pixel: a draw that does not rescale, or
    /// [`crate::Interpolation::Nearest`].
    Single = 0,
    /// Bilinear blended in the shader from four single-texel conversions:
    /// the fallback when the chroma plane cannot be bound on its own.
    Shader = 1,
    /// Bilinear through the texture units' LINEAR filter, on the combined
    /// plane for luma and a (U, V) view of the chroma plane.
    Hardware = 2,
    /// Bilinear through the texture unit from one NV12 import sampled as raw
    /// YUV (`GL_EXT_YUV_target`), where the chroma plane cannot be bound on
    /// its own. Drawn by the Y2Y programs, not `nv_r8_programs`.
    HardwareYuv = 3,
}

/// What an `nv_r8` draw can bind, which decides its [`NvSampling`].
#[derive(Clone, Copy, Debug)]
struct NvSamplingInputs {
    /// The draw rescales and the interpolation is bilinear.
    bilinear: bool,
    /// The texture units may filter (`nv_hw_filter`).
    hw_filter: bool,
    /// The source is a DMA-BUF import rather than an upload.
    imported: bool,
    /// The import's chroma plane is bound as its own (U, V) texture.
    chroma_view: bool,
    /// The Y2Y programs built, the source is NV12, and [`y2y_pays_off`].
    y2y: bool,
}

impl NvSampling {
    /// An upload's chroma plane can always be bound on its own, an import's
    /// only where the GPU takes the chroma plane's offset. Where it cannot,
    /// a GPU with the Y2Y programs still filters in hardware.
    fn choose(inputs: NvSamplingInputs) -> Self {
        let NvSamplingInputs {
            bilinear,
            hw_filter,
            imported,
            chroma_view,
            y2y,
        } = inputs;
        if !bilinear {
            NvSampling::Single
        } else if hw_filter && (!imported || chroma_view) {
            NvSampling::Hardware
        } else if hw_filter && y2y {
            NvSampling::HardwareYuv
        } else {
            NvSampling::Shader
        }
    }

    /// Index into `nv_r8_programs`: two programs (u8, int8) per sampling.
    fn program(self, is_int8: bool) -> usize {
        self as usize * 2 + usize::from(is_int8)
    }
}

/// OpenGL single-threaded image converter.
pub struct GLProcessorST {
    camera_eglimage_texture: Texture,
    camera_normal_texture: Texture,
    render_texture: Texture,
    segmentation_texture: Texture,
    segmentation_program: GlProgram,
    instanced_segmentation_program: GlProgram,
    proto_texture: Texture,
    proto_segmentation_program: GlProgram,
    proto_segmentation_int8_nearest_program: GlProgram,
    proto_segmentation_int8_bilinear_program: GlProgram,
    proto_dequant_int8_program: GlProgram,
    proto_segmentation_f32_program: GlProgram,
    color_program: GlProgram,
    /// Bounding-box outline thickness in destination pixels; never 0.
    box_line_width: f32,
    /// Last opacity value set on shader uniforms (avoids redundant GL calls).
    cached_opacity: f32,
    /// Allocated proto texture dimensions for SubImage3D fast path: (w, h, layers, internal_fmt).
    proto_tex_dims: (usize, usize, usize, u32),
    /// Whether GL_OES_texture_float_linear is available (allows GL_LINEAR on R32F textures).
    has_float_linear: bool,
    /// Whether GL_EXT_texture_format_BGRA8888 is available (allows BGRA destinations).
    pub(super) has_bgra: bool,
    /// Whether `GL_EXT_color_buffer_float` is advertised in the
    /// extension string, i.e. the GPU can render to an F32 color
    /// attachment. The probe is extension-string only — GLES 3.2 core
    /// also mandates F32 color buffers, but this flag does not consult
    /// `GL_VERSION`, so a 3.2-core context without the extension string
    /// reports `false`. Surfaced through `RenderDtypeSupport`; on Linux
    /// this gates the F32 NHWC PBO render path
    /// (`FloatRenderPath::PboF32Nhwc`) and on Windows the RGBA32F
    /// zero-copy paths, via `classify_float_render`.
    pub(super) supports_f32_color: bool,
    /// Whether `GL_EXT_color_buffer_half_float` is advertised, i.e. the
    /// GPU can render to an F16 color attachment. Surfaced through
    /// `RenderDtypeSupport`; on Linux this gates the F16 NCHW PBO and
    /// zero-copy DMA-BUF render paths (`FloatRenderPath::PboF16Nchw`,
    /// `FloatRenderPath::ZeroCopyF16Nchw`) and on Windows the RGBA16F
    /// zero-copy paths, via `classify_float_render`.
    pub(super) supports_f16_color: bool,
    /// Interpolation mode for int8 proto textures.
    int8_interpolation_mode: Int8InterpolationMode,
    /// Intermediate FBO texture for two-pass int8 dequant path.
    proto_dequant_texture: Texture,
    /// Allocated dequant texture dims for the recreate-on-change gate:
    /// (w, h, layers, internal_fmt). Mirrors `proto_tex_dims`.
    proto_dequant_tex_dims: (usize, usize, usize, u32),
    /// Persistent FBO for the two-pass int8 dequant render — previously a
    /// fresh `FrameBuffer::new()` per call.
    proto_dequant_fbo: FrameBuffer,
    /// Per-detection quad uniform locations, `(program_id, mask_coeff,
    /// class_index)`, re-resolved only when the bound proto program
    /// changes. `Cell` because the resolving call sites hold `&self`
    /// borrows of the program; id 0 = unresolved.
    proto_quad_locs: std::cell::Cell<(u32, i32, i32)>,
    /// Compute shader program for HWC→CHW proto repack (GLES 3.1 only).
    proto_repack_compute_program: Option<u32>,
    /// `(width, height, num_protos)` uniform locations for the compute
    /// program, resolved once at compile — previously three
    /// GetUniformLocation string lookups per dispatch.
    proto_compute_locs: (i32, i32, i32),
    /// SSBO for proto data upload (compute shader path).
    proto_ssbo: u32,
    /// Current allocated size of proto SSBO in bytes (0 = not allocated).
    proto_ssbo_size: usize,
    vertex_buffer: Buffer,
    texture_buffer: Buffer,
    /// Persistent FBO for the convert() render path.
    /// Created once, reused by re-attaching textures each frame.
    convert_fbo: FrameBuffer,
    /// Persistent FBO for draw_decoded_masks / draw_proto_masks render path.
    /// Separate from convert_fbo so EGLImage binding state is not shared
    /// between convert and draw, avoiding redundant EGLImageTargetTexture2DOES
    /// calls on every frame when both paths are used.
    draw_fbo: FrameBuffer,
    /// Texture used as FBO color attachment for draw operations (DMA path).
    /// Separate from render_texture so EGLImageTargetTexture2DOES calls made
    /// by convert do not invalidate the draw path's bound EGLImage, and
    /// vice versa.
    draw_render_texture: Texture,
    /// EGLImage cache for source DMA buffers.
    src_egl_cache: ImportCache<PlatformImport>,
    /// EGLImage cache for destination DMA buffers.
    dst_egl_cache: ImportCache<PlatformImport>,
    /// Whether the BGRA byte-swap workaround warning has been logged.
    bgra_warned: bool,
    /// Reusable RGBA staging buffer for `read_pixels_into`'s fallback path
    /// (drivers whose implementation read-pair rejects direct RGB/RED
    /// reads — ANGLE/Metal, V3D). Grown on demand, kept at high-water mark.
    readback_scratch: Vec<u8>,
    /// Test hook: make every zero-copy DESTINATION import fail, the way a
    /// driver that refuses the buffer does, so the fallback to the
    /// mapped-texture readback is exercised on hosts whose driver accepts
    /// every destination. Injected at the import itself
    /// (`get_or_create_egl_image` for `CacheKind::Dst` and
    /// `get_or_create_egl_image_rgb`), not at the routing decision, so what a
    /// test drives is the real trigger.
    #[cfg(test)]
    pub(super) fail_dst_import: bool,
    /// While set, a failed zero-copy destination import PROPAGATES instead of
    /// falling back to the mapped-texture readback — at both sites that can
    /// fall back, `bind_dst` and the packed-RGB pre-flight. Exactly one caller
    /// sets it: `verify_dma_buf_roundtrip`, whose whole question is whether
    /// this display can render into a DMA-BUF at all. Serving that convert through
    /// the fallback would answer the question with the fallback's own output
    /// and leave a display that cannot import a destination believing it can —
    /// and would run a texture upload over the shared render texture before
    /// the first real convert, which is state the probe has no business
    /// leaving behind.
    probe_dst_import_only: bool,
    /// Buffers whose destination import has already been reported as declined
    /// into the mapped-texture readback. Warn once per buffer, debug on the
    /// repeats — the same shape as `nv_import_warned` on the source side, so a
    /// per-frame decline on a pooled buffer does not flood the log.
    dst_import_warned: std::collections::HashSet<u64>,
    /// Whether the GPU is a Verisilicon/Vivante core (detected via GL_RENDERER).
    /// Used to block operations known to cause unrecoverable GPU hangs.
    pub(super) is_vivante: bool,
    /// Whether the GPU is an Arm Mali core (GL_RENDERER). Used to decline a
    /// source DMA-BUF import at a plane offset Mali would sample zeros from,
    /// so the upload path takes it instead — see `rejects_unaligned_import_offset`
    /// and issue #165. Its reach is now the imports the aligned-base rebase
    /// does not move: a source it rebases presents an aligned base and stays
    /// zero-copy, so what still declines is NV12's two-plane import, the
    /// combined-plane R8 import, YUYV's macropixel phase, planar R8, and any
    /// packed source the rebase could not apply to (#170).
    is_mali: bool,
    /// Whether the GPU is a virtualized/paravirtual device (GL_RENDERER).
    /// Concurrent GL across contexts mis-renders on paravirtual Metal
    /// (observed on macOS CI runners: parallel processors produce ~60-86%
    /// diverged output bytes); such devices get the Full serialization
    /// policy, like Vivante.
    is_virtual_gpu: bool,
    /// Whether the GL implementation is ANGLE (GLES over Metal/D3D — the
    /// only GL on macOS). Concurrent GL across contexts loses per-draw
    /// state there, so ANGLE takes the Full serialization policy; see
    /// [`requires_full_serialization`].
    is_angle: bool,
    /// Whether the GPU is a Qualcomm Adreno on the proprietary driver
    /// (GL_RENDERER). Takes the Full serialization policy, and its DMA-BUF
    /// imports at an unaligned plane offset — destinations included — or of
    /// a two-buffer NV12 are declined onto the upload / readback routes; see
    /// [`RendererTraits::adreno`].
    pub(super) is_adreno: bool,
    /// Whether to use renderbuffer-backed EGLImages for DMA destinations.
    ///
    /// Set `EDGEFIRST_OPENGL_RENDERSURFACE=1` to enable (required on i.MX 95 / Mali-G310
    /// with Neutron NPU DMA-BUF destinations). Defaults to `false` (texture path) for
    /// 0.13.x compatibility with Vivante (i.MX 8MP). Will become the automatic default
    /// on non-Vivante platforms in a future release after broader testing.
    use_renderbuffer: bool,
    /// Intermediate RGBA texture for two-pass packed RGB conversion.
    /// Pass 1 renders YUYV/NV12→RGBA here; Pass 2 packs RGBA→RGB to DMA dest.
    packed_rgb_intermediate_tex: Texture,
    /// FBO for pass 1 of packed RGB conversion (renders to intermediate texture).
    packed_rgb_fbo: FrameBuffer,
    /// Current allocated size of the intermediate texture (0,0 = unallocated).
    packed_rgb_intermediate_size: (usize, usize),
    texture_program: GlProgram,
    /// External-OES sampler programs (`None` where the platform lacks
    /// `GL_OES_EGL_image_external_essl3` — ANGLE/Metal).
    texture_program_yuv: Option<GlProgram>,
    /// Int8 variant of texture_program — applies XOR 0x80 bias in fragment shader.
    texture_int8_program: GlProgram,
    /// Int8 variant of texture_program_yuv — applies XOR 0x80 bias in fragment shader.
    texture_int8_program_yuv: Option<GlProgram>,
    texture_program_planar: Option<GlProgram>,
    /// Shader: existing planar RGB with int8 bias (XOR 0x80) applied to output.
    texture_program_planar_int8: Option<GlProgram>,
    /// YUYV (RG-sampled) → RGBA, portable `sampler2D`: an IOSurface attach
    /// on macOS, and an upload from host memory or a PBO everywhere.
    yuyv_program_2d: GlProgram,
    /// `yuyv_program_2d` plus the int8 XOR-0x80 bias.
    yuyv_int8_program_2d: GlProgram,
    /// Link-time uniform locations for `yuyv_program_2d` and
    /// `yuyv_int8_program_2d`, in that order
    /// (src_size, y_offset, y_scale, c_vr, c_ug, c_vg, c_ub, src_extent).
    yuyv_2d_locs: [[i32; 8]; 2],
    /// Link-time `src_extent` locations for `texture_program` and
    /// `texture_int8_program`, the `sampler2D` source programs
    /// `draw_src_texture` selects between;
    /// see [`Self::texture_src_extent_loc`].
    texture_src_extent_locs: [i32; 2],
    /// Link-time `src_extent` locations for the four external-OES programs,
    /// in the order `[yuv, yuv_int8, planar, planar_int8]`. `-1` on a
    /// platform without external OES, where the programs are `None` and
    /// `glUniform4f(-1, ..)` is a defined no-op.
    external_src_extent_locs: [i32; 4],
    /// Shader: packed RGB -> RGBA8 packing (2D texture source, pass 2).
    packed_rgba8_program_2d: GlProgram,
    /// Shader: packed RGB int8 -> RGBA8 packing with XOR 0x80 (2D texture source, pass 2).
    packed_rgba8_int8_program_2d: GlProgram,
    /// Shader: planar RGB from 2D texture (two-pass NV12→RGBA→PlanarRgb workaround).
    texture_program_planar_2d: GlProgram,
    /// Shader: planar RGB int8 from 2D texture (two-pass NV12→RGBA→PlanarRgb workaround).
    texture_program_planar_int8_2d: GlProgram,
    /// Shader: RGBA8 → R32F-wide F32 NHWC `[H,W,3]` packed render (PBO float path).
    float_f32_nhwc_program: GlProgram,
    /// Shader: RGBA8 → four-elements-per-texel packed NCHW `[C,H,W]` render.
    /// Serves the F16 PBO path and the F16/F32 zero-copy planar paths — the
    /// GLSL is dtype-agnostic, the attachment carries the element width.
    float_f16_nchw_program: GlProgram,
    /// Shader: RGBA8 → four-elements-per-texel packed NHWC `[H,W,3]` render
    /// (F16/F32 zero-copy interleaved path).
    float_nhwc_pack_program: GlProgram,
    /// Shader: RGBA8 → float `Rgba` render, one texel per pixel (F16/F32
    /// zero-copy RGBA path).
    float_rgba_program: GlProgram,
    /// Float render target texture (R32F or RGBA16F), reattached to `convert_fbo`.
    float_render_texture: Texture,
    /// Cached storage spec of `float_render_texture`: `(packed_w, packed_h,
    /// internal_format)`. Mirrors the `proto_tex_dims` pattern: only call
    /// `TexImage2D` (storage spec) when this changes; otherwise reuse the
    /// existing storage (skip the per-frame reallocation on the fixed-size
    /// video path). `(0, 0, 0)` means unallocated.
    float_render_tex_dims: (usize, usize, u32),
    /// Path B shaders: NV12/NV16/NV24 R8 → RGBA8, indexed by
    /// [`NvSampling::program`]: one per sampling, u8 or int8 (XOR 0x80 bias)
    /// output.
    nv_r8_programs: [GlProgram; 6],
    /// Link-time uniform locations + colorimetry-upload skip, per program.
    nv_r8_uniforms: [NvUniformState; 6],
    /// The chroma plane of an NV source as (U, V) texels, for
    /// [`NvSampling::Hardware`]: an upload, or a view of the source's
    /// DMA-BUF.
    nv_uv_texture: Texture,
    /// Chroma-plane imports for `nv_uv_texture`, keyed like `nv_r8_egl_cache`.
    nv_uv_egl_cache: ImportCache<PlatformImport>,
    /// Y2Y NV programs (u8, int8) and their uniforms, where
    /// `GL_EXT_YUV_target` is available ([`NvSampling::HardwareYuv`]).
    nv_y2y_programs: Option<([GlProgram; 2], [NvUniformState; 2])>,
    /// Set once the driver refuses a chroma-plane import, so later resizes
    /// take the shader-filtered program instead of retrying it every frame.
    nv_uv_import_refused: bool,
    /// Texture for the Path-B R8 EGLImage source (TEXTURE_2D, not EXTERNAL_OES).
    nv_r8_texture: Texture,
    /// EGLImage cache for Path-B R8 source imports (keyed like src_egl_cache).
    nv_r8_egl_cache: ImportCache<PlatformImport>,
    /// Which path ran for the most recent NV* convert (instrumentation).
    pub(super) last_nv_convert_path: NvConvertPath,
    /// How the last `nv_r8` draw sampled its source (test observable).
    pub(super) last_nv_sampling: Option<NvSampling>,
    /// Zero-copy feed telemetry (see `ConvertStats`). Plain fields — this
    /// struct lives on the single-threaded GL worker.
    pub(super) convert_stats: super::cache::ConvertStats,
    /// NV import failures already warned about (keyed by buffer identity):
    /// first occurrence warns, repeats log at debug — an import that fails
    /// once fails every frame, and a per-frame warn is log spam.
    nv_import_warned: std::collections::HashSet<u64>,
    /// The PBOs this processor's context allocated; see [`OwnedPbos`].
    /// Shared with the `GLProcessorThreaded` front end, which records each
    /// PBO as it hands it out.
    pub(super) owned_pbos: std::sync::Arc<OwnedPbos>,
    /// Uniform locations per float-path program (see [`FloatQuadLocs`]).
    pub(super) float_quad_locs: std::collections::HashMap<u32, FloatQuadLocs>,
    /// Output mapping applied by `draw_float_quad` for the current convert.
    pub(super) float_norm: FloatNorm,
    /// The mapped int8 programs, with their `q_*` uniform locations, and the
    /// uniforms they hold. Empty until the mapped build links.
    int8_programs: Vec<(u32, [i32; 6])>,
    int_quant: Option<IntQuant>,
    /// Whether the int8 fields hold the mapped build.
    int8_mapped: bool,
    /// The int8 build not in use, once both exist.
    int8_alt: Option<Int8Set>,
    /// Letterbox clear bytes for the current integer convert, when mapped.
    int_pad: Option<[u8; 4]>,
    /// Whether that pad is an output-domain value, which a two-pass route
    /// (pixel pad in pass 1, mapped in pass 2) cannot write.
    int_pad_output: bool,
    /// Static full-screen quad VBOs `(pos, uv)` for the float paths,
    /// uploaded once (`STATIC_DRAW`) — previously `BufferData`-re-uploaded
    /// on every float draw. `0` = not yet created (lazy, on the first
    /// float draw). Deleted in `Drop`.
    pub(super) float_quad_pos_vbo: u32,
    pub(super) float_quad_uv_vbo: u32,
    /// Client preference for NV* path selection (`EDGEFIRST_NV_CONVERT_PATH`).
    nv_path_pref: NvPathPref,
    /// Colorimetry/performance trade-off (see [`crate::ColorimetryMode`]).
    colorimetry_mode: crate::ColorimetryMode,
    /// `true` when `EDGEFIRST_COLORIMETRY` pinned the mode for this
    /// processor's lifetime — `set_colorimetry_mode` then logs and keeps it.
    colorimetry_env_pinned: bool,
    /// How resizing converts resample (see [`crate::Interpolation`]): the
    /// source textures' filter and the NV program family.
    interpolation: crate::Interpolation,
    /// Whether a bilinear NV resize may filter through the texture units
    /// ([`NvSampling::Hardware`]). `EDGEFIRST_GL_NO_NV_HW_FILTER=1` clears
    /// it, leaving the shader-filtered program: a diagnostic switch, and the
    /// way tests reach that program on GPUs that accept every chroma view.
    nv_hw_filter: bool,
    /// When `true`, a convert's terminal `glFinish` is skipped so a batch of
    /// tiles rendered into one shared destination import syncs only once, via a
    /// single `finish_via_fence` at [`flush`](Self::flush). Set for the duration
    /// of a single [`convert_deferred`](Self::convert_deferred) and reset
    /// unconditionally (even on error) so a subsequent standalone `convert` never
    /// silently returns on an unfinished GPU. Always `false` between calls.
    pub(super) defer_finish: bool,
    /// `true` when one or more `convert_deferred` calls have rendered without a
    /// `glFinish` and a [`flush`](Self::flush) (single `finish_via_fence`) is
    /// still owed. Read by the CUDA map path to auto-flush before handing the
    /// device a buffer whose batched render may still be in flight; cleared by
    /// the flush. See [`flush_pending`](Self::flush_pending).
    pub(super) pending_flush: bool,
    /// `true` when a `record_completion` inside a batch queued a device fence
    /// signal without submitting the command buffer, so one submission is
    /// still owed. Paid once by [`flush_pending`](Self::flush_pending),
    /// alongside the batch's single `finish_via_fence`. Always `false` on a
    /// platform with no device fence.
    pub(super) pending_submit: bool,
    pub(super) gl_context: PlatformDisplay,
}

impl Drop for GLProcessorST {
    fn drop(&mut self) {
        // A batch left open owes one device submission. The values it recorded
        // are already published on destinations that outlive this processor,
        // so a consumer may be waiting on one; dropping without submitting
        // would leave that wait unsatisfiable forever. `GLProcessorThreaded`
        // reaches this by joining the worker that owns the processor, which is
        // also the thread that must issue the submission.
        if self.pending_submit {
            Platform::submit_recorded(&self.gl_context);
            self.pending_submit = false;
        }
        unsafe {
            {
                if self.proto_ssbo != 0 {
                    edgefirst_gl::gl::DeleteBuffers(1, &self.proto_ssbo);
                }
                if self.float_quad_pos_vbo != 0 {
                    let ids = [self.float_quad_pos_vbo, self.float_quad_uv_vbo];
                    edgefirst_gl::gl::DeleteBuffers(2, ids.as_ptr());
                }
                if let Some(program) = self.proto_repack_compute_program {
                    edgefirst_gl::gl::DeleteProgram(program);
                }
            }
        }
    }
}

/// Emit a warning the first time a draw operation falls back from the
/// DMA-BUF fast path to the CPU readback fallback. The fast path is silent;
/// the slow path is loud (once) so a regression — for example a tensor with
/// a non-aligned pitch or a missing extension — does not silently degrade
/// performance by 10–20× without anyone noticing.
///
/// The message includes the failing call site, the failing setup function,
/// and the underlying error so the user can map it back to the root cause
/// (commonly Mali's 64-byte pitch alignment requirement). Subsequent
/// fallbacks are demoted to debug-level.
fn warn_slow_path_once(call_site: &str, failing_setup: &str, err: &crate::Error) {
    use std::sync::Once;
    static SLOW_PATH_WARNED: Once = Once::new();
    let mut emitted = false;
    SLOW_PATH_WARNED.call_once(|| {
        log::warn!(
            "{call_site}: GL DMA-BUF fast path unavailable, falling back to CPU \
             readback (10–20× slower). Cause: {failing_setup} returned {err:?}. \
             On Mali Valhall (i.MX 95) this is usually because the destination \
             tensor's row pitch is not 64-byte aligned — see \
             `ImageProcessor::create_image` for automatic alignment. \
             Subsequent fallbacks will be logged at debug level."
        );
        emitted = true;
    });
    if !emitted {
        log::debug!("{call_site}: GL DMA-BUF fast path unavailable ({failing_setup}: {err:?})");
    }
}

/// Reinterpret a `&mut Tensor<i8>` as `&mut Tensor<u8>`.
///
/// # Safety
/// `i8` and `u8` have identical size, alignment, and validity for all bit
/// patterns. `Tensor<T>` stores data behind indirection (DMA-BUF fd, SHM
/// mapping, mmap'd memory, or PBO) — the `T` parameter affects only the
/// typed view returned by `map()`, not the struct layout. The GL backend
/// operates on raw bytes and applies XOR 0x80 bias either in the fragment
/// shader or as a CPU post-process, so the reinterpretation is semantically
/// correct. This transmutation must not be used to access `chroma()` through
/// the returned reference — the chroma `Box<Tensor<T>>` would also be
/// reinterpreted and its drop glue could theoretically differ.
unsafe fn tensor_i8_as_u8_mut(t: &mut Tensor<i8>) -> &mut Tensor<u8> {
    unsafe { &mut *(t as *mut Tensor<i8> as *mut Tensor<u8>) }
}

/// Reinterpret a `&Tensor<i8>` as `&Tensor<u8>`.
///
/// # Safety
/// Same rationale as [`tensor_i8_as_u8_mut`]. The returned reference must not
/// be used to access `chroma()`.
unsafe fn tensor_i8_as_u8(t: &Tensor<i8>) -> &Tensor<u8> {
    unsafe { &*(t as *const Tensor<i8> as *const Tensor<u8>) }
}

/// Extract `&Tensor<u8>` and `PixelFormat` from a `&TensorDyn` source.
/// For I8 sources, reinterprets the bytes as u8.
fn dyn_to_u8_src(src: &TensorDyn) -> crate::Result<(&Tensor<u8>, PixelFormat)> {
    match src.dtype() {
        DType::U8 => {
            let t = src.as_typed::<u8>().expect("dtype checked");
            let fmt = t.format().ok_or(Error::NotAnImage)?;
            Ok((t, fmt))
        }
        DType::I8 => {
            let t = src.as_typed::<i8>().expect("dtype checked");
            let fmt = t.format().ok_or(Error::NotAnImage)?;
            // SAFETY: i8/u8 are layout-identical
            Ok((unsafe { tensor_i8_as_u8(t) }, fmt))
        }
        _ => Err(Error::UnsupportedFormat(format!(
            "GL backend requires u8 or i8 source, got {:?}",
            src.dtype()
        ))),
    }
}

/// Extract `&mut Tensor<u8>`, `PixelFormat`, and `is_int8` from a `&mut TensorDyn` destination.
/// For I8 destinations, reinterprets the bytes as u8 and sets `is_int8 = true`.
fn dyn_to_u8_dst(dst: &mut TensorDyn) -> crate::Result<(&mut Tensor<u8>, PixelFormat, bool)> {
    match dst.dtype() {
        DType::U8 => {
            let t = dst.as_typed_mut::<u8>().expect("dtype checked");
            let fmt = t.format().ok_or(Error::NotAnImage)?;
            Ok((t, fmt, false))
        }
        DType::I8 => {
            let t = dst.as_typed_mut::<i8>().expect("dtype checked");
            let fmt = t.format().ok_or(Error::NotAnImage)?;
            // SAFETY: i8/u8 are layout-identical
            Ok((unsafe { tensor_i8_as_u8_mut(t) }, fmt, true))
        }
        _ => Err(Error::UnsupportedFormat(format!(
            "GL backend requires u8 or i8 destination, got {:?}",
            dst.dtype()
        ))),
    }
}

/// Refuse a `view()`/`batch()` draw destination, or one carrying a
/// `plane_offset`.
///
/// The policy `convert_inner` applies, for the same reason: a sub-region
/// destination is lowered to a band only on the u8/i8 zero-copy path, and only
/// for a convert. Two of the draw's three arms cannot place one at all. The
/// zero-copy arm imports the whole parent surface and
/// `setup_draw_renderbuffer_dma` sets `glViewport(0, 0, w, h)` on it with none
/// of the band lowering `setup_renderbuffer_dma` does, so the frame would land
/// in the parent's first rows; the PBO arm reads at buffer offset 0, which is
/// what `plan_pbo_readback` refuses. The Mem arm could place it -- a view's
/// mapping begins at the view origin and `effective_row_stride` is the
/// parent's pitch, so `read_pixels_into_tensor` spaces the rows correctly --
/// but it is refused with the other two so the draw carries one rule rather
/// than a per-arm one, and because the CPU backend, which writes any
/// sub-region through offset + parent stride, is the fallback for all three.
/// A Mem view destination therefore goes to the CPU backend where GL used to
/// take it.
fn check_draw_dst_placement(dst: &TensorDyn) -> crate::Result<()> {
    let is_view = dst.view_origin().is_some();
    let plane_offset = dst.plane_offset().unwrap_or(0);
    if is_view || plane_offset != 0 {
        return Err(Error::NotSupported(format!(
            "GL mask draw places its frame at the destination surface's \
             origin -- viewport 0,0 on an imported surface, buffer offset 0 \
             in a readback -- so it cannot fill a sub-region destination \
             (view={is_view}, plane_offset={plane_offset}); CPU fallback \
             handles it"
        )));
    }
    Ok(())
}

impl ImageProcessorTrait for GLProcessorST {
    fn convert(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        options: Option<crate::ConvertOptions>,
    ) -> crate::Result<()> {
        self.convert_inner(src, dst, &options.unwrap_or_default())?;
        // Recorded after every convert, deferred (batched) or not — see
        // `GlPlatform::record_completion`. A leaf with a device fence
        // flushes the GL work first so the recorded value covers it even
        // when the terminal `glFinish` is deferred to `flush`.
        //
        // Inside a batch the device's command buffer is left unsubmitted:
        // one submission per tile is exactly the cost `convert_deferred`
        // exists to avoid. `flush_pending` pays the one that is owed.
        let submit = !self.defer_finish;
        if Platform::record_completion(&self.gl_context, dst, submit).is_some() && !submit {
            self.pending_submit = true;
        }
        Ok(())
    }

    fn convert_deferred(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        options: Option<crate::ConvertOptions>,
    ) -> Result<(), crate::Error> {
        // Render without the terminal `glFinish` (gated in `convert_to` by
        // `defer_finish`), leaving a single `finish_via_fence` owed at `flush`.
        // The flag resets unconditionally so a later standalone `convert` always
        // finishes; only a successful deferred render arms `pending_flush`.
        self.defer_finish = true;
        let result = self.convert(src, dst, options);
        self.defer_finish = false;
        if result.is_ok() {
            self.pending_flush = true;
        } else if self.pending_submit {
            // Earlier tiles of this batch may have recorded fence values and
            // left the device submission owed. The caller has no reason to
            // call `flush` after an error, so those values -- already
            // published on their destinations -- would never reach a waiter.
            //
            // Only the submission. `pending_flush` stays owed, as it was
            // before an error could reach here: paying it means
            // `finish_via_fence`, a blocking CPU wait on every platform, and
            // an error return is not the place to start one. This branch is a
            // no-op wherever `record_completion` records nothing, which is
            // every leaf but Windows.
            Platform::submit_recorded(&self.gl_context);
            self.pending_submit = false;
        }
        result
    }

    fn flush(&mut self) -> Result<(), crate::Error> {
        let _span = tracing::trace_span!("image.flush.gl", pending = self.pending_flush).entered();
        self.flush_pending();
        Ok(())
    }

    fn draw_decoded_masks(
        &mut self,
        dst: &mut TensorDyn,
        detect: &[DetectBox],
        segmentation: &[Segmentation],
        overlay: crate::MaskOverlay<'_>,
    ) -> Result<(), crate::Error> {
        check_draw_dst_placement(dst)?;
        let bg = overlay.background.map(|bg| dyn_to_u8_src(bg)).transpose()?;
        // Scoped so the typed borrow of `dst` ends before the completion is
        // recorded on it.
        {
            let (dst_u8, dst_fmt, _is_int8) = dyn_to_u8_dst(dst)?;
            self.draw_decoded_masks_impl(
                dst_u8,
                dst_fmt,
                detect,
                segmentation,
                overlay.opacity,
                bg,
                overlay.color_mode,
            )?;
        }
        // Recorded after the draw as after a convert (see
        // `GlPlatform::record_completion`), so a texture destination carries
        // the fence value covering the drawn frame.
        //
        // `submit` is `true`: every writer of `defer_finish` -- the batch in
        // `convert_deferred`, the fence export in `convert_fenced`, and pass 1
        // of the three two-pass converts -- sets it inside a convert and
        // clears it before returning, so no draw runs under it. When a batch
        // opened by an earlier `convert_deferred` is still unsubmitted, this
        // submission also submits the signals it left queued: they were
        // allocated in order under the device lock, so submitting them early
        // matches what the batch's own `flush` would have done, and
        // `flush_pending`'s later `submit_recorded` is an idempotent
        // `Flush`.
        Platform::record_completion(&self.gl_context, dst, true);
        Ok(())
    }

    fn draw_proto_masks(
        &mut self,
        dst: &mut TensorDyn,
        detect: &[DetectBox],
        proto_data: &ProtoData,
        overlay: crate::MaskOverlay<'_>,
    ) -> crate::Result<()> {
        check_draw_dst_placement(dst)?;
        let bg = overlay.background.map(|bg| dyn_to_u8_src(bg)).transpose()?;
        // Scoped as in `draw_decoded_masks`.
        {
            let (dst_u8, dst_fmt, _is_int8) = dyn_to_u8_dst(dst)?;
            self.draw_proto_masks_impl(
                dst_u8,
                dst_fmt,
                detect,
                proto_data,
                overlay.opacity,
                bg,
                overlay.color_mode,
            )?;
        }
        // Recorded and submitted as in `draw_decoded_masks`.
        Platform::record_completion(&self.gl_context, dst, true);
        Ok(())
    }

    fn set_class_colors(&mut self, colors: &[[u8; 4]]) -> crate::Result<()> {
        if colors.is_empty() {
            return Ok(());
        }
        let colors_f32 = colors
            .iter()
            .map(|c| {
                [
                    c[0] as f32 / 255.0,
                    c[1] as f32 / 255.0,
                    c[2] as f32 / 255.0,
                    c[3] as f32 / 255.0,
                ]
            })
            .take(20)
            .collect::<Vec<[f32; 4]>>();

        self.segmentation_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.instanced_segmentation_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.proto_segmentation_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.proto_segmentation_int8_nearest_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.proto_segmentation_int8_bilinear_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.proto_segmentation_f32_program
            .load_uniform_4fv(c"colors", &colors_f32)?;
        self.color_program
            .load_uniform_4fv(c"colors", &colors_f32)?;

        Ok(())
    }

    fn set_box_line_width(&mut self, width: u32) -> crate::Result<()> {
        crate::check_box_line_width(width)?;
        self.box_line_width = width as f32;
        Ok(())
    }
}

/// Whether `EDGEFIRST_ALLOW_SOFTWARE_GL=1` is set, opting in to running the GL
/// backend on a software renderer (Mesa llvmpipe/softpipe/swrast).
///
/// Off by default and in production; the CI coverage lane sets it so the GL
/// render path executes on llvmpipe where no GPU exists.
fn software_gl_override_enabled() -> bool {
    std::env::var_os("EDGEFIRST_ALLOW_SOFTWARE_GL").is_some_and(|v| v == "1")
}

/// Per-cache import-cache capacity when neither the caller nor the
/// environment asks for one. See
/// [`ImageProcessorConfig::egl_cache_capacity`](crate::ImageProcessorConfig::egl_cache_capacity)
/// for what the number bounds, and `with_cache_capacity` for why it is 16.
const DEFAULT_EGL_CACHE_CAPACITY: usize = 16;

/// Resolve the import-cache capacity: config > environment > default.
///
/// Pure so the precedence is unit-testable without a GL context or a mutated
/// process environment — the caller passes the raw
/// `EDGEFIRST_EGL_CACHE_CAPACITY` value. Config wins over the environment so
/// a stray env var in a deployment cannot silently override an embedder that
/// measured its own pool. Zero and unparseable values are rejected at both
/// levels and fall through, since a zero-capacity cache would evict every
/// entry it inserted.
fn resolve_egl_cache_capacity(config: Option<usize>, env: Option<&str>) -> usize {
    config
        .filter(|&c| c > 0)
        .or_else(|| env.and_then(|v| v.parse::<usize>().ok()).filter(|&c| c > 0))
        .unwrap_or(DEFAULT_EGL_CACHE_CAPACITY)
}

/// Decide whether to reject an initialized GL context for being a software
/// renderer. Pure so it is unit-testable without touching the environment or a
/// real GL context: reject only when the renderer is software AND the override
/// is not enabled.
fn should_reject_software_gl(is_software_renderer: bool, override_enabled: bool) -> bool {
    is_software_renderer && !override_enabled
}

fn parse_nv_path_pref() -> NvPathPref {
    match std::env::var("EDGEFIRST_NV_CONVERT_PATH") {
        Ok(v) => match v.to_ascii_lowercase().as_str() {
            "sampler" | "external" | "a" => NvPathPref::ForceSampler,
            "shader" | "r8" | "b" => NvPathPref::ForceShader,
            "auto" | "" => NvPathPref::Auto,
            other => {
                log::warn!(
                    "EDGEFIRST_NV_CONVERT_PATH={other:?} not recognised \
                     (expected sampler|shader|auto), using auto"
                );
                NvPathPref::Auto
            }
        },
        Err(_) => NvPathPref::Auto,
    }
}

fn parse_colorimetry_env() -> Option<crate::ColorimetryMode> {
    match std::env::var("EDGEFIRST_COLORIMETRY") {
        Ok(v) => match v.to_ascii_lowercase().as_str() {
            "exact" => Some(crate::ColorimetryMode::Exact),
            "fast" => Some(crate::ColorimetryMode::Fast),
            "" => None,
            other => {
                log::warn!(
                    "EDGEFIRST_COLORIMETRY={other:?} not recognised \
                     (expected fast|exact), ignoring"
                );
                None
            }
        },
        Err(_) => None,
    }
}

fn apply_forced_transfer(backend: &mut TransferBackend) {
    let Ok(val) = std::env::var("EDGEFIRST_FORCE_TRANSFER") else {
        return;
    };
    let forced = match val.to_ascii_lowercase().as_str() {
        "dmabuf" | "dma" => Some(TransferBackend::DmaBuf),
        "pbo" => Some(TransferBackend::Pbo),
        "sync" => Some(TransferBackend::Sync),
        other => {
            log::warn!(
                "EDGEFIRST_FORCE_TRANSFER={other:?} not recognised \
                 (expected dmabuf|pbo|sync), ignoring"
            );
            None
        }
    };
    if let Some(forced) = forced {
        log::info!(
            "EDGEFIRST_FORCE_TRANSFER override: {:?} → {forced:?}",
            backend
        );
        *backend = forced;
    }
}

/// GL_RENDERER-derived driver traits that feed per-driver policy.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
struct RendererTraits {
    /// Verisilicon/Vivante core — GPU-hang workarounds + Full serialization.
    vivante: bool,
    /// Arm Mali (i.MX 95 G310 and kin). Its DMA-BUF import silently samples
    /// zeros when `EGL_DMA_BUF_PLANE0_OFFSET_EXT` is not 64-byte aligned —
    /// the import succeeds and no EGL error follows — so a source at such an
    /// offset is declined and uploaded instead (issue #165). The trait
    /// remains; the offset it is asked about is now the one the import will
    /// present, so a packed source folded onto an aligned base keeps the
    /// zero copy and only what the fold could not move declines (issue
    /// #170).
    mali: bool,
    /// Software rasterizer (llvmpipe/softpipe/swrast) — rejected unless the
    /// coverage-lane override is set.
    software: bool,
    /// Virtualized/paravirtual GPU — concurrent GL across contexts
    /// mis-renders (observed: Apple Paravirtual device on macOS CI runners);
    /// gets the Full serialization policy.
    virtual_gpu: bool,
    /// ANGLE — the GLES-over-Metal/D3D translation layer, the only GL
    /// implementation on macOS. Concurrent GL across contexts loses
    /// per-draw state there; gets the Full serialization policy. See
    /// [`requires_full_serialization`].
    angle: bool,
    /// Qualcomm Adreno on the proprietary KGSL stack (IQ-9075 / Adreno 663).
    /// One `eglDestroyImage` unmaps the import's driver mapping twice, which
    /// destroys any mapping another thread created in between, so it gets the
    /// Full serialization policy (see `edgefirst_tensor::pin::
    /// with_cpu_mappings_excluded` for the CPU-side half). Its DMA-BUF import
    /// also silently misplaces a `EGL_DMA_BUF_PLANE0_OFFSET_EXT` that is not
    /// 64-byte aligned — for destinations as well as sources — and samples
    /// garbage from an NV12 whose chroma lives in a second DMA-BUF.
    adreno: bool,
}

/// Whether this driver needs per-message global serialization
/// (`SerializationPolicy::Full`) rather than the parallel `LifecycleOnly`
/// policy. Pure so the policy is unit-testable without a GL context, like
/// [`should_reject_software_gl`].
///
/// The `LifecycleOnly` default — several `ImageProcessor`s running GL work
/// genuinely in parallel, each on its own thread and context — was validated
/// by the P0 spike (2026-06) on **Mali G310, V3D and Tegra/Orin only**. Two
/// driver families are known to break it:
///
/// * **Vivante/galcore** (i.MX 8M Plus): not thread-safe for concurrent
///   EGL/GL at all; concurrent access corrupts driver-internal state.
/// * **ANGLE**, including on a real (non-paravirtual) Apple GPU: a deferred
///   draw does not reliably execute with the per-draw state its own
///   processor programmed while another context is active. Measured on
///   macOS 27 / ANGLE Metal / Apple M2 Max: a tiled convert's source-region
///   transform is silently reset to identity — or the draw lands nothing at
///   all — for ~0.3% of tiles at 8 concurrent processors, scaling with
///   concurrency and never occurring at 1. `EDGEFIRST_GL_SERIALIZE=full`
///   drives it to zero, which is what this default now selects.
///
///   ANGLE was previously in the policy's "everywhere else" bucket by
///   omission: it was never in the P0 validation set, only assumed to
///   behave like the drivers that were. Paravirtual Metal was already
///   caught by `virtual_gpu`; the underlying defect is not specific to
///   virtualization. Silently wrong pixels is the worse failure mode, so
///   correctness is the default and `EDGEFIRST_GL_SERIALIZE=lifecycle`
///   remains available to re-measure once ANGLE is genuinely validated.
/// * **Adreno** (proprietary KGSL driver): one `eglDestroyImage` unmaps the
///   import's driver mapping twice, so a mapping another context's thread
///   creates in between is destroyed and its next access faults. Measured on
///   IQ-9075 / Adreno 663: 9/30 runs of four concurrent processors SIGSEGV
///   under `LifecycleOnly`, 0/30 under `Full`.
///
/// Serialization costs throughput only when a process runs several
/// `ImageProcessor`s concurrently; a single-processor pipeline is unaffected.
fn requires_full_serialization(t: RendererTraits) -> bool {
    t.vivante || t.virtual_gpu || t.angle || t.adreno
}

/// Capability probe results from a freshly-current GL context
/// (`gl_check_support`): extension-derived feature flags plus the
/// GL_RENDERER-derived driver traits.
struct GlSupport {
    has_float_linear: bool,
    /// `GL_EXT_YUV_target` on a platform with external-OES imports: the Y2Y
    /// NV programs can sample raw, filtered YUV from an NV12 import.
    has_yuv_target: bool,
    has_bgra: bool,
    renderer: RendererTraits,
    supports_f32_color: bool,
    supports_f16_color: bool,
}

/// Whether `glReadPixels(format, UNSIGNED_BYTE)` is accepted on the bound
/// read framebuffer: `RGBA` always is; anything else only when it is the
/// implementation-defined pair (ES 3.0 § 4.3.2). Shared by the Mem and PBO
/// readback paths.
///
/// # Safety
/// Must run on the GL thread with a complete read framebuffer bound.
unsafe fn direct_read_supported(format: u32) -> bool {
    if format == edgefirst_gl::gl::RGBA {
        return true;
    }
    let mut impl_fmt = 0i32;
    let mut impl_type = 0i32;
    // SAFETY: two GetIntegerv queries on a current context.
    unsafe {
        edgefirst_gl::gl::GetIntegerv(
            edgefirst_gl::gl::IMPLEMENTATION_COLOR_READ_FORMAT,
            &mut impl_fmt,
        );
        edgefirst_gl::gl::GetIntegerv(
            edgefirst_gl::gl::IMPLEMENTATION_COLOR_READ_TYPE,
            &mut impl_type,
        );
    }
    impl_fmt as u32 == format && impl_type as u32 == edgefirst_gl::gl::UNSIGNED_BYTE
}

/// Bytes `glReadPixels` writes per pixel for a pack format.
fn pack_channels(format: u32) -> usize {
    match format {
        edgefirst_gl::gl::RGB => 3,
        edgefirst_gl::gl::RED => 1,
        _ => 4,
    }
}

/// Re-space the `rows` tightly packed rows of `tight_row` bytes at the head of
/// `buf` so that row `y` starts at `y * stride`.
///
/// `glReadPixels` packs its rows at `width * channels` bytes whatever pitch the
/// destination has, and `GL_PACK_ROW_LENGTH` counts pixels, so it cannot
/// express a byte pitch that the pixel size does not divide -- a D3D11 staging
/// pitch is 128-byte aligned on NVIDIA and 3 divides no such number, so an RGB
/// destination needs the rows moved after the read.
///
/// Rows move back to front: `stride > tight_row` puts every row's destination
/// after its source, so no row is overwritten before it has moved. `buf` must
/// hold `(rows - 1) * stride + tight_row` bytes, which the caller checks with
/// [`padded_readback_bytes`] before reading.
fn spread_rows(buf: &mut [u8], rows: usize, tight_row: usize, stride: usize) {
    if stride <= tight_row || rows < 2 || tight_row == 0 {
        return;
    }
    for y in (1..rows).rev() {
        buf.copy_within(y * tight_row..y * tight_row + tight_row, y * stride);
    }
}

/// Bytes a destination must map to hold `rows` rows of `tight_row` bytes at
/// `stride`, or `None` when the destination is tight and the read lands as-is.
fn padded_readback_bytes(rows: usize, tight_row: usize, stride: usize) -> Option<usize> {
    if stride <= tight_row || rows == 0 {
        return None;
    }
    Some((rows - 1) * stride + tight_row)
}

/// `GL_PACK_ROW_LENGTH` that lays rows out at a `stride`-byte pitch, or `None`
/// when the pitch is tight (GL already lands the rows there) or is not a whole
/// number of `pixel_bytes`-byte pixels, which that pixel-counting state cannot
/// express -- a 128-byte aligned pitch is never a multiple of 3, so an RGB
/// destination's rows are read tight and moved afterwards instead.
///
/// `pixel_bytes` is what one pixel of the *pack format* occupies: the channel
/// count for the u8 readback, and the texel size for the float one (4 for
/// `RED`/`FLOAT`, 8 for `RGBA`/`HALF_FLOAT`).
///
/// The pixel count converts back to the byte pitch only because
/// `PACK_ALIGNMENT` is 1 (set once in `new`): GL spaces rows at
/// `alignment * ceil(pixel_bytes * PACK_ROW_LENGTH / alignment)`, so at the
/// default alignment of 4 an odd pitch would be rounded up and the
/// destination's rows would land somewhere else again.
fn pack_row_length(tight_row: usize, stride: usize, pixel_bytes: usize) -> Option<i32> {
    if stride <= tight_row || pixel_bytes == 0 || !stride.is_multiple_of(pixel_bytes) {
        return None;
    }
    i32::try_from(stride / pixel_bytes).ok()
}

/// `GL_UNPACK_ROW_LENGTH` for a source whose rows sit `stride` bytes apart, or
/// `0` for a tight source (GL's own "rows are `width` pixels" default).
///
/// The upload counterpart of [`pack_row_length`], and it refuses where that
/// one falls back: a readback whose pitch is not a whole number of pixels can
/// be read tight and spread afterwards, but an *upload* has no equivalent --
/// GL would have to read pixels that are not there. Truncating the division
/// instead is silent corruption: `UNPACK_ROW_LENGTH` counts PIXELS, so a
/// 64-byte-aligned RGB pitch of 1024 truncates to 341 and GL advances 1023
/// bytes per row, shearing the image by one byte per row with the right shape,
/// the right byte count, and no error. Refuse the source instead and let the
/// caller decline to the CPU backend -- what the CPU upload path in
/// `draw_src_texture` already does with the same wording.
///
/// `pixel_bytes` is what one pixel of the *unpack format* occupies (the
/// channel count for the u8 paths, a fixed 4 for the RGBA-only float PBO arm).
/// `what` names the format in the refusal.
///
/// Reads back to the byte pitch only because `UNPACK_ALIGNMENT` is 1 (set once
/// in `new`), exactly as [`pack_row_length`] documents for the pack side.
fn unpack_row_length(
    stride: Option<usize>,
    tight_px: usize,
    pixel_bytes: usize,
    what: &str,
) -> Result<i32, Error> {
    let Some(stride) = stride else {
        return Ok(0);
    };
    if pixel_bytes == 0 || !stride.is_multiple_of(pixel_bytes) {
        return Err(Error::NotSupported(format!(
            "source row pitch {stride} B is not a whole number of \
             {what} pixels ({pixel_bytes} B/px); upload would \
             shear rows"
        )));
    }
    let px = stride / pixel_bytes;
    if px == tight_px {
        return Ok(0);
    }
    i32::try_from(px).map_err(|_| {
        Error::NotSupported(format!(
            "source row pitch {stride} B is {px} {what} pixels, past what \
             GL_UNPACK_ROW_LENGTH can express"
        ))
    })
}

/// The PBOs one GL context allocated, recorded by the address of their
/// `PboOpsVtable`.
///
/// GL buffer names belong to a context, and HAL's contexts share nothing, so
/// a PBO allocated by another processor -- or wrapped from outside with
/// `ef_tensor_wrap_pbo` -- names a different buffer here, or none. Neither
/// the buffer name nor the `BufferIdentity` can tell them apart: a PBO's
/// identity is derived from the name alone, and under the dynamic tensor
/// backend every handle, including each `view()`, derives a fresh one. The
/// vtable lives in the allocation's shared handle, so every view of it
/// reports the same address on both backends. Each record also holds a
/// `Weak` of the PBO's own ops, which only that allocation holds, so an
/// address is matched only while the allocation that owned it is alive and
/// cannot have been reused.
#[derive(Default)]
pub(crate) struct OwnedPbos(std::sync::Mutex<Vec<OwnedPbo>>);

struct OwnedPbo {
    vtable: usize,
    ops: std::sync::Weak<dyn edgefirst_tensor::PboOps>,
}

impl std::fmt::Debug for OwnedPbos {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let owned = self.0.lock().unwrap_or_else(|e| e.into_inner());
        f.debug_tuple("OwnedPbos").field(&owned.len()).finish()
    }
}

impl OwnedPbos {
    /// Record a PBO this context allocated. `ops` must be the operations
    /// created for that one allocation.
    pub(crate) fn insert(
        &self,
        vtable: Option<*const std::ffi::c_void>,
        ops: &std::sync::Arc<dyn edgefirst_tensor::PboOps>,
    ) {
        let Some(vtable) = vtable else { return };
        let mut owned = self.0.lock().unwrap_or_else(|e| e.into_inner());
        owned.retain(|p| p.ops.strong_count() > 0);
        owned.push(OwnedPbo {
            vtable: vtable as usize,
            ops: std::sync::Arc::downgrade(ops),
        });
    }

    fn contains(&self, vtable: Option<*const std::ffi::c_void>) -> bool {
        let Some(vtable) = vtable else { return false };
        let owned = self.0.lock().unwrap_or_else(|e| e.into_inner());
        owned
            .iter()
            .any(|p| p.vtable == vtable as usize && p.ops.strong_count() > 0)
    }
}

/// A source's pixels opened for a texture upload: its PBO when this context
/// owns it, otherwise a CPU map held until the upload has read it.
///
/// An owned PBO is read through `PIXEL_UNPACK_BUFFER`, a copy the GPU makes,
/// so the buffer is never mapped for it. Any other PBO is mapped through its
/// own operations, which reach the context that owns it (see
/// [`OwnedPbos`]). A `view()` of a PBO shares its parent's
/// buffer id and names its own window with `plane_offset` (the parent's
/// pitch arrives through `UNPACK_ROW_LENGTH`), so the offset is what makes
/// each view read its own pixels rather than the parent's top-left corner.
enum SrcPixels<'a> {
    Pbo { buffer_id: u32, offset: usize },
    Mapped(edgefirst_tensor::HostView<'a, u8>),
}

impl SrcPixels<'_> {
    fn open(src: &Tensor<u8>, owned: &OwnedPbos) -> Result<Self, Error> {
        match src.pbo_id() {
            Some(buffer_id) if owned.contains(src.pbo_vtable_ptr()) => {
                // GL refuses to read a buffer that is mapped.
                if src.pbo_is_mapped() == Some(true) {
                    return Err(Error::OpenGl(
                        "Cannot convert from a mapped PBO tensor".to_string(),
                    ));
                }
                Ok(Self::Pbo {
                    buffer_id,
                    offset: src.plane_offset().unwrap_or(0),
                })
            }
            _ => Ok(Self::Mapped(src.map_read()?)),
        }
    }

    fn source(&self) -> UploadSource<'_> {
        match self {
            Self::Pbo { buffer_id, offset } => UploadSource::Pbo {
                buffer_id: *buffer_id,
                offset: *offset,
            },
            Self::Mapped(map) => UploadSource::Bytes(map.as_slice()),
        }
    }

    /// Count this source feed and name it on the convert's span.
    fn record(&self, stats: &mut super::cache::ConvertStats, span: &tracing::Span) {
        match self {
            Self::Pbo { .. } => {
                stats.src_pbo_uploads += 1;
                span.record("src_feed", "pbo");
            }
            Self::Mapped(_) => {
                stats.src_uploads += 1;
                span.record("src_feed", "upload");
            }
        }
    }
}

/// What a PBO readback has to know about its destination before it can issue
/// the `glReadPixels`: the pitch to place the rows at, the bytes they will
/// occupy, and the `GL_PACK_ROW_LENGTH` that expresses the pitch -- `None`
/// when the rows have to be read tight and moved afterwards.
///
/// Produced by [`plan_pbo_readback`] and shared by the u8 and float PBO
/// readbacks, which differ in pack format and in what they do around the
/// read, not in how the two pitches reconcile.
struct PboReadbackLayout {
    /// The destination's row pitch in bytes.
    stride: usize,
    /// Bytes of one row that are actually pixels.
    tight_row: usize,
    /// Bytes the `rows` rows occupy at `stride`, which the PBO must hold.
    needed: usize,
    /// `GL_PACK_ROW_LENGTH` in pixels, or `None` for read-tight-and-spread.
    row_length: Option<i32>,
}

/// Reconcile a PBO destination's declared pitch with the tight rows
/// `glReadPixels` produces, or refuse the destination.
///
/// Refused, rather than silently mis-copied:
///
/// * A pitch shorter than one row cannot describe the destination, and
///   clamping it up would write rows the caller never asked for -- the same
///   refusal the source path makes of a pitch that is not a whole number of
///   pixels.
/// * A `view()`/`batch()` destination, or one carrying a `plane_offset`. Both
///   readbacks write at *buffer offset 0* and bound themselves on the whole
///   allocation, so a sub-region destination would be filled from the top of
///   its parent's buffer -- a wrong copy with no error. Both callers decline
///   such a destination before reaching here (`convert_inner` for a convert,
///   `check_draw_dst_placement` for an overlay draw); this is the guard at the
///   place that actually holds the offset-0 assumption, so it holds whatever
///   a future caller does.
/// * A PBO too small for the rows at that pitch.
fn plan_pbo_readback(
    stride: usize,
    is_view: bool,
    plane_offset: usize,
    capacity: usize,
    width: usize,
    rows: usize,
    pixel_bytes: usize,
) -> crate::Result<PboReadbackLayout> {
    let tight_row = width * pixel_bytes;
    if stride < tight_row {
        return Err(crate::Error::OpenGl(format!(
            "destination row pitch is {stride} B but one {width}-pixel row \
             of this readback format is {tight_row} B"
        )));
    }
    if is_view || plane_offset != 0 {
        return Err(crate::Error::NotSupported(format!(
            "GL PBO readback writes at buffer offset 0, so it cannot fill a \
             sub-region destination (view={is_view}, plane_offset={plane_offset}); \
             CPU fallback handles it"
        )));
    }
    let needed = padded_readback_bytes(rows, tight_row, stride).unwrap_or(rows * tight_row);
    if capacity < needed {
        return Err(crate::Error::OpenGl(format!(
            "PBO destination is {capacity} B but the readback needs {needed} B \
             at a {stride} B pitch"
        )));
    }
    Ok(PboReadbackLayout {
        stride,
        tight_row,
        needed,
        row_length: pack_row_length(tight_row, stride, pixel_bytes),
    })
}

/// Map the first `len` bytes of PBO `buffer_id` with `access` bits for the
/// duration of `f`, then unmap and unbind.
///
/// The one way the GL thread may touch a PBO's bytes: `Tensor::map` on a PBO
/// tensor sends a message to this same thread and would deadlock.
///
/// # Safety
///
/// Must run on the GL thread while nothing else holds `buffer_id` mapped, and
/// `len` must not exceed the buffer's allocation.
unsafe fn with_mapped_pbo(
    buffer_id: u32,
    len: usize,
    access: u32,
    what: &str,
    f: impl FnOnce(&mut [u8]),
) -> crate::Result<()> {
    // SAFETY: the caller's contract -- GL thread, `buffer_id` not already
    // mapped, `len` within the allocation -- so `MapBufferRange` returns a
    // pointer to `len` writable bytes, valid until the `UnmapBuffer` below,
    // and `f` is the only holder of the slice for that span.
    let ok = unsafe {
        edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER, buffer_id);
        let ptr = edgefirst_gl::gl::MapBufferRange(
            edgefirst_gl::gl::PIXEL_PACK_BUFFER,
            0,
            len as isize,
            access,
        );
        if ptr.is_null() {
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER, 0);
            return Err(crate::Error::OpenGl(format!(
                "glMapBufferRange returned null for the {what}"
            )));
        }
        f(std::slice::from_raw_parts_mut(ptr as *mut u8, len));
        let ok = edgefirst_gl::gl::UnmapBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER);
        edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER, 0);
        ok
    };
    // GL_FALSE from glUnmapBuffer means the contents were lost while mapped
    // (a display-mode change, or the driver evicting the memory). It raises no
    // GL error, so `check_gl_error` would report success on a destination full
    // of garbage. Same verdict `threaded.rs`'s `handle_pbo_unmap` returns.
    if ok == edgefirst_gl::gl::FALSE {
        return Err(crate::Error::OpenGl(format!(
            "PBO data was corrupted during mapping ({what})"
        )));
    }
    Ok(())
}

/// `glReadPixels` a `w`x`h` RGBA frame into `scratch`, growing it to
/// `w * h * 4` bytes first.
///
/// The fallback both readbacks share where the destination's pack format is
/// not an accepted one: the frame arrives as RGBA and the caller repacks its
/// leading channels. Split out so the PBO path reaches the read without
/// passing an empty `out` to [`read_pixels_into`], which would re-probe
/// `direct_read_supported` and, if the two probes ever disagreed, read through
/// an empty slice's pointer.
///
/// `scratch` keeps its high-water mark, so the path costs no per-call
/// allocation after the first read of a given size; the caller must bound its
/// own use of it to `w * h * 4`.
///
/// # Safety
/// Must run on the GL thread with a complete read framebuffer bound,
/// `ReadBuffer` selected and no `PIXEL_PACK_BUFFER` bound.
unsafe fn read_pixels_rgba_scratch(w: usize, h: usize, scratch: &mut Vec<u8>) {
    if scratch.len() < w * h * 4 {
        scratch.resize(w * h * 4, 0);
    }
    // SAFETY: the caller's contract, and `scratch` now holds `w * h * 4`
    // bytes, which is what an RGBA/UNSIGNED_BYTE read of this frame writes at
    // `PACK_ALIGNMENT` 1.
    unsafe {
        edgefirst_gl::gl::ReadPixels(
            0,
            0,
            w as i32,
            h as i32,
            edgefirst_gl::gl::RGBA,
            edgefirst_gl::gl::UNSIGNED_BYTE,
            scratch.as_mut_ptr() as *mut c_void,
        );
    }
}

/// `glReadPixels` the bound read-framebuffer into `out`, honoring the ES 3
/// guarantee: only `RGBA`/`UNSIGNED_BYTE` plus ONE implementation-defined
/// pair are accepted. Mesa and the embedded drivers take `RGB`/`RED`
/// directly; ANGLE/Metal (and V3D) reject them with `GL_INVALID_OPERATION`.
/// When the direct read is unsupported, read an RGBA scratch and repack the
/// leading channels (the FBO attachment has the destination's channel
/// layout, so RGB keeps rgb, RED keeps r).
///
/// Plain `glReadPixels`, NOT `glReadnPixels`: the robust variant is an
/// ES 3.2 entry point and ANGLE/Metal (ES 3.0 max) rejects it at
/// validation. Reads are tightly packed (`PACK_ALIGNMENT=1` at init), so
/// the bounds the robust variant checked hold by construction as long as
/// the caller sized `out`.
///
/// `scratch` is the caller's reusable staging buffer
/// (`GLProcessorST::readback_scratch`) — grown on demand and kept at its
/// high-water mark, so neither indirect route costs a per-call allocation
/// after the first read of a given size.
///
/// `stride` is how far apart `out`'s rows sit, and **only the first
/// `w * channels` bytes of each are ever written**. The bytes between one
/// row's end and the next row's start belong to somebody else whenever `out`
/// is a `view()`'s window into a wider parent — they are the sibling columns
/// to the right of the tile — so a read that packs `h` tight rows at the head
/// of `out` and re-spaces them afterwards leaves its own tail sitting in
/// them. It did: a 320-wide tile read into a 512-wide parent overwrote 192
/// parent pixels on each of the first 150 rows (issue #177). Where the pitch
/// is a whole number of pixels GL lays the rows out itself through
/// `GL_PACK_ROW_LENGTH` — which is what the PBO readback has always done —
/// and where it is not (a 3-byte pixel never divides a 64- or 128-byte
/// aligned pitch) the frame is read tight into `scratch` and the rows are
/// copied out one at a time.
///
/// The pixel count converts back to the byte pitch only because
/// `PACK_ALIGNMENT` is 1 (set once in `new`) — see [`pack_row_length`].
///
/// # Safety
/// Must run on the GL thread with a complete read framebuffer bound and
/// `ReadBuffer` selected, and `out` must hold `(h - 1) * stride + w *
/// channels` bytes for the pack format (nothing here can check it — the read
/// goes through a raw pointer).
unsafe fn read_pixels_into(
    w: usize,
    h: usize,
    format: u32,
    scratch: &mut Vec<u8>,
    out: &mut [u8],
    stride: usize,
) {
    let channels = pack_channels(format);
    let tight_row = w * channels;
    unsafe {
        if direct_read_supported(format) {
            if stride == tight_row {
                edgefirst_gl::gl::ReadPixels(
                    0,
                    0,
                    w as i32,
                    h as i32,
                    format,
                    edgefirst_gl::gl::UNSIGNED_BYTE,
                    out.as_mut_ptr() as *mut c_void,
                );
                return;
            }
            if let Some(px) = pack_row_length(tight_row, stride, channels) {
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::PACK_ROW_LENGTH, px);
                edgefirst_gl::gl::ReadPixels(
                    0,
                    0,
                    w as i32,
                    h as i32,
                    format,
                    edgefirst_gl::gl::UNSIGNED_BYTE,
                    out.as_mut_ptr() as *mut c_void,
                );
                // Back to GL's own "rows are `width` pixels" default, so the
                // next read of a tight destination is unaffected.
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::PACK_ROW_LENGTH, 0);
                return;
            }
            // A pitch `GL_PACK_ROW_LENGTH` cannot express. The scratch is
            // otherwise unused on this branch, so the tight frame lands there
            // and each row is copied to its place.
            if scratch.len() < h * tight_row {
                scratch.resize(h * tight_row, 0);
            }
            edgefirst_gl::gl::ReadPixels(
                0,
                0,
                w as i32,
                h as i32,
                format,
                edgefirst_gl::gl::UNSIGNED_BYTE,
                scratch.as_mut_ptr() as *mut c_void,
            );
            for y in 0..h {
                out[y * stride..y * stride + tight_row]
                    .copy_from_slice(&scratch[y * tight_row..y * tight_row + tight_row]);
            }
            return;
        }
        read_pixels_rgba_scratch(w, h, scratch);
        // Row by row, at the destination's pitch. The scratch keeps its
        // high-water mark from earlier, larger reads, so each row is taken
        // from its own `w`-pixel window rather than walked continuously.
        let rgba = scratch.as_chunks::<4>().0;
        for y in 0..h {
            for (px, dst_px) in rgba[y * w..]
                .iter()
                .take(w)
                .zip(out[y * stride..y * stride + tight_row].chunks_exact_mut(channels))
            {
                dst_px.copy_from_slice(&px[..channels]);
            }
        }
    }
}

/// Classify a GL_RENDERER string into driver-policy traits. Pure —
/// unit-testable without a GL context.
fn classify_renderer(renderer: &str) -> RendererTraits {
    let lower = renderer.to_ascii_lowercase();
    RendererTraits {
        vivante: lower.contains("vivante") || lower.contains("gc7000") || lower.contains("galcore"),
        mali: lower.contains("mali"),
        software: lower.contains("llvmpipe")
            || lower.contains("softpipe")
            || lower.contains("swrast")
            || lower.contains("software rasterizer")
            // D3D11 WARP (ANGLE on Windows without a GPU, e.g. CI runners).
            || lower.contains("basic render driver"),
        virtual_gpu: lower.contains("paravirtual") || lower.contains("virtio"),
        angle: lower.contains("angle"),
        adreno: lower.contains("adreno"),
    }
}

/// The plane-offset alignment Mali needs from a DMA-BUF **source** import.
///
/// Measured on i.MX 95 (issue #165): offsets 32 and 2080 sample zeros with no
/// EGL error at all; 64, 256 and 2048 sample correctly, and offset 0 (the
/// whole image, not a window) is the control. Two data points bracket the rule
/// rather than pin it — the true requirement is somewhere in `(32, 2048]` — so
/// 64 is the tightest value consistent with the measurements rather than a
/// documented driver constant.
///
/// Sources only, and deliberately: this is a rule about a driver that fails
/// SILENTLY, which nothing downstream can detect, so it has to be predicted.
/// Vivante refuses a *destination* at an unaligned offset the opposite way —
/// `eglCreateImage` returns `EGL_BAD_ACCESS`, measured at offset 2080 against
/// 2048 rendering correctly — and a refusal that loud needs no prediction: the
/// destination arms fall back to the mapped-texture readback when the import
/// fails, whatever the driver and whatever its reason (issue #175).
pub(super) const DMA_IMPORT_OFFSET_ALIGN: usize = 64;

/// Whether `plane_offset` is one of the offsets no measured embedded driver
/// imports correctly. Pure, so the per-driver rules below are unit-testable
/// without a GL context, like [`classify_renderer`].
fn unaligned_import_offset(plane_offset: usize) -> bool {
    !plane_offset.is_multiple_of(DMA_IMPORT_OFFSET_ALIGN)
}

/// Whether a source import at `plane_offset` would be silently misread on a
/// driver that misplaces unaligned offsets: Mali samples zeros,
/// Adreno samples from the wrong base. `misplaces` is
/// [`GLProcessorST::misplaces_unaligned_offsets`].
///
/// Checks ONE plane's offset. Every plane the import passes to EGL has to be
/// checked by its caller: a two-plane NV12 import hands EGL a plane-1 offset
/// of its own, which can be unaligned while plane 0 is aligned — see
/// [`nv12_plane1_offset`].
///
/// Asked of the offset the import will PRESENT, which for a source is
/// [`source_import_plane0_offset`] rather than the tensor's own: a rebased
/// source imports at an aligned base and is not declined, an unrebased one
/// still carries its unaligned offset and is (issue #170).
fn rejects_unaligned_import_offset(misplaces: bool, plane_offset: usize) -> bool {
    misplaces && unaligned_import_offset(plane_offset)
}

/// The plane-0 offset a SOURCE import of `img` will present to EGL.
///
/// Not `img.plane_offset()`: since issue #170 a source at an unaligned
/// offset may import from the aligned base below it with the remainder
/// folded into the sampling rectangle, and it is the base, not the tensor's
/// own offset, that reaches `EGL_DMA_BUF_PLANE0_OFFSET_EXT`. Asking the
/// tensor would decline a rebased source for nothing AND pass an unrebased
/// one that comes back black, so the answer comes from the same function the
/// import is built from — `dma_import::resolve_source_plane0`, the single
/// source of truth.
///
/// Off Linux there is no DMA-BUF import to rebase, so the tensor's own
/// offset is the answer; no non-Linux backend reports a Mali renderer
/// anyway, which is the only thing that consults this.
fn source_import_plane0_offset(img: &Tensor<u8>, img_fmt: PixelFormat) -> usize {
    #[cfg(target_os = "linux")]
    {
        super::dma_import::resolved_source_plane0_offset(img, img_fmt)
    }
    #[cfg(not(target_os = "linux"))]
    {
        let _ = img_fmt;
        img.plane_offset().unwrap_or(0)
    }
}

/// The byte offset a destination import bases at **on the route that collapses
/// a view to its parent** — `bind_dst`'s `get_or_create_egl_image(Dst)`.
///
/// The engine has two zero-copy destination import routes and they treat a
/// `view()` differently, so [`GlPlatform::dst_import_places`] — the one
/// destination question that must be answered BEFORE the import, because the
/// import it guards succeeds and places the buffer wrongly — has to know which
/// route it is guarding:
///
/// * **`bind_dst` → `get_or_create_egl_image(CacheKind::Dst)` →
///   `Platform::import_buffer(.., for_dst = true)`.** A fresh `view()`/`batch()`
///   destination imports its PARENT and places the tile with `glViewport`, so
///   the import bases at 0 however far into the buffer the view's own bytes
///   start: `DmaImportAttrs::from_tensor` (`dma_import.rs` ~`:202`) and
///   `BufferImportKey::from_tensor` (`cache.rs` ~`:167`) both collapse to 0
///   whenever `view_origin` is `Some`. **This function.**
/// * **`convert_via_engine`'s packed-RGB plan and the zero-copy float paths →
///   `get_or_create_egl_image_rgb` → `Platform::import_buffer_packed`.** That
///   one passes `plane_offset()` straight to `EGL_DMA_BUF_PLANE0_OFFSET_EXT`
///   with no `view_origin` collapse (`platform/linux.rs` ~`:199`), so a
///   destination there IS imported at its own offset. Those sites pass the raw
///   `plane_offset()` and must NOT use this function.
///
/// Getting the first case wrong costs the zero-copy path for nothing: asking
/// `plane_offset()` there declines every tile view whose byte offset happens
/// to be unaligned (an RGBA `x0` of 8 is 32 bytes) although its import bases
/// at 0 and would have succeeded. It cost correctness too, until the
/// mapped-texture path it lowered to was fixed for a view destination (#177).
///
/// Pure, and takes the two field values rather than a tensor, so it serves both
/// `Tensor<u8>` and `TensorDyn` call sites and is unit-testable without either.
fn view_collapsed_dst_base(
    view_origin: Option<edgefirst_tensor::ViewOrigin>,
    plane_offset: Option<usize>,
) -> usize {
    if view_origin.is_some() {
        0
    } else {
        plane_offset.unwrap_or(0)
    }
}

/// Whether a semi-planar source's chroma plane lives in a different DMA-BUF
/// from its luma. A multiplane tensor whose planes are `dup`s of one buffer
/// shares the `(st_dev, st_ino)` identity and is not separate.
fn chroma_in_separate_buffer(img: &Tensor<u8>) -> bool {
    img.chroma()
        .is_some_and(|c| c.buffer_identity().id() != img.buffer_identity().id())
}

/// The plane-1 (interleaved CbCr) byte offset a *contiguous* NV12 import hands
/// EGL: the chroma plane follows the full-height luma plane in the same buffer,
/// so it starts `pitch * height` past the luma offset. Mirrors
/// `DmaImportAttrs::from_tensor`'s contiguous arm (`dma_import.rs` ~`:225`) —
/// keep the two in step.
///
/// A multiplane NV12 does not use this: its chroma is a separate DMA-BUF whose
/// import offset is the chroma tensor's own `plane_offset()`.
///
/// Pure and saturating so a nonsense geometry cannot panic in release or wrap
/// into a spuriously aligned value in debug.
fn nv12_plane1_offset(plane0_offset: usize, pitch: usize, height: usize) -> usize {
    plane0_offset.saturating_add(pitch.saturating_mul(height))
}

impl GLProcessorST {
    /// Issue the single batched GPU sync if a `convert_deferred` is still owed,
    /// then clear the pending flag. No-op when nothing is pending. Used by both
    /// [`flush`](ImageProcessorTrait::flush) and the CUDA map path (which
    /// auto-flushes before handing the device a possibly-in-flight buffer).
    ///
    /// # Safety contract
    /// Must run on the GL worker thread that owns the context (it is, being
    /// driven from the worker loop under `GL_MUTEX`).
    pub(super) fn flush_pending(&mut self) {
        if self.pending_flush {
            // SAFETY: called on the context-owning GL worker thread.
            unsafe { float::finish_via_fence() };
            self.pending_flush = false;
        }
        if self.pending_submit {
            // One device submission for the whole batch: the per-convert
            // `record_completion` calls queued their signals without one.
            Platform::submit_recorded(&self.gl_context);
            self.pending_submit = false;
        }
    }

    /// Build a processor.
    ///
    /// `capacity` is the per-cache import-cache bound
    /// ([`ImageProcessorConfig::egl_cache_capacity`]); `None` (or `Some(0)`)
    /// defers to `EDGEFIRST_EGL_CACHE_CAPACITY` and then to the default —
    /// see [`resolve_egl_cache_capacity`].
    ///
    /// [`ImageProcessorConfig::egl_cache_capacity`]: crate::ImageProcessorConfig::egl_cache_capacity
    pub fn new(
        kind: Option<EglDisplayKind>,
        capacity: Option<usize>,
    ) -> Result<GLProcessorST, crate::Error> {
        // Display bring-up goes through the platform seam — the contract
        // each platform leaf (Linux EGL, ANGLE/Metal, Android EGL,
        // ANGLE/D3D11) implements instead of forking this engine. On Linux
        // this delegates straight to `GlContext::new`.
        let gl_context = Platform::init_display(kind)?;
        // Load the GL function pointers exactly once per process — `edgefirst_gl`
        // bindings are gl_generator `static mut` function-pointer tables, so
        // re-running `load_with` per construction would be a data race with
        // unlocked workers. Platform-routed: Linux loads via this display's
        // eglGetProcAddress; macOS loaded at shared-display init already.
        Platform::load_gl_once(&gl_context);

        let GlSupport {
            has_float_linear,
            has_yuv_target,
            has_bgra,
            renderer:
                RendererTraits {
                    vivante: is_vivante,
                    mali: is_mali,
                    software: is_software_renderer,
                    virtual_gpu: is_virtual_gpu,
                    angle: is_angle,
                    adreno: is_adreno,
                },
            supports_f32_color,
            supports_f16_color,
        } = Self::gl_check_support()?;

        // Software renderers (llvmpipe, softpipe, swrast) are CPU-based OpenGL
        // implementations that are slower and less capable than our native CPU
        // backend. Reject them early — the caller falls back to CPU automatically.
        //
        // `EDGEFIRST_ALLOW_SOFTWARE_GL=1` overrides the rejection. It exists
        // for the CI coverage lane, which runs the GL render path (e.g. the
        // float PBO roundtrips) on Mesa llvmpipe where no GPU is available —
        // the rendered output is numerically identical to a hardware GPU since
        // it runs the same GLSL. Production never sets it, so the default
        // (reject software GL, fall back to CPU) is unchanged.
        if should_reject_software_gl(is_software_renderer, software_gl_override_enabled()) {
            return Err(crate::Error::NotSupported(
                "software OpenGL renderer detected (llvmpipe/softpipe/swrast); \
                 GL backend disabled — check EGL ICD configuration if a \
                 hardware GPU is expected (set EDGEFIRST_ALLOW_SOFTWARE_GL=1 \
                 to override, e.g. for coverage on Mesa llvmpipe)"
                    .into(),
            ));
        }
        if is_software_renderer {
            log::warn!(
                "software OpenGL renderer in use (EDGEFIRST_ALLOW_SOFTWARE_GL=1); \
                 slower than the CPU backend — intended for CI coverage only"
            );
        }

        // Uploads and downloads are all packed with no alignment requirements
        unsafe {
            edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::PACK_ALIGNMENT, 1);
            edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ALIGNMENT, 1);
        }

        // External-OES sampler programs exist only where the platform's
        // import binding uses them (Linux Path A); ANGLE/Metal rejects the
        // extension at shader-compile time, so they are not built there.
        let texture_program_planar = if Platform::EXTERNAL_OES {
            Some(GlProgram::new(
                generate_vertex_shader(),
                generate_planar_rgb_shader(),
            )?)
        } else {
            None
        };

        let texture_program =
            GlProgram::new(generate_vertex_shader(), generate_texture_fragment_shader())?;

        let texture_program_yuv = if Platform::EXTERNAL_OES {
            Some(GlProgram::new(
                generate_vertex_shader(),
                generate_texture_fragment_shader_yuv(),
            )?)
        } else {
            None
        };

        // The default build; the mapped one links on the first mapped convert.
        let int8 = Int8Set::new(false, has_yuv_target)?;
        // SAFETY: linked above on this thread's current context, and
        // `GetUniformLocation` reads a linked program without needing it
        // current. The name is a `c"..."` literal, so the pointer is a live
        // NUL-terminated string for the call.
        let texture_src_extent_locs = [
            unsafe {
                edgefirst_gl::gl::GetUniformLocation(texture_program.id, c"src_extent".as_ptr())
            },
            int8.texture_src_extent_loc,
        ];

        let yuyv_program_2d = GlProgram::new(
            generate_vertex_shader(),
            super::shaders_common::YUYV_RGBA_2D_FRAGMENT,
        )?;
        let yuyv_2d_locs = [yuyv_2d_locs(&yuyv_program_2d), int8.yuyv_2d_locs];

        let segmentation_program =
            GlProgram::new(generate_vertex_shader(), generate_segmentation_shader())?;
        segmentation_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;
        let instanced_segmentation_program = GlProgram::new(
            generate_vertex_shader(),
            generate_instanced_segmentation_shader(),
        )?;
        instanced_segmentation_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        // Existing f16 proto shader (RGBA16F, 4 protos per layer)
        let proto_segmentation_program = GlProgram::new(
            generate_vertex_shader(),
            generate_proto_segmentation_shader(),
        )?;
        proto_segmentation_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        // Int8 proto shaders (R8I, 1 proto per layer, 32 layers)
        let proto_segmentation_int8_nearest_program = GlProgram::new(
            generate_vertex_shader(),
            generate_proto_segmentation_shader_int8_nearest(),
        )?;
        proto_segmentation_int8_nearest_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        let proto_segmentation_int8_bilinear_program = GlProgram::new(
            generate_vertex_shader(),
            generate_proto_segmentation_shader_int8_bilinear(),
        )?;
        proto_segmentation_int8_bilinear_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        let proto_dequant_int8_program = GlProgram::new(
            generate_vertex_shader(),
            generate_proto_dequant_shader_int8(),
        )?;

        // F32 proto shader (R32F, 1 proto per layer, 32 layers)
        let proto_segmentation_f32_program = GlProgram::new(
            generate_vertex_shader(),
            generate_proto_segmentation_shader_f32(),
        )?;
        proto_segmentation_f32_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        let color_program = GlProgram::new(generate_vertex_shader(), generate_color_shader())?;
        color_program.load_uniform_4fv(c"colors", &DEFAULT_COLORS)?;

        // SAFETY: each program, when present, was linked above on this
        // thread's current context; `GetUniformLocation` reads a linked
        // program without needing it current, and the name is a `c"..."`
        // literal.
        let [yuv_loc, planar_loc] = [
            texture_program_yuv.as_ref(),
            texture_program_planar.as_ref(),
        ]
        .map(|p| {
            p.map_or(-1, |p| unsafe {
                edgefirst_gl::gl::GetUniformLocation(p.id, c"src_extent".as_ptr())
            })
        });
        let external_src_extent_locs = [
            yuv_loc,
            int8.yuv_src_extent_loc,
            planar_loc,
            int8.planar_src_extent_loc,
        ];

        // Planar RGB shaders with sampler2D (for two-pass NV12→RGBA→PlanarRgb on Vivante)
        let texture_program_planar_2d =
            GlProgram::new(generate_vertex_shader(), generate_planar_rgb_shader_2d())?;

        // RGB packing shaders (2D only — used in pass 2 of two-pass pipeline)
        let packed_rgba8_program_2d =
            GlProgram::new(generate_vertex_shader(), generate_packed_rgba8_shader_2d())?;

        // Float render programs. All four are full-viewport fragment shaders
        // driven by `gl_FragCoord`; the standard vertex shader emits a
        // full-screen quad so every packed output texel is visited. Crop and
        // letterbox are entirely uniform-driven (src_rect_uv/dst_rect_px/
        // pad_color), matching the macOS IOSurface contract. They are built
        // once per processor and live for its lifetime.
        let float_f32_nhwc_program =
            GlProgram::new(generate_vertex_shader(), generate_packed_f32_nhwc_shader())?;
        let float_f16_nchw_program = GlProgram::new(
            generate_vertex_shader(),
            generate_planar_rgb_f16_packed_shader(),
        )?;
        let float_nhwc_pack_program = GlProgram::new(
            generate_vertex_shader(),
            generate_float_nhwc_packed_shader(),
        )?;
        let float_rgba_program =
            GlProgram::new(generate_vertex_shader(), generate_float_rgba_shader())?;

        // Path B: NV12/NV16/NV24 → RGBA via R8 texelFetch shader (ES 3.0 core, no extension).
        let Int8Set {
            texture: texture_int8_program,
            texture_yuv: texture_int8_program_yuv,
            planar: texture_program_planar_int8,
            planar_2d: texture_program_planar_int8_2d,
            yuyv_2d: yuyv_int8_program_2d,
            packed_rgba8_2d: packed_rgba8_int8_program_2d,
            nv_r8: [nv_int8, nv_bilinear_int8, nv_hw_bilinear_int8],
            nv_r8_uniforms: [nv_int8_u, nv_bilinear_int8_u, nv_hw_bilinear_int8_u],
            nv_y2y: y2y_int8,
            ..
        } = int8;
        let [nv, nv_bilinear, nv_hw_bilinear] = [
            generate_nv_to_rgba_shader_2d(),
            generate_nv_to_rgba_bilinear_shader_2d(),
            generate_nv_to_rgba_hw_bilinear_shader_2d(),
        ]
        .map(|src| GlProgram::new(generate_vertex_shader(), src));
        let [nv, nv_bilinear, nv_hw_bilinear] = [nv?, nv_bilinear?, nv_hw_bilinear?];
        // Resolve uniform locations once at link time (the NV draw is per-frame)
        // and upload the constant sampler bindings while the programs are fresh:
        // pass-2 packing samples the intermediate on unit 1, planar-2d on unit 0.
        let [nv_u, nv_bilinear_u, nv_hw_bilinear_u] =
            [&nv, &nv_bilinear, &nv_hw_bilinear].map(NvUniformState::resolve);
        let nv_r8_programs = [
            nv,
            nv_int8,
            nv_bilinear,
            nv_bilinear_int8,
            nv_hw_bilinear,
            nv_hw_bilinear_int8,
        ];
        let nv_r8_uniforms = [
            nv_u,
            nv_int8_u,
            nv_bilinear_u,
            nv_bilinear_int8_u,
            nv_hw_bilinear_u,
            nv_hw_bilinear_int8_u,
        ];
        let nv_y2y_programs = if has_yuv_target {
            match (
                GlProgram::new(generate_vertex_shader(), generate_nv_to_rgba_y2y_shader()),
                y2y_int8,
            ) {
                (Ok(u8_program), Some((int8_program, int8_uniforms))) => {
                    let u8_uniforms = NvUniformState::resolve(&u8_program);
                    Some(([u8_program, int8_program], [u8_uniforms, int8_uniforms]))
                }
                (a, _) => {
                    log::info!(
                        "GL_EXT_YUV_target present but the Y2Y NV programs did not build \
                         ({:?}); bilinear NV resizes of imports filter in the shader",
                        a.err()
                    );
                    None
                }
            }
        } else {
            None
        };
        packed_rgba8_program_2d.load_uniform_1i(c"tex", 1)?;
        texture_program_planar_2d.load_uniform_1i(c"tex", 0)?;

        let camera_eglimage_texture = Texture::new();
        let camera_normal_texture = Texture::new();
        let render_texture = Texture::new();
        let draw_render_texture = Texture::new();
        let segmentation_texture = Texture::new();
        let proto_texture = Texture::new();
        let proto_dequant_texture = Texture::new();
        let vertex_buffer = Buffer::new(0, 3, 100);
        let texture_buffer = Buffer::new(1, 2, 100);

        // EGLImage cache capacity (per cache: src / dst / nv_r8 / nv_uv). What the
        // number MEANS -- a buffer count and not a size, its scope, and the
        // pinned-memory formula -- is documented once, on
        // `ImageProcessorConfig::egl_cache_capacity`, which is what a caller
        // reads. What follows is only why the DEFAULT is 16.
        //
        // Entries are retained past the lifetime of the tensor that produced
        // them (the point of `CachedImport`), and a retained import pins its
        // buffer, so capacity bounds memory rather than handle count. At 4K
        // NV12 (12.4 MB/frame) that is 199 MB per cache at 16, against 796 MB
        // per cache at the pre-retention default of 64 -- and the three-cache
        // upper bound at 64, 2.39 GB, exceeds total RAM on the i.MX 8M Plus
        // and i.MX 95, with CMA a fraction of RAM again. (The three-cache
        // totals are upper bounds, not exact figures: `src` and `nv_r8` often
        // hold two imports of the SAME source buffer, and two entries naming
        // one buffer pin it once. The per-cache column is exact, and it is
        // what the decision turns on.)
        //
        // 64 was chosen when capacity bounded handles, and was justified as
        // free for fixed-dimension workloads while naming dataset validation
        // -- a high-cardinality varied-size stream -- as the case needing an
        // override. Retention inverts that: high cardinality is exactly where
        // every frame is a distinct allocation and the cache fills with 64
        // different buffers. 16 covers a realistic producer pool (V4L2
        // capture, typically 4-8 buffers over one or two sizes) with headroom.
        //
        // The failure modes are asymmetric: a miss costs one
        // eglCreateImageKHR (100 us - 1 ms on Mali/Vivante/V3D), while
        // exhausting CMA costs the frame or the process. The default belongs
        // on the safe side, with the config field and the environment
        // variable as the documented answers for a caller that has measured.
        let egl_cache_capacity = resolve_egl_cache_capacity(
            capacity,
            std::env::var("EDGEFIRST_EGL_CACHE_CAPACITY")
                .ok()
                .as_deref(),
        );

        // NV* conversion-path preference. `auto` (default) prefers the portable,
        // colorimetry-exact in-shader ShaderR8 path; `sampler`/`shader` force a
        // path for benchmarking / platform bring-up (an impossible force warns
        // and falls back). Mirrors the EDGEFIRST_FORCE_TRANSFER idiom below.
        let nv_path_pref = parse_nv_path_pref();
        if nv_path_pref != NvPathPref::Auto {
            log::info!("EDGEFIRST_NV_CONVERT_PATH override: {nv_path_pref:?}");
        }

        // Colorimetry/performance trade-off. The env var pins the mode for the
        // processor's lifetime (set_colorimetry_mode logs and keeps it);
        // otherwise the config default is Fast (issue #106 policy) and
        // `set_colorimetry_mode` may change it.
        let colorimetry_env = parse_colorimetry_env();
        if let Some(mode) = colorimetry_env {
            log::info!("EDGEFIRST_COLORIMETRY override: {mode:?}");
        }

        let mut converter = GLProcessorST {
            gl_context,
            texture_program,
            texture_program_yuv,
            texture_int8_program,
            texture_int8_program_yuv,
            texture_program_planar,
            texture_program_planar_int8,
            yuyv_program_2d,
            yuyv_int8_program_2d,
            yuyv_2d_locs,
            texture_src_extent_locs,
            external_src_extent_locs,
            packed_rgba8_program_2d,
            packed_rgba8_int8_program_2d,
            texture_program_planar_2d,
            texture_program_planar_int8_2d,
            float_f32_nhwc_program,
            float_f16_nchw_program,
            float_nhwc_pack_program,
            float_rgba_program,
            float_render_texture: Texture::new(),
            float_render_tex_dims: (0, 0, 0),
            camera_eglimage_texture,
            camera_normal_texture,
            segmentation_texture,
            proto_texture,
            proto_segmentation_int8_nearest_program,
            proto_segmentation_int8_bilinear_program,
            proto_dequant_int8_program,
            proto_segmentation_f32_program,
            has_float_linear,
            has_bgra,
            supports_f32_color,
            supports_f16_color,
            int8_interpolation_mode: Int8InterpolationMode::Bilinear,
            proto_dequant_texture,
            proto_dequant_tex_dims: (0, 0, 0, 0),
            proto_dequant_fbo: FrameBuffer::new(),
            proto_quad_locs: std::cell::Cell::new((0, -1, -1)),
            vertex_buffer,
            texture_buffer,
            convert_fbo: FrameBuffer::new(),
            draw_fbo: FrameBuffer::new(),
            draw_render_texture,
            src_egl_cache: ImportCache::new(egl_cache_capacity),
            dst_egl_cache: ImportCache::new(egl_cache_capacity),
            bgra_warned: false,
            readback_scratch: Vec::new(),
            #[cfg(test)]
            fail_dst_import: false,
            probe_dst_import_only: false,
            dst_import_warned: std::collections::HashSet::new(),
            is_vivante,
            is_mali,
            is_virtual_gpu,
            is_angle,
            is_adreno,
            use_renderbuffer: std::env::var("EDGEFIRST_OPENGL_RENDERSURFACE")
                .map(|v| v == "1")
                .unwrap_or(false),
            packed_rgb_intermediate_tex: Texture::new(),
            packed_rgb_fbo: FrameBuffer::new(),
            packed_rgb_intermediate_size: (0, 0),
            render_texture,
            segmentation_program,
            instanced_segmentation_program,
            proto_segmentation_program,
            color_program,
            box_line_width: crate::DEFAULT_BOX_LINE_WIDTH as f32,
            cached_opacity: f32::NAN, // sentinel: forces first set_opacity_uniform to initialize all shaders
            proto_tex_dims: (0, 0, 0, 0),
            proto_repack_compute_program: None,
            proto_compute_locs: (-1, -1, -1),
            proto_ssbo: 0,
            proto_ssbo_size: 0,
            nv_r8_programs,
            nv_r8_uniforms,
            nv_r8_texture: Texture::new(),
            nv_r8_egl_cache: ImportCache::new(egl_cache_capacity),
            nv_uv_texture: Texture::new(),
            nv_uv_egl_cache: ImportCache::new(egl_cache_capacity),
            nv_uv_import_refused: false,
            nv_y2y_programs,
            last_nv_convert_path: NvConvertPath::None,
            last_nv_sampling: None,
            convert_stats: Default::default(),
            nv_import_warned: std::collections::HashSet::new(),
            owned_pbos: Default::default(),
            float_quad_locs: std::collections::HashMap::new(),
            float_norm: FloatNorm::IDENTITY,
            int8_programs: Vec::new(),
            int8_mapped: false,
            int8_alt: None,
            int_quant: None,
            int_pad: None,
            int_pad_output: false,
            float_quad_pos_vbo: 0,
            float_quad_uv_vbo: 0,
            nv_path_pref,
            colorimetry_mode: colorimetry_env.unwrap_or_default(),
            colorimetry_env_pinned: colorimetry_env.is_some(),
            interpolation: crate::Interpolation::default(),
            nv_hw_filter: std::env::var("EDGEFIRST_GL_NO_NV_HW_FILTER").map_or(true, |v| v != "1"),
            defer_finish: false,
            pending_flush: false,
            pending_submit: false,
        };
        check_gl_error(function!(), line!())?;

        // Compile compute shader for proto repack if GLES 3.1 is available.
        // Enabled via EDGEFIRST_PROTO_COMPUTE=1 while validating on target GPUs.
        let compute_enabled = converter.gl_context.has_compute
            && std::env::var("EDGEFIRST_PROTO_COMPUTE")
                .map(|v| v == "1")
                .unwrap_or(false);
        if compute_enabled {
            match Self::compile_compute_program(generate_proto_repack_compute_shader()) {
                Ok(program) => {
                    log::info!("Proto repack compute shader compiled successfully");
                    converter.proto_repack_compute_program = Some(program);
                    unsafe {
                        converter.proto_compute_locs = (
                            edgefirst_gl::gl::GetUniformLocation(program, c"width".as_ptr()),
                            edgefirst_gl::gl::GetUniformLocation(program, c"height".as_ptr()),
                            edgefirst_gl::gl::GetUniformLocation(program, c"num_protos".as_ptr()),
                        );
                    }
                    let mut ssbo = 0u32;
                    unsafe { edgefirst_gl::gl::GenBuffers(1, &mut ssbo) };
                    converter.proto_ssbo = ssbo;
                }
                Err(e) => {
                    log::warn!("Proto repack compute shader failed: {e}; using CPU fallback");
                }
            }
        }

        log::debug!(
            "GLProcessorST: DMA destination attachment mode: {}",
            if converter.use_renderbuffer {
                "renderbuffer (EDGEFIRST_OPENGL_RENDERSURFACE=1)"
            } else {
                "texture (default)"
            }
        );

        // Verify DMA-buf actually works (catches NVIDIA discrete GPUs where
        // EGLImage creation succeeds but rendered data is all zeros)
        if converter.gl_context.transfer_backend.is_dma() && !converter.verify_dma_buf_roundtrip() {
            log::info!("DMA-buf verification failed — falling back to PBO transfers");
            // Structured twin of the log line: this downgrade silently costs
            // every future convert its zero-copy path, so subscribers
            // (profiler, telemetry) get a machine-readable event too.
            tracing::event!(
                tracing::Level::INFO,
                from = "dmabuf",
                to = "pbo",
                "image.convert.gl.transfer_downgrade"
            );
            converter.gl_context.transfer_backend = TransferBackend::Pbo;
        }

        // If DMA-buf failed/unavailable but GL is alive, use PBO transfers.
        // Software renderers never reach here — they are rejected above.
        if converter.gl_context.transfer_backend == TransferBackend::Sync {
            log::info!("Upgrading transfer backend from Sync to Pbo (GL context available)");
            converter.gl_context.transfer_backend = TransferBackend::Pbo;
        }

        // Allow env-var override for benchmarking specific transfer paths.
        // Values: "dmabuf", "pbo", "sync" (case-insensitive).
        apply_forced_transfer(&mut converter.gl_context.transfer_backend);

        log::debug!(
            "GLConverter created (transfer={:?})",
            converter.gl_context.transfer_backend,
        );
        Ok(converter)
    }

    /// Verify that DMA-buf EGLImage round-trip actually works on this GPU.
    ///
    /// Renders a solid red quad to a 64x64 DMA-buf-backed RGBA texture via
    /// EGLImage, then reads it back and checks that the center pixel is red.
    /// Returns `true` if the data round-trips correctly.
    ///
    /// This catches GPUs like NVIDIA discrete where `eglCreateImage` from
    /// `dma_heap` fds succeeds but the rendered data is all zeros.
    fn verify_dma_buf_roundtrip(&mut self) -> bool {
        // Allocate a 64x64 RGBA DMA source tensor and fill it with solid red
        let src = match Tensor::<u8>::image(
            64,
            64,
            PixelFormat::Rgba,
            Some(TensorMemory::DmaBuf),
            edgefirst_tensor::CpuAccess::Write,
        ) {
            Ok(img) => img,
            Err(e) => {
                log::info!("verify_dma_buf_roundtrip: failed to allocate DMA source: {e}");
                return false;
            }
        };

        {
            let mut map = match src.map_write() {
                Ok(m) => m,
                Err(e) => {
                    log::info!("verify_dma_buf_roundtrip: failed to map DMA source: {e}");
                    return false;
                }
            };
            for pixel in map.as_chunks_mut::<4>().0 {
                pixel[0] = 255; // R
                pixel[1] = 0; // G
                pixel[2] = 0; // B
                pixel[3] = 255; // A
            }
        }

        // Allocate a 64x64 RGBA DMA destination tensor
        let mut dst = match Tensor::<u8>::image(
            64,
            64,
            PixelFormat::Rgba,
            Some(TensorMemory::DmaBuf),
            edgefirst_tensor::CpuAccess::Read,
        ) {
            Ok(img) => img,
            Err(e) => {
                log::info!("verify_dma_buf_roundtrip: failed to allocate DMA destination: {e}");
                return false;
            }
        };

        // Run the full DMA-buf EGLImage render pipeline (RGBA→RGBA DMA is a
        // single-pass zero-copy plan through the engine).
        // The probe declines the fallback the real converts take (issue #175):
        // its question is whether this display can render into a DMA-BUF at
        // all, and the answer demotes the whole transfer backend to PBO,
        // sources included. A convert serviced by the mapped-texture readback
        // would answer that question with the fallback's own output. The flag
        // clears before the `?`-free early return below either way.
        self.probe_dst_import_only = true;
        let outcome = self.convert_via_engine(
            &mut dst,
            PixelFormat::Rgba,
            &src,
            PixelFormat::Rgba,
            false,
            Rotation::None,
            Flip::None,
            ResolvedCrop::no_crop(),
        );
        self.probe_dst_import_only = false;
        if let Err(e) = outcome {
            log::info!("verify_dma_buf_roundtrip: convert failed: {e}");
            return false;
        }

        // Read back the center pixel at (32, 32) from the destination
        let map = match dst.map_read() {
            Ok(m) => m,
            Err(e) => {
                log::info!("verify_dma_buf_roundtrip: failed to map DMA destination: {e}");
                return false;
            }
        };

        let offset = (32 * 64 + 32) * 4;
        if map.len() < offset + 4 {
            log::info!("verify_dma_buf_roundtrip: destination buffer too small");
            return false;
        }

        let r = map[offset];
        let g = map[offset + 1];
        let b = map[offset + 2];
        let a = map[offset + 3];

        let pass = r > 250 && g < 5 && b < 5 && a > 250;

        if pass {
            log::info!("verify_dma_buf_roundtrip: PASSED (center pixel RGBA={r},{g},{b},{a})");
        } else {
            log::info!(
                "verify_dma_buf_roundtrip: FAILED (center pixel RGBA={r},{g},{b},{a}, \
                 expected ~255,0,0,255)"
            );
        }

        pass
    }

    /// Sets the interpolation mode for int8 proto textures.
    pub fn set_int8_interpolation_mode(&mut self, mode: Int8InterpolationMode) {
        self.int8_interpolation_mode = mode;
        log::debug!("Int8 interpolation mode set to {:?}", mode);
    }

    /// Sets the colorimetry/performance trade-off (see
    /// [`crate::ColorimetryMode`]). When `EDGEFIRST_COLORIMETRY` pinned the
    /// mode at construction, the env value wins: this logs and keeps it.
    pub fn set_colorimetry_mode(&mut self, mode: crate::ColorimetryMode) {
        if self.colorimetry_env_pinned {
            if mode != self.colorimetry_mode {
                log::info!(
                    "ColorimetryMode::{mode:?} requested but EDGEFIRST_COLORIMETRY pins \
                     {:?} — keeping the env override",
                    self.colorimetry_mode
                );
            }
            return;
        }
        self.colorimetry_mode = mode;
        log::debug!("Colorimetry mode set to {:?}", mode);
    }

    /// Sets how resizing converts resample (see [`crate::Interpolation`]).
    /// `ImageProcessor::set_interpolation` resolves the
    /// `EDGEFIRST_INTERPOLATION` override before it reaches here.
    pub fn set_interpolation(&mut self, mode: crate::Interpolation) {
        self.interpolation = mode;
        log::debug!("Interpolation set to {mode:?}");
    }

    /// Whether the Y2Y NV programs ([`NvSampling::HardwareYuv`]) built.
    #[cfg(test)]
    pub(super) fn has_y2y(&self) -> bool {
        self.nv_y2y_programs.is_some()
    }

    /// Allow or forbid [`NvSampling::Hardware`] (see `nv_hw_filter`).
    #[cfg(test)]
    pub(super) fn set_nv_hw_filter(&mut self, enabled: bool) {
        self.nv_hw_filter = enabled;
    }

    /// `MIN`/`MAG` filter for a source texture that a draw resamples.
    pub(super) fn source_filter(&self) -> u32 {
        match self.interpolation.supported() {
            crate::Interpolation::Nearest => edgefirst_gl::gl::NEAREST,
            _ => edgefirst_gl::gl::LINEAR,
        }
    }

    /// Snapshot the EGLImage cache counters (src, dst, NV R8).
    ///
    /// Steady-state tests capture this after warmup and after an N-frame
    /// loop and assert `total_misses()` stays flat — the cache-behavior
    /// equality gate for GL refactors.
    pub(crate) fn egl_cache_stats(&self) -> GlCacheStats {
        GlCacheStats {
            src: self.src_egl_cache.stats(),
            dst: self.dst_egl_cache.stats(),
            nv_r8: self.nv_r8_egl_cache.stats(),
            nv_uv: self.nv_uv_egl_cache.stats(),
        }
    }

    /// A tensor's memory as this context can use it: a PBO allocated by
    /// another context counts as host memory, read and written through its
    /// own map, because its buffer name means nothing here (see
    /// [`OwnedPbos`]).
    fn usable_memory(
        &self,
        memory: TensorMemory,
        pbo_vtable: Option<*const std::ffi::c_void>,
    ) -> TensorMemory {
        match memory {
            TensorMemory::Pbo if !self.owned_pbos.contains(pbo_vtable) => TensorMemory::Mem,
            other => other,
        }
    }

    pub(crate) fn convert_stats(&self) -> super::cache::ConvertStats {
        self.convert_stats
    }

    /// The body of [`ImageProcessorTrait::convert`], separated out so the
    /// trait method can record GPU completion on `dst` after every call
    /// (see [`GlPlatform::record_completion`]) without every early return
    /// in this function having to do it itself. A per-convert interpolation
    /// in `options` replaces the processor's for this call only.
    fn convert_inner(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        options: &crate::ConvertOptions,
    ) -> crate::Result<()> {
        let processor_mode = self.interpolation;
        if let Some(mode) = options.get_interpolation() {
            self.interpolation = mode;
        }
        let result = self.convert_resampling(src, dst, options);
        self.interpolation = processor_mode;
        result
    }

    /// [`Self::convert_inner`] with `self.interpolation` already chosen.
    fn convert_resampling(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        options: &crate::ConvertOptions,
    ) -> crate::Result<()> {
        let (rotation, flip, crop) = (
            options.get_rotation(),
            options.get_flip(),
            options.get_crop(),
        );
        // A view()/batch() destination is lowered to a glViewport/scissor band
        // only on the u8/i8 DMA packed path (see `setup_renderbuffer_dma` +
        // `convert_to`). For any other GL destination — a non-DMA CPU upload, a
        // PBO, or a float render target — that lowering does not exist, so
        // decline and let the dispatcher fall back to the CPU backend, which
        // writes the sub-region correctly via offset + parent stride.
        if dst.view_origin().is_some()
            && !(self.gl_context.transfer_backend.is_zero_copy()
                && dst.memory() == TensorMemory::DmaBuf
                && matches!(
                    dst.dtype(),
                    edgefirst_tensor::DType::U8 | edgefirst_tensor::DType::I8
                ))
        {
            return Err(Error::NotSupported(
                "GL view()/batch() destination is supported only for u8/i8 DMA buffers; \
                 CPU fallback handles other cases"
                    .into(),
            ));
        }

        let crop = crop.resolve(
            src.width().unwrap_or(0),
            src.height().unwrap_or(0),
            dst.width().unwrap_or(0),
            dst.height().unwrap_or(0),
            options.get_placement(),
        )?;
        let mapping = crate::options::output_map_for(options, dst, crop.dst_rect.is_some())?;
        let pad_output = mapping.as_ref().and_then(|(_, p)| *p);
        let mut crop = crop;
        let mut pad_output_exact = false;
        self.float_norm = FloatNorm::IDENTITY;
        self.int_pad = None;
        self.int_pad_output = false;
        let mut int_mapped = false;
        if let Some((map, pad_output)) = &mapping {
            let pad = crop.dst_color.map(|p| map.pad_values(p, *pad_output));
            if map.bounds.is_some() {
                // The int8 programs work in RGB order; Bgra swaps on readback.
                if dst.format() == Some(PixelFormat::Bgra) {
                    return Err(Error::NotSupported(
                        "GL integer output mapping of Bgra; CPU fallback".into(),
                    ));
                }
                self.use_int8_set(true)?;
                self.load_int_quant(IntQuant::from_map(map))?;
                self.int_pad = pad.map(|v| v.map(|x| x as i32 as u8));
                int_mapped = true;
                // An output pad that some sample maps to exactly is that pixel
                // pad, which every route (two-pass included) can render.
                if let (Some(p), Some([_, _, _, a])) = (pad, crop.dst_color) {
                    let samples = [
                        map.sample_for(0, p[0]),
                        map.sample_for(1, p[1]),
                        map.sample_for(2, p[2]),
                    ];
                    if let [Some(sr), Some(sg), Some(sb)] = samples {
                        crop.dst_color = Some([sr, sg, sb, a]);
                        pad_output_exact = true;
                    }
                }
            } else {
                // The float shaders sample in [0, 1]; the map is per 8-bit value.
                self.float_norm = FloatNorm {
                    scale: map.scale.map(|s| s * 255.0),
                    offset: map.offset,
                    pad,
                };
            }
        }
        if !int_mapped && dst.dtype() == edgefirst_tensor::DType::I8 {
            self.use_int8_set(false)?;
        }

        // F16/F32 destination: check for a GL float render path BEFORE the u8
        // extraction functions reject the dtype. When a path is found, dispatch
        // to convert_float_to_pbo (stub → NotSupported → CPU fallback). When
        // None, fall through to the existing u8 path unchanged.
        let dst_dtype = dst.dtype();
        if matches!(
            dst_dtype,
            edgefirst_tensor::DType::F16 | edgefirst_tensor::DType::F32
        ) {
            let src_fmt = src.format().ok_or(Error::NotAnImage)?;
            let dst_fmt = dst.format().ok_or(Error::NotAnImage)?;
            let support = float_render_support(
                self.is_vivante,
                self.float_import_refused(),
                self.supports_f32_color,
                self.supports_f16_color,
            );
            // Fused NV*→float (the model-input convert): two engine passes —
            // NV→RGBA full-res into a cached intermediate, then the packed
            // float render with the caller's crop/letterbox. The float
            // classifier runs on the RGBA intermediate rather than the NV
            // source, so the verdict is pass 2's.
            let nv_src = matches!(
                src_fmt,
                PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
            );
            let path = classify_float_render(
                if nv_src { PixelFormat::Rgba } else { src_fmt },
                dst_fmt,
                dst_dtype,
                self.usable_memory(dst.memory(), dst.pbo_vtable_ptr()),
                support,
                <Platform as GlPlatform>::ZERO_COPY_FLOAT,
            );
            // Sibling of the view_origin guard above, for the
            // offset-without-view_origin case: none of the four zero-copy
            // float destination imports (`convert_float_to_zero_copy`,
            // `convert_nv_to_float_two_pass` -> `get_or_create_egl_image_rgb`
            // -> `import_buffer_packed`) go through `bind_dst`'s placement
            // gate, and on ANGLE they bind the whole buffer from its origin.
            // A destination rebuilt from a descriptor has no `view_origin` to
            // place it by, and there is no mapped-texture readback for a
            // float DMA destination to lower to, so decline outright rather
            // than render at the buffer's origin.
            if matches!(
                path,
                FloatRenderPath::ZeroCopyF16Nchw
                    | FloatRenderPath::ZeroCopyF32Nchw
                    | FloatRenderPath::ZeroCopyFloatNhwc
                    | FloatRenderPath::ZeroCopyFloatRgba
            ) {
                let places = match dst_dtype {
                    edgefirst_tensor::DType::F16 => Platform::dst_import_places(
                        dst.as_typed::<half::f16>().expect("dtype checked"),
                    ),
                    edgefirst_tensor::DType::F32 => {
                        Platform::dst_import_places(dst.as_typed::<f32>().expect("dtype checked"))
                    }
                    _ => unreachable!("dst_dtype is F16 or F32 in this branch"),
                };
                // No driver-refusal term here, unlike the u8 arms: there is no
                // mapped-texture readback for a FLOAT DMA destination to fall
                // back to (`read_pixels_into` packs `UNSIGNED_BYTE`), so a
                // driver that refuses such a destination has nothing to lower
                // to inside GL. Its `eglCreateImage` failure propagates out of
                // the convert and `ImageProcessor` runs the CPU converter,
                // which is where the removed Vivante predicate sent it too --
                // by a cleaner route, but to the same place (issue #175).
                // What stays is the PLACEMENT question, which no import
                // failure can answer because such an import succeeds.
                if !places {
                    return Err(Error::NotSupported(format!(
                        "GL float destination at plane offset {} cannot be placed by \
                         this platform/driver -- either no view origin and an import \
                         that binds the whole buffer from its origin, or a driver whose \
                         import rejects the offset -- and there is no mapped-texture \
                         readback for a float DMA destination to lower to; CPU fallback \
                         handles it",
                        dst.plane_offset().unwrap_or(0)
                    )));
                }
            }
            match path {
                FloatRenderPath::ZeroCopyF16Nchw
                | FloatRenderPath::ZeroCopyF32Nchw
                | FloatRenderPath::ZeroCopyFloatNhwc
                | FloatRenderPath::ZeroCopyFloatRgba => {
                    let _span = Self::enter_image_convert_gl_span(
                        src_fmt,
                        dst_fmt,
                        false,
                        src.memory(),
                        dst.memory(),
                    );
                    let convert_span = tracing::Span::current();
                    return if nv_src {
                        self.convert_nv_to_float_two_pass(
                            src,
                            dst,
                            path,
                            rotation,
                            flip,
                            crop,
                            &convert_span,
                        )
                    } else {
                        self.convert_float_to_zero_copy(
                            src,
                            dst,
                            path,
                            rotation,
                            flip,
                            crop,
                            &convert_span,
                        )
                    };
                }
                FloatRenderPath::PboF16Nchw
                | FloatRenderPath::PboF32Nhwc
                | FloatRenderPath::PboF32Nchw
                | FloatRenderPath::PboF16Nhwc => {
                    let _span = Self::enter_image_convert_gl_span(
                        src_fmt,
                        dst_fmt,
                        false,
                        src.memory(),
                        dst.memory(),
                    );
                    let convert_span = tracing::Span::current();
                    return self.convert_float_to_pbo(
                        src,
                        dst,
                        path,
                        rotation,
                        flip,
                        crop,
                        &convert_span,
                    );
                }
                FloatRenderPath::None => {}
            }
            // path == None: fall through to the u8 path, which will reject
            // F16/F32 via dyn_to_u8_dst → CPU fallback (existing behavior).
        }

        // Capture odd-destination dims before the mutable borrow below, for the
        // defense-in-depth wrap at the end (rule #2).
        let dst_odd = match (dst.width(), dst.height()) {
            (Some(w), Some(h)) if w % 2 != 0 || h % 2 != 0 => Some((w, h)),
            _ => None,
        };

        let (src_u8, src_fmt) = dyn_to_u8_src(src)?;
        let (dst_u8, dst_fmt, is_int8) = dyn_to_u8_dst(dst)?;
        // A mapped u8 destination renders through the int8 programs too.
        let is_int8 = is_int8 || int_mapped;
        self.int_pad_output = int_mapped && pad_output.is_some() && !pad_output_exact;

        let result = self.convert_impl(
            src_u8, src_fmt, dst_u8, dst_fmt, is_int8, rotation, flip, crop,
        );

        // Defense-in-depth (rule #2): `Tensor::image` now 64-aligns DMA strides,
        // so image()-allocated destinations import fine at any width. But an
        // externally-imported destination with an odd, non-64-aligned stride can
        // still be rejected by a GPU that requires an aligned EGLImage pitch
        // (Mali `BadAlloc`, Vivante `BadAccess`). Surface such EGL/GL failures as
        // a descriptive `NotSupported` that PRESERVES the underlying error and
        // flags it as a platform-consistency limitation, rather than leaking a
        // raw `EGL(BadAlloc)`. (The F16/F32 float paths return earlier; their
        // destinations are 64-aligned by the same allocator fix.)
        match result {
            Err(e) if dst_odd.is_some() && matches!(e, Error::EGL(_) | Error::OpenGl(_)) => {
                let (w, h) = dst_odd.unwrap();
                Err(Error::NotSupported(format!(
                    "Conversion failed with {e:?} and target tensor has odd \
                     dimensions {w}x{h}, which is not supported by all platforms"
                )))
            }
            other => other,
        }
    }

    /// Convert without the terminal CPU sync, exporting a native fence fd
    /// that signals when the GPU work completes — the GL→NPU handoff.
    ///
    /// Uses the same `defer_finish` mechanism as batching to skip the
    /// pure-GPU tails' sync; paths that read back to the CPU (PBO/upload
    /// destinations) sync internally regardless, so the fence degenerates
    /// to already-signaled there — correct, just no faster than `convert`.
    /// When the platform has no native fence (`Ok(None)` / export error)
    /// the blocking contract is restored with an explicit `glFinish`.
    pub(crate) fn convert_fenced(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        options: crate::ConvertOptions,
    ) -> Result<Option<super::CompletionFence>, crate::Error> {
        self.defer_finish = true;
        let result = self.convert_inner(src, dst, &options);
        self.defer_finish = false;
        result?;
        // One flush and one signal for the whole call: the value recorded on
        // the destination is the value the returned fence waits on, so
        // `dst.gpu_completion()` and the fence name the same point rather
        // than two adjacent ones. `record_completion` submits here (this is
        // not a batch) so a consumer in another process sees the value.
        let recorded = Platform::record_completion(&self.gl_context, dst, true);
        match Platform::export_completion_fence(&self.gl_context, recorded) {
            Ok(Some(fd)) => Ok(Some(fd)),
            Ok(None) => {
                unsafe { edgefirst_gl::gl::Finish() };
                check_gl_error(function!(), line!())?;
                Ok(None)
            }
            Err(e) => {
                // A failed export must not skip the sync — fall back to
                // the blocking contract rather than hand back a dst the
                // GPU may still be writing.
                log::debug!("native fence export failed ({e:?}); falling back to glFinish");
                unsafe { edgefirst_gl::gl::Finish() };
                check_gl_error(function!(), line!())?;
                Ok(None)
            }
        }
    }

    // Internal methods operating on Tensor<u8> + PixelFormat directly.

    /// The convert span both the u8 engine and the float route record feed
    /// fields on. Recording sites must use this handle, not `Span::current()`,
    /// because a child (`image.convert.gl.engine`, a two-pass span, or
    /// `nv_to_planar_float`) does not declare `src_feed`/`dst_feed` and
    /// `tracing` drops those records silently.
    pub(super) fn enter_image_convert_gl_span(
        src_fmt: PixelFormat,
        dst_fmt: PixelFormat,
        is_int8: bool,
        src_memory: TensorMemory,
        dst_memory: TensorMemory,
    ) -> tracing::span::EnteredSpan {
        tracing::trace_span!(
            "image.convert.gl",
            ?src_fmt,
            ?dst_fmt,
            is_int8,
            src_memory = ?src_memory,
            dst_memory = ?dst_memory,
            // Recorded at the source-feed site: import | pbo | upload —
            // the zero-copy observable (see ConvertStats).
            src_feed = tracing::field::Empty,
            // Recorded at the destination-feed site for EVERY destination:
            // zero_copy | mapped_texture | pbo -- how the convert's output
            // reached the tensor (see `DstTarget::feed`). It is deliberately
            // not a refusal marker: `zero_copy` and `mapped_texture` are both
            // stated, so a trace never has to read an absent field as "written
            // directly". The field has to be declared here or the record
            // would be a silent no-op.
            dst_feed = tracing::field::Empty,
        )
        .entered()
    }

    #[allow(clippy::too_many_arguments)]
    pub(super) fn convert_impl(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
    ) -> crate::Result<()> {
        let _span = Self::enter_image_convert_gl_span(
            src_fmt,
            dst_fmt,
            is_int8,
            src.memory(),
            dst.memory(),
        );
        if !Self::check_src_format_supported(self.gl_context.transfer_backend, src, src_fmt) {
            if src_fmt == PixelFormat::Vyuy
                && self.gl_context.transfer_backend.is_dma()
                && src.memory() == TensorMemory::DmaBuf
            {
                log::warn!(
                    "VYUY format not supported via EGL DMA-BUF import; \
                     falling back to CPU/G2D path"
                );
            }
            return Err(crate::Error::NotSupported(format!(
                "Opengl doesn't support {src_fmt} source texture",
            )));
        }

        if !Self::dst_format_renderable(
            self.gl_context.transfer_backend,
            dst.memory(),
            dst_fmt,
            self.has_bgra,
        ) {
            return Err(crate::Error::NotSupported(format!(
                "Opengl doesn't support {dst_fmt} destination texture",
            )));
        }

        log::debug!(
            "dst tensor: {:?} src tensor :{:?}",
            dst.memory(),
            src.memory()
        );
        check_gl_error(function!(), line!())?;
        log::trace!(
            "GL convert_impl: {src_fmt}→{dst_fmt} int8={is_int8} \
             src_mem={:?} dst_mem={:?} transfer={:?}",
            src.memory(),
            dst.memory(),
            self.gl_context.transfer_backend,
        );

        self.convert_via_engine(dst, dst_fmt, src, src_fmt, is_int8, rotation, flip, crop)
    }

    /// The single u8/i8 convert engine: classify the destination
    /// ([`super::render::lower_dst`]), pick the render plan
    /// ([`super::render::plan_convert`]), then `bind_dst` → render →
    /// readback. The two-pass plans delegate to their render strategies;
    /// every single-pass convert — DMA, Mem, or PBO on either side — runs
    /// the same code.
    #[allow(clippy::too_many_arguments)]
    fn convert_via_engine(
        &mut self,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
    ) -> crate::Result<()> {
        // Same gate as `bind_dst`, for the destination import that does not go
        // through it: the packed-RGB two-pass plan's pass 2
        // (`convert_to_packed_rgb` -> `get_or_create_egl_image_rgb`), a
        // zero-copy import via `import_buffer_packed`, which on ANGLE binds
        // the whole buffer from its origin. A destination rebuilt from a
        // descriptor carries a plane offset but no `view_origin`, so without
        // this it would still take `DstLowering::ZeroCopy` here and render at
        // the buffer's origin. The RAW `plane_offset` here, not the
        // view-collapsed base: this route passes `plane_offset()` straight to
        // EGL with no `view_origin` collapse (`platform/linux.rs` ~`:199`), so
        // a view destination on it really is imported at its own offset. See
        // `view_collapsed_dst_base` for the route that differs.
        // v1 view()/batch() destination support covers only the SINGLE-PASS
        // PACKED formats. Packed RGB and every planar layout reinterpret the
        // destination geometry (`W*3/4 × H`, `H*3` bands), which neither
        // destination route places a tile in: the zero-copy route's
        // `glViewport`/`glScissor` band is computed in the destination's own
        // pixels, and the mapped-texture route's readback writes `dst_w`-wide
        // rows at the parent's pitch. So such a destination declines here and
        // the CPU backend takes it. (Band tiling for those is a follow-up.)
        //
        // Asked of the destination alone, BEFORE the lowering is chosen, and
        // deliberately: keying it on `lowering == ZeroCopy` left the refusal
        // depending on a decision that can still change underneath it — a
        // refused import re-plans onto the mapped-texture route below, and the
        // guard would then wave the very destination it exists to refuse
        // straight onto a path that cannot place it either.
        if dst.view_origin().is_some()
            && (dst_fmt == PixelFormat::Rgb || dst_fmt.layout() == PixelLayout::Planar)
        {
            return Err(crate::Error::NotSupported(
                "GL view()/batch() destination not yet supported for packed-RGB / \
                 planar formats (CPU fallback handles it)"
                    .into(),
            ));
        }
        let dst_offset = view_collapsed_dst_base(dst.view_origin(), dst.plane_offset());
        // Adreno accepts a destination import at an unaligned base and renders
        // to the wrong place without an EGL error (Vivante refuses it loudly,
        // Mali and V3D render correctly), so the refusal has to be predicted.
        let places = Platform::dst_import_places(dst)
            && !(self.is_adreno && unaligned_import_offset(dst_offset));
        if !places {
            log::debug!(
                "convert_via_engine: zero-copy destination importing at base offset \
                 {dst_offset} cannot be placed by this platform/driver; rendering \
                 to a texture and reading back through map()"
            );
        }
        // The `image.convert.gl` span, captured BEFORE the engine span below is
        // entered, because that is the span the feed fields belong to. A
        // `Span::current()` inside the engine span (or inside a two-pass
        // pass span) names a child that does not declare them, and a record
        // against an undeclared field is a silent no-op.
        let convert_span = tracing::Span::current();
        let mut lowering = super::render::lower_dst(
            self.gl_context.transfer_backend.is_zero_copy() && places,
            self.usable_memory(dst.memory(), dst.pbo_vtable_ptr()),
        );
        // A PBO counts as host here: it has no import either, and only the
        // upload path can read it.
        let src_host = matches!(
            src.memory(),
            TensorMemory::Mem | TensorMemory::Shm | TensorMemory::Pbo
        );
        let mut plan = super::render::plan_convert(src_fmt, src_host, dst_fmt, lowering);
        // The packed-RGB plan imports the destination in its pass 2, AFTER
        // pass 1 has rendered, and a texture-lowered RGB destination is a
        // different plan entirely (one genuine RGB pass, no W*3/4
        // reinterpretation). So the import is asked for here, before any
        // rendering: a refusal re-plans onto the mapped-texture path instead
        // of ending the convert, and the pass-2 call that follows is a cache
        // hit. `bind_dst` needs no equivalent — it can fall back in place,
        // and its guard covers the attach as well as the import.
        if plan == super::render::ConvertPlan::TwoPassPackedRgb {
            match self.probe_packed_rgb_dst_import(dst, dst_fmt) {
                // The packed-RGB plan never reaches `bind_dst` -- its pass 2
                // attaches the import itself -- so the feed is recorded here
                // instead, with the same vocabulary, rather than leaving this
                // one route silent.
                Ok(()) => {
                    convert_span.record("dst_feed", DstTarget::ZeroCopyImage.feed());
                }
                // The probe declines the fallback too, for the same reason
                // `bind_dst` does: it is answering the probe's question, not
                // serving a caller's convert.
                Err(e) if self.probe_dst_import_only => return Err(e),
                Err(e) => {
                    self.note_dst_import_fallback(dst, dst_fmt, &e);
                    lowering = super::render::lower_dst(false, dst.memory());
                    plan = super::render::plan_convert(src_fmt, src_host, dst_fmt, lowering);
                }
            }
        }
        let _span = tracing::trace_span!(
            "image.convert.gl.engine",
            ?plan,
            ?lowering,
            src_pbo = src.memory() == TensorMemory::Pbo,
        )
        .entered();

        match plan {
            super::render::ConvertPlan::TwoPassPackedRgb => {
                return self.convert_to_packed_rgb(
                    src,
                    src_fmt,
                    dst,
                    dst_fmt,
                    is_int8,
                    rotation,
                    flip,
                    crop,
                    &convert_span,
                )
            }
            super::render::ConvertPlan::TwoPassNvPlanar => {
                return self.convert_nv_to_planar_two_pass(
                    src,
                    src_fmt,
                    dst,
                    dst_fmt,
                    is_int8,
                    rotation,
                    flip,
                    crop,
                    lowering,
                    &convert_span,
                )
            }
            super::render::ConvertPlan::SinglePass => {}
        }

        let (target, bound) = self.bind_dst(dst, dst_fmt, crop, lowering)?;
        // A refused import changed the lowering underneath the plan that was
        // chosen against `ZeroCopy`. Re-plan against what was actually bound:
        // the pair `(SinglePass, TextureMem)` is legal for a PACKED
        // destination and not for a planar one, where the single-pass planar
        // shader imports its source unconditionally -- so a heap source would
        // have failed out to the CPU backend instead of completing through
        // the fallback that had just been set up for it.
        //
        // The two-pass plan binds the destination itself, at its pass 2, so
        // the bind above is discarded; that costs one texture setup on a path
        // the driver has already made slow, and keeps the "one plan, one
        // route" invariant `plan_convert` documents.
        let replanned = super::render::plan_convert(src_fmt, src_host, dst_fmt, bound);
        if replanned != super::render::ConvertPlan::SinglePass {
            debug_assert_eq!(
                replanned,
                super::render::ConvertPlan::TwoPassNvPlanar,
                "a texture lowering can only re-plan onto the planar two-pass route"
            );
            return self.convert_nv_to_planar_two_pass(
                src,
                src_fmt,
                dst,
                dst_fmt,
                is_int8,
                rotation,
                flip,
                crop,
                bound,
                &convert_span,
            );
        }
        Self::record_dst_feed(&convert_span, target);
        // A `view()`/`batch()` destination is placed by a band viewport ONLY
        // where the render target is the shared parent import
        // (`setup_renderbuffer_dma`). The texture lowerings render into an
        // offscreen target that is the tile itself, at origin (0, 0), and
        // place it in the readback instead, so they must not carry the band
        // into `glScissor` — doing so clipped away the tile's own left/top
        // edge and left the previous frame's pixels there (issue #177).
        let band = match target {
            DstTarget::ZeroCopyImage => dst.view_origin(),
            DstTarget::Texture { .. } => None,
        };

        // Bias the letterbox clear colour for int8 on every lowering: the
        // fragment shader XORs rendered pixels and no readback un-biases,
        // so the glClear'd letterbox region must be pre-biased.
        let crop = self.int8_bias_clear(is_int8, crop);

        let start = Instant::now();
        self.render_packed_or_planar(
            src,
            src_fmt,
            dst,
            dst_fmt,
            band,
            is_int8,
            rotation,
            flip,
            crop,
            &convert_span,
        )?;
        log::debug!("engine render ({plan:?}) takes {:?}", start.elapsed());

        if let DstTarget::Texture { readback } = target {
            // Data is already int8-biased by the shader — readback copies bytes.
            let start = Instant::now();
            self.readback_rendered(dst, dst_fmt, readback.pbo_id())?;
            log::debug!("engine readback takes {:?}", start.elapsed());
        }
        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    pub(super) fn draw_decoded_masks_impl(
        &mut self,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        detect: &[DetectBox],
        segmentation: &[Segmentation],
        opacity: f32,
        background: Option<(&Tensor<u8>, PixelFormat)>,
        color_mode: crate::ColorMode,
    ) -> Result<(), crate::Error> {
        use crate::FunctionTimer;

        let _timer = FunctionTimer::new("GLProcessorST::draw_decoded_masks");
        if !matches!(
            dst_fmt,
            PixelFormat::Rgba | PixelFormat::Bgra | PixelFormat::Rgb
        ) {
            return Err(crate::Error::NotSupported(
                "Opengl image rendering only supports RGBA, BGRA, or RGB images".to_string(),
            ));
        }

        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let memory = self.usable_memory(dst.memory(), dst.pbo_vtable_ptr());
        // Trace logs are expensive to format (struct Debug, env reads). Gate
        // on the global level filter so they're a single integer compare
        // when trace logging is disabled.
        if log::log_enabled!(log::Level::Trace) {
            log::trace!(
                "draw_decoded_masks: dst.memory()={memory:?} {dst_w}x{dst_h} fmt={dst_fmt:?}"
            );
        }
        let pbo_buffer_id = if memory == TensorMemory::Pbo {
            match (dst.pbo_id(), dst.pbo_is_mapped()) {
                (Some(id), Some(false)) => Some(id),
                _ => None,
            }
        } else {
            None
        };

        let is_dma = match memory {
            TensorMemory::DmaBuf => match self.setup_draw_renderbuffer_dma(dst, dst_fmt) {
                Ok(()) => {
                    if log::log_enabled!(log::Level::Trace) {
                        log::trace!(
                            "draw_decoded_masks: DMA fast path (setup_draw_renderbuffer_dma OK)"
                        );
                    }
                    true
                }
                Err(e) => {
                    warn_slow_path_once("draw_decoded_masks", "setup_draw_renderbuffer_dma", &e);
                    if let Some(buffer_id) = pbo_buffer_id {
                        self.setup_renderbuffer_from_pbo(dst, dst_fmt, buffer_id)?;
                    } else {
                        self.setup_renderbuffer_non_dma(dst, dst_fmt, ResolvedCrop::no_crop())?;
                    }
                    false
                }
            },
            _ if pbo_buffer_id.is_some() => {
                if log::log_enabled!(log::Level::Trace) {
                    log::trace!("draw_decoded_masks: PBO path");
                }
                self.setup_renderbuffer_from_pbo(dst, dst_fmt, pbo_buffer_id.unwrap())?;
                false
            }
            _ => {
                if log::log_enabled!(log::Level::Trace) {
                    log::trace!("draw_decoded_masks: non-DMA fallback (memory={memory:?})");
                }
                self.setup_renderbuffer_non_dma(dst, dst_fmt, ResolvedCrop::no_crop())?;
                false
            }
        };

        // Write the base layer of the framebuffer *before* running mask
        // passes.  The framebuffer's backing storage (DMA renderbuffer or
        // render_texture) may contain stale pixels from a previous frame
        // in a triple-buffered pipeline, so we always actively write it.
        //
        // - background + zero-copy destination: draw bg into the
        //   destination framebuffer itself (see
        //   `draw_background_into_bound_fbo`).
        // - background + non-DMA destination: upload bg pixels into the
        //   render_texture that backs the FBO (glTexImage2D). The CPU
        //   memcpy is into a GL texture, not into the user's DMA buffer, so
        //   it's a pure upload — not a cache-flushing mapped copy.
        // - no background: glClear(0x00000000) on the framebuffer.
        if let Some((bg, bg_fmt)) = background {
            if bg.width() != Some(dst_w) || bg.height() != Some(dst_h) {
                return Err(crate::Error::InvalidShape(
                    "background dimensions do not match dst".into(),
                ));
            }
            if is_dma {
                self.draw_background_into_bound_fbo(bg, bg_fmt)?;
            } else {
                // Non-DMA destination: upload bg pixels into the
                // render_texture attached to the FBO. Writing to dst
                // directly would be wrong — the final readback later
                // overwrites dst with the framebuffer contents, so we
                // have to seed the framebuffer itself.
                self.upload_pixels_to_render_texture(bg, bg_fmt, dst_w, dst_h)?;
            }
        } else {
            // No background: actively clear the framebuffer so stale
            // pixels from the previous frame do not leak into the output.
            unsafe {
                edgefirst_gl::gl::ClearColor(0.0, 0.0, 0.0, 0.0);
                edgefirst_gl::gl::Clear(edgefirst_gl::gl::COLOR_BUFFER_BIT);
            }
        }

        edgefirst_gl::enable(edgefirst_gl::gl::BLEND);
        edgefirst_gl::blend_func_separate(
            edgefirst_gl::gl::SRC_ALPHA,
            edgefirst_gl::gl::ONE_MINUS_SRC_ALPHA,
            edgefirst_gl::gl::ZERO,
            edgefirst_gl::gl::ONE,
        );

        self.set_opacity_uniform(opacity)?;
        self.render_box(dst_w, dst_h, detect, color_mode)?;
        self.render_segmentation(detect, segmentation, color_mode)?;

        edgefirst_gl::finish();
        if !is_dma {
            let format = match dst_fmt {
                PixelFormat::Rgb => edgefirst_gl::gl::RGB,
                PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA,
                _ => unreachable!(),
            };
            if let Some(buffer_id) = pbo_buffer_id {
                self.read_pixels_into_pbo(
                    dst,
                    buffer_id,
                    dst_w,
                    dst_h,
                    format,
                    dst_fmt == PixelFormat::Bgra,
                )?;
            } else {
                self.read_pixels_into_tensor(
                    dst,
                    dst_w,
                    dst_h,
                    format,
                    dst_fmt == PixelFormat::Bgra,
                )?;
            }
        }

        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    pub(super) fn draw_proto_masks_impl(
        &mut self,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        detect: &[DetectBox],
        proto_data: &ProtoData,
        opacity: f32,
        background: Option<(&Tensor<u8>, PixelFormat)>,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        use crate::FunctionTimer;

        let _timer = FunctionTimer::new("GLProcessorST::draw_proto_masks");
        if !matches!(
            dst_fmt,
            PixelFormat::Rgba | PixelFormat::Bgra | PixelFormat::Rgb
        ) {
            return Err(crate::Error::NotSupported(
                "Opengl image rendering only supports RGBA, BGRA, or RGB images".to_string(),
            ));
        }

        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let memory = self.usable_memory(dst.memory(), dst.pbo_vtable_ptr());
        if log::log_enabled!(log::Level::Trace) {
            log::trace!(
                "draw_proto_masks: dst.memory()={memory:?} {dst_w}x{dst_h} fmt={dst_fmt:?}"
            );
        }
        let pbo_buffer_id = if memory == TensorMemory::Pbo {
            match (dst.pbo_id(), dst.pbo_is_mapped()) {
                (Some(id), Some(false)) => Some(id),
                _ => None,
            }
        } else {
            None
        };

        let is_dma = match memory {
            TensorMemory::DmaBuf => match self.setup_draw_renderbuffer_dma(dst, dst_fmt) {
                Ok(()) => {
                    if log::log_enabled!(log::Level::Trace) {
                        log::trace!(
                            "draw_proto_masks: DMA fast path (setup_draw_renderbuffer_dma OK)"
                        );
                    }
                    true
                }
                Err(e) => {
                    warn_slow_path_once("draw_proto_masks", "setup_draw_renderbuffer_dma", &e);
                    if let Some(buffer_id) = pbo_buffer_id {
                        self.setup_renderbuffer_from_pbo(dst, dst_fmt, buffer_id)?;
                    } else {
                        self.setup_renderbuffer_non_dma(dst, dst_fmt, ResolvedCrop::no_crop())?;
                    }
                    false
                }
            },
            _ if pbo_buffer_id.is_some() => {
                if log::log_enabled!(log::Level::Trace) {
                    log::trace!("draw_proto_masks: PBO path");
                }
                self.setup_renderbuffer_from_pbo(dst, dst_fmt, pbo_buffer_id.unwrap())?;
                false
            }
            _ => {
                if log::log_enabled!(log::Level::Trace) {
                    log::trace!("draw_proto_masks: non-DMA fallback (memory={memory:?})");
                }
                self.setup_renderbuffer_non_dma(dst, dst_fmt, ResolvedCrop::no_crop())?;
                false
            }
        };

        // Write the base layer of the framebuffer before running mask
        // passes. See `draw_decoded_masks_impl` for the rationale — we
        // never assume dst is cleared on entry.
        if let Some((bg, bg_fmt)) = background {
            if bg.width() != Some(dst_w) || bg.height() != Some(dst_h) {
                return Err(crate::Error::InvalidShape(
                    "background dimensions do not match dst".into(),
                ));
            }
            if is_dma {
                self.draw_background_into_bound_fbo(bg, bg_fmt)?;
            } else {
                self.upload_pixels_to_render_texture(bg, bg_fmt, dst_w, dst_h)?;
            }
        } else {
            unsafe {
                edgefirst_gl::gl::ClearColor(0.0, 0.0, 0.0, 0.0);
                edgefirst_gl::gl::Clear(edgefirst_gl::gl::COLOR_BUFFER_BIT);
            }
        }

        edgefirst_gl::enable(edgefirst_gl::gl::BLEND);
        edgefirst_gl::blend_func_separate(
            edgefirst_gl::gl::SRC_ALPHA,
            edgefirst_gl::gl::ONE_MINUS_SRC_ALPHA,
            edgefirst_gl::gl::ZERO,
            edgefirst_gl::gl::ONE,
        );

        self.set_opacity_uniform(opacity)?;
        self.render_box(dst_w, dst_h, detect, color_mode)?;
        self.render_proto_segmentation(detect, proto_data, color_mode)?;
        // Leave blending off, as `draw_decoded_masks_impl` does on its drawing
        // path at the end of `render_segmentation`. Blend-off is this file's resting state -- a
        // path that needs blending enables it on entry, as both mask draws do
        // -- and every drawing call above has already been issued, so this
        // changes nothing about what was composited, only what a later
        // operation on this processor inherits -- which until now was the
        // mask draw's `SRC_ALPHA, ONE_MINUS_SRC_ALPHA`, still enabled.
        edgefirst_gl::disable(edgefirst_gl::gl::BLEND);

        edgefirst_gl::finish();
        if !is_dma {
            let format = match dst_fmt {
                PixelFormat::Rgb => edgefirst_gl::gl::RGB,
                PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA,
                _ => unreachable!(),
            };
            if let Some(buffer_id) = pbo_buffer_id {
                self.read_pixels_into_pbo(
                    dst,
                    buffer_id,
                    dst_w,
                    dst_h,
                    format,
                    dst_fmt == PixelFormat::Bgra,
                )?;
            } else {
                self.read_pixels_into_tensor(
                    dst,
                    dst_w,
                    dst_h,
                    format,
                    dst_fmt == PixelFormat::Bgra,
                )?;
            }
        }

        Ok(())
    }

    pub(super) fn check_src_format_supported(
        backend: TransferBackend,
        img: &Tensor<u8>,
        fmt: PixelFormat,
    ) -> bool {
        if backend.is_zero_copy() && img.memory() == TensorMemory::DmaBuf {
            // Zero-copy import path supports:
            //   Path A (samplerExternalOES): RGBA, GREY, YUYV, NV12
            //   Path B (R8 texelFetch shader): NV16, NV24 (contiguous only)
            // VYUY excluded: Vivante GPU accepts the DRM fourcc but produces
            // incorrect output (similarity ~0.28 vs reference).
            // NV16/NV24 use Path B — the contiguous-only check is enforced at
            // EGLImage creation time in `from_tensor_nv_r8`; multiplane
            // sources fall back to CPU via the error path.
            matches!(
                fmt,
                PixelFormat::Rgba
                    | PixelFormat::Grey
                    | PixelFormat::Yuyv
                    | PixelFormat::Nv12
                    | PixelFormat::Nv16
                    | PixelFormat::Nv24
            )
        } else {
            // Non-DMA (PBO/Sync): packed RGB(A)/Grey upload via
            // draw_src_texture, plus single-plane NV12/NV16/NV24 via the
            // R8-upload ShaderR8 path (combined buffer uploaded as R8 +
            // in-shader YUV). Multiplane NV12 can't be uploaded as one R8
            // texture and falls to CPU.
            //
            // YUYV (uploaded as RG for the YUYV program), and any NV source
            // in a PBO, only where the platform has no zero-copy import: there
            // the upload is the GPU route, and it beats the CPU several times
            // over (Tegra). Where import exists, such a source is one the
            // DMA-BUF heap could not place, and the upload is the slow road --
            // Mesa V3D's PBO upload runs well behind the CPU converter -- so
            // those stay on the CPU.
            let uploads_yuv = !backend.is_zero_copy();
            let nv_single_plane = matches!(
                fmt,
                PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
            ) && !img.is_multiplane();
            matches!(
                fmt,
                PixelFormat::Rgb | PixelFormat::Rgba | PixelFormat::Grey
            ) || (fmt == PixelFormat::Yuyv && uploads_yuv)
                || (nv_single_plane && (img.memory() != TensorMemory::Pbo || uploads_yuv))
        }
    }

    /// Whether the GL backend renders a `fmt` destination held in `memory`;
    /// a destination it declines is filled by the CPU fallback instead.
    pub(crate) fn dst_format_renderable(
        backend: TransferBackend,
        memory: TensorMemory,
        fmt: PixelFormat,
        has_bgra: bool,
    ) -> bool {
        if fmt == PixelFormat::Bgra && !has_bgra {
            return false;
        }
        if backend.is_zero_copy() && memory == TensorMemory::DmaBuf {
            matches!(
                fmt,
                PixelFormat::Rgba
                    | PixelFormat::Bgra
                    | PixelFormat::Grey
                    | PixelFormat::PlanarRgb
                    | PixelFormat::PlanarRgba
                    | PixelFormat::Rgb
            )
        } else {
            // Planar RGB(A) into heap (`Mem`) or `Pbo` memory routes through
            // `plan_convert`'s two-pass plan (`TwoPassNvPlanar`, selected
            // for every source format on a texture lowering — see its doc),
            // not the single-pass planar shader: that shader needs
            // `Platform::EXTERNAL_OES` (unavailable on ANGLE/Android) and a
            // DMA-importable source. `readback_rendered` recovers the
            // single-channel (R8) render target — full dst_w, `channels`
            // planes stacked in height, no multi-byte-per-texel packing —
            // into the destination's CHW layout.
            matches!(
                fmt,
                PixelFormat::Rgb
                    | PixelFormat::Rgba
                    | PixelFormat::Bgra
                    | PixelFormat::Grey
                    | PixelFormat::PlanarRgb
                    | PixelFormat::PlanarRgba
            )
        }
    }

    /// Query GL capabilities and detect GPU vendor/renderer type — see
    /// [`GlSupport`]. The two float-color flags report whether the GPU can
    /// render to F32 / F16 color attachments (independent extensions: a
    /// configuration may have one but not the other), surfaced via
    /// `RenderDtypeSupport`.
    fn gl_check_support() -> Result<GlSupport, crate::Error> {
        if let Ok(version) = edgefirst_gl::get_string(edgefirst_gl::gl::SHADING_LANGUAGE_VERSION) {
            log::debug!("GL Shading Language Version: {version:?}");
        } else {
            log::warn!("Could not get GL Shading Language Version");
        }

        // Detect GPU vendor / software / virtualized renderers via GL_RENDERER.
        let mut traits = edgefirst_gl::get_string(edgefirst_gl::gl::RENDERER)
            .map(|r| {
                log::info!("GL_RENDERER: {r}");
                classify_renderer(&r)
            })
            .unwrap_or_default();
        // The Adreno workarounds are measured on the proprietary Linux (KGSL)
        // driver. Android's Adreno system EGL is device-validated thread-safe
        // and imports through AHardwareBuffer, so none of them apply there.
        traits.adreno &= cfg!(target_os = "linux");
        let RendererTraits {
            vivante: is_vivante,
            mali: is_mali,
            software: is_software_renderer,
            virtual_gpu: is_virtual_gpu,
            angle: is_angle,
            adreno: is_adreno,
        } = traits;
        if is_vivante {
            log::warn!(
                "Vivante GPU detected — NV12 → planar RGB conversions will use \
                 two-pass workaround to avoid GPU hang (EDGEAI-1180)"
            );
        }
        if is_mali {
            log::info!(
                "Mali GPU detected — a source DMA-BUF whose plane offset is not \
                 {DMA_IMPORT_OFFSET_ALIGN}-byte aligned will be uploaded \
                 rather than imported: Mali's import samples zeros from such an \
                 offset without reporting an EGL error (issue #165)"
            );
        }
        if is_software_renderer {
            log::warn!(
                "Software OpenGL renderer detected — GPU backend will be disabled. \
                 Image processing will use the CPU backend instead. \
                 Check EGL ICD configuration if a hardware GPU is expected."
            );
        }
        if is_virtual_gpu {
            log::warn!(
                "Virtualized GPU detected — concurrent GL across contexts \
                 mis-renders on paravirtual Metal (observed on macOS CI \
                 runners); processors will serialize per-message (Full \
                 policy, same as Vivante). Override with \
                 EDGEFIRST_GL_SERIALIZE=lifecycle."
            );
        } else if is_angle {
            log::info!(
                "ANGLE detected — a deferred draw does not reliably execute \
                 with the per-draw state its own processor programmed while \
                 another context is active, so processors will serialize \
                 per-message (Full policy). Costs throughput only when one \
                 process runs several ImageProcessors concurrently. Override \
                 with EDGEFIRST_GL_SERIALIZE=lifecycle."
            );
        }
        if is_adreno {
            log::info!(
                "Adreno GPU detected — processors will serialize per-message \
                 (Full policy; override with EDGEFIRST_GL_SERIALIZE=lifecycle), \
                 DMA-BUF imports at a plane offset that is not \
                 {DMA_IMPORT_OFFSET_ALIGN}-byte aligned and two-buffer NV12 \
                 sources take the upload / readback routes"
            );
        }

        let extensions = unsafe {
            let str = edgefirst_gl::gl::GetString(edgefirst_gl::gl::EXTENSIONS);
            if str.is_null() {
                return Err(crate::Error::GLVersion(
                    "GL returned no supported extensions".to_string(),
                ));
            }
            CStr::from_ptr(str as *const c_char)
                .to_string_lossy()
                .to_string()
        };
        log::debug!("GL Extensions: {extensions}");
        // The external-OES sampler is required only where the platform's
        // import binding uses it (Linux Path A); ANGLE/Metal binds every
        // import as TEXTURE_2D and never exposes the extension.
        let required_ext: &[&str] = if Platform::EXTERNAL_OES {
            &["GL_OES_EGL_image_external_essl3"]
        } else {
            &[]
        };
        let extensions = extensions.split_ascii_whitespace().collect::<BTreeSet<_>>();
        for required in required_ext {
            if !extensions.contains(required) {
                return Err(crate::Error::GLVersion(format!(
                    "GL does not support {required} extension",
                )));
            }
        }

        // EDGEFIRST_GL_NO_FLOAT_LINEAR=1 forces the capability off so the
        // f32→f16-repack proto fallback (taken only on GPUs lacking the
        // extension) is reachable on float-linear-capable lanes — no CI lane
        // has such a GPU, so without the override the fallback arm has zero
        // coverage anywhere.
        let force_no_float_linear = std::env::var("EDGEFIRST_GL_NO_FLOAT_LINEAR")
            .map(|v| v == "1")
            .unwrap_or(false);
        let has_float_linear =
            extensions.contains("GL_OES_texture_float_linear") && !force_no_float_linear;
        if force_no_float_linear {
            log::info!("GL_OES_texture_float_linear forced OFF via EDGEFIRST_GL_NO_FLOAT_LINEAR");
        }
        log::debug!("GL_OES_texture_float_linear: {has_float_linear}");

        let has_bgra = extensions.contains("GL_EXT_texture_format_BGRA8888");
        log::debug!("GL_EXT_texture_format_BGRA8888: {has_bgra}");

        // Float-color-buffer extensions gate F32/F16 destinations on the
        // IOSurface render path. The two extensions are independent: a
        // configuration may expose one but not the other, so consumers
        // (e.g. profiler/ORT CoreML path) probe each separately and pick
        // the preferred dtype.
        let supports_f32_color = extensions.contains("GL_EXT_color_buffer_float");
        let supports_f16_color = extensions.contains("GL_EXT_color_buffer_half_float");
        log::debug!("GL_EXT_color_buffer_float: {supports_f32_color}");
        log::debug!("GL_EXT_color_buffer_half_float: {supports_f16_color}");

        let has_yuv_target = Platform::EXTERNAL_OES && extensions.contains("GL_EXT_YUV_target");
        log::debug!("GL_EXT_YUV_target: {has_yuv_target}");

        Ok(GlSupport {
            has_float_linear,
            has_yuv_target,
            has_bgra,
            renderer: traits,
            supports_f32_color,
            supports_f16_color,
        })
    }

    /// Invalidate EGL binding state on all destination textures.
    /// Called when the dst EGLImage cache evicts or sweeps entries.
    fn invalidate_dst_textures(&mut self) {
        self.render_texture.invalidate_egl_binding();
        self.draw_render_texture.invalidate_egl_binding();
    }

    /// Invalidate EGL binding state on all source textures.
    /// Called when the src EGLImage cache evicts or sweeps entries.
    fn invalidate_src_textures(&mut self) {
        self.camera_eglimage_texture.invalidate_egl_binding();
        self.nv_r8_texture.invalidate_egl_binding();
        self.nv_uv_texture.invalidate_egl_binding();
        self.camera_normal_texture.invalidate_egl_binding();
    }

    /// Ask the driver for the packed-RGB plan's destination import before any
    /// rendering happens, so a refusal can re-plan.
    ///
    /// Exactly the import `convert_to_packed_rgb`'s pass 2 makes — same
    /// surface geometry, same packed format — so a success here is the cache
    /// entry pass 2 will hit and costs nothing twice.
    ///
    /// `Ok(())` when there is nothing to ask: a geometry that does not resolve
    /// (a width whose `W*3` bytes do not divide into whole RGBA texels) is not
    /// a driver refusal, so it is left for pass 2 to report exactly as it does
    /// today rather than being reported here as a fallback.
    fn probe_packed_rgb_dst_import(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
    ) -> crate::Result<()> {
        let (Some(dst_w), Some(dst_h)) = (dst.width(), dst.height()) else {
            return Ok(());
        };
        let Some(layout) = edgefirst_tensor::packed_rgb888_layout(dst_w, dst_h) else {
            return Ok(());
        };
        self.get_or_create_egl_image_rgb(
            dst,
            dst_fmt,
            layout.surface_w,
            layout.surface_h,
            super::platform::PackedImportFormat::Rgba8888,
        )
        .map(|_| ())
    }

    /// Record a zero-copy destination import that the driver refused, and
    /// leave GL in a state the mapped-texture setup can start from.
    ///
    /// The destination-side twin of the source arms' decline handling: count
    /// it in [`ConvertStats::dst_import_fallbacks`], warn once per buffer and
    /// debug on the repeats (`dst_import_warned`, the shape `nv_import_warned`
    /// already has), and drain the GL error queue. Draining matters because
    /// the refusal can be a GL error rather than an EGL one — attaching the
    /// image raises `GL_INVALID_OPERATION` on some desktop drivers — and
    /// `check_gl_error` reads one flag per call, so a leftover flag would
    /// surface as a spurious failure of the fallback that follows.
    ///
    /// [`ConvertStats::dst_import_fallbacks`]: super::cache::ConvertStats::dst_import_fallbacks
    fn note_dst_import_fallback(&mut self, dst: &Tensor<u8>, dst_fmt: PixelFormat, e: &Error) {
        self.convert_stats.dst_import_fallbacks += 1;
        let w = dst.width().unwrap_or(0);
        let h = dst.height().unwrap_or(0);
        let offset = dst.plane_offset().unwrap_or(0);
        if self.dst_import_warned.insert(dst.buffer_identity().id()) {
            log::warn!(
                "zero-copy destination import refused for {dst_fmt} ({w}x{h}) at plane \
                 offset {offset}; rendering to a texture and reading back through map() \
                 (slower, still correct): {e}"
            );
        } else {
            log::debug!(
                "zero-copy destination import refused for {dst_fmt} ({w}x{h}) at plane \
                 offset {offset} (repeat): {e}"
            );
        }
        // Bounded: a driver reports a small fixed set of flags, and the loop
        // ends at the first NO_ERROR either way.
        unsafe {
            for _ in 0..8 {
                if edgefirst_gl::gl::GetError() == edgefirst_gl::gl::NO_ERROR {
                    break;
                }
            }
        }
    }

    /// Classify and bind the destination render target — the single entry
    /// point absorbing the per-memory `setup_renderbuffer_*` fan-out. The
    /// pure classification lives in [`super::render::lower_dst`]; this
    /// performs the GL work and tells the caller what completes the convert.
    fn bind_dst(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
        crop: ResolvedCrop,
        lowering: super::render::DstLowering,
    ) -> crate::Result<(DstTarget, super::render::DstLowering)> {
        // The lowering goes IN as the caller's and comes back as the effective
        // one, and both halves matter.
        //
        // In, because `convert_via_engine` pairs it with a `ConvertPlan`: a
        // refused packed-RGB import re-plans onto the mapped route, and asking
        // `dst_import_places` again here would answer `true` (the IMPORT
        // failed, the PLACEMENT is fine), bind a zero-copy destination under a
        // plan chosen for a texture one.
        //
        // Out, because a refusal DISCOVERED here changes it: the caller's plan
        // was chosen against `ZeroCopy` and may not be legal against the
        // texture lowering the fallback just took. Returning it lets the
        // caller re-plan instead of rendering the stale route.
        let effective = match lowering {
            super::render::DstLowering::ZeroCopy => {
                // A destination import that FAILS lowers the convert to the
                // mapped-texture readback, exactly as a failed source import
                // lowers to the upload path -- rather than ending the convert
                // and sending the whole thing to the CPU backend. That is what
                // replaced the per-driver refusal predicates: Vivante's
                // `eglCreateImage` returns `EGL_BAD_ACCESS` for a destination
                // at an offset that is not 64-byte aligned, and the refusal
                // itself is now the trigger, so a future driver quirk of the
                // same kind needs no new trait (issue #175).
                //
                // The whole zero-copy setup is guarded, not just the import
                // call: attaching the image to the texture and the FBO can
                // fail after `eglCreateImage` succeeded (a desktop NVIDIA EGL
                // raises `GL_INVALID_OPERATION` there), and either way the
                // destination has not been written yet.
                match self.setup_renderbuffer_dma(dst, dst_fmt) {
                    Ok(()) => (DstTarget::ZeroCopyImage, lowering),
                    Err(e) if self.probe_dst_import_only => return Err(e),
                    Err(e) => {
                        self.note_dst_import_fallback(dst, dst_fmt, &e);
                        self.setup_renderbuffer_non_dma(dst, dst_fmt, crop)?;
                        (
                            DstTarget::Texture {
                                readback: DstReadback::Mem,
                            },
                            super::render::DstLowering::TextureMem,
                        )
                    }
                }
            }
            super::render::DstLowering::TexturePbo => {
                let id = dst.pbo_id().ok_or_else(|| {
                    crate::Error::OpenGl(
                        "bind_dst: PBO-lowered destination is not a PBO tensor".to_string(),
                    )
                })?;
                if dst.pbo_is_mapped() == Some(true) {
                    return Err(crate::Error::OpenGl(
                        "Cannot convert to a mapped PBO tensor".to_string(),
                    ));
                }
                self.setup_renderbuffer_from_pbo(dst, dst_fmt, id)?;
                (
                    DstTarget::Texture {
                        readback: DstReadback::Pbo(id),
                    },
                    lowering,
                )
            }
            super::render::DstLowering::TextureMem => {
                self.setup_renderbuffer_non_dma(dst, dst_fmt, crop)?;
                (
                    DstTarget::Texture {
                        readback: DstReadback::Mem,
                    },
                    lowering,
                )
            }
        };
        Ok(effective)
    }

    /// Record how the convert's output will reach the destination, for EVERY
    /// target and not only a refused import: a field present on some routes
    /// and absent on others reads as "zero-copy" when it really means "nobody
    /// said", which is how an ordinary texture-lowered convert could pass for
    /// a zero-copy one in a trace.
    ///
    /// Called where the route is COMMITTED rather than inside `bind_dst`,
    /// because a bind whose lowering the caller then re-plans away from is not
    /// the route the convert took -- recording there put the same value on the
    /// span twice, which an `fmt` subscriber prints twice.
    fn record_dst_feed(convert_span: &tracing::Span, target: DstTarget) {
        convert_span.record("dst_feed", target.feed());
    }

    fn setup_renderbuffer_dma(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
    ) -> crate::Result<()> {
        self.convert_fbo.bind();
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;

        let (width, height) = if dst_fmt.layout() == PixelLayout::Planar {
            (dst_w as i32, (dst_h * dst_fmt.channels()) as i32)
        } else {
            (dst_w as i32, dst_h as i32)
        };

        let dst_key = BufferImportKey::from_tensor(dst, dst_fmt, true);
        let luma_id = dst_key.luma_id;

        let dest_egl = self.get_or_create_egl_image(CacheKind::Dst, dst, dst_fmt)?;
        match self.cached_dst_renderbuffer(dst, dst_fmt) {
            Some(rbo) => unsafe {
                edgefirst_gl::gl::BindRenderbuffer(edgefirst_gl::gl::RENDERBUFFER, rbo);
                edgefirst_gl::gl::FramebufferRenderbuffer(
                    edgefirst_gl::gl::FRAMEBUFFER,
                    edgefirst_gl::gl::COLOR_ATTACHMENT0,
                    edgefirst_gl::gl::RENDERBUFFER,
                    rbo,
                );
                check_gl_error(function!(), line!())?;
            },
            None => unsafe {
                if let Some(p) = &self.texture_program_yuv {
                    edgefirst_gl::gl::UseProgram(p.id);
                }
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
                edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.render_texture.id);
                super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::LINEAR);
                if self
                    .render_texture
                    .bind_egl_image(&self.gl_context, dst_key, dest_egl)?
                {
                    edgefirst_gl::gl::FramebufferTexture2D(
                        edgefirst_gl::gl::FRAMEBUFFER,
                        edgefirst_gl::gl::COLOR_ATTACHMENT0,
                        edgefirst_gl::gl::TEXTURE_2D,
                        self.render_texture.id,
                        0,
                    );
                    log::trace!("setup_renderbuffer_dma: bound new dst EGLImage id={luma_id:#x}");
                } else {
                    log::trace!(
                        "setup_renderbuffer_dma: reusing bound dst EGLImage id={luma_id:#x}"
                    );
                }
                check_gl_error(function!(), line!())?;
            },
        }

        // A view()/batch() destination imported the whole PARENT above (cache key
        // + `DmaImportAttrs` both pivot on `view_origin`); render this tile into
        // its band via `glViewport`. A whole tensor fills its full surface. The
        // matching `glScissor` (so the letterbox clear cannot wipe sibling tiles)
        // is set in `convert_to`, which owns the clear — both lower the band
        // through `region_to_viewport_top_down`, the single home for the
        // verified top-down orientation of the dst DMA EGLImage.
        let vp = match dst.view_origin() {
            Some(vo) => super::render::region_to_viewport_top_down(crate::Region::new(
                vo.x, vo.y, dst_w, dst_h,
            )),
            None => super::render::Viewport {
                x: 0,
                y: 0,
                w: width,
                h: height,
            },
        };
        unsafe {
            edgefirst_gl::gl::Viewport(vp.x, vp.y, vp.w, vp.h);
        }
        Ok(())
    }

    /// Variant of [`setup_renderbuffer_dma`] used exclusively by draw operations
    /// (`draw_decoded_masks`, `draw_proto_masks`).
    ///
    /// Uses a dedicated FBO (`draw_fbo`) and texture (`draw_render_texture`) so
    /// that `EGLImageTargetTexture2DOES` calls made during convert do not
    /// invalidate the draw path's cached binding, and vice versa.  On Vivante
    /// GC7000UL (texture path, `use_renderbuffer = false`) each
    /// `EGLImageTargetTexture2DOES` call costs ~4–11 ms, so eliminating the
    /// cross-path invalidation removes two redundant calls per frame when both
    /// convert and draw are active.
    fn setup_draw_renderbuffer_dma(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
    ) -> crate::Result<()> {
        self.draw_fbo.bind();
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;

        let (width, height) = if dst_fmt.layout() == PixelLayout::Planar {
            (dst_w as i32, (dst_h * dst_fmt.channels()) as i32)
        } else {
            (dst_w as i32, dst_h as i32)
        };

        let dst_key = BufferImportKey::from_tensor(dst, dst_fmt, true);
        let luma_id = dst_key.luma_id;

        let dest_egl = self.get_or_create_egl_image(CacheKind::Dst, dst, dst_fmt)?;
        match self.cached_dst_renderbuffer(dst, dst_fmt) {
            Some(rbo) => unsafe {
                edgefirst_gl::gl::BindRenderbuffer(edgefirst_gl::gl::RENDERBUFFER, rbo);
                edgefirst_gl::gl::FramebufferRenderbuffer(
                    edgefirst_gl::gl::FRAMEBUFFER,
                    edgefirst_gl::gl::COLOR_ATTACHMENT0,
                    edgefirst_gl::gl::RENDERBUFFER,
                    rbo,
                );
                check_gl_error(function!(), line!())?;
            },
            None => unsafe {
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
                edgefirst_gl::gl::BindTexture(
                    edgefirst_gl::gl::TEXTURE_2D,
                    self.draw_render_texture.id,
                );
                super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::LINEAR);
                if self
                    .draw_render_texture
                    .bind_egl_image(&self.gl_context, dst_key, dest_egl)?
                {
                    edgefirst_gl::gl::FramebufferTexture2D(
                        edgefirst_gl::gl::FRAMEBUFFER,
                        edgefirst_gl::gl::COLOR_ATTACHMENT0,
                        edgefirst_gl::gl::TEXTURE_2D,
                        self.draw_render_texture.id,
                        0,
                    );
                    log::trace!(
                        "setup_draw_renderbuffer_dma: bound new dst EGLImage id={luma_id:#x}"
                    );
                } else {
                    log::trace!(
                        "setup_draw_renderbuffer_dma: reusing bound dst EGLImage id={luma_id:#x}"
                    );
                }
                check_gl_error(function!(), line!())?;
            },
        }

        unsafe {
            edgefirst_gl::gl::Viewport(0, 0, width, height);
        }
        Ok(())
    }

    /// The int8 programs, whose `quantize()` uniforms `load_int_quant` sets,
    /// with their `quantize()` uniform locations in [`Self::upload_quant`] order.
    fn collect_int8_programs(&self) -> Vec<(u32, [i32; 6])> {
        let mut ids = vec![
            self.texture_int8_program.id,
            self.yuyv_int8_program_2d.id,
            self.packed_rgba8_int8_program_2d.id,
            self.texture_program_planar_int8_2d.id,
        ];
        ids.extend(self.texture_int8_program_yuv.iter().map(|p| p.id));
        ids.extend(self.texture_program_planar_int8.iter().map(|p| p.id));
        // `NvSampling::program`: u8 at even indices, int8 at odd.
        ids.extend(self.nv_r8_programs.iter().skip(1).step_by(2).map(|p| p.id));
        if let Some((programs, _)) = &self.nv_y2y_programs {
            ids.push(programs[1].id);
        }
        ids.into_iter()
            .map(|id| {
                // SAFETY: on the GL thread with this processor's context
                // current; `id` is a linked program and the names C literals.
                let locs = [
                    c"q_scale",
                    c"q_offset",
                    c"q_lo",
                    c"q_hi",
                    c"q_zero",
                    c"q_wrap",
                ]
                .map(|name| unsafe { edgefirst_gl::gl::GetUniformLocation(id, name.as_ptr()) });
                (id, locs)
            })
            .collect()
    }

    /// Upload `q` to one program's `quantize()` uniforms, with the rounding
    /// and zero point folded in so the shader costs what the plain bias did.
    ///
    /// # Safety
    /// On the GL thread with this processor's context current and `id` bound.
    unsafe fn upload_quant(locs: &[i32; 6], q: &IntQuant) {
        let offset = q.offset.map(|o| o + 0.5);
        let lo: [f32; 3] = std::array::from_fn(|c| q.lo[c] - q.zero[c]);
        let hi: [f32; 3] = std::array::from_fn(|c| q.hi[c] - q.zero[c]);
        let zero = q.zero.map(|z| z / 255.0);
        let wrap = q.zero.map(|z| -z - 0.5);
        for (loc, v) in locs.iter().zip([&q.scale, &offset, &lo, &hi, &zero, &wrap]) {
            // SAFETY: the caller's contract.
            unsafe { edgefirst_gl::gl::Uniform3fv(*loc, 1, v.as_ptr()) };
        }
    }

    /// Put the mapped int8 build in the int8 fields when `mapped`, else the
    /// default one, linking the mapped build on first use. The default build
    /// has the plain bias in literals, which Vivante runs measurably faster
    /// than the uniforms.
    fn use_int8_set(&mut self, mapped: bool) -> crate::Result<()> {
        if self.int8_mapped == mapped {
            return Ok(());
        }
        let mut alt = match self.int8_alt.take() {
            Some(alt) => alt,
            None => {
                let set = Int8Set::new(true, self.nv_y2y_programs.is_some())?;
                if set.nv_y2y.is_none() && self.nv_y2y_programs.take().is_some() {
                    log::info!(
                        "the mapped int8 Y2Y program did not build; NV filters in the shader"
                    );
                }
                set
            }
        };
        self.swap_int8_set(&mut alt);
        self.int8_alt = Some(alt);
        self.int8_mapped = mapped;
        if mapped && self.int8_programs.is_empty() {
            self.int8_programs = self.collect_int8_programs();
        }
        Ok(())
    }

    /// Exchange the int8 programs and their link-time state with `set`.
    fn swap_int8_set(&mut self, set: &mut Int8Set) {
        use std::mem::swap;
        swap(&mut self.texture_int8_program, &mut set.texture);
        swap(&mut self.texture_int8_program_yuv, &mut set.texture_yuv);
        swap(&mut self.texture_program_planar_int8, &mut set.planar);
        swap(&mut self.texture_program_planar_int8_2d, &mut set.planar_2d);
        swap(&mut self.yuyv_int8_program_2d, &mut set.yuyv_2d);
        swap(&mut self.yuyv_2d_locs[1], &mut set.yuyv_2d_locs);
        swap(
            &mut self.packed_rgba8_int8_program_2d,
            &mut set.packed_rgba8_2d,
        );
        for (i, (program, uniforms)) in set
            .nv_r8
            .iter_mut()
            .zip(set.nv_r8_uniforms.iter_mut())
            .enumerate()
        {
            swap(&mut self.nv_r8_programs[2 * i + 1], program);
            swap(&mut self.nv_r8_uniforms[2 * i + 1], uniforms);
        }
        if let (Some((programs, uniforms)), Some((program, u))) =
            (self.nv_y2y_programs.as_mut(), set.nv_y2y.as_mut())
        {
            swap(&mut programs[1], program);
            swap(&mut uniforms[1], u);
        }
        swap(
            &mut self.texture_src_extent_locs[1],
            &mut set.texture_src_extent_loc,
        );
        swap(
            &mut self.external_src_extent_locs[1],
            &mut set.yuv_src_extent_loc,
        );
        swap(
            &mut self.external_src_extent_locs[3],
            &mut set.planar_src_extent_loc,
        );
    }

    /// Upload `q` to every mapped int8 program, unless they already hold it.
    /// Uniforms are per-program state, so the draws need no change.
    fn load_int_quant(&mut self, q: IntQuant) -> crate::Result<()> {
        if self.int_quant == Some(q) {
            return Ok(());
        }
        // SAFETY: on the GL thread with this processor's context current; the
        // ids are programs this processor linked and still owns.
        unsafe {
            let mut current = 0i32;
            edgefirst_gl::gl::GetIntegerv(edgefirst_gl::gl::CURRENT_PROGRAM, &mut current);
            for (id, locs) in &self.int8_programs {
                edgefirst_gl::gl::UseProgram(*id);
                Self::upload_quant(locs, &q);
            }
            edgefirst_gl::gl::UseProgram(current as u32);
            check_gl_error(function!(), line!())?;
        }
        self.int_quant = Some(q);
        Ok(())
    }

    /// Point a mapped int8 `program`'s `quantize()` at one plane's colour
    /// channel, for the planar draws that swizzle each plane's channel into
    /// `.r`; `None` restores the loaded per-channel uniforms. A no-op for
    /// other programs and for coefficients equal across channels.
    ///
    /// # Safety
    /// On the GL thread with this processor's context current and `program`
    /// bound.
    unsafe fn set_plane_quant(&self, program: u32, plane: Option<usize>) {
        let Some(q) = self.int_quant else {
            return;
        };
        let same = |v: &[f32; 3]| v.iter().all(|&x| x == v[0]);
        if [&q.scale, &q.offset, &q.zero, &q.lo, &q.hi]
            .into_iter()
            .all(same)
        {
            return;
        }
        let Some((_, locs)) = self.int8_programs.iter().find(|(p, _)| *p == program) else {
            return;
        };
        let q = match plane {
            Some(p) if p < 3 => IntQuant {
                scale: [q.scale[p]; 3],
                offset: [q.offset[p]; 3],
                zero: [q.zero[p]; 3],
                lo: [q.lo[p]; 3],
                hi: [q.hi[p]; 3],
            },
            _ => q,
        };
        // SAFETY: the caller's contract; `program` is bound.
        unsafe { Self::upload_quant(locs, &q) };
    }

    /// The letterbox clear colour for integer destinations, since `glClear`
    /// bypasses the shader that otherwise maps the output: the mapped pad of
    /// the current convert, else the plain XOR 0x80 for int8. No-op when there
    /// is no fill colour. Shared by every destination path.
    fn int8_bias_clear(&self, is_int8: bool, mut crop: ResolvedCrop) -> ResolvedCrop {
        if let (Some(color), Some(pad)) = (crop.dst_color.as_mut(), self.int_pad) {
            *color = pad;
        } else if is_int8 {
            if let Some(ref mut color) = crop.dst_color {
                color[0] ^= 0x80;
                color[1] ^= 0x80;
                color[2] ^= 0x80;
            }
        }
        crop
    }

    /// Render `src` into the already-bound destination FBO as `dst_fmt`,
    /// dispatching packed vs planar; the draws select their int8 program
    /// variants from `is_int8` at draw time. This is the converged per-tile
    /// draw shared by the texture and DMA destination paths — they differ
    /// only in FBO setup and readback, never in this draw.
    #[allow(clippy::too_many_arguments)]
    fn render_packed_or_planar(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        band: Option<edgefirst_tensor::ViewOrigin>,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> crate::Result<()> {
        if dst_fmt.layout() == PixelLayout::Planar {
            self.convert_to_planar(
                src,
                src_fmt,
                dst,
                dst_fmt,
                is_int8,
                rotation,
                flip,
                crop,
                convert_span,
            )
        } else {
            self.convert_to(
                src,
                src_fmt,
                dst,
                dst_fmt,
                band,
                is_int8,
                rotation,
                flip,
                crop,
                convert_span,
            )
        }
    }

    /// `glReadPixels` the bound read-framebuffer into `dst`'s own mapping,
    /// placing each row at the destination's row pitch and undoing the BGRA
    /// channel order when `swap_rb`.
    ///
    /// The one place the GL engine writes a CPU-mapped destination, so it is
    /// the one place that has to reconcile the two pitches: the read packs its
    /// rows at `width * channels` while the mapping spaces them at
    /// `effective_row_stride()`. They differ for any pitch-padded backing --
    /// the D3D11 staging texture behind a Windows `TensorMemory::DmaBuf`
    /// tensor, an IOSurface, a tensor carrying a declared stride -- and a tight
    /// write into a padded window shears every row after the first.
    ///
    /// A `view()` destination is the case where the padding is not the
    /// destination's own: its window's rows sit at the PARENT's pitch and what
    /// separates them is the parent's columns to the right of the tile. So the
    /// readback places each row at the pitch and writes nothing between them
    /// -- see [`read_pixels_into`], which owns that rule for both of its
    /// routes (issue #177).
    fn read_pixels_into_tensor(
        &mut self,
        dst: &mut Tensor<u8>,
        width: usize,
        rows: usize,
        format: u32,
        swap_rb: bool,
    ) -> crate::Result<()> {
        let tight_row = width * pack_channels(format);
        let stride = dst.effective_row_stride().unwrap_or(tight_row);
        // A pitch shorter than one row cannot describe this destination, and
        // clamping it would write rows the caller never asked for. Refused with
        // both numbers, as the source path refuses a pitch that is not a whole
        // number of pixels.
        if stride < tight_row {
            return Err(crate::Error::OpenGl(format!(
                "destination row pitch is {stride} B but one {width}-pixel row \
                 of this readback format is {tight_row} B"
            )));
        }
        let mut dst_map = dst.map_for_write()?;
        let out = dst_map.as_mut_slice();
        // `read_pixels_into` writes `tight_row` bytes at every `stride`, so the
        // last row's end is the far bound. It is checked before the read,
        // because the read itself goes through a raw pointer and cannot check
        // anything.
        let needed = padded_readback_bytes(rows, tight_row, stride).unwrap_or(rows * tight_row);
        if out.len() < needed {
            return Err(crate::Error::OpenGl(format!(
                "destination maps {} B, needs {needed} B at a {stride} B pitch",
                out.len()
            )));
        }
        // SAFETY: called on the GL thread with a complete read framebuffer
        // bound; the rows fit `out` at this pitch by the check above, which
        // covers the unpadded case as well as the padded one.
        unsafe {
            edgefirst_gl::gl::ReadBuffer(edgefirst_gl::gl::COLOR_ATTACHMENT0);
            read_pixels_into(width, rows, format, &mut self.readback_scratch, out, stride);
        }
        check_gl_error(function!(), line!())?;
        if swap_rb {
            // Row by row: the swap must not walk the padding between rows, and
            // a padded pitch need not be a multiple of the 4-byte chunk.
            for y in 0..rows {
                for chunk in out[y * stride..y * stride + tight_row]
                    .as_chunks_mut::<4>()
                    .0
                {
                    chunk.swap(0, 2);
                }
            }
        }
        Ok(())
    }

    /// `glReadPixels` the bound read-framebuffer into the PBO behind `dst`,
    /// placing each row at the destination's row pitch and undoing the BGRA
    /// channel order when `swap_rb`.
    ///
    /// The PBO counterpart of [`Self::read_pixels_into_tensor`]: the same two
    /// pitches to reconcile, but the destination is never mapped through the
    /// tensor -- a PBO map round-trips through this very thread -- so every
    /// CPU visit here is a `glMapBufferRange`. Where the pitch is a whole
    /// number of pixels GL lays the rows out itself through
    /// `GL_PACK_ROW_LENGTH`, so an RGBA destination keeps its CPU-free
    /// transfer; a pitch no pixel size divides is read tight and spread in a
    /// mapping, as the Mem path does; and the RGBA-scratch repack ANGLE forces
    /// for RGB/RED writes each row at the pitch directly. A tight destination
    /// takes exactly the reads it always did.
    fn read_pixels_into_pbo(
        &mut self,
        dst: &Tensor<u8>,
        buffer_id: u32,
        width: usize,
        rows: usize,
        format: u32,
        swap_rb: bool,
    ) -> crate::Result<()> {
        let channels = pack_channels(format);
        let PboReadbackLayout {
            stride,
            tight_row,
            needed,
            row_length,
        } = plan_pbo_readback(
            dst.effective_row_stride().unwrap_or(width * channels),
            dst.view_origin().is_some(),
            dst.plane_offset().unwrap_or(0),
            dst.capacity_bytes(),
            width,
            rows,
            channels,
        )?;
        // Set when the rows were read tight into a padded destination and
        // still have to be moved out to the pitch.
        let mut spread = false;
        // SAFETY: called on the GL thread with a complete read framebuffer
        // bound; every span written lies within `needed`, checked above.
        unsafe {
            edgefirst_gl::gl::ReadBuffer(edgefirst_gl::gl::COLOR_ATTACHMENT0);
            if direct_read_supported(format) {
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER, buffer_id);
                // The bytes between rows at this pitch are the destination's
                // padding; a driver may write them while packing (Vivante
                // does, issue #167). `needed` keeps every written byte inside
                // the buffer either way.
                if let Some(pixels) = row_length {
                    edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::PACK_ROW_LENGTH, pixels);
                }
                edgefirst_gl::gl::ReadPixels(
                    0,
                    0,
                    width as i32,
                    rows as i32,
                    format,
                    edgefirst_gl::gl::UNSIGNED_BYTE,
                    std::ptr::null_mut(),
                );
                if row_length.is_some() {
                    edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::PACK_ROW_LENGTH, 0);
                }
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_PACK_BUFFER, 0);
                edgefirst_gl::gl::Finish();
                spread = stride > tight_row && row_length.is_none();
            } else {
                // ANGLE rejects a direct RGB/RED read with
                // GL_INVALID_OPERATION -- ES 3 guarantees only
                // RGBA/UNSIGNED_BYTE plus one implementation-defined pair -- so
                // read RGBA into the scratch and repack each row's leading
                // channels into the mapped PBO at the pitch, as the Mem path
                // does. Costs one CPU copy; the RGBA route above is unaffected.
                read_pixels_rgba_scratch(width, rows, &mut self.readback_scratch);
                let scratch = &self.readback_scratch;
                // The repack writes only pixel bytes, so a padded destination
                // is mapped read-write to keep its pad;
                // GL_MAP_INVALIDATE_RANGE_BIT would leave the pad undefined. A
                // tight destination is written whole and keeps the invalidating
                // map, which spares the driver a read-back.
                let access = if stride > tight_row {
                    edgefirst_gl::gl::MAP_READ_BIT | edgefirst_gl::gl::MAP_WRITE_BIT
                } else {
                    edgefirst_gl::gl::MAP_WRITE_BIT | edgefirst_gl::gl::MAP_INVALIDATE_RANGE_BIT
                };
                with_mapped_pbo(buffer_id, needed, access, "PBO readback repack", |out| {
                    for (y, row) in out.chunks_mut(stride).take(rows).enumerate() {
                        let pixels = scratch[y * width * 4..(y + 1) * width * 4]
                            .as_chunks::<4>()
                            .0;
                        for (px, dst_px) in pixels
                            .iter()
                            .zip(row[..tight_row].chunks_exact_mut(channels))
                        {
                            dst_px.copy_from_slice(&px[..channels]);
                        }
                    }
                })?;
            }
        }
        check_gl_error(function!(), line!())?;
        if spread || swap_rb {
            // SAFETY: GL thread, the read above has completed, and `needed`
            // lies within the allocation.
            unsafe {
                with_mapped_pbo(
                    buffer_id,
                    needed,
                    edgefirst_gl::gl::MAP_READ_BIT | edgefirst_gl::gl::MAP_WRITE_BIT,
                    "PBO readback row placement",
                    |buf| {
                        if spread {
                            spread_rows(buf, rows, tight_row, stride);
                        }
                        if swap_rb {
                            // Row by row: the swap must not walk the padding
                            // between rows, and a padded pitch need not be a
                            // multiple of the 4-byte chunk.
                            for y in 0..rows {
                                for chunk in buf[y * stride..y * stride + tight_row]
                                    .as_chunks_mut::<4>()
                                    .0
                                {
                                    chunk.swap(0, 2);
                                }
                            }
                        }
                    },
                )?;
            }
            check_gl_error(function!(), line!())?;
        }
        Ok(())
    }

    /// Read the rendered FBO colour attachment (`COLOR_ATTACHMENT0`) into the
    /// destination, applying the BGRA byte-swap when `dst_fmt` is BGRA. `pbo_id`
    /// selects the target: `None` reads straight into the mapped Mem tensor (the
    /// preceding draw has already finished the GPU); `Some(id)` reads into the
    /// bound PBO PACK buffer and issues a finishing flush so the async transfer
    /// completes. The converged readback shared by the non-DMA and any-to-PBO
    /// paths — they differ only in this target selector.
    fn readback_rendered(
        &mut self,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        pbo_id: Option<u32>,
    ) -> crate::Result<()> {
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let dest_format = match dst_fmt {
            PixelFormat::Rgb => edgefirst_gl::gl::RGB,
            PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA,
            PixelFormat::Grey => edgefirst_gl::gl::RED,
            // Same single-channel R8 target as `setup_renderbuffer_non_dma` /
            // `setup_renderbuffer_from_pbo`: full dst_w (one byte per
            // texel — NOT a multi-byte-per-texel pack), dst_h stacked
            // `channels` times. CHW planes are contiguous in row-major
            // order, so a single-channel readback at that geometry lands
            // directly in the destination's CHW byte layout.
            PixelFormat::PlanarRgb | PixelFormat::PlanarRgba => edgefirst_gl::gl::RED,
            _ => {
                return Err(crate::Error::NotSupported(format!(
                    "GL readback not supported for {dst_fmt}"
                )))
            }
        };
        let read_h = if dst_fmt.layout() == PixelLayout::Planar {
            dst_h * dst_fmt.channels()
        } else {
            dst_h
        };
        match pbo_id {
            None => self.read_pixels_into_tensor(
                dst,
                dst_w,
                read_h,
                dest_format,
                dst_fmt == PixelFormat::Bgra,
            ),
            Some(buffer_id) => self.read_pixels_into_pbo(
                dst,
                buffer_id,
                dst_w,
                read_h,
                dest_format,
                dst_fmt == PixelFormat::Bgra,
            ),
        }
    }

    fn setup_renderbuffer_non_dma(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
        crop: ResolvedCrop,
    ) -> crate::Result<()> {
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let is_planar = dst_fmt.layout() == PixelLayout::Planar;

        let (width, height) = if is_planar {
            // Full dst_w, NOT dst_w/4: `convert_to_planar` draws each plane as
            // one full-width quad (see `draw_camera_texture_to_rgb_planar`'s
            // texture-swizzle-per-plane loop) into a single-channel R8
            // target, byte-for-byte identical to the proven DMA target
            // geometry in `setup_renderbuffer_dma` — there is no 4-texels-
            // per-column packing in this shader to justify a narrower width.
            let height = match dst_fmt.channels() {
                4 => dst_h * 4,
                3 => dst_h * 3,
                1 => dst_h,
                _ => unreachable!(),
            };
            (dst_w as i32, height as i32)
        } else {
            (dst_w as i32, dst_h as i32)
        };

        // BGRA textures as framebuffer color attachments have GPU-dependent
        // swizzle behavior: some implementations don't swizzle fragment shader
        // output, causing R↔B channel swap. Work around this by using RGBA
        // format internally — BGRA pixel data is byte-swapped (R↔B) before
        // upload, and the readback path swaps back.
        let is_bgra = !is_planar && dst_fmt == PixelFormat::Bgra;
        if is_bgra && !self.bgra_warned {
            log::warn!(
                "BGRA destination: using RGBA internal format with CPU R↔B byte-swap workaround"
            );
            self.bgra_warned = true;
        }
        let format = if is_planar {
            edgefirst_gl::gl::RED
        } else {
            match dst_fmt {
                PixelFormat::Rgb => edgefirst_gl::gl::RGB,
                PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA, // BGRA uses RGBA internally
                PixelFormat::Grey => edgefirst_gl::gl::RED,
                _ => unreachable!(),
            }
        };

        let start = Instant::now();
        self.convert_fbo.bind();

        let map;
        let mut swapped_buf;

        // Seed the render target with the destination's current pixels, so a
        // letterbox band that is neither cleared nor drawn keeps what the
        // destination already held.
        //
        // Skipped whenever a fill colour was asked for, which is every
        // letterbox `Crop` the public API can build: `convert_to`'s
        // `glClear` covers the whole target before anything is drawn, so the
        // upload would be read back out of the framebuffer having been
        // overwritten in full — pure cost, and on a strided or `view()`
        // destination a misleading one, since `TexImage2D` reads the map
        // tight and would shear the rows it uploaded.
        let seeded = crop.dst_color.is_none()
            && crop.dst_rect.is_some_and(|c| {
                c.top != 0 || c.left != 0 || c.height != dst_h || c.width != dst_w
            });
        // No public `Crop` reaches this arm today: `Crop::resolve` returns a
        // partial `dst_rect` only for `Fit::Letterbox`, which always carries
        // its pad colour, so a partial rect without one can only come from a
        // `ResolvedCrop` built inside the crate.
        let pixels = if !seeded {
            std::ptr::null()
        } else {
            map = dst.map_read()?;
            if is_bgra {
                // Swap R↔B to convert BGRA→RGBA for the RGBA texture.
                swapped_buf = map.as_slice().to_vec();
                for chunk in swapped_buf.as_chunks_mut::<4>().0 {
                    chunk.swap(0, 2);
                }
                swapped_buf.as_ptr() as *const c_void
            } else {
                map.as_ptr() as *const c_void
            }
        };
        unsafe {
            edgefirst_gl::gl::UseProgram(self.texture_program.id);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.render_texture.id);
            super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::LINEAR);

            edgefirst_gl::gl::TexImage2D(
                edgefirst_gl::gl::TEXTURE_2D,
                0,
                self.render_internal_format(format),
                width,
                height,
                0,
                format,
                edgefirst_gl::gl::UNSIGNED_BYTE,
                pixels,
            );
            // TexImage2D overwrites any EGLImage binding on this texture.
            self.render_texture.invalidate_egl_binding();
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.render_texture.id,
                0,
            );
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, width, height);
        }
        log::debug!("Set up framebuffer takes {:?}", start.elapsed());
        Ok(())
    }

    /// Draw `bg` as the base layer of the bound zero-copy destination
    /// framebuffer. Where external-OES sampling exists (Linux) a zero-copy
    /// background is blitted through its EGLImage; elsewhere, and for a
    /// host-memory background on every platform, it goes through the 2D
    /// source texture: `draw_src_texture` attaches a zero-copy background
    /// where the platform imports as `TEXTURE_2D` and uploads a host one.
    /// Uploading into `render_texture` instead would swap that texture in
    /// as the colour attachment and leave the destination untouched, since
    /// a zero-copy destination has no readback pass. Blending is off: the
    /// base layer replaces whatever the destination held.
    fn draw_background_into_bound_fbo(
        &mut self,
        bg: &Tensor<u8>,
        bg_fmt: PixelFormat,
    ) -> crate::Result<()> {
        edgefirst_gl::disable(edgefirst_gl::gl::BLEND);
        let full_src = RegionOfInterest {
            left: 0.0,
            top: 1.0,
            right: 1.0,
            bottom: 0.0,
        };
        let full_dst = RegionOfInterest {
            left: -1.0,
            top: 1.0,
            right: 1.0,
            bottom: -1.0,
        };
        if Platform::EXTERNAL_OES && bg.memory() == TensorMemory::DmaBuf {
            let bg_egl = self.get_or_create_egl_image(CacheKind::Src, bg, bg_fmt)?;
            self.draw_camera_texture_eglimage(
                bg,
                bg_fmt,
                bg_egl,
                full_src,
                full_dst,
                0,
                crate::Flip::None,
                false,
                None,
            )
        } else {
            // An overlay background, not a convert: there is no
            // `image.convert.gl` span to record a source feed on, and
            // `ConvertStats` counts it either way.
            self.draw_src_texture(
                bg,
                bg_fmt,
                full_src,
                full_dst,
                0,
                crate::Flip::None,
                false,
                &tracing::Span::none(),
            )
        }
    }

    /// Set up a framebuffer for overlay rendering on a PBO-backed destination.
    ///
    /// Binds the PBO as `GL_PIXEL_UNPACK_BUFFER` and uploads its contents to
    /// the render texture via `TexImage2D` with a NULL pointer — GL reads
    /// directly from PBO memory without any CPU-side `map()` call. This avoids
    /// the deadlock that occurs when `setup_renderbuffer_non_dma` tries to
    /// `tensor.map()` a PBO on the GL thread.
    /// Upload CPU-side pixel data into `self.render_texture` which is
    /// attached as the FBO color attachment.  Used for the non-DMA
    /// background path in `draw_decoded_masks_impl` /
    /// `draw_proto_masks_impl`: the source buffer is a user-provided
    /// tensor in plain memory, so we do a single CPU→GPU upload into the
    /// texture rather than memcpying into the caller's dst (which the
    /// final framebuffer readback would overwrite anyway).
    ///
    /// If the source is BGRA we byte-swap into a scratch buffer so the
    /// RGBA-internal render target holds the correct pixels after the
    /// later readback-time R↔B swap.
    fn upload_pixels_to_render_texture(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst_w: usize,
        dst_h: usize,
    ) -> crate::Result<()> {
        use edgefirst_tensor::TensorMapTrait;
        let map = src.map_read()?;
        let src_slice = map.as_slice();
        let format = match src_fmt {
            PixelFormat::Rgb => edgefirst_gl::gl::RGB,
            PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA,
            _ => {
                return Err(crate::Error::NotSupported(format!(
                    "non-DMA bg upload not supported for {src_fmt}",
                )))
            }
        };
        let swapped: Option<Vec<u8>> = if src_fmt == PixelFormat::Bgra {
            let mut v = src_slice.to_vec();
            for chunk in v.as_chunks_mut::<4>().0 {
                chunk.swap(0, 2);
            }
            Some(v)
        } else {
            None
        };
        let pixels = swapped.as_deref().unwrap_or(src_slice).as_ptr() as *const c_void;

        unsafe {
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.render_texture.id);
            edgefirst_gl::gl::TexImage2D(
                edgefirst_gl::gl::TEXTURE_2D,
                0,
                format as i32,
                dst_w as i32,
                dst_h as i32,
                0,
                format,
                edgefirst_gl::gl::UNSIGNED_BYTE,
                pixels,
            );
            // TexImage2D invalidates any prior EGLImage binding.
            self.render_texture.invalidate_egl_binding();
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.render_texture.id,
                0,
            );
            check_gl_error(function!(), line!())?;
        }
        Ok(())
    }

    /// Low-level PBO render-target setup with explicit GL format and type.
    ///
    /// Binds `buffer_id` as `GL_PIXEL_UNPACK_BUFFER`, calls `TexImage2D` with
    /// the provided `internal_format`, `client_format`, and `gl_type`, then
    /// attaches the texture to the FBO color attachment and sets the viewport.
    ///
    /// The `(width, height)` are the logical pixel dimensions of the render
    /// target (caller is responsible for planar-packing remapping if needed).
    ///
    /// # Safety (caller responsibility)
    /// `internal_format`, `client_format`, and `gl_type` must form a valid
    /// `TexImage2D` combination for the bound GLES context.
    #[allow(clippy::too_many_arguments)]
    fn setup_renderbuffer_from_pbo_inner(
        &mut self,
        width: i32,
        height: i32,
        buffer_id: u32,
        internal_format: u32,
        client_format: u32,
        gl_type: u32,
        row_length: Option<i32>,
    ) -> crate::Result<()> {
        self.convert_fbo.bind();
        unsafe {
            edgefirst_gl::gl::UseProgram(self.texture_program.id);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.render_texture.id);
            super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::LINEAR);

            // Upload existing PBO content to the render texture.
            // Binding PBO as UNPACK buffer makes TexImage2D read from it.
            //
            // `row_length` is the destination's own pitch expressed in pixels
            // (`None` when its rows are tight, or when the pitch is not a
            // whole number of pixels and GL therefore cannot express it --
            // the same limit `plan_pbo_readback` works around on the way
            // back out). Without it a pitch-aligned destination is read back
            // to back and the seed shears.
            //
            // The `pixels` argument stays 0: with a buffer bound it is a byte
            // offset, and the only destinations that would need a non-zero
            // one -- a `view()`, or any tensor carrying a plane offset -- are
            // refused before the readback by `plan_pbo_readback`, so none
            // reaches here.
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_UNPACK_BUFFER, buffer_id);
            if let Some(px) = row_length {
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, px);
            }
            edgefirst_gl::gl::TexImage2D(
                edgefirst_gl::gl::TEXTURE_2D,
                0,
                internal_format as i32,
                width,
                height,
                0,
                client_format,
                gl_type,
                std::ptr::null(),
            );
            if row_length.is_some() {
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, 0);
            }
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::PIXEL_UNPACK_BUFFER, 0);
            // TexImage2D overwrites any EGLImage binding on this texture.
            self.render_texture.invalidate_egl_binding();

            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.render_texture.id,
                0,
            );
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, width, height);
        }
        Ok(())
    }

    /// Set up a u8 (UNSIGNED_BYTE) PBO render target for the given format.
    ///
    /// Computes the correct GL `format` from `dst_fmt` (handling planar
    /// packing layout) and delegates to [`setup_renderbuffer_from_pbo_inner`]
    /// with `UNSIGNED_BYTE` as the GL type.  The next task adds an analogous
    /// float variant that calls the inner helper with `R32F`/`RGBA16F` and
    /// `FLOAT`/`HALF_FLOAT` respectively.
    fn setup_renderbuffer_from_pbo(
        &mut self,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
        buffer_id: u32,
    ) -> crate::Result<()> {
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let is_planar = dst_fmt.layout() == PixelLayout::Planar;

        let (width, height) = if is_planar {
            // Same full-width geometry as `setup_renderbuffer_non_dma` — see
            // its comment; both feed the identical `convert_to_planar` draw.
            let height = match dst_fmt.channels() {
                4 => dst_h * 4,
                3 => dst_h * 3,
                1 => dst_h,
                _ => unreachable!(),
            };
            (dst_w as i32, height as i32)
        } else {
            (dst_w as i32, dst_h as i32)
        };

        let format = if is_planar {
            edgefirst_gl::gl::RED
        } else {
            match dst_fmt {
                PixelFormat::Rgb => edgefirst_gl::gl::RGB,
                PixelFormat::Rgba | PixelFormat::Bgra => edgefirst_gl::gl::RGBA,
                PixelFormat::Grey => edgefirst_gl::gl::RED,
                _ => {
                    return Err(crate::Error::NotSupported(format!(
                        "PBO renderbuffer not supported for {dst_fmt}",
                    )))
                }
            }
        };

        // The seed reads the destination's CURRENT bytes, so it has to know
        // how far apart its rows are. `pack_row_length`'s rule is the same on
        // this side as on the readback's: `None` for a tight pitch (nothing
        // to express) and for one that is not a whole number of pixels (GL
        // cannot express it either way -- the readback reads tight and
        // spreads afterwards; there is no equivalent for an upload).
        let px_bytes = match format {
            edgefirst_gl::gl::RGBA => 4,
            edgefirst_gl::gl::RGB => 3,
            _ => 1, // RED: Grey, and every plane of a planar destination
        };
        let tight_row = width as usize * px_bytes;
        let row_length = dst
            .effective_row_stride()
            .and_then(|stride| pack_row_length(tight_row, stride, px_bytes));

        self.setup_renderbuffer_from_pbo_inner(
            width,
            height,
            buffer_id,
            self.render_internal_format(format) as u32,
            format,
            edgefirst_gl::gl::UNSIGNED_BYTE,
            row_length,
        )
    }

    /// Pick the NV* GPU conversion path for `src`/`src_fmt`, honoring the
    /// `EDGEFIRST_NV_CONVERT_PATH` preference. Returns the path to *attempt*;
    /// an EGLImage-creation error does not end the convert — the caller retries
    /// a single-plane NV source as an R8 *upload* of the combined plane, which
    /// is still [`NvConvertPath::ShaderR8`] (#166), and only a true-multiplane
    /// NV12 is left to reach [`NvConvertPath::Cpu`]. Forcing an unavailable
    /// path logs a warning and falls back to the only viable one rather than
    /// failing.
    ///
    /// Capability:
    /// - [`NvConvertPath::ShaderR8`] needs a single combined-plane buffer, so it
    ///   covers single-plane NV12/NV16/NV24 but NOT true-multiplane NV12.
    /// - [`NvConvertPath::ExternalSampler`] (samplerExternalOES) is wired for
    ///   NV12 only (incl. multiplane); NV16/NV24 have no sampler path.
    ///
    /// `render_fmt` is the format of the render target this draw writes
    /// (Rgb/PlanarRgb arrive here only as the LOGICAL format of a two-pass
    /// convert whose pass 1 renders an RGBA intermediate; the only R8 render
    /// target reachable with an NV source is a single-pass Grey destination).
    fn select_nv_path(
        &self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        render_fmt: PixelFormat,
    ) -> NvConvertPath {
        // `ShaderR8` (R8 texelFetch) only applies to SINGLE-PLANE semi-planar
        // NV12/NV16/NV24. Everything else routed through this picker —
        // RGBA/Grey/YUYV/RGB and true-multiplane NV12 — uses the
        // `ExternalSampler` (samplerExternalOES / `draw_camera_texture_eglimage`)
        // path, so that is the default.
        let shader_capable = matches!(
            src_fmt,
            PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
        ) && !src.is_multiplane();
        if !shader_capable {
            return NvConvertPath::ExternalSampler;
        }
        // From here: single-plane NV12/NV16/NV24 — ShaderR8 is viable. Only NV12
        // also has an ExternalSampler path (NV16/NV24 do not).
        match self.nv_path_pref {
            NvPathPref::ForceShader => NvConvertPath::ShaderR8,
            NvPathPref::ForceSampler => {
                if src_fmt == PixelFormat::Nv12
                    && self.is_vivante
                    && render_fmt == PixelFormat::Grey
                {
                    // See the Auto-arm comment: sampler → R8 target wedges the
                    // GC7000UL. Refuse the force rather than hang the GPU.
                    log::warn!(
                        "EDGEFIRST_NV_CONVERT_PATH=sampler refused for NV12→Grey on Vivante \
                         (samplerExternalOES → R8 render target hangs the GPU); using shader"
                    );
                    NvConvertPath::ShaderR8
                } else if src_fmt == PixelFormat::Nv12 {
                    NvConvertPath::ExternalSampler
                } else {
                    log::warn!(
                        "EDGEFIRST_NV_CONVERT_PATH=sampler unavailable for {src_fmt:?} \
                         (no external-sampler path); using shader"
                    );
                    NvConvertPath::ShaderR8
                }
            }
            // Auto: prefer the portable, colorimetry-exact in-shader ShaderR8
            // wherever it is also the fast path (Mali, V3D, Tegra — shader and
            // sampler are comparable there, so exactness is free).
            //
            // EXCEPTION — Vivante (i.MX 8MP): the texelFetch shader is ~12×
            // slower than the hardware samplerExternalOES (on-target benchmark:
            // NV12 720p convert 29ms shader vs 2.5ms sampler). For single-plane
            // 4-aligned NV12 (the sampler import constraint) the pick follows
            // the HIGH-PERFORMANCE-default policy (issue #106):
            //
            // * `ColorimetryMode::Fast` (default): take the sampler for EVERY
            //   colorimetry — the driver applies its fixed BT.601-limited
            //   matrix, which is exact for BT.601-limited sources (Phase 2
            //   probe: ≤1 vs CPU) and approximate for the rest.
            // * `ColorimetryMode::Exact` (config/env opt-in): take the sampler
            //   only when the driver matrix MATCHES the source's resolved
            //   (encoding, range); everything else renders through the exact
            //   in-shader matrix, at Vivante's 12× cost.
            NvPathPref::Auto => {
                // NEVER pair the external sampler with an R8 (Grey) render
                // target on Vivante: samplerExternalOES → R8 attachment wedges
                // the GC7000UL (the EDGEAI-1180 hang class — found when the
                // Fast policy first routed nv12@dma→grey@dma to the sampler;
                // the GPU hangs unrecoverably mid-draw). This gate applies in
                // BOTH colorimetry modes: the old BT.601-limited carve-out had
                // the same latent hang, just unreachable with HD sources.
                let vivante_sampler_usable = src_fmt == PixelFormat::Nv12
                    && self.is_vivante
                    && render_fmt != PixelFormat::Grey
                    && src.width().is_some_and(|w| w.is_multiple_of(4));
                let take_sampler = vivante_sampler_usable
                    && match self.colorimetry_mode {
                        crate::ColorimetryMode::Fast => true,
                        crate::ColorimetryMode::Exact => {
                            let cm = crate::colorimetry::resolve_colorimetry(
                                src.colorimetry(),
                                src.height(),
                            );
                            cm.encoding == Some(edgefirst_tensor::ColorEncoding::Bt601)
                                && cm.range == Some(edgefirst_tensor::ColorRange::Limited)
                        }
                    };
                if take_sampler {
                    NvConvertPath::ExternalSampler
                } else {
                    NvConvertPath::ShaderR8
                }
            }
        }
    }

    /// `band` is the destination tile's origin **inside the bound render
    /// target**, and is `Some` only when that target is the shared parent
    /// import a `view()`/`batch()` destination is placed in by
    /// `setup_renderbuffer_dma`'s viewport. It is NOT `dst.view_origin()`:
    /// the mapped-texture and PBO lowerings render into an offscreen target
    /// that IS the tile, at origin (0, 0), and place it afterwards in the
    /// readback, so scissoring them to the view's parent coordinates would
    /// clip away the tile's own left/top edge (issue #177). The two-pass
    /// plans' pass 1 renders into an engine-internal intermediate for the
    /// same reason and passes `None` too. Callers derive it from what
    /// [`Self::bind_dst`] classified the destination as.
    #[allow(clippy::too_many_arguments)]
    fn convert_to(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &Tensor<u8>,
        _dst_fmt: PixelFormat,
        band: Option<edgefirst_tensor::ViewOrigin>,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> Result<(), crate::Error> {
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        self.convert_to_dims(
            src,
            src_fmt,
            dst_w,
            dst_h,
            band,
            _dst_fmt,
            is_int8,
            rotation,
            flip,
            crop,
            convert_span,
        )
    }

    /// The body of [`convert_to`], taking the destination geometry directly:
    /// renders `src` to the currently-bound FBO. Callers rendering into an
    /// engine-internal texture (the fused float two-pass) have no `Tensor<u8>`
    /// destination to lend — only its dimensions. `dst_fmt` feeds only
    /// `select_nv_path`'s Vivante carve-out, never the render target format
    /// (that is whatever the bound FBO holds).
    #[allow(clippy::too_many_arguments)]
    fn convert_to_dims(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst_w: usize,
        dst_h: usize,
        dst_view_origin: Option<edgefirst_tensor::ViewOrigin>,
        dst_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> Result<(), crate::Error> {
        let src_w = src.width().ok_or(Error::NotAnImage)?;
        let src_h = src.height().ok_or(Error::NotAnImage)?;
        check_gl_error(function!(), line!())?;

        // A view()/batch() destination shares ONE parent EGLImage with its
        // sibling tiles; the band viewport was set in `setup_renderbuffer_dma`.
        // Confine this tile's letterbox `glClear` (below) and draw to the same
        // band via `glScissor` so they cannot wipe a sibling. The RAII guard
        // disables `SCISSOR_TEST` on every exit (success, `?`, or unwind) so the
        // next convert/draw starts from a clean state.
        struct ScissorGuard(bool);
        impl Drop for ScissorGuard {
            fn drop(&mut self) {
                if self.0 {
                    unsafe { edgefirst_gl::gl::Disable(edgefirst_gl::gl::SCISSOR_TEST) };
                }
            }
        }
        // Band rect via `region_to_viewport_top_down` — the SAME lowering as
        // the band viewport in `bind_dst`'s setup, so scissor and viewport can
        // never disagree on the orientation convention.
        let _scissor = match dst_view_origin {
            Some(vo) => {
                let vp = super::render::region_to_viewport_top_down(crate::Region::new(
                    vo.x, vo.y, dst_w, dst_h,
                ));
                unsafe {
                    edgefirst_gl::gl::Scissor(vp.x, vp.y, vp.w, vp.h);
                    edgefirst_gl::gl::Enable(edgefirst_gl::gl::SCISSOR_TEST);
                }
                ScissorGuard(true)
            }
            None => ScissorGuard(false),
        };

        let has_crop = crop
            .dst_rect
            .is_some_and(|x| x.left != 0 || x.top != 0 || x.width != dst_w || x.height != dst_h);
        if has_crop {
            if let Some(dst_color) = crop.dst_color {
                unsafe {
                    edgefirst_gl::gl::ClearColor(
                        dst_color[0] as f32 / 255.0,
                        dst_color[1] as f32 / 255.0,
                        dst_color[2] as f32 / 255.0,
                        dst_color[3] as f32 / 255.0,
                    );
                    edgefirst_gl::gl::Clear(edgefirst_gl::gl::COLOR_BUFFER_BIT);
                };
            }
        }

        let src_roi = if let Some(crop) = crop.src_rect {
            RegionOfInterest::from_crop(&crop, src_w, src_h)
        } else {
            RegionOfInterest {
                left: 0.,
                top: 1.,
                right: 1.,
                bottom: 0.,
            }
        };

        let cvt_screen_coord = |normalized| normalized * 2.0 - 1.0;
        let dst_roi = if let Some(crop) = crop.dst_rect {
            RegionOfInterest {
                left: cvt_screen_coord(crop.left as f32 / dst_w as f32),
                top: cvt_screen_coord((crop.top + crop.height) as f32 / dst_h as f32),
                right: cvt_screen_coord((crop.left + crop.width) as f32 / dst_w as f32),
                bottom: cvt_screen_coord(crop.top as f32 / dst_h as f32),
            }
        } else {
            RegionOfInterest {
                left: -1.,
                top: 1.,
                right: 1.,
                bottom: -1.,
            }
        };
        let rotation_offset = match rotation {
            crate::Rotation::None => 0,
            crate::Rotation::Clockwise90 => 1,
            crate::Rotation::Rotate180 => 2,
            crate::Rotation::CounterClockwise90 => 3,
        };
        let nv_rect = NvSampleRect::new(
            crop.src_rect,
            crop.dst_rect,
            (src_w, src_h),
            (dst_w, dst_h),
            rotation,
        );
        if self.gl_context.transfer_backend.is_zero_copy() && src.memory() == TensorMemory::DmaBuf {
            // Choose the NV* path (ShaderR8 vs ExternalSampler) honoring the
            // EDGEFIRST_NV_CONVERT_PATH preference. See `select_nv_path`: Auto
            // prefers the portable, colorimetry-exact in-shader ShaderR8 for
            // single-plane NV12/NV16/NV24, using the driver ExternalSampler only
            // for true-multiplane NV12 (which ShaderR8 cannot import).
            let chosen = self.select_nv_path(src, src_fmt, dst_fmt);

            if !Platform::EXTERNAL_OES && chosen == NvConvertPath::ExternalSampler {
                // No samplerExternalOES on this platform (ANGLE/Metal):
                // packed/Grey zero-copy sources attach as TEXTURE_2D inside
                // draw_src_texture; formats it can't take fall back to CPU
                // via its error.
                self.draw_src_texture(
                    src,
                    src_fmt,
                    src_roi,
                    dst_roi,
                    rotation_offset,
                    flip,
                    is_int8,
                    convert_span,
                )?;
            } else if chosen == NvConvertPath::ShaderR8 {
                match self.get_or_create_nv_r8_egl_image(src, src_fmt) {
                    Ok(r8_egl) => {
                        tracing::trace!(
                            path = "ShaderR8",
                            src_fmt = ?src_fmt,
                            "image.convert.gl.nv_path"
                        );
                        self.convert_stats.src_imports += 1;
                        convert_span.record("src_feed", "import");
                        // Recorded from the draw's result, not before it: a
                        // failed draw must not leave a ShaderR8 claim, and it
                        // must not leave the PREVIOUS convert's value either.
                        match self.draw_nv_texture_2d(
                            src,
                            src_fmt,
                            Some(r8_egl),
                            nv_rect,
                            dst_roi,
                            rotation_offset,
                            flip,
                            is_int8,
                            convert_span,
                        ) {
                            Ok(()) => self.last_nv_convert_path = NvConvertPath::ShaderR8,
                            Err(e) => {
                                self.last_nv_convert_path = NvConvertPath::Cpu;
                                return Err(e);
                            }
                        }
                    }
                    Err(e) => {
                        let src_w = src.width().unwrap_or(0);
                        let src_h = src.height().unwrap_or(0);
                        self.convert_stats.zero_copy_declines += 1;
                        // Warn once per buffer — a steady-state video pipeline
                        // hits this every frame with the same buffers, and a
                        // per-frame warn floods the log. Repeats drop to debug.
                        // `log`, not `tracing`: the workspace installs no
                        // `tracing-log` bridge, so a `tracing::warn!` reaches no
                        // ordinary board or field log at all -- and this is the
                        // line that diagnoses #165 on a Mali box. The sibling
                        // arm below already uses `log`. Same warn-once shape.
                        if self.nv_import_warned.insert(src.buffer_identity().id()) {
                            log::warn!(
                                "Path B R8 EGLImage creation failed for {src_fmt} \
                                 ({src_w}x{src_h}); uploading the combined plane instead: {e}"
                            );
                        } else {
                            log::debug!(
                                "Path B R8 EGLImage creation failed for {src_fmt} \
                                 ({src_w}x{src_h}) (repeat): {e}"
                            );
                        }
                        // The same shader on an R8 *upload* of the combined
                        // plane, which reads the source through `map()` — the
                        // route the non-DMA NV branch below already takes.
                        // `draw_src_texture` has no NV arm and would have
                        // returned NotSupported, sending the whole convert to
                        // the CPU (issue #166).
                        let start = Instant::now();
                        // The R8 import declined (Mali's alignment rule, the
                        // ANGLE leaves' offset refusal, or a driver that cannot
                        // import the buffer at all). If the upload draws, this
                        // is still a GPU convert and records ShaderR8, not Cpu
                        // -- recorded from the result, so a failed upload
                        // records Cpu rather than keeping the previous
                        // convert's value.
                        match self.draw_nv_texture_2d(
                            src,
                            src_fmt,
                            None,
                            nv_rect,
                            dst_roi,
                            rotation_offset,
                            flip,
                            is_int8,
                            convert_span,
                        ) {
                            Ok(()) => self.last_nv_convert_path = NvConvertPath::ShaderR8,
                            Err(e) => {
                                self.last_nv_convert_path = NvConvertPath::Cpu;
                                return Err(e);
                            }
                        }
                        log::debug!("NV R8 upload takes {:?}", start.elapsed());
                    }
                }
            } else {
                // ExternalSampler path (samplerExternalOES): NV12 (incl.
                // multiplane) and all non-shader DMA formats (RGBA/Grey/YUYV);
                // single-plane NV12/NV16/NV24 take ShaderR8 above.
                match self.get_or_create_egl_image(CacheKind::Src, src, src_fmt) {
                    Ok(src_egl) => {
                        if src_fmt == PixelFormat::Nv12 {
                            tracing::trace!(path = "ExternalSampler", src_fmt = ?src_fmt, "image.convert.gl.nv_path");
                        }
                        self.convert_stats.src_imports += 1;
                        convert_span.record("src_feed", "import");
                        // Recorded from the draw's result (see the ShaderR8
                        // arm): a failed draw records neither ExternalSampler
                        // nor the previous convert's value.
                        match self.draw_camera_texture_eglimage(
                            src,
                            src_fmt,
                            src_egl,
                            src_roi,
                            dst_roi,
                            rotation_offset,
                            flip,
                            is_int8,
                            None,
                        ) {
                            Ok(()) => {
                                if src_fmt == PixelFormat::Nv12 {
                                    self.last_nv_convert_path = NvConvertPath::ExternalSampler;
                                }
                            }
                            Err(e) => {
                                if src_fmt == PixelFormat::Nv12 {
                                    self.last_nv_convert_path = NvConvertPath::Cpu;
                                }
                                return Err(e);
                            }
                        }
                    }
                    Err(e) => {
                        let src_w = src.width().unwrap_or(0);
                        let src_h = src.height().unwrap_or(0);
                        // A single-plane NV source has a GPU route left even
                        // when the sampler import is refused: the R8 upload of
                        // the combined plane, exactly as in the ShaderR8 arm
                        // above. `draw_src_texture` has no NV arm, so without
                        // this the whole convert died here (issue #166) — which
                        // is how an unaligned NV12 plane offset failed on
                        // Vivante, whose Auto policy takes the sampler and
                        // whose EGL refuses such an offset outright.
                        let nv_upload_capable = matches!(
                            src_fmt,
                            PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
                        ) && !src.is_multiplane();
                        if src_fmt == PixelFormat::Nv12 && !nv_upload_capable {
                            self.last_nv_convert_path = NvConvertPath::Cpu;
                        }
                        self.convert_stats.zero_copy_declines += 1;
                        // Warn once per buffer (see the ShaderR8 arm): repeats
                        // on the same pooled buffer drop to debug.
                        if self.nv_import_warned.insert(src.buffer_identity().id()) {
                            log::warn!(
                                "EGL image creation failed for {src_fmt} ({src_w}x{src_h}), \
                                 falling back to texture upload (slower): {e}"
                            );
                        } else {
                            log::debug!(
                                "EGL image creation failed for {src_fmt} ({src_w}x{src_h}) \
                                 (repeat): {e}"
                            );
                        }
                        let start = Instant::now();
                        if nv_upload_capable {
                            // Same shader, same in-shader matrix, source read
                            // through `map()`.
                            // Recorded from the result: a drawn upload is still
                            // a GPU convert (ShaderR8), a failed one records Cpu
                            // rather than keeping the previous convert's value.
                            match self.draw_nv_texture_2d(
                                src,
                                src_fmt,
                                None,
                                nv_rect,
                                dst_roi,
                                rotation_offset,
                                flip,
                                is_int8,
                                convert_span,
                            ) {
                                Ok(()) => {
                                    if src_fmt == PixelFormat::Nv12 {
                                        self.last_nv_convert_path = NvConvertPath::ShaderR8;
                                    }
                                }
                                Err(e) => {
                                    if src_fmt == PixelFormat::Nv12 {
                                        self.last_nv_convert_path = NvConvertPath::Cpu;
                                    }
                                    return Err(e);
                                }
                            }
                            log::debug!("NV R8 upload takes {:?}", start.elapsed());
                        } else if matches!(
                            src_fmt,
                            PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
                        ) {
                            // A multiplane NV source has no upload route
                            // (`draw_src_texture` has no NV arm), so the
                            // import's own refusal is the reason to report.
                            return Err(e);
                        } else {
                            self.draw_src_texture(
                                src,
                                src_fmt,
                                src_roi,
                                dst_roi,
                                rotation_offset,
                                flip,
                                is_int8,
                                convert_span,
                            )?;
                            log::debug!("draw_src_texture takes {:?}", start.elapsed());
                        }
                    }
                }
            }
        } else if matches!(
            src_fmt,
            PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
        ) && !src.is_multiplane()
        {
            // Non-DMA single-plane NV* (a host or PBO source, or any source
            // on a backend without DMA-BUF import, e.g. orin): the SAME
            // ShaderR8 in-shader path used for DMA, with the combined buffer
            // UPLOADED as R8 instead of EGLImage-imported. Multiplane NV12
            // (separate Y/UV buffers) cannot be uploaded as one R8 texture →
            // CPU below.
            tracing::trace!(path = "ShaderR8-upload", src_fmt = ?src_fmt, "image.convert.gl.nv_path");
            // Recorded from the draw's result, like the four DMA arms above: a
            // failed upload records Cpu rather than leaving a ShaderR8 claim or
            // the previous convert's value.
            match self.draw_nv_texture_2d(
                src,
                src_fmt,
                None,
                nv_rect,
                dst_roi,
                rotation_offset,
                flip,
                is_int8,
                convert_span,
            ) {
                Ok(()) => self.last_nv_convert_path = NvConvertPath::ShaderR8,
                Err(e) => {
                    self.last_nv_convert_path = NvConvertPath::Cpu;
                    return Err(e);
                }
            }
        } else {
            // Non-DMA source, non-NV (or multiplane NV): CPU texture-upload path.
            if matches!(
                src_fmt,
                PixelFormat::Nv12 | PixelFormat::Nv16 | PixelFormat::Nv24
            ) {
                self.last_nv_convert_path = NvConvertPath::Cpu;
            }
            let start = Instant::now();
            self.draw_src_texture(
                src,
                src_fmt,
                src_roi,
                dst_roi,
                rotation_offset,
                flip,
                is_int8,
                convert_span,
            )?;
            log::debug!("draw_src_texture takes {:?}", start.elapsed());
        }

        // In a batch (`defer_finish`), skip the per-tile drain so the whole
        // batch syncs once via `finish_via_fence` in `convert_batch`. Outside a
        // batch this is the standalone convert's completion point and must run.
        if !self.defer_finish {
            let start = Instant::now();
            unsafe { edgefirst_gl::gl::Finish() };
            log::debug!("gl_Finish takes {:?}", start.elapsed());
        }
        check_gl_error(function!(), line!())?;
        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    fn convert_to_planar(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &Tensor<u8>,
        dst_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> Result<(), crate::Error> {
        let src_w = src.width().ok_or(Error::NotAnImage)?;
        let src_h = src.height().ok_or(Error::NotAnImage)?;
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        // if let Some(crop) = crop.src_rect
        //     && (crop.left > 0
        //         || crop.top > 0
        //         || crop.height < src.height()
        //         || crop.width < src.width())
        // {
        //     return Err(crate::Error::NotSupported(
        //         "Cropping in planar RGB mode is not supported".to_string(),
        //     ));
        // }

        // if let Some(crop) = crop.dst_rect
        //     && (crop.left > 0
        //         || crop.top > 0
        //         || crop.height < src.height()
        //         || crop.width < src.width())
        // {
        //     return Err(crate::Error::NotSupported(
        //         "Cropping in planar RGB mode is not supported".to_string(),
        //     ));
        // }

        let alpha = match dst_fmt {
            PixelFormat::PlanarRgb => false,
            PixelFormat::PlanarRgba => true,
            _ => {
                return Err(crate::Error::NotSupported(
                    "Destination format must be PlanarRgb or PlanarRgba".to_string(),
                ));
            }
        };
        log::trace!(
            "convert_to_planar: int8={is_int8}, interpolation={:?}",
            self.int8_interpolation_mode
        );

        let src_roi = if let Some(crop) = crop.src_rect {
            RegionOfInterest::from_crop(&crop, src_w, src_h)
        } else {
            RegionOfInterest {
                left: 0.,
                top: 1.,
                right: 1.,
                bottom: 0.,
            }
        };

        let cvt_screen_coord = |normalized| normalized * 2.0 - 1.0;
        let dst_roi = if let Some(crop) = crop.dst_rect {
            RegionOfInterest {
                left: cvt_screen_coord(crop.left as f32 / dst_w as f32),
                top: cvt_screen_coord((crop.top + crop.height) as f32 / dst_h as f32),
                right: cvt_screen_coord((crop.left + crop.width) as f32 / dst_w as f32),
                bottom: cvt_screen_coord(crop.top as f32 / dst_h as f32),
            }
        } else {
            RegionOfInterest {
                left: -1.,
                top: 1.,
                right: 1.,
                bottom: -1.,
            }
        };
        let rotation_offset = match rotation {
            crate::Rotation::None => 0,
            crate::Rotation::Clockwise90 => 1,
            crate::Rotation::Rotate180 => 2,
            crate::Rotation::CounterClockwise90 => 3,
        };

        let has_crop = crop
            .dst_rect
            .is_some_and(|x| x.left != 0 || x.top != 0 || x.width != dst_w || x.height != dst_h);
        if has_crop {
            if let Some(dst_color) = crop.dst_color {
                self.clear_rect_planar(
                    dst_w,
                    dst_h,
                    [
                        dst_color[0] as f32 / 255.0,
                        dst_color[1] as f32 / 255.0,
                        dst_color[2] as f32 / 255.0,
                        dst_color[3] as f32 / 255.0,
                    ],
                    alpha,
                )?;
            }
        }

        let src_key = BufferImportKey::from_tensor(src, src_fmt, false);
        let src_egl = self.get_or_create_egl_image(CacheKind::Src, src, src_fmt)?;
        // This route imports unconditionally -- there is no upload arm to
        // choose between -- but it is still a source feed, and a field
        // recorded on every convert except one is worse than no field: the
        // single-pass planar route would be the only u8 convert whose
        // `src_feed` is absent, which reads as "not fed by GL at all".
        self.convert_stats.src_imports += 1;
        convert_span.record("src_feed", "import");
        // As in `draw_src_texture`: the import may cover more of the texture
        // than the logical image, and may start it partway in. One cache
        // lookup feeds both the source rectangle and the sampling clamp.
        let src_map = self.cached_src_import_map(src, src_fmt);
        let src_extent =
            super::render::sample_clamp_rect_within((src_w, src_h), src_map, src_roi.uv_bounds());
        let src_roi = super::render::scale_roi_to_import(src_roi, (src_w, src_h), src_map);

        self.draw_camera_texture_to_rgb_planar(
            src_key,
            src_egl,
            src_roi,
            src_extent,
            dst_roi,
            rotation_offset,
            flip,
            alpha,
            is_int8,
        )?;
        unsafe { edgefirst_gl::gl::Finish() };
        check_gl_error(function!(), line!())?;

        Ok(())
    }

    /// Render packed RGB (or int8 RGB) to a DMA destination buffer using a
    /// two-pass architecture:
    ///
    /// **Pass 1:** Render source → intermediate RGBA texture via `convert_to()`
    /// (reuses the battle-tested RGBA path with full crop/letterbox/rotation/flip).
    ///
    /// **Pass 2:** Pack intermediate RGBA → RGB DMA destination using a simple
    /// packing shader with 2D sampler. The destination DMA buffer is reinterpreted
    /// as RGBA8 at (W*3/4) x H dimensions.
    #[allow(clippy::too_many_arguments)]
    fn convert_to_packed_rgb(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> crate::Result<()> {
        if self.int_pad_output {
            return Err(Error::NotSupported(
                "GL two-pass integer convert cannot write an output-domain pad; CPU fallback"
                    .into(),
            ));
        }
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;

        // Canonical RGBA8888-packed geometry (single source of truth shared
        // with the Android AHardwareBuffer allocation side — the same rule
        // that keeps the F16 packing from drifting between crates).
        let layout = edgefirst_tensor::packed_rgb888_layout(dst_w, dst_h).ok_or_else(|| {
            crate::Error::NotSupported(format!(
                "Packed RGB requires width%4==0 (W*3 bytes must divide into \
                 whole RGBA8888 texels), got width={dst_w}"
            ))
        })?;
        let render_w = layout.surface_w;
        let render_h = layout.surface_h;

        log::debug!(
            "convert_to_packed_rgb: {dst_w}x{dst_h} -> {render_w}x{render_h} two-pass int8={is_int8}",
        );

        // --- Pass 1: Render source → intermediate RGBA texture ---
        let _pass1 =
            tracing::trace_span!("image.convert.gl.pack_rgb.pass1_rgba", dst_w, dst_h).entered();
        self.ensure_packed_rgb_intermediate(dst_w, dst_h)?;
        self.packed_rgb_fbo.bind();
        unsafe {
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.packed_rgb_intermediate_tex.id,
                0,
            );
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, dst_w as i32, dst_h as i32);
        }
        // convert_to() renders to the currently-bound FBO (packed_rgb_fbo → intermediate).
        // It uses dst only for width/height in ROI coordinate math.
        // Handles: source binding (DMA EGLImage or upload), crop, letterbox, rotation, flip.
        // Pass 1 renders UN-biased (is_int8 = false): the int8 XOR-0x80 bias is
        // applied once, by pass 2's packing shader.
        //
        // Pass 1 must NOT glFinish (convert_to's standalone-boundary sync):
        // same-context command ordering already guarantees pass 2 samples the
        // finished intermediate, and the convert syncs once at pass 2's end.
        // The flag restores before `?` so an error cannot leak defer state.
        let saved_defer = self.defer_finish;
        self.defer_finish = true;
        let pass1 = self.convert_to(
            src,
            src_fmt,
            dst,
            dst_fmt,
            None,
            false,
            rotation,
            flip,
            crop,
            convert_span,
        );
        self.defer_finish = saved_defer;
        pass1?;
        drop(_pass1);

        // --- Pass 2: Pack intermediate RGBA → RGB DMA destination ---
        let _pass2 =
            tracing::trace_span!("image.convert.gl.pack_rgb.pass2_pack", render_w, render_h)
                .entered();
        self.convert_fbo.bind();
        let dest_egl = self.get_or_create_egl_image_rgb(
            dst,
            dst_fmt,
            render_w,
            render_h,
            super::platform::PackedImportFormat::Rgba8888,
        )?;
        unsafe {
            match self.cached_dst_renderbuffer(dst, dst_fmt) {
                Some(rbo) => {
                    edgefirst_gl::gl::BindRenderbuffer(edgefirst_gl::gl::RENDERBUFFER, rbo);
                    edgefirst_gl::gl::FramebufferRenderbuffer(
                        edgefirst_gl::gl::FRAMEBUFFER,
                        edgefirst_gl::gl::COLOR_ATTACHMENT0,
                        edgefirst_gl::gl::RENDERBUFFER,
                        rbo,
                    );
                }
                None => {
                    edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
                    edgefirst_gl::gl::BindTexture(
                        edgefirst_gl::gl::TEXTURE_2D,
                        self.render_texture.id,
                    );
                    super::core::set_tex_filter(
                        edgefirst_gl::gl::TEXTURE_2D,
                        edgefirst_gl::gl::NEAREST,
                    );
                    Platform::attach_tex_image_2d(&self.gl_context, dest_egl)?;
                    // Raw re-target bypasses bind_egl_image's key tracking:
                    // drop the cached key so a later bind_egl_image on this
                    // texture cannot "reuse" a binding this call replaced
                    // (silent write into the wrong destination buffer).
                    self.render_texture.invalidate_egl_binding();
                    edgefirst_gl::gl::FramebufferTexture2D(
                        edgefirst_gl::gl::FRAMEBUFFER,
                        edgefirst_gl::gl::COLOR_ATTACHMENT0,
                        edgefirst_gl::gl::TEXTURE_2D,
                        self.render_texture.id,
                        0,
                    );
                }
            }
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, render_w as i32, render_h as i32);
        }

        // Bind intermediate RGBA texture as source for the packing shader
        let program = if is_int8 {
            &self.packed_rgba8_int8_program_2d
        } else {
            &self.packed_rgba8_program_2d
        };
        unsafe {
            edgefirst_gl::gl::UseProgram(program.id);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE1);
            edgefirst_gl::gl::BindTexture(
                edgefirst_gl::gl::TEXTURE_2D,
                self.packed_rgb_intermediate_tex.id,
            );
            super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::NEAREST);
        }

        // (`tex` = unit 1 is constant per program, uploaded at link time.)

        // Draw full-viewport quad to pack RGBA→RGB
        self.draw_fullscreen_quad()?;

        // Pass 2 bound the intermediate on TEXTURE1: unbind it there and
        // restore unit 0 as the active unit. Draw/setup sites select their
        // unit before binding, but the processor-wide invariant between
        // operations is "unit 0 active" — leaking unit 1 here is what broke
        // the second heap-source convert (GL_INVALID_VALUE upload into the
        // wrong texture). The unbind is for Vivante: while the intermediate
        // stayed bound to unit 1, the planar pass 2 that samples it on unit 0
        // through a per-plane TEXTURE_SWIZZLE_R wrote wrong second and third
        // planes for every planar convert that followed a packed-RGB one.
        unsafe {
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, 0);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
        };

        unsafe { edgefirst_gl::gl::Finish() };
        check_gl_error(function!(), line!())?;
        Ok(())
    }

    /// Two-pass `ConvertPlan::TwoPassNvPlanar` render: ANY source format
    /// into a planar destination, via an ordinary packed intermediate.
    /// Named for its original motivation — the Verisilicon/Vivante
    /// GC7000UL single-pass NV12→PlanarRgb GPU hang — but `plan_convert`
    /// now also selects this plan for non-NV sources on a texture (Mem/Pbo)
    /// lowering, where the single-pass planar shader has no route at all
    /// (see `ConvertPlan::TwoPassNvPlanar`'s doc). This method splits the
    /// operation:
    ///
    /// **Pass 1:** src→RGBA into `packed_rgb_intermediate_tex` via
    /// `convert_to()` (full resize/crop/rotation/flip, no int8 bias) — the
    /// same packed path every non-planar destination already uses, so it
    /// inherits that path's per-format source handling for free.
    ///
    /// **Pass 2:** RGBA→PlanarRgb from the intermediate into whatever
    /// `bind_dst` classified the destination as (zero-copy: written
    /// directly, no readback; texture: read back below) via
    /// [`draw_intermediate_to_rgb_planar`] (channel deinterleave + optional
    /// int8 bias).
    #[allow(clippy::too_many_arguments)]
    fn convert_nv_to_planar_two_pass(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        dst: &mut Tensor<u8>,
        dst_fmt: PixelFormat,
        is_int8: bool,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        lowering: super::render::DstLowering,
        convert_span: &tracing::Span,
    ) -> crate::Result<()> {
        if self.int_pad_output {
            return Err(Error::NotSupported(
                "GL two-pass integer convert cannot write an output-domain pad; CPU fallback"
                    .into(),
            ));
        }
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;

        let alpha = match dst_fmt {
            PixelFormat::PlanarRgb => false,
            PixelFormat::PlanarRgba => true,
            _ => {
                return Err(crate::Error::NotSupported(
                    "Destination format must be PlanarRgb or PlanarRgba".to_string(),
                ));
            }
        };

        log::debug!(
            "convert_nv_to_planar_two_pass: {src_fmt}→{dst_fmt} {dst_w}x{dst_h} int8={is_int8}",
        );

        // --- Pass 1: src→RGBA into intermediate texture ---
        // No int8 bias here — bias is applied in pass 2's planar shader.
        let _pass1 = tracing::trace_span!("image.convert.gl.nv_to_planar.pass1_rgba", dst_w, dst_h)
            .entered();
        self.ensure_packed_rgb_intermediate(dst_w, dst_h)?;
        self.packed_rgb_fbo.bind();
        unsafe {
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.packed_rgb_intermediate_tex.id,
                0,
            );
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, dst_w as i32, dst_h as i32);
        }
        // convert_to() renders to the currently-bound FBO (packed_rgb_fbo → intermediate RGBA).
        // Note: dst_fmt is passed but ignored (_dst_fmt in convert_to's signature) — the actual
        // output format is RGBA because we bound packed_rgb_fbo above. dst is used only for
        // width/height in ROI coordinate math.
        // Pass 1 renders UN-biased (is_int8 = false): the int8 XOR-0x80 bias is
        // applied once, by pass 2's planar deinterleave shader.
        //
        // Pass 1 must NOT glFinish (convert_to's standalone-boundary sync):
        // same-context command ordering already guarantees pass 2 samples the
        // finished intermediate, and the convert syncs once at pass 2's end.
        let saved_defer = self.defer_finish;
        self.defer_finish = true;
        let pass1 = self.convert_to(
            src,
            src_fmt,
            dst,
            dst_fmt,
            None,
            false,
            rotation,
            flip,
            crop,
            convert_span,
        );
        self.defer_finish = saved_defer;
        pass1?;
        drop(_pass1);

        // --- Pass 2: RGBA→planar into the classified destination ---
        // bind_dst rebinds convert_fbo with the destination target (DMA
        // EGLImage — zero-copy, no readback needed — or a texture backed by
        // the Mem/Pbo readback below), replacing packed_rgb_fbo that was
        // active during pass 1. It also sets the viewport to
        // (dst_w, dst_h * planes) for the tall R8 planar target.
        let _pass2 = tracing::trace_span!(
            "image.convert.gl.nv_to_planar.pass2_deinterleave",
            dst_w,
            dst_h
        )
        .entered();
        let (target, _bound) = self.bind_dst(dst, dst_fmt, crop, lowering)?;
        Self::record_dst_feed(convert_span, target);

        // Pass 2 is a fullscreen blit from the intermediate to the planar
        // destination. Pass 1 (convert_to above) already placed the image
        // content at the correct letterbox position within the intermediate
        // AND filled the padding region with the requested dst_color.
        // Re-applying the dst_rect crop here would map the full intermediate
        // (whose content is already correctly placed) into only the content
        // sub-region, shrinking the image by the letterbox content fraction
        // a second time. Observed downstream as bounding boxes compressed by
        // exactly (content/canvas) in the padded dimension on i.MX 8M Plus.
        //
        // No int8 bias-clear here either: pass 2 performs no clear, and the
        // planar deinterleave shader applies the int8 bias itself (is_int8
        // flag on the draw below).
        let dst_roi = RegionOfInterest {
            left: -1.,
            top: 1.,
            right: 1.,
            bottom: -1.,
        };

        self.draw_intermediate_to_rgb_planar(dst_roi, alpha, is_int8)?;

        unsafe { edgefirst_gl::gl::Finish() };
        check_gl_error(function!(), line!())?;

        // A texture-lowered destination (Mem/Pbo) rendered into an offscreen
        // target above — mirror the SinglePass engine's post-render readback.
        // Zero-copy wrote the destination's own EGLImage directly.
        if let DstTarget::Texture { readback } = target {
            self.readback_rendered(dst, dst_fmt, readback.pbo_id())?;
        }
        Ok(())
    }

    /// Allocates or resizes the intermediate RGBA texture for two-pass packed RGB.
    fn ensure_packed_rgb_intermediate(&mut self, width: usize, height: usize) -> crate::Result<()> {
        if self.packed_rgb_intermediate_size == (width, height) {
            return Ok(());
        }
        unsafe {
            edgefirst_gl::gl::BindTexture(
                edgefirst_gl::gl::TEXTURE_2D,
                self.packed_rgb_intermediate_tex.id,
            );
            super::core::set_tex_filter(edgefirst_gl::gl::TEXTURE_2D, edgefirst_gl::gl::NEAREST);
            edgefirst_gl::gl::TexImage2D(
                edgefirst_gl::gl::TEXTURE_2D,
                0,
                edgefirst_gl::gl::RGBA as i32,
                width as i32,
                height as i32,
                0,
                edgefirst_gl::gl::RGBA,
                edgefirst_gl::gl::UNSIGNED_BYTE,
                std::ptr::null(),
            );
            check_gl_error(function!(), line!())?;
        }
        self.packed_rgb_intermediate_size = (width, height);
        Ok(())
    }

    /// Draw a fullscreen quad for the currently-bound shader program.
    /// Used by the pass-2 packing shader in the two-pass packed RGB pipeline.
    fn draw_fullscreen_quad(&self) -> Result<(), crate::Error> {
        unsafe {
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            let vertices: [f32; 12] = [
                -1.0, 1.0, 0.0, // top-left
                1.0, 1.0, 0.0, // top-right
                1.0, -1.0, 0.0, // bottom-right
                -1.0, -1.0, 0.0, // bottom-left
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * vertices.len()) as isize,
                vertices.as_ptr() as *const c_void,
            );

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

            // Texture coordinates (the packed shader uses gl_FragCoord, not tc,
            // but we still need valid buffers for the vertex attribute layout)
            let tex_coords: [f32; 8] = [0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * tex_coords.len()) as isize,
                tex_coords.as_ptr() as *const c_void,
            );

            let indices: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                indices.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                indices.as_ptr() as *const c_void,
            );
        }
        check_gl_error(function!(), line!())?;
        Ok(())
    }

    /// Fill each plane of the `(width, split * height)` planar target with
    /// its pad value before the content is drawn over it. Plane `i` is the
    /// framebuffer band of rows `[i * height, (i + 1) * height)` (the draws
    /// start from the bottom).
    fn clear_rect_planar(
        &self,
        width: usize,
        height: usize,
        color: [f32; 4],
        alpha: bool,
    ) -> Result<(), Error> {
        let split = if alpha { 4 } else { 3 };
        // SAFETY: on the GL thread with the planar target bound.
        unsafe {
            if color[..split].iter().all(|&c| c == color[0]) {
                edgefirst_gl::gl::ClearColor(color[0], color[0], color[0], 1.0);
                edgefirst_gl::gl::Clear(edgefirst_gl::gl::COLOR_BUFFER_BIT);
                return Ok(());
            }
            edgefirst_gl::gl::Enable(edgefirst_gl::gl::SCISSOR_TEST);
            for (i, c) in color.iter().enumerate().take(split) {
                edgefirst_gl::gl::Scissor(0, (i * height) as i32, width as i32, height as i32);
                edgefirst_gl::gl::ClearColor(*c, *c, *c, 1.0);
                edgefirst_gl::gl::Clear(edgefirst_gl::gl::COLOR_BUFFER_BIT);
            }
            edgefirst_gl::gl::Disable(edgefirst_gl::gl::SCISSOR_TEST);
        }
        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    fn draw_camera_texture_to_rgb_planar(
        &mut self,
        src_key: BufferImportKey,
        egl_img: PlatformHandle,
        src_roi: RegionOfInterest,
        // The rectangle a sample may reach on the imported texture
        // (`render::sample_clamp_rect`), computed at the call site from the
        // same `ImportMap` that produced `src_roi`.
        src_extent: [f32; 4],
        mut dst_roi: RegionOfInterest,
        rotation_offset: usize,
        flip: Flip,
        alpha: bool,
        int8: bool,
    ) -> Result<(), Error> {
        let texture_target = edgefirst_gl::gl::TEXTURE_EXTERNAL_OES;
        match flip {
            Flip::None => {}
            Flip::Vertical => {
                std::mem::swap(&mut dst_roi.top, &mut dst_roi.bottom);
            }
            Flip::Horizontal => {
                std::mem::swap(&mut dst_roi.left, &mut dst_roi.right);
            }
        }
        let program_id = if int8 {
            &self.texture_program_planar_int8
        } else {
            &self.texture_program_planar
        }
        .as_ref()
        .ok_or_else(|| {
            Error::NotSupported("external-OES planar program unavailable on this platform".into())
        })?
        .id;
        let raw_alpha_id = self.texture_program_planar.as_ref().map_or(0, |p| p.id);
        unsafe {
            edgefirst_gl::gl::UseProgram(program_id);
            let [e0, e1, e2, e3] = src_extent;
            edgefirst_gl::gl::Uniform4f(self.external_src_extent_loc(int8, true), e0, e1, e2, e3);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(texture_target, self.camera_eglimage_texture.id);
            super::core::set_tex_filter(texture_target, self.source_filter());
            edgefirst_gl::gl::TexParameteri(
                texture_target,
                edgefirst_gl::gl::TEXTURE_WRAP_S,
                edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
            );

            edgefirst_gl::gl::TexParameteri(
                texture_target,
                edgefirst_gl::gl::TEXTURE_WRAP_T,
                edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
            );

            if self.camera_eglimage_texture.bind_egl_image_external(
                &self.gl_context,
                src_key,
                egl_img,
            )? {
                check_gl_error(function!(), line!())?;
                log::trace!(
                    "draw_camera_planar: bound new src EGLImage id={:#x}",
                    src_key.luma_id
                );
            } else {
                log::trace!(
                    "draw_camera_planar: reusing bound src EGLImage id={:#x}",
                    src_key.luma_id
                );
            }
            let y_centers = if alpha {
                vec![-3.0 / 4.0, -1.0 / 4.0, 1.0 / 4.0, 3.0 / 4.0]
            } else {
                vec![-2.0 / 3.0, 0.0, 2.0 / 3.0]
            };
            let planes = y_centers.len() as f32;
            let swizzles = [
                edgefirst_gl::gl::RED,
                edgefirst_gl::gl::GREEN,
                edgefirst_gl::gl::BLUE,
                edgefirst_gl::gl::ALPHA,
            ];
            // starts from bottom
            for (i, y_center) in y_centers.iter().enumerate() {
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
                edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);
                let camera_vertices: [f32; 12] = [
                    dst_roi.left,
                    dst_roi.top / planes + y_center,
                    0., // left top
                    dst_roi.right,
                    dst_roi.top / planes + y_center,
                    0., // right top
                    dst_roi.right,
                    dst_roi.bottom / planes + y_center,
                    0., // right bottom
                    dst_roi.left,
                    dst_roi.bottom / planes + y_center,
                    0., // left bottom
                ];
                edgefirst_gl::gl::BufferData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    (size_of::<f32>() * camera_vertices.len()) as isize,
                    camera_vertices.as_ptr() as *const c_void,
                    edgefirst_gl::gl::DYNAMIC_DRAW,
                );

                edgefirst_gl::gl::BindBuffer(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    self.texture_buffer.id,
                );
                edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);
                let texture_vertices: [f32; 16] = [
                    src_roi.left,
                    src_roi.top,
                    src_roi.right,
                    src_roi.top,
                    src_roi.right,
                    src_roi.bottom,
                    src_roi.left,
                    src_roi.bottom,
                    src_roi.left,
                    src_roi.top,
                    src_roi.right,
                    src_roi.top,
                    src_roi.right,
                    src_roi.bottom,
                    src_roi.left,
                    src_roi.bottom,
                ];

                edgefirst_gl::gl::BufferData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    (size_of::<f32>() * 8) as isize,
                    (texture_vertices[(rotation_offset * 2)..]).as_ptr() as *const c_void,
                    edgefirst_gl::gl::DYNAMIC_DRAW,
                );
                let vertices_index: [u32; 4] = [0, 1, 2, 3];
                // self.texture_program_planar
                //     .load_uniform_1i(c"color_index", 2 - i as i32);

                edgefirst_gl::gl::TexParameteri(
                    texture_target,
                    edgefirst_gl::gl::TEXTURE_SWIZZLE_R,
                    swizzles[i] as i32,
                );
                if int8 && i == 3 {
                    // Integer alpha stays the raw byte: the u8 program draws it.
                    self.set_plane_quant(program_id, None);
                    edgefirst_gl::gl::UseProgram(raw_alpha_id);
                    let [e0, e1, e2, e3] = src_extent;
                    edgefirst_gl::gl::Uniform4f(
                        self.external_src_extent_loc(false, true),
                        e0,
                        e1,
                        e2,
                        e3,
                    );
                } else {
                    self.set_plane_quant(program_id, Some(i));
                }

                edgefirst_gl::gl::DrawElements(
                    edgefirst_gl::gl::TRIANGLE_FAN,
                    vertices_index.len() as i32,
                    edgefirst_gl::gl::UNSIGNED_INT,
                    vertices_index.as_ptr() as *const c_void,
                );
            }
            if !(int8 && alpha) {
                self.set_plane_quant(program_id, None);
            }
            // Reset the texture swizzle to identity before returning. The
            // loop above left `TEXTURE_SWIZZLE_R` pointing at the last
            // requested planar channel (`GL_BLUE` for RGB, `GL_ALPHA` when
            // `alpha` is true). The GLES spec says `GL_TEXTURE_SWIZZLE_*` is
            // undefined for `GL_TEXTURE_EXTERNAL_OES`, but NXP Vivante and
            // Mali drivers honor it on external textures and the swizzle
            // persists across subsequent samples — including the bg blit in
            // `draw_decoded_masks`, which then channel-permutes the entire
            // overlay's background. Restoring identity before any later
            // sampler sees this texture is the safe move.
            edgefirst_gl::gl::TexParameteri(
                texture_target,
                edgefirst_gl::gl::TEXTURE_SWIZZLE_R,
                edgefirst_gl::gl::RED as i32,
            );
            check_gl_error(function!(), line!())?;
        }
        Ok(())
    }

    /// Draw the intermediate RGBA texture to planar RGB output.
    ///
    /// Pass 2 of the two-pass NV12→PlanarRgb workaround for Vivante GPUs.
    /// Mirrors [`draw_camera_texture_to_rgb_planar`] but sources from
    /// `packed_rgb_intermediate_tex` (a `TEXTURE_2D`) instead of an EGLImage
    /// (`TEXTURE_EXTERNAL_OES`). No rotation/flip — those were handled in pass 1.
    fn draw_intermediate_to_rgb_planar(
        &self,
        dst_roi: RegionOfInterest,
        alpha: bool,
        int8: bool,
    ) -> Result<(), Error> {
        let texture_target = edgefirst_gl::gl::TEXTURE_2D;
        unsafe {
            let program = if int8 {
                &self.texture_program_planar_int8_2d
            } else {
                &self.texture_program_planar_2d
            };
            edgefirst_gl::gl::UseProgram(program.id);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(texture_target, self.packed_rgb_intermediate_tex.id);
            // NEAREST: a 1:1 copy of pass 1's output, which already resampled.
            // LINEAR would blend a sliver of the neighbouring texel wherever
            // the interpolated coordinate misses the texel centre (±1 on V3D
            // and Adreno).
            super::core::set_tex_filter_clamp(texture_target, edgefirst_gl::gl::NEAREST);

            // (`tex` = unit 0 is constant per program, uploaded at link time.)
            check_gl_error(function!(), line!())?;

            let y_centers = if alpha {
                vec![-3.0 / 4.0, -1.0 / 4.0, 1.0 / 4.0, 3.0 / 4.0]
            } else {
                vec![-2.0 / 3.0, 0.0, 2.0 / 3.0]
            };
            let planes = y_centers.len() as f32;
            let swizzles = [
                edgefirst_gl::gl::RED,
                edgefirst_gl::gl::GREEN,
                edgefirst_gl::gl::BLUE,
                edgefirst_gl::gl::ALPHA,
            ];

            // Source ROI is always fullscreen (intermediate is already at destination size)
            let src_roi = RegionOfInterest {
                left: 0.0,
                top: 1.0,
                right: 1.0,
                bottom: 0.0,
            };

            for (i, y_center) in y_centers.iter().enumerate() {
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
                edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);
                let camera_vertices: [f32; 12] = [
                    dst_roi.left,
                    dst_roi.top / planes + y_center,
                    0., // left top
                    dst_roi.right,
                    dst_roi.top / planes + y_center,
                    0., // right top
                    dst_roi.right,
                    dst_roi.bottom / planes + y_center,
                    0., // right bottom
                    dst_roi.left,
                    dst_roi.bottom / planes + y_center,
                    0., // left bottom
                ];
                edgefirst_gl::gl::BufferData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    (size_of::<f32>() * camera_vertices.len()) as isize,
                    camera_vertices.as_ptr() as *const c_void,
                    edgefirst_gl::gl::DYNAMIC_DRAW,
                );

                edgefirst_gl::gl::BindBuffer(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    self.texture_buffer.id,
                );
                edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);
                // No rotation — pass 1 already handled it. Use base texture coords directly.
                let texture_vertices: [f32; 8] = [
                    src_roi.left,
                    src_roi.top,
                    src_roi.right,
                    src_roi.top,
                    src_roi.right,
                    src_roi.bottom,
                    src_roi.left,
                    src_roi.bottom,
                ];
                edgefirst_gl::gl::BufferData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    (size_of::<f32>() * texture_vertices.len()) as isize,
                    texture_vertices.as_ptr() as *const c_void,
                    edgefirst_gl::gl::DYNAMIC_DRAW,
                );

                let vertices_index: [u32; 4] = [0, 1, 2, 3];

                edgefirst_gl::gl::TexParameteri(
                    texture_target,
                    edgefirst_gl::gl::TEXTURE_SWIZZLE_R,
                    swizzles[i] as i32,
                );
                if int8 && i == 3 {
                    // Integer alpha stays the raw byte: the u8 program draws it.
                    self.set_plane_quant(program.id, None);
                    edgefirst_gl::gl::UseProgram(self.texture_program_planar_2d.id);
                } else {
                    self.set_plane_quant(program.id, Some(i));
                }

                edgefirst_gl::gl::DrawElements(
                    edgefirst_gl::gl::TRIANGLE_FAN,
                    vertices_index.len() as i32,
                    edgefirst_gl::gl::UNSIGNED_INT,
                    vertices_index.as_ptr() as *const c_void,
                );
            }
            if !(int8 && alpha) {
                self.set_plane_quant(program.id, None);
            }
            // Reset the texture swizzle to identity (see the matching
            // comment in `draw_camera_texture_to_rgb_planar` above). This
            // path operates on a `TEXTURE_2D` intermediate, which honors the
            // swizzle per spec — leaving `TEXTURE_SWIZZLE_R` set to the last
            // planar channel selected (for example `GL_BLUE` for RGB or
            // `GL_ALPHA` for RGBA) poisons every later sampler bound to this
            // texture object.
            edgefirst_gl::gl::TexParameteri(
                texture_target,
                edgefirst_gl::gl::TEXTURE_SWIZZLE_R,
                edgefirst_gl::gl::RED as i32,
            );
            check_gl_error(function!(), line!())?;
        }
        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    fn draw_src_texture(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        mut src_roi: RegionOfInterest,
        mut dst_roi: RegionOfInterest,
        rotation_offset: usize,
        flip: Flip,
        is_int8: bool,
        convert_span: &tracing::Span,
    ) -> Result<(), Error> {
        let src_w = src.width().ok_or(Error::NotAnImage)?;
        let src_h = src.height().ok_or(Error::NotAnImage)?;
        let texture_target = edgefirst_gl::gl::TEXTURE_2D;
        // Zero-copy source attach: on platforms whose imports bind as
        // TEXTURE_2D (macOS IOSurface), a Dma-memory source is imported
        // and attached to the source texture instead of being uploaded.
        // Import errors fall back to the upload below (the map() of an
        // IOSurface tensor is always valid); YUYV has no upload arm and
        // is accepted only when its RG attach succeeds.
        let zero_copy_attach = if !self.gl_context.transfer_backend.is_dma()
            && self.gl_context.transfer_backend.is_zero_copy()
            && src.memory() == TensorMemory::DmaBuf
            && matches!(
                src_fmt,
                PixelFormat::Rgba | PixelFormat::Grey | PixelFormat::Yuyv
            ) {
            let key = BufferImportKey::from_tensor(src, src_fmt, false);
            match self.get_or_create_egl_image(CacheKind::Src, src, src_fmt) {
                Ok(handle) => Some((key, handle)),
                Err(e) => {
                    self.convert_stats.zero_copy_declines += 1;
                    log::debug!("zero-copy source import failed ({e:?}); uploading instead");
                    None
                }
            }
        } else {
            None
        };
        // An import can cover more of the texture than the logical image (a
        // pool tensor narrowed by `configure_image`) and can start it partway
        // in (a source rebased onto an aligned DMA-BUF base, issue #170);
        // sample only the logical part. `WHOLE` when the source is uploaded
        // instead, and on every platform whose import is already the logical
        // image.
        let import_map = if zero_copy_attach.is_some() {
            self.cached_src_import_map(src, src_fmt)
        } else {
            super::render::ImportMap::WHOLE
        };
        // The shader clamps every sample to the crop's (or else the logical
        // image's) half-texel-inset rectangle on the texture, so an upscale's
        // last row or column cannot blend the texel beyond the crop or a
        // narrowed or shifted image.
        let [u0, v0, u1, v1] = super::render::sample_clamp_rect_within(
            (src_w, src_h),
            import_map,
            src_roi.uv_bounds(),
        );
        src_roi = super::render::scale_roi_to_import(src_roi, (src_w, src_h), import_map);
        let texture_format = match src_fmt {
            PixelFormat::Rgb => edgefirst_gl::gl::RGB,
            PixelFormat::Rgba => edgefirst_gl::gl::RGBA,
            PixelFormat::Grey => edgefirst_gl::gl::RED,
            // YUYV samples as RG, one texel per pixel: R is the pixel's Y,
            // G alternates U (even column) and V (odd column). An attach and
            // an upload of the raw bytes both give that layout.
            PixelFormat::Yuyv => edgefirst_gl::gl::RG,
            _ => {
                return Err(Error::NotSupported(format!(
                    "draw_src_texture does not support {src_fmt:?} (use DMA-BUF path for YUV)",
                )));
            }
        };
        // Draw-time program selection: the int8 program is the same shader
        // plus the XOR-0x80 bias, selected here instead of swap-and-restore
        // around the render.
        let program_id = if src_fmt == PixelFormat::Yuyv {
            if is_int8 {
                self.yuyv_int8_program_2d.id
            } else {
                self.yuyv_program_2d.id
            }
        } else if is_int8 {
            self.texture_int8_program.id
        } else {
            self.texture_program.id
        };
        unsafe {
            edgefirst_gl::gl::UseProgram(program_id);
            if src_fmt == PixelFormat::Yuyv {
                // YUYV program inputs: source texel grid + the YUV→RGB
                // matrix/range resolved from the tensor colorimetry (same
                // resolution rule as the NV paths).
                let cm = crate::colorimetry::resolve_colorimetry(src.colorimetry(), src.height());
                let coeffs = crate::colorimetry::yuv_to_rgb_coeffs(
                    cm.encoding
                        .unwrap_or(edgefirst_tensor::ColorEncoding::Bt709),
                    cm.range.unwrap_or(edgefirst_tensor::ColorRange::Limited),
                );
                let [src_size, y_offset, y_scale, c_vr, c_ug, c_vg, c_ub, src_extent] =
                    self.yuyv_2d_locs[usize::from(is_int8)];
                // The shader rebuilds texel coordinates as `floor(tc * src_size)`,
                // and `tc` was just scaled onto the imported texture, so this
                // must be the texture's own texel grid — not the logical image's,
                // which would land the pair lookup on the wrong column. A
                // nonzero origin would break the Y/UV pair phase, so YUYV is
                // never rebased (`DmaImportAttrs::from_tensor`).
                debug_assert_eq!(
                    import_map.origin,
                    (0, 0),
                    "YUYV must not be sampled through a shifted import"
                );
                let (grid_w, grid_h) = import_map
                    .extent
                    .map_or((src_w as f32, src_h as f32), |(pw, ph)| {
                        (pw as f32, ph as f32)
                    });
                edgefirst_gl::gl::Uniform2f(src_size, grid_w, grid_h);
                edgefirst_gl::gl::Uniform4f(src_extent, u0, v0, u1, v1);
                edgefirst_gl::gl::Uniform1f(y_offset, coeffs.y_offset);
                edgefirst_gl::gl::Uniform1f(y_scale, coeffs.y_scale);
                edgefirst_gl::gl::Uniform1f(c_vr, coeffs.c_vr);
                edgefirst_gl::gl::Uniform1f(c_ug, coeffs.c_ug);
                edgefirst_gl::gl::Uniform1f(c_vg, coeffs.c_vg);
                edgefirst_gl::gl::Uniform1f(c_ub, coeffs.c_ub);
            } else {
                edgefirst_gl::gl::Uniform4f(self.texture_src_extent_loc(is_int8), u0, v0, u1, v1);
            }
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(texture_target, self.camera_normal_texture.id);
            super::core::set_tex_filter_clamp(texture_target, self.source_filter());
            if src_fmt == PixelFormat::Grey {
                for swizzle in [
                    edgefirst_gl::gl::TEXTURE_SWIZZLE_R,
                    edgefirst_gl::gl::TEXTURE_SWIZZLE_G,
                    edgefirst_gl::gl::TEXTURE_SWIZZLE_B,
                ] {
                    edgefirst_gl::gl::TexParameteri(
                        edgefirst_gl::gl::TEXTURE_2D,
                        swizzle,
                        edgefirst_gl::gl::RED as i32,
                    );
                }
            } else {
                for (swizzle, src_comp) in [
                    (edgefirst_gl::gl::TEXTURE_SWIZZLE_R, edgefirst_gl::gl::RED),
                    (edgefirst_gl::gl::TEXTURE_SWIZZLE_G, edgefirst_gl::gl::GREEN),
                    (edgefirst_gl::gl::TEXTURE_SWIZZLE_B, edgefirst_gl::gl::BLUE),
                ] {
                    edgefirst_gl::gl::TexParameteri(
                        edgefirst_gl::gl::TEXTURE_2D,
                        swizzle,
                        src_comp as i32,
                    );
                }
            }
            // The source map exposes the full row-padded allocation (DMA/IOSurface
            // tensors carry a 64-byte-aligned pitch). TexImage2D otherwise reads
            // `src_w` tight pixels per row from a padded buffer, shearing every row
            // after the first — the failure mode for odd-width Grey/RGB, whose
            // 1-/3-bpp pitch is not 4-aligned so they can't take the stride-aware
            // EGLImage path. Tell GL the real row length (in pixels) so it skips
            // the padding; reset afterwards so other uploads stay tight.
            if let Some((key, handle)) = zero_copy_attach {
                self.camera_normal_texture
                    .bind_egl_image(&self.gl_context, key, handle)?;
                // Poison the upload-tracking dims: a later upload on this
                // texture must TexImage2D fresh storage, never
                // TexSubImage2D into the attached client buffer.
                self.camera_normal_texture.forget_storage();
                self.convert_stats.src_imports += 1;
                convert_span.record("src_feed", "import");
            } else {
                let src_bpp = src_fmt.channels().max(1);
                // A recorded pitch that is not a whole number of pixels
                // cannot be expressed via UNPACK_ROW_LENGTH (which counts
                // pixels) — decline to the CPU backend rather than upload
                // sheared rows. Reachable on Android, where gralloc may pad
                // the RGB-in-RGBA8888 surface to a byte pitch that 3 does
                // not divide. `unpack_row_length` is the one place that rule
                // lives, shared with the two PBO upload arms.
                let row_len_px = unpack_row_length(
                    src.effective_row_stride(),
                    src_w,
                    src_bpp,
                    &format!("{src_fmt:?}"),
                )?;
                // Open before touching pixel-store state: a `?` here must not
                // leave `UNPACK_ROW_LENGTH` set for the next upload.
                let pixels = SrcPixels::open(src, &self.owned_pbos)?;
                pixels.record(&mut self.convert_stats, convert_span);
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, row_len_px);
                // What GL will read: every row but the last at the stride
                // `UNPACK_ROW_LENGTH` just set, plus the last row's own
                // pixels. `UNPACK_ALIGNMENT` is 1, so no row is padded
                // further.
                let row_stride_b = if row_len_px == 0 {
                    src_w * src_bpp
                } else {
                    row_len_px as usize * src_bpp
                };
                let required = if src_h == 0 {
                    0
                } else {
                    (src_h - 1) * row_stride_b + src_w * src_bpp
                };
                let uploaded = self.camera_normal_texture.upload(
                    texture_target,
                    src_w,
                    src_h,
                    texture_format,
                    required,
                    pixels.source(),
                );
                // Reset on both outcomes; nothing between the set and here
                // can return early now.
                edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, 0);
                uploaded?;
            }

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            match flip {
                Flip::None => {}
                Flip::Vertical => {
                    std::mem::swap(&mut dst_roi.top, &mut dst_roi.bottom);
                }
                Flip::Horizontal => {
                    std::mem::swap(&mut dst_roi.left, &mut dst_roi.right);
                }
            }

            let camera_vertices: [f32; 12] = [
                dst_roi.left,
                dst_roi.top,
                0., // left top
                dst_roi.right,
                dst_roi.top,
                0., // right top
                dst_roi.right,
                dst_roi.bottom,
                0., // right bottom
                dst_roi.left,
                dst_roi.bottom,
                0., // left bottom
            ];
            edgefirst_gl::gl::BufferData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                (size_of::<f32>() * camera_vertices.len()) as isize,
                camera_vertices.as_ptr() as *const c_void,
                edgefirst_gl::gl::DYNAMIC_DRAW,
            );
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);
            let texture_vertices: [f32; 16] = [
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
            ];

            edgefirst_gl::gl::BufferData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                (size_of::<f32>() * 8) as isize,
                (texture_vertices[(rotation_offset * 2)..]).as_ptr() as *const c_void,
                edgefirst_gl::gl::DYNAMIC_DRAW,
            );
            let vertices_index: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                vertices_index.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                vertices_index.as_ptr() as *const c_void,
            );
            check_gl_error(function!(), line!())?;

            Ok(())
        }
    }

    #[allow(clippy::too_many_arguments)]
    /// `y2y` selects the Y2Y NV programs instead of the driver's YUV->RGB
    /// sampler, with the source's resolved (encoding, range) for their
    /// in-shader matrix ([`NvSampling::HardwareYuv`]).
    #[allow(clippy::too_many_arguments)]
    fn draw_camera_texture_eglimage(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        egl_img: PlatformHandle,
        src_roi: RegionOfInterest,
        mut dst_roi: RegionOfInterest,
        rotation_offset: usize,
        flip: Flip,
        is_int8: bool,
        y2y: Option<(
            edgefirst_tensor::ColorEncoding,
            edgefirst_tensor::ColorRange,
        )>,
    ) -> Result<(), Error> {
        let src_key = BufferImportKey::from_tensor(src, src_fmt, false);
        let luma_id = src_key.luma_id;
        let crop_uv = src_roi.uv_bounds();
        // As in `draw_src_texture`: the import may cover more of the texture
        // than the logical image, and may start it partway in.
        let src_roi = self.scale_src_roi(src_roi, src, src_fmt);
        // The external-OES programs sample through the same mapping, so they
        // clamp through it too: a rebased source (issue #170) has real texels
        // in front of its first column and behind its last, and a LINEAR
        // kernel at either edge would otherwise blend them, or the pixels
        // beyond a source crop.
        let (src_w, src_h) = (
            src.width().ok_or(Error::NotAnImage)?,
            src.height().ok_or(Error::NotAnImage)?,
        );
        let [e0, e1, e2, e3] = super::render::sample_clamp_rect_within(
            (src_w, src_h),
            self.cached_src_import_map(src, src_fmt),
            crop_uv,
        );
        // Draw-time program selection (see draw_src_texture).
        let (program_id, extent_loc, y2y_upload) = match y2y {
            Some(colorimetry) => {
                let (programs, uniforms) = self.nv_y2y_programs.as_ref().ok_or_else(|| {
                    Error::NotSupported("Y2Y NV programs unavailable on this GPU".into())
                })?;
                let state = &uniforms[usize::from(is_int8)];
                let upload = (state.last_colorimetry != Some(colorimetry))
                    .then_some((state.locs, colorimetry));
                (
                    programs[usize::from(is_int8)].id,
                    state.locs.src_extent,
                    upload,
                )
            }
            None => {
                let program = if is_int8 {
                    &self.texture_int8_program_yuv
                } else {
                    &self.texture_program_yuv
                }
                .as_ref()
                .ok_or_else(|| {
                    Error::NotSupported(
                        "external-OES sampler program unavailable on this platform".into(),
                    )
                })?;
                (
                    program.id,
                    self.external_src_extent_loc(is_int8, false),
                    None,
                )
            }
        };
        let texture_target = edgefirst_gl::gl::TEXTURE_EXTERNAL_OES;
        unsafe {
            edgefirst_gl::gl::UseProgram(program_id);
            edgefirst_gl::gl::Uniform4f(extent_loc, e0, e1, e2, e3);
            if let Some((locs, (encoding, range))) = y2y_upload {
                let k = crate::colorimetry::yuv_to_rgb_coeffs(encoding, range);
                edgefirst_gl::gl::Uniform1f(locs.y_offset, k.y_offset);
                edgefirst_gl::gl::Uniform1f(locs.y_scale, k.y_scale);
                edgefirst_gl::gl::Uniform1f(locs.c_vr, k.c_vr);
                edgefirst_gl::gl::Uniform1f(locs.c_ug, k.c_ug);
                edgefirst_gl::gl::Uniform1f(locs.c_vg, k.c_vg);
                edgefirst_gl::gl::Uniform1f(locs.c_ub, k.c_ub);
            }
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(texture_target, self.camera_eglimage_texture.id);
            super::core::set_tex_filter_clamp(texture_target, self.source_filter());

            // Note: GL_TEXTURE_SWIZZLE_* is not supported for
            // GL_TEXTURE_EXTERNAL_OES in GLES. YUV→RGB conversion is
            // handled by the driver when sampling from an external texture,
            // and greyscale EGLImages replicate luma to all channels
            // automatically via the YUV shader.

            if self.camera_eglimage_texture.bind_egl_image_external(
                &self.gl_context,
                src_key,
                egl_img,
            )? {
                check_gl_error(function!(), line!())?;
                log::trace!("draw_camera: bound new src EGLImage id={luma_id:#x}");
            } else {
                log::trace!("draw_camera: reusing bound src EGLImage id={luma_id:#x}");
            }
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            match flip {
                Flip::None => {}
                Flip::Vertical => {
                    std::mem::swap(&mut dst_roi.top, &mut dst_roi.bottom);
                }
                Flip::Horizontal => {
                    std::mem::swap(&mut dst_roi.left, &mut dst_roi.right);
                }
            }

            let camera_vertices: [f32; 12] = [
                dst_roi.left,
                dst_roi.top,
                0., // left top
                dst_roi.right,
                dst_roi.top,
                0., // right top
                dst_roi.right,
                dst_roi.bottom,
                0., // right bottom
                dst_roi.left,
                dst_roi.bottom,
                0., // left bottom
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * camera_vertices.len()) as isize,
                camera_vertices.as_ptr() as *const c_void,
            );

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

            let texture_vertices: [f32; 16] = [
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * 8) as isize,
                (texture_vertices[(rotation_offset * 2)..]).as_ptr() as *const c_void,
            );

            let vertices_index: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                vertices_index.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                vertices_index.as_ptr() as *const c_void,
            );
        }
        check_gl_error(function!(), line!())?;
        if let (Some(colorimetry), Some((_, uniforms))) = (y2y, self.nv_y2y_programs.as_mut()) {
            uniforms[usize::from(is_int8)].last_colorimetry = Some(colorimetry);
        }
        Ok(())
    }

    /// `ShaderR8`: render NV12/NV16/NV24 → RGBA8 via the R8 texelFetch shader.
    ///
    /// The combined semi-planar buffer is presented as a single-plane R8
    /// `TEXTURE_2D` and the shader addresses Y and UV bytes directly,
    /// parameterised by four uniforms derived from the source format.
    ///
    /// `r8_src` selects how the R8 texture is established:
    /// - `Some(egl_img)` — zero-copy EGLImage import (DMA-BUF source, the
    ///   `create_image_from_dma_nv_r8` path).
    /// - `None` — CPU upload of the combined buffer via `glTexImage2D` (the
    ///   non-DMA / PBO path, e.g. orin where DMA-BUF EGLImage import is
    ///   unavailable). Same shader, same exact in-shader matrix.
    ///
    /// Renders into the currently-bound FBO (the RGBA8 intermediate or the
    /// DMA destination) — identical output slot to `draw_camera_texture_eglimage`.
    #[allow(clippy::too_many_arguments)]
    fn draw_nv_texture_2d(
        &mut self,
        src: &Tensor<u8>,
        src_fmt: PixelFormat,
        r8_src: Option<PlatformHandle>,
        src_rect: NvSampleRect,
        mut dst_roi: RegionOfInterest,
        rotation_offset: usize,
        flip: Flip,
        is_int8: bool,
        convert_span: &tracing::Span,
    ) -> Result<(), Error> {
        let src_w = src.width().ok_or(Error::NotAnImage)?;
        let src_h = src.height().ok_or(Error::NotAnImage)?;
        let tex_width = src.effective_row_stride().unwrap_or(src_w) as i32;

        // Format-specific shader uniforms from the shared `chroma_layout`
        // (single source of truth with the codec writer + CPU readers + macOS
        // shader). `chroma_lines` (== `uv_rows_per_luma`) is the number of R8
        // buffer rows each image-chroma-row occupies (NV24's CbCr row is 2W
        // bytes = 2 rows; NV12/NV16 are W bytes = 1 row). The shader uses it for
        // direct 2D texel addressing (no per-pixel integer divide/modulo, which
        // is pathologically slow on some embedded GPUs e.g. Vivante GC7000UL).
        let layout = src_fmt.chroma_layout().ok_or_else(|| {
            Error::NotSupported(format!(
                "draw_nv_texture_2d: unsupported format {src_fmt:?}"
            ))
        })?;
        let chroma_shift_x = layout.shift_x as i32;
        let chroma_shift_y = layout.shift_y as i32;
        let chroma_lines = layout.uv_rows_per_luma as i32;

        let src_key = BufferImportKey::from_tensor(src, src_fmt, false);
        let luma_id = src_key.luma_id;
        // No `scale_src_roi` here, unlike the uv-sampling paths: this shader
        // turns `tc` into integer texel coordinates through `img_size` and
        // reads them with `texelFetch`, so the logical plane is already
        // addressed from the texture origin however large the texture is.

        // Draw-time program selection, for EVERY destination lowering: the
        // int8 programs add the XOR-0x80 bias, and a draw that rescales
        // bilinearly filters through the texture units when the chroma plane
        // can be bound on its own. An upload always can be; an import only
        // where the GPU takes the chroma plane's offset.
        let bilinear =
            src_rect.resample && self.interpolation.supported() == crate::Interpolation::Bilinear;
        let uv_import = if bilinear && self.nv_hw_filter && r8_src.is_some() {
            self.get_or_create_nv_uv_egl_image(src, src_fmt)
                .inspect_err(|e| log::debug!("NV chroma view unavailable ({e}); shader-filtered"))
                .ok()
        } else {
            None
        };
        // Only NV12 has a full-image DMA-BUF import for the Y2Y programs.
        let mut sampling = NvSampling::choose(NvSamplingInputs {
            bilinear,
            hw_filter: self.nv_hw_filter,
            imported: r8_src.is_some(),
            chroma_view: uv_import.is_some(),
            y2y: self.nv_y2y_programs.is_some()
                && src_fmt == PixelFormat::Nv12
                && y2y_pays_off(src_w * src_h, src_rect.dst_pixels),
        });
        let colorimetry = nv_colorimetry(src.colorimetry(), src.height());
        if sampling == NvSampling::HardwareYuv {
            match self.get_or_create_egl_image(CacheKind::Src, src, src_fmt) {
                Ok(img) => {
                    self.draw_camera_texture_eglimage(
                        src,
                        src_fmt,
                        img,
                        src_rect.roi(src_w, src_h),
                        dst_roi,
                        rotation_offset,
                        flip,
                        is_int8,
                        Some(colorimetry),
                    )?;
                    self.last_nv_sampling = Some(sampling);
                    return Ok(());
                }
                Err(e) => {
                    log::debug!("NV12 import for Y2Y unavailable ({e}); shader-filtered");
                    sampling = NvSampling::Shader;
                }
            }
        }
        let program = sampling.program(is_int8);
        let r8_filter = if sampling == NvSampling::Hardware {
            edgefirst_gl::gl::LINEAR
        } else {
            edgefirst_gl::gl::NEAREST
        };
        let (shift_x, shift_y) = (layout.shift_x, layout.shift_y);
        let chroma_w = src_w.div_ceil(1 << shift_x);
        let chroma_h = src_h.div_ceil(1 << shift_y);
        let combined_h = src_fmt.combined_plane_height(src_h).ok_or_else(|| {
            Error::NotSupported(format!(
                "draw_nv_texture_2d: {src_fmt:?} is not semi-planar"
            ))
        })?;
        let prog_id = self.nv_r8_programs[program].id;

        // Path B applies the `nv_colorimetry` matrix in-shader, so it is
        // colorimetry-correct on every GPU regardless of EGL color-hint
        // support.
        let state = &mut self.nv_r8_uniforms[program];
        let locs = state.locs;
        // Uniform values persist per program: re-upload the six matrix floats
        // only when this program's (encoding, range) actually changed. The
        // marker is recorded AFTER the draw succeeds — an error between here
        // and the upload must not leave a "already uploaded" claim for values
        // that never reached the program.
        let upload_colorimetry = state.last_colorimetry != Some(colorimetry);

        unsafe {
            edgefirst_gl::gl::UseProgram(prog_id);
            edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.nv_r8_texture.id);
            // NEAREST for the texelFetch programs (which ignore it anyway);
            // LINEAR where the hardware filters luma.
            super::core::set_tex_filter_clamp(edgefirst_gl::gl::TEXTURE_2D, r8_filter);

            match r8_src {
                Some(egl_img) => {
                    if self
                        .nv_r8_texture
                        .bind_egl_image(&self.gl_context, src_key, egl_img)?
                    {
                        check_gl_error(function!(), line!())?;
                        log::trace!("draw_nv_texture_2d: bound new R8 EGLImage id={luma_id:#x}");
                    } else {
                        log::trace!(
                            "draw_nv_texture_2d: reusing bound R8 EGLImage id={luma_id:#x}"
                        );
                    }
                }
                None => {
                    // Upload path: the combined semi-planar buffer as an R8
                    // texture (tex_width × combined_plane_height), from host
                    // memory or straight from a PBO. The shader addresses it
                    // identically to the EGLImage case, so the in-shader YUV
                    // matrix is byte-for-byte the same as the DMA ShaderR8
                    // path. Used where DMA-BUF EGLImage import is unavailable
                    // (e.g. orin), declined, or the source is not a DMA-BUF.
                    let combined_h = src_fmt.combined_plane_height(src_h).ok_or_else(|| {
                        Error::NotSupported(format!(
                            "draw_nv_texture_2d upload: {src_fmt:?} is not semi-planar"
                        ))
                    })?;
                    let needed = tex_width as usize * combined_h;
                    // A map already starts at the source's plane offset for
                    // every backing: `Mem` and each platform's DMA variant
                    // write it through `set_plane_offset`, and an Shm window
                    // only ever gets one from its own `view()`. So the window
                    // is read from its own start. Adding `plane_offset` on top
                    // of the map, as this once did, read an offset frame at
                    // twice its offset or refused it as too short -- pinned by
                    // `offset_nv_source_upload.rs`. A PBO has no map, so its
                    // upload is the one that carries the offset.
                    let pixels = SrcPixels::open(src, &self.owned_pbos)?;
                    pixels.record(&mut self.convert_stats, convert_span);
                    // Adreno does not orphan an EGLImage sibling on TexImage2D:
                    // an upload into a texture that last held an imported R8
                    // plane samples partly from that import. A fresh texture
                    // name guarantees the upload owns its storage.
                    if self.is_adreno {
                        self.nv_r8_texture = Texture::new();
                        edgefirst_gl::gl::BindTexture(
                            edgefirst_gl::gl::TEXTURE_2D,
                            self.nv_r8_texture.id,
                        );
                        super::core::set_tex_filter_clamp(edgefirst_gl::gl::TEXTURE_2D, r8_filter);
                    }
                    // Fresh storage every frame: this texture alternates between
                    // imported planes and uploads, and only an attach knows when
                    // it has replaced the storage. `UNPACK_ALIGNMENT` is 1 (set
                    // once in `new`), so any row width is valid.
                    self.nv_r8_texture.forget_storage();
                    self.nv_r8_texture.upload(
                        edgefirst_gl::gl::TEXTURE_2D,
                        tex_width as usize,
                        combined_h,
                        edgefirst_gl::gl::RED,
                        needed,
                        pixels.source(),
                    )?;
                    check_gl_error(function!(), line!())?;
                    log::trace!("draw_nv_texture_2d: uploaded R8 ({tex_width}x{combined_h})");
                }
            }

            if sampling == NvSampling::Hardware {
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE1);
                let bound = self.bind_nv_chroma(src, src_key, uv_import, chroma_w, chroma_h);
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
                bound?;
            }

            // Per-source uniforms through link-time-cached locations (the
            // `src` sampler binding is constant and uploaded at resolve time).
            edgefirst_gl::gl::Uniform2i(locs.img_size, src_w as i32, src_h as i32);
            edgefirst_gl::gl::Uniform1i(locs.tex_width, tex_width);
            edgefirst_gl::gl::Uniform2i(locs.chroma_shift, chroma_shift_x, chroma_shift_y);
            edgefirst_gl::gl::Uniform1i(locs.chroma_lines, chroma_lines);
            if sampling == NvSampling::Hardware {
                // The crop's half-texel-inset rectangle on each texture, so
                // the LINEAR kernel never reaches past the crop (or, for luma,
                // into the chroma rows below the image).
                let (tw, th) = (tex_width as f32, combined_h as f32);
                edgefirst_gl::gl::Uniform2f(locs.luma_scale, src_w as f32 / tw, src_h as f32 / th);
                edgefirst_gl::gl::Uniform4f(
                    locs.luma_clamp,
                    (src_rect.left as f32 + 0.5) / tw,
                    (src_rect.top as f32 + 0.5) / th,
                    (src_rect.right as f32 - 0.5) / tw,
                    (src_rect.bottom as f32 - 0.5) / th,
                );
                let (cw, ch) = (chroma_w as f32, chroma_h as f32);
                edgefirst_gl::gl::Uniform2f(
                    locs.chroma_scale,
                    src_w as f32 / (chroma_w << shift_x) as f32,
                    src_h as f32 / (chroma_h << shift_y) as f32,
                );
                edgefirst_gl::gl::Uniform4f(
                    locs.chroma_clamp,
                    ((src_rect.left >> shift_x) as f32 + 0.5) / cw,
                    ((src_rect.top >> shift_y) as f32 + 0.5) / ch,
                    (src_rect.right.div_ceil(1 << shift_x) as f32 - 0.5) / cw,
                    (src_rect.bottom.div_ceil(1 << shift_y) as f32 - 0.5) / ch,
                );
            }
            edgefirst_gl::gl::Uniform4i(
                locs.src_rect,
                src_rect.left as i32,
                src_rect.top as i32,
                src_rect.right as i32 - 1,
                src_rect.bottom as i32 - 1,
            );

            if upload_colorimetry {
                let coeffs = crate::colorimetry::yuv_to_rgb_coeffs(colorimetry.0, colorimetry.1);
                edgefirst_gl::gl::Uniform1f(locs.y_offset, coeffs.y_offset);
                edgefirst_gl::gl::Uniform1f(locs.y_scale, coeffs.y_scale);
                edgefirst_gl::gl::Uniform1f(locs.c_vr, coeffs.c_vr);
                edgefirst_gl::gl::Uniform1f(locs.c_ug, coeffs.c_ug);
                edgefirst_gl::gl::Uniform1f(locs.c_vg, coeffs.c_vg);
                edgefirst_gl::gl::Uniform1f(locs.c_ub, coeffs.c_ub);
            }

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            match flip {
                Flip::None => {}
                Flip::Vertical => {
                    std::mem::swap(&mut dst_roi.top, &mut dst_roi.bottom);
                }
                Flip::Horizontal => {
                    std::mem::swap(&mut dst_roi.left, &mut dst_roi.right);
                }
            }

            let camera_vertices: [f32; 12] = [
                dst_roi.left,
                dst_roi.top,
                0.,
                dst_roi.right,
                dst_roi.top,
                0.,
                dst_roi.right,
                dst_roi.bottom,
                0.,
                dst_roi.left,
                dst_roi.bottom,
                0.,
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * camera_vertices.len()) as isize,
                camera_vertices.as_ptr() as *const c_void,
            );

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

            let src_roi = RegionOfInterest {
                left: src_rect.left as f32 / src_w as f32,
                top: src_rect.bottom as f32 / src_h as f32,
                right: src_rect.right as f32 / src_w as f32,
                bottom: src_rect.top as f32 / src_h as f32,
            };
            let texture_vertices: [f32; 16] = [
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * 8) as isize,
                (texture_vertices[(rotation_offset * 2)..]).as_ptr() as *const c_void,
            );

            let vertices_index: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                vertices_index.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                vertices_index.as_ptr() as *const c_void,
            );
            if sampling == NvSampling::Hardware {
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE1);
                edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, 0);
                edgefirst_gl::gl::ActiveTexture(edgefirst_gl::gl::TEXTURE0);
            }
        }
        self.last_nv_sampling = Some(sampling);
        check_gl_error(function!(), line!())?;
        // The draw (and its colorimetry upload, when taken) succeeded — only
        // now record the program's uploaded (encoding, range).
        if upload_colorimetry {
            self.nv_r8_uniforms[program].last_colorimetry = Some(colorimetry);
        }
        Ok(())
    }

    /// Look up or create the Path-B R8 EGLImage for an NV* source tensor.
    ///
    /// Uses a dedicated cache (`nv_r8_egl_cache`) that is keyed identically to
    /// `src_egl_cache` but stores R8 imports so that the two don't interfere.
    fn get_or_create_nv_r8_egl_image(
        &mut self,
        img: &Tensor<u8>,
        img_fmt: PixelFormat,
    ) -> Result<PlatformHandle, crate::Error> {
        // Before the lookup, not inside the miss arm: a hit returns a cached
        // import without consulting the platform at all, so an identity that
        // has stopped naming its buffer would be served a stale image.
        Platform::validate_import_identity(img, "NV source")?;
        // Mali samples zeros from an unaligned plane offset without reporting
        // an EGL error, so refuse the import here and let the caller's failure
        // arm upload the window through `map()` instead (issue #165). Always a
        // source, so there is no destination case to exempt.
        //
        // Plane 0 is the whole check here: this path binds the COMBINED
        // semi-planar plane as ONE R8 texture at plane 0's offset and the
        // shader addresses the chroma bytes inside it by texel arithmetic, so
        // EGL is never handed a second plane offset. The two-plane import in
        // `get_or_create_egl_image` is the one that needs plane 1 checked too.
        //
        // The aligned-base rebase that keeps packed sources zero-copy (issue
        // #170) does not apply here, and cannot: this import's pitch IS its
        // width (`tex_width`), so widening it by the shift would overlap
        // every row with the next, and the alternative -- a uniform shift
        // with the width unchanged -- makes the shader address luma at
        // `y * tex_width + x + shift`, which wraps rows and so needs a
        // per-texel integer divide and modulo. That is exactly the
        // arithmetic the NV shader's divide-free addressing exists to avoid (3.3x on
        // Vivante), and it would also leave the last `shift` bytes of the
        // final chroma row outside the import, which for NV24 are pixels.
        // So the NV path keeps the decline and uploads the combined plane,
        // which issue #166's routing already sends to the R8 upload rather
        // than the CPU.
        let offset = img.plane_offset().unwrap_or(0);
        if rejects_unaligned_import_offset(self.misplaces_unaligned_offsets(), offset) {
            return Err(crate::Error::NotSupported(format!(
                "this GPU misreads a DMA-BUF imported at a plane offset that \
                 is not {DMA_IMPORT_OFFSET_ALIGN}-byte aligned ({offset}); \
                 uploading the window instead (issue #165)"
            )));
        }
        // The NV R8 path imports a SOURCE (NV12/16/24 as one R8 texture), so it
        // never collapses onto a destination parent import.
        let id = BufferImportKey::from_tensor(img, img_fmt, false);
        let luma_id = id.luma_id;

        {
            let ts = self.nv_r8_egl_cache.next_timestamp();
            if let Some(cached) = self.nv_r8_egl_cache.entries.get_mut(&id) {
                self.nv_r8_egl_cache.hits += 1;
                cached.last_used = ts;
                log::trace!("nv_r8_egl_cache hit: id={luma_id:#x}");
                return Ok(Platform::import_handle(&cached.import));
            }
            self.nv_r8_egl_cache.misses += 1;
            log::trace!("nv_r8_egl_cache miss: id={luma_id:#x}");
        }

        let egl_image_obj = Platform::import_buffer_nv_r8(&self.gl_context, img, img_fmt)?;
        self.nv_r8_texture.invalidate_egl_binding();

        let handle = Platform::import_handle(&egl_image_obj);
        self.nv_r8_egl_cache.insert(id, egl_image_obj, None);
        Ok(handle)
    }

    /// Bind the chroma plane of `src` as (U, V) texels to `nv_uv_texture` on
    /// the active texture unit, with LINEAR filtering: the `import` when there
    /// is one, else an upload of the plane from the source's pixels.
    fn bind_nv_chroma(
        &mut self,
        src: &Tensor<u8>,
        src_key: BufferImportKey,
        import: Option<PlatformHandle>,
        chroma_w: usize,
        chroma_h: usize,
    ) -> Result<(), Error> {
        if self.is_adreno && import.is_none() {
            // As for the R8 plane: a texture that held an import keeps
            // sampling it after an upload on Adreno.
            self.nv_uv_texture = Texture::new();
        }
        unsafe {
            edgefirst_gl::gl::BindTexture(edgefirst_gl::gl::TEXTURE_2D, self.nv_uv_texture.id);
            super::core::set_tex_filter_clamp(
                edgefirst_gl::gl::TEXTURE_2D,
                edgefirst_gl::gl::LINEAR,
            );
        }
        if let Some(handle) = import {
            // SAFETY: `handle` comes from `nv_uv_egl_cache`, which owns the
            // import for at least as long as this draw; the texture is bound
            // to the active unit above.
            unsafe {
                self.nv_uv_texture
                    .bind_egl_image(&self.gl_context, src_key, handle)?;
            }
            return check_gl_error(function!(), line!());
        }
        let src_w = src.width().ok_or(Error::NotAnImage)?;
        let src_h = src.height().ok_or(Error::NotAnImage)?;
        let layout = src
            .format()
            .and_then(|f| f.chroma_layout())
            .ok_or_else(|| Error::NotSupported("NV chroma upload: not semi-planar".into()))?;
        let stride = src.effective_row_stride().unwrap_or(src_w);
        let pitch = stride * layout.uv_rows_per_luma;
        let pixels = SrcPixels::open(src, &self.owned_pbos)?;
        self.nv_uv_texture.forget_storage();
        unsafe {
            edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, (pitch / 2) as i32);
        }
        let uploaded = self.nv_uv_texture.upload(
            edgefirst_gl::gl::TEXTURE_2D,
            chroma_w,
            chroma_h,
            edgefirst_gl::gl::RG,
            pitch * (chroma_h - 1) + chroma_w * 2,
            pixels.source().offset_by(stride * src_h),
        );
        unsafe {
            edgefirst_gl::gl::PixelStorei(edgefirst_gl::gl::UNPACK_ROW_LENGTH, 0);
        }
        uploaded?;
        check_gl_error(function!(), line!())
    }

    /// Look up or create the chroma-plane (U, V) EGLImage of a single-plane
    /// NV* source for [`NvSampling::Hardware`], cached in `nv_uv_egl_cache`.
    /// The plane sits `row_stride * height` bytes past the luma plane, so it
    /// needs its own offset check on GPUs that misread unaligned offsets.
    fn get_or_create_nv_uv_egl_image(
        &mut self,
        img: &Tensor<u8>,
        img_fmt: PixelFormat,
    ) -> Result<PlatformHandle, crate::Error> {
        if !Platform::NV_CHROMA_IMPORT || self.nv_uv_import_refused {
            return Err(crate::Error::NotSupported(
                "no chroma-plane import on this platform or driver".into(),
            ));
        }
        Platform::validate_import_identity(img, "NV chroma source")?;
        let height = img.height().ok_or(Error::NotAnImage)?;
        let stride = img
            .effective_row_stride()
            .unwrap_or(img.width().ok_or(Error::NotAnImage)?);
        let offset = img.plane_offset().unwrap_or(0) + stride * height;
        if rejects_unaligned_import_offset(self.misplaces_unaligned_offsets(), offset) {
            return Err(crate::Error::NotSupported(format!(
                "chroma plane offset {offset} is not {DMA_IMPORT_OFFSET_ALIGN}-byte aligned"
            )));
        }
        let id = BufferImportKey::from_tensor(img, img_fmt, false);
        {
            let ts = self.nv_uv_egl_cache.next_timestamp();
            if let Some(cached) = self.nv_uv_egl_cache.entries.get_mut(&id) {
                self.nv_uv_egl_cache.hits += 1;
                cached.last_used = ts;
                return Ok(Platform::import_handle(&cached.import));
            }
        }
        // A miss counts an import made: a refusal imports nothing, and is
        // remembered so the next resize does not repeat the attempt.
        let egl_image_obj = Platform::import_buffer_nv_chroma(&self.gl_context, img, img_fmt)
            .inspect_err(|e| {
                log::info!("NV chroma-plane import refused ({e}); resizing with the shader filter");
                self.nv_uv_import_refused = true;
            })?;
        self.nv_uv_egl_cache.misses += 1;
        self.nv_uv_texture.invalidate_egl_binding();
        let handle = Platform::import_handle(&egl_image_obj);
        self.nv_uv_egl_cache.insert(id, egl_image_obj, None);
        Ok(handle)
    }

    /// Look up or create an EGLImage for a DMA tensor, returning the EGL image handle.
    ///
    /// Returns `egl::Image` (a `Copy` type wrapping `*const c_void`) to avoid borrow
    /// conflicts with the caller. The cache retains ownership of the `EglImage` value;
    /// the handle remains valid as long as the entry lives in the cache.
    fn get_or_create_egl_image(
        &mut self,
        cache: CacheKind,
        img: &Tensor<u8>,
        img_fmt: PixelFormat,
    ) -> Result<PlatformHandle, crate::Error> {
        // Test hook: stand in for a driver that refuses this destination, so
        // the fallback to the mapped-texture readback is exercised on hosts
        // whose driver accepts every destination (issue #175). Destinations
        // only — the source arms have their own decline paths.
        #[cfg(test)]
        if cache == CacheKind::Dst && self.fail_dst_import {
            return Err(crate::Error::OpenGl(
                "EDGEFIRST test hook: zero-copy destination import refused".to_string(),
            ));
        }
        // Before the lookup, not inside the miss arm: a hit returns a cached
        // import without consulting the platform at all, so an identity that
        // has stopped naming its buffer would be served a stale image.
        Platform::validate_import_identity(
            img,
            match cache {
                CacheKind::Src => "source",
                CacheKind::Dst => "destination",
            },
        )?;
        // Mali samples zeros from a source imported at a plane offset that is
        // not 64-byte aligned, with no EGL error to notice (issue #165). The
        // question is asked of the offset the import will actually PRESENT,
        // not of the tensor's own: since issue #170 a packed source at an
        // unaligned offset imports from the aligned base below it with the
        // remainder folded into the sampling rectangle, so it is exempt --
        // but only when that rebase really applied. An offset that is not a
        // whole number of pixels (`offset % bpp != 0`: a 64-padded RGB row
        // stride of 320 is not a multiple of 3, so row 1 column 1 is byte
        // 323) or a pitch with no room to widen (a whole 64-wide RGBA tensor
        // at a `set_plane_offset` window has a tight 256-byte pitch) leaves
        // the import unaligned, and keying the exemption on the FORMAT would
        // wave exactly those through into a black frame. NV12's two-plane
        // import, YUYV's macropixel phase and planar R8 are never rebased
        // and so never exempt. The caller's failure arm uploads the window
        // through `map()`.
        //
        // Destinations are untouched: a destination view imports its parent at
        // offset 0 and is rendered into by viewport, never sampled at an
        // offset.
        if cache == CacheKind::Src {
            // Every plane offset this import will pass to EGL, not just plane
            // 0. A two-plane NV12 import hands EGL a plane-1 offset of its own
            // (`dma_import.rs` ~`:225`), and that one can be unaligned while
            // plane 0 is aligned. It cannot happen on a HAL allocation, whose
            // 64-aligned pitch makes `pitch * height` 64-aligned at every
            // height; it can on a DMA-BUF adopted through `from_fd`, whose
            // pitch is the producer's and need not be padded, and on a
            // multiplane NV12 whose chroma buffer carries its own offset. Mali
            // would then sample zeros for chroma alone — silently
            // colour-shifted output rather than a black frame, which is harder
            // to notice than the luma case.
            // The offset EGL will be handed, which is the tensor's own
            // unless the rebase moved it.
            let offset = source_import_plane0_offset(img, img_fmt);
            // Plane 1 is derived from that same value, which for NV12 is
            // the tensor's own offset unchanged: the rebase never covers a
            // semi-planar format, so there is nothing for it to have moved.
            let chroma_offset = (img_fmt == PixelFormat::Nv12).then(|| {
                if img.is_multiplane() {
                    // A separate chroma DMA-BUF imports at its own offset.
                    img.chroma().and_then(|c| c.plane_offset()).unwrap_or(0)
                } else {
                    nv12_plane1_offset(
                        offset,
                        img.effective_row_stride()
                            .unwrap_or_else(|| img.width().unwrap_or(0)),
                        img.height().unwrap_or(0),
                    )
                }
            });
            // A fixed array, not a `Vec`: this runs on every convert.
            let planes = [
                Some(("plane 0", offset)),
                chroma_offset.map(|o| ("chroma plane", o)),
            ];
            if let Some((which, bad)) = planes.into_iter().flatten().find(|&(_, o)| {
                rejects_unaligned_import_offset(self.misplaces_unaligned_offsets(), o)
            }) {
                return Err(crate::Error::NotSupported(format!(
                    "this GPU misreads a DMA-BUF imported at a plane offset that \
                     is not {DMA_IMPORT_OFFSET_ALIGN}-byte aligned ({which} at \
                     {bad}); uploading the window instead (issue #165)"
                )));
            }
            // Adreno imports only the first plane's DMA-BUF of a multi-fd
            // import and samples chroma from the wrong buffer, with no EGL
            // error. Chroma in the luma's own buffer — a single-buffer NV12,
            // or a multiplane tensor whose planes share one DMA-BUF — imports
            // correctly and stays zero-copy. GL has no upload route for a
            // semi-planar source, so the convert is declined to the CPU.
            if self.is_adreno && chroma_in_separate_buffer(img) {
                return Err(crate::Error::NotSupported(
                    "Adreno misreads a semi-planar source whose chroma is a \
                     separate DMA-BUF (only the first buffer is imported)"
                        .into(),
                ));
            }
        }
        // Identity + offset + geometry: sub-region views share one buffer
        // identity but need distinct EGLImages (offset), and a pooled buffer
        // reconfigured to a new size/format/stride needs a fresh import
        // (geometry) — see BufferImportKey. Only a destination view collapses onto
        // its parent key; a source view keys on its own region.
        let id = BufferImportKey::from_tensor(img, img_fmt, cache == CacheKind::Dst);
        let luma_id = id.luma_id;

        {
            let egl_cache = match cache {
                CacheKind::Src => &mut self.src_egl_cache,
                CacheKind::Dst => &mut self.dst_egl_cache,
            };
            let ts = egl_cache.next_timestamp();
            if let Some(cached) = egl_cache.entries.get_mut(&id) {
                egl_cache.hits += 1;
                cached.last_used = ts;
                log::trace!("ImportCache {:?} hit: id={luma_id:#x}", cache);
                return Ok(Platform::import_handle(&cached.import));
            }
            egl_cache.misses += 1;
            log::trace!("ImportCache {:?} miss: id={luma_id:#x}", cache);
        }

        // Create the EGL image BEFORE evicting — if creation fails, we don't
        // want to have destroyed a valid cache entry for nothing. Only a
        // destination view imports its parent (glViewport tiling); a source view
        // imports its own region (it is sampled, not rendered into).
        let for_dst = cache == CacheKind::Dst;
        let egl_image_obj = Platform::import_buffer(&self.gl_context, img, img_fmt, for_dst)?;

        // Optionally create a GL renderbuffer backed by this EGLImage for use as an FBO
        // color attachment.  Renderbuffers are required on Mali/Neutron GPUs (i.MX 95)
        // but are not supported on all drivers (e.g. Vivante on i.MX 8MP).
        // Enabled via EDGEFIRST_OPENGL_RENDERSURFACE=1; defaults to the texture path.
        let rbo = if cache == CacheKind::Dst && self.use_renderbuffer {
            let mut rbo: u32 = 0;
            unsafe {
                edgefirst_gl::gl::GenRenderbuffers(1, &mut rbo);
                edgefirst_gl::gl::BindRenderbuffer(edgefirst_gl::gl::RENDERBUFFER, rbo);
                Platform::attach_renderbuffer_storage(
                    &self.gl_context,
                    Platform::import_handle(&egl_image_obj),
                )?;
                if let Err(e) = check_gl_error(function!(), line!()) {
                    edgefirst_gl::gl::DeleteRenderbuffers(1, &rbo);
                    return Err(e);
                }
            }
            Some(rbo)
        } else {
            None
        };

        // Invalidate texture binding state: we're inserting a new entry and
        // may evict the currently-bound one.
        match cache {
            CacheKind::Src => self.invalidate_src_textures(),
            CacheKind::Dst => self.invalidate_dst_textures(),
        }

        let handle = Platform::import_handle(&egl_image_obj);
        let egl_cache = match cache {
            CacheKind::Src => &mut self.src_egl_cache,
            CacheKind::Dst => &mut self.dst_egl_cache,
        };
        egl_cache.insert(id, egl_image_obj, rbo);
        Ok(handle)
    }

    /// Where the cached source import puts `img`'s logical image on the
    /// texture it covers ([`GlPlatform::import_extent`] +
    /// [`GlPlatform::import_origin`]). ONE cache lookup for both, because
    /// this runs on every convert. Read after the import so the entry
    /// exists; [`ImportMap::WHOLE`](super::render::ImportMap::WHOLE) on every
    /// platform whose import is the logical image, and when the source was
    /// fed by upload instead.
    fn cached_src_import_map(
        &self,
        img: &Tensor<u8>,
        fmt: PixelFormat,
    ) -> super::render::ImportMap {
        let id = BufferImportKey::from_tensor(img, fmt, false);
        self.src_egl_cache
            .entries
            .get(&id)
            .map(|entry| {
                let map = super::render::ImportMap {
                    extent: Platform::import_extent(&entry.import),
                    origin: Platform::import_origin(&entry.import),
                };
                // The origin is only meaningful against an extent: every fold
                // helper takes the map as the identity when `extent` is
                // `None`, so a leaf that shifted the image without saying how
                // big the texture is would drop the shift silently and show
                // up as a black or torn frame on that board alone, with
                // nothing to see locally. The two travel together.
                debug_assert!(
                    map.origin == (0, 0) || map.extent.is_some(),
                    "an import origin {:?} without an extent is dropped by the fold",
                    map.origin,
                );
                map
            })
            .unwrap_or(super::render::ImportMap::WHOLE)
    }

    /// [`Self::cached_src_import_map`] applied to a source rectangle: the
    /// single site that turns logical-image coordinates into texture
    /// coordinates for the uv-sampling paths. The NV combined-plane path does
    /// not use it — its shader indexes texels absolutely from `img_size`, so a
    /// narrowed plane already reads the right texels, which is also why the NV
    /// R8 import is never rebased to an aligned base (issue #170); it keeps
    /// the Stage F decline.
    fn scale_src_roi(
        &self,
        roi: RegionOfInterest,
        img: &Tensor<u8>,
        fmt: PixelFormat,
    ) -> RegionOfInterest {
        let (Some(w), Some(h)) = (img.width(), img.height()) else {
            return roi;
        };
        super::render::scale_roi_to_import(roi, (w, h), self.cached_src_import_map(img, fmt))
    }

    /// The `src_extent` location of the `sampler2D` source program
    /// `draw_src_texture` selects for `is_int8`.
    fn texture_src_extent_loc(&self, is_int8: bool) -> i32 {
        let [plain, int8] = self.texture_src_extent_locs;
        if is_int8 {
            int8
        } else {
            plain
        }
    }

    /// The `src_extent` location of the external-OES program the two camera
    /// draws select for `is_int8` and `planar`.
    fn external_src_extent_loc(&self, is_int8: bool, planar: bool) -> i32 {
        let [yuv, yuv_int8, pl, pl_int8] = self.external_src_extent_locs;
        match (planar, is_int8) {
            (false, false) => yuv,
            (false, true) => yuv_int8,
            (true, false) => pl,
            (true, true) => pl_int8,
        }
    }

    /// The float paths' `(src_rect_uv, src_extent)` uniforms. When
    /// [`FloatSrcFeed::Import`] fed this convert the uv is mapped onto the
    /// texture the import covers and the extent is the logical image's
    /// half-texel-inset rectangle on it; both float uv builders normalize
    /// over the logical dims and then come through here, so a
    /// `configure_image`-narrowed pool source samples its own region rather
    /// than the whole pool texture. The upload and PBO feeds put the logical
    /// image in a texture of exactly its size, so the uv passes through and
    /// the extent is that texture's own inset.
    pub(super) fn float_src_mapping_for_feed(
        &self,
        feed: float::FloatSrcFeed,
        src_rect_uv: [f32; 4],
        src_u8: &Tensor<u8>,
        src_w: usize,
        src_h: usize,
    ) -> ([f32; 4], [f32; 4]) {
        let map = if feed == float::FloatSrcFeed::Import {
            self.cached_src_import_map(src_u8, PixelFormat::Rgba)
        } else {
            super::render::ImportMap::WHOLE
        };
        (
            super::render::scale_uv_rect_to_import(src_rect_uv, (src_w, src_h), map),
            super::render::sample_clamp_rect((src_w, src_h), map),
        )
    }

    /// Look up the renderbuffer ID for a cached destination EGLImage.
    fn cached_dst_renderbuffer<T>(&self, img: &Tensor<T>, fmt: PixelFormat) -> Option<u32>
    where
        T: num_traits::Num + Clone + std::fmt::Debug + Send + Sync + edgefirst_tensor::Element,
    {
        let id = BufferImportKey::from_tensor(img, fmt, true);
        self.dst_egl_cache
            .entries
            .get(&id)
            .and_then(|entry| entry.renderbuffer)
    }

    /// Create an EGLImage from a DMA buffer with explicitly specified internal
    /// dimensions and format. Used when the GL render surface differs from the
    /// logical image dimensions (e.g., packed RGB reinterpretation, or the F16
    /// RGBA16F-packed planar destination).
    ///
    /// Generic over the tensor element type so it works for both `u8`
    /// (packed-RGB DMA) and `f16` (RGBA16F-packed DMA) destinations. Only the
    /// DMA fd, stride and offset are read from the tensor; `width`, `height`,
    /// `drm_format` and `bpp` describe the GL-visible packed surface.
    /// Get or create an EGLImage for a packed DMA destination with
    /// reinterpreted dimensions. Uses the dst cache keyed by buffer identity.
    ///
    /// Generic over the tensor element type so it serves both the `u8`
    /// packed-RGB destination (`PackedImportFormat::Rgba8888`) and the
    /// `f16` RGBA16F-packed planar destination (`Rgba16161616F`).
    fn get_or_create_egl_image_rgb<T>(
        &mut self,
        img: &Tensor<T>,
        img_fmt: PixelFormat,
        width: usize,
        height: usize,
        packed: super::platform::PackedImportFormat,
    ) -> Result<PlatformHandle, crate::Error>
    where
        T: num_traits::Num + Clone + std::fmt::Debug + Send + Sync + edgefirst_tensor::Element,
    {
        // Before the lookup, not inside the miss arm: a hit returns a cached
        // import without consulting the platform at all, so an identity that
        // has stopped naming its buffer would be served a stale image.
        // Test hook: stand in for a driver that refuses this destination, so
        // the fallback to the mapped-texture readback is exercised on hosts
        // whose driver accepts every destination (issue #175).
        #[cfg(test)]
        if self.fail_dst_import {
            return Err(crate::Error::OpenGl(
                "EDGEFIRST test hook: zero-copy destination import refused".to_string(),
            ));
        }
        Platform::validate_import_identity(img, "packed destination")?;
        // Keyed identically to `cached_dst_renderbuffer` and the logical-dims
        // dst path: the packed render dims derive deterministically from the
        // tensor's logical geometry, so `from_tensor` is a consistent key.
        let id = BufferImportKey::from_tensor(img, img_fmt, true);

        let ts = self.dst_egl_cache.next_timestamp();
        if let Some(cached) = self.dst_egl_cache.entries.get_mut(&id) {
            self.dst_egl_cache.hits += 1;
            cached.last_used = ts;
            log::trace!("ImportCache dst (RGB) hit: id={:#x}", id.luma_id);
            return Ok(Platform::import_handle(&cached.import));
        }
        self.dst_egl_cache.misses += 1;
        log::trace!("ImportCache dst (RGB) miss: id={:#x}", id.luma_id);
        // Invalidate dst texture binding state on cache miss (new EGLImage creation).
        self.invalidate_dst_textures();

        let egl_image_obj =
            Platform::import_buffer_packed(&self.gl_context, img, width, height, packed)?;
        let handle = Platform::import_handle(&egl_image_obj);

        let rbo = if self.use_renderbuffer {
            let mut rbo: u32 = 0;
            unsafe {
                edgefirst_gl::gl::GenRenderbuffers(1, &mut rbo);
                edgefirst_gl::gl::BindRenderbuffer(edgefirst_gl::gl::RENDERBUFFER, rbo);
                Platform::attach_renderbuffer_storage(
                    &self.gl_context,
                    Platform::import_handle(&egl_image_obj),
                )?;
                if let Err(e) = check_gl_error(function!(), line!()) {
                    edgefirst_gl::gl::DeleteRenderbuffers(1, &rbo);
                    return Err(e);
                }
            }
            Some(rbo)
        } else {
            None
        };

        self.dst_egl_cache.insert(id, egl_image_obj, rbo);
        Ok(handle)
    }

    // Reshapes the segmentation to be compatible with RGBA texture array rendering.
    fn reshape_segmentation_to_rgba(&self, segmentation: &[u8], shape: [usize; 3]) -> Vec<u8> {
        let [height, width, classes] = shape;

        let n_layer_stride = height * width * 4;
        let n_row_stride = width * 4;
        let n_col_stride = 4;
        let row_stride = width * classes;
        let col_stride = classes;

        let mut new_segmentation = vec![0u8; n_layer_stride * classes.div_ceil(4)];

        for i in 0..height {
            for j in 0..width {
                for k in 0..classes.div_ceil(4) * 4 {
                    if k >= classes {
                        new_segmentation[n_layer_stride * (k / 4)
                            + i * n_row_stride
                            + j * n_col_stride
                            + k % 4] = 0;
                    } else {
                        new_segmentation[n_layer_stride * (k / 4)
                            + i * n_row_stride
                            + j * n_col_stride
                            + k % 4] = segmentation[i * row_stride + j * col_stride + k];
                    }
                }
            }
        }

        new_segmentation
    }

    fn render_modelpack_segmentation(
        &mut self,
        dst_roi: RegionOfInterest,
        segmentation: &[u8],
        shape: [usize; 3],
    ) -> Result<(), crate::Error> {
        log::debug!("start render_segmentation_to_image");

        // TODO: Implement specialization for 2 classes and 4 classes which shouldn't
        // need rearranging the data
        let new_segmentation = self.reshape_segmentation_to_rgba(segmentation, shape);

        let [height, width, classes] = shape;

        let format = edgefirst_gl::gl::RGBA;
        let texture_target = edgefirst_gl::gl::TEXTURE_2D_ARRAY;
        self.segmentation_program
            .load_uniform_1i(c"background_index", shape[2] as i32 - 1)?;

        edgefirst_gl::use_program(self.segmentation_program.id);

        edgefirst_gl::bind_texture(texture_target, self.segmentation_texture.id);
        edgefirst_gl::active_texture(edgefirst_gl::gl::TEXTURE0);
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_MIN_FILTER,
            edgefirst_gl::gl::LINEAR as i32,
        );
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_MAG_FILTER,
            edgefirst_gl::gl::LINEAR as i32,
        );
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_WRAP_S,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );

        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_WRAP_T,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );

        edgefirst_gl::tex_image3d(
            texture_target,
            0,
            format as i32,
            width as i32,
            height as i32,
            classes.div_ceil(4) as i32,
            0,
            format,
            edgefirst_gl::gl::UNSIGNED_BYTE,
            Some(&new_segmentation),
        );

        let src_roi = RegionOfInterest {
            left: 0.,
            top: 1.,
            right: 1.,
            bottom: 0.,
        };

        unsafe {
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            let camera_vertices: [f32; 12] = [
                dst_roi.left,
                dst_roi.top,
                0., // left top
                dst_roi.right,
                dst_roi.top,
                0., // right top
                dst_roi.right,
                dst_roi.bottom,
                0., // right bottom
                dst_roi.left,
                dst_roi.bottom,
                0., // left bottom
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * camera_vertices.len()) as isize,
                camera_vertices.as_ptr() as *const c_void,
            );

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

            let texture_vertices: [f32; 8] = [
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * 8) as isize,
                (texture_vertices[0..]).as_ptr() as *const c_void,
            );

            let vertices_index: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                vertices_index.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                vertices_index.as_ptr() as *const c_void,
            );
        }

        Ok(())
    }

    /// Bind the instanced segmentation program and configure the persistent
    /// mask texture for a batch of `render_yolo_segmentation` calls.
    ///
    /// Call once before the per-detection loop. Hoisting this out of
    /// `render_yolo_segmentation` avoids N× redundant `glTexParameteri`,
    /// `glUseProgram`, and `glBindTexture` calls per frame.
    fn setup_yolo_segmentation_pass(&self) {
        let texture_target = edgefirst_gl::gl::TEXTURE_2D;
        edgefirst_gl::use_program(self.instanced_segmentation_program.id);
        edgefirst_gl::active_texture(edgefirst_gl::gl::TEXTURE0);
        edgefirst_gl::bind_texture(texture_target, self.segmentation_texture.id);
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_MIN_FILTER,
            edgefirst_gl::gl::LINEAR as i32,
        );
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_MAG_FILTER,
            edgefirst_gl::gl::LINEAR as i32,
        );
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_WRAP_S,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );
        edgefirst_gl::tex_parameteri(
            texture_target,
            edgefirst_gl::gl::TEXTURE_WRAP_T,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );
    }

    /// Render a single pre-decoded YOLO segmentation mask as a coloured
    /// overlay quad. The caller must invoke [`setup_yolo_segmentation_pass`]
    /// once before the first call in a batch so the program, bound texture,
    /// and texture parameters are already set.
    ///
    /// Each call uploads the mask via `glTexImage2D`, which implicitly
    /// orphans the previous storage on most drivers. This avoids the
    /// read-after-write hazard a persistent texture would introduce on
    /// Vivante, which serialises every `glTexSubImage2D` against the still
    /// in-flight previous draw and ends up slower than orphaning.
    /// Compared with the original implementation we still drop the
    /// per-instance CPU 1 px zero-pad copy — the shader's
    /// `smoothstep(0.5, 0.65)` provides the edge antialiasing that the
    /// padding used to proxy for, and texel-centre UVs keep bilinear
    /// sampling strictly inside the uploaded mask region.
    fn render_yolo_segmentation(
        &mut self,
        dst_roi: RegionOfInterest,
        segmentation: &[u8],
        shape: [usize; 2],
        class: usize,
    ) -> Result<(), crate::Error> {
        let [height, width] = shape;
        let texture_target = edgefirst_gl::gl::TEXTURE_2D;

        // Per-instance allocation + upload, equivalent to the old code path
        // but without the CPU pad copy. `glTexImage2D` here implicitly
        // orphans the texture's previous backing store on Vivante / Mali —
        // the in-flight previous draw keeps the old storage alive while
        // the new mask uploads to fresh memory, preserving CPU/GPU
        // parallelism.
        edgefirst_gl::tex_image2d(
            texture_target,
            0,
            edgefirst_gl::gl::R8 as i32,
            width as i32,
            height as i32,
            0,
            edgefirst_gl::gl::RED,
            edgefirst_gl::gl::UNSIGNED_BYTE,
            Some(segmentation),
        );

        self.instanced_segmentation_program
            .load_uniform_1i(c"class_index", class as i32)?;

        // Texel-centre UVs: bilinear filtering returns the exact uploaded
        // texel value at each corner of the quad, so no sampling reaches
        // outside the mask data and no zero-padding border is needed.
        let u_lo = 0.5 / width as f32;
        let v_lo = 0.5 / height as f32;
        let u_hi = (width as f32 - 0.5) / width as f32;
        let v_hi = (height as f32 - 0.5) / height as f32;

        // tc.y = 0 corresponds to mask row 0 (image top); NDC top of the quad
        // (`dst_roi.top`, which holds `cvt_screen_coord(seg.ymax)`) renders
        // image bottom, so the first two tex vertices get `v_hi`.
        let src_roi = RegionOfInterest {
            left: u_lo,
            top: v_hi,
            right: u_hi,
            bottom: v_lo,
        };

        unsafe {
            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

            let camera_vertices: [f32; 12] = [
                dst_roi.left,
                dst_roi.top,
                0., // left top
                dst_roi.right,
                dst_roi.top,
                0., // right top
                dst_roi.right,
                dst_roi.bottom,
                0., // right bottom
                dst_roi.left,
                dst_roi.bottom,
                0., // left bottom
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * camera_vertices.len()) as isize,
                camera_vertices.as_ptr() as *const c_void,
            );

            edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.texture_buffer.id);
            edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

            let texture_vertices: [f32; 8] = [
                src_roi.left,
                src_roi.top,
                src_roi.right,
                src_roi.top,
                src_roi.right,
                src_roi.bottom,
                src_roi.left,
                src_roi.bottom,
            ];
            edgefirst_gl::gl::BufferSubData(
                edgefirst_gl::gl::ARRAY_BUFFER,
                0,
                (size_of::<f32>() * 8) as isize,
                (texture_vertices).as_ptr() as *const c_void,
            );

            let vertices_index: [u32; 4] = [0, 1, 2, 3];
            edgefirst_gl::gl::DrawElements(
                edgefirst_gl::gl::TRIANGLE_FAN,
                vertices_index.len() as i32,
                edgefirst_gl::gl::UNSIGNED_INT,
                vertices_index.as_ptr() as *const c_void,
            );

            // Vivante (i.MX 8MP GC7000UL) regresses ~2× when many masks
            // queue without periodic drains: the driver appears to enter
            // a slow allocation path once its command buffer or texture
            // orphan queue fills. An explicit `glFinish()` per instance
            // matches the legacy behaviour and keeps the per-instance
            // cost bounded.
            //
            // Mali Valhall (i.MX 95) is the opposite — `glFinish()` here
            // forces a TBDR tile store-unload of the framebuffer per
            // draw, which dominates the per-instance cost. Letting the
            // pipeline batch into the single `edgefirst_gl::finish()` at the end
            // of `draw_decoded_masks_impl` recovers ~30% on a 40-mask
            // crowd scene.
            if self.is_vivante {
                edgefirst_gl::gl::Finish();
            }
        }

        Ok(())
    }

    /// Repack proto tensor `(H, W, num_protos)` as f32 into RGBA f16 layers
    /// suitable for upload to a GL_TEXTURE_2D_ARRAY with GL_RGBA16F.
    ///
    /// Returns `(repacked_bytes, num_layers)` where each layer is H*W*4 half-floats.
    /// Render YOLO proto segmentation masks using the fused GPU pipeline.
    ///
    /// Dispatches on the proto tensor's runtime dtype via
    /// [`edgefirst_tensor::TensorDyn::dtype`]:
    /// - `I8`: uploads raw int8 as `GL_R8I`, dequantizes in shader (requires
    ///   per-tensor [`edgefirst_tensor::Quantization`] on the proto tensor).
    /// - `F32`: uploads as `GL_R32F` with hardware bilinear (if available),
    ///   or falls back to the `RGBA16F` repack path for older drivers.
    /// - `F16`: repacks natively into `RGBA16F` without a widening step.
    fn render_proto_segmentation(
        &mut self,
        detect: &[DetectBox],
        proto_data: &ProtoData,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        use edgefirst_tensor::{DType, QuantMode, TensorMapTrait, TensorTrait};

        if detect.is_empty() {
            return Ok(());
        }
        let proto_shape = proto_data.protos.shape();
        if proto_shape.len() != 3 {
            return Err(crate::Error::InvalidShape(format!(
                "protos tensor must be rank-3, got {proto_shape:?}"
            )));
        }
        // Interpret shape based on physical layout.
        let (height, width, num_protos) = match proto_data.layout {
            ProtoLayout::Nhwc => (proto_shape[0], proto_shape[1], proto_shape[2]),
            ProtoLayout::Nchw => (proto_shape[1], proto_shape[2], proto_shape[0]),
        };
        let coeff_shape = proto_data.mask_coefficients.shape();
        if coeff_shape.len() != 2 || coeff_shape[1] != num_protos {
            return Err(crate::Error::InvalidShape(format!(
                "mask_coefficients shape {coeff_shape:?} incompatible with protos \
                 {proto_shape:?} (expected [N, {num_protos}])"
            )));
        }
        // Genuine "no detections this frame" → nothing to render.
        if coeff_shape[0] == 0 {
            return Ok(());
        }
        let texture_target = edgefirst_gl::gl::TEXTURE_2D_ARRAY;

        // Pure path decision: upload strategy × program × count uniform.
        // Rejects NCHW layouts and unsupported proto dtypes up front (the
        // caller falls back to the CPU path on NotSupported).
        let plan = super::proto_dispatch::plan_proto(
            proto_data.protos.dtype(),
            proto_data.layout,
            self.proto_repack_compute_program.is_some(),
            self.has_float_linear,
            self.int8_interpolation_mode,
        )?;

        // The proto render's span — the path previously had none (only a
        // FunctionTimer wall-clock at the draw_proto_masks entry). Plan
        // fields make the chosen upload/program visible in traces.
        let _span = tracing::trace_span!(
            "image.draw.gl.proto",
            dtype = ?proto_data.protos.dtype(),
            upload = ?plan.upload,
            program = ?plan.program,
            num_protos,
            detections = detect.len(),
        )
        .entered();

        // Coefficient slice for the GL uniform upload path. The shaders
        // consume f32 regardless of source dtype, but we hold the F32 case
        // as a borrowed slice (no allocation) and only widen for F16. The
        // `Cow<[f32]>` lets both arms share a single downstream pass.
        //
        // The F16 widening is one flat `Vec<f32>`, replacing the prior
        // `Vec<Vec<f32>>` (one inner Vec per detection) — avoids N small
        // heap allocations per frame on the hot path.
        let mc_map_f32;
        let mc_map_f16;
        let mc_map_i8;
        let coeff_widen_f16: Vec<f32>;
        let coeff_dequant: Vec<f32>;
        let coeff_slice: &[f32] = match proto_data.mask_coefficients.dtype() {
            DType::F32 => {
                let t = proto_data.mask_coefficients.as_f32().expect("F32");
                mc_map_f32 = t.map_read()?;
                mc_map_f32.as_slice()
            }
            DType::F16 => {
                let t = proto_data.mask_coefficients.as_f16().expect("F16");
                mc_map_f16 = t.map_read()?;
                coeff_widen_f16 = mc_map_f16.as_slice().iter().map(|v| v.to_f32()).collect();
                &coeff_widen_f16[..]
            }
            DType::I8 => {
                let t = proto_data.mask_coefficients.as_i8().expect("I8");
                mc_map_i8 = t.map_read()?;
                let quant = t.quantization();
                coeff_dequant = super::proto_dispatch::dequant_coeffs(
                    mc_map_i8.as_slice(),
                    quant.as_ref().map(|q| q.mode()),
                    "I8",
                )?;
                &coeff_dequant[..]
            }
            DType::I16 => {
                let t = proto_data.mask_coefficients.as_i16().expect("I16");
                let mc_map_i16 = t.map_read()?;
                let quant = t.quantization();
                coeff_dequant = super::proto_dispatch::dequant_coeffs(
                    mc_map_i16.as_slice(),
                    quant.as_ref().map(|q| q.mode()),
                    "I16",
                )?;
                &coeff_dequant[..]
            }
            other => {
                return Err(crate::Error::InvalidShape(format!(
                    "mask_coefficients dtype {other:?} not supported on GL seg path"
                )));
            }
        };

        // Each proto-dtype arm holds its `TensorMap` for the duration of the
        // GL upload and passes an `ArrayView3` borrowed from the mapped slice
        // to the helper — no per-frame `to_owned()` clone of the proto tensor.
        match proto_data.protos.dtype() {
            DType::I8 => {
                let t = proto_data.protos.as_i8().expect("I8");
                let m = t.map_read()?;
                let quant = t.quantization().ok_or_else(|| {
                    crate::Error::InvalidShape("I8 protos require quantization metadata".into())
                })?;
                // GL shader path: per-tensor quant only (shader uploads a
                // single scale/zp uniform). Per-channel would require a
                // shader rewrite — return NotSupported for now.
                let (scale, zp) = match quant.mode() {
                    QuantMode::PerTensor { scale, zero_point } => (scale, zero_point),
                    QuantMode::PerTensorSymmetric { scale } => (scale, 0_i32),
                    QuantMode::PerChannel { axis, .. }
                    | QuantMode::PerChannelSymmetric { axis, .. } => {
                        return Err(crate::Error::NotSupported(format!(
                            "GL seg path: per-channel quantization (axis={axis}) \
                             not yet supported — falls back to CPU in caller"
                        )));
                    }
                };
                let protos_view = ndarray::ArrayView3::<i8>::from_shape(
                    (height, width, num_protos),
                    m.as_slice(),
                )
                .map_err(|e| crate::Error::InvalidShape(format!("{e}")))?;
                // Pass the pair straight through: the scale/zero_point were read
                // from the tensor's own `edgefirst_tensor::Quantization`, and
                // wrapping them in the decoder's near-identical type only to
                // unwrap them one level down was a pure adapter.
                let quantization = (scale, zp);
                self.render_proto_segmentation_int8(
                    plan,
                    detect,
                    coeff_slice,
                    protos_view,
                    quantization,
                    height,
                    width,
                    num_protos,
                    texture_target,
                    color_mode,
                )?;
            }
            DType::F32 => {
                let t = proto_data.protos.as_f32().expect("F32");
                let m = t.map_read()?;
                let protos_view = ndarray::ArrayView3::<f32>::from_shape(
                    (height, width, num_protos),
                    m.as_slice(),
                )
                .map_err(|e| crate::Error::InvalidShape(format!("{e}")))?;
                self.render_proto_layers(
                    plan,
                    detect,
                    coeff_slice,
                    ProtoLayersData::F32(protos_view),
                    height,
                    width,
                    num_protos,
                    texture_target,
                    color_mode,
                )?;
            }
            DType::F16 => {
                let t = proto_data.protos.as_f16().expect("F16");
                let m = t.map_read()?;
                let protos_view = ndarray::ArrayView3::<half::f16>::from_shape(
                    (height, width, num_protos),
                    m.as_slice(),
                )
                .map_err(|e| crate::Error::InvalidShape(format!("{e}")))?;
                self.render_proto_layers(
                    plan,
                    detect,
                    coeff_slice,
                    ProtoLayersData::F16(protos_view),
                    height,
                    width,
                    num_protos,
                    texture_target,
                    color_mode,
                )?;
            }
            other => {
                return Err(crate::Error::InvalidShape(format!(
                    "GL seg path: proto dtype {other:?} not supported"
                )));
            }
        }

        unsafe { edgefirst_gl::gl::Finish() };
        Ok(())
    }

    /// Render detection quads using the active program. Shared by all proto
    /// shader paths.
    fn render_proto_detection_quads(
        &self,
        program: &GlProgram,
        detect: &[DetectBox],
        mask_coefficients: &[f32],
        num_protos: usize,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        let cvt_screen_coord = |normalized: f32| normalized * 2.0 - 1.0;

        // Resolve the per-detection uniform locations once per program
        // switch — `load_uniform_*` is a driver string lookup plus a
        // redundant UseProgram, and this loop previously paid both twice
        // per detection per frame. The caller has already bound `program`.
        let (cached_id, mut loc_coeff, mut loc_class) = self.proto_quad_locs.get();
        if cached_id != program.id {
            unsafe {
                loc_coeff =
                    edgefirst_gl::gl::GetUniformLocation(program.id, c"mask_coeff".as_ptr());
                loc_class =
                    edgefirst_gl::gl::GetUniformLocation(program.id, c"class_index".as_ptr());
            }
            self.proto_quad_locs.set((program.id, loc_coeff, loc_class));
        }

        // Stride the flat `mask_coefficients` buffer by `num_protos` so we
        // get one slice per detection. `chunks_exact` requires the total
        // length to be a multiple of `num_protos`; the dispatcher already
        // validates `coeff_shape == [N, num_protos]` upstream.
        for (idx, (det, coeff)) in detect
            .iter()
            .zip(mask_coefficients.chunks_exact(num_protos))
            .enumerate()
        {
            let color_index = color_mode.index(idx, det.label);
            let mut packed_coeff = [[0.0f32; 4]; 8];
            for (i, val) in coeff.iter().enumerate().take(32) {
                packed_coeff[i / 4][i % 4] = *val;
            }

            unsafe {
                edgefirst_gl::gl::Uniform4fv(loc_coeff, 8, packed_coeff.as_ptr() as *const f32);
                edgefirst_gl::gl::Uniform1i(loc_class, color_index as i32);
            }

            let dst_roi = RegionOfInterest {
                left: cvt_screen_coord(det.bbox.xmin),
                top: cvt_screen_coord(det.bbox.ymax),
                right: cvt_screen_coord(det.bbox.xmax),
                bottom: cvt_screen_coord(det.bbox.ymin),
            };

            // Proto texture coords: tex row 0 = image top (data uploaded in
            // row-major order where y=0 is top of image, and GL treats the
            // first row of pixel data as the bottom of the texture — but
            // texelFetch(y=0) returns that bottom row, which is our image top).
            // So tc.y=0 → image top, tc.y=1 → image bottom.
            // At NDC top (higher Y = image bottom = ymax), we want tc.y = ymax.
            // At NDC bottom (lower Y = image top = ymin), we want tc.y = ymin.
            let src_roi = RegionOfInterest {
                left: det.bbox.xmin,
                top: det.bbox.ymax,
                right: det.bbox.xmax,
                bottom: det.bbox.ymin,
            };

            unsafe {
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
                edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);

                let camera_vertices: [f32; 12] = [
                    dst_roi.left,
                    dst_roi.top,
                    0.,
                    dst_roi.right,
                    dst_roi.top,
                    0.,
                    dst_roi.right,
                    dst_roi.bottom,
                    0.,
                    dst_roi.left,
                    dst_roi.bottom,
                    0.,
                ];
                edgefirst_gl::gl::BufferSubData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    0,
                    (size_of::<f32>() * camera_vertices.len()) as isize,
                    camera_vertices.as_ptr() as *const c_void,
                );

                edgefirst_gl::gl::BindBuffer(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    self.texture_buffer.id,
                );
                edgefirst_gl::gl::EnableVertexAttribArray(self.texture_buffer.buffer_index);

                let texture_vertices: [f32; 8] = [
                    src_roi.left,
                    src_roi.top,
                    src_roi.right,
                    src_roi.top,
                    src_roi.right,
                    src_roi.bottom,
                    src_roi.left,
                    src_roi.bottom,
                ];
                edgefirst_gl::gl::BufferSubData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    0,
                    (size_of::<f32>() * 8) as isize,
                    texture_vertices.as_ptr() as *const c_void,
                );

                let vertices_index: [u32; 4] = [0, 1, 2, 3];
                edgefirst_gl::gl::DrawElements(
                    edgefirst_gl::gl::TRIANGLE_FAN,
                    vertices_index.len() as i32,
                    edgefirst_gl::gl::UNSIGNED_INT,
                    vertices_index.as_ptr() as *const c_void,
                );
            }
        }
        Ok(())
    }

    /// Int8 proto path: upload raw i8 protos per `plan.upload`, render per
    /// `plan.program`.
    #[allow(clippy::too_many_arguments)]
    fn render_proto_segmentation_int8(
        &mut self,
        plan: super::proto_dispatch::ProtoPlan,
        detect: &[DetectBox],
        mask_coefficients: &[f32],
        protos: ndarray::ArrayView3<'_, i8>,
        quantization: (f32, i32),
        height: usize,
        width: usize,
        num_protos: usize,
        texture_target: u32,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        // Protos are (H, W, num_protos) in row-major HWC. The GL texture
        // needs layer-first CHW (one proto per layer).
        if plan.upload == super::proto_dispatch::ProtoUpload::I8Compute {
            let compute_program = self.proto_repack_compute_program.ok_or_else(|| {
                crate::Error::InvalidShape(
                    "plan selected I8Compute without a compiled compute program".into(),
                )
            })?;
            // === GLES 3.1 compute shader path ===
            // Upload HWC data as-is to SSBO, let GPU transpose via compute.
            // Fall through to CPU repack if proto array is non-contiguous.
            let mut data = match protos.as_slice() {
                Some(s) => std::borrow::Cow::Borrowed(s),
                None => std::borrow::Cow::Owned(protos.iter().copied().collect()),
            };
            // Pad to a 4-byte boundary for SSBO int[] alignment — by copying,
            // not by over-reading past the slice end.
            if data.len() % 4 != 0 {
                let mut owned = data.into_owned();
                owned.resize(owned.len().next_multiple_of(4), 0);
                data = std::borrow::Cow::Owned(owned);
            }
            let data_bytes = data.len();

            // Allocate as R32I (imageStore-compatible; the int8 fragment
            // shaders read integers identically from R8I or R32I via
            // texelFetch). Immutable storage + binding handled by the gate.
            if self.ensure_proto_texture(
                texture_target,
                edgefirst_gl::gl::R32I,
                width,
                height,
                num_protos,
            ) {
                Self::set_proto_tex_params(texture_target, edgefirst_gl::gl::NEAREST);
            }

            unsafe {
                // Upload HWC data to SSBO
                edgefirst_gl::gl::BindBuffer(
                    edgefirst_gl::gl::SHADER_STORAGE_BUFFER,
                    self.proto_ssbo,
                );
                if data_bytes > self.proto_ssbo_size {
                    edgefirst_gl::gl::BufferData(
                        edgefirst_gl::gl::SHADER_STORAGE_BUFFER,
                        data_bytes as isize,
                        data.as_ptr() as *const std::ffi::c_void,
                        edgefirst_gl::gl::STREAM_DRAW,
                    );
                    self.proto_ssbo_size = data_bytes;
                } else {
                    edgefirst_gl::gl::BufferSubData(
                        edgefirst_gl::gl::SHADER_STORAGE_BUFFER,
                        0,
                        data_bytes as isize,
                        data.as_ptr() as *const std::ffi::c_void,
                    );
                }
                edgefirst_gl::gl::BindBufferBase(
                    edgefirst_gl::gl::SHADER_STORAGE_BUFFER,
                    0,
                    self.proto_ssbo,
                );

                // Bind texture as image for compute write (R32I for compatibility)
                edgefirst_gl::gl::BindImageTexture(
                    0,
                    self.proto_texture.id,
                    0,
                    edgefirst_gl::gl::TRUE,
                    0,
                    edgefirst_gl::gl::WRITE_ONLY,
                    edgefirst_gl::gl::R32I,
                );

                // Dispatch compute (uniform locations resolved at compile)
                edgefirst_gl::gl::UseProgram(compute_program);
                let (loc_w, loc_h, loc_np) = self.proto_compute_locs;
                edgefirst_gl::gl::Uniform1i(loc_w, width as i32);
                edgefirst_gl::gl::Uniform1i(loc_h, height as i32);
                edgefirst_gl::gl::Uniform1i(loc_np, num_protos as i32);

                let groups_x = width.div_ceil(16) as u32;
                let groups_y = height.div_ceil(16) as u32;
                edgefirst_gl::gl::DispatchCompute(groups_x, groups_y, 1);
                edgefirst_gl::gl::MemoryBarrier(
                    edgefirst_gl::gl::TEXTURE_FETCH_BARRIER_BIT
                        | edgefirst_gl::gl::SHADER_IMAGE_ACCESS_BARRIER_BIT,
                );

                // Unbind SSBO and log any GL errors from compute dispatch
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::SHADER_STORAGE_BUFFER, 0);
                loop {
                    let err = edgefirst_gl::gl::GetError();
                    if err == edgefirst_gl::gl::NO_ERROR {
                        break;
                    }
                    log::debug!("GL error after compute dispatch: 0x{err:x}");
                }
            }
        } else {
            // === GLES 3.0 fallback: CPU repack ===
            let tex_data = super::proto_dispatch::repack_layers(protos);

            self.upload_proto_texture(
                texture_target,
                edgefirst_gl::gl::R8I,
                width,
                height,
                num_protos,
                edgefirst_gl::gl::RED_INTEGER,
                edgefirst_gl::gl::BYTE,
                edgefirst_gl::gl::NEAREST,
                &tex_data,
            );
        }

        let (proto_scale, proto_zp) = quantization;
        let proto_scaled_zp = -(proto_zp as f32) * proto_scale;

        match plan.program {
            super::proto_dispatch::ProtoProgram::Int8Nearest
            | super::proto_dispatch::ProtoProgram::Int8Bilinear => {
                let program = if plan.program == super::proto_dispatch::ProtoProgram::Int8Nearest {
                    &self.proto_segmentation_int8_nearest_program
                } else {
                    &self.proto_segmentation_int8_bilinear_program
                };
                edgefirst_gl::use_program(program.id);
                program.load_uniform_1i(c"num_protos", num_protos as i32)?;
                program.load_uniform_1f(c"proto_scale", proto_scale)?;
                program.load_uniform_1f(c"proto_scaled_zp", proto_scaled_zp)?;
                self.render_proto_detection_quads(
                    program,
                    detect,
                    mask_coefficients,
                    num_protos,
                    color_mode,
                )?;
            }
            super::proto_dispatch::ProtoProgram::Int8TwoPass => {
                self.render_proto_int8_two_pass(
                    detect,
                    mask_coefficients,
                    quantization,
                    height,
                    width,
                    num_protos,
                    texture_target,
                    color_mode,
                )?;
            }
            other => {
                return Err(crate::Error::InvalidShape(format!(
                    "proto program {other:?} is not an int8 program"
                )));
            }
        }

        Ok(())
    }

    /// Two-pass int8 path: dequant int8→RGBA16F FBO, then render with
    /// existing f16 shader using GL_LINEAR.
    #[allow(clippy::too_many_arguments)]
    fn render_proto_int8_two_pass(
        &mut self,
        detect: &[DetectBox],
        mask_coefficients: &[f32],
        quantization: (f32, i32),
        height: usize,
        width: usize,
        num_protos: usize,
        texture_target: u32,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        let num_layers = num_protos.div_ceil(4);

        // Save the caller's FBO, viewport and blend state so we can restore
        // all three after dequant.
        let (saved_fbo, saved_viewport, blend_was_enabled) = unsafe {
            let mut fbo: i32 = 0;
            edgefirst_gl::gl::GetIntegerv(edgefirst_gl::gl::FRAMEBUFFER_BINDING, &mut fbo);
            let mut vp = [0i32; 4];
            edgefirst_gl::gl::GetIntegerv(edgefirst_gl::gl::VIEWPORT, vp.as_mut_ptr());
            let blend =
                edgefirst_gl::gl::IsEnabled(edgefirst_gl::gl::BLEND) == edgefirst_gl::gl::TRUE;
            (fbo as u32, vp, blend)
        };

        // Pass 1: Dequantize int8 → RGBA16F texture via the persistent
        // dequant FBO. The render target is gated like the proto texture
        // (recreate-on-change immutable storage) instead of a fresh
        // TexImage3D per call.
        if Self::ensure_immutable_tex_array(
            &mut self.proto_dequant_texture,
            &mut self.proto_dequant_tex_dims,
            texture_target,
            edgefirst_gl::gl::RGBA16F,
            width,
            height,
            num_layers,
        ) {
            Self::set_proto_tex_params(texture_target, edgefirst_gl::gl::LINEAR);
        }

        // The dequant render is not a composite, so blending must be off for
        // it. `draw_proto_masks_impl` enables `GL_BLEND` with
        // `SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ZERO, ONE` for the mask quads, and
        // this pass inherits that state. But it writes four dequantized protos
        // per RGBA16F texel, so the alpha channel carries proto `4k+3` as data
        // rather than coverage: blended, protos `4k..4k+2` come out scaled by
        // their group's alpha proto, and the `ZERO`/`ONE` alpha factors mean
        // every `4k+3` proto is never written at all, leaving whatever the
        // `TexStorage3D` allocation above happened to contain. That made the
        // rendered mask a function of uninitialised GPU memory -- issue #184,
        // whose run-to-run drift on Vivante was exactly that recycled memory.
        edgefirst_gl::disable(edgefirst_gl::gl::BLEND);

        let (proto_scale, proto_zp) = quantization;
        let proto_scaled_zp = -(proto_zp as f32) * proto_scale;

        let dequant_program = &self.proto_dequant_int8_program;
        edgefirst_gl::use_program(dequant_program.id);
        dequant_program.load_uniform_1f(c"proto_scale", proto_scale)?;
        dequant_program.load_uniform_1f(c"proto_scaled_zp", proto_scaled_zp)?;

        // Bind the int8 proto texture to TEXTURE0 for the dequant shader
        edgefirst_gl::active_texture(edgefirst_gl::gl::TEXTURE0);
        edgefirst_gl::bind_texture(texture_target, self.proto_texture.id);

        // Render each RGBA16F layer (4 protos per layer)
        for layer in 0..num_layers {
            self.proto_dequant_fbo.bind();
            unsafe {
                edgefirst_gl::gl::FramebufferTextureLayer(
                    edgefirst_gl::gl::FRAMEBUFFER,
                    edgefirst_gl::gl::COLOR_ATTACHMENT0,
                    self.proto_dequant_texture.id,
                    0,
                    layer as i32,
                );
                edgefirst_gl::gl::Viewport(0, 0, width as i32, height as i32);
            }
            dequant_program.load_uniform_1i(c"base_layer", (layer * 4) as i32)?;
            self.draw_fullscreen_quad()?;
        }

        // Restore the caller's FBO and viewport.
        unsafe {
            edgefirst_gl::gl::BindFramebuffer(edgefirst_gl::gl::FRAMEBUFFER, saved_fbo);
            edgefirst_gl::gl::Viewport(
                saved_viewport[0],
                saved_viewport[1],
                saved_viewport[2],
                saved_viewport[3],
            );
        }
        // Pass 2 *is* a composite -- it draws the mask quads the single-pass
        // proto paths draw -- so hand it back the blend state it came in
        // with. Restored rather than unconditionally enabled: the caller's
        // state is what pass 2 is entitled to, and nothing here says blending
        // was on. An error return from pass 1 leaves blending disabled, which
        // is where `render_segmentation` leaves it on success too.
        if blend_was_enabled {
            edgefirst_gl::enable(edgefirst_gl::gl::BLEND);
        }

        // Pass 2: render with existing f16 shader reading from dequant texture
        let program = &self.proto_segmentation_program;
        edgefirst_gl::use_program(program.id);
        edgefirst_gl::active_texture(edgefirst_gl::gl::TEXTURE0);
        edgefirst_gl::bind_texture(texture_target, self.proto_dequant_texture.id);
        program.load_uniform_1i(c"num_layers", num_layers as i32)?;
        self.render_proto_detection_quads(
            program,
            detect,
            mask_coefficients,
            num_protos,
            color_mode,
        )?;

        Ok(())
    }

    /// One render for every layered-float proto plan — F32→R32F native,
    /// F32→RGBA16F fallback, and native F16→RGBA16F — driven entirely by
    /// the [`ProtoPlan`](super::proto_dispatch::ProtoPlan): upload strategy
    /// picks the repack + texture format, `plan.program` the sampler
    /// program, `plan.count_uniform` the layer-count uniform. Replaces the
    /// three per-dtype `render_proto_segmentation_{f32,f16,f16_native}`
    /// bodies that differed only in those three choices.
    #[allow(clippy::too_many_arguments)]
    fn render_proto_layers(
        &mut self,
        plan: super::proto_dispatch::ProtoPlan,
        detect: &[DetectBox],
        mask_coefficients: &[f32],
        data: ProtoLayersData<'_>,
        height: usize,
        width: usize,
        num_protos: usize,
        texture_target: u32,
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        use super::proto_dispatch::{CountUniform, ProtoProgram, ProtoUpload};

        let num_layers = num_protos.div_ceil(4);
        match (plan.upload, &data) {
            (ProtoUpload::F32R32f, ProtoLayersData::F32(v)) => {
                // Repack protos to layer-first layout: (num_protos, H, W)
                let tex_data = super::proto_dispatch::repack_layers(*v);
                self.upload_proto_texture(
                    texture_target,
                    edgefirst_gl::gl::R32F,
                    width,
                    height,
                    num_protos,
                    edgefirst_gl::gl::RED,
                    edgefirst_gl::gl::FLOAT,
                    edgefirst_gl::gl::LINEAR,
                    &tex_data,
                );
            }
            (ProtoUpload::F32ToRgba16f, ProtoLayersData::F32(v)) => {
                let (tex_data, _) =
                    super::proto_dispatch::repack_rgba_f16_layers(*v, half::f16::from_f32);
                self.upload_proto_texture(
                    texture_target,
                    edgefirst_gl::gl::RGBA16F,
                    width,
                    height,
                    num_layers,
                    edgefirst_gl::gl::RGBA,
                    edgefirst_gl::gl::HALF_FLOAT,
                    edgefirst_gl::gl::LINEAR,
                    &tex_data,
                );
            }
            (ProtoUpload::F16Rgba16f, ProtoLayersData::F16(v)) => {
                let (tex_data, _) = super::proto_dispatch::repack_rgba_f16_layers(*v, |x| x);
                self.upload_proto_texture(
                    texture_target,
                    edgefirst_gl::gl::RGBA16F,
                    width,
                    height,
                    num_layers,
                    edgefirst_gl::gl::RGBA,
                    edgefirst_gl::gl::HALF_FLOAT,
                    edgefirst_gl::gl::LINEAR,
                    &tex_data,
                );
            }
            (upload, _) => {
                return Err(crate::Error::InvalidShape(format!(
                    "proto upload {upload:?} incompatible with the provided proto data"
                )));
            }
        }

        let program = match plan.program {
            ProtoProgram::F32 => &self.proto_segmentation_f32_program,
            ProtoProgram::F16 => &self.proto_segmentation_program,
            other => {
                return Err(crate::Error::InvalidShape(format!(
                    "proto program {other:?} is not a layered-float program"
                )));
            }
        };
        edgefirst_gl::use_program(program.id);
        match plan.count_uniform {
            CountUniform::NumProtos => program.load_uniform_1i(c"num_protos", num_protos as i32)?,
            CountUniform::NumLayers => program.load_uniform_1i(c"num_layers", num_layers as i32)?,
        }
        self.render_proto_detection_quads(
            program,
            detect,
            mask_coefficients,
            num_protos,
            color_mode,
        )
    }

    fn render_segmentation(
        &mut self,
        detect: &[DetectBox],
        segmentation: &[Segmentation],
        color_mode: crate::ColorMode,
    ) -> crate::Result<()> {
        if segmentation.is_empty() {
            return Ok(());
        }

        // Rank guard BEFORE indexing shape()[2] -- see the same guard in the
        // CPU dispatcher. A TensorDyn mask can be any rank, and this is
        // reachable from the public draw_decoded_masks.
        if let Some(bad) = segmentation
            .iter()
            .find(|s| s.segmentation.shape().len() != 3)
        {
            return Err(crate::Error::InvalidShape(format!(
                "segmentation must be [H, W, C], got {:?}",
                bad.segmentation.shape()
            )));
        }

        let is_modelpack = segmentation[0].segmentation.shape()[2] > 1;
        // top and bottom are flipped because OpenGL uses 0,0 as bottom left
        let cvt_screen_coord = |normalized| normalized * 2.0 - 1.0;
        if is_modelpack {
            let seg = &segmentation[0];
            let dst_roi = RegionOfInterest {
                left: cvt_screen_coord(seg.xmin),
                top: cvt_screen_coord(seg.ymax),
                right: cvt_screen_coord(seg.xmax),
                bottom: cvt_screen_coord(seg.ymin),
            };
            // A TensorDyn is contiguous by construction, so unlike the former
            // Array3 there is no as_standard_layout() copy to make first.
            let segment = seg.segmentation.as_u8().ok_or(Error::Internal(
                "segmentation must be a U8 tensor".to_owned(),
            ))?;
            let segment_map = segment.map_read()?;
            let slice = segment_map.as_slice();

            self.render_modelpack_segmentation(
                dst_roi,
                slice,
                [
                    seg.segmentation.shape()[0],
                    seg.segmentation.shape()[1],
                    seg.segmentation.shape()[2],
                ],
            )?;
        } else {
            // Hoist program bind, texture bind, and texture parameter
            // configuration out of the per-detection loop. These never
            // change between masks, so a single setup call replaces
            // ~5×N redundant GL state calls.
            self.setup_yolo_segmentation_pass();

            for (idx, (seg, det)) in segmentation.iter().zip(detect).enumerate() {
                let color_index = color_mode.index(idx, det.label);
                let dst_roi = RegionOfInterest {
                    left: cvt_screen_coord(seg.xmin),
                    top: cvt_screen_coord(seg.ymax),
                    right: cvt_screen_coord(seg.xmax),
                    bottom: cvt_screen_coord(seg.ymin),
                };

                let segment = seg.segmentation.as_u8().ok_or(Error::Internal(
                    "segmentation must be a U8 tensor".to_owned(),
                ))?;
                let segment_map = segment.map_read()?;
                let slice = segment_map.as_slice();

                self.render_yolo_segmentation(
                    dst_roi,
                    slice,
                    [seg.segmentation.shape()[0], seg.segmentation.shape()[1]],
                    color_index,
                )?;
            }
        }

        edgefirst_gl::disable(edgefirst_gl::gl::BLEND);
        Ok(())
    }

    /// Compile a GLES 3.1 compute shader program from source.
    fn compile_compute_program(source: &str) -> Result<u32, Error> {
        unsafe {
            let cs = edgefirst_gl::gl::CreateShader(edgefirst_gl::gl::COMPUTE_SHADER);
            if super::shaders::compile_shader_from_str(cs, source, "proto_repack_compute").is_err()
            {
                edgefirst_gl::gl::DeleteShader(cs);
                return Err(Error::OpenGl("compute shader compile failed".into()));
            }

            let program = edgefirst_gl::gl::CreateProgram();
            edgefirst_gl::gl::AttachShader(program, cs);
            edgefirst_gl::gl::LinkProgram(program);

            let mut linked: i32 = 0;
            edgefirst_gl::gl::GetProgramiv(program, edgefirst_gl::gl::LINK_STATUS, &mut linked);
            edgefirst_gl::gl::DeleteShader(cs);

            if linked == 0 {
                let mut log_len = 0;
                edgefirst_gl::gl::GetProgramiv(
                    program,
                    edgefirst_gl::gl::INFO_LOG_LENGTH,
                    &mut log_len,
                );
                let mut log_buf: Vec<u8> = vec![0; log_len as usize];
                edgefirst_gl::gl::GetProgramInfoLog(
                    program,
                    log_len,
                    std::ptr::null_mut(),
                    log_buf.as_mut_ptr() as *mut std::ffi::c_char,
                );
                let msg = String::from_utf8_lossy(&log_buf);
                edgefirst_gl::gl::DeleteProgram(program);
                return Err(Error::OpenGl(format!("compute program link failed: {msg}")));
            }
            Ok(program)
        }
    }

    /// Ensure the shared proto `GL_TEXTURE_2D_ARRAY` uses immutable storage and
    /// is recreated when dimensions or internal format change.
    #[allow(clippy::too_many_arguments)]
    /// Ensure `proto_texture` is an immutable-storage (`TexStorage3D`) array
    /// of exactly `(w, h, layers, internal_fmt)`, recreating the texture
    /// object on any change, and bind it on `TEXTURE0`. Returns `true` when
    /// recreated (sampler params reset with the object and must be
    /// re-applied by the caller).
    ///
    /// Immutable storage is what makes the compute path's
    /// `BindImageTexture` legal — ES 3.1 requires it, and `imageStore` into
    /// a `TexImage3D`-allocated texture silently writes nowhere on
    /// conformant drivers (Vivante and Mali both rendered garbage masks).
    /// Recreate-on-change is what keeps the `(dims, internal_fmt)` gate
    /// honest when renders alternate proto dtypes on one processor: the
    /// previous `TexImage3D` scheme left `proto_tex_dims` stale after a
    /// float upload re-allocated the shared texture, so the next int8
    /// upload `TexSubImage3D`'d into an R32F allocation → GL_INVALID_VALUE
    /// (0x501). Both found by the proto churn/compute regression tests.
    fn ensure_proto_texture(
        &mut self,
        target: u32,
        internal_fmt: u32,
        w: usize,
        h: usize,
        layers: usize,
    ) -> bool {
        Self::ensure_immutable_tex_array(
            &mut self.proto_texture,
            &mut self.proto_tex_dims,
            target,
            internal_fmt,
            w,
            h,
            layers,
        )
    }

    /// The shared immutable-array allocation gate behind
    /// [`Self::ensure_proto_texture`] — also used by the two-pass dequant
    /// target, which keeps its own texture/dims pair.
    fn ensure_immutable_tex_array(
        texture: &mut Texture,
        tex_dims: &mut (usize, usize, usize, u32),
        target: u32,
        internal_fmt: u32,
        w: usize,
        h: usize,
        layers: usize,
    ) -> bool {
        let dims = (w, h, layers, internal_fmt);
        edgefirst_gl::active_texture(edgefirst_gl::gl::TEXTURE0);
        if dims == *tex_dims {
            edgefirst_gl::bind_texture(target, texture.id);
            return false;
        }
        // Immutable storage cannot be re-specified: recreate the object
        // (the old one is deleted by Texture's Drop).
        *texture = Texture::new();
        edgefirst_gl::bind_texture(target, texture.id);
        unsafe {
            edgefirst_gl::gl::TexStorage3D(
                target,
                1,
                internal_fmt,
                w as i32,
                h as i32,
                layers as i32,
            );
        }
        *tex_dims = dims;
        true
    }

    /// Apply the proto texture sampler params (`filter` + CLAMP_TO_EDGE).
    /// Needed (only) after [`Self::ensure_proto_texture`] recreates the
    /// object; params are per-texture state.
    fn set_proto_tex_params(target: u32, filter: u32) {
        unsafe { super::core::set_tex_filter(target, filter) };
        edgefirst_gl::tex_parameteri(
            target,
            edgefirst_gl::gl::TEXTURE_WRAP_S,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );
        edgefirst_gl::tex_parameteri(
            target,
            edgefirst_gl::gl::TEXTURE_WRAP_T,
            edgefirst_gl::gl::CLAMP_TO_EDGE as i32,
        );
    }

    #[allow(clippy::too_many_arguments)]
    fn upload_proto_texture<T: Copy>(
        &mut self,
        target: u32,
        internal_fmt: u32,
        w: usize,
        h: usize,
        layers: usize,
        format: u32,
        dtype: u32,
        filter: u32,
        data: &[T],
    ) {
        if self.ensure_proto_texture(target, internal_fmt, w, h, layers) {
            Self::set_proto_tex_params(target, filter);
        }
        unsafe {
            edgefirst_gl::gl::TexSubImage3D(
                target,
                0,
                0,
                0,
                0,
                w as i32,
                h as i32,
                layers as i32,
                format,
                dtype,
                data.as_ptr() as *const std::ffi::c_void,
            );
        }
    }

    /// Set the `opacity` uniform on all segmentation and color shader programs.
    /// Skips GL calls entirely when opacity hasn't changed since the last call.
    fn set_opacity_uniform(&mut self, opacity: f32) -> Result<(), Error> {
        if (opacity - self.cached_opacity).abs() < f32::EPSILON {
            return Ok(());
        }
        for program in [
            &self.color_program,
            &self.segmentation_program,
            &self.instanced_segmentation_program,
            &self.proto_segmentation_program,
            &self.proto_segmentation_int8_nearest_program,
            &self.proto_segmentation_int8_bilinear_program,
            &self.proto_segmentation_f32_program,
        ] {
            program.load_uniform_1f(c"opacity", opacity)?;
        }
        self.cached_opacity = opacity;
        Ok(())
    }

    fn render_box(
        &mut self,
        dst_w: usize,
        dst_h: usize,
        detect: &[DetectBox],
        color_mode: crate::ColorMode,
    ) -> Result<(), Error> {
        unsafe {
            edgefirst_gl::gl::UseProgram(self.color_program.id);
            let rescale = |x: f32| x * 2.0 - 1.0;
            let thickness = self.box_line_width;
            for (idx, d) in detect.iter().enumerate() {
                let color_index = color_mode.index(idx, d.label);
                self.color_program
                    .load_uniform_1i(c"class_index", color_index as i32)?;
                edgefirst_gl::gl::BindBuffer(edgefirst_gl::gl::ARRAY_BUFFER, self.vertex_buffer.id);
                edgefirst_gl::gl::EnableVertexAttribArray(self.vertex_buffer.buffer_index);
                let bbox: [f32; 4] = d.bbox.into();
                let outer_box = [
                    bbox[0] - thickness / dst_w as f32,
                    bbox[1] - thickness / dst_h as f32,
                    bbox[2] + thickness / dst_w as f32,
                    bbox[3] + thickness / dst_h as f32,
                ];
                let camera_vertices: [f32; 24] = [
                    rescale(bbox[0]),
                    rescale(bbox[3]),
                    0., // bottom left
                    rescale(bbox[2]),
                    rescale(bbox[3]),
                    0., // bottom right
                    rescale(bbox[2]),
                    rescale(bbox[1]),
                    0., // top right
                    rescale(bbox[0]),
                    rescale(bbox[1]),
                    0., // top left
                    rescale(outer_box[0]),
                    rescale(outer_box[3]),
                    0., // bottom left
                    rescale(outer_box[2]),
                    rescale(outer_box[3]),
                    0., // bottom right
                    rescale(outer_box[2]),
                    rescale(outer_box[1]),
                    0., // top right
                    rescale(outer_box[0]),
                    rescale(outer_box[1]),
                    0., // top left
                ];
                edgefirst_gl::gl::BufferData(
                    edgefirst_gl::gl::ARRAY_BUFFER,
                    (size_of::<f32>() * camera_vertices.len()) as isize,
                    camera_vertices.as_ptr() as *const c_void,
                    edgefirst_gl::gl::DYNAMIC_DRAW,
                );

                let vertices_index: [u32; 10] = [0, 1, 5, 2, 6, 3, 7, 0, 4, 5];
                edgefirst_gl::gl::DrawElements(
                    edgefirst_gl::gl::TRIANGLE_STRIP,
                    vertices_index.len() as i32,
                    edgefirst_gl::gl::UNSIGNED_INT,
                    vertices_index.as_ptr() as *const c_void,
                );
            }
        }
        check_gl_error(function!(), line!())?;
        Ok(())
    }

    /// Report the float render support that this processor instance should
    /// advertise.  Delegates to [`float_render_support`].
    /// Whether the GPU is a Verisilicon/Vivante core (GL_RENDERER). Used by
    /// tests to gate properties that only hold on Vivante's NV12 path (e.g. the
    /// contiguous-vs-multiplane equality, which splits Path A/B off Vivante).
    pub(super) fn is_vivante(&self) -> bool {
        self.is_vivante
    }

    pub(super) fn supported_render_dtypes(&self) -> crate::RenderDtypeSupport {
        float_render_support(
            self.is_vivante,
            self.float_import_refused(),
            self.supports_f32_color,
            self.supports_f16_color,
        )
    }

    /// Fused NV12/NV16/NV24 → zero-copy float destination: two GPU passes
    /// under one call with a **GPU-resident intermediate** — the pixel path is
    /// zero-copy src → GPU → texture → GPU → zero-copy dst, never touching
    /// host memory. Pass 1 renders the YUV source with the caller's full
    /// geometry (resize, crop, letterbox) into the shared intermediate
    /// RGBA8 texture at destination resolution (the same texture the
    /// packed-RGB and Vivante planar two-passes use); pass 2 packs that
    /// texture 1:1 into the destination `path` names. The model-input
    /// convert previously only the legacy macOS backend offered — now
    /// portable (Linux DMA-BUF f16 targets and Windows float textures
    /// included).
    #[allow(clippy::too_many_arguments)]
    fn convert_nv_to_float_two_pass(
        &mut self,
        src: &TensorDyn,
        dst: &mut TensorDyn,
        path: FloatRenderPath,
        rotation: crate::Rotation,
        flip: Flip,
        crop: ResolvedCrop,
        convert_span: &tracing::Span,
    ) -> crate::Result<()> {
        // Parity with the float render paths: rotation/flip stay on the CPU
        // fallback until the fused path grows an oracle for them (pass 1
        // could render them, but untested behavior must not silently flip
        // backend).
        if rotation != crate::Rotation::None || flip != Flip::None {
            return Err(crate::Error::NotSupported(
                "GL fused NV→float: rotation/flip not supported; using CPU fallback".to_string(),
            ));
        }
        let src_u8 = src.as_u8().ok_or(Error::NotAnImage)?;
        let src_fmt = src.format().ok_or(Error::NotAnImage)?;
        let dst_w = dst.width().ok_or(Error::NotAnImage)?;
        let dst_h = dst.height().ok_or(Error::NotAnImage)?;
        let _span =
            tracing::trace_span!("image.convert.gl.nv_to_planar_float", dst_w, dst_h).entered();

        // ── Pass 1: NV → RGBA with the caller's full geometry, into the
        // shared intermediate texture (GPU-only; no tensor, no import) ──
        self.ensure_packed_rgb_intermediate(dst_w, dst_h)?;
        self.packed_rgb_fbo.bind();
        unsafe {
            edgefirst_gl::gl::FramebufferTexture2D(
                edgefirst_gl::gl::FRAMEBUFFER,
                edgefirst_gl::gl::COLOR_ATTACHMENT0,
                edgefirst_gl::gl::TEXTURE_2D,
                self.packed_rgb_intermediate_tex.id,
                0,
            );
            check_gl_error(function!(), line!())?;
            edgefirst_gl::gl::Viewport(0, 0, dst_w as i32, dst_h as i32);
        }
        // Pass 1 must NOT glFinish (convert_to's standalone-boundary sync):
        // same-context command ordering already guarantees pass 2 samples
        // the finished intermediate; the convert syncs once at pass 2's
        // fence. The flag restores before `?` so an error cannot leak
        // defer state.
        let saved_defer = self.defer_finish;
        self.defer_finish = true;
        let pass1 = self.convert_to_dims(
            src_u8,
            src_fmt,
            dst_w,
            dst_h,
            None,
            PixelFormat::Rgba,
            false,
            rotation,
            flip,
            crop,
            convert_span,
        );
        self.defer_finish = saved_defer;
        pass1?;

        // ── Pass 2: 1:1 pack of the intermediate into the zero-copy float
        // destination. Pass 1 already placed the content band at destination
        // geometry, so pass 2 samples its letterbox rectangle 1:1 from the
        // same rectangle of the intermediate (re-applying the crop's scaling
        // would letterbox a second time, the PR #107 bug class) and writes the
        // pad outside it, which is what an output-domain pad needs.
        let (mut src_rect_uv, mut dst_rect_px, mut pad_color) =
            super::core::float_crop_uniforms(&ResolvedCrop::no_crop(), dst_w, dst_h, dst_w, dst_h)?;
        // The pixel pad in sampler units; a mapped convert's `FloatNorm::pad`
        // replaces it in `draw_float_quad`.
        if let Some(c) = crop.dst_color {
            pad_color = c.map(|v| v as f32 / 255.0);
        }
        if let Some(r) = crop.dst_rect {
            dst_rect_px = [r.left as f32, r.top as f32, r.width as f32, r.height as f32];
            src_rect_uv = [
                r.left as f32 / dst_w as f32,
                r.top as f32 / dst_h as f32,
                r.width as f32 / dst_w as f32,
                r.height as f32 / dst_h as f32,
            ];
        }
        // The intermediate texture is exactly the pass-1 destination.
        let src_extent =
            super::render::sample_clamp_rect((dst_w, dst_h), super::render::ImportMap::WHOLE);
        self.render_float_to_zero_copy_tail(
            self.packed_rgb_intermediate_tex.id,
            src_rect_uv,
            src_extent,
            dst_rect_px,
            pad_color,
            dst,
            path,
            convert_span,
        )
    }

    /// Release per-pass platform texture attachments — called by the
    /// dispatch wrapper after each message whose GPU work has synced
    /// (no-op while a deferred batch still owes its flush, and on
    /// platforms with persistent bindings).
    pub(super) fn end_gpu_pass_if_synced(&self) {
        if !self.pending_flush {
            Platform::end_gpu_pass(&self.gl_context);
        }
    }

    /// Platform hook run by the dispatch wrapper before every message —
    /// see [`super::platform::GlPlatform::begin_gpu_pass`]. A no-op
    /// everywhere except ANGLE/D3D11, which must be told this context is
    /// the one about to issue commands.
    pub(super) fn begin_gpu_pass(&self) {
        Platform::begin_gpu_pass(&self.gl_context);
    }

    /// Whether this driver's DMA-BUF import accepts a plane offset that is
    /// not [`DMA_IMPORT_OFFSET_ALIGN`]-byte aligned and then reads from the
    /// wrong place, with no EGL error to catch: Mali and Adreno.
    /// Such an offset has to be predicted and routed to the upload path.
    pub(super) fn misplaces_unaligned_offsets(&self) -> bool {
        self.is_mali || self.is_adreno
    }

    /// Whether every float destination GL could serve is a DMA-BUF import
    /// this driver refuses: Adreno imports no float DMA-BUF format, and on a
    /// zero-copy transfer backend every float destination is such an import.
    fn float_import_refused(&self) -> bool {
        self.is_adreno && self.gl_context.transfer_backend.is_zero_copy()
    }

    /// The `glTexImage2D` internal format for a GL-owned render target whose
    /// client format is `format`. Adreno leaves a framebuffer whose colour
    /// attachment has the unsized `GL_RED` internal format incomplete
    /// (`GL_FRAMEBUFFER_INCOMPLETE_ATTACHMENT`, so every draw into a Grey or
    /// planar target fails `GL_INVALID_FRAMEBUFFER_OPERATION`); the sized
    /// `GL_R8`, which ES 3.0 lists as colour-renderable, is complete.
    fn render_internal_format(&self, format: u32) -> i32 {
        if self.is_adreno && format == edgefirst_gl::gl::RED {
            edgefirst_gl::gl::R8 as i32
        } else {
            format as i32
        }
    }

    /// Assemble the immutable capability surface for this processor.
    /// Captured ONCE by the dispatch wrapper at worker startup (before its
    /// message loop) — `serialize_gl` is the Vivante/galcore process-wide
    /// serialization requirement; see `PlatformCaps` in `platform/mod.rs`.
    pub(super) fn platform_caps(&self) -> super::platform::PlatformCaps {
        super::platform::PlatformCaps {
            transfer_backend: self.gl_context.transfer_backend,
            render_dtypes: self.supported_render_dtypes(),
            // Full per-message serialization where concurrent GL across
            // contexts is unsafe — see `requires_full_serialization`.
            // `software` is always false here: software renderers are
            // rejected in `new` before a processor exists.
            serialize_gl: requires_full_serialization(RendererTraits {
                vivante: self.is_vivante(),
                mali: self.is_mali,
                software: false,
                virtual_gpu: self.is_virtual_gpu,
                angle: self.is_angle,
                adreno: self.is_adreno,
            }),
            external_oes: Platform::EXTERNAL_OES,
            native_fence_sync: Platform::native_fence_sync(&self.gl_context),
            has_bgra: self.has_bgra,
        }
    }
}

#[cfg(test)]
#[cfg_attr(coverage_nightly, coverage(off))]
mod tests {
    use super::{
        pack_row_length, padded_readback_bytes, plan_pbo_readback, resolve_egl_cache_capacity,
        should_reject_software_gl, spread_rows, unpack_row_length, Error,
        DEFAULT_EGL_CACHE_CAPACITY,
    };

    /// The measured Mali-G310 crossover: Y2Y for 720p and 1080p into 640x640,
    /// the shader-filtered program for 4K into 640x640.
    #[test]
    fn y2y_pays_off_below_ten_source_pixels_per_output_pixel() {
        let out = 640 * 640;
        assert!(super::y2y_pays_off(1280 * 720, out));
        assert!(super::y2y_pays_off(1920 * 1080, out));
        assert!(!super::y2y_pays_off(3840 * 2160, out));
        assert!(super::y2y_pays_off(3840 * 2160, 1280 * 1280));
    }

    /// Every combination of what a draw can bind maps to one sampling: an
    /// upload or a bound chroma view filters in hardware, an import without
    /// one takes Y2Y where it is available, and the shader blend otherwise.
    #[test]
    fn nv_sampling_choice_covers_every_binding() {
        use super::{NvSampling, NvSamplingInputs};
        for bits in 0u8..32 {
            let inputs = NvSamplingInputs {
                bilinear: bits & 1 != 0,
                hw_filter: bits & 2 != 0,
                imported: bits & 4 != 0,
                chroma_view: bits & 8 != 0,
                y2y: bits & 16 != 0,
            };
            let expected = if !inputs.bilinear {
                NvSampling::Single
            } else if !inputs.hw_filter {
                NvSampling::Shader
            } else if !inputs.imported || inputs.chroma_view {
                NvSampling::Hardware
            } else if inputs.y2y {
                NvSampling::HardwareYuv
            } else {
                NvSampling::Shader
            };
            assert_eq!(NvSampling::choose(inputs), expected, "{inputs:?}");
        }
    }

    /// The Mali case: an NV12 import whose chroma plane Mali refuses to bind.
    #[test]
    fn nv_sampling_takes_y2y_only_for_an_import_without_a_chroma_view() {
        use super::{NvSampling, NvSamplingInputs};
        let mali = NvSamplingInputs {
            bilinear: true,
            hw_filter: true,
            imported: true,
            chroma_view: false,
            y2y: true,
        };
        assert_eq!(NvSampling::choose(mali), NvSampling::HardwareYuv);
        let chroma_view = NvSamplingInputs {
            chroma_view: true,
            ..mali
        };
        assert_eq!(NvSampling::choose(chroma_view), NvSampling::Hardware);
        let opted_out = NvSamplingInputs {
            hw_filter: false,
            ..mali
        };
        assert_eq!(NvSampling::choose(opted_out), NvSampling::Shader);
        let nearest = NvSamplingInputs {
            bilinear: false,
            ..mali
        };
        assert_eq!(NvSampling::choose(nearest), NvSampling::Single);
    }

    /// The Y2Y draw's ROI is the crop's true edges in texture coordinates,
    /// flipped vertically like every other external-sampler ROI.
    #[test]
    fn nv_sample_rect_roi_maps_the_crop_edges() {
        let rect = super::NvSampleRect::new(
            Some(crate::Rect::new(160, 90, 960, 540)),
            None,
            (1280, 720),
            (640, 640),
            crate::Rotation::None,
        );
        let roi = rect.roi(1280, 720);
        assert_eq!(roi.left, 0.125);
        assert_eq!(roi.right, 0.875);
        assert_eq!(roi.top, 0.875);
        assert_eq!(roi.bottom, 0.125);

        let whole =
            super::NvSampleRect::new(None, None, (1280, 720), (640, 640), crate::Rotation::None)
                .roi(1280, 720);
        assert_eq!(whole.uv_bounds(), [0.0, 0.0, 1.0, 1.0]);
    }

    /// The NV matrix follows the tensor's colorimetry and fills a missing axis
    /// from the SD/HD height heuristic.
    #[test]
    fn nv_colorimetry_resolves_missing_axes_by_height() {
        use edgefirst_tensor::{ColorEncoding, ColorRange, Colorimetry};
        assert_eq!(
            super::nv_colorimetry(None, Some(720)),
            (ColorEncoding::Bt709, ColorRange::Limited)
        );
        assert_eq!(
            super::nv_colorimetry(None, Some(480)),
            (ColorEncoding::Bt601, ColorRange::Limited)
        );
        let full_601 = Colorimetry {
            encoding: Some(ColorEncoding::Bt601),
            range: Some(ColorRange::Full),
            ..Default::default()
        };
        assert_eq!(
            super::nv_colorimetry(Some(full_601), Some(1080)),
            (ColorEncoding::Bt601, ColorRange::Full)
        );
    }

    /// A tight destination is the common case and must not be touched: the
    /// read already landed each row where it belongs.
    #[test]
    fn spread_rows_leaves_a_tight_destination_alone() {
        let mut buf: Vec<u8> = (0..12).collect();
        let before = buf.clone();
        spread_rows(&mut buf, 4, 3, 3);
        assert_eq!(buf, before, "a tight pitch is a no-op");
        // A pitch under a row is refused by the caller; here it is inert
        // rather than a panic or a backwards move.
        spread_rows(&mut buf, 4, 3, 2);
        assert_eq!(buf, before, "a pitch below the row is a no-op");
    }

    /// Nothing to move with fewer than two rows, and a zero row count must not
    /// underflow the reverse range.
    #[test]
    fn spread_rows_handles_zero_and_one_row() {
        let mut empty: Vec<u8> = Vec::new();
        spread_rows(&mut empty, 0, 3, 8);
        assert!(empty.is_empty());

        let mut one = vec![1u8, 2, 3, 0, 0, 0, 0, 0];
        let before = one.clone();
        spread_rows(&mut one, 1, 3, 8);
        assert_eq!(one, before, "row 0 already starts at offset 0");
    }

    /// The move itself: rows go back to front, so a row's destination never
    /// lands on a row that has not moved yet.
    #[test]
    fn spread_rows_places_each_row_at_the_pitch() {
        let (rows, tight, stride) = (4usize, 3usize, 5usize);
        // One distinct byte per row, tightly packed, then the padded span.
        let mut buf = vec![0u8; (rows - 1) * stride + tight];
        for y in 0..rows {
            buf[y * tight..y * tight + tight].fill(b'a' + y as u8);
        }
        spread_rows(&mut buf, rows, tight, stride);
        for y in 0..rows {
            assert_eq!(
                &buf[y * stride..y * stride + tight],
                &[b'a' + y as u8; 3],
                "row {y} did not land at offset {}",
                y * stride
            );
        }
    }

    #[test]
    fn padded_readback_bytes_reports_only_a_padded_span() {
        // Tight, and shorter-than-tight: nothing to reserve beyond the read.
        assert_eq!(padded_readback_bytes(4, 3, 3), None);
        assert_eq!(padded_readback_bytes(4, 3, 2), None);
        // No rows means no span at all, whatever the pitch.
        assert_eq!(padded_readback_bytes(0, 3, 8), None);
        // Padded: every row but the last costs a whole pitch, the last only
        // its own bytes -- the trailing padding is not addressed.
        assert_eq!(padded_readback_bytes(4, 3, 5), Some(3 * 5 + 3));
        assert_eq!(padded_readback_bytes(1, 3, 5), Some(3));
    }

    /// A tight pitch leaves the pack state alone, a pitch of whole pixels is
    /// expressed in pixels, and a pitch the pixel size does not divide is not
    /// expressible at all -- the caller then reads tight and moves the rows.
    #[test]
    fn pack_row_length_covers_only_a_padded_whole_pixel_pitch() {
        // Tight, and shorter-than-tight: nothing for GL to do.
        assert_eq!(pack_row_length(64, 64, 4), None);
        assert_eq!(pack_row_length(64, 32, 4), None);
        // RGBA at a 128-byte aligned pitch: 32 pixels per row.
        assert_eq!(pack_row_length(64, 128, 4), Some(32));
        // RGB at that same pitch: 128 is not a multiple of 3.
        assert_eq!(pack_row_length(48, 128, 3), None);
        // A single-byte pixel divides every pitch.
        assert_eq!(pack_row_length(16, 17, 1), Some(17));
        assert_eq!(pack_row_length(16, 17, 0), None);
    }

    /// The upload rule, which REFUSES where the pack side falls back: GL has
    /// no read-tight-and-spread for an upload, and `UNPACK_ROW_LENGTH` counts
    /// pixels, so a pitch no pixel size divides has to be declined rather
    /// than truncated. The 1024/3 case is the one the padded-RGB PBOs hit.
    #[test]
    fn unpack_row_length_refuses_a_pitch_that_is_not_whole_pixels() {
        // No recorded pitch: GL's own default, nothing to express.
        assert!(matches!(unpack_row_length(None, 64, 4, "Rgba"), Ok(0)));
        // A tight pitch resolves to the same width GL already assumes.
        assert!(matches!(unpack_row_length(Some(256), 64, 4, "Rgba"), Ok(0)));
        // RGBA at a 64-byte-aligned pitch: 80 pixels per row.
        assert!(matches!(
            unpack_row_length(Some(320), 64, 4, "Rgba"),
            Ok(80)
        ));
        // A single-byte pixel divides every pitch.
        assert!(matches!(unpack_row_length(Some(17), 16, 1, "Grey"), Ok(17)));
        // RGB at a 64-byte-aligned pitch: 3 does not divide 1024. Truncating
        // would give 341 px = 1023 B and shear every row by a byte.
        let Err(e) = unpack_row_length(Some(1024), 341, 3, "Rgb") else {
            panic!("a pitch that is not a whole number of pixels must be refused");
        };
        assert!(
            matches!(e, Error::NotSupported(ref m) if m.contains("1024") && m.contains("Rgb")),
            "unexpected error: {e:?}"
        );
        // Likewise an RGBA pitch 4 does not divide -- the float PBO arm's case.
        assert!(matches!(
            unpack_row_length(Some(1026), 256, 4, "RGBA"),
            Err(Error::NotSupported(_))
        ));
        // A zero pixel size cannot describe anything.
        assert!(matches!(
            unpack_row_length(Some(16), 16, 0, "Rgba"),
            Err(Error::NotSupported(_))
        ));
    }

    /// The planner is the one place a PBO readback decides what it may write,
    /// so each refusal is pinned: a pitch shorter than a row, a destination
    /// that is a sub-region of somebody else's buffer, and a PBO too small
    /// for the rows at their pitch. The accepted cases carry the three
    /// routes: tight, whole-texel pitch, and a pitch no texel size divides.
    #[test]
    fn plan_pbo_readback_refuses_what_it_cannot_place() {
        // RGBA8 64 wide: 256 B tight.
        let tight = plan_pbo_readback(256, false, 0, 256 * 8, 64, 8, 4).expect("tight");
        assert_eq!((tight.stride, tight.tight_row), (256, 256));
        assert_eq!(tight.needed, 256 * 8, "a tight read fills every row");
        assert_eq!(tight.row_length, None, "GL already lands tight rows");

        // A whole-texel pitch is expressed in the pack state, and only the
        // last row's own bytes are needed past the final pitch step.
        let padded = plan_pbo_readback(320, false, 0, 320 * 8, 64, 8, 4).expect("padded");
        assert_eq!(padded.row_length, Some(80));
        assert_eq!(padded.needed, 320 * 7 + 256);

        // A pitch the texel size does not divide: read tight, spread after.
        let odd = plan_pbo_readback(257, false, 0, 257 * 8, 64, 8, 4).expect("odd pitch");
        assert_eq!(odd.row_length, None);
        assert_eq!(odd.needed, 257 * 7 + 256);

        // F16 NCHW: 8-byte texels, so a 4-byte pad is not expressible either.
        assert_eq!(
            plan_pbo_readback(132, false, 0, 1 << 16, 16, 12, 8)
                .expect("f16 plane row")
                .row_length,
            None
        );
        assert_eq!(
            plan_pbo_readback(136, false, 0, 1 << 16, 16, 12, 8)
                .expect("f16 plane row")
                .row_length,
            Some(17)
        );

        // A pitch under one row describes no destination this can fill.
        assert!(plan_pbo_readback(255, false, 0, 1 << 16, 64, 8, 4).is_err());
        // A view or a plane offset means the rows do not start at byte 0 of
        // the buffer, which is the only place the readback can write.
        assert!(plan_pbo_readback(256, true, 0, 1 << 16, 64, 8, 4).is_err());
        assert!(plan_pbo_readback(256, false, 64, 1 << 16, 64, 8, 4).is_err());
        // One byte short of the span the rows occupy.
        assert!(plan_pbo_readback(320, false, 0, 320 * 7 + 255, 64, 8, 4).is_err());
    }

    #[test]
    fn cache_capacity_config_beats_environment() {
        // The precedence that matters: an embedder that measured its own pool
        // must not be silently overridden by a stray env var in a deployment.
        assert_eq!(resolve_egl_cache_capacity(Some(4), Some("64")), 4);
    }

    #[test]
    fn cache_capacity_falls_back_through_env_to_default() {
        assert_eq!(resolve_egl_cache_capacity(None, Some("64")), 64);
        assert_eq!(
            resolve_egl_cache_capacity(None, None),
            DEFAULT_EGL_CACHE_CAPACITY
        );
    }

    #[test]
    fn cache_capacity_rejects_zero_and_garbage_at_both_levels() {
        // A zero-capacity cache would evict every entry it inserted, so zero
        // is refused wherever it comes from and the next source is consulted.
        assert_eq!(resolve_egl_cache_capacity(Some(0), Some("32")), 32);
        assert_eq!(
            resolve_egl_cache_capacity(Some(0), Some("0")),
            DEFAULT_EGL_CACHE_CAPACITY
        );
        assert_eq!(
            resolve_egl_cache_capacity(None, Some("plenty")),
            DEFAULT_EGL_CACHE_CAPACITY
        );
        assert_eq!(
            resolve_egl_cache_capacity(None, Some("-1")),
            DEFAULT_EGL_CACHE_CAPACITY
        );
    }

    // The override env reader (`software_gl_override_enabled`) is a thin
    // `var_os == "1"` wrapper; it is exercised end-to-end by the GL-init path
    // on the Mesa-llvmpipe coverage lane. The decision logic below is the part
    // worth pinning in a pure unit test.

    #[test]
    fn software_gl_rejected_by_default() {
        // Software renderer, no override → reject (caller falls back to CPU).
        assert!(should_reject_software_gl(true, false));
    }

    #[test]
    fn software_gl_allowed_with_override() {
        // Software renderer + override → do not reject (CI coverage path).
        assert!(!should_reject_software_gl(true, true));
    }

    #[test]
    fn hardware_gl_never_rejected() {
        // A hardware renderer is never rejected, override or not.
        assert!(!should_reject_software_gl(false, false));
        assert!(!should_reject_software_gl(false, true));
    }

    // Real GL_RENDERER strings from the fleet: classification drives the
    // Vivante workarounds, the software-GL rejection, and the Full
    // serialization policy (Vivante + virtualized GPUs + ANGLE).
    #[test]
    fn classify_renderer_fleet_strings() {
        use super::{classify_renderer, RendererTraits};
        let real_gpu = RendererTraits::default();

        // imx8mp (Vivante GC7000UL)
        let t = classify_renderer("Vivante GC7000UL");
        assert!(t.vivante && !t.software && !t.virtual_gpu && !t.angle && !t.mali);
        // Apple Silicon via ANGLE (developer machines) — a REAL GPU, not
        // paravirtual, but still ANGLE and still loses per-draw state under
        // concurrent GL.
        let t = classify_renderer(
            "ANGLE (Apple, ANGLE Metal Renderer: Apple M2 Max, \
             Version 26.4.1 (Build 25E253))",
        );
        assert!(t.angle && !t.virtual_gpu && !t.software && !t.vivante);
        // Mali: plain hardware for the serialization policy, but carries the
        // `mali` trait that gates the unaligned-source-offset decline (#165).
        assert_eq!(
            classify_renderer("Mali-G310"),
            RendererTraits {
                mali: true,
                ..RendererTraits::default()
            }
        );
        assert_eq!(
            classify_renderer("Mali-G52"),
            RendererTraits {
                mali: true,
                ..RendererTraits::default()
            }
        );
        // V3D / Tegra: plain hardware, the P0-validated parallel set, and NOT
        // Mali. V3D was measured importing an unaligned source offset
        // correctly (#165); Tegra/Orin is unmeasured — that board has no DMA
        // heap, so no DMA-BUF source can be built on it to test.
        assert_eq!(classify_renderer("V3D 7.1"), real_gpu);
        // Qualcomm Adreno (IQ-9075, proprietary KGSL driver).
        assert_eq!(
            classify_renderer("Adreno (TM) 663"),
            RendererTraits {
                adreno: true,
                ..RendererTraits::default()
            }
        );
        assert_eq!(
            classify_renderer("NVIDIA Tegra Orin (nvgpu)/integrated"),
            real_gpu
        );
        // Mesa software rasterizer (CI coverage lane)
        let t = classify_renderer("llvmpipe (LLVM 15.0.7, 256 bits)");
        assert!(t.software && !t.vivante && !t.virtual_gpu && !t.angle);
        // Windows: ANGLE over Direct3D 11 on a real GPU — ANGLE, not software.
        let t = classify_renderer(
            "ANGLE (NVIDIA, NVIDIA GeForce RTX 3070 (0x00002484) Direct3D11 vs_5_0 ps_5_0, \
             D3D11-32.0.16.1656)",
        );
        assert!(t.angle && !t.software && !t.virtual_gpu && !t.vivante);
        // Windows: ANGLE over D3D11 WARP (GPU-less CI runner) — ANGLE and software.
        let t = classify_renderer(
            "ANGLE (Microsoft, Microsoft Basic Render Driver Direct3D11 vs_5_0 ps_5_0, \
             D3D11-10.0.26100.1)",
        );
        assert!(t.angle && t.software && !t.virtual_gpu && !t.vivante);
        // GitHub macOS runner: virtualized Metal — concurrent GL across
        // contexts mis-renders there; must select the Full policy.
        let t = classify_renderer(
            "ANGLE (Apple, ANGLE Metal Renderer: Apple Paravirtual device, \
             Version 15.7.7 (Build 24G720))",
        );
        assert!(t.virtual_gpu && t.angle && !t.software && !t.vivante);
    }

    // The plane-offset rule that decides whether a Mali source DMA-BUF is
    // imported or uploaded. The offsets are the ones measured on i.MX 95
    // (issue #165): 32 and 2080 sampled zeros; 64, 256 and 2048 sampled
    // correctly, and offset 0 is the whole-image control, not a window.
    // The offset rule itself is unchanged by issue #170: these are still the
    // offsets Mali samples zeros from, and `rejects_unaligned_import_offset` is
    // still the predicate. What changed is which formats are asked.
    #[test]
    fn mali_declines_only_unaligned_source_offsets() {
        use super::rejects_unaligned_import_offset as rejects;

        // Mali, unaligned — declined so the upload path takes the source.
        assert!(rejects(true, 32));
        assert!(rejects(true, 2080));
        // Mali, aligned — imported, as measured.
        assert!(!rejects(true, 0));
        assert!(!rejects(true, 64));
        assert!(!rejects(true, 2048));
        // Every other driver imports any offset; the rule must not touch them.
        assert!(!rejects(false, 32));
        assert!(!rejects(false, 2080));
        // 256 was measured too, and is the RGBA test's `(0, 1)` origin.
        assert!(!rejects(true, 256));
    }

    // Which imports still reach that rule. A packed source the fold rebases
    // presents an aligned base and must NOT be declined -- declining it is
    // one regression this test exists to catch, because it costs the zero
    // copy silently and every pixel still comes out right through the
    // upload. Exempting one the fold could NOT move is the other, and that
    // one comes back black, which is why the exemption is keyed on the
    // resolved offset rather than on the format.
    #[cfg(target_os = "linux")]
    #[test]
    fn mali_declines_the_imports_the_fold_could_not_move() {
        use super::super::dma_import::resolve_source_plane0;
        use super::{PixelFormat, DMA_IMPORT_OFFSET_ALIGN};

        // Exactly the question the gate asks, through the same resolver
        // the import is built from -- not a mirror of it.
        let aligned = |fmt, w, pitch, off| {
            resolve_source_plane0(fmt, w, pitch, off)
                .0
                .is_multiple_of(DMA_IMPORT_OFFSET_ALIGN)
        };

        // Rebased onto an aligned base: exempt. A 16-pixel view 8 pixels
        // into a 256-byte-pitched RGBA parent, at the offset i.MX 95
        // sampled zeros from.
        assert!(aligned(PixelFormat::Rgba, 16, 256, 2080));
        assert!(aligned(PixelFormat::Bgra, 16, 256, 32));
        // Already aligned: exempt, and untouched.
        assert!(aligned(PixelFormat::Rgba, 64, 256, 2048));
        assert!(aligned(PixelFormat::Nv12, 64, 64, 0));
        // Packed, but the fold cannot move it -- these are the two shapes
        // that would come back black if the exemption were keyed on the
        // format. A whole 64-wide RGBA tensor at a `set_plane_offset`
        // window has a tight 256-byte pitch with no room to widen; a
        // 100-wide RGB surface has a 64-padded 320-byte stride that is not
        // a multiple of 3, so row 1 does not start on a whole pixel.
        assert!(!aligned(PixelFormat::Rgba, 64, 256, 32));
        assert!(!aligned(PixelFormat::Rgb, 16, 320, 323));
        // Never rebased, so still declined at an unaligned offset: NV12's
        // second plane carries an offset of its own and the R8 import's
        // pitch is its width; YUYV/VYUY carry a macropixel phase a texel
        // shift would break; planar RGB stacks its planes by row.
        for fmt in [
            PixelFormat::Nv12,
            PixelFormat::Nv16,
            PixelFormat::Nv24,
            PixelFormat::Yuyv,
            PixelFormat::Vyuy,
            PixelFormat::PlanarRgb,
        ] {
            assert!(!aligned(fmt, 64, 256, 32), "{fmt:?} must not be exempt");
        }
    }

    // The offset rule is a SOURCE rule, and only Mali's. Vivante's refusal of
    // an unaligned destination is loud (`EGL_BAD_ACCESS` from
    // `eglCreateImage`) and is handled by falling back when the import fails,
    // so no predicate predicts it and no driver is gated on the destination
    // side -- Mali least of all, which was measured rendering into offset 2080
    // correctly (issue #175).
    #[test]
    fn the_offset_rule_is_a_source_rule_and_only_malis() {
        use super::rejects_unaligned_import_offset;

        assert!(
            rejects_unaligned_import_offset(true, 2080),
            "the Mali source rule covers 2080"
        );
        assert!(rejects_unaligned_import_offset(true, 32));
        assert!(!rejects_unaligned_import_offset(true, 2048));
        assert!(!rejects_unaligned_import_offset(true, 0));
        // The offsets Adreno misread on IQ-9075, against its correct control.
        assert!(rejects_unaligned_import_offset(true, 16416));
        assert!(rejects_unaligned_import_offset(true, 6176));
        assert!(!rejects_unaligned_import_offset(true, 16384));
        // A driver that places unaligned offsets correctly (V3D, Vivante
        // sources) is never declined.
        assert!(!rejects_unaligned_import_offset(false, 2080));
        assert!(!rejects_unaligned_import_offset(false, 32));
    }

    // The offset a destination import actually bases at, which is what the
    // PLACEMENT question must be asked of -- and which of the two routes is
    // being guarded. `bind_dst`'s import collapses a fresh view() to 0 however
    // far into the buffer its own bytes start; the `import_buffer_packed`
    // routes do NOT collapse and really do import at the tensor's own offset.
    // Both shapes are asserted here.
    #[test]
    fn a_view_destination_imports_at_base_zero() {
        use super::view_collapsed_dst_base as base;
        use edgefirst_tensor::ViewOrigin;

        // A fresh view: `view_origin` is Some, so the import bases at 0 -- even
        // at an unaligned byte offset like an RGBA x0 of 8 (2080 here).
        let vo = Some(ViewOrigin {
            parent_width: 64,
            parent_height: 64,
            parent_row_stride: 256,
            x: 8,
            y: 8,
        });
        assert_eq!(base(vo, Some(2080)), 0);
        // Still 0 at an aligned offset, and 0 even if the offset is absent.
        assert_eq!(base(vo, Some(2048)), 0);
        assert_eq!(base(vo, None), 0);

        // No view_origin -- rebuilt from a descriptor, or a whole tensor at a
        // foreign offset. Now the import really does base at the offset.
        assert_eq!(base(None, Some(2080)), 2080);
        assert_eq!(base(None, Some(2048)), 2048);
        // A whole tensor with no offset at all is base 0.
        assert_eq!(base(None, None), 0);

        // THE OTHER ROUTE. `import_buffer_packed` passes `plane_offset()`
        // straight to EGL with no collapse, so `convert_via_engine`'s packed
        // plan and the float paths ask the RAW offset. The two routes
        // genuinely disagree for the same tensor, which is the whole reason
        // the helper is route-specific: `dst_import_places` asks whether an
        // import will PLACE the destination correctly, and the answer differs
        // by which offset the import will actually base at.
        let raw = |plane_offset: Option<usize>| plane_offset.unwrap_or(0);
        assert_eq!(raw(Some(2080)), 2080);
        assert_ne!(base(vo, Some(2080)), raw(Some(2080)));
    }

    // The chroma-plane offset a contiguous NV12 import hands EGL, and whether
    // Mali's rule catches an unaligned one while plane 0 looks fine.
    //
    // A 64-aligned pitch makes `pitch * height` 64-aligned at EVERY height, so
    // a HAL allocation can never produce an unaligned plane 1 — which is why
    // plane 0 alone looked sufficient. It stops being sufficient for a DMA-BUF
    // adopted through `from_fd`, whose pitch is the producer's and need not be
    // padded at all: then `pitch * height` is unaligned for any height that
    // does not itself supply the missing factor of 64.
    #[test]
    fn nv12_chroma_plane_offset_is_checked_independently_of_plane_zero() {
        use super::{nv12_plane1_offset as plane1, rejects_unaligned_import_offset as rejects};

        // HAL-shaped: 64-aligned pitch, offset 0. Both planes aligned, at an
        // even height and at an odd one alike.
        assert_eq!(plane1(0, 256, 64), 16384);
        assert_eq!(plane1(0, 256, 65), 16640);
        assert!(!rejects(true, plane1(0, 256, 64)));
        assert!(!rejects(true, plane1(0, 256, 65)));

        // A foreign pitch from `from_fd`: plane 0 is aligned and plane 1 is
        // NOT. This is the case a plane-0-only check misses, and the shorter
        // the frame the likelier it is.
        assert!(!rejects(true, 0), "plane 0 looks fine");
        assert_eq!(plane1(0, 100, 3), 300);
        assert!(rejects(true, plane1(0, 100, 3)), "plane 1 must be caught");
        assert_eq!(plane1(0, 48, 5), 240);
        assert!(rejects(true, plane1(0, 48, 5)));
        assert_eq!(plane1(0, 96, 1), 96);
        assert!(rejects(true, plane1(0, 96, 1)));

        // A foreign pitch whose height DOES supply the missing factor keeps
        // plane 1 aligned and must NOT be declined — the rule is the offset's
        // alignment, not whether the pitch was padded.
        assert_eq!(plane1(0, 100, 64), 6400);
        assert!(!rejects(true, plane1(0, 100, 64)));
        assert_eq!(plane1(0, 96, 2), 192);
        assert!(!rejects(true, plane1(0, 96, 2)));

        // The luma offset carries into plane 1: aligned + aligned stays
        // aligned, and an unaligned plane 0 shifts plane 1 out of alignment
        // too (plane 0 is checked first, so the message names plane 0).
        assert_eq!(plane1(2048, 256, 64), 18432);
        assert!(!rejects(true, plane1(2048, 256, 64)));
        assert!(rejects(true, plane1(32, 256, 64)));

        // Saturating, so a nonsense geometry cannot wrap into a spuriously
        // aligned value or panic in debug.
        assert_eq!(plane1(usize::MAX, 256, 64), usize::MAX);
        assert_eq!(plane1(0, usize::MAX, 2), usize::MAX);

        // Non-Mali is untouched at every one of them.
        assert!(!rejects(false, plane1(0, 100, 3)));
        assert!(!rejects(false, plane1(0, 96, 1)));
    }

    // The serialization policy each fleet renderer selects. The parallel
    // (`LifecycleOnly`) policy is validated ONLY on Mali/V3D/Tegra; every
    // other driver family that has been measured breaks it.
    #[test]
    fn serialization_policy_per_renderer() {
        use super::{classify_renderer, requires_full_serialization};
        let policy = |r: &str| requires_full_serialization(classify_renderer(r));

        // Parallel: the P0-validated set.
        assert!(!policy("Mali-G310"));
        assert!(!policy("V3D 7.1"));
        assert!(!policy("NVIDIA Tegra Orin (nvgpu)/integrated"));

        // Serialized: driver is not thread-safe for concurrent GL.
        assert!(policy("Vivante GC7000UL"));
        // Serialized: concurrent contexts unmap foreign DMA-BUF mappings.
        assert!(policy("Adreno (TM) 663"));
        // Serialized: ANGLE on a real Apple GPU loses per-draw state under
        // concurrent GL — the regression this policy exists to prevent.
        assert!(policy(
            "ANGLE (Apple, ANGLE Metal Renderer: Apple M2 Max, \
             Version 27.0 (Build 26A5388g))"
        ));
        // Serialized: paravirtual Metal, by both traits.
        assert!(policy(
            "ANGLE (Apple, ANGLE Metal Renderer: Apple Paravirtual device, \
             Version 15.7.7 (Build 24G720))"
        ));
        // Serialized: ANGLE over Direct3D 11 (Windows) — same ANGLE rule.
        assert!(policy(
            "ANGLE (NVIDIA, NVIDIA GeForce RTX 3070 (0x00002484) Direct3D11 vs_5_0 ps_5_0, \
             D3D11-32.0.16.1656)"
        ));
    }
}