grafo 0.17.0

//! Renderer for the Grafo library.
use ahash::{HashMap, HashMapExt};
use lyon::tessellation::FillTessellator;
use std::num::NonZeroUsize;
use std::sync::{Arc, RwLock};
use std::time::Duration;
use tracing::warn;
use wgpu::{BindGroup, BufferUsages, CompositeAlphaMode, SurfaceTarget};

#[cfg(feature = "render_metrics")]
use self::metrics::RenderLoopMetricsTracker;
use self::types::{DrawCommand, RendererScratch};
use crate::effect::{
    self, compile_composite_pipeline, compile_effect_pipeline, create_params_bind_group,
    EffectError, EffectInstance, LoadedEffect, OffscreenTexturePool,
};
use crate::pipeline::{
    compute_padded_bytes_per_row, create_and_depth_texture, create_argb_swizzle_bind_group,
    create_argb_swizzle_pipeline, create_msaa_color_texture, create_offscreen_color_texture,
    create_pipeline, create_readback_buffer, create_storage_input_buffer,
    create_storage_output_buffer, encode_copy_texture_to_buffer, render_buffer_range_to_texture,
    ArgbParams, PipelineType, Uniforms,
};
use crate::shape::{CachedShapeDrawData, DrawShapeCommand, Shape};
use crate::texture_manager::TextureManager;
use crate::util::{to_logical, PoolManager};
use crate::vertex::{InstanceColor, InstanceMetadata, InstanceTransform};
use crate::CachedShapeHandle;
pub use construction::RendererCreationError;

mod construction;
mod draw_queue;
mod effects;
#[cfg(feature = "render_metrics")]
pub mod metrics;
mod passes;
mod preparation;
mod readback;
mod rect_utils;
mod rendering;
mod surface;
mod traversal;
pub(crate) mod types;

pub type MathRect = lyon::math::Box2D;

// TODO: move to the config/constructor
const MAX_CACHED_SHAPES: usize = 1024;

/// Semantic texture layers for a shape. Background is layer 0, Foreground is layer 1.
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
pub enum TextureLayer {
    Background,
    Foreground,
}

impl From<TextureLayer> for usize {
    fn from(value: TextureLayer) -> Self {
        match value {
            TextureLayer::Background => 0,
            TextureLayer::Foreground => 1,
        }
    }
}

/// Controls whether a shape clips descendants attached to it in the draw tree.
#[derive(Copy, Clone, Debug, Default, Eq, PartialEq, Hash)]
pub enum ShapeOverflow {
    /// Descendants are clipped to this shape. This is the default.
    #[default]
    Hidden,
    /// Descendants can render outside this shape, while still inheriting ancestor clips.
    Visible,
}

/// The renderer for the Grafo library. This is the main struct used to render shapes and images.
///
/// A [`Renderer`] owns one render surface and one independent draw queue. Create a
/// [`RendererContext`] once and pass clones of it to additional renderers when multiple
/// windows should share the same GPU device, texture storage, and loaded-shape cache. Shape
/// cache keys are scoped to the context: use the same content-derived key to reuse a shape across
/// renderers, and avoid reusing a key for different shapes because loading or removing it affects
/// every renderer using the context.
#[derive(Clone)]
pub struct RendererContext {
    pub(crate) inner: Arc<RendererContextInner>,
}

pub(crate) struct RendererContextInner {
    pub(crate) instance: Arc<wgpu::Instance>,
    pub(crate) adapter: Arc<wgpu::Adapter>,
    pub(crate) device: Arc<wgpu::Device>,
    pub(crate) queue: Arc<wgpu::Queue>,
    pub(crate) texture_manager: TextureManager,
    pub(crate) shape_cache: RwLock<HashMap<u64, CachedShapeHandle>>,
}

pub struct Renderer<'a> {
    // Window information
    /// Size of the window in pixels.
    pub(crate) physical_size: (u32, u32),
    /// Scale factor of the window (e.g., for high-DPI displays).
    scale_factor: f64,

    /// AA fringe offset in physical pixels. Controls how far the anti-aliasing
    /// fringe extends outward from shape edges. Default is 0.75.
    fringe_width: f32,

    // WGPU components
    context: RendererContext,
    instance: Arc<wgpu::Instance>,
    surface: Option<wgpu::Surface<'a>>,
    device: Arc<wgpu::Device>,
    queue: Arc<wgpu::Queue>,
    config: wgpu::SurfaceConfiguration,

    tessellator: FillTessellator,
    buffers_pool_manager: PoolManager,
    texture_manager: TextureManager,

    /// Tree structure holding shapes to be rendered.
    draw_tree: easy_tree::Tree<DrawCommand>,
    /// Maps node metadata indices to their clip-parent node ids.
    metadata_to_clips: HashMap<usize, usize>,

    /// Uniforms for the stencil-increment ("and") rendering pipeline.
    and_uniforms: Uniforms,
    /// GPU buffer backing the "and" pipeline uniforms.
    and_uniform_buffer: wgpu::Buffer,
    /// Bind group for the stencil-increment rendering pipeline.
    and_bind_group: BindGroup,
    /// Render pipeline for stencil-increment operations.
    and_pipeline: Arc<wgpu::RenderPipeline>,
    /// Bind group layouts for shape texture layers (groups 1 and 2).
    shape_texture_bind_group_layout_background: Arc<wgpu::BindGroupLayout>,
    shape_texture_bind_group_layout_foreground: Arc<wgpu::BindGroupLayout>,
    /// Bind group layout for backdrop textures (group 3, bindings 3 and 4).
    backdrop_texture_bind_group_layout: Arc<wgpu::BindGroupLayout>,
    /// Monotonic counter to invalidate cached shape texture bind groups when the layout changes.
    shape_texture_layout_epoch: u64,
    /// Default transparent texture bind groups for both layers.
    default_shape_texture_bind_groups: [Arc<wgpu::BindGroup>; 2], // [background, foreground]
    /// Default transparent bind group for backdrop sampling.
    default_backdrop_texture_bind_group: Arc<wgpu::BindGroup>,

    /// Render pipeline for decrementing stencil values.
    decrementing_pipeline: Arc<wgpu::RenderPipeline>,
    /// Uniforms for the decrementing pipeline.
    decrementing_uniforms: Uniforms,
    /// GPU buffer backing the decrementing pipeline uniforms.
    decrementing_uniform_buffer: wgpu::Buffer,
    /// Bind group for the decrementing pipeline.
    decrementing_bind_group: BindGroup,

    temp_vertices: Vec<crate::vertex::CustomVertex>,
    temp_indices: Vec<u16>,

    /// Per-frame map from cache key to (index_start, index_count) in the
    /// aggregated buffers, used to avoid duplicating vertex/index data for
    /// cached shapes that share the same geometry.
    geometry_dedup_map: HashMap<u64, (usize, usize)>,

    /// Per-frame instance transforms for shapes.
    temp_instance_transforms: Vec<InstanceTransform>,
    /// Per-frame instance colors for shapes.
    temp_instance_colors: Vec<InstanceColor>,
    /// Per-frame instance metadata (draw order) for shapes.
    temp_instance_metadata: Vec<InstanceMetadata>,

    aggregated_vertex_buffer: Option<wgpu::Buffer>,
    aggregated_index_buffer: Option<wgpu::Buffer>,
    aggregated_instance_transform_buffer: Option<wgpu::Buffer>,
    aggregated_instance_color_buffer: Option<wgpu::Buffer>,
    aggregated_instance_metadata_buffer: Option<wgpu::Buffer>,

    identity_instance_transform_buffer: Option<wgpu::Buffer>,
    identity_instance_color_buffer: Option<wgpu::Buffer>,
    identity_instance_metadata_buffer: Option<wgpu::Buffer>,

    // Cached resources for render_to_argb32 compute swizzle path
    argb_cs_bgl: Option<wgpu::BindGroupLayout>,
    argb_cs_pipeline: Option<wgpu::ComputePipeline>,
    argb_swizzle_bind_group: Option<wgpu::BindGroup>,
    argb_params_buffer: Option<wgpu::Buffer>,
    argb_input_buffer: Option<wgpu::Buffer>,
    argb_output_storage_buffer: Option<wgpu::Buffer>,
    argb_readback_buffer: Option<wgpu::Buffer>,
    argb_input_buffer_size: u64,
    argb_output_buffer_size: u64,
    argb_cached_width: u32,
    argb_cached_height: u32,
    argb_offscreen_texture: Option<wgpu::Texture>,

    // Cached resources for render_to_buffer (BGRA bytes) path
    rtb_offscreen_texture: Option<wgpu::Texture>,
    rtb_readback_buffer: Option<wgpu::Buffer>,
    rtb_cached_width: u32,
    rtb_cached_height: u32,

    /// Current MSAA sample count (1 = off, 4 = 4x, etc.)
    msaa_sample_count: u32,

    /// The multisampled color texture (None when sample_count == 1).
    msaa_color_texture: Option<wgpu::Texture>,
    /// View of the MSAA color texture.
    msaa_color_texture_view: Option<wgpu::TextureView>,

    /// Cached depth/stencil texture, reused across frames.
    /// Recreated on resize or MSAA sample count change.
    depth_stencil_texture: Option<wgpu::Texture>,
    /// View of the cached depth/stencil texture.
    depth_stencil_view: Option<wgpu::TextureView>,

    // ── Effect system ──────────────────────────────────────────────────
    /// Loaded (compiled) effects, keyed by user-provided effect_id.
    loaded_effects: HashMap<u64, LoadedEffect>,
    /// Per-node group effect instances, keyed by node_id.
    group_effects: HashMap<usize, EffectInstance>,
    /// Per-node backdrop effect instances, keyed by node_id.
    /// A backdrop effect processes the pixels already rendered behind a shape.
    backdrop_effects: HashMap<usize, EffectInstance>,
    /// Pool of offscreen textures for effect compositing.
    offscreen_texture_pool: OffscreenTexturePool,
    /// Shared composite pipeline for drawing effect results into the parent target.
    /// Created lazily on first use.
    composite_pipeline: Option<wgpu::RenderPipeline>,
    /// Bind group layout for the composite pipeline's input texture.
    composite_bgl: Option<wgpu::BindGroupLayout>,
    /// Reusable sampler for effect texture sampling.
    effect_sampler: Option<wgpu::Sampler>,

    // ── Backdrop effect infrastructure ─────────────────────────────────
    /// Fullscreen sampling pipeline used to downsample a captured backdrop region.
    texture_blit_pipeline: Option<wgpu::RenderPipeline>,
    /// Stencil-only pipeline: writes stencil but no color output.
    /// Used for Step 1 of the three-step backdrop draw.
    stencil_only_pipeline: Option<wgpu::RenderPipeline>,
    /// Shape color pipeline with stencil Keep: draws color but doesn't modify stencil.
    /// Used for Step 3 of the three-step backdrop draw.
    backdrop_color_pipeline: Option<wgpu::RenderPipeline>,
    /// Gradient color pipeline with stencil Keep for backdrop shapes.
    backdrop_color_gradient_pipeline: Option<wgpu::RenderPipeline>,

    /// Pipeline for rendering leaf nodes (no children) with stencil Equal + Keep.
    /// Avoids the redundant increment + decrement pair for childless shapes.
    leaf_draw_pipeline: Arc<wgpu::RenderPipeline>,
    /// Gradient pipeline for leaf nodes.
    leaf_draw_gradient_pipeline: Arc<wgpu::RenderPipeline>,
    /// Gradient pipeline for visible non-leaf parents that increment stencil.
    and_gradient_pipeline: Arc<wgpu::RenderPipeline>,

    // ── Gradient fill infrastructure ───────────────────────────────────
    /// Bind group layout for gradient resources (group 3 in shader).
    gradient_bind_group_layout: wgpu::BindGroupLayout,
    /// Bind group layout for gradient resources plus backdrop sampling.
    backdrop_gradient_bind_group_layout: wgpu::BindGroupLayout,
    /// Monotonic counter to invalidate cached gradient bind groups when the layout changes.
    gradient_bind_group_layout_epoch: u64,
    /// Sampler for gradient ramp textures (nearest, clamp-to-edge).
    gradient_ramp_sampler: wgpu::Sampler,

    #[cfg(feature = "render_metrics")]
    /// Tracking for cumulative render-loop timing metrics.
    render_loop_metrics_tracker: RenderLoopMetricsTracker,

    #[cfg(feature = "render_metrics")]
    /// Per-phase timing breakdown for the most recently rendered frame.
    last_phase_timings: self::metrics::PhaseTimings,

    #[cfg(feature = "render_metrics")]
    /// Per-frame pipeline switch counts for the most recently rendered frame.
    last_pipeline_switch_counts: self::metrics::PipelineSwitchCounts,

    /// Wall-clock CPU time spent inside the most recent `render_to_texture_view()` call.
    ///
    /// This measures CPU-side traversal planning, render/effect pass encoding,
    /// and `queue.submit`, but excludes presentation, readback mapping, and any
    /// forced GPU waits after submission.
    last_render_to_texture_view_cpu_time: Duration,

    // ── Reusable scratch state ───────────────────────────────────────────
    scratch: RendererScratch,
}

/// Default AA fringe width in physical pixels.
const DEFAULT_FRINGE_WIDTH: f32 = 0.75;

impl<'a> Renderer<'a> {
    const DEFAULT_FRINGE_WIDTH: f32 = DEFAULT_FRINGE_WIDTH;

    pub(super) fn begin_frame_scratch(&mut self) {
        self.scratch.begin_frame();
    }

    pub(super) fn trim_scratch_on_resize_or_policy(&mut self) {
        // This is safe to call frequently: `shrink_to` is effectively a no-op
        // when capacities are below thresholds, so this acts as amortized
        // memory hygiene for long-running sessions.
        self.buffers_pool_manager.trim();
        self.scratch.trim_to_policy();
    }

    /// Returns the wall-clock CPU time spent in the most recent `render_to_texture_view()` call.
    pub fn last_render_to_texture_view_cpu_time(&self) -> Duration {
        self.last_render_to_texture_view_cpu_time
    }
}