onedrop_renderer/

noise.rs

//! Procedural noise textures for the noise texture pack.
//!
//! MilkDrop 2 ships every preset with a fixed set of noise textures sampled by
//! user comp shaders. The names and resolutions follow Geiss's reference
//! implementation (mirrored in projectM's `PerlinNoise.cpp`):
//!
//! | Name             | Shape       | Channels | Used by                    |
//! | ---------------- | ----------- | -------- | -------------------------- |
//! | `noise_lq`       | 256 × 256   | RGBA8    | 74 / 168 in-the-wild comps |
//! | `noise_mq`       | 64 × 64     | RGBA8    | 1 / 168                    |
//! | `noise_hq`       | 32 × 32     | RGBA8    | 42 / 168                   |
//! | `noisevol_lq`    | 32 × 32 × 32 | RGBA8   | 4 / 168                    |
//! | `noisevol_hq`    | 8 × 8 × 8   | RGBA8    | 77 / 168                   |
//!
//! Reference MilkDrop generates each byte with `rand() & 0xFF` and lets the
//! sampler's bilinear/trilinear filtering produce smooth pseudo-noise.
//! Matching that exactly fixes the visual style every authored preset was
//! tuned against, so we mirror it: independent xorshift32 stream per
//! texture, seeded deterministically so reload paths produce bit-identical
//! frames.
//!
//! The textures are generated once at engine init; the data lives in CPU
//! memory long enough to upload to the GPU and is then dropped.

/// Tiny deterministic PRNG. Replaces `rand()` from MilkDrop's reference
/// without taking a workspace-wide dependency for a few hundred KB of init
/// data. Mixed with the texture name's first byte so the three 2D and two
/// 3D textures don't share a stream.
struct XorShift32(u32);

impl XorShift32 {
    fn new(seed: u32) -> Self {
        // xorshift32 is degenerate at 0 — bias away from it.
        Self(seed.max(1))
    }
    fn next_u32(&mut self) -> u32 {
        let mut x = self.0;
        x ^= x << 13;
        x ^= x >> 17;
        x ^= x << 5;
        self.0 = x;
        x
    }
    fn next_u8(&mut self) -> u8 {
        (self.next_u32() & 0xFF) as u8
    }
}

/// Dimensions + byte payload for one noise texture. RGBA8 layout in all
/// cases: 4 bytes per texel, tightly packed in row-major (and slice-major
/// for the 3D textures), no padding.
#[derive(Debug, Clone)]
pub struct NoiseTexture {
    pub width: u32,
    pub height: u32,
    pub depth: u32,
    pub bytes: Vec<u8>,
}

impl NoiseTexture {
    /// `vec4<f32>(w, h, 1/w, 1/h)` for the `texsize_<name>` uniform that real
    /// presets reference. For 3D textures the depth axis is exposed too,
    /// but every authored shader treats `texsize_noisevol_*` as a vec4 and
    /// only reads `.xy` / `.zw`, so we match the MD2 convention.
    pub fn texsize(&self) -> [f32; 4] {
        let w = self.width as f32;
        let h = self.height as f32;
        [w, h, 1.0 / w, 1.0 / h]
    }
}

/// Full noise pack used by the comp pass. Names match MD2 sampler conventions
/// (`sampler_noise_lq`, `sampler_noisevol_hq`, …) without the `sampler_`
/// prefix.
pub struct NoisePack {
    pub noise_lq: NoiseTexture,
    pub noise_mq: NoiseTexture,
    pub noise_hq: NoiseTexture,
    pub noisevol_lq: NoiseTexture,
    pub noisevol_hq: NoiseTexture,
}

impl NoisePack {
    /// Generate the standard MD2 noise pack with a fixed seed. Every call
    /// produces the same bytes — letting tests assert byte-level invariants
    /// and the visual output stay stable across runs / reloads.
    pub fn generate() -> Self {
        Self {
            noise_lq: gen_2d(256, 256, 0x4D2B_157Bu32),
            noise_mq: gen_2d(64, 64, 0x9E37_79B9),
            noise_hq: gen_2d(32, 32, 0xC2B2_AE35),
            noisevol_lq: gen_3d(32, 32, 32, 0x5851_F42D),
            noisevol_hq: gen_3d(8, 8, 8, 0xB7E1_5163),
        }
    }
}

fn gen_2d(w: u32, h: u32, seed: u32) -> NoiseTexture {
    let mut rng = XorShift32::new(seed);
    let mut bytes = Vec::with_capacity((w * h * 4) as usize);
    for _ in 0..(w * h * 4) {
        bytes.push(rng.next_u8());
    }
    NoiseTexture {
        width: w,
        height: h,
        depth: 1,
        bytes,
    }
}

fn gen_3d(w: u32, h: u32, d: u32, seed: u32) -> NoiseTexture {
    let mut rng = XorShift32::new(seed);
    let mut bytes = Vec::with_capacity((w * h * d * 4) as usize);
    for _ in 0..(w * h * d * 4) {
        bytes.push(rng.next_u8());
    }
    NoiseTexture {
        width: w,
        height: h,
        depth: d,
        bytes,
    }
}

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

    /// Byte counts match the documented dimensions — guards against an
    /// off-by-one in the generator (e.g. forgetting to multiply by 4 for
    /// RGBA, or by `depth` for the 3D textures).
    #[test]
    fn byte_lengths_match_dimensions() {
        let p = NoisePack::generate();
        assert_eq!(p.noise_lq.bytes.len(), 256 * 256 * 4);
        assert_eq!(p.noise_mq.bytes.len(), 64 * 64 * 4);
        assert_eq!(p.noise_hq.bytes.len(), 32 * 32 * 4);
        assert_eq!(p.noisevol_lq.bytes.len(), 32 * 32 * 32 * 4);
        assert_eq!(p.noisevol_hq.bytes.len(), 8 * 8 * 8 * 4);
    }

    /// Two independent generations produce bit-identical output. Required
    /// for the determinism contract (re-loading a preset must not visibly
    /// change the noise).
    #[test]
    fn generation_is_deterministic() {
        let a = NoisePack::generate();
        let b = NoisePack::generate();
        assert_eq!(a.noise_lq.bytes, b.noise_lq.bytes);
        assert_eq!(a.noisevol_hq.bytes, b.noisevol_hq.bytes);
    }

    /// Each texture must use its own seed — if they accidentally share a
    /// stream the comp shader's mixing of `tex2D(noise_lq, …)` with
    /// `tex3D(noisevol_hq, …)` collapses to a single source of variance.
    /// Checking that the first 16 bytes diverge is a cheap but specific
    /// sanity test.
    #[test]
    fn textures_have_independent_streams() {
        let p = NoisePack::generate();
        assert_ne!(&p.noise_lq.bytes[..16], &p.noise_mq.bytes[..16]);
        assert_ne!(&p.noise_lq.bytes[..16], &p.noise_hq.bytes[..16]);
        assert_ne!(&p.noisevol_lq.bytes[..16], &p.noisevol_hq.bytes[..16]);
        assert_ne!(&p.noise_lq.bytes[..16], &p.noisevol_lq.bytes[..16]);
    }

    /// Output should look like noise: roughly uniform across the 0..=255
    /// range. We don't need a strict statistical test — a coarse histogram
    /// check is enough to catch bugs where a bad PRNG seed sticks at a
    /// constant or a small subrange.
    #[test]
    fn output_spans_full_byte_range() {
        let p = NoisePack::generate();
        let mut buckets = [0u32; 4];
        for &b in &p.noise_lq.bytes {
            buckets[(b / 64) as usize] += 1;
        }
        for (i, &count) in buckets.iter().enumerate() {
            assert!(
                count > 1000,
                "bucket {i} only got {count} samples out of {} — distribution looks broken",
                p.noise_lq.bytes.len()
            );
        }
    }

    /// `texsize` matches MD2's `vec4(w, h, 1/w, 1/h)` convention exactly —
    /// real presets read all four components and visual output diverges if
    /// the reciprocals are wrong.
    #[test]
    fn texsize_layout_matches_md2_convention() {
        let t = NoiseTexture {
            width: 256,
            height: 128,
            depth: 1,
            bytes: vec![],
        };
        let v = t.texsize();
        assert_eq!(v[0], 256.0);
        assert_eq!(v[1], 128.0);
        assert!((v[2] - 1.0 / 256.0).abs() < 1e-9);
        assert!((v[3] - 1.0 / 128.0).abs() < 1e-9);
    }
}