@bloomengine/engine 0.3.1

package/native/shared/src/renderer/material_pipeline.rs

@@ -0,0 +1,604 @@
+// Material pipeline — the entry point for custom WGSL materials against
+// the ABI described in docs/rfc/0001-material-render-graph.md.
+//
+// This module is deliberately self-contained. It owns the bind-group
+// layouts, pipeline-layout composition, and the preprocessor driver.
+// The rest of the renderer doesn't know or care how a material is
+// compiled — it just receives a `MaterialPipeline` and uses the
+// layouts for binding groups that the shader declares it consumes.
+//
+// Phase 1b scope: everything needed to *compile* a material pipeline
+// from user WGSL against the ABI. Draw dispatch, per-draw uniform
+// writes, and FFI glue all land in follow-up phases.
+
+use super::shader_include::{BakedSource, IncludeError, process};
+
+// =====================================================================
+// Bind-group layouts — one struct, five layouts, matching RFC §1
+// =====================================================================
+
+/// The five bind-group layouts every ABI-compliant pipeline binds.
+/// Owned by Renderer once per process (not per pipeline). Cheap to clone
+/// references since `wgpu::BindGroupLayout` is Arc'd internally.
+pub struct MaterialAbiLayouts {
+    pub per_frame:        wgpu::BindGroupLayout,
+    pub per_view:         wgpu::BindGroupLayout,
+    pub per_material:     wgpu::BindGroupLayout,
+    pub per_draw:         wgpu::BindGroupLayout,
+    pub scene_inputs:     wgpu::BindGroupLayout,
+}
+
+impl MaterialAbiLayouts {
+    pub fn create(device: &wgpu::Device) -> Self {
+        Self {
+            per_frame:    create_per_frame_layout(device),
+            per_view:     create_per_view_layout(device),
+            per_material: create_per_material_layout(device),
+            per_draw:     create_per_draw_layout(device),
+            scene_inputs: create_scene_inputs_layout(device),
+        }
+    }
+}
+
+fn create_per_frame_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout {
+    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("abi_per_frame"),
+        entries: &[wgpu::BindGroupLayoutEntry {
+            binding: 0,
+            visibility: wgpu::ShaderStages::VERTEX | wgpu::ShaderStages::FRAGMENT,
+            ty: wgpu::BindingType::Buffer {
+                ty: wgpu::BufferBindingType::Uniform,
+                has_dynamic_offset: false,
+                min_binding_size: None,
+            },
+            count: None,
+        }],
+    })
+}
+
+fn create_per_view_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout {
+    // Mirror of the ABI header: UBO at 0, env colour + sampler at 1+2,
+    // env diffuse at 3, BRDF LUT + sampler at 4+5, three cascades at
+    // 6..8, comparison sampler at 9.
+    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("abi_per_view"),
+        entries: &[
+            entry_ubo(0, wgpu::ShaderStages::VERTEX | wgpu::ShaderStages::FRAGMENT),
+            entry_tex_f(1, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(2, wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_f(3, wgpu::ShaderStages::FRAGMENT),
+            entry_tex_f(4, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(5, wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_depth(6, wgpu::ShaderStages::FRAGMENT),
+            entry_tex_depth(7, wgpu::ShaderStages::FRAGMENT),
+            entry_tex_depth(8, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(9, wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Comparison),
+        ],
+    })
+}
+
+fn create_per_material_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout {
+    // PBR texture + sampler pairs: base, normal, mr, emissive, occlusion.
+    // Bindings 0..9 are texture/sampler pairs. Binding 10 is
+    // MaterialFactors UBO. Binding 11 is the user_params UBO (shader-
+    // defined type; 256-byte cap enforced by the pipeline-creation
+    // helper, not by the layout itself). Bindings 12 (texture) + 13
+    // (sampler) are the EN-011 planar reflection RT — bound to the
+    // engine's 1×1 black default for materials without a probe so
+    // unconditional sampling is always safe. Bindings 14/15/16/17 are
+    // the EN-014 texture-array slots (albedo / normal / MR + a shared
+    // sampler) for splat-mapped terrain materials — bound to a 1×1×1
+    // black stub array when a material doesn't declare its own.
+    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("abi_per_material"),
+        entries: &[
+            entry_tex_f(0,  wgpu::ShaderStages::FRAGMENT),
+            entry_samp(1,   wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_f(2,  wgpu::ShaderStages::FRAGMENT),
+            entry_samp(3,   wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_f(4,  wgpu::ShaderStages::FRAGMENT),
+            entry_samp(5,   wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_f(6,  wgpu::ShaderStages::FRAGMENT),
+            entry_samp(7,   wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_f(8,  wgpu::ShaderStages::FRAGMENT),
+            entry_samp(9,   wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_ubo(10,   wgpu::ShaderStages::VERTEX | wgpu::ShaderStages::FRAGMENT),
+            entry_ubo(11,   wgpu::ShaderStages::VERTEX | wgpu::ShaderStages::FRAGMENT),
+            // EN-011 — planar reflection RT (texture + sampler).
+            entry_tex_f(12, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(13,  wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            // EN-014 — texture-array slots for splat-mapped terrain.
+            entry_tex_f_array(14, wgpu::ShaderStages::FRAGMENT),
+            entry_tex_f_array(15, wgpu::ShaderStages::FRAGMENT),
+            entry_tex_f_array(16, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(17, wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+        ],
+    })
+}
+
+fn create_per_draw_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout {
+    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("abi_per_draw"),
+        entries: &[
+            entry_ubo(0, wgpu::ShaderStages::VERTEX | wgpu::ShaderStages::FRAGMENT),
+            entry_ubo(1, wgpu::ShaderStages::VERTEX),   // JointMatrices (1024 × mat4)
+        ],
+    })
+}
+
+fn create_scene_inputs_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout {
+    device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
+        label: Some("abi_scene_inputs"),
+        entries: &[
+            entry_tex_f(0,     wgpu::ShaderStages::FRAGMENT),
+            entry_samp(1,      wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::Filtering),
+            entry_tex_depth(2, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(3,      wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::NonFiltering),
+            // Phase 7 — impulse_tex is R32Float which is non-filterable
+            // in wgpu 29 without a feature flag, so the binding is
+            // declared NonFiltering. Materials sample via textureLoad
+            // (no filtering; 0.5 m / texel is already coarse).
+            entry_tex_f_nonfilt(4, wgpu::ShaderStages::FRAGMENT),
+            entry_samp(5,      wgpu::ShaderStages::FRAGMENT, wgpu::SamplerBindingType::NonFiltering),
+            entry_tex_f(6,     wgpu::ShaderStages::FRAGMENT),
+        ],
+    })
+}
+
+fn entry_tex_f_nonfilt(binding: u32, vis: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Texture {
+            sample_type: wgpu::TextureSampleType::Float { filterable: false },
+            view_dimension: wgpu::TextureViewDimension::D2,
+            multisampled: false,
+        },
+        count: None,
+    }
+}
+
+// Small helpers for binding entry construction.
+fn entry_ubo(binding: u32, vis: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Buffer {
+            ty: wgpu::BufferBindingType::Uniform,
+            has_dynamic_offset: false,
+            min_binding_size: None,
+        },
+        count: None,
+    }
+}
+fn entry_tex_f(binding: u32, vis: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Texture {
+            sample_type: wgpu::TextureSampleType::Float { filterable: true },
+            view_dimension: wgpu::TextureViewDimension::D2,
+            multisampled: false,
+        },
+        count: None,
+    }
+}
+/// EN-014 — `texture_2d_array<f32>` binding entry. Used for the
+/// splat-mapped terrain slots (albedo / normal / MR arrays) at
+/// bindings 14/15/16. Filterable so games can use linear filtering
+/// per-layer.
+fn entry_tex_f_array(binding: u32, vis: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Texture {
+            sample_type: wgpu::TextureSampleType::Float { filterable: true },
+            view_dimension: wgpu::TextureViewDimension::D2Array,
+            multisampled: false,
+        },
+        count: None,
+    }
+}
+fn entry_tex_depth(binding: u32, vis: wgpu::ShaderStages) -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Texture {
+            sample_type: wgpu::TextureSampleType::Depth,
+            view_dimension: wgpu::TextureViewDimension::D2,
+            multisampled: false,
+        },
+        count: None,
+    }
+}
+fn entry_samp(binding: u32, vis: wgpu::ShaderStages, ty: wgpu::SamplerBindingType)
+              -> wgpu::BindGroupLayoutEntry {
+    wgpu::BindGroupLayoutEntry {
+        binding, visibility: vis,
+        ty: wgpu::BindingType::Sampler(ty),
+        count: None,
+    }
+}
+
+// =====================================================================
+// Fragment output profile — opaque or translucent
+// =====================================================================
+
+/// Fragment output profile a material declares. Decides the pipeline's
+/// colour attachment layout and blend state. See ABI §1.8.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum FragmentProfile {
+    /// Four MRT attachments: HDR, material, velocity, albedo.
+    Opaque,
+    /// Single HDR attachment, alpha-blended. Does not write depth.
+    Translucent,
+}
+
+/// Scheduling bucket — tells the render graph which pass a draw
+/// belongs in and what sort order to apply. Distinct from
+/// `FragmentProfile` (which describes pipeline outputs): a material
+/// with profile `Translucent` could be in either `Transparent` or
+/// `Refractive`, and `Additive` is its own bucket even though it
+/// shares attachment layout with `Transparent`.
+///
+/// See RFC 0001 §3.2.
+#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
+pub enum Bucket {
+    /// Opaque draws. Front-to-back sort for early-z efficiency. Runs
+    /// in the main HDR pass; writes the full 4-MRT G-buffer.
+    Opaque,
+    /// Alpha-cutout draws (foliage cards, chain-link fences, leaf
+    /// silhouettes). Runs in the opaque pass with full G-buffer write
+    /// + sun shadow + SSAO, but the fragment shader is expected to
+    /// `discard` against `MaterialFactors.alpha_cutoff`. Rendered
+    /// double-sided so foliage is visible from both faces.
+    Cutout,
+    /// Translucent draws. Back-to-front sort for correct blending.
+    /// Single HDR attachment, alpha-blended, depth-test without
+    /// depth-write. Runs in the translucent sub-pass (Phase 4b).
+    Transparent,
+    /// Translucent + reads the scene colour snapshot (for refraction,
+    /// Fresnel, shoreline effects). Same pass + sort as Transparent
+    /// but the graph inserts a SceneColor snapshot before this
+    /// bucket runs.
+    Refractive,
+    /// Additive-blend draws — particle flares, sparks, weapon
+    /// glows. Order-independent, so no sort needed. Runs in the
+    /// translucent sub-pass.
+    Additive,
+}
+
+impl Bucket {
+    /// True if this bucket dispatches in the translucent sub-pass
+    /// (single HDR attachment, alpha/additive blending) rather than
+    /// the main HDR pass.
+    pub fn is_translucent(self) -> bool {
+        matches!(self, Bucket::Transparent | Bucket::Refractive | Bucket::Additive)
+    }
+    /// True if this bucket requires a SceneColor snapshot before it
+    /// runs. Only Refractive does today; future buckets (e.g.
+    /// VolumetricFog) may join.
+    pub fn needs_scene_color(self) -> bool {
+        matches!(self, Bucket::Refractive)
+    }
+}
+
+// =====================================================================
+// Material pipeline — the compiled artefact
+// =====================================================================
+
+/// A pipeline ready to receive draws. Owns only the `RenderPipeline`;
+/// the layouts are borrowed from the shared `MaterialAbiLayouts`.
+pub struct MaterialPipeline {
+    pub pipeline: wgpu::RenderPipeline,
+    pub profile:  FragmentProfile,
+    pub bucket:   Bucket,
+    pub reads_scene: bool,
+    /// EN-001 — true when the pipeline was compiled with the
+    /// per-instance vertex layout (slot 1, step_mode = Instance). The
+    /// dispatch site uses this as a sanity flag — it doesn't change
+    /// what bind groups get bound, only which `set_vertex_buffer(1, …)`
+    /// path runs for a given draw command.
+    pub wants_instancing: bool,
+    /// Label carried through for debug output.
+    pub label: String,
+    /// EN-011 V2 — sibling pipeline with front-face culling for use in
+    /// planar reflection passes. Reflection inverts triangle winding,
+    /// so an opaque material that would normally cull back-faces needs
+    /// to cull front-faces in the mirrored pass — otherwise single-
+    /// sided geometry renders inside-out. Lazily compiled the first
+    /// time the material gets linked to a probe via
+    /// `MaterialSystem::set_reflection_probe`. Reuses the main
+    /// pipeline's shader module — the only difference is `cull_mode`.
+    ///
+    /// `None` for materials whose original cull mode is already
+    /// `None` (translucent, cutout) — flipping a non-culled pipeline
+    /// is a no-op so we don't bother compiling a duplicate.
+    pub reflection_pipeline: Option<wgpu::RenderPipeline>,
+}
+
+/// Options passed to compile a material. Matches the material-descriptor
+/// shape in RFC §3.1, minus the textures / parameters (those are game
+/// data, set per draw).
+pub struct MaterialCompileDesc<'a> {
+    pub label:         &'a str,
+    pub entry_path:    &'a str,                 // e.g. "materials/water.wgsl"
+    /// Additional (path, source) entries layered over the baked library.
+    /// Game-supplied shaders live here.
+    pub extra_sources: &'a [(&'a str, &'a str)],
+    pub profile:       FragmentProfile,
+    pub bucket:        Bucket,
+    pub reads_scene:   bool,
+    pub hdr_format:    wgpu::TextureFormat,
+    pub material_format: wgpu::TextureFormat,
+    pub velocity_format: wgpu::TextureFormat,
+    pub albedo_format:   wgpu::TextureFormat,
+    pub depth_format:    wgpu::TextureFormat,
+    pub vertex_buffers:  &'a [wgpu::VertexBufferLayout<'a>],
+    /// EN-001 — when true, `compile_material` appends
+    /// `InstanceData3D::desc()` to `vertex_buffers` so the pipeline
+    /// expects a second VB at slot 1 with step_mode = Instance.
+    pub wants_instancing: bool,
+}
+
+#[derive(Debug)]
+pub enum MaterialCompileError {
+    Include(IncludeError),
+    Naga(String),
+    Wgpu(String),
+}
+impl From<IncludeError> for MaterialCompileError {
+    fn from(e: IncludeError) -> Self { MaterialCompileError::Include(e) }
+}
+
+/// Compile a material pipeline. This is the happy-path you call at
+/// `loadMaterial()` time.
+pub fn compile_material(
+    device: &wgpu::Device,
+    layouts: &MaterialAbiLayouts,
+    desc: &MaterialCompileDesc<'_>,
+) -> Result<MaterialPipeline, MaterialCompileError> {
+    // 1. Resolve #include chain against the baked library +
+    //    game-supplied overlay.
+    let baked_entries = BAKED_ENTRIES_SNAPSHOT;    // from library snapshot below
+    let mut entries: Vec<(&str, &str)> = baked_entries.to_vec();
+    for &(p, s) in desc.extra_sources {
+        entries.push((p, s));
+    }
+    let source = BakedSource { entries: &entries };
+    let expanded = process(&source, desc.entry_path)?;
+
+    // 2. Create shader module. wgpu's WGSL parser surfaces errors as
+    //    panics through the default handler; we catch them by
+    //    pushing the scope and popping on failure.
+    let _ = device.push_error_scope(wgpu::ErrorFilter::Validation);
+    let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
+        label: Some(desc.label),
+        source: wgpu::ShaderSource::Wgsl(expanded.into()),
+    });
+    // Note: we don't poll the error scope here because wgpu 29 returns
+    // validation errors synchronously via the device's uncaptured-error
+    // handler; callers should install their own handler for hot-reload.
+
+    // 3. Pipeline layout — always binds groups 0..3; only includes
+    //    scene_inputs when the material declares it.
+    let mut bg_layouts: Vec<Option<&wgpu::BindGroupLayout>> = vec![
+        Some(&layouts.per_frame),
+        Some(&layouts.per_view),
+        Some(&layouts.per_material),
+        Some(&layouts.per_draw),
+    ];
+    if desc.reads_scene {
+        bg_layouts.push(Some(&layouts.scene_inputs));
+    }
+    let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
+        label: Some(desc.label),
+        bind_group_layouts: &bg_layouts,
+        immediate_size: 0,
+    });
+
+    // 4. Colour targets based on profile.
+    let opaque_targets = [
+        Some(wgpu::ColorTargetState {
+            format: desc.hdr_format,
+            blend: None,
+            write_mask: wgpu::ColorWrites::ALL,
+        }),
+        Some(wgpu::ColorTargetState {
+            format: desc.material_format,
+            blend: None,
+            write_mask: wgpu::ColorWrites::ALL,
+        }),
+        Some(wgpu::ColorTargetState {
+            format: desc.velocity_format,
+            blend: None,
+            write_mask: wgpu::ColorWrites::ALL,
+        }),
+        Some(wgpu::ColorTargetState {
+            format: desc.albedo_format,
+            blend: None,
+            write_mask: wgpu::ColorWrites::ALL,
+        }),
+    ];
+    // Additive bucket uses src+dst on color; alpha-blending buckets
+    // (Transparent, Refractive) use SrcAlpha/OneMinusSrcAlpha. Both
+    // share the single HDR attachment.
+    let additive_blend = wgpu::BlendState {
+        color: wgpu::BlendComponent {
+            src_factor: wgpu::BlendFactor::One,
+            dst_factor: wgpu::BlendFactor::One,
+            operation:  wgpu::BlendOperation::Add,
+        },
+        alpha: wgpu::BlendComponent::OVER,
+    };
+    let translucent_blend = match desc.bucket {
+        Bucket::Additive => additive_blend,
+        _                => wgpu::BlendState::ALPHA_BLENDING,
+    };
+    let translucent_targets = [Some(wgpu::ColorTargetState {
+        format: desc.hdr_format,
+        blend: Some(translucent_blend),
+        write_mask: wgpu::ColorWrites::ALL,
+    })];
+    let targets: &[Option<wgpu::ColorTargetState>] = match desc.profile {
+        FragmentProfile::Opaque      => &opaque_targets,
+        FragmentProfile::Translucent => &translucent_targets,
+    };
+
+    // 5. Depth-stencil — translucent reads depth, doesn't write.
+    let depth_stencil = Some(wgpu::DepthStencilState {
+        format: desc.depth_format,
+        depth_write_enabled: Some(matches!(desc.profile, FragmentProfile::Opaque)),
+        depth_compare: Some(wgpu::CompareFunction::Less),
+        stencil: wgpu::StencilState::default(),
+        bias: wgpu::DepthBiasState::default(),
+    });
+
+    // 6. Vertex + fragment entry points. Convention: `vs_main` / `fs_main`.
+    //    Materials can override by prefixing their shader with
+    //    `// @entry vs:foo fs:bar` but the first version is fixed names.
+    //
+    //    EN-001 — when `wants_instancing` is set, append the standard
+    //    InstanceData3D layout so the pipeline expects a second VB at
+    //    slot 1 (step_mode = Instance). The owned Vec only lives long
+    //    enough to be referenced by the RenderPipelineDescriptor.
+    let vertex_buffers_owned: Vec<wgpu::VertexBufferLayout<'_>>;
+    let vertex_buffers: &[wgpu::VertexBufferLayout<'_>] = if desc.wants_instancing {
+        vertex_buffers_owned = desc.vertex_buffers
+            .iter()
+            .cloned()
+            .chain(std::iter::once(crate::renderer::types::InstanceData3D::desc()))
+            .collect();
+        &vertex_buffers_owned
+    } else {
+        desc.vertex_buffers
+    };
+    // Translucent materials (water, glass, particles) are commonly
+    // viewed from both sides, so they render double-sided. Cutout
+    // materials (foliage cards, chain-link fences) likewise need to
+    // be visible from both faces. Plain Opaque materials cull backfaces.
+    let main_cull = if matches!(desc.profile, FragmentProfile::Translucent)
+            || matches!(desc.bucket, Bucket::Cutout) {
+        None
+    } else {
+        Some(wgpu::Face::Back)
+    };
+
+    let make_pipeline = |cull: Option<wgpu::Face>, label_suffix: &str| {
+        let label_owned = format!("{}{}", desc.label, label_suffix);
+        device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
+            label: Some(&label_owned),
+            layout: Some(&pipeline_layout),
+            vertex: wgpu::VertexState {
+                module: &module,
+                entry_point: Some("vs_main"),
+                buffers: vertex_buffers,
+                compilation_options: Default::default(),
+            },
+            fragment: Some(wgpu::FragmentState {
+                module: &module,
+                entry_point: Some("fs_main"),
+                targets,
+                compilation_options: Default::default(),
+            }),
+            primitive: wgpu::PrimitiveState {
+                topology: wgpu::PrimitiveTopology::TriangleList,
+                front_face: wgpu::FrontFace::Ccw,
+                cull_mode: cull,
+                ..Default::default()
+            },
+            depth_stencil: depth_stencil.clone(),
+            multisample: wgpu::MultisampleState::default(),
+            multiview_mask: None,
+            cache: None,
+        })
+    };
+
+    let pipeline = make_pipeline(main_cull, "");
+
+    // EN-011 V2 — eagerly compile a reflection sibling with cull_mode
+    // flipped (Back → Front). Reflection mirrors world-space, which
+    // inverts triangle winding; without this swap, single-sided opaque
+    // geometry renders inside-out in the planar-reflection pass.
+    //
+    // Only build the variant when the original cull mode is `Back` —
+    // for `None` (translucent, cutout) and any future `Front`-default
+    // case, the reflection variant would be identical to the main
+    // pipeline (or already-flipped), so we save the compile cost.
+    //
+    // The cost when we DO build is a single extra pipeline per
+    // material (typically 5-30 in a scene). Compiled here rather
+    // than lazily at `set_reflection_probe` time so we never need to
+    // stash the WGSL source for a later recompile.
+    let reflection_pipeline = match main_cull {
+        Some(wgpu::Face::Back)  => Some(make_pipeline(Some(wgpu::Face::Front), "_reflection")),
+        Some(wgpu::Face::Front) => Some(make_pipeline(Some(wgpu::Face::Back),  "_reflection")),
+        None                    => None,
+    };
+
+    Ok(MaterialPipeline {
+        pipeline,
+        profile:          desc.profile,
+        bucket:           desc.bucket,
+        reads_scene:      desc.reads_scene,
+        wants_instancing: desc.wants_instancing,
+        label:            desc.label.to_string(),
+        reflection_pipeline,
+    })
+}
+
+// =====================================================================
+// Baked library snapshot
+// =====================================================================
+//
+// `shader_library::library()` returns an `impl ShaderSource`; for the
+// compile path above we need a `&[(&str, &str)]` slice so the
+// BakedSource we build can layer user overrides on top. Mirror the
+// library contents here; kept in sync by a test.
+
+const BAKED_ENTRIES_SNAPSHOT: &[(&str, &str)] = &[
+    ("material_abi.wgsl",           include_str!("../../../shared/shaders/material_abi.wgsl")),
+    ("common/pbr.wgsl",             include_str!("../../../shared/shaders/common/pbr.wgsl")),
+    ("common/shadows.wgsl",         include_str!("../../../shared/shaders/common/shadows.wgsl")),
+    ("common/fog.wgsl",             include_str!("../../../shared/shaders/common/fog.wgsl")),
+    ("common/tonemap.wgsl",         include_str!("../../../shared/shaders/common/tonemap.wgsl")),
+    ("common/sky.wgsl",             include_str!("../../../shared/shaders/common/sky.wgsl")),
+    ("materials/test_minimal.wgsl", include_str!("../../../shared/shaders/materials/test_minimal.wgsl")),
+];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Ensure the baked snapshot used by compile_material matches the
+    /// shader library. If this fails, an entry was added to the library
+    /// but not the snapshot (or vice-versa) — fix either.
+    #[test]
+    fn snapshot_matches_library() {
+        use super::super::shader_include::ShaderSource;
+        use super::super::shader_library;
+        let lib = shader_library::library();
+        for (path, body) in BAKED_ENTRIES_SNAPSHOT {
+            let from_lib = lib.fetch(path)
+                .unwrap_or_else(|| panic!("snapshot includes '{}' not in library", path));
+            assert_eq!(*body, from_lib, "mismatch for {}", path);
+        }
+    }
+
+    /// End-to-end validation: resolve the minimal test material's
+    /// includes and parse the result through naga (wgpu's WGSL
+    /// front-end). If the ABI header has a syntax error, or if a
+    /// struct reference is missing, naga fails this test.
+    ///
+    /// This test does not create a wgpu device — it's pure front-end
+    /// parsing — so it runs in any CI or dev environment without a
+    /// GPU. The downside is it doesn't verify the full pipeline
+    /// descriptor (blend state, vertex buffer layout, etc.); those are
+    /// exercised when `compile_material` runs at application startup.
+    #[test]
+    fn test_minimal_parses_through_naga() {
+        let source = BakedSource { entries: BAKED_ENTRIES_SNAPSHOT };
+        let expanded = process(&source, "materials/test_minimal.wgsl")
+            .expect("preprocessor resolves test_minimal.wgsl");
+        let result = wgpu::naga::front::wgsl::parse_str(&expanded);
+        if let Err(ref e) = result {
+            eprintln!("naga parse error:\n{}", e.emit_to_string(&expanded));
+        }
+        assert!(result.is_ok(), "test_minimal.wgsl should parse via naga after include expansion");
+    }
+}