viewport_lib/renderer/

mod.rs

//! `ViewportRenderer` : the main entry point for the viewport library.
//!
//! Wraps [`ViewportGpuResources`] and provides `prepare()` / `paint()` methods
//! that take raw `wgpu` types. GUI framework adapters (e.g. the egui
//! `CallbackTrait` impl in the application crate) delegate to these methods.

#[macro_use]
mod types;
mod indirect;
mod paths;
pub use paths::{OwnedPath, PassPath, PassView};
mod picking;
pub use picking::PickRectResult;
mod prepare;
mod render;
pub mod shader_hashes;
mod shadow_debug_stats;
mod shadows;
pub mod stats;
pub use shadow_debug_stats::ShadowDebugStats;

#[cfg(test)]
mod hidden_tests;

pub use self::types::{
    AnimTrack, AtlasViewerCorner, BorderMode, CameraFrame, ClipObject, ClipShape,
    ComputeFilterItem, ComputeFilterKind, CylindricalFacing, DebugOutputMode, DebugQuantity,
    DebugVis, DecalAnimation, DecalBlendMode, DecalItem, DecalProjection, EffectsFrame,
    EmitterConfig, EnvironmentMap, FilterMode, ForceField, FrameData, GaussianSplatData,
    GaussianSplatId, GaussianSplatItem, GlyphItem, GlyphSetRefItem, GlyphType,
    GpuParticleSystemItem, GradientStop, GroundPlane, GroundPlaneMode, ImageAnchor, ImageSliceItem,
    InteractionFrame, LabelAnchor, LabelItem, LerpAnim, LicOverlay, LightKind, LightSource,
    LightingSettings, LineCap, LineJoin, LoadingBarAnchor, LoadingBarItem, MeshInstanceItem,
    NineSlice, OVERLAY_MAX_GRADIENT_STOPS, OverlayAnimation, OverlayAnimations, OverlayEasing, ParticleMeshAlign,
    OverlayFill, OverlayFrame, OverlayImageItem, OverlayPolylineItem, OverlayRectItem,
    OverlayShape, OverlayShapeItem, OverlayTextureId, PathTrack, PickId, PointCloudItem,
    PointCloudRefItem, PointRenderMode, PolylineItem, PolylineRefItem, PostProcessSettings,
    RenderCamera, RepeatMode, RibbonItem, RibbonRefItem, RulerItem, ScalarBarAnchor, ScalarBarItem,
    ScalarBarOrientation, ScatterQuality, ScatterSettings, ScatterVolumeItem, SceneEffects,
    SceneFrame, SceneRenderItem, ScreenImageItem, ShDegree, ShadowFilter, SliceAxis, SpawnShape,
    SpriteBlend, SpriteInstanceSetRefItem, SpriteItem, SpriteLitParams, SpriteNormalMode,
    SpriteOrientation, SpriteSetRefItem, SpriteSizeMode, StreamtubeItem, StreamtubeRefItem,
    SurfaceLICConfig, SurfaceSubmission, TensorGlyphItem, TensorGlyphSetRefItem, TextureTransform,
    TileMode, ToneMapping, TriangleDirection, TubeItem, TubeRefItem, VelocityDist,
    ViewportEffects, ViewportFrame, VolumeItem, VolumeMeshItem, VolumeSurfaceSliceItem,
    VolumeTransparency, aabb_wireframe_polyline, sphere_wireframe_polyline,
};

/// An opaque handle to a per-viewport GPU state slot.
///
/// Obtained from [`ViewportRenderer::create_viewport`] and passed to
/// [`ViewportRenderer::prepare_viewport`], [`ViewportRenderer::paint_viewport`],
/// and [`ViewportRenderer::render_viewport`].
///
/// The slot index is managed internally. To bind a `ViewportId` to a camera frame,
/// use [`CameraFrame::with_viewport_id`]. Single-viewport applications that use
/// the legacy [`ViewportRenderer::prepare`] / [`ViewportRenderer::paint`] API do
/// not need this type.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct ViewportId(pub(crate) usize);

use self::shadows::{compute_cascade_matrix, compute_cascade_splits};
use self::types::{INSTANCING_THRESHOLD, InstancedBatch};
use crate::resources::{
    BatchMeta, CLIP_VOLUME_MAX, CameraUniform, ClipPlanesUniform, ClipVolumeEntry,
    ClipVolumesUniform, GridUniform, InstanceAabb, InstanceData, LightsUniform, ObjectUniform,
    OutlineEdgeUniform, OutlineObjectBuffers, OutlineUniform, PickInstance, ShadowAtlasUniform,
    SingleLightUniform, SplatOutlineMaskUniform, ViewportGpuResources,
};

/// Per-viewport GPU state: uniform buffers and bind groups that differ per viewport.
///
/// Each viewport slot owns its own camera, clip planes, clip volume, shadow info,
/// and grid buffers, plus the bind groups that reference them. Scene-global
/// resources (lights, shadow atlas texture, IBL) are shared via the bind group
/// pointing to buffers on `ViewportGpuResources`.
pub(crate) struct ViewportSlot {
    pub camera_buf: wgpu::Buffer,
    pub clip_planes_buf: wgpu::Buffer,
    pub clip_volume_buf: wgpu::Buffer,
    pub shadow_info_buf: wgpu::Buffer,
    pub grid_buf: wgpu::Buffer,
    /// Camera bind group (group 0) referencing this slot's per-viewport buffers
    /// plus shared scene-global resources.
    pub camera_bind_group: wgpu::BindGroup,
    /// Grid bind group (group 0 for grid pipeline) referencing this slot's grid buffer.
    pub grid_bind_group: wgpu::BindGroup,
    /// Per-viewport HDR post-process render targets.
    ///
    /// Created lazily on first HDR render call and resized when viewport dimensions change.
    pub hdr: Option<crate::resources::ViewportHdrState>,
    /// Per-fragment debug storage buffer (group 0 binding 12). Allocated at
    /// `width * height * 16` bytes when debug_vis is active; None otherwise.
    pub debug_frag_buf: Option<wgpu::Buffer>,
    /// Viewport dimensions for which `debug_frag_buf` was allocated.
    pub debug_frag_dims: (u32, u32),

    // --- Per-viewport interaction state ---
    /// Per-frame outline buffers for selected objects, rebuilt in prepare().
    pub outline_object_buffers: Vec<OutlineObjectBuffers>,
    /// Per-frame outline buffers for selected Gaussian splat sets, rebuilt in prepare().
    pub splat_outline_buffers: Vec<crate::resources::SplatOutlineBuffers>,
    /// Indices into `volume_gpu_data` for selected volumes, rebuilt in prepare().
    pub volume_outline_indices: Vec<usize>,
    /// Indices into `glyph_gpu_data` for selected glyph sets, rebuilt in prepare().
    /// Each entry is (gpu_data_index, instance_filter): None draws all instances,
    /// Some(indices) draws only those specific instance indices.
    pub glyph_outline_indices: Vec<(usize, Option<Vec<u32>>)>,
    /// Indices into `tensor_glyph_gpu_data` for selected tensor glyph sets, rebuilt in prepare().
    pub tensor_glyph_outline_indices: Vec<(usize, Option<Vec<u32>>)>,
    /// Indices into `sprite_gpu_data` for selected sprite sets, rebuilt in prepare().
    pub sprite_outline_indices: Vec<(usize, Option<Vec<u32>>)>,
    /// Per-frame inline quad outline buffers for selected image slices, rebuilt in prepare().
    pub raw_geom_outline_buffers: Vec<crate::resources::RawGeomOutlineBuffers>,
    /// Per-frame NDC rect outline buffers for selected screen images, rebuilt in prepare().
    pub screen_rect_outline_buffers: Vec<crate::resources::ScreenRectOutlineBuffers>,
    /// Indices into `implicit_gpu_data` for selected GPU implicit items, rebuilt in prepare().
    pub implicit_outline_indices: Vec<usize>,
    /// Per-frame outline data for selected GPU marching cubes jobs, rebuilt in prepare().
    pub mc_outline_data: Vec<crate::resources::gpu_marching_cubes::McOutlineItem>,
    /// Outline items for selected streamtubes (index into streamtube_gpu_data + mask bind group).
    pub streamtube_outline_items: Vec<crate::resources::CurveMeshOutlineItem>,
    /// Outline items for selected tubes.
    pub tube_outline_items: Vec<crate::resources::CurveMeshOutlineItem>,
    /// Outline items for selected ribbons.
    pub ribbon_outline_items: Vec<crate::resources::CurveMeshOutlineItem>,
    /// Indices into polyline_gpu_data for selected user polylines.
    pub polyline_outline_indices: Vec<usize>,
    /// Per-frame x-ray buffers for selected objects, rebuilt in prepare().
    pub xray_object_buffers: Vec<(
        crate::resources::mesh_store::MeshId,
        wgpu::Buffer,
        wgpu::BindGroup,
    )>,
    /// Per-frame constraint guide line buffers, rebuilt in prepare().
    pub constraint_line_buffers: Vec<(
        wgpu::Buffer,
        wgpu::Buffer,
        u32,
        wgpu::Buffer,
        wgpu::BindGroup,
    )>,
    /// Per-frame cap geometry buffers (section view cross-section fill), rebuilt in prepare().
    pub cap_buffers: Vec<(
        wgpu::Buffer,
        wgpu::Buffer,
        u32,
        wgpu::Buffer,
        wgpu::BindGroup,
    )>,
    /// Per-frame clip plane fill overlay buffers, rebuilt in prepare().
    pub clip_plane_fill_buffers: Vec<(
        wgpu::Buffer,
        wgpu::Buffer,
        u32,
        wgpu::Buffer,
        wgpu::BindGroup,
    )>,
    /// Per-frame clip plane line overlay buffers, rebuilt in prepare().
    pub clip_plane_line_buffers: Vec<(
        wgpu::Buffer,
        wgpu::Buffer,
        u32,
        wgpu::Buffer,
        wgpu::BindGroup,
    )>,
    /// Vertex buffer for axes indicator geometry (rebuilt each frame).
    pub axes_vertex_buffer: wgpu::Buffer,
    /// Number of vertices in the axes indicator buffer.
    pub axes_vertex_count: u32,
    /// Gizmo model-matrix uniform buffer.
    pub gizmo_uniform_buf: wgpu::Buffer,
    /// Gizmo bind group (group 1: model matrix uniform).
    pub gizmo_bind_group: wgpu::BindGroup,
    /// Gizmo vertex buffer.
    pub gizmo_vertex_buffer: wgpu::Buffer,
    /// Gizmo index buffer.
    pub gizmo_index_buffer: wgpu::Buffer,
    /// Number of indices in the current gizmo mesh.
    pub gizmo_index_count: u32,

    // --- Sub-object highlight (per-viewport, generation-cached) ---
    /// Per-viewport dynamic resolution intermediate render target.
    /// `None` when render_scale == 1.0 or not yet initialised.
    pub dyn_res: Option<crate::resources::dyn_res::DynResTarget>,
    /// Per-viewport intermediate render target for the HDR eframe callback path.
    /// `None` until the first `prepare_hdr_callback` call for this viewport.
    pub hdr_callback: Option<crate::resources::dyn_res::HdrCallbackTarget>,
    /// Cached GPU data for sub-object highlight rendering.
    /// `None` when no sub-object selection is active and no volumes are selected.
    pub sub_highlight: Option<crate::resources::SubHighlightGpuData>,
    /// Version of the last sub-selection snapshot that was uploaded.
    /// `u64::MAX` forces a rebuild on the first frame.
    pub sub_highlight_generation: u64,
}

/// Retained pick state for one GPU implicit surface, built during `prepare()`.
struct GpuImplicitPickItem {
    id: u64,
    primitives: Vec<crate::resources::ImplicitPrimitive>,
    blend_mode: crate::resources::ImplicitBlendMode,
    max_steps: u32,
    step_scale: f32,
    hit_threshold: f32,
    max_distance: f32,
}

/// Retained pick state for one GPU marching cubes job, built during `prepare()`.
struct GpuMcPickItem {
    id: u64,
    isovalue: f32,
    volume_data: std::sync::Arc<crate::geometry::marching_cubes::VolumeData>,
}

/// Renderer wrapping all GPU resources and providing `prepare()` and `paint()` methods.
/// Per-viewport scene-colour resolve sampled by the refractive sprite pass.
///
/// Lazily allocated on the first frame containing a refractive sprite; resized
/// whenever the HDR target dimensions change. The bind group is rebuilt with
/// the resolve when either changes.
struct SpriteRefractionResolve {
    texture: wgpu::Texture,
    view: wgpu::TextureView,
    size: [u32; 2],
}

/// Owns the GPU pipelines and per-frame state for rendering a scene. Call
/// `prepare` once per frame to upload data, then `paint_to` (or `render`) to
/// issue draw calls.
pub struct ViewportRenderer {
    resources: ViewportGpuResources,
    /// Instanced batches prepared for the current frame. Empty when using per-object path.
    instanced_batches: Vec<InstancedBatch>,
    /// Whether the current frame uses the instanced draw path.
    use_instancing: bool,
    /// True when the device supports `INDIRECT_FIRST_INSTANCE`.
    gpu_culling_supported: bool,
    /// True when GPU-driven culling is active (supported and not disabled by the caller).
    gpu_culling_enabled: bool,
    /// GPU culling compute pipelines and frustum buffer. Created lazily on the first
    /// frame where `gpu_culling_enabled` is true and instance buffers are present.
    cull_resources: Option<indirect::CullResources>,
    /// Registered item-type plugins keyed by
    /// [`ItemTypePlugin::type_name`](crate::plugin_api::ItemTypePlugin::type_name).
    /// `init_gpu` is invoked once on registration; per-frame `prepare` and
    /// `paint` fire when a matching collection is on `SceneFrame`.
    item_type_plugins:
        std::collections::HashMap<&'static str, Box<dyn crate::plugin_api::ItemTypePlugin>>,
    /// Monotonic frame counter passed to plugin contexts.
    plugin_frame_index: u64,
    /// Performance counters from the last frame.
    last_stats: crate::renderer::stats::FrameStats,
    /// Last scene generation seen during prepare(). u64::MAX forces rebuild on first frame.
    last_scene_generation: u64,
    /// Last selection generation seen during prepare(). u64::MAX forces rebuild on first frame.
    last_selection_generation: u64,
    /// Last scene_items count seen during prepare(). usize::MAX forces rebuild on first frame.
    /// Included in cache key so that frustum-culling changes (different visible set, different
    /// count) correctly invalidate the instance buffer even when scene_generation is stable.
    last_scene_items_count: usize,
    /// Count of items that passed the instanced-path filter on the last rebuild.
    /// Used in place of has_per_frame_mutations so scenes that mix instanced and
    /// non-instanced items (e.g. one two-sided mesh + 10k static boxes) still hit
    /// the instanced batch cache on frames where the filtered set is unchanged.
    last_instancable_count: usize,
    /// Total instance count from the last rebuild. Used as a fast length check
    /// in `structure_preserved` and as `instance_count` for GPU cull dispatches.
    cached_instance_count: usize,
    /// Per-batch content hash from the last rebuild, indexed by batch position.
    /// A hash mismatch triggers a `write_buffer` for that batch; a match skips it.
    cached_instance_hashes: Vec<u64>,
    /// Cached instanced batch descriptors from last rebuild.
    cached_instanced_batches: Vec<InstancedBatch>,
    /// When true, the next cache-miss forces a full buffer upload instead of the
    /// per-batch partial-upload path. Set by `force_dirty()` and consumed once.
    force_full_upload: bool,
    /// Per-frame point cloud GPU data, rebuilt in prepare(), consumed in paint().
    point_cloud_gpu_data: Vec<crate::resources::PointCloudGpuData>,
    /// Per-frame glyph GPU data, rebuilt in prepare(), consumed in paint().
    glyph_gpu_data: Vec<crate::resources::GlyphGpuData>,
    /// Per-frame tensor glyph GPU data, rebuilt in prepare(), consumed in paint().
    tensor_glyph_gpu_data: Vec<crate::resources::TensorGlyphGpuData>,
    /// Per-frame polyline GPU data, rebuilt in prepare(), consumed in paint().
    polyline_gpu_data: Vec<crate::resources::PolylineGpuData>,
    /// Per-frame volume GPU data, rebuilt in prepare(), consumed in paint().
    volume_gpu_data: Vec<crate::resources::VolumeGpuData>,
    /// Per-frame streamtube GPU data, rebuilt in prepare(), consumed in paint().
    streamtube_gpu_data: Vec<crate::resources::StreamtubeGpuData>,
    /// Per-frame general tube GPU data, rebuilt in prepare(), consumed in paint().
    tube_gpu_data: Vec<crate::resources::StreamtubeGpuData>,
    /// Per-frame ribbon GPU data, rebuilt in prepare(), consumed in paint().
    ribbon_gpu_data: Vec<crate::resources::StreamtubeGpuData>,
    /// Indices into streamtube_gpu_data for selected streamtubes (set in prepare_scene, consumed in prepare_viewport).
    streamtube_selected_gpu_indices: Vec<usize>,
    /// Indices into tube_gpu_data for selected tubes (set in prepare_scene, consumed in prepare_viewport).
    tube_selected_gpu_indices: Vec<usize>,
    /// Indices into ribbon_gpu_data for selected ribbons (set in prepare_scene, consumed in prepare_viewport).
    ribbon_selected_gpu_indices: Vec<usize>,
    /// Indices into polyline_gpu_data for selected user polylines (set in prepare_scene, consumed in prepare_viewport).
    polyline_selected_gpu_indices: Vec<usize>,
    /// Per-frame image slice GPU data, rebuilt in prepare(), consumed in paint().
    image_slice_gpu_data: Vec<crate::resources::ImageSliceGpuData>,
    /// Per-frame volume surface slice GPU data, rebuilt in prepare(), consumed in paint().
    volume_surface_slice_gpu_data: Vec<crate::resources::VolumeSurfaceSliceGpuData>,
    /// Per-frame Surface LIC GPU data, rebuilt in prepare(), consumed in paint().
    lic_gpu_data: Vec<crate::resources::LicSurfaceGpuData>,
    /// Per-frame GPU implicit surface data, rebuilt in prepare(), consumed in paint().
    implicit_gpu_data: Vec<crate::resources::implicit::ImplicitGpuItem>,
    /// Per-frame decal GPU data, rebuilt in prepare(), consumed in paint() (D1).
    decal_gpu_data: Vec<crate::resources::decal::DecalGpuItem>,
    /// Per-frame decal exclude GPU data, rebuilt in prepare(), consumed in paint() (D5).
    decal_exclude_items: Vec<crate::resources::decal::DecalExcludeGpuItem>,
    /// Per-frame GPU marching cubes render data, rebuilt in prepare(), consumed in paint().
    mc_gpu_data: Vec<crate::resources::gpu_marching_cubes::McFrameData>,
    /// Per-frame sprite GPU data, rebuilt in prepare(), consumed in paint().
    sprite_gpu_data: Vec<crate::resources::SpriteGpuData>,
    /// Per-frame mesh-instance batches, rebuilt in prepare(), consumed in paint().
    mesh_instance_gpu_data: Vec<crate::resources::MeshInstanceGpuData>,
    /// Per-frame GPU particle systems, dispatched in prepare(), consumed in paint().
    particle_gpu_data: Vec<crate::resources::gpu_particles::ParticleFrameData>,
    /// Scene-colour resolve textures for the refractive sprite pass, indexed
    /// alongside `viewport_slots`. Lazily allocated when the first refractive
    /// sprite appears for a viewport.
    sprite_refraction_resolves: Vec<Option<SpriteRefractionResolve>>,
    /// Per-frame Gaussian splat draw data, rebuilt in prepare_viewport_internal(), consumed in paint().
    gaussian_splat_draw_data: Vec<crate::resources::GaussianSplatDrawData>,
    /// Per-frame screen-image GPU data, rebuilt in prepare(), consumed in paint().
    screen_image_gpu_data: Vec<crate::resources::ScreenImageGpuData>,
    /// Per-frame overlay image GPU data, rebuilt in prepare(), consumed in paint().
    overlay_image_gpu_data: Vec<crate::resources::ScreenImageGpuData>,
    /// Per-frame overlay label GPU data, rebuilt in prepare(), consumed in paint().
    label_gpu_data: Option<crate::resources::LabelGpuData>,
    /// Per-frame scalar bar GPU data, rebuilt in prepare(), consumed in paint().
    scalar_bar_gpu_data: Option<crate::resources::LabelGpuData>,
    /// Per-frame ruler GPU data, rebuilt in prepare(), consumed in paint().
    ruler_gpu_data: Option<crate::resources::LabelGpuData>,
    /// Per-frame loading bar GPU data, rebuilt in prepare(), consumed in paint().
    loading_bar_gpu_data: Option<crate::resources::LabelGpuData>,
    /// Per-frame overlay rect GPU data, rebuilt in prepare(), consumed in paint().
    overlay_rect_gpu_data: Option<crate::resources::LabelGpuData>,
    /// Per-frame SDF overlay shape GPU data, rebuilt in prepare(), consumed in paint().
    overlay_shape_gpu_data: Option<crate::resources::OverlayShapeGpuData>,
    /// Cached GPU textures for the backdrop blur effect (frosted glass).
    /// Recreated when the viewport size changes.
    backdrop_blur_state: Option<crate::resources::BackdropBlurState>,
    /// Per-viewport GPU state slots.
    ///
    /// Indexed by `FrameData::camera.viewport_index`. Each slot owns independent
    /// uniform buffers and bind groups for camera, clip planes, clip volume,
    /// shadow info, and grid. Slots are grown lazily in `prepare` via
    /// `ensure_viewport_slot`. There are at most 4 in the current UI.
    viewport_slots: Vec<ViewportSlot>,
    /// GPU compute filter results from the last `prepare()` call.
    ///
    /// Each entry contains a compacted index buffer + count for one filtered mesh.
    /// Consumed during `paint()` to override the mesh's default index buffer.
    /// Cleared and rebuilt each frame.
    compute_filter_results: Vec<crate::resources::ComputeFilterResult>,
    /// Per-item uniform buffers for wireframe mode. In wireframe mode multiple scene
    /// items can share the same MeshId, but each needs its own object uniform (model
    /// matrix, colour, etc.). The mesh's single `object_uniform_buf` gets overwritten
    /// by the last item prepared, so we maintain a separate pool here. Indexed in the
    /// same order as the visible scene items. Grown lazily, never shrunk.
    wireframe_uniform_bufs: Vec<wgpu::Buffer>,
    /// Bind groups corresponding to `wireframe_uniform_bufs`. Each bind group pairs
    /// the per-item uniform buffer with the mesh's fallback textures so it is
    /// compatible with the object bind group layout.
    wireframe_bind_groups: Vec<wgpu::BindGroup>,
    /// Per-scene-item uniform buffers for the per-object draw path. Multiple scene
    /// items can share the same MeshId, but each needs its own object uniform
    /// (model matrix, colour, etc.). The mesh's single `object_uniform_buf` is
    /// stomped by the last item prepared, so we maintain a parallel pool indexed
    /// by position in `scene_items`. Grown lazily, never shrunk.
    per_item_object_uniform_bufs: Vec<wgpu::Buffer>,
    /// Bind groups corresponding to `per_item_object_uniform_bufs`. Each pairs the
    /// per-item uniform buffer with the mesh's real textures, LUT, matcap, scalar
    /// buffer, etc. -- the same resources that `mesh.object_bind_group` references,
    /// just with binding 0 swapped for the per-item uniform.
    per_item_object_bind_groups: Vec<Option<wgpu::BindGroup>>,
    /// Cache keys for `per_item_object_bind_groups`. When the key matches we only
    /// write the uniform; otherwise we rebuild the bind group.
    per_item_object_cache_keys: Vec<u64>,
    /// Per-frame list of boundary mesh IDs to draw in wireframe for
    /// TransparentVolumeMeshItems with `appearance.wireframe = true`.
    /// Cleared and rebuilt each frame in prepare_scene_internal.
    tvm_wireframe_draws: Vec<crate::resources::mesh_store::MeshId>,
    /// Shared uniform buffer for TVM boundary wireframe draws (wireframe=1, model=identity).
    /// Created once on first use, reused every frame.
    tvm_wireframe_buf: Option<wgpu::Buffer>,
    /// Bind group for TVM boundary wireframe draws. Pairs `tvm_wireframe_buf` with
    /// fallback textures matching the object bind group layout.
    tvm_wireframe_bg: Option<wgpu::BindGroup>,
    /// Cascade-0 light-space view-projection matrix from the last shadow prepare.
    /// Cached here so `prepare_viewport_internal` can copy it into the ground plane uniform.
    last_cascade0_shadow_mat: glam::Mat4,
    /// Current runtime mode controlling internal default behavior.
    runtime_mode: crate::renderer::stats::RuntimeMode,
    /// Optional cap on how much main-thread time `prepare` is allowed to
    /// spend running apply closures for completed upload jobs.
    ///
    /// `None` means unbounded (apply work runs to completion in one
    /// frame). `Some(d)` spreads the cost across frames so heavy
    /// completions do not produce one fat frame; the deferred applies
    /// run on the next call to `prepare`.
    upload_budget: Option<std::time::Duration>,
    /// Active performance policy: target FPS, render scale bounds, and permitted reductions.
    performance_policy: crate::renderer::stats::PerformancePolicy,
    /// Current render scale tracked by the adaptation controller (or set manually).
    ///
    /// Clamped to `[policy.min_render_scale, policy.max_render_scale]`.
    /// Reported in `FrameStats::render_scale` each frame.
    current_render_scale: f32,
    /// Instant the renderer was constructed. Used as the t=0 reference for
    /// per-frame animated effects (e.g. `ScatterVolume::noise` time scrolling).
    start_instant: std::time::Instant,
    /// Instant recorded at the start of the most recent `prepare()` call.
    /// Used to compute `total_frame_ms` on the following frame.
    last_prepare_instant: Option<std::time::Instant>,
    /// Frame counter incremented each `prepare()` call. Used for picking throttle in Playback mode.
    frame_counter: u64,
    /// Surface items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_scene_items: Vec<SceneRenderItem>,
    /// Point cloud items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_point_cloud_items: Vec<PointCloudItem>,
    /// Gaussian splat items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_splat_items: Vec<GaussianSplatItem>,
    /// Volume items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_volume_items: Vec<VolumeItem>,
    /// Scatter volume items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_scatter_volume_items: Vec<crate::renderer::types::ScatterVolumeItem>,
    /// Volumes packed into the GPU storage buffer this frame
    /// (volume, density_multiplier, flag bits). Stored so `render_viewport`
    /// can re-upload as needed without re-walking the scene frame.
    pub(crate) prepared_scatter_volumes:
        Vec<(crate::scene::scatter_volume::ScatterVolume, f32, u32)>,
    /// Subset of the prepared scatter volumes that carry `RefractionParams`.
    /// Cleared and refilled each frame by `prepare_viewport`. The refraction
    /// pass walks this list; an empty list skips the pass entirely.
    pub(crate) prepared_refraction_volumes: Vec<(crate::scene::scatter_volume::ScatterVolume, f32)>,
    /// Per-viewport scatter intermediates and temporal history. Indexed by
    /// `vp_idx`. Grown lazily inside the scatter pass; each entry is
    /// reallocated when the requested scatter target size or downsample mode
    /// changes.
    pub(crate) scatter_viewport_states: Vec<Option<crate::resources::ScatterViewportState>>,
    /// Opaque volume mesh items from the last `prepare()` call, retained for cell-level `pick()` dispatch.
    pick_volume_mesh_items: Vec<VolumeMeshItem>,
    /// Polyline items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_polyline_items: Vec<PolylineItem>,
    /// Glyph items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_glyph_items: Vec<GlyphItem>,
    /// Tensor glyph items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_tensor_glyph_items: Vec<TensorGlyphItem>,
    /// Sprite items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_sprite_items: Vec<SpriteItem>,
    /// Streamtube items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_streamtube_items: Vec<StreamtubeItem>,
    /// Tube items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_tube_items: Vec<TubeItem>,
    /// Ribbon items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_ribbon_items: Vec<RibbonItem>,
    /// Image slice items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_image_slice_items: Vec<ImageSliceItem>,
    /// Volume surface slice items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_volume_surface_slice_items: Vec<VolumeSurfaceSliceItem>,
    /// Screen image items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_screen_image_items: Vec<ScreenImageItem>,
    /// GPU implicit surface items from the last `prepare()` call, retained for `pick()` dispatch.
    pick_implicit_items: Vec<GpuImplicitPickItem>,
    /// GPU marching cubes jobs from the last `prepare()` call, retained for `pick()` dispatch.
    pick_mc_items: Vec<GpuMcPickItem>,

    // --- GPU timestamp queries ---
    /// Timestamp query set with 2 entries (scene-pass begin + end).
    /// `None` when `TIMESTAMP_QUERY` is unavailable or not yet initialized.
    ts_query_set: Option<wgpu::QuerySet>,
    /// Resolve buffer: 2 × u64, GPU-only (`QUERY_RESOLVE | COPY_SRC`).
    ts_resolve_buf: Option<wgpu::Buffer>,
    /// Staging buffer: 2 × u64, CPU-readable (`COPY_DST | MAP_READ`).
    ts_staging_buf: Option<wgpu::Buffer>,
    /// Nanoseconds per GPU timestamp tick, from `queue.get_timestamp_period()`.
    ts_period: f32,
    /// Whether the staging buffer holds unread timestamp data from the previous frame.
    ts_needs_readback: bool,

    // --- Indirect-args readback (GPU-driven culling visible instance count) ---
    /// CPU-readable staging buffer for `indirect_args_buf` (batch_count × 20 bytes).
    /// Grown lazily; never shrunk.
    indirect_readback_buf: Option<wgpu::Buffer>,
    /// Number of batches whose data was copied into `indirect_readback_buf` last frame.
    indirect_readback_batch_count: u32,
    /// True when `indirect_readback_buf` holds unread data from the previous cull pass.
    indirect_readback_pending: bool,

    // --- Per-pass degradation state ---
    /// Tiered degradation ladder position (0 = none, 1 = shadows, 2 = volumes, 3 = effects).
    /// Advanced one step per over-budget frame once render scale hits minimum;
    /// reversed one step per comfortably-under-budget frame.
    degradation_tier: u8,
    /// Whether the shadow pass was skipped this frame due to budget pressure.
    /// Computed once per frame at the top of prepare() and used by both
    /// prepare_scene_internal and reported in FrameStats.
    degradation_shadows_skipped: bool,
    /// Whether volume raymarch step size was doubled this frame due to budget pressure.
    degradation_volume_quality_reduced: bool,
    /// Whether SSAO, contact shadows, and bloom were skipped this frame.
    /// Set in prepare(); read by the render path.
    degradation_effects_throttled: bool,

    // --- D8: shadow debug stats cache ---
    /// Cascade count from the last prepare_scene_internal call.
    last_cascade_count: u32,
    /// Cascade split distances from the last prepare_scene_internal call.
    last_cascade_splits: [f32; 4],
    /// Shadow frustum half-extent from the last prepare_scene_internal call.
    last_shadow_extent: f32,
    /// Shadow atlas resolution from the last prepare_scene_internal call.
    last_shadow_atlas_resolution: u32,
    /// Contact shadow enabled state from the last prepare_scene_internal call.
    last_contact_shadow_active: bool,
    /// Cascade splits from the last tracing log emission. Sentinel [f32::MAX; 4] forces
    /// a log on the first frame.
    last_logged_cascade_splits: [f32; 4],
    /// Lights dropped by the CPU frustum cull on the most recent frame.
    /// Surfaced through the cluster debug overlay when enabled.
    pub(crate) last_frustum_culled_lights: u32,
    /// Most recent cluster build readback. Populated when a frame's
    /// `ViewportFrame::cluster_stats_request` was true.
    pub(crate) last_cluster_stats: Option<crate::resources::clustered::ClusterStats>,
    /// Shadow atlas uniform from the last prepare_scene_internal call. Seeds
    /// the shadow buffer of viewport slots created after the scene prepare has
    /// already written existing slots, so a new viewport's first frame does
    /// not sample shadows through a zeroed uniform.
    pub(crate) last_shadow_atlas_uniform: crate::resources::ShadowAtlasUniform,
}

impl ViewportRenderer {
    /// Create a new renderer with default settings (no MSAA).
    /// Call once at application startup.
    pub fn new(device: &wgpu::Device, target_format: wgpu::TextureFormat) -> Self {
        Self::with_sample_count(device, target_format, 1)
    }

    /// Create a new renderer with the specified MSAA sample count (1, 2, or 4).
    ///
    /// When using MSAA (sample_count > 1), the caller must create multisampled
    /// colour and depth textures and use them as render pass attachments with the
    /// final surface texture as the resolve target.
    pub fn with_sample_count(
        device: &wgpu::Device,
        target_format: wgpu::TextureFormat,
        sample_count: u32,
    ) -> Self {
        let gpu_culling_supported = device
            .features()
            .contains(wgpu::Features::INDIRECT_FIRST_INSTANCE);
        Self {
            resources: ViewportGpuResources::new(device, target_format, sample_count),
            instanced_batches: Vec::new(),
            use_instancing: false,
            gpu_culling_supported,
            gpu_culling_enabled: gpu_culling_supported,
            cull_resources: None,
            item_type_plugins: std::collections::HashMap::new(),
            plugin_frame_index: 0,
            last_stats: crate::renderer::stats::FrameStats::default(),
            last_scene_generation: u64::MAX,
            last_selection_generation: u64::MAX,
            last_scene_items_count: usize::MAX,
            last_instancable_count: usize::MAX,
            cached_instance_count: 0,
            cached_instance_hashes: Vec::new(),
            cached_instanced_batches: Vec::new(),
            force_full_upload: false,
            point_cloud_gpu_data: Vec::new(),
            glyph_gpu_data: Vec::new(),
            tensor_glyph_gpu_data: Vec::new(),
            polyline_gpu_data: Vec::new(),
            volume_gpu_data: Vec::new(),
            streamtube_gpu_data: Vec::new(),
            tube_gpu_data: Vec::new(),
            ribbon_gpu_data: Vec::new(),
            streamtube_selected_gpu_indices: Vec::new(),
            tube_selected_gpu_indices: Vec::new(),
            ribbon_selected_gpu_indices: Vec::new(),
            polyline_selected_gpu_indices: Vec::new(),
            image_slice_gpu_data: Vec::new(),
            volume_surface_slice_gpu_data: Vec::new(),
            sprite_gpu_data: Vec::new(),
            mesh_instance_gpu_data: Vec::new(),
            particle_gpu_data: Vec::new(),
            sprite_refraction_resolves: Vec::new(),
            gaussian_splat_draw_data: Vec::new(),
            lic_gpu_data: Vec::new(),
            implicit_gpu_data: Vec::new(),
            decal_gpu_data: Vec::new(),
            decal_exclude_items: Vec::new(),
            mc_gpu_data: Vec::new(),
            screen_image_gpu_data: Vec::new(),
            overlay_image_gpu_data: Vec::new(),
            label_gpu_data: None,
            scalar_bar_gpu_data: None,
            ruler_gpu_data: None,
            loading_bar_gpu_data: None,
            overlay_rect_gpu_data: None,
            overlay_shape_gpu_data: None,
            backdrop_blur_state: None,
            viewport_slots: Vec::new(),
            compute_filter_results: Vec::new(),
            wireframe_uniform_bufs: Vec::new(),
            wireframe_bind_groups: Vec::new(),
            per_item_object_uniform_bufs: Vec::new(),
            per_item_object_bind_groups: Vec::new(),
            per_item_object_cache_keys: Vec::new(),
            tvm_wireframe_draws: Vec::new(),
            tvm_wireframe_buf: None,
            tvm_wireframe_bg: None,
            last_cascade0_shadow_mat: glam::Mat4::IDENTITY,
            runtime_mode: crate::renderer::stats::RuntimeMode::Interactive,
            performance_policy: crate::renderer::stats::PerformancePolicy::default(),
            upload_budget: None,
            current_render_scale: 1.0,
            start_instant: std::time::Instant::now(),
            last_prepare_instant: None,
            frame_counter: 0,
            pick_scene_items: Vec::new(),
            pick_point_cloud_items: Vec::new(),
            pick_splat_items: Vec::new(),
            pick_volume_items: Vec::new(),
            pick_scatter_volume_items: Vec::new(),
            prepared_scatter_volumes: Vec::new(),
            prepared_refraction_volumes: Vec::new(),
            scatter_viewport_states: Vec::new(),
            pick_volume_mesh_items: Vec::new(),
            pick_polyline_items: Vec::new(),
            pick_glyph_items: Vec::new(),
            pick_tensor_glyph_items: Vec::new(),
            pick_sprite_items: Vec::new(),
            pick_streamtube_items: Vec::new(),
            pick_tube_items: Vec::new(),
            pick_ribbon_items: Vec::new(),
            pick_image_slice_items: Vec::new(),
            pick_volume_surface_slice_items: Vec::new(),
            pick_screen_image_items: Vec::new(),
            pick_implicit_items: Vec::new(),
            pick_mc_items: Vec::new(),
            ts_query_set: None,
            ts_resolve_buf: None,
            ts_staging_buf: None,
            ts_period: 1.0,
            ts_needs_readback: false,
            indirect_readback_buf: None,
            indirect_readback_batch_count: 0,
            indirect_readback_pending: false,
            degradation_tier: 0,
            degradation_shadows_skipped: false,
            degradation_volume_quality_reduced: false,
            degradation_effects_throttled: false,
            last_cascade_count: 0,
            last_cascade_splits: [0.0; 4],
            last_shadow_extent: 20.0,
            last_shadow_atlas_resolution: 4096,
            last_contact_shadow_active: false,
            last_logged_cascade_splits: [f32::MAX; 4],
            last_frustum_culled_lights: 0,
            last_cluster_stats: None,
            last_shadow_atlas_uniform: bytemuck::Zeroable::zeroed(),
        }
    }

    /// Access the underlying GPU resources (e.g. for mesh uploads).
    pub fn resources(&self) -> &ViewportGpuResources {
        &self.resources
    }

    /// Performance counters from the last completed frame.
    pub fn last_frame_stats(&self) -> crate::renderer::stats::FrameStats {
        self.last_stats
    }

    /// Diagnostics from the cluster build pass on the most recent frame that
    /// requested them (`ViewportFrame::cluster_stats_request`). Returns
    /// `None` until a request has been served.
    pub fn cluster_stats(&self) -> Option<crate::resources::clustered::ClusterStats> {
        self.last_cluster_stats
    }

    /// Disable GPU-driven culling, reverting to the direct draw path.
    ///
    /// Has no effect when the device does not support `INDIRECT_FIRST_INSTANCE`
    /// (culling is already disabled on those devices).
    pub fn disable_gpu_driven_culling(&mut self) {
        self.gpu_culling_enabled = false;
    }

    /// Force a full instance buffer upload on the next frame.
    ///
    /// Normally the renderer skips GPU writes for instanced batches whose data
    /// has not changed since the last upload. Call this when you have mutated
    /// batch-relevant state through a path the renderer cannot observe (for
    /// example, directly modifying GPU buffer contents or scene items after
    /// `collect_render_items` runs). The flag is consumed once and resets
    /// automatically after the next `prepare` call.
    pub fn force_dirty(&mut self) {
        self.force_full_upload = true;
        // Also invalidate the generation cache so the next prepare is guaranteed
        // to enter the rebuild path even if the scene generation is unchanged.
        self.last_scene_generation = u64::MAX;
    }

    /// Re-enable GPU-driven culling after a call to `disable_gpu_driven_culling`.
    ///
    /// Has no effect when the device does not support `INDIRECT_FIRST_INSTANCE`.
    pub fn enable_gpu_driven_culling(&mut self) {
        if self.gpu_culling_supported {
            self.gpu_culling_enabled = true;
        }
    }

    /// Cap the per-frame cost of running upload-job apply closures.
    ///
    /// `None` is the default and matches the historical behaviour:
    /// `prepare` drains every completed upload's apply step in one
    /// shot. `Some(d)` switches `prepare` over to
    /// `process_uploads_with_budget` so applies that overflow the
    /// budget spill to the next frame. Useful when a stress load lands
    /// many heavy completions on the same frame and the bunched apply
    /// work shows up as one fat frame at the end of the load.
    pub fn set_upload_budget(&mut self, budget: Option<std::time::Duration>) {
        self.upload_budget = budget;
    }

    /// Currently configured upload budget. See `set_upload_budget`.
    pub fn upload_budget(&self) -> Option<std::time::Duration> {
        self.upload_budget
    }

    /// Set the runtime mode controlling internal default behavior.
    ///
    /// - [`RuntimeMode::Interactive`]: full picking rate, full quality (default).
    /// - [`RuntimeMode::Playback`]: picking throttled to reduce CPU overhead during animation.
    /// - [`RuntimeMode::Paused`]: full picking rate, full quality.
    /// - [`RuntimeMode::Capture`]: full quality, intended for screenshot/export workflows.
    pub fn set_runtime_mode(&mut self, mode: crate::renderer::stats::RuntimeMode) {
        self.runtime_mode = mode;
    }

    /// Return the current runtime mode.
    pub fn runtime_mode(&self) -> crate::renderer::stats::RuntimeMode {
        self.runtime_mode
    }

    /// Set the performance policy controlling target FPS, render scale bounds,
    /// and permitted quality reductions.
    ///
    /// The internal adaptation controller activates when
    /// `policy.allow_dynamic_resolution` is `true` and `policy.target_fps` is
    /// `Some`. It adjusts `render_scale` within `[min_render_scale,
    /// max_render_scale]` each frame based on `total_frame_ms`.
    pub fn set_performance_policy(&mut self, policy: crate::renderer::stats::PerformancePolicy) {
        self.performance_policy = policy;
        // Clamp current scale into the new bounds immediately.
        self.current_render_scale = self
            .current_render_scale
            .clamp(policy.min_render_scale, policy.max_render_scale);
    }

    /// Return the active performance policy.
    pub fn performance_policy(&self) -> crate::renderer::stats::PerformancePolicy {
        self.performance_policy
    }

    /// Manually set the render scale.
    ///
    /// Effective when `performance_policy.allow_dynamic_resolution` is `false`.
    /// When dynamic resolution is enabled the adaptation controller overrides
    /// this value each frame.
    ///
    /// The value is clamped to `[policy.min_render_scale, policy.max_render_scale]`.
    ///
    /// Works on both the LDR and HDR render paths. On the HDR path, the scene,
    /// bloom, SSAO, tone-map, and FXAA all run at the scaled resolution; the
    /// result is upscale-blitted to native resolution before overlays and grid.
    pub fn set_render_scale(&mut self, scale: f32) {
        self.current_render_scale = scale.clamp(
            self.performance_policy.min_render_scale,
            self.performance_policy.max_render_scale,
        );
    }

    /// Set the target frame rate used to compute [`FrameStats::missed_budget`].
    ///
    /// Convenience wrapper that updates `performance_policy.target_fps`.
    pub fn set_target_fps(&mut self, fps: Option<f32>) {
        self.performance_policy.target_fps = fps;
    }

    /// Mutable access to the underlying GPU resources (e.g. for mesh uploads).
    pub fn resources_mut(&mut self) -> &mut ViewportGpuResources {
        &mut self.resources
    }

    /// Returns true when the current frame is rendered via the instanced draw path.
    ///
    /// When true, edits to mesh.wgsl shadow sampling code have no effect - the active
    /// shader is mesh_instanced.wgsl. Check this before testing shader changes.
    pub fn is_using_instanced_path(&self) -> bool {
        self.use_instancing
    }

    /// Returns the number of instanced batches prepared for the current frame.
    ///
    /// Zero when using the non-instanced path. Each batch corresponds to a distinct
    /// (MeshId, material) combination in the scene.
    pub fn instanced_batch_count(&self) -> usize {
        self.instanced_batches.len()
    }

    /// Run the GPU-driven cull compute against a plugin's
    /// [`CullSubmission`](crate::plugin_api::CullSubmission).
    ///
    /// Encodes two compute passes into `encoder`:
    /// 1. one thread per instance, tests AABB against `frustum`, claims a
    ///    visibility slot via atomic add;
    /// 2. one thread per batch, writes a `DrawIndexedIndirect` entry into
    ///    `sub.indirect_out` with the final visible count and zeroes the
    ///    counter for the next call.
    ///
    /// After the encoder runs, draw each batch with
    /// `pass.draw_indexed_indirect(sub.indirect_out, batch_idx * 20)` using
    /// `sub.visible_out` as the per-instance lookup buffer.
    ///
    /// The cull pipeline is created lazily on the first call. Returns
    /// without dispatching if the device does not support
    /// `INDIRECT_FIRST_INSTANCE` (call
    /// [`is_gpu_culling_supported`](Self::is_gpu_culling_supported) first).
    pub fn submit_cull(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        frustum: &crate::camera::frustum::Frustum,
        sub: &crate::plugin_api::CullSubmission<'_>,
    ) {
        if !self.gpu_culling_supported {
            return;
        }
        if self.cull_resources.is_none() {
            self.cull_resources = Some(crate::renderer::indirect::CullResources::new(device));
        }
        let cull = self.cull_resources.as_ref().unwrap();
        cull.dispatch(encoder, device, queue, frustum, None, sub);
    }

    /// Same as [`submit_cull`](Self::submit_cull) for one shadow cascade.
    ///
    /// Uploads the frustum to the cascade slot (so a single frame can submit
    /// the main pass plus every cascade without overwriting an in-flight
    /// upload) and forces the cull shader's shadow flag so
    /// `InstanceAabb::cast_shadows = 0` entries are skipped.
    ///
    /// `cascade_idx` must be in `0..4`; values outside that range panic in
    /// debug builds and clamp to 3 in release.
    pub fn submit_cull_shadow(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        cascade_idx: usize,
        cascade_frustum: &crate::camera::frustum::Frustum,
        sub: &crate::plugin_api::CullSubmission<'_>,
    ) {
        if !self.gpu_culling_supported {
            return;
        }
        debug_assert!(cascade_idx < 4, "cascade_idx must be in 0..4");
        let cascade_idx = cascade_idx.min(3);
        if self.cull_resources.is_none() {
            self.cull_resources = Some(crate::renderer::indirect::CullResources::new(device));
        }
        let cull = self.cull_resources.as_ref().unwrap();
        cull.dispatch(
            encoder,
            device,
            queue,
            cascade_frustum,
            Some(cascade_idx),
            sub,
        );
    }

    /// Convenience wrapper around [`submit_cull`](Self::submit_cull) for the
    /// common case of one mesh with N instances.
    ///
    /// The renderer fills its scratch [`BatchMeta`] slot from `draw`, zeroes
    /// its scratch counter, seeds the indirect entry, and runs a one-batch
    /// cull. Plugins that only have a single mesh per submission don't have
    /// to allocate either buffer themselves.
    ///
    /// `indirect_out` must hold one `DrawIndexedIndirect` entry (20 bytes).
    pub fn submit_cull_single_mesh(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        frustum: &crate::camera::frustum::Frustum,
        instance_aabbs: &wgpu::Buffer,
        instance_count: u32,
        visible_out: &wgpu::Buffer,
        indirect_out: &wgpu::Buffer,
        draw: crate::plugin_api::SingleMeshDraw,
        shadow_pass: bool,
    ) {
        self.dispatch_cull_single_mesh(
            device,
            queue,
            encoder,
            frustum,
            None,
            instance_aabbs,
            instance_count,
            visible_out,
            indirect_out,
            draw,
            shadow_pass,
        );
    }

    /// Single-mesh shadow variant of
    /// [`submit_cull_single_mesh`](Self::submit_cull_single_mesh).
    pub fn submit_cull_shadow_single_mesh(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        cascade_idx: usize,
        cascade_frustum: &crate::camera::frustum::Frustum,
        instance_aabbs: &wgpu::Buffer,
        instance_count: u32,
        visible_out: &wgpu::Buffer,
        indirect_out: &wgpu::Buffer,
        draw: crate::plugin_api::SingleMeshDraw,
    ) {
        debug_assert!(cascade_idx < 4, "cascade_idx must be in 0..4");
        let cascade_idx = cascade_idx.min(3);
        self.dispatch_cull_single_mesh(
            device,
            queue,
            encoder,
            cascade_frustum,
            Some(cascade_idx),
            instance_aabbs,
            instance_count,
            visible_out,
            indirect_out,
            draw,
            true,
        );
    }

    #[allow(clippy::too_many_arguments)]
    fn dispatch_cull_single_mesh(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        encoder: &mut wgpu::CommandEncoder,
        frustum: &crate::camera::frustum::Frustum,
        cascade: Option<usize>,
        instance_aabbs: &wgpu::Buffer,
        instance_count: u32,
        visible_out: &wgpu::Buffer,
        indirect_out: &wgpu::Buffer,
        draw: crate::plugin_api::SingleMeshDraw,
        shadow_pass: bool,
    ) {
        if !self.gpu_culling_supported {
            return;
        }
        if self.cull_resources.is_none() {
            self.cull_resources = Some(crate::renderer::indirect::CullResources::new(device));
        }
        let cull = self.cull_resources.as_ref().unwrap();
        let (meta_buf, counter_buf) = cull.scratch_single_mesh_buffers();
        let meta = crate::plugin_api::BatchMeta {
            index_count: draw.index_count,
            first_index: draw.first_index,
            instance_offset: 0,
            instance_count,
            vis_offset: 0,
            is_transparent: 0,
            _pad: [0, 0],
        };
        queue.write_buffer(meta_buf, 0, bytemuck::bytes_of(&meta));
        queue.write_buffer(counter_buf, 0, &[0u8; 4]);
        // Seed the static fields of the indirect entry; the compute pass
        // overwrites `instance_count` with the final visible count.
        let seed: [u32; 5] = [
            draw.index_count,
            0,
            draw.first_index,
            draw.base_vertex as u32,
            draw.first_instance,
        ];
        queue.write_buffer(indirect_out, 0, bytemuck::cast_slice(&seed));

        let sub = crate::plugin_api::CullSubmission {
            instance_aabbs,
            instance_count,
            batch_meta: meta_buf,
            batch_count: 1,
            counter: counter_buf,
            visible_out,
            indirect_out,
            shadow_pass,
        };
        cull.dispatch(encoder, device, queue, frustum, cascade, &sub);
    }

    /// Register an [`ItemTypePlugin`](crate::plugin_api::ItemTypePlugin).
    ///
    /// Invokes the plugin's `init_gpu` against the current device and
    /// shared bind layout, then stores it keyed by `type_name()` for the
    /// remainder of the renderer's lifetime. Registering a second plugin
    /// with the same `type_name` replaces the first.
    ///
    /// The renderer will dispatch `prepare` and `paint` to the plugin on
    /// every frame where
    /// [`SceneFrame::submit_plugin_items`](crate::renderer::SceneFrame::submit_plugin_items)
    /// has populated a collection under the same name.
    pub fn with_item_type_plugin(
        &mut self,
        device: &wgpu::Device,
        mut plugin: Box<dyn crate::plugin_api::ItemTypePlugin>,
    ) {
        let shared = self.resources.shared_bindings();
        plugin.init_gpu(device, &shared);
        let name = plugin.type_name();
        self.item_type_plugins.insert(name, plugin);
    }

    /// Returns true when an item-type plugin with `type_name` is
    /// registered.
    pub fn has_item_type_plugin(&self, type_name: &str) -> bool {
        self.item_type_plugins.contains_key(type_name)
    }

    /// Walk registered item-type plugins, invoke `prepare` for each one
    /// that has a matching collection submitted on `frame.scene`, and
    /// return the concatenated command buffers.
    ///
    /// Called internally from the lib's prepare paths; not part of the
    /// consumer-facing API.
    pub(crate) fn dispatch_plugin_prepare(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        frame: &FrameData,
    ) -> Vec<wgpu::CommandBuffer> {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return Vec::new();
        }
        self.plugin_frame_index = self.plugin_frame_index.wrapping_add(1);
        let mut bufs: Vec<wgpu::CommandBuffer> = Vec::new();
        for (name, plugin) in self.item_type_plugins.iter_mut() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                // Constructed per plugin because `Jobs` borrows `&resources`
                // and the borrow only needs to live for this iteration.
                let ctx = crate::plugin_api::ItemFrameContext {
                    camera: &frame.camera.render_camera,
                    viewport_size: glam::Vec2::from(frame.camera.viewport_size),
                    viewport_index: frame.camera.viewport_index,
                    frame_index: self.plugin_frame_index,
                    jobs: crate::resources::Jobs::new(&self.resources),
                };
                bufs.extend(plugin.prepare(device, queue, &ctx, items.as_ref()));
            }
        }
        bufs
    }

    /// Walk registered item-type plugins and invoke `paint` for each one
    /// that has a matching collection submitted on `frame.scene`.
    ///
    /// Called from inside the lib's HDR scene pass between built-in
    /// opaques and the skybox.
    pub(crate) fn dispatch_plugin_paint<'rp>(
        &'rp self,
        pass: &mut wgpu::RenderPass<'rp>,
        frame: &'rp FrameData,
    ) {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return;
        }
        let ctx = crate::plugin_api::PaintContext {
            camera: &frame.camera.render_camera,
            viewport_size: glam::Vec2::from(frame.camera.viewport_size),
            viewport_index: frame.camera.viewport_index,
            frame_index: self.plugin_frame_index,
        };
        for (name, plugin) in self.item_type_plugins.iter() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                plugin.paint(pass, &ctx, items.as_ref());
            }
        }
    }

    /// Walk registered plugins and invoke `paint_transparent` for each
    /// one whose collection is on `frame.scene`.
    ///
    /// Called from inside the lib's OIT render pass, after built-in
    /// transparent draws.
    pub(crate) fn dispatch_plugin_paint_transparent<'rp>(
        &'rp self,
        pass: &mut wgpu::RenderPass<'rp>,
        frame: &'rp FrameData,
    ) {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return;
        }
        let ctx = crate::plugin_api::PaintContext {
            camera: &frame.camera.render_camera,
            viewport_size: glam::Vec2::from(frame.camera.viewport_size),
            viewport_index: frame.camera.viewport_index,
            frame_index: self.plugin_frame_index,
        };
        for (name, plugin) in self.item_type_plugins.iter() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                plugin.paint_transparent(pass, &ctx, items.as_ref());
            }
        }
    }

    /// Walk registered plugins and invoke `cast_shadow_pass` for the
    /// given cascade.
    ///
    /// Currently unused: the shadow-pass call site inlines the plugin
    /// dispatch because the surrounding scope holds a mutable borrow of
    /// `self.resources` that blocks a normal `&self` method call. Kept
    /// alongside the other dispatchers as the natural shape; a future
    /// refactor that splits the resources borrow can switch back.
    #[allow(dead_code)]
    pub(crate) fn dispatch_plugin_shadow<'rp>(
        &'rp self,
        pass: &mut wgpu::RenderPass<'rp>,
        frame: &'rp FrameData,
        cascade_idx: u32,
        light_view_proj: glam::Mat4,
    ) {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return;
        }
        let ctx = crate::plugin_api::ShadowCastContext {
            cascade_idx,
            light_view_proj,
            camera: &frame.camera.render_camera,
            viewport_index: frame.camera.viewport_index,
            frame_index: self.plugin_frame_index,
        };
        for (name, plugin) in self.item_type_plugins.iter() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                plugin.cast_shadow_pass(pass, &ctx, items.as_ref());
            }
        }
    }

    /// Walk registered plugins and invoke `cull` for each one whose
    /// collection is on `frame.scene`.
    ///
    /// Called from the lib's prepare path once the camera frustum for
    /// the frame is known.
    pub(crate) fn dispatch_plugin_cull(
        &mut self,
        frustum: &crate::camera::frustum::Frustum,
        frame: &FrameData,
    ) {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return;
        }
        for (name, plugin) in self.item_type_plugins.iter_mut() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                let ctx = crate::plugin_api::ItemFrameContext {
                    camera: &frame.camera.render_camera,
                    viewport_size: glam::Vec2::from(frame.camera.viewport_size),
                    viewport_index: frame.camera.viewport_index,
                    frame_index: self.plugin_frame_index,
                    jobs: crate::resources::Jobs::new(&self.resources),
                };
                plugin.cull(frustum, &ctx, items.as_ref());
            }
        }
    }

    /// Walk registered item-type plugins and invoke `outline_mask` for
    /// each one whose collection is on `frame.scene`.
    ///
    /// Called from inside the lib's outline-mask render pass.
    pub(crate) fn dispatch_plugin_outline_mask<'rp>(
        &'rp self,
        pass: &mut wgpu::RenderPass<'rp>,
        frame: &'rp FrameData,
    ) {
        if self.item_type_plugins.is_empty() || frame.scene.plugin_items.is_empty() {
            return;
        }
        let ctx = crate::plugin_api::OutlineMaskContext {
            camera: &frame.camera.render_camera,
            viewport_size: glam::Vec2::from(frame.camera.viewport_size),
            viewport_index: frame.camera.viewport_index,
            frame_index: self.plugin_frame_index,
        };
        for (name, plugin) in self.item_type_plugins.iter() {
            if let Some(items) = frame.scene.plugin_items.get(*name) {
                plugin.outline_mask(pass, &ctx, items.as_ref());
            }
        }
    }

    /// True when the device supports the features GPU-driven culling needs.
    ///
    /// Plugins should gate `submit_cull` calls on this. If false, the lib
    /// silently no-ops the submission and the plugin must fall back to
    /// direct draws.
    pub fn is_gpu_culling_supported(&self) -> bool {
        self.gpu_culling_supported
    }

    /// Returns per-frame shadow and lighting pipeline statistics for debug inspection.
    ///
    /// All fields reflect the most recently completed `prepare` call (one frame
    /// behind the display). Returns default values before the first `prepare` call.
    pub fn shadow_debug_stats(&self) -> ShadowDebugStats {
        ShadowDebugStats {
            using_instanced_path: self.use_instancing,
            instanced_batch_count: self.instanced_batches.len(),
            cascade_count: self.last_cascade_count,
            cascade_splits: self.last_cascade_splits,
            shadow_atlas_resolution: self.last_shadow_atlas_resolution,
            shadow_extent_world: self.last_shadow_extent,
            contact_shadow_active: self.last_contact_shadow_active,
        }
    }

    /// Read the debug values at a specific pixel from the per-fragment storage buffer.
    ///
    /// Returns `None` when debug_vis is inactive (no buffer allocated) or when `(x, y)`
    /// is outside the viewport. The four channels correspond to the current R/G/B channel
    /// selectors plus 1.0 for alpha.
    ///
    /// This submits a GPU-to-CPU copy and waits synchronously. Only call from outside
    /// a render pass (e.g., in the next frame's prepare step), not inside paint callbacks.
    ///
    /// The returned values are from the previous rendered frame.
    pub fn read_debug_pixel(
        &self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        x: u32,
        y: u32,
    ) -> Option<[f32; 4]> {
        // Use the primary viewport slot (index 0).
        let slot = self.viewport_slots.first()?;
        let buf = slot.debug_frag_buf.as_ref()?;
        let (vw, vh) = slot.debug_frag_dims;
        if x >= vw || y >= vh {
            return None;
        }
        let byte_offset = ((y as u64) * (vw as u64) + (x as u64)) * 16;
        let staging = device.create_buffer(&wgpu::BufferDescriptor {
            label: None,
            size: 16,
            usage: wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });
        let mut encoder =
            device.create_command_encoder(&wgpu::CommandEncoderDescriptor { label: None });
        encoder.copy_buffer_to_buffer(buf, byte_offset, &staging, 0, 16);
        queue.submit(Some(encoder.finish()));
        let slice = staging.slice(..);
        let (tx, rx) = std::sync::mpsc::channel::<Result<(), wgpu::BufferAsyncError>>();
        slice.map_async(wgpu::MapMode::Read, move |r| {
            let _ = tx.send(r);
        });
        let _ = device.poll(wgpu::PollType::Wait {
            submission_index: None,
            timeout: Some(std::time::Duration::from_secs(5)),
        });
        rx.recv().ok()?.ok()?;
        let data = slice.get_mapped_range();
        Some(bytemuck::pod_read_unaligned::<[f32; 4]>(&data))
    }

    /// Upload a Gaussian splat set to the GPU.
    ///
    /// Call once per splat set at startup or when it changes. The returned
    /// [`GaussianSplatId`] is valid until [`remove_gaussian_splats`](Self::remove_gaussian_splats) is called.
    ///
    /// # Errors
    ///
    /// Returns [`ViewportError::InvalidGaussianSplatData`](crate::error::ViewportError::InvalidGaussianSplatData)
    /// if `data.positions` is empty or if `positions`, `scales`, `rotations`, and `opacities`
    /// differ in length.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use viewport_lib::error::ViewportError;
    /// # use viewport_lib::renderer::{GaussianSplatData, ViewportRenderer};
    /// # fn demo(renderer: &mut ViewportRenderer, device: &wgpu::Device, queue: &wgpu::Queue) {
    /// let result = renderer.upload_gaussian_splats(device, queue, &GaussianSplatData::default());
    /// assert!(matches!(result, Err(ViewportError::InvalidGaussianSplatData { .. })));
    /// # }
    /// ```
    pub fn upload_gaussian_splats(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        data: &GaussianSplatData,
    ) -> crate::error::ViewportResult<GaussianSplatId> {
        self.resources.upload_gaussian_splats(device, queue, data)
    }

    /// Remove an uploaded Gaussian splat set by handle.
    ///
    /// After this call the `id` is invalid and must not be submitted in `SceneFrame`.
    pub fn remove_gaussian_splats(&mut self, id: GaussianSplatId) {
        self.resources.remove_gaussian_splats(id);
    }

    /// Upload an equirectangular HDR environment map and precompute IBL textures.
    ///
    /// `pixels` is row-major RGBA f32 data (4 floats per texel), `width`x`height`.
    /// This rebuilds camera bind groups so shaders immediately see the new textures.
    ///
    /// # Errors
    ///
    /// Returns [`ViewportError::InvalidTextureData`](crate::error::ViewportError::InvalidTextureData)
    /// if `pixels.len()` does not equal `width * height * 4`.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use viewport_lib::error::ViewportError;
    /// # use viewport_lib::renderer::ViewportRenderer;
    /// # fn demo(renderer: &mut ViewportRenderer, device: &wgpu::Device, queue: &wgpu::Queue) {
    /// // 2x2 RGBA image requires exactly 16 floats.
    /// let result = renderer.upload_environment_map(device, queue, &[0.0f32; 12], 2, 2);
    /// assert!(matches!(result, Err(ViewportError::InvalidTextureData { expected: 16, actual: 12 })));
    /// # }
    /// ```
    pub fn upload_environment_map(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        pixels: &[f32],
        width: u32,
        height: u32,
    ) -> crate::error::ViewportResult<()> {
        crate::resources::environment::upload_environment_map(
            &mut self.resources,
            device,
            queue,
            pixels,
            width,
            height,
        )?;
        self.rebuild_camera_bind_groups(device);
        Ok(())
    }

    /// Current state of an in-flight upload job.
    pub fn upload_status(&self, id: crate::resources::JobId) -> crate::resources::UploadStatus {
        self.resources.upload_status(id)
    }

    /// Count of upload jobs still in flight.
    pub fn uploads_pending(&self) -> usize {
        self.resources.uploads_pending()
    }

    /// Wall-clock work duration recorded for an async upload job. See
    /// [`ViewportGpuResources::job_duration`].
    pub fn job_duration(&self, id: crate::resources::JobId) -> Option<std::time::Duration> {
        self.resources.job_duration(id)
    }

    /// Drop the recorded duration for `id` after reading it. See
    /// [`ViewportGpuResources::drop_job_duration`].
    pub fn drop_job_duration(&mut self, id: crate::resources::JobId) {
        self.resources.drop_job_duration(id);
    }

    /// Start an asynchronous 3D volume texture upload. See
    /// [`ViewportGpuResources::begin_upload_volume`].
    pub fn begin_upload_volume(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        data: Vec<f32>,
        dims: [u32; 3],
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources
            .begin_upload_volume(device, queue, data, dims)
    }

    /// Take the volume id produced by a completed
    /// [`begin_upload_volume`](Self::begin_upload_volume) job.
    pub fn upload_result_volume(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::resources::VolumeId> {
        self.resources.upload_result_volume(id)
    }

    /// Start an asynchronous marching-cubes-ready volume upload. See
    /// [`ViewportGpuResources::begin_upload_volume_for_mc`].
    pub fn begin_upload_volume_for_mc(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        vol: crate::geometry::marching_cubes::VolumeData,
    ) -> crate::resources::JobId {
        self.resources
            .begin_upload_volume_for_mc(device, queue, vol)
    }

    /// Take the [`VolumeGpuId`](crate::resources::VolumeGpuId) produced by a
    /// completed [`begin_upload_volume_for_mc`](Self::begin_upload_volume_for_mc) job.
    pub fn upload_result_volume_mc(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::resources::VolumeGpuId> {
        self.resources.upload_result_volume_mc(id)
    }

    /// Start an asynchronous boundary-only volume mesh upload. See
    /// [`ViewportGpuResources::begin_upload_volume_mesh`].
    pub fn begin_upload_volume_mesh(
        &mut self,
        device: &wgpu::Device,
        data: crate::resources::volume_mesh::VolumeMeshData,
    ) -> crate::resources::JobId {
        self.resources.begin_upload_volume_mesh(device, data)
    }

    /// Take the [`VolumeMeshItem`](crate::VolumeMeshItem)
    /// produced by a completed
    /// [`begin_upload_volume_mesh`](Self::begin_upload_volume_mesh) job.
    pub fn upload_result_volume_mesh(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::VolumeMeshItem> {
        self.resources.upload_result_volume_mesh(id)
    }

    /// Start an asynchronous clipped volume mesh upload. See
    /// [`ViewportGpuResources::begin_upload_clipped_volume_mesh`].
    pub fn begin_upload_clipped_volume_mesh(
        &mut self,
        device: &wgpu::Device,
        data: crate::resources::volume_mesh::VolumeMeshData,
        clip_planes: Vec<[f32; 4]>,
    ) -> crate::resources::JobId {
        self.resources
            .begin_upload_clipped_volume_mesh(device, data, clip_planes)
    }

    /// Take the [`VolumeMeshItem`](crate::VolumeMeshItem)
    /// produced by a completed
    /// [`begin_upload_clipped_volume_mesh`](Self::begin_upload_clipped_volume_mesh) job.
    pub fn upload_result_clipped_volume_mesh(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::VolumeMeshItem> {
        self.resources.upload_result_clipped_volume_mesh(id)
    }

    /// Start an asynchronous sparse voxel grid upload. See
    /// [`ViewportGpuResources::begin_upload_sparse_volume_grid_data`].
    pub fn begin_upload_sparse_volume_grid_data(
        &mut self,
        device: &wgpu::Device,
        data: crate::resources::SparseVolumeGridData,
    ) -> crate::resources::JobId {
        self.resources
            .begin_upload_sparse_volume_grid_data(device, data)
    }

    /// Take the [`MeshId`](crate::resources::mesh_store::MeshId) produced by a completed
    /// [`begin_upload_sparse_volume_grid_data`](Self::begin_upload_sparse_volume_grid_data)
    /// job.
    pub fn upload_result_sparse_volume_grid(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::resources::mesh_store::MeshId> {
        self.resources.upload_result_sparse_volume_grid(id)
    }

    /// Start an asynchronous Gaussian splat upload. See
    /// [`ViewportGpuResources::begin_upload_gaussian_splats`].
    pub fn begin_upload_gaussian_splats(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        data: crate::renderer::GaussianSplatData,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources
            .begin_upload_gaussian_splats(device, queue, data)
    }

    /// Take the [`GaussianSplatId`](crate::renderer::GaussianSplatId) produced by a
    /// completed [`begin_upload_gaussian_splats`](Self::begin_upload_gaussian_splats) job.
    pub fn upload_result_gaussian_splats(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::renderer::GaussianSplatId> {
        self.resources.upload_result_gaussian_splats(id)
    }

    /// Start an asynchronous overlay texture upload. See
    /// [`ViewportGpuResources::begin_upload_overlay_texture`].
    pub fn begin_upload_overlay_texture(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        width: u32,
        height: u32,
        rgba_data: Vec<u8>,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources
            .begin_upload_overlay_texture(device, queue, width, height, rgba_data)
    }

    /// Take the [`OverlayTextureId`](crate::renderer::OverlayTextureId) produced by a
    /// completed [`begin_upload_overlay_texture`](Self::begin_upload_overlay_texture) job.
    pub fn upload_result_overlay_texture(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::renderer::OverlayTextureId> {
        self.resources.upload_result_overlay_texture(id)
    }

    /// True when no upload jobs are in flight.
    pub fn all_uploads_complete(&self) -> bool {
        self.resources.all_uploads_complete()
    }

    /// Register a callback to fire when an upload job finishes. See
    /// [`ViewportGpuResources::on_upload_complete`] for the semantics.
    pub fn on_upload_complete<F>(&mut self, id: crate::resources::JobId, cb: F)
    where
        F: FnOnce(&crate::resources::UploadStatus) + Send + 'static,
    {
        self.resources.on_upload_complete(id, cb);
    }

    /// Start an asynchronous albedo texture upload. See
    /// [`ViewportGpuResources::begin_upload_texture`] for the semantics.
    pub fn begin_upload_texture(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        width: u32,
        height: u32,
        rgba: Vec<u8>,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources
            .begin_upload_texture(device, queue, width, height, rgba)
    }

    /// Start an asynchronous normal-map upload. See
    /// [`ViewportGpuResources::begin_upload_normal_map`] for the semantics.
    pub fn begin_upload_normal_map(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        width: u32,
        height: u32,
        rgba: Vec<u8>,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources
            .begin_upload_normal_map(device, queue, width, height, rgba)
    }

    /// Take the texture id from a completed async texture upload. See
    /// [`ViewportGpuResources::upload_result_texture`] for the error
    /// semantics.
    pub fn upload_result_texture(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<u64> {
        self.resources.upload_result_texture(id)
    }

    /// Start an asynchronous mesh upload.
    ///
    /// Returns a `JobId` immediately. The CPU prep (tangent computation,
    /// vertex repack, normal-line build) runs on a worker thread; GPU
    /// buffer creation and store insertion run on the main thread during
    /// the next `process_uploads` call after the worker finishes. Once the
    /// status is `Ready`, take the produced `MeshId` with
    /// `upload_result_mesh`.
    ///
    /// Ownership of `data` transfers into the worker; clone at the call
    /// site if you need to retain it.
    ///
    /// # Errors
    ///
    /// Same validation errors as `upload_mesh_data` (empty mesh, length
    /// mismatch, invalid vertex index), all reported before the job is
    /// submitted.
    pub fn begin_upload_mesh_data(
        &mut self,
        device: &wgpu::Device,
        data: crate::resources::MeshData,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        self.resources.begin_upload_mesh_data(device, data)
    }

    /// Take the `MeshId` produced by a completed `begin_upload_mesh_data`
    /// job. See [`ViewportGpuResources::upload_result_mesh`] for the error
    /// semantics.
    pub fn upload_result_mesh(
        &mut self,
        id: crate::resources::JobId,
    ) -> crate::error::ViewportResult<crate::resources::mesh_store::MeshId> {
        self.resources.upload_result_mesh(id)
    }

    /// Start an asynchronous environment-map upload.
    ///
    /// Returns immediately with a `JobId`. The caller drives the upload-job
    /// runner from the renderer's prepare path each frame; once the job
    /// reports `Ready`, the IBL textures are live on the renderer and a
    /// subsequent call to `rebuild_camera_bind_groups` makes them visible
    /// to shaders.
    ///
    /// Ownership of `pixels` transfers into the background worker.
    ///
    /// # Errors
    ///
    /// Returns [`ViewportError::InvalidTextureData`](crate::error::ViewportError::InvalidTextureData)
    /// if `pixels.len() != width * height * 4`.
    pub fn begin_upload_environment_map(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        pixels: Vec<f32>,
        width: u32,
        height: u32,
    ) -> crate::error::ViewportResult<crate::resources::JobId> {
        crate::resources::environment::begin_upload_environment_map(
            &mut self.resources,
            device,
            queue,
            pixels,
            width,
            height,
        )
    }

    /// Rebuild the primary and per-viewport camera bind groups.
    ///
    /// Call after IBL textures are uploaded so the shaders see the new
    /// environment. The synchronous `upload_environment_map` does this
    /// internally; consumers driving the async path through
    /// `begin_upload_environment_map` should call this themselves once the
    /// matching job reports `Ready`.
    pub fn rebuild_camera_bind_groups(&mut self, device: &wgpu::Device) {
        self.resources.camera_bind_group = self.resources.create_camera_bind_group(
            device,
            &self.resources.camera_uniform_buf,
            &self.resources.clip_planes_uniform_buf,
            &self.resources.shadow_info_buf,
            &self.resources.clip_volume_uniform_buf,
            &self.resources.debug_frag_sentinel_buf,
            "camera_bind_group",
        );

        for slot in &mut self.viewport_slots {
            let dbg_buf = slot
                .debug_frag_buf
                .as_ref()
                .unwrap_or(&self.resources.debug_frag_sentinel_buf);
            slot.camera_bind_group = self.resources.create_camera_bind_group(
                device,
                &slot.camera_buf,
                &slot.clip_planes_buf,
                &slot.shadow_info_buf,
                &slot.clip_volume_buf,
                dbg_buf,
                "per_viewport_camera_bg",
            );
        }
    }

    /// Ensure a per-viewport slot exists for `viewport_index`.
    ///
    /// Creates a full `ViewportSlot` with independent uniform buffers for camera,
    /// clip planes, clip volume, shadow info, and grid. The camera bind group
    /// references this slot's per-viewport buffers plus shared scene-global
    /// resources. Slots are created lazily and never destroyed.
    fn ensure_viewport_slot(&mut self, device: &wgpu::Device, viewport_index: usize) {
        while self.viewport_slots.len() <= viewport_index {
            let camera_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_camera_buf"),
                size: std::mem::size_of::<CameraUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            let clip_planes_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_clip_planes_buf"),
                size: std::mem::size_of::<ClipPlanesUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            let clip_volume_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_clip_volume_buf"),
                size: std::mem::size_of::<ClipVolumesUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            // Seeded with the latest shadow atlas uniform rather than zeros:
            // prepare_scene_internal writes shadow info only to slots that
            // exist at that point, so a slot created later in the same frame
            // would otherwise render its first frame with zeroed cascade
            // matrices (NaN shadow UVs, everything shadowed).
            let shadow_info_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_shadow_info_buf"),
                size: std::mem::size_of::<ShadowAtlasUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: true,
            });
            shadow_info_buf
                .slice(..)
                .get_mapped_range_mut()
                .copy_from_slice(bytemuck::cast_slice(&[self.last_shadow_atlas_uniform]));
            shadow_info_buf.unmap();
            let grid_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_grid_buf"),
                size: std::mem::size_of::<GridUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });

            let camera_bind_group = self.resources.create_camera_bind_group(
                device,
                &camera_buf,
                &clip_planes_buf,
                &shadow_info_buf,
                &clip_volume_buf,
                &self.resources.debug_frag_sentinel_buf,
                "per_viewport_camera_bg",
            );

            let grid_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("vp_grid_bind_group"),
                layout: &self.resources.grid_bind_group_layout,
                entries: &[wgpu::BindGroupEntry {
                    binding: 0,
                    resource: grid_buf.as_entire_binding(),
                }],
            });

            // Per-viewport gizmo buffers (initial mesh: Translate, no hover, identity orientation).
            let (gizmo_verts, gizmo_indices) = crate::interaction::gizmo::build_gizmo_mesh(
                crate::interaction::gizmo::GizmoMode::Translate,
                crate::interaction::gizmo::GizmoAxis::None,
                glam::Quat::IDENTITY,
            );
            let gizmo_vertex_buffer = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_gizmo_vertex_buf"),
                size: (std::mem::size_of::<crate::resources::Vertex>() * gizmo_verts.len().max(1))
                    as u64,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: true,
            });
            gizmo_vertex_buffer
                .slice(..)
                .get_mapped_range_mut()
                .copy_from_slice(bytemuck::cast_slice(&gizmo_verts));
            gizmo_vertex_buffer.unmap();
            let gizmo_index_count = gizmo_indices.len() as u32;
            let gizmo_index_buffer = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_gizmo_index_buf"),
                size: (std::mem::size_of::<u32>() * gizmo_indices.len().max(1)) as u64,
                usage: wgpu::BufferUsages::INDEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: true,
            });
            gizmo_index_buffer
                .slice(..)
                .get_mapped_range_mut()
                .copy_from_slice(bytemuck::cast_slice(&gizmo_indices));
            gizmo_index_buffer.unmap();
            let gizmo_uniform = crate::interaction::gizmo::GizmoUniform {
                model: glam::Mat4::IDENTITY.to_cols_array_2d(),
            };
            let gizmo_uniform_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_gizmo_uniform_buf"),
                size: std::mem::size_of::<crate::interaction::gizmo::GizmoUniform>() as u64,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: true,
            });
            gizmo_uniform_buf
                .slice(..)
                .get_mapped_range_mut()
                .copy_from_slice(bytemuck::cast_slice(&[gizmo_uniform]));
            gizmo_uniform_buf.unmap();
            let gizmo_bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
                label: Some("vp_gizmo_bind_group"),
                layout: &self.resources.gizmo_bind_group_layout,
                entries: &[wgpu::BindGroupEntry {
                    binding: 0,
                    resource: gizmo_uniform_buf.as_entire_binding(),
                }],
            });

            // Per-viewport axes vertex buffer (2048 vertices = enough for all axes geometry).
            let axes_vertex_buffer = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("vp_axes_vertex_buf"),
                size: (std::mem::size_of::<crate::widgets::axes_indicator::AxesVertex>() * 2048)
                    as u64,
                usage: wgpu::BufferUsages::VERTEX | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });

            self.viewport_slots.push(ViewportSlot {
                camera_buf,
                clip_planes_buf,
                clip_volume_buf,
                shadow_info_buf,
                grid_buf,
                camera_bind_group,
                grid_bind_group,
                hdr: None,
                debug_frag_buf: None,
                debug_frag_dims: (0, 0),
                outline_object_buffers: Vec::new(),
                splat_outline_buffers: Vec::new(),
                volume_outline_indices: Vec::new(),
                glyph_outline_indices: Vec::new(),
                tensor_glyph_outline_indices: Vec::new(),
                sprite_outline_indices: Vec::new(),
                raw_geom_outline_buffers: Vec::new(),
                screen_rect_outline_buffers: Vec::new(),
                implicit_outline_indices: Vec::new(),
                mc_outline_data: Vec::new(),
                streamtube_outline_items: Vec::new(),
                tube_outline_items: Vec::new(),
                ribbon_outline_items: Vec::new(),
                polyline_outline_indices: Vec::new(),
                xray_object_buffers: Vec::new(),
                constraint_line_buffers: Vec::new(),
                cap_buffers: Vec::new(),
                clip_plane_fill_buffers: Vec::new(),
                clip_plane_line_buffers: Vec::new(),
                axes_vertex_buffer,
                axes_vertex_count: 0,
                gizmo_uniform_buf,
                gizmo_bind_group,
                gizmo_vertex_buffer,
                gizmo_index_buffer,
                gizmo_index_count,
                sub_highlight: None,
                sub_highlight_generation: u64::MAX,
                dyn_res: None,
                hdr_callback: None,
            });
        }
    }

    // -----------------------------------------------------------------------
    // Multi-viewport public API
    // -----------------------------------------------------------------------

    /// Create a new viewport slot and return its handle.
    ///
    /// The returned [`ViewportId`] is stable for the lifetime of the renderer.
    /// Pass it to [`prepare_viewport`](Self::prepare_viewport),
    /// [`paint_viewport`](Self::paint_viewport), and
    /// [`render_viewport`](Self::render_viewport) each frame.
    ///
    /// Also set the viewport slot on the camera frame when building the
    /// [`FrameData`] for this viewport:
    /// ```rust,ignore
    /// let id = renderer.create_viewport(&device);
    /// let frame = FrameData {
    ///     camera: CameraFrame::from_camera(&cam, size).with_viewport_id(id),
    ///     ..Default::default()
    /// };
    /// ```
    pub fn create_viewport(&mut self, device: &wgpu::Device) -> ViewportId {
        let idx = self.viewport_slots.len();
        self.ensure_viewport_slot(device, idx);
        ViewportId(idx)
    }

    /// Release the heavy GPU texture memory (HDR targets, OIT, bloom, SSAO) held
    /// by `id`.
    ///
    /// The slot index is not reclaimed : future calls with this `ViewportId` will
    /// lazily recreate the texture resources as needed.  This is useful when a
    /// viewport is hidden or minimised and you want to reduce VRAM pressure without
    /// invalidating the handle.
    pub fn destroy_viewport(&mut self, id: ViewportId) {
        if let Some(slot) = self.viewport_slots.get_mut(id.0) {
            slot.hdr = None;
        }
    }

    /// Returns the owned-encoder rendering path.
    ///
    /// Use when you own the window loop and wgpu encoder (winit, raw wgpu).
    /// See [`OwnedPath`] for available methods.
    pub fn owned(&mut self) -> OwnedPath<'_> {
        OwnedPath { renderer: self }
    }

    /// Returns the pass-based rendering path.
    ///
    /// Use when a framework provides you with a render pass (eframe, iced).
    /// See [`PassPath`] for available methods.
    pub fn pass(&mut self) -> PassPath<'_> {
        PassPath { renderer: self }
    }

    /// Returns a read-only paint view for framework paint callbacks.
    ///
    /// Use this in callbacks where only a shared reference to the renderer is
    /// available (e.g. eframe's `CallbackTrait::paint` where `callback_resources`
    /// is `&CallbackResources`). Exposes only the paint methods, not prepare.
    pub fn pass_view(&self) -> PassView<'_> {
        PassView { renderer: self }
    }

    /// Prepare shared scene data.  Call **once per frame**, before any
    /// [`prepare_viewport`](Self::prepare_viewport) calls.
    ///
    /// `frame` provides the scene content (`frame.scene`) and the primary camera
    /// used for shadow cascade framing (`frame.camera`).  In a multi-viewport
    /// setup use any one viewport's `FrameData` here : typically the perspective
    /// view : as the shadow framing reference.
    ///
    /// `scene_effects` carries the scene-global effects: lighting, environment
    /// map, and compute filters.  Obtain it by constructing [`SceneEffects`]
    /// directly or via [`EffectsFrame::split`].
    pub(crate) fn prepare_scene(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        frame: &FrameData,
        scene_effects: &SceneEffects<'_>,
    ) {
        self.prepare_scene_internal(device, queue, frame, scene_effects);
    }

    /// Prepare per-viewport GPU state (camera, clip planes, overlays, axes).
    ///
    /// Call once per viewport per frame, **after** [`prepare_scene`](Self::prepare_scene).
    ///
    /// `id` must have been obtained from [`create_viewport`](Self::create_viewport).
    /// `frame.camera.viewport_index` must equal the slot for `id`; use
    /// [`CameraFrame::with_viewport_id`] when building the frame.
    pub(crate) fn prepare_viewport(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        id: ViewportId,
        frame: &FrameData,
    ) {
        debug_assert_eq!(
            frame.camera.viewport_index, id.0,
            "frame.camera.viewport_index ({}) must equal the ViewportId ({}); \
             use CameraFrame::with_viewport_id(id)",
            frame.camera.viewport_index, id.0,
        );
        let (_, viewport_fx) = frame.effects.split();
        self.prepare_viewport_internal(device, queue, frame, &viewport_fx);
    }

    /// Issue draw calls for `id` into a render pass with any lifetime.
    ///
    /// Identical to [`paint_viewport`](Self::paint_viewport) but accepts a render pass with a
    /// non-`'static` lifetime, making it usable from winit, iced, or raw wgpu where the encoder
    /// creates its own render pass.
    pub(crate) fn paint_viewport_to<'rp>(
        &self,
        render_pass: &mut wgpu::RenderPass<'rp>,
        id: ViewportId,
        frame: &FrameData,
    ) {
        let vp_idx = id.0;
        let camera_bg = self.viewport_camera_bind_group(vp_idx);
        let grid_bg = self.viewport_grid_bind_group(vp_idx);
        let vp_slot = self.viewport_slots.get(vp_idx);
        emit_draw_calls!(
            &self.resources,
            &mut *render_pass,
            frame,
            self.use_instancing,
            &self.instanced_batches,
            camera_bg,
            grid_bg,
            &self.compute_filter_results,
            vp_slot,
            &self.wireframe_bind_groups,
            &self.per_item_object_bind_groups
        );
        emit_scivis_draw_calls!(
            &self.resources,
            &mut *render_pass,
            &self.point_cloud_gpu_data,
            &self.glyph_gpu_data,
            &self.polyline_gpu_data,
            &self.volume_gpu_data,
            &self.streamtube_gpu_data,
            camera_bg,
            &self.tube_gpu_data,
            &self.image_slice_gpu_data,
            &self.tensor_glyph_gpu_data,
            &self.ribbon_gpu_data,
            &self.volume_surface_slice_gpu_data,
            &self.sprite_gpu_data,
            &self.mesh_instance_gpu_data,
            false
        );
        // Gaussian splats (alpha-blended, back-to-front sorted, no depth write).
        if !self.gaussian_splat_draw_data.is_empty() {
            if let Some(ref dual) = self.resources.gaussian_splat_pipeline {
                render_pass.set_pipeline(dual.for_format(false));
                render_pass.set_bind_group(0, camera_bg, &[]);
                for dd in &self.gaussian_splat_draw_data {
                    if dd.wireframe {
                        continue;
                    }
                    if let Some(set) = self.resources.gaussian_splat_store.get(dd.store_index) {
                        if let Some(Some(vp_sort)) = set.viewport_sort.get(dd.viewport_index) {
                            render_pass.set_bind_group(1, &vp_sort.render_bg, &[]);
                            render_pass.draw(0..6, 0..dd.count);
                        }
                    }
                }
            }
        }
        // TransparentVolumeMesh boundary wireframe overlay.
        if !self.tvm_wireframe_draws.is_empty() {
            if let Some(ref tvm_bg) = self.tvm_wireframe_bg {
                render_pass.set_bind_group(0, camera_bg, &[]);
                for mesh_id in &self.tvm_wireframe_draws {
                    if let Some(mesh) = self.resources.mesh_store.get(*mesh_id) {
                        render_pass.set_pipeline(&self.resources.wireframe_pipeline);
                        render_pass.set_bind_group(
                            2,
                            &self.resources.deform.dummy_bind_group,
                            &[],
                        );
                        render_pass.set_bind_group(1, tvm_bg, &[]);
                        render_pass.set_vertex_buffer(0, mesh.vertex_buffer.slice(..));
                        render_pass.set_index_buffer(
                            mesh.edge_index_buffer.slice(..),
                            wgpu::IndexFormat::Uint32,
                        );
                        render_pass.draw_indexed(0..mesh.edge_index_count, 0, 0..1);
                    }
                }
            }
        }
        // Shadow atlas viewer overlay.
        if frame.effects.show_shadow_atlas {
            render_pass.set_pipeline(&self.resources.shadow_atlas_viewer_pipeline);
            render_pass.set_bind_group(0, &self.resources.shadow_atlas_viewer_bg, &[]);
            render_pass.draw(0..6, 0..1);
        }
    }

    /// Return a reference to the camera bind group for the given viewport slot.
    ///
    /// Falls back to `resources.camera_bind_group` if no per-viewport slot
    /// exists (e.g. in single-viewport mode before the first prepare call).
    fn viewport_camera_bind_group(&self, viewport_index: usize) -> &wgpu::BindGroup {
        self.viewport_slots
            .get(viewport_index)
            .map(|slot| &slot.camera_bind_group)
            .unwrap_or(&self.resources.camera_bind_group)
    }

    /// Return a reference to the grid bind group for the given viewport slot.
    ///
    /// Falls back to `resources.grid_bind_group` if no per-viewport slot exists.
    fn viewport_grid_bind_group(&self, viewport_index: usize) -> &wgpu::BindGroup {
        self.viewport_slots
            .get(viewport_index)
            .map(|slot| &slot.grid_bind_group)
            .unwrap_or(&self.resources.grid_bind_group)
    }

    /// Ensure the dyn-res intermediate render target exists for `vp_idx` at the
    /// given `scaled_size`, creating or recreating it when size changes.
    ///
    /// `surface_size` is the native output dimensions (used to size the upscale
    /// blit correctly). `ensure_dyn_res_pipeline` is called automatically.
    pub(crate) fn ensure_dyn_res_target(
        &mut self,
        device: &wgpu::Device,
        vp_idx: usize,
        scaled_size: [u32; 2],
        surface_size: [u32; 2],
    ) {
        self.resources.ensure_dyn_res_pipeline(device);
        let needs_create = match &self.viewport_slots[vp_idx].dyn_res {
            None => true,
            Some(dr) => dr.scaled_size != scaled_size || dr.surface_size != surface_size,
        };
        if needs_create {
            let target = self
                .resources
                .create_dyn_res_target(device, scaled_size, surface_size);
            self.viewport_slots[vp_idx].dyn_res = Some(target);
        }
    }

    /// Ensure per-viewport HDR state exists for `viewport_index` at dimensions `w`×`h`.
    ///
    /// Calls `ensure_hdr_shared` once to initialise shared pipelines/BGLs/samplers, then
    /// lazily creates or resizes the `ViewportHdrState` inside the slot. Idempotent: if the
    /// slot already has HDR state at the correct size nothing is recreated.
    pub(crate) fn ensure_viewport_hdr(
        &mut self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        viewport_index: usize,
        w: u32,
        h: u32,
        ssaa_factor: u32,
        render_scale: f32,
    ) {
        let format = self.resources.target_format;
        // Ensure shared infrastructure (pipelines, BGLs, samplers) exists.
        self.resources.ensure_hdr_shared(device, queue, format);
        // When render_scale < 1.0, the HDR upscale path needs the dyn_res
        // pipeline and sampler for the final upscale-blit to output resolution.
        if render_scale < 1.0 - 0.001 {
            self.resources.ensure_dyn_res_pipeline(device);
        }
        // Compute the scene-resolution render target size.
        let scale = render_scale.clamp(0.1, 1.0);
        let scene_w = ((w as f32) * scale).round() as u32;
        let scene_h = ((h as f32) * scale).round() as u32;
        // Ensure the slot exists.
        self.ensure_viewport_slot(device, viewport_index);
        let slot = &mut self.viewport_slots[viewport_index];
        // Create or resize the per-viewport HDR state.
        let needs_create = match &slot.hdr {
            None => true,
            Some(s) => {
                s.output_size != [w, h]
                    || s.scene_size != [scene_w.max(1), scene_h.max(1)]
                    || s.ssaa_factor != ssaa_factor
            }
        };
        if needs_create {
            slot.hdr = Some(self.resources.create_hdr_viewport_state(
                device,
                queue,
                format,
                w,
                h,
                scene_w.max(1),
                scene_h.max(1),
                ssaa_factor,
            ));
        }
    }
}