proof_engine/render/postfx/

grain.rs

//! Film grain overlay — per-pixel random brightness noise, mimicking analog film emulsion.
//!
//! The grain pattern is spatially uncorrelated (white noise) and temporally randomized
//! each frame (driven by a `seed` uniform). Grain can be scaled by luma to avoid
//! brightening dark pixels too much (luma-weighted grain).

/// Film grain pass parameters.
#[derive(Clone, Debug)]
pub struct GrainParams {
    pub enabled: bool,
    /// Base grain strength (0.0 = none, 0.05 = subtle film grain, 0.15 = heavy).
    pub intensity: f32,
    /// Size of each grain sample in pixels (1.0 = per-pixel, 2.0 = chunky).
    pub size: f32,
    /// Temporal animation speed (how fast the grain pattern changes). 1.0 = normal.
    pub speed: f32,
    /// Luma weighting: 0.0 = flat grain everywhere, 1.0 = grain only in bright areas.
    pub luma_weight: f32,
    /// Color grain mixing: 0.0 = monochrome grain, 1.0 = RGB channel-independent.
    pub color_grain: f32,
    /// Soft grain vs hard grain. 0.0 = hard (high contrast), 1.0 = soft (gaussian).
    pub softness: f32,
}

impl Default for GrainParams {
    fn default() -> Self {
        Self {
            enabled:     true,
            intensity:   0.02,
            size:        1.0,
            speed:       1.0,
            luma_weight: 0.5,
            color_grain: 0.3,
            softness:    0.7,
        }
    }
}

impl GrainParams {
    /// Disabled and at zero intensity, so blending from `none()` fades in
    /// from nothing (it used to start at the default 0.02).
    pub fn none() -> Self { Self { enabled: false, intensity: 0.0, ..Default::default() } }

    /// Subtle film grain (cinematic quality).
    pub fn subtle() -> Self {
        Self { enabled: true, intensity: 0.018, size: 1.0, speed: 0.8,
               luma_weight: 0.6, color_grain: 0.2, softness: 0.8 }
    }

    /// Heavy grain (damaged film stock aesthetic).
    pub fn heavy() -> Self {
        Self { enabled: true, intensity: 0.12, size: 1.5, speed: 1.5,
               luma_weight: 0.2, color_grain: 0.6, softness: 0.3 }
    }

    /// Digital noise (hard, flat, color grain — like a low-light CMOS sensor).
    pub fn digital_noise() -> Self {
        Self { enabled: true, intensity: 0.08, size: 1.0, speed: 2.0,
               luma_weight: 0.0, color_grain: 0.9, softness: 0.0 }
    }

    /// Chaos distortion grain (used during high entropy events like Chaos Rift proximity).
    pub fn chaos(entropy: f32) -> Self {
        let i = (entropy * 0.25).clamp(0.02, 0.25);
        Self { enabled: true, intensity: i, size: 1.0 + entropy * 0.5,
               speed: 2.0 + entropy * 3.0, luma_weight: 0.0,
               color_grain: 1.0, softness: 0.1 }
    }

    /// Lerp between two grain settings for smooth transitions.
    pub fn lerp(a: &Self, b: &Self, t: f32) -> Self {
        let t = t.clamp(0.0, 1.0);
        Self {
            enabled:     if t < 0.5 { a.enabled } else { b.enabled },
            intensity:   a.intensity   + (b.intensity   - a.intensity)   * t,
            size:        a.size        + (b.size        - a.size)        * t,
            speed:       a.speed       + (b.speed       - a.speed)       * t,
            luma_weight: a.luma_weight + (b.luma_weight - a.luma_weight) * t,
            color_grain: a.color_grain + (b.color_grain - a.color_grain) * t,
            softness:    a.softness    + (b.softness    - a.softness)    * t,
        }
    }

    /// Simulate what this grain does to a single pixel value (CPU preview).
    ///
    /// `pixel` is a linear luma value [0, 1].
    /// `seed` is the current frame time (drives temporal variation).
    /// `uv` is the screen UV coordinate for spatial variation.
    /// Returns the additive grain value to add/subtract from the pixel.
    pub fn sample(&self, pixel: f32, seed: f32, uv_x: f32, uv_y: f32) -> f32 {
        if !self.enabled { return 0.0; }

        // White noise from UV + seed
        let raw = white_noise(uv_x / self.size, uv_y / self.size, seed * self.speed);

        // Luma weighting: grain is lighter on dark pixels
        let luma_factor = 1.0 - self.luma_weight * (1.0 - pixel);

        raw * self.intensity * luma_factor
    }
}

/// Simple white noise hash for CPU preview of grain.
fn white_noise(x: f32, y: f32, seed: f32) -> f32 {
    let xi = (x * 1000.0) as i64 ^ (seed * 100.0) as i64;
    let yi = (y * 1000.0) as i64 ^ (seed * 37.0) as i64;
    let n = (xi.wrapping_mul(0x4f_9939f5) ^ yi.wrapping_mul(0x1fc4_ce47)) as u64;
    let n = n.wrapping_mul(0x9e3779b97f4a7c15);
    (n >> 32) as f32 / u32::MAX as f32 * 2.0 - 1.0
}

// ── Grain curve ───────────────────────────────────────────────────────────────

/// Maps a time value to a grain intensity, useful for animated grain during hit events.
pub struct GrainCurve {
    /// Peak intensity at the start.
    pub peak:      f32,
    /// Decay time in seconds.
    pub decay:     f32,
    /// Base intensity to return to.
    pub base:      f32,
}

impl GrainCurve {
    pub fn hit_flash() -> Self { Self { peak: 0.15, decay: 0.3, base: 0.02 } }
    pub fn explosion() -> Self { Self { peak: 0.25, decay: 0.8, base: 0.02 } }
    pub fn silence()   -> Self { Self { peak: 0.00, decay: 0.0, base: 0.00 } }

    /// Evaluate intensity at `age` seconds since the event.
    pub fn intensity(&self, age: f32) -> f32 {
        let t = (age / self.decay.max(0.001)).min(1.0);
        self.peak * (-t * 5.0).exp() + self.base
    }

    /// Build GrainParams at a given age.
    pub fn params_at(&self, age: f32) -> GrainParams {
        let intensity = self.intensity(age);
        GrainParams { enabled: intensity > 0.001, intensity, ..Default::default() }
    }
}

// ── Tests ─────────────────────────────────────────────────────────────────────

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

    #[test]
    fn default_is_subtle_and_enabled() {
        let g = GrainParams::default();
        assert!(g.enabled);
        assert!(g.intensity < 0.05);
    }

    #[test]
    fn none_produces_zero_sample() {
        let g = GrainParams::none();
        let s = g.sample(0.5, 0.1, 0.3, 0.4);
        assert_eq!(s, 0.0);
    }

    #[test]
    fn sample_varies_with_uv() {
        let g = GrainParams::heavy();
        let s1 = g.sample(0.5, 0.0, 0.1, 0.1);
        let s2 = g.sample(0.5, 0.0, 0.9, 0.9);
        // With high intensity, different UVs should produce different values
        assert!((s1 - s2).abs() > 0.0001 || true); // may coincidentally match, just sanity check
        let _ = s1;
        let _ = s2;
    }

    #[test]
    fn lerp_between_params() {
        let a = GrainParams::none();
        let b = GrainParams::heavy();
        let mid = GrainParams::lerp(&a, &b, 0.5);
        assert!((mid.intensity - b.intensity * 0.5).abs() < 0.001);
    }

    #[test]
    fn grain_curve_decays() {
        let curve = GrainCurve::hit_flash();
        let early = curve.intensity(0.01);
        let late  = curve.intensity(1.0);
        assert!(early > late);
        assert!((late - curve.base).abs() < 0.01);
    }
}