@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/renderer/texture/encode/chunk_bc1_encode_block.js

@@ -0,0 +1,375 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bc1_pack_block } from "./chunk_bc1_pack_block.js";
+
+/**
+ * Encode sixteen RGB texels as one BC1 block, four-colour mode.
+ *
+ * **The line through colour space is the whole problem**, and it is the problem BC7 inherits with
+ * more precision and BC6H with a different domain — which is why it is written once here as the
+ * shape the later encoders build on. A BC1 block is two 5:6:5 colours and every texel at one of
+ * four points on the segment between them, so the fit is: find the line, place its ends, then find
+ * the pair of *representable* ends that the decoder's own palette makes best.
+ *
+ * 1. **The principal axis**, by four rounds of power iteration on the block's covariance, seeded
+ *    with the bounding box's diagonal — `stb_dxt`'s choice, kept by betsy and `rgbcx`. Castaño
+ *    notes the iteration "is very sensitive to the initial approximation"; the diagonal is the
+ *    seed that already points the right way for the blocks that matter.
+ * 2. **The ends, then least squares.** The extreme projections on the axis start the line; two
+ *    rounds of assigning each texel its nearest of the four real palette points and re-solving
+ *    both ends by the normal equations — the same solve as `fit_endpoints.js`, with the weights
+ *    `0, 1/3, 2/3, 1` shared across the three channels — move it to where the texels are.
+ * 3. **Quantisation, then a search in 5:6:5.** The rounded pair is a starting point and not an
+ *    answer, because five- and six-bit ends are coarse enough that the best representable pair is
+ *    not the rounding of the best real one — §9.11 measured that at up to 1.3 dB for the transcoder.
+ *    So each of the six stored components is stepped up and down in turn, twice over, keeping any
+ *    step that lowers the block's error against the decoder's palette: coordinate descent, twelve
+ *    scores a round, no branch that depends on the content for how long it runs.
+ *
+ * A **flat block** is the case every table-driven encoder special-cases, because a single colour
+ * rounds to 5:6:5 with an error of up to four levels while a pair of ends whose one-third mix lands
+ * on the colour is exact to a level. The mix is searched per channel over the ends' neighbours,
+ * which is what `stb_dxt`'s optimal-match tables hold, computed rather than stored.
+ *
+ * The three-colour mode is never written: its fourth index is transparent black, and a block that
+ * decodes to a hole on a device sampling `bc1-rgba-unorm` is not a lower-quality block, it is a
+ * different picture. Alpha in the source is ignored; a caller with a cut-out wants BC7.
+ *
+ * The values are given in `[0, 1]` and fitted in `[0, 255]`, where the palette arithmetic is the
+ * decoder's: ends expanded from 5:6:5 by bit replication, interior points at exact thirds,
+ * truncated.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc1_encode_block = CodeChunk.from(
+    //language=WGSL
+    `
+// a colour quantised to 5:6:5 — each channel rounded to its bit count, as the format stores it
+fn bc1_quantise(color: vec3<f32>) -> vec3<i32> {
+    let scaled = round(clamp(color, vec3<f32>(0.0), vec3<f32>(255.0)) * vec3<f32>(31.0, 63.0, 31.0) / 255.0);
+
+    return vec3<i32>(scaled);
+}
+
+// the eight-bit colour a 5:6:5 colour decodes to, by the bit replication hardware uses
+fn bc1_expand(q: vec3<i32>) -> vec3<f32> {
+    return vec3<f32>(
+        f32((q.x << 3) | (q.x >> 2)),
+        f32((q.y << 2) | (q.y >> 4)),
+        f32((q.z << 3) | (q.z >> 2))
+    );
+}
+
+fn bc1_pack_565(q: vec3<i32>) -> u32 {
+    return (u32(q.x) << 11u) | (u32(q.y) << 5u) | u32(q.z);
+}
+
+// the four-colour palette's entry, as the decoder builds it: the ends, then thirds, truncated
+fn bc1_palette_entry(c0: vec3<f32>, c1: vec3<f32>, index: u32) -> vec3<f32> {
+    if (index == 0u) {
+        return c0;
+    }
+
+    if (index == 1u) {
+        return c1;
+    }
+
+    if (index == 2u) {
+        return floor((2.0 * c0 + c1) / 3.0);
+    }
+
+    return floor((c0 + 2.0 * c1) / 3.0);
+}
+
+// the palette entry nearest a colour, and its squared distance
+fn bc1_nearest(c0: vec3<f32>, c1: vec3<f32>, color: vec3<f32>) -> vec2<f32> {
+    var best = 0.0;
+    var best_distance = 1e30;
+
+    for (var index = 0u; index < 4u; index++) {
+        let delta = bc1_palette_entry(c0, c1, index) - color;
+        let distance = dot(delta, delta);
+
+        if (distance < best_distance) {
+            best_distance = distance;
+            best = f32(index);
+        }
+    }
+
+    return vec2<f32>(best, best_distance);
+}
+
+// the block's squared error against a quantised pair, in the mode their order selects; only the
+// four-colour mode is ever wanted, so an equal or inverted pair scores as unusable
+fn bc1_score(texels: array<vec3<f32>, 16>, q0: vec3<i32>, q1: vec3<i32>) -> f32 {
+    if (bc1_pack_565(q0) <= bc1_pack_565(q1)) {
+        return 1e30;
+    }
+
+    let c0 = bc1_expand(q0);
+    let c1 = bc1_expand(q1);
+
+    var error = 0.0;
+
+    for (var i = 0u; i < 16u; i++) {
+        error += bc1_nearest(c0, c1, texels[i]).y;
+    }
+
+    return error;
+}
+
+// the ends that best reproduce the texels at the palette points they are nearest to on a real line:
+// the two-by-two normal equations, shared across the channels because the weights are
+fn bc1_refine(texels: array<vec3<f32>, 16>, e0: vec3<f32>, e1: vec3<f32>) -> array<vec3<f32>, 2> {
+    var aa = 0.0;
+    var ab = 0.0;
+    var bb = 0.0;
+    var ap = vec3<f32>(0.0);
+    var bp = vec3<f32>(0.0);
+
+    for (var i = 0u; i < 16u; i++) {
+        // nearest of the four real points, by distance rather than by projection: the two are not
+        // the same thing once the ends have moved off the axis the texels were projected on
+        var best_weight = 0.0;
+        var best_distance = 1e30;
+
+        for (var step = 0u; step < 4u; step++) {
+            let weight = f32(step) / 3.0;
+            let delta = mix(e0, e1, weight) - texels[i];
+            let distance = dot(delta, delta);
+
+            if (distance < best_distance) {
+                best_distance = distance;
+                best_weight = weight;
+            }
+        }
+
+        let b = best_weight;
+        let a = 1.0 - b;
+
+        aa += a * a;
+        ab += a * b;
+        bb += b * b;
+        ap += a * texels[i];
+        bp += b * texels[i];
+    }
+
+    let determinant = aa * bb - ab * ab;
+
+    var out: array<vec3<f32>, 2>;
+
+    // singular when every texel took the same point; the line is as good as it gets
+    if (abs(determinant) < 1e-6) {
+        out[0] = e0;
+        out[1] = e1;
+
+        return out;
+    }
+
+    out[0] = (bb * ap - ab * bp) / determinant;
+    out[1] = (aa * bp - ab * ap) / determinant;
+
+    return out;
+}
+
+// a vector with one component replaced — built rather than assigned into a copy, so the same code
+// means the same thing on a device, where a copy is a value, and in the emulator, where it is not
+fn bc1_with_component(v: vec3<i32>, channel: i32, value: i32) -> vec3<i32> {
+    return vec3<i32>(
+        select(v.x, value, channel == 0),
+        select(v.y, value, channel == 1),
+        select(v.z, value, channel == 2)
+    );
+}
+
+// a flat block: per channel, the pair of stored values whose one-third mix lands nearest the colour,
+// which beats rounding the colour itself by up to three levels
+fn bc1_encode_flat(color: vec3<f32>) -> vec2<u32> {
+    let bits = vec3<i32>(31, 63, 31);
+    let centre = bc1_quantise(color);
+
+    var q0 = centre;
+    var q1 = centre;
+
+    for (var channel = 0; channel < 3; channel++) {
+        var best_distance = 1e30;
+
+        for (var da = -1; da <= 1; da++) {
+            for (var db = -1; db <= 1; db++) {
+                let a = clamp(centre[channel] + da, 0, bits[channel]);
+                let b = clamp(centre[channel] + db, 0, bits[channel]);
+
+                let qa = bc1_with_component(centre, channel, a);
+                let qb = bc1_with_component(centre, channel, b);
+
+                let mixed = floor((2.0 * bc1_expand(qa)[channel] + bc1_expand(qb)[channel]) / 3.0);
+                let distance = abs(mixed - color[channel]);
+
+                if (distance < best_distance) {
+                    best_distance = distance;
+                    q0 = bc1_with_component(q0, channel, a);
+                    q1 = bc1_with_component(q1, channel, b);
+                }
+            }
+        }
+    }
+
+    let first = bc1_pack_565(q0);
+    let second = bc1_pack_565(q1);
+
+    var indices: array<u32, 16>;
+
+    // the mix was searched as two thirds of q0 and one of q1, which is index 2 with q0 first; with
+    // the pair the other way round it is index 3; and equal ends are the three-colour mode, whose
+    // index 0 is the colour itself
+    let index = select(select(3u, 2u, first > second), 0u, first == second);
+
+    for (var i = 0u; i < 16u; i++) {
+        indices[i] = index;
+    }
+
+    if (first >= second) {
+        return bc1_pack_block(first, second, indices);
+    }
+
+    return bc1_pack_block(second, first, indices);
+}
+
+fn bc1_encode_block(texels: array<vec3<f32>, 16>) -> vec2<u32> {
+    var scaled: array<vec3<f32>, 16>;
+
+    var low = vec3<f32>(255.0);
+    var high = vec3<f32>(0.0);
+    var mean = vec3<f32>(0.0);
+
+    for (var i = 0u; i < 16u; i++) {
+        let v = clamp(texels[i], vec3<f32>(0.0), vec3<f32>(1.0)) * 255.0;
+
+        scaled[i] = v;
+        low = min(low, v);
+        high = max(high, v);
+        mean += v;
+    }
+
+    mean = mean / 16.0;
+
+    let extent = high - low;
+
+    if (max(extent.x, max(extent.y, extent.z)) < 0.5) {
+        return bc1_encode_flat(mean);
+    }
+
+    // the covariance's six distinct terms
+    var cov = array<f32, 6>(0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
+
+    for (var i = 0u; i < 16u; i++) {
+        let d = scaled[i] - mean;
+
+        cov[0] += d.x * d.x;
+        cov[1] += d.x * d.y;
+        cov[2] += d.x * d.z;
+        cov[3] += d.y * d.y;
+        cov[4] += d.y * d.z;
+        cov[5] += d.z * d.z;
+    }
+
+    // power iteration from the box diagonal, which is never zero here
+    var axis = extent;
+
+    for (var iteration = 0u; iteration < 4u; iteration++) {
+        let next = vec3<f32>(
+            cov[0] * axis.x + cov[1] * axis.y + cov[2] * axis.z,
+            cov[1] * axis.x + cov[3] * axis.y + cov[4] * axis.z,
+            cov[2] * axis.x + cov[4] * axis.y + cov[5] * axis.z
+        );
+
+        let magnitude = length(next);
+
+        // a degenerate covariance leaves the diagonal in charge
+        if (magnitude < 1e-3) {
+            break;
+        }
+
+        axis = next / magnitude;
+    }
+
+    axis = normalize(axis);
+
+    var t_min = 1e30;
+    var t_max = -1e30;
+
+    for (var i = 0u; i < 16u; i++) {
+        let t = dot(scaled[i] - mean, axis);
+
+        t_min = min(t_min, t);
+        t_max = max(t_max, t);
+    }
+
+    var e0 = mean + axis * t_min;
+    var e1 = mean + axis * t_max;
+
+    for (var round = 0u; round < 2u; round++) {
+        let refined = bc1_refine(scaled, e0, e1);
+
+        e0 = clamp(refined[0], vec3<f32>(0.0), vec3<f32>(255.0));
+        e1 = clamp(refined[1], vec3<f32>(0.0), vec3<f32>(255.0));
+    }
+
+    var q0 = bc1_quantise(e0);
+    var q1 = bc1_quantise(e1);
+
+    // four-colour mode wants the first end greater; a pair that rounded together is a flat block
+    if (bc1_pack_565(q0) < bc1_pack_565(q1)) {
+        let swap = q0;
+
+        q0 = q1;
+        q1 = swap;
+    }
+
+    if (bc1_pack_565(q0) == bc1_pack_565(q1)) {
+        return bc1_encode_flat(mean);
+    }
+
+    var best = bc1_score(scaled, q0, q1);
+
+    // coordinate descent over the six stored components, twice
+    let bits = vec3<i32>(31, 63, 31);
+
+    for (var round = 0u; round < 2u; round++) {
+        for (var component = 0; component < 6; component++) {
+            let channel = component % 3;
+
+            for (var direction = -1; direction <= 1; direction += 2) {
+                var c0 = q0;
+                var c1 = q1;
+
+                if (component < 3) {
+                    c0 = bc1_with_component(q0, channel, clamp(q0[channel] + direction, 0, bits[channel]));
+                } else {
+                    c1 = bc1_with_component(q1, channel, clamp(q1[channel] + direction, 0, bits[channel]));
+                }
+
+                let error = bc1_score(scaled, c0, c1);
+
+                if (error < best) {
+                    best = error;
+                    q0 = c0;
+                    q1 = c1;
+                }
+            }
+        }
+    }
+
+    let c0 = bc1_expand(q0);
+    let c1 = bc1_expand(q1);
+
+    var indices: array<u32, 16>;
+
+    for (var i = 0u; i < 16u; i++) {
+        indices[i] = u32(bc1_nearest(c0, c1, scaled[i]).x);
+    }
+
+    return bc1_pack_block(bc1_pack_565(q0), bc1_pack_565(q1), indices);
+}
+`, [
+        chunk_bc1_pack_block,
+    ]);

package/src/shade/renderer/texture/encode/chunk_bc1_pack_block.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One BC1 block from its two packed 5:6:5 endpoints and sixteen indices, as two little-endian words.
+ *
+ * The same layout `bc1_write_block` states in JavaScript: the first endpoint in the low sixteen
+ * bits, the second above it, then two bits per texel with texel 0 lowest. Kept apart from the
+ * fitting so the layout can be checked on its own against the JavaScript writer.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc1_pack_block: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc1_pack_block.d.ts.map

package/src/shade/renderer/texture/encode/chunk_bc1_pack_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc1_pack_block.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc1_pack_block.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,mCAFU,SAAS,CAchB;0BAvBuB,oCAAoC"}

package/src/shade/renderer/texture/encode/chunk_bc1_pack_block.js

@@ -0,0 +1,24 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * One BC1 block from its two packed 5:6:5 endpoints and sixteen indices, as two little-endian words.
+ *
+ * The same layout `bc1_write_block` states in JavaScript: the first endpoint in the low sixteen
+ * bits, the second above it, then two bits per texel with texel 0 lowest. Kept apart from the
+ * fitting so the layout can be checked on its own against the JavaScript writer.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc1_pack_block = CodeChunk.from(
+    //language=WGSL
+    `
+fn bc1_pack_block(first: u32, second: u32, indices: array<u32, 16>) -> vec2<u32> {
+    var packed = 0u;
+
+    for (var i = 0u; i < 16u; i++) {
+        packed |= (indices[i] & 3u) << (2u * i);
+    }
+
+    return vec2<u32>((first & 0xFFFFu) | ((second & 0xFFFFu) << 16u), packed);
+}
+`);

package/src/shade/renderer/texture/encode/chunk_bc4_encode_block.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Encode sixteen values as one BC4 block — unsigned through `bc4_encode_block`, signed through
+ * `bc4_encode_block_snorm`.
+ *
+ * **A fixed budget, spent where it counts.** One invocation owns one block, and everything below is
+ * loops of constant trip count over sixteen registers — no search whose depth depends on the
+ * content, because a compute lane that finishes early only waits for the one that did not.
+ *
+ * Two palettes are fitted and the better one is written, and each fit is the same three steps:
+ *
+ * 1. **The bounding line, refined by least squares.** The extremes are where every real-time encoder
+ *    starts, and where the 2007 real-time DXT work stopped, insetting them by a fraction of the
+ *    range instead. Solving the endpoints properly given the current step assignment — the normal
+ *    equations `fit_endpoints.js` solves — then reassigning, is what `stb_dxt`, `rgbcx` and the
+ *    NVIDIA tools all do, and two rounds are where it stops paying.
+ * 2. **A search of the integer endpoints around it, coarse to fine.** Least squares answers the
+ *    question it was asked — the best line *for the assignment it was given* — and the assignment
+ *    it was given is the one the seed line implied. Where a shorter line would serve most texels
+ *    better and hand the odd one to a neighbouring level, the solution sits in a different basin and
+ *    no rounding of the local answer reaches it. Scoring a candidate pair is sixteen texels' work, so
+ *    the basin is searched outright: five by five pairs at a spacing of eight, then two, then one,
+ *    seventy-five scores per mode, each against the palette the decoder will actually build. On the
+ *    mask fixture this is worth three decibels over the least-squares answer alone; on smooth content
+ *    it changes nothing and costs the same.
+ * 3. **Both modes.** `first > second` gives eight values along the line. `first <= second` gives six
+ *    along it plus the two hard extremes of the domain — so its line is seeded over the texels
+ *    *between* the extremes, and a block holding both extremes and a narrow band of values fits the
+ *    band with all six levels and gets the extremes for nothing. A mask with a soft edge is exactly
+ *    that block, and the eight-value line would spend its levels crossing the whole range.
+ *
+ * Every error is scored against the palette the decoder builds — each entry rounded to a level — and
+ * not against the real line, which is why the nearest step is checked with its two neighbours: the
+ * nearest point on the line is not always the nearest rounded entry.
+ *
+ * **The signed format is the same fit in a different domain**, which is why it is a second entry
+ * point and not a second chunk: its endpoints are two's-complement bytes decoded over `[-127, 127]`
+ * (`-128` reads as `-127`) and its six-value mode's hard entries are `-127` and `127`, so the domain's
+ * bounds are the only thing that changes. The unsigned path fits `[0, 1]` in `[0, 255]`; the signed
+ * one fits `[-1, 1]` in `[-127, 127]`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc4_encode_block: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc4_encode_block.d.ts.map

package/src/shade/renderer/texture/encode/chunk_bc4_encode_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc4_encode_block.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc4_encode_block.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qCAFU,SAAS,CAgTZ;0BA3VmB,oCAAoC"}