Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-render

Source of release 0.1.2

0.1.2 / shaders / splats.glsl

// Gaussian splats along a ray, after 3D Gaussian Ray Tracing (Moenne-Loccoz et
// al. 2024). The host's side is src/render/splats.lucb; the records are
// reached by address (K_SPLATS) and traced through the TLAS's splat instance
// (mask 2, a Blas of boxes) or the splats' own software BVH.
//
// The model. A ray meets each Gaussian once, at its point of maximum response:
// there the splat covers α = min(0.99, opacity · exp(-½ d²)), d the ray's
// Mahalanobis distance from the center, and shows its color, the SH evaluated
// toward the ray's direction (the viewport's display_color). Splats under the
// cull (1/255) or past 3σ do not count. Along a segment of a path, the splats
// met in order of distance add radiance Σ Tᵢ αᵢ cᵢ (Tᵢ = Π_{j<i} (1 - αⱼ)) and
// pass on the fraction T = Π (1 - αᵢ) of whatever lies beyond.
//
// In the integrator splats are a non-scattering layer that emits and absorbs.
// Nothing samples them as lights, so the emission a camera path's segment
// gathers is the only technique for it (weight 1, no MIS term); light sampling
// and light tracing see them only as transmittance, which is deterministic and
// the same for every technique that carries light along a segment (BSDF rays,
// shadow rays, light paths, their camera connections), so the MIS weights
// between techniques are untouched and the estimate stays unbiased. Captured
// lighting is emitted as it was captured; relit splats (Relight GSplats) bake
// their new colors into Cd and the SH before rendering. Light paths carry no
// splat emission (they start at lights) and are only attenuated.
//
// Long segments end by Russian roulette once less than 1% gets through: the
// segment survives with probability T / 0.01 and keeps T = 0.01, so the
// expected transmittance and emission are exact.

#extension GL_EXT_control_flow_attributes : require

#define K_SPLATS 25         // xy the records' address, zw the harmonics' address
#define K_SPLAT_TREE 26     // xy the software BVH's address, z the splat count, w the cull
#define SPLAT_K 32          // hits gathered per round (the k-buffer)
#define SPLAT_ROULETTE 0.01

layout(buffer_reference, std430, buffer_reference_align = 16) readonly buffer SplatRecords { uvec4 records[]; };
layout(buffer_reference, std430, buffer_reference_align = 4) readonly buffer SplatWords { uint words[]; };
struct SplatNode {
    vec3 lo;
    uint first;
    vec3 hi;
    uint count;
};
layout(buffer_reference, std430, buffer_reference_align = 16) readonly buffer SplatNodes { SplatNode nodes[]; };

uint64_t splat_address(vec2 bits) { return packUint2x32(uvec2(floatBitsToUint(bits.x), floatBitsToUint(bits.y))); }
SplatRecords splat_records() { return SplatRecords(splat_address(constants[K_SPLATS].xy)); }
SplatWords splat_words() { return SplatWords(splat_address(constants[K_SPLATS].zw)); }
SplatNodes splat_tree() { return SplatNodes(splat_address(constants[K_SPLAT_TREE].xy)); }
bool splats_present() { return HAS_SPLATS && constants[K_SPLAT_TREE].z > 0.0; }
float splat_cull() { return constants[K_SPLAT_TREE].w; }

// `v` turned by unit quaternion `q` (xyzw).
vec3 splat_turn(vec4 q, vec3 v) {
    vec3 t = 2.0 * cross(q.xyz, v);
    return v + q.w * t + cross(q.xyz, t);
}

// Splat `s`'s α where the ray from `o` along unit `d` passes nearest its center
// (in the splat's own metric), and the distance `t` there; 0 past 3σ. In the
// splat's frame scaled to unit σ the ray is o' + t d', and the squared distance
// of its nearest point is |o' × d'|² / |d'|², free of cancellation.
float splat_alpha(SplatRecords records, uint s, vec3 o, vec3 d, out float t) {
    uvec4 r0 = records.records[s * 4u];
    uvec4 r1 = records.records[s * 4u + 1u];
    uvec4 r2 = records.records[s * 4u + 2u];
    vec4 q = uintBitsToFloat(r1);
    vec3 inverse = uintBitsToFloat(r2.xyz);
    vec3 lo = splat_turn(q, o - uintBitsToFloat(r0.xyz)) * inverse;
    vec3 ld = splat_turn(q, d) * inverse;
    float dd = dot(ld, ld);
    t = -dot(lo, ld) / dd;
    vec3 c = cross(lo, ld);
    float m2 = dot(c, c) / dd;
    if (!(m2 <= 9.0)) return 0.0;
    float alpha = min(0.99, uintBitsToFloat(r0.w) * exp(-0.5 * m2));
    return alpha >= splat_cull() ? alpha : 0.0;
}

// The 3DGS SH constants (bands 1..3).
const float splat_c1 = 0.4886025119029199;
const float splat_c2[5] = float[5](1.0925484305920792, -1.0925484305920792, 0.31539156525252005, -1.0925484305920792, 0.5462742152960396);
const float splat_c3[7] = float[7](-0.5900435899266435, 2.890611442640554, -0.4570457994644658, 0.3731763325901154, -0.4570457994644658,
                                   1.445305721320277, -0.5900435899266435);

float splat_half(SplatWords words, uint first, uint index) {
    vec2 pair = unpackHalf2x16(words.words[first + (index >> 1u)]);
    return (index & 1u) == 0u ? pair.x : pair.y;
}

vec3 splat_item(SplatWords words, uint first, uint item) {
    return vec3(splat_half(words, first, item * 3u), splat_half(words, first, item * 3u + 1u), splat_half(words, first, item * 3u + 2u));
}

// The SH bands' color toward unit `d` (in the SH frame), over `used` items
// starting at word `first`; as luce-3d's splat_project.comp evaluates them.
vec3 splat_bands(SplatWords w, uint first, uint used, vec3 d) {
    float x = d.x, y = d.y, z = d.z;
    vec3 c = -splat_c1 * y * splat_item(w, first, 0u) + splat_c1 * z * splat_item(w, first, 1u) - splat_c1 * x * splat_item(w, first, 2u);
    if (used < 8u) return c;
    float xx = x * x, yy = y * y, zz = z * z;
    c += splat_c2[0] * x * y * splat_item(w, first, 3u) + splat_c2[1] * y * z * splat_item(w, first, 4u)
       + splat_c2[2] * (2.0 * zz - xx - yy) * splat_item(w, first, 5u) + splat_c2[3] * x * z * splat_item(w, first, 6u)
       + splat_c2[4] * (xx - yy) * splat_item(w, first, 7u);
    if (used < 15u) return c;
    c += splat_c3[0] * y * (3.0 * xx - yy) * splat_item(w, first, 8u) + splat_c3[1] * x * y * z * splat_item(w, first, 9u)
       + splat_c3[2] * y * (4.0 * zz - xx - yy) * splat_item(w, first, 10u) + splat_c3[3] * z * (2.0 * zz - 3.0 * xx - 3.0 * yy) * splat_item(w, first, 11u)
       + splat_c3[4] * x * (4.0 * zz - xx - yy) * splat_item(w, first, 12u) + splat_c3[5] * z * (xx - yy) * splat_item(w, first, 13u)
       + splat_c3[6] * x * (xx - 3.0 * yy) * splat_item(w, first, 14u);
    return c;
}

float splat_srgb_decode(float c) {
    return c <= 0.04045 ? c / 12.92 : pow((c + 0.055) / 1.055, 2.4);
}

// Splat `s`'s radiance seen along unit `d`: the DC (in the cloud's encoding)
// plus the bands, clamped at 0, decoded, from linear Rec.709 to ACEScg, as a Spec.
Spec splat_radiance(SplatRecords records, uint s, vec3 d, vec4 lambda) {
    uvec4 r2 = records.records[s * 4u + 2u];
    uvec4 r3 = records.records[s * 4u + 3u];
    vec3 encoded = uintBitsToFloat(r3.xyz);
    uint items = r3.w & 31u;
    if (items >= 3u) {
        SplatWords words = splat_words();
        uint first = r2.w;
        vec4 frame = vec4(unpackHalf2x16(words.words[first]), unpackHalf2x16(words.words[first + 1u]));
        frame /= max(length(frame), 1e-20);
        encoded += splat_bands(words, first + 2u, items, splat_turn(frame, d));
    }
    encoded = max(encoded, vec3(0.0));
    if ((r3.w & 32u) != 0u)
        encoded = vec3(splat_srgb_decode(encoded.r), splat_srgb_decode(encoded.g), splat_srgb_decode(encoded.b));
    // Rec.709 to ACEScg (Bradford), as src/render/environment.lucb.
    vec3 aces = vec3(dot(vec3(0.613097, 0.339523, 0.047379), encoded), dot(vec3(0.070194, 0.916354, 0.013452), encoded),
                     dot(vec3(0.020616, 0.109570, 0.869815), encoded));
    return spec_of_texel(aces, lambda);
}

// A 32-bit mix (sampler.glsl's hash_u32): roulette needs no low-discrepancy numbers.
uint splat_hash(uint x) {
    x ^= x >> 16; x *= 0x21f0aaadu;
    x ^= x >> 15; x *= 0x735a2d97u;
    x ^= x >> 15;
    return x;
}

// A segment's seed: the path, the sample and the bounce, salted per use.
uint splat_seed(uint path, uint bounces, uint salt) {
    return splat_hash(path ^ splat_hash(params.sample_index * 0x9e3779b9u + params.seed) ^ (bounces * 0x85ebca6bu) ^ salt);
}

// A uniform number in [0, 1) for roulette `round` of a segment.
float splat_random(uint seed, uint round) {
    return float(splat_hash(seed ^ (round * 0x9e3779b9u)) >> 8) * (1.0 / 16777216.0);
}

// Russian roulette on a transmittance under SPLAT_ROULETTE: kept at
// SPLAT_ROULETTE with probability T / SPLAT_ROULETTE, else 0.
float splat_roulette(float kept, uint seed, uint round) {
    if (kept >= SPLAT_ROULETTE) return kept;
    return splat_random(seed, round) * SPLAT_ROULETTE < kept ? SPLAT_ROULETTE : 0.0;
}

// The k nearest splats of a round: distances ascending and the splats; empty
// slots hold t = INFINITY. Every index below is a constant once the loops are
// unrolled, so the arrays stay in registers (indexed at run time they went to
// thread memory, the kernel's largest cost), and α is not kept but evaluated
// again when the round is composited, which keeps the state a third smaller.
// 32 slots finish most rays in one round; a round costs a whole traversal.
struct SplatHits {
    float t[SPLAT_K];
    uint s[SPLAT_K];
};

void splat_hits_clear(out SplatHits hits) {
    [[unroll]] for (uint i = 0u; i < SPLAT_K; i++) {
        hits.t[i] = INFINITY;
        hits.s[i] = 0u;
    }
}

bool splat_hits_full(SplatHits hits) { return hits.t[SPLAT_K - 1u] < INFINITY; }

// Keep hit (t, s) among the nearest SPLAT_K by insertion: each slot keeps
// the nearer of itself and the hit carried down; the farthest falls off the end.
void splat_keep(inout SplatHits hits, float t, uint s) {
    [[unroll]] for (uint i = 0u; i < SPLAT_K; i++) {
        bool nearer = t < hits.t[i];
        float kt = hits.t[i];
        uint ks = hits.s[i];
        hits.t[i] = nearer ? t : kt;
        hits.s[i] = nearer ? s : ks;
        t = nearer ? kt : t;
        s = nearer ? ks : s;
    }
}

// The entry distance of the ray into a node's box within [t_lo, t_hi], or -1.
float splat_box_entry(vec3 lo, vec3 hi, vec3 origin, vec3 inverse, float t_lo, float t_hi) {
    vec3 a = (lo - origin) * inverse;
    vec3 b = (hi - origin) * inverse;
    vec3 near = min(a, b);
    vec3 far = max(a, b);
    float enter = max(max(near.x, near.y), max(near.z, t_lo));
    float leave = min(min(far.x, far.y), min(far.z, t_hi));
    return enter <= leave ? enter : -1.0;
}

#define SPLAT_STACK 48

// The SPLAT_K nearest splats whose maximum response lies in (t_lo, t_hi).
SplatHits splat_gather(vec3 o, vec3 d, float t_lo, float t_hi) {
    SplatHits hits;
    splat_hits_clear(hits);
    SplatRecords records = splat_records();
    float cutoff = t_hi;
#if RAY_QUERY
    rayQueryInitializeEXT(query, scene_tlas, gl_RayFlagsNoneEXT, 0x02u, o, t_lo, d, t_hi);
    while (rayQueryProceedEXT(query)) {
        if (rayQueryGetIntersectionTypeEXT(query, false) != gl_RayQueryCandidateIntersectionAABBEXT) continue;
        uint s = uint(rayQueryGetIntersectionPrimitiveIndexEXT(query, false));
        float t;
        float alpha = splat_alpha(records, s, o, d, t);
        if (alpha <= 0.0 || !(t > t_lo && t < cutoff)) continue;
        splat_keep(hits, t, s);
        // Full: nothing past the farthest kept can enter, so the query culls beyond it.
        if (splat_hits_full(hits)) {
            cutoff = hits.t[SPLAT_K - 1u];
            rayQueryGenerateIntersectionEXT(query, cutoff);
        }
    }
#else
    SplatNodes tree = splat_tree();
    vec3 safe = mix(d, sign(d) * 1e-20 + vec3(equal(d, vec3(0.0))) * 1e-20, lessThan(abs(d), vec3(1e-20)));
    vec3 inverse = 1.0 / safe;
    uint stack[SPLAT_STACK];
    uint depth = 0u;
    uint node = 0u;
    if (tree.nodes[0].lo.x > tree.nodes[0].hi.x || splat_box_entry(tree.nodes[0].lo, tree.nodes[0].hi, o, inverse, t_lo, cutoff) < 0.0) return hits;
    while (true) {
        SplatNode current = tree.nodes[node];
        if (current.count > 0u) {
            for (uint i = 0u; i < current.count; i++) {
                uint s = current.first + i;
                float t;
                float alpha = splat_alpha(records, s, o, d, t);
                if (alpha <= 0.0 || !(t > t_lo && t < cutoff)) continue;
                splat_keep(hits, t, s);
                if (splat_hits_full(hits)) cutoff = hits.t[SPLAT_K - 1u];
            }
        } else {
            uint left = current.first;
            float a = splat_box_entry(tree.nodes[left].lo, tree.nodes[left].hi, o, inverse, t_lo, cutoff);
            float b = splat_box_entry(tree.nodes[left + 1u].lo, tree.nodes[left + 1u].hi, o, inverse, t_lo, cutoff);
            if (a >= 0.0 && b >= 0.0) {
                uint near_child = a <= b ? left : left + 1u;
                if (depth < SPLAT_STACK) stack[depth++] = a <= b ? left + 1u : left;
                node = near_child;
                continue;
            }
            if (a >= 0.0) { node = left; continue; }
            if (b >= 0.0) { node = left + 1u; continue; }
        }
        // Nodes waiting on the stack may have fallen past the cutoff since.
        bool found = false;
        while (depth > 0u && !found) {
            node = stack[--depth];
            found = splat_box_entry(tree.nodes[node].lo, tree.nodes[node].hi, o, inverse, t_lo, cutoff) >= 0.0;
        }
        if (!found) break;
    }
#endif
    return hits;
}

// The splats along the ray from `o` (unit `d`) up to `t_hi`, front to back:
// the radiance they add (`added`, to be weighed by the path's throughput) and
// the fraction they pass on (`kept`), in rounds of the SPLAT_K nearest.
void splat_composite(vec3 o, vec3 d, float t_hi, vec4 lambda, uint seed, out Spec added, out float kept) {
    added = Spec(0.0);
    kept = 1.0;
    SplatRecords records = splat_records();
    float t_lo = 0.0;
    for (uint round = 0u; round < 4096u; round++) {
        SplatHits hits = splat_gather(o, d, t_lo, t_hi);
        [[unroll]] for (uint i = 0u; i < SPLAT_K; i++) {
            if (hits.t[i] == INFINITY) break;
            float t;
            float alpha = splat_alpha(records, hits.s[i], o, d, t);
            added += splat_radiance(records, hits.s[i], d, lambda) * (kept * alpha);
            kept *= 1.0 - alpha;
        }
        if (!splat_hits_full(hits)) return;
        t_lo = hits.t[SPLAT_K - 1u];
        kept = splat_roulette(kept, seed, round);
        if (kept == 0.0) return;
    }
}

// The fraction of light the splats pass along the ray from `o` (unit `d`)
// over (t_lo, t_hi): the product of their (1 - α), in any order.
float splat_transmittance(vec3 o, vec3 d, float t_lo, float t_hi, uint seed) {
    float kept = 1.0;
    uint round = 0u;
    SplatRecords records = splat_records();
#if RAY_QUERY
    rayQueryInitializeEXT(query, scene_tlas, gl_RayFlagsNoneEXT, 0x02u, o, t_lo, d, t_hi);
    while (rayQueryProceedEXT(query)) {
        if (rayQueryGetIntersectionTypeEXT(query, false) != gl_RayQueryCandidateIntersectionAABBEXT) continue;
        float t;
        float alpha = splat_alpha(records, uint(rayQueryGetIntersectionPrimitiveIndexEXT(query, false)), o, d, t);
        if (alpha <= 0.0 || !(t > t_lo && t < t_hi)) continue;
        kept *= 1.0 - alpha;
        if (kept < SPLAT_ROULETTE) {
            kept = splat_roulette(kept, seed, round++);
            if (kept == 0.0) {
                rayQueryTerminateEXT(query);
                return 0.0;
            }
        }
    }
#else
    SplatNodes tree = splat_tree();
    vec3 safe = mix(d, sign(d) * 1e-20 + vec3(equal(d, vec3(0.0))) * 1e-20, lessThan(abs(d), vec3(1e-20)));
    vec3 inverse = 1.0 / safe;
    uint stack[SPLAT_STACK];
    uint depth = 0u;
    uint node = 0u;
    if (tree.nodes[0].lo.x > tree.nodes[0].hi.x || splat_box_entry(tree.nodes[0].lo, tree.nodes[0].hi, o, inverse, t_lo, t_hi) < 0.0) return 1.0;
    while (true) {
        SplatNode current = tree.nodes[node];
        if (current.count > 0u) {
            for (uint i = 0u; i < current.count; i++) {
                float t;
                float alpha = splat_alpha(records, current.first + i, o, d, t);
                if (alpha <= 0.0 || !(t > t_lo && t < t_hi)) continue;
                kept *= 1.0 - alpha;
                if (kept < SPLAT_ROULETTE) {
                    kept = splat_roulette(kept, seed, round++);
                    if (kept == 0.0) return 0.0;
                }
            }
        } else {
            uint left = current.first;
            bool a = splat_box_entry(tree.nodes[left].lo, tree.nodes[left].hi, o, inverse, t_lo, t_hi) >= 0.0;
            bool b = splat_box_entry(tree.nodes[left + 1u].lo, tree.nodes[left + 1u].hi, o, inverse, t_lo, t_hi) >= 0.0;
            if (a && b) {
                if (depth < SPLAT_STACK) stack[depth++] = left + 1u;
                node = left;
                continue;
            }
            if (a) { node = left; continue; }
            if (b) { node = left + 1u; continue; }
        }
        if (depth == 0u) break;
        node = stack[--depth];
    }
#endif
    return kept;
}