facett-core 0.1.16

//! **The L0 GPU lane** (feature `wgpu`) — the extracted shared scaffold the three
//! skin kernels (facett-map `GpuMapRenderer`, facett-map3d `Map3dRenderer`,
//! facett-graph3d `LogoRenderer`) will be re-pointed at in Phase C.
//!
//! All three share the identical `egui_wgpu::CallbackTrait` plumbing: a `*Renderer`
//! stored in `callback_resources`, **installed once** via an `install_renderer`,
//! driven by a paint callback. Phase A extracts:
//!
//! - [`types`] — the bytemuck `Vertex`/`Uniform`/`DrawIndirectArgs` structs +
//!   `color32_to_f32` (byte-identical to the skins' copies).
//! - [`buffer`] — the upload-once + **chunking** algorithm (fix #12), verbatim.
//! - [`install_renderer`] — the install-once lifecycle each kernel hand-rolls.
//! - [`CULL_WGSL`] / [`DRAW_WGSL`] — the cull + draw shaders, **byte-identical** to
//!   `facett-map/src/gpu/*.wgsl` (do not change their semantics).
//!
//! Nothing in the skins consumes this yet — it is the scaffold for Phase B/C.

/// **wgpu glue for the adapter-selection policy** — `wgpu::AdapterInfo` →
/// [`AdapterFacts`](crate::render::adapter::AdapterFacts), the live selector, the
/// `request_best_adapter` replacement for the naive headless probes, and the
/// `egui_wgpu::WgpuConfiguration` an eframe host installs. See [`adapter_wgpu`].
pub mod adapter_wgpu;
pub mod blur;
pub mod buffer;
/// **THE shared instanced graph-cloud renderer** — screen-space emissive node discs
/// + edge filaments as GPU instances, plus the live `egui_wgpu` paint callback and
/// its install-once lifecycle. Consumed by `facett-graph3d` (which re-exports it as
/// `graph_gpu`) AND by the 2-D graph family (`facett-graphpan` / `facett-graphview` /
/// `facett-graphnav`). See [`graphcloud`].
pub mod graphcloud;
/// **Final-look colour grade** (AgX tonemap + vignette + film grain + CAS sharpen +
/// blue-noise-style dither) as an optional post over the HDR offscreen colour — a
/// new, composable seam that does **not** touch the map3d ACES tonemap. See
/// [`colorgrade`].
pub mod colorgrade;
/// **GPU label collision + the indirect label draw** (GFX_V2 §3.B item 4) — three
/// compute passes over a fixed spatial grid whose third pass *produces the draw* by
/// `atomicAdd`ing onto a `DrawIndirectArgs`. The collision rule itself lives in
/// [`crate::label_grid`]; the WGSL here is its device transcription. See
/// [`label_collide`].
pub mod label_collide;
/// **MSDF text / label rendering** — crisp glowing labels at any zoom from a
/// multi-channel signed-distance-field atlas. See [`msdf`].
pub mod msdf;
pub mod offscreen;
/// **The in-GPU pass clock** — TIMESTAMP_QUERY around a lane's encoded passes,
/// resolved through a non-blocking readback ring into the per-lane clock stats
/// (`crate::render::lane::clock_stats_of`). Feature-detected; a device without the
/// feature reports `None`, never `0`. See [`pass_clock`].
pub mod pass_clock;
/// **OIT — order-independent transparency via per-pixel fragment linked lists**
/// (GFX_V2 §3.C item 7): gather every translucent fragment onto its pixel's list,
/// then sort and composite per pixel in one fullscreen resolve. See [`oit`].
pub mod oit;
/// **GPU picking — the colour-encoded ID pass** (GFX_V2 §7 item 8): render pickable
/// geometry into an `R32Uint` target where the value IS the [`PickId`](crate::engine::pick::PickId),
/// then read back the texel under the cursor. See [`picking`].
pub mod picking;
/// **The host lane for GPU picking** — install-once + the one `pick_at` entry point a
/// widget calls to turn a click into a `PickId`. See [`pick_host`].
pub mod pick_host;
/// **GPU compute particles** — storage-buffer boids stepped in a compute shader and
/// drawn as soft additive points into the HDR target. See [`particles`].
pub mod particles;
/// **THE one GPU→CPU readback** — the `map_async` + row-padding dance, spelled once
/// instead of in seventeen hand-rolled copies. See [`readback`].
pub mod readback;
pub mod sdf_pipeline;
/// **TAA — Halton jitter + a velocity-reprojecting temporal resolve** (GFX_V2 §5
/// item 7): the fix for sub-pixel vector lines shimmering under camera motion, which
/// MSAA cannot solve. See [`taa`].
pub mod taa;
pub mod types;

pub use adapter_wgpu::{
    decide_for, facett_wgpu_options, facts_of, facts_of_all, kind_of, preferred_backends,
    request_best_adapter, select_adapter,
};
pub use blur::{gaussian_taps, GaussianBlur, BLUR_WGSL};
pub use graphcloud::{
    render_graph_offscreen, BloomParams, EdgeInstance, GraphGpu, GraphRender, GraphScene,
    NodeInstance,
};
pub use buffer::{
    ChunkSpan, chunk_budget, chunk_budget_stride, partition_chunks, partition_chunks_stride,
    rebase_chunk_meta,
};
pub use colorgrade::{
    agx_tonemap, ign, srgb_oetf, vignette_factor, ColorGrade, ColorGradeParams, COLORGRADE_WGSL,
};
pub use label_collide::{
    LabelCollider, LabelStats, LABEL_COLLIDE_WGSL, LABEL_DRAW_WGSL, LABEL_GLYPH_CAPACITY,
};
pub use msdf::{
    coverage, disk_msdf_atlas, median3, screen_px_range, GlyphInstance, MsdfText, MSDF_WGSL,
};
pub use particles::{
    advect_cpu, step_cpu, DrawParams, FlowGeometry, GpuParticles, Particle, ParticleBuffers,
    SimParams, PARTICLES_WGSL,
};
pub use offscreen::{
    gpu_scissor_px, scissor_intersection, OffscreenColorDepth, ScissorPx, BLIT_WGSL, DEPTH_FORMAT,
    OFFSCREEN_FORMAT,
};
pub use oit::{
    OitBatch, OitPass, OitVertex, OIT_DEFAULT_LAYERS, OIT_MAX_LAYERS, OIT_NODE_SIZE,
    OIT_VERTEX_STRIDE, OIT_WGSL,
};
pub use pass_clock::{PassClock, PassClockSlot, PASS_CLOCK_FEATURES};
pub use pick_host::{install_pick_host, pick_at, pick_host_installed, pick_passes_run, PickHost};
pub use readback::{map_read_all, read_buffer_range, read_texture_region, strip_row_padding};
pub use taa::{
    halton, history_weight, jitter_px, TaaPass, TAA_FEEDBACK_CAP, TAA_PHASES, TAA_WGSL,
};
pub use picking::{
    logical_to_texel, painter_depth, PickBatch, PickPass, PickTarget, PickVertex,
    PICK_DEPTH_FORMAT, PICK_FORMAT, PICK_VERTEX_STRIDE, PICK_WGSL,
};
pub use sdf_pipeline::{
    GpuSdfHeadless, GpuSdfRenderer, SdfUniforms, offscreen_render, LINE_WGSL, SDF_WGSL,
};
pub use types::{
    DrawIndirectArgs, DrawUniforms, GpuWayMeta, Vertex, ViewportCull, color32_to_f32,
    rebase_vertex_origin,
};

/// **THE shared WGSL prelude** — `px_to_ndc`, `coverage_from_sd`, `coverage_inside`
/// and `resolve_line_width_px`, the geometry maths every facett line/SDF shader
/// needs. WGSL has no `#include`, so it is prepended as text by [`wgsl`]. See
/// `common.wgsl` for why each function is bit-identical to the copies it replaced.
pub const COMMON_WGSL: &str = include_str!("common.wgsl");

/// Compose a shader: [`COMMON_WGSL`] followed by `body`.
///
/// **The one composer.** Every `create_shader_module` in facett that wants the shared
/// maths goes through here — facett-core's SDF/line/draw pipelines and facett-map's
/// pretty-line pipeline alike — so the prelude cannot be attached two different ways.
#[must_use]
pub fn wgsl(body: &str) -> String {
    let mut s = String::with_capacity(COMMON_WGSL.len() + body.len() + 1);
    s.push_str(COMMON_WGSL);
    s.push('\n');
    s.push_str(body);
    s
}

/// The GPU frustum-cull + LOD + stream-compaction compute shader — the country-scale
/// chunked pipeline. **The single copy**: facett-map's `GpuMapRenderer` builds its
/// compute pipeline from this constant (it used to hold a byte-identical twin at
/// `facett-map/src/gpu/cull.wgsl`, watched by a guard test; the twin is gone, so
/// there is nothing left to drift). The chunking partition in [`buffer`] keeps this
/// per-way shader unchanged.
pub const CULL_WGSL: &str = include_str!("cull.wgsl");

/// The line-draw vertex/fragment shader for OSM ways — **the single copy**, consumed
/// by facett-map's `GpuMapRenderer` (its byte-identical twin at
/// `facett-map/src/gpu/draw.wgsl` is gone). Needs the [`COMMON_WGSL`] prelude:
/// compose it with [`wgsl`].
pub const DRAW_WGSL: &str = include_str!("draw.wgsl");

/// **Install-once** lifecycle, generic over the renderer type — the pattern all
/// three skin kernels hand-roll (`install_renderer` in facett-map / facett-map3d /
/// facett-graph3d). If a renderer of type `R` is already in the egui-wgpu
/// `RenderState`'s `callback_resources`, this is a no-op; otherwise `make` builds
/// one (from the device + target format) and inserts it. Hosts call this once at
/// startup so the paint callback can `resources.get::<R>()`.
///
/// Returns `true` if a renderer was newly installed, `false` if one already existed.
///
/// It also **registers the lane** with [`crate::render::lane`] under
/// `std::any::type_name::<R>()`, whether or not this call did the inserting. That is
/// how an About box can say "a GPU lane is installed" without every lane wiring
/// itself up: the one install writer is the one place that knows. A lane that also
/// counts frames declares it next to its own install
/// ([`lane::note_reports_frames`](crate::render::lane::note_reports_frames)).
pub fn install_renderer<R, F>(render_state: &egui_wgpu::RenderState, make: F) -> bool
where
    R: 'static + Send + Sync,
    F: FnOnce(&wgpu::Device, wgpu::TextureFormat) -> R,
{
    crate::render::lane::note_installed(std::any::type_name::<R>());
    if render_state.renderer.read().callback_resources.get::<R>().is_some() {
        return false; // already installed
    }
    let renderer = make(&render_state.device, render_state.target_format);
    render_state.renderer.write().callback_resources.insert(renderer);
    true
}

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

    /// The cull shader's per-way contract (6 u32 words/vertex) is unchanged.
    ///
    /// This replaces `shaders_are_byte_identical_to_facett_map`, which compared this
    /// constant against `include_str!("../../../../facett-map/src/gpu/cull.wgsl")`.
    /// That guard is deleted rather than kept: facett-map no longer HAS its own copy
    /// (LAW #5 — fixed by construction, not by a watcher), and the cross-crate
    /// `include_str!` it needed reached outside this crate's package directory, so it
    /// only ever resolved inside the monorepo checkout.
    ///
    /// `VPV` is an `override`, not a `const`, so ONE cull shader compacts both the
    /// 24 B `Vertex` stream (default, 6 words) and the 48 B `LineVertex` quad stream
    /// (11 words) — see `facett-map`'s `line_cull_pipeline`. The default must stay 6
    /// so a pipeline that sets no constants is unchanged.
    #[test]
    fn cull_shader_keeps_its_per_way_contract() {
        assert!(CULL_WGSL.contains("override VPV: u32 = 6u;"), "VPV is overridable and still defaults to 6");
        assert!(!CULL_WGSL.contains("const VPV"), "VPV must not go back to a baked const — that forces a twin shader");
        assert!(CULL_WGSL.contains("@workgroup_size(64)"));
    }

    /// The shared prelude really is prepended, and the bodies really do delegate: a
    /// shader body that declared its own `px_to_ndc` would collide at compile time,
    /// and one that never calls it would have silently kept a private copy.
    #[test]
    fn every_shared_shader_takes_its_maths_from_the_one_prelude() {
        for (name, body) in
            [("sdf", SDF_WGSL), ("line", LINE_WGSL), ("draw", DRAW_WGSL), ("oit", OIT_WGSL)]
        {
            assert!(
                !body.contains("fn px_to_ndc"),
                "{name}.wgsl re-declares px_to_ndc instead of using the prelude"
            );
            assert!(
                !body.contains("fn coverage_from_sd"),
                "{name}.wgsl re-declares coverage_from_sd instead of using the prelude"
            );
            assert!(body.contains("px_to_ndc("), "{name}.wgsl calls the shared px_to_ndc");
            let composed = wgsl(body);
            assert!(composed.starts_with(COMMON_WGSL), "{name}.wgsl is composed prelude-first");
            assert!(composed.contains("fn px_to_ndc"), "the composed {name} module defines px_to_ndc once");
            assert_eq!(
                composed.matches("fn px_to_ndc").count(),
                1,
                "exactly ONE definition of px_to_ndc reaches the {name} shader module"
            );
        }
        // The prelude carries the maths the "two scales of land and lines" bug lived
        // in, so facett-map's line lane can share it rather than re-spell it.
        assert!(COMMON_WGSL.contains("fn resolve_line_width_px"));
        assert!(COMMON_WGSL.contains("fn coverage_inside"));
    }
}