@bornengine/engine 0.4.16

package/native/shared/src/decals.rs

@@ -0,0 +1,245 @@
+//! EN-027 — surface decals (bullet holes, scorch, blood splats).
+//!
+//! Textbook AAA decals are a deferred pass: project a box, read depth,
+//! rewrite the G-buffer before lighting. That is the right long-term shape and
+//! it is what a future revision should do. It is also a new pass wired into a
+//! hand-ordered 559 KB frame, for a feature whose entire visible job here is
+//! "the wall remembers the bullet".
+//!
+//! So this version is a *sticker*: an oriented quad, pushed a couple of
+//! millimetres along the surface normal, drawn through the existing instanced
+//! cutout material path. It depth-tests against the world, receives no
+//! lighting of its own (the material multiplies the surface's own shading), and
+//! costs one draw call for the whole ring. It cannot wrap around a corner —
+//! that is the honest limitation, and for bullet holes on flat stone and blood
+//! on flat ground nobody will ever see it.
+//!
+//! Packing note: the instance stride only carries a single Y rotation, but a
+//! decal needs an arbitrary orientation. A unit normal is two angles, so it
+//! fits in the two spare `extra` slots, leaving `rot_y` free to mean roll
+//! about the normal and `extra.x` to carry the atlas frame.
+
+/// A decal in flight. Fades out over the last `fade` seconds of its life so it
+/// does not pop.
+struct Decal {
+    pos: [f32; 3],
+    /// Surface normal, stored as azimuth/elevation to fit the instance stride.
+    az: f32,
+    el: f32,
+    roll: f32,
+    size: f32,
+    color: [f32; 4],
+    frame: f32,
+    age: f32,
+    life: f32,
+    fade: f32,
+}
+
+/// Look + lifetime for the *next* spawns. Set once per decal type (bullet
+/// hole, scorch, blood) rather than passed on every hit — a spawn is then 8
+/// f64 args, which is exactly the ARM64 register ceiling the FFI has to
+/// respect.
+#[derive(Clone, Copy)]
+pub struct DecalStyle {
+    pub frame: f32,
+    pub color: [f32; 4],
+    pub life: f32,
+    pub fade: f32,
+}
+
+impl Default for DecalStyle {
+    fn default() -> Self {
+        Self { frame: 0.0, color: [1.0; 4], life: 0.0, fade: 0.0 }
+    }
+}
+
+pub struct DecalManager {
+    decals: Vec<Decal>,
+    capacity: usize,
+    /// Ring cursor: once full, the oldest decal is the one overwritten.
+    next: usize,
+    pub instance_buffer: u32,
+    pub style: DecalStyle,
+    packed: Vec<f32>,
+    pub live: u32,
+}
+
+impl DecalManager {
+    pub fn new() -> Self {
+        Self {
+            decals: Vec::new(),
+            capacity: 0,
+            next: 0,
+            instance_buffer: 0,
+            style: DecalStyle::default(),
+            packed: Vec::new(),
+            live: 0,
+        }
+    }
+
+    pub fn init(&mut self, capacity: usize, instance_buffer: u32) {
+        self.capacity = capacity;
+        self.instance_buffer = instance_buffer;
+        self.decals = Vec::with_capacity(capacity);
+        self.packed = vec![0.0; capacity * 12];
+        self.next = 0;
+        self.live = 0;
+    }
+
+    /// Place a decal using the current `style`. `n` is the surface normal (need
+    /// not be normalized).
+    pub fn spawn_styled(&mut self, pos: [f32; 3], n: [f32; 3], size: f32, roll: f32) {
+        let st = self.style;
+        self.spawn(pos, n, size, roll, st.frame, st.color, st.life, st.fade);
+    }
+
+    /// Place a decal. `n` is the surface normal (need not be normalized);
+    /// `life <= 0` means permanent (well — until the ring wraps).
+    #[allow(clippy::too_many_arguments)]
+    pub fn spawn(
+        &mut self,
+        pos: [f32; 3],
+        n: [f32; 3],
+        size: f32,
+        roll: f32,
+        frame: f32,
+        color: [f32; 4],
+        life: f32,
+        fade: f32,
+    ) {
+        if self.capacity == 0 { return; }
+        let len = (n[0] * n[0] + n[1] * n[1] + n[2] * n[2]).sqrt();
+        let nn = if len > 1e-5 { [n[0] / len, n[1] / len, n[2] / len] } else { [0.0, 1.0, 0.0] };
+        // Spherical encode. el is the angle off +Y; az is the heading in XZ.
+        let el = nn[1].clamp(-1.0, 1.0).acos();
+        let az = nn[2].atan2(nn[0]);
+
+        let d = Decal {
+            // Lift off the surface: z-fighting on a coplanar quad is guaranteed
+            // otherwise, and 2 mm is under the depth precision of anything the
+            // player can stand close enough to notice.
+            pos: [
+                pos[0] + nn[0] * 0.002,
+                pos[1] + nn[1] * 0.002,
+                pos[2] + nn[2] * 0.002,
+            ],
+            az, el, roll,
+            size,
+            color,
+            frame,
+            age: 0.0,
+            life: if life <= 0.0 { f32::MAX } else { life },
+            fade: fade.max(0.0),
+        };
+
+        if self.decals.len() < self.capacity {
+            self.decals.push(d);
+        } else {
+            self.decals[self.next] = d;
+            self.next = (self.next + 1) % self.capacity;
+        }
+    }
+
+    /// Age everything, drop the expired, repack. Returns the live count.
+    pub fn update(&mut self, dt: f32) -> u32 {
+        let mut i = 0usize;
+        while i < self.decals.len() {
+            self.decals[i].age += dt;
+            if self.decals[i].age >= self.decals[i].life {
+                self.decals.swap_remove(i);
+                // The ring cursor indexes into a Vec that just shrank; clamp it
+                // or the next spawn writes out of bounds.
+                if self.next >= self.decals.len().max(1) { self.next = 0; }
+                continue;
+            }
+            i += 1;
+        }
+
+        for (i, d) in self.decals.iter().enumerate() {
+            // Fade only over the tail of the lifetime.
+            let alpha = if d.fade > 0.0 && d.life != f32::MAX {
+                let remaining = d.life - d.age;
+                (remaining / d.fade).clamp(0.0, 1.0)
+            } else { 1.0 };
+            let o = i * 12;
+            self.packed[o]      = d.pos[0];
+            self.packed[o + 1]  = d.pos[1];
+            self.packed[o + 2]  = d.pos[2];
+            self.packed[o + 3]  = d.roll;
+            self.packed[o + 4]  = d.size;
+            self.packed[o + 5]  = d.color[0];
+            self.packed[o + 6]  = d.color[1];
+            self.packed[o + 7]  = d.color[2];
+            self.packed[o + 8]  = d.color[3] * alpha;
+            self.packed[o + 9]  = d.frame;   // extra.x
+            self.packed[o + 10] = d.az;      // extra.y
+            self.packed[o + 11] = d.el;      // extra.z
+        }
+        self.live = self.decals.len() as u32;
+        self.live
+    }
+
+    pub fn packed(&self) -> &[f32] { &self.packed }
+
+    pub fn clear(&mut self) {
+        self.decals.clear();
+        self.next = 0;
+        self.live = 0;
+    }
+}
+
+impl Default for DecalManager {
+    fn default() -> Self { Self::new() }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ring_wraps_without_growing() {
+        let mut m = DecalManager::new();
+        m.init(4, 1);
+        for i in 0..10 {
+            m.spawn([i as f32, 0.0, 0.0], [0.0, 1.0, 0.0], 0.2, 0.0, 0.0, [1.0; 4], 0.0, 0.0);
+        }
+        assert_eq!(m.update(0.016), 4);
+    }
+
+    #[test]
+    fn expired_decals_are_reclaimed() {
+        let mut m = DecalManager::new();
+        m.init(8, 1);
+        m.spawn([0.0; 3], [0.0, 1.0, 0.0], 0.2, 0.0, 0.0, [1.0; 4], 1.0, 0.2);
+        assert_eq!(m.update(0.5), 1);
+        assert_eq!(m.update(0.6), 0);
+    }
+
+    #[test]
+    fn permanent_decals_survive() {
+        let mut m = DecalManager::new();
+        m.init(8, 1);
+        m.spawn([0.0; 3], [0.0, 1.0, 0.0], 0.2, 0.0, 0.0, [1.0; 4], 0.0, 0.0);
+        for _ in 0..100 { m.update(1.0); }
+        assert_eq!(m.live, 1);
+    }
+
+    /// The normal must survive the spherical round-trip, or every decal on a
+    /// wall silently lies flat on the floor.
+    #[test]
+    fn normal_encoding_round_trips() {
+        let mut m = DecalManager::new();
+        m.init(4, 1);
+        let n = [0.0f32, 0.0, 1.0];
+        m.spawn([0.0; 3], n, 1.0, 0.0, 0.0, [1.0; 4], 0.0, 0.0);
+        m.update(0.0);
+        let az = m.packed[10];
+        let el = m.packed[11];
+        let rx = el.sin() * az.cos();
+        let ry = el.cos();
+        let rz = el.sin() * az.sin();
+        assert!((rx - n[0]).abs() < 1e-4, "x {rx}");
+        assert!((ry - n[1]).abs() < 1e-4, "y {ry}");
+        assert!((rz - n[2]).abs() < 1e-4, "z {rz}");
+    }
+}

package/native/shared/src/drs.rs

@@ -0,0 +1,211 @@
+//! Dynamic resolution scaling (DRS) — self-tunes the renderer's
+//! `render_scale` to track a target framerate. Lives outside the
+//! renderer so it can read frame-time from the engine without
+//! threading a timing source down.
+//!
+//! Algorithm sketch:
+//! - Smooth frame time with an EMA (~10-frame window).
+//! - After a cooldown, step `render_scale` down one rung when EMA
+//!   exceeds target × 1.10, up one rung when EMA falls below
+//!   target × 0.80. Asymmetric thresholds — humans tolerate blur
+//!   better than stutter, so we drop quickly and recover slowly.
+//! - 6-rung ladder spaced ~√2 apart: 0.50 → 0.58 → 0.67 → 0.75 →
+//!   0.85 → 1.00. Keeps step size proportional to fragment cost.
+//! - Cooldown of 30 frames between any two steps prevents thrashing.
+
+use crate::renderer::Renderer;
+
+/// Discrete render-scale rungs DRS can choose from. Spaced so each
+/// step is roughly a √2 change in fragment-shader cost.
+const STEPS: &[f32] = &[0.50, 0.58, 0.67, 0.75, 0.85, 1.00];
+
+/// EMA smoothing factor — α=0.1 ≈ 10-frame effective window.
+/// Responsive enough to catch a sustained spike, slow enough to
+/// ignore single-frame outliers.
+const EMA_ALPHA: f32 = 0.1;
+
+/// Frames between any two scale steps. At 60 fps this is 0.5 s,
+/// long enough for the EMA to reflect the post-step frame time.
+const COOLDOWN_FRAMES: u32 = 30;
+
+/// Step *down* (cheaper) when EMA exceeds target × this.
+const HYSTERESIS_DOWN: f32 = 1.10;
+/// Step *up* (sharper) only when EMA falls below target × this.
+/// Tighter than HYSTERESIS_DOWN — blur is preferable to stutter.
+const HYSTERESIS_UP: f32 = 0.80;
+
+pub struct DrsController {
+    pub enabled: bool,
+    /// Per-frame target in milliseconds (1000 / target_hz).
+    pub target_frame_ms: f32,
+    ema_ms: f32,
+    frames_since_step: u32,
+    /// Index into `STEPS`. Starts at the top so DRS only ever cuts
+    /// from the user's chosen baseline downward — once enabled it
+    /// will climb back as headroom appears.
+    idx: usize,
+}
+
+impl DrsController {
+    pub fn new() -> Self {
+        Self {
+            enabled: false,
+            target_frame_ms: 1000.0 / 60.0,
+            ema_ms: 0.0,
+            frames_since_step: 0,
+            idx: STEPS.len() - 1, // 1.0 — start at native, step down as needed
+        }
+    }
+
+    /// Enable DRS targeting the given refresh rate in Hz. Snaps the
+    /// internal index to whichever rung is closest to the renderer's
+    /// current `render_scale` so the first step doesn't overshoot.
+    pub fn enable(&mut self, target_hz: f32, current_scale: f32) {
+        self.enabled = true;
+        self.target_frame_ms = 1000.0 / target_hz.max(1.0);
+        self.ema_ms = 0.0;
+        self.frames_since_step = 0;
+        self.idx = closest_step_idx(current_scale);
+    }
+
+    pub fn disable(&mut self) {
+        self.enabled = false;
+    }
+
+    /// Called once per frame from `EngineState::begin_frame` after
+    /// `delta_time` is updated. `dt_seconds` is wall-clock frame time.
+    pub fn tick(&mut self, dt_seconds: f64, renderer: &mut Renderer) {
+        if !self.enabled {
+            return;
+        }
+
+        let frame_ms = (dt_seconds * 1000.0) as f32;
+        // EMA bootstrap — first frame after enable, seed the buffer
+        // with the observed value so we don't spend 10 frames climbing
+        // from 0 toward the steady state.
+        if self.ema_ms == 0.0 {
+            self.ema_ms = frame_ms;
+        } else {
+            self.ema_ms += EMA_ALPHA * (frame_ms - self.ema_ms);
+        }
+
+        self.frames_since_step = self.frames_since_step.saturating_add(1);
+        if self.frames_since_step < COOLDOWN_FRAMES {
+            return;
+        }
+
+        let target = self.target_frame_ms;
+        if self.ema_ms > target * HYSTERESIS_DOWN && self.idx > 0 {
+            self.idx -= 1;
+            renderer.set_render_scale(STEPS[self.idx]);
+            self.frames_since_step = 0;
+        } else if self.ema_ms < target * HYSTERESIS_UP && self.idx + 1 < STEPS.len() {
+            self.idx += 1;
+            renderer.set_render_scale(STEPS[self.idx]);
+            self.frames_since_step = 0;
+        }
+    }
+
+    pub fn current_scale(&self) -> f32 { STEPS[self.idx] }
+}
+
+impl Default for DrsController {
+    fn default() -> Self { Self::new() }
+}
+
+fn closest_step_idx(scale: f32) -> usize {
+    let mut best = 0usize;
+    let mut best_d = (STEPS[0] - scale).abs();
+    for (i, s) in STEPS.iter().enumerate().skip(1) {
+        let d = (s - scale).abs();
+        if d < best_d {
+            best_d = d;
+            best = i;
+        }
+    }
+    best
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn closest_step_idx_picks_nearest_rung() {
+        // STEPS = [0.50, 0.58, 0.67, 0.75, 0.85, 1.00]
+        assert_eq!(closest_step_idx(0.50), 0);
+        assert_eq!(closest_step_idx(0.53), 0); // closer to 0.50 (Δ0.03) than 0.58 (Δ0.05)
+        assert_eq!(closest_step_idx(0.55), 1); // closer to 0.58 (Δ0.03) than 0.50 (Δ0.05)
+        assert_eq!(closest_step_idx(0.70), 2); // closer to 0.67 (Δ0.03) than 0.75 (Δ0.05)
+        assert_eq!(closest_step_idx(1.00), 5);
+        assert_eq!(closest_step_idx(2.00), 5); // clamped at top
+        assert_eq!(closest_step_idx(0.0), 0);  // clamped at bottom
+    }
+
+    #[test]
+    fn disabled_controller_never_steps() {
+        let mut drs = DrsController::new();
+        // Don't enable. Even with a huge frame time the controller
+        // should be a no-op (no renderer reference passed: skip via
+        // early return — exercised by reading enabled state).
+        for _ in 0..100 {
+            // Mimic: tick() early-returns when !enabled. We test by
+            // confirming idx hasn't moved off its initial top rung.
+            assert!(!drs.enabled);
+        }
+        assert_eq!(drs.idx, STEPS.len() - 1);
+    }
+
+    #[test]
+    fn enable_seeds_index_to_nearest_rung() {
+        let mut drs = DrsController::new();
+        drs.enable(60.0, 0.75);
+        assert_eq!(drs.idx, 3); // 0.75 is rung 3
+        assert_eq!(drs.current_scale(), 0.75);
+        assert!(drs.enabled);
+        assert!((drs.target_frame_ms - 1000.0 / 60.0).abs() < 0.001);
+    }
+
+    /// Synthetic frame-time trace: induce a 33 ms spike on a 60 fps
+    /// (16.67 ms) target and confirm the controller steps down,
+    /// then steps back up when frame time recovers.
+    #[test]
+    fn step_down_on_spike_recover_on_idle() {
+        let mut drs = DrsController::new();
+        drs.enable(60.0, 1.0);
+        let start_idx = drs.idx;
+
+        // Simulate the EMA + cooldown logic *without* a renderer by
+        // inlining the same updates against a local idx tracker.
+        let target = drs.target_frame_ms;
+        let mut idx = drs.idx;
+        let mut ema = 0.0f32;
+        let mut cooldown = 0u32;
+
+        let advance = |ms: f32, ema: &mut f32, idx: &mut usize, cooldown: &mut u32| {
+            if *ema == 0.0 { *ema = ms; } else { *ema += EMA_ALPHA * (ms - *ema); }
+            *cooldown = cooldown.saturating_add(1);
+            if *cooldown < COOLDOWN_FRAMES { return; }
+            if *ema > target * HYSTERESIS_DOWN && *idx > 0 {
+                *idx -= 1; *cooldown = 0;
+            } else if *ema < target * HYSTERESIS_UP && *idx + 1 < STEPS.len() {
+                *idx += 1; *cooldown = 0;
+            }
+        };
+
+        // 200 frames at 33ms (double target) should drop the rung
+        // at least once.
+        for _ in 0..200 {
+            advance(33.0, &mut ema, &mut idx, &mut cooldown);
+        }
+        assert!(idx < start_idx, "expected step-down, idx={idx}");
+
+        // 400 frames at 8ms (well under HYSTERESIS_UP * target = 13.3ms)
+        // should recover at least one rung.
+        let after_spike = idx;
+        for _ in 0..400 {
+            advance(8.0, &mut ema, &mut idx, &mut cooldown);
+        }
+        assert!(idx > after_spike, "expected step-up, idx={idx}");
+    }
+}