@bornengine/engine 0.4.16

package/native/shared/shaders/material_abi.wgsl

@@ -0,0 +1,383 @@
+// Bloom shader ABI header — see docs/rfc/0001-material-render-graph.md.
+//
+// ABI-VERSION: 3
+//
+// Included by every 3D shader (built-in PBR, sky, custom user materials).
+// Defines the five bind groups and the vertex attribute layout that any
+// Bloom-compatible 3D pipeline targets. Groups 0, 1, 3 are required;
+// group 2 is required for PBR materials and optional otherwise; group 4
+// is opt-in via the material descriptor's `reads_scene = true`.
+//
+// Bumping the version means every consumer has to be updated in the same
+// PR. Version-check happens in engine/renderer/shaders.rs at pipeline
+// creation time: mismatched headers are a hard error, not a warning.
+
+// =====================================================================
+// Group 0 — PerFrame (written once per frame, read by every 3D draw)
+// =====================================================================
+
+struct PerFrame {
+  // Clock / counters
+  time:              f32,   // seconds since process start, wraps every ~2²³ s
+  delta_time:        f32,   // seconds since previous frame
+  frame_index:       u32,   // monotonic, wraps at u32::MAX
+  _pad0:             u32,
+
+  // Resolutions
+  screen_resolution: vec2<f32>, // physical pixels (matches swapchain)
+  render_resolution: vec2<f32>, // may be smaller than screen when TSR < 1
+
+  // TAA / TSR jitter applied to the projection this frame
+  taa_jitter:        vec2<f32>,
+  _pad1:             vec2<f32>,
+
+  // Global wind field. xy = direction in the XZ plane (need not be
+  // normalised; magnitude scales effective amplitude); z = amplitude
+  // (~0.1 m typical for grass); w = frequency in Hz (~1.0 typical).
+  // Foliage / cloth materials sample this in their vertex stage.
+  wind:              vec4<f32>,
+
+  // Cloud deck. x = shadow strength (0 = the world ignores the clouds),
+  // y = deck height in metres, z = feature scale, w = drift speed in m/s.
+  // Feed it to `cloud_shadow_at` from common/clouds.wgsl and multiply the
+  // result into DIRECT sunlight only — this is the same deck the sky pass
+  // draws, so a shadow here has a cloud above it.
+  cloud:             vec4<f32>,
+};
+
+@group(0) @binding(0) var<uniform> frame: PerFrame;
+
+// =====================================================================
+// Group 1 — PerView (camera + lighting + env maps + shadows)
+// =====================================================================
+
+struct DirLight {
+  direction: vec4<f32>,  // xyz + intensity
+  color:     vec4<f32>,  // rgb + _pad
+};
+
+struct PointLight {
+  position:  vec4<f32>,  // xyz + range
+  color:     vec4<f32>,  // rgb + intensity
+};
+
+struct PerView {
+  // View matrices
+  view:           mat4x4<f32>,
+  proj:           mat4x4<f32>,
+  view_proj:      mat4x4<f32>,
+  prev_view_proj: mat4x4<f32>,  // for motion vectors / TAA reprojection
+  inv_proj:       mat4x4<f32>,
+
+  // Camera state
+  camera_pos:     vec4<f32>,    // xyz=world pos, w=env_intensity
+  camera_dir:     vec4<f32>,    // xyz=forward, w=fovy_rad
+
+  // Basic scene lighting
+  ambient:        vec4<f32>,    // rgb + intensity
+  fog:            vec4<f32>,    // rgb + density
+
+  // Legacy single-sun shortcut (also in dir_lights[0])
+  sun_dir:        vec4<f32>,    // xyz + intensity
+  sun_color:      vec4<f32>,    // rgb + 0
+
+  // Arrayed lights
+  dir_light_count:   vec4<f32>, // x = count, y = shadows-enabled flag, zw = 0
+  dir_lights:        array<DirLight,  8>,
+  point_light_count: vec4<f32>,
+  point_lights:     array<PointLight, 256>,
+
+  // Shadow data — three cascades, split by shadow_splits.xyz
+  shadow_splits:   vec4<f32>,
+  shadow_view:     mat4x4<f32>,                   // orientation for cascade compute
+  shadow_cascades: array<mat4x4<f32>, 3>,         // light-space view-proj per cascade
+};
+
+@group(1) @binding(0) var<uniform> view: PerView;
+
+// Environment maps — pre-filtered at load time.
+@group(1) @binding(1) var env_tex:          texture_2d<f32>;
+@group(1) @binding(2) var env_samp:         sampler;
+@group(1) @binding(3) var env_diffuse_tex:  texture_2d<f32>;
+
+// BRDF LUT for IBL specular (split-sum approximation).
+@group(1) @binding(4) var brdf_lut_tex:     texture_2d<f32>;
+@group(1) @binding(5) var brdf_lut_samp:    sampler;
+
+// Shadow depth textures, one per cascade.
+@group(1) @binding(6) var shadow_tex_0:     texture_depth_2d;
+@group(1) @binding(7) var shadow_tex_1:     texture_depth_2d;
+@group(1) @binding(8) var shadow_tex_2:     texture_depth_2d;
+@group(1) @binding(9) var shadow_samp:      sampler_comparison;
+
+// =====================================================================
+// Group 2 — PerMaterial (PBR textures + factors + user params)
+// =====================================================================
+//
+// All texture bindings have a 1×1 white default bound when a material
+// doesn't provide its own — shaders can unconditionally sample.
+
+struct MaterialFactors {
+  metal_rough:    vec4<f32>,  // x=metallic, y=roughness, z=has_mr_tex, w=alpha_cutoff
+  emissive:       vec4<f32>,  // rgb + 0
+  base_color:     vec4<f32>,  // rgba tint multiplier
+  // EN-012 — shading-model selector + foliage transmission RGB.
+  // x = shading_model (0 = default lit, 1 = foliage,
+  //                    2 = subsurface — V2 stub),
+  // yzw = transmission_color (rgb tint for back-lit foliage; ignored
+  //       for default lit). Default (1, 1, 1) when not set.
+  shading_model:  vec4<f32>,
+  // EN-012 — foliage shading parameters. Read by `shade_foliage`
+  // (in common/pbr.wgsl) when shading_model.x == 1.0.
+  // x = transmission_amount (0..1, how much sun-behind-leaf bleeds
+  //                          through into the camera),
+  // y = wrap_factor (0..1, how much wrap-lambert wraps the diffuse
+  //                  term — 0 is standard lambert, 1 is light fully
+  //                  wrapping around to the back face),
+  // zw = reserved.
+  foliage_params: vec4<f32>,
+};
+
+@group(2) @binding(0)  var base_color_tex:   texture_2d<f32>;
+@group(2) @binding(1)  var base_color_samp:  sampler;
+@group(2) @binding(2)  var normal_tex:       texture_2d<f32>;
+@group(2) @binding(3)  var normal_samp:      sampler;
+@group(2) @binding(4)  var mr_tex:           texture_2d<f32>;
+@group(2) @binding(5)  var mr_samp:          sampler;
+@group(2) @binding(6)  var em_tex:           texture_2d<f32>;
+@group(2) @binding(7)  var em_samp:          sampler;
+@group(2) @binding(8)  var occ_tex:          texture_2d<f32>;
+@group(2) @binding(9)  var occ_samp:         sampler;
+@group(2) @binding(10) var<uniform> material: MaterialFactors;
+
+// Binding 11 is reserved for per-material user params. Shaders that
+// declare user params do so via:
+//
+//   struct UserParams { … up to 256 bytes … };
+//   @group(2) @binding(11) var<uniform> user: UserParams;
+//
+// Materials that don't use it leave binding 11 unclaimed; the engine's
+// pipeline layout allocates a 16-byte stub UBO there so the bind group
+// always matches the layout.
+
+// EN-011 — Planar reflection RT. Bound by the engine for materials
+// linked to a reflection probe via `setMaterialReflectionProbe`.
+// Materials without a probe get a 1×1 black default texture so
+// unconditional sampling is safe.
+//
+// The RT is `Rgba16Float` HDR (matches the engine's pipeline) and
+// holds the previous frame's mirror-camera render of the world
+// minus excluded materials. Sample with screen-space UV — the
+// reflection texture is camera-aligned. Typical water shader pattern:
+//
+//   let screen_uv = clip_position.xy / vec2<f32>(frame.screen_resolution);
+//   let perturb = wave_normal.xz * 0.05;       // wobble strength
+//   let refl = textureSample(planar_reflection_tex,
+//                            planar_reflection_samp,
+//                            screen_uv + perturb).rgb;
+//
+// Reads are NaN-safe: the default 1×1 black texture means a material
+// can sample even when the game forgot to bind a probe.
+@group(2) @binding(12) var planar_reflection_tex:  texture_2d<f32>;
+@group(2) @binding(13) var planar_reflection_samp: sampler;
+
+// =====================================================================
+// EN-014 — Texture-array slots for splat-mapped terrain.
+// =====================================================================
+//
+// Three optional `texture_2d_array<f32>` slots. Materials that don't
+// bind a texture array see a 1×1×1 stub array (single transparent
+// black layer) so unconditional sampling is safe.
+//
+// Layer count is capped at 16 layers per array in V1. Games address
+// individual layers via a fragment-shader argument:
+//   let albedo = textureSample(albedo_array, albedo_array_samp,
+//                              uv_world_xz, layer_idx);
+//
+// Pair these with a splat-weight texture (RGBA8 with 4 weight channels)
+// in user_params for terrain blending. Single sampler is reused across
+// all 3 arrays — terrain layers share UV / filtering, so a per-array
+// sampler would just waste binding slots.
+@group(2) @binding(14) var albedo_array:      texture_2d_array<f32>;
+@group(2) @binding(15) var normal_array:      texture_2d_array<f32>;
+@group(2) @binding(16) var mr_array:          texture_2d_array<f32>;
+@group(2) @binding(17) var albedo_array_samp: sampler;
+
+// =====================================================================
+// Group 3 — PerDraw (transform + skinning)
+// =====================================================================
+
+struct PerDraw {
+  mvp:        mat4x4<f32>,
+  model:      mat4x4<f32>,
+  prev_mvp:   mat4x4<f32>,  // for motion vectors
+  model_tint: vec4<f32>,
+  skin_info:  vec4<u32>,    // x=joint_offset into global buffer, y=joint_count, zw=0
+};
+
+struct JointMatrices {
+  matrices: array<mat4x4<f32>, 1024>,  // global joint buffer; draws read slices by offset
+};
+
+@group(3) @binding(0) var<uniform> draw:   PerDraw;
+@group(3) @binding(1) var<uniform> joints: JointMatrices;
+
+// EN-022 — standard motion vector from current/previous clip positions.
+// Matches the core path's convention exactly (NDC delta × 0.5). Vertex
+// shaders pass their clip position plus a previous-frame clip position:
+// static geometry uses `draw.prev_mvp * local` (or
+// `view.prev_view_proj * world` — for static models the two agree);
+// procedurally displaced geometry (wind sway) re-evaluates the
+// displacement at `frame.time - frame.delta_time` and projects with
+// `view.prev_view_proj`. Write the result to OpaqueOut.velocity — a
+// zero write disables TAA's motion-adaptive clamp for that surface
+// (the round-2 audit's primary TSR-shimmer mechanism, F8).
+fn abi_motion_vector(curr_clip: vec4<f32>, prev_clip: vec4<f32>) -> vec2<f32> {
+  let c = curr_clip.xy / curr_clip.w;
+  let p = prev_clip.xy / prev_clip.w;
+  return (c - p) * 0.5;
+}
+
+// =====================================================================
+// Group 4 — SceneInputs (optional; `reads_scene = true` materials only)
+// =====================================================================
+//
+// The render graph synthesises a SceneColor snapshot pass before the
+// first consumer runs. Materials that don't declare reads_scene never
+// receive this group and pay no cost for the copy.
+
+@group(4) @binding(0) var scene_color_tex:  texture_2d<f32>;
+@group(4) @binding(1) var scene_color_samp: sampler;
+@group(4) @binding(2) var scene_depth_tex:  texture_depth_2d;
+@group(4) @binding(3) var scene_depth_samp: sampler;
+@group(4) @binding(4) var impulse_tex:      texture_2d<f32>;  // world-space decals / splashes
+@group(4) @binding(5) var impulse_samp:     sampler;
+@group(4) @binding(6) var motion_vectors:   texture_2d<f32>;
+
+// =====================================================================
+// Vertex attribute layout (matches renderer::types::Vertex3D)
+// =====================================================================
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) normal:   vec3<f32>,
+  @location(2) color:    vec4<f32>,   // per-vertex tint multiplier
+  @location(3) uv:       vec2<f32>,
+  @location(4) joints:   vec4<f32>,   // bone indices as floats (engine convention)
+  @location(5) weights:  vec4<f32>,   // sum to 1.0 for skinned, 0 for unskinned
+  @location(6) tangent:  vec4<f32>,   // xyz=tangent, w=bitangent sign (+1 / -1)
+};
+
+// =====================================================================
+// Fragment output profiles
+// =====================================================================
+
+// Opaque profile — writes the full forward G-buffer. Materials that use
+// this must live in `Bucket::Opaque` and render in the main_hdr pass.
+struct OpaqueOut {
+  @location(0) hdr:      vec4<f32>,  // HDR colour, pre-bloom
+  @location(1) material: vec2<f32>,  // metallic, roughness for SSR / SSGI
+  @location(2) velocity: vec2<f32>,  // NDC-space motion, for TAA reprojection
+  @location(3) albedo:   vec4<f32>,  // for SSGI bounce colour
+};
+
+// Translucent profile — writes HDR only, alpha blended. Materials in
+// `Bucket::Transparent`, `Refractive`, or `Additive` use this. The main
+// HDR pass' G-buffer targets are load-op'd in the translucent sub-pass;
+// material/velocity/albedo remain whatever the opaque pass left them.
+struct TranslucentOut {
+  @location(0) hdr: vec4<f32>,
+};
+
+// =====================================================================
+// Standard helpers
+// =====================================================================
+
+// Skinning — blends a world-space position through the joint matrices,
+// using the per-draw joint_offset so multiple skinned models share the
+// global joint buffer.
+fn world_position_from_skinned(
+  local_pos: vec3<f32>, vertex: VertexInput, include_non_skinned: bool,
+) -> vec4<f32> {
+  let total_weight = vertex.weights.x + vertex.weights.y
+                   + vertex.weights.z + vertex.weights.w;
+  var pos = vec4<f32>(local_pos, 1.0);
+  if (total_weight > 0.01) {
+    let off = draw.skin_info.x;
+    let j0 = off + u32(vertex.joints.x);
+    let j1 = off + u32(vertex.joints.y);
+    let j2 = off + u32(vertex.joints.z);
+    let j3 = off + u32(vertex.joints.w);
+    pos = joints.matrices[j0] * pos * vertex.weights.x
+        + joints.matrices[j1] * pos * vertex.weights.y
+        + joints.matrices[j2] * pos * vertex.weights.z
+        + joints.matrices[j3] * pos * vertex.weights.w;
+  } else if (include_non_skinned) {
+    pos = draw.model * pos;
+  }
+  return pos;
+}
+
+// Standard NDC-space motion vector computation. Pass the current and
+// previous clip positions, get back a vec2 suitable for the
+// velocity G-buffer target.
+fn compute_motion_vector(curr_clip: vec4<f32>, prev_clip: vec4<f32>) -> vec2<f32> {
+  let curr_ndc = curr_clip.xy / curr_clip.w;
+  let prev_ndc = prev_clip.xy / prev_clip.w;
+  return (curr_ndc - prev_ndc) * 0.5;
+}
+
+// Linearise a hardware depth value given the bound projection. Useful
+// for materials that read `scene_depth_tex` (group 4 binding 2).
+fn linearize_depth(z_ndc: f32) -> f32 {
+  // Standard reverse-depth linearisation: the engine uses a standard
+  // depth range (0..1) with proj.z mapping near→0, far→1.
+  // Derived from the inv_proj mat4; this cheap form works for our
+  // perspective projections. Override in shaders that don't match.
+  let z_clip = z_ndc * 2.0 - 1.0;
+  let a = view.proj[2][2];
+  let b = view.proj[3][2];
+  // z_eye = b / (z_clip + a). Result is negative (camera looks down -Z).
+  return -b / (z_clip + a);
+}
+
+// =====================================================================
+// EN-001 — Instance attribute layout (wants_instancing pipelines)
+// =====================================================================
+//
+// Materials compiled via `compile_material_instanced` get a second
+// vertex buffer at slot 1, step_mode = Instance. Game shaders that opt
+// into instancing extend their VertexInput with these locations IN
+// ADDITION to the standard 0..6 above:
+//
+//   struct InstancedVertexInput {
+//     @location(0)  position:        vec3<f32>,
+//     @location(1)  normal:          vec3<f32>,
+//     @location(2)  color:           vec4<f32>,
+//     @location(3)  uv:              vec2<f32>,
+//     @location(4)  joints:          vec4<f32>,
+//     @location(5)  weights:         vec4<f32>,
+//     @location(6)  tangent:         vec4<f32>,
+//     @location(7)  instance_pos:    vec3<f32>,
+//     @location(8)  instance_rot_y:  f32,
+//     @location(9)  instance_scale:  f32,
+//     @location(10) instance_tint:   vec4<f32>,
+//   };
+//
+// Typical vertex-shader pattern:
+//
+//   let cy = cos(in.instance_rot_y);
+//   let sy = sin(in.instance_rot_y);
+//   let local = in.position * in.instance_scale;
+//   let world = vec3<f32>(
+//     cy * local.x + sy * local.z,
+//     local.y,
+//     -sy * local.x + cy * local.z,
+//   ) + in.instance_pos;
+//   let world_pos = vec4<f32>(world, 1.0);
+//   out.clip_position = view.view_proj * world_pos;
+//
+// The Rust-side `InstanceData3D` struct mirrors this layout and is
+// the canonical CPU representation. Per-draw `model_tint` is
+// multiplied against `instance_tint` in the fragment shader so games
+// can dim/colour an entire instanced batch without re-uploading.

package/native/shared/shaders/materials/test_minimal.wgsl

@@ -0,0 +1,42 @@
+// Minimal ABI-compliant test material (opaque profile).
+//
+// Reads PerFrame.time and PerDraw.mvp to render the bound geometry
+// with a solid time-pulsed colour. Writes the full 4-MRT G-buffer so
+// the main HDR pass accepts it without a translucent sub-pass (that's
+// phase 2's job). Proves the material pipeline + submission plumbing
+// works end-to-end.
+
+#include "material_abi.wgsl"
+
+struct VsOut {
+  @builtin(position) clip_position: vec4<f32>,
+  @location(0) world_normal: vec3<f32>,
+  @location(1) local_color:  vec3<f32>,
+};
+
+@vertex
+fn vs_main(in: VertexInput) -> VsOut {
+  var out: VsOut;
+  out.clip_position = draw.mvp * vec4<f32>(in.position, 1.0);
+  out.world_normal = normalize((draw.model * vec4<f32>(in.normal, 0.0)).xyz);
+
+  // Pulse colour with PerFrame.time to demonstrate the binding.
+  let pulse = 0.5 + 0.5 * sin(frame.time * 1.5);
+  out.local_color = vec3<f32>(pulse, 0.4, 1.0 - pulse) * draw.model_tint.rgb;
+  return out;
+}
+
+@fragment
+fn fs_main(in: VsOut) -> OpaqueOut {
+  var out: OpaqueOut;
+  // Simple directional-ish shading so the cube reads as 3D.
+  let n = normalize(in.world_normal);
+  let light_dir = normalize(vec3<f32>(0.3, 0.7, 0.4));
+  let diffuse = max(dot(n, light_dir), 0.0);
+  let lit = in.local_color * (0.3 + 0.7 * diffuse);
+  out.hdr      = vec4<f32>(lit, 1.0);
+  out.material = vec2<f32>(0.0, 0.9);            // non-metal, rough
+  out.velocity = vec2<f32>(0.0, 0.0);
+  out.albedo   = vec4<f32>(in.local_color, 1.0);
+  return out;
+}

package/native/shared/src/anim_mixer.rs

@@ -0,0 +1,61 @@
+//! EN-028 — per-model animation mixer state.
+//!
+//! Split out of `models.rs` (EN-052 line budget) when EN-055 landed: the
+//! mixer is exactly the state that is PER-INSTANCE under animation
+//! instancing, so it earns its own module. Re-exported from `models`, so
+//! `crate::models::AnimMixer` paths are unchanged.
+//!
+//! Three things a single-clip sampler cannot do, all of which read as
+//! "cheap" on screen: transitions pop, an attacking character has to stop
+//! walking, and authored locomotion arcs (a pounce, a lunge) get replaced
+//! by hand-tuned kinematics because the root is nailed to the rest pose.
+//!
+//! Layout: a base track that crossfades from `prev` to `cur` over
+//! `fade_dur`, plus one optional additive-by-mask layer (an attack driving
+//! the spine-up while the legs keep walking). All clocks advance in
+//! `advance_animation`, so the game hands over a dt and never tracks clip
+//! time itself.
+
+#[derive(Clone)]
+pub struct AnimMixer {
+    pub cur_clip: usize,
+    pub cur_time: f32,
+    pub cur_speed: f32,
+    pub cur_loop: bool,
+    /// Clip we are fading *out* of. `fade_dur <= 0` means no fade in flight.
+    pub prev_clip: usize,
+    pub prev_time: f32,
+    pub prev_speed: f32,
+    pub prev_loop: bool,
+    pub fade_t: f32,
+    pub fade_dur: f32,
+    /// Masked layer. `layer_clip < 0` = inactive.
+    pub layer_clip: i32,
+    pub layer_time: f32,
+    pub layer_speed: f32,
+    pub layer_loop: bool,
+    pub layer_weight: f32,
+    /// Root joint of the masked subtree (e.g. the spine). Every joint at or
+    /// below it takes the layer pose; everything else keeps the base pose.
+    pub layer_mask_root: i32,
+    /// Opt-in root motion. Off by default so existing games are unchanged.
+    pub root_motion: bool,
+    pub root_delta: [f32; 3],
+    /// True once a non-looping `cur_clip` has played past its duration.
+    pub finished: bool,
+    pub started: bool,
+}
+
+impl Default for AnimMixer {
+    fn default() -> Self {
+        Self {
+            cur_clip: 0, cur_time: 0.0, cur_speed: 1.0, cur_loop: true,
+            prev_clip: 0, prev_time: 0.0, prev_speed: 1.0, prev_loop: true,
+            fade_t: 0.0, fade_dur: 0.0,
+            layer_clip: -1, layer_time: 0.0, layer_speed: 1.0, layer_loop: false,
+            layer_weight: 0.0, layer_mask_root: -1,
+            root_motion: false, root_delta: [0.0; 3],
+            finished: false, started: false,
+        }
+    }
+}