@woosh/meep-engine 3.14.2 → 3.14.3

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

@@ -0,0 +1,310 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_astc_pack_4x4_rgb } from "./chunk_astc_pack_4x4_rgb.js";
+
+/**
+ * Encode sixteen RGB texels as one ASTC 4x4 block: one partition, eight-bit endpoints, three-bit
+ * weights.
+ *
+ * **The one corner of ASTC this tree can already read.** Step 9f derived this block's layout from
+ * the specification and beat the reference encoder with it; step 9h inverted the packings. What is
+ * ported here is the encoder's part: the same RGB line as BC1's, fitted under ASTC's own
+ * arithmetic, which is not BC1's in two places that each cost a level if ignored:
+ *
+ * 1. **The interpolation.** ASTC widens each eight-bit endpoint to sixteen by replication,
+ *    interpolates there with a `+32` round, and takes the top eight bits. Against the direct form
+ *    that disagrees on one texel in twenty, always by a level, so every score here is the
+ *    specification's form — `astc_interpolate` in `astc_block.js`, in WGSL.
+ * 2. **The endpoint order.** Colour endpoint mode 8 compares the two ends by the sum of their
+ *    channels and, when the second's is below the first's, *swaps them and blue-contracts both* —
+ *    a different picture, not a mirrored one, recorded by no bit. So a fitted pair whose sums come
+ *    out the wrong way round is written the other way up with its weights inverted, which decodes
+ *    identically; that is `astc_order_endpoints`, in WGSL.
+ *
+ * Eight weight levels, unevenly spaced — `0, 9, 18, 27, 37, 46, 55, 64` of 64 — over eight-bit
+ * ends: between BC1 and BC7 mode 6 in what it can hold, at BC7's eight bits a texel. The fit is
+ * the principal axis, the extreme projections, two rounds of least squares with those weights, and
+ * one round of coordinate descent over the six stored bytes against the decoder's palette. Alpha
+ * is not read: mode 8 carries none, and a cut-out wants the RGBA mode, which is a later chunk.
+ *
+ * This is the only target here that no device in reach can sample, so it rests on the CPU decoder
+ * alone — the decoder that §9.17 held against the reference encoder's blocks before trusting it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_astc_encode_block_4x4_rgb = CodeChunk.from(
+    //language=WGSL
+    `
+// what a three-bit weight unquantizes to, out of 64: replicated up to six bits and nudged so the
+// top of the range is exactly 64
+fn astc_weight3(index: u32) -> f32 {
+    var weights = array<f32, 8>(0.0, 9.0, 18.0, 27.0, 37.0, 46.0, 55.0, 64.0);
+
+    return weights[index];
+}
+
+// one channel decoded as the format decodes it: sixteen-bit replicated ends, a rounded weighted
+// sum, the top eight bits
+fn astc_interpolate(c0: f32, c1: f32, weight: f32) -> f32 {
+    let wide0 = c0 * 257.0;
+    let wide1 = c1 * 257.0;
+
+    return floor(floor((wide0 * (64.0 - weight) + wide1 * weight + 32.0) / 64.0) / 256.0);
+}
+
+fn astc_palette_entry(e0: vec3<f32>, e1: vec3<f32>, index: u32) -> vec3<f32> {
+    let w = astc_weight3(index);
+
+    return vec3<f32>(
+        astc_interpolate(e0.x, e1.x, w),
+        astc_interpolate(e0.y, e1.y, w),
+        astc_interpolate(e0.z, e1.z, w)
+    );
+}
+
+// the weight whose palette entry is nearest a texel, and the squared distance
+fn astc_nearest(e0: vec3<f32>, e1: vec3<f32>, texel: vec3<f32>) -> vec2<f32> {
+    let direction = e1 - e0;
+    let span = dot(direction, direction);
+
+    var estimate = 0.0;
+
+    if (span > 0.0) {
+        estimate = clamp(round(dot(texel - e0, direction) / span * 7.0), 0.0, 7.0);
+    }
+
+    var best = estimate;
+    var best_distance = 1e30;
+
+    for (var offset = -1.0; offset <= 1.0; offset += 1.0) {
+        let candidate = clamp(estimate + offset, 0.0, 7.0);
+
+        let delta = astc_palette_entry(e0, e1, u32(candidate)) - texel;
+        let distance = dot(delta, delta);
+
+        if (distance < best_distance) {
+            best_distance = distance;
+            best = candidate;
+        }
+    }
+
+    return vec2<f32>(best, best_distance);
+}
+
+fn astc_score(texels: array<vec3<f32>, 16>, e0: vec3<f32>, e1: vec3<f32>) -> f32 {
+    var error = 0.0;
+
+    for (var i = 0u; i < 16u; i++) {
+        error += astc_nearest(e0, e1, texels[i]).y;
+    }
+
+    return error;
+}
+
+fn astc_refine(texels: array<vec3<f32>, 16>, e0: vec3<f32>, e1: vec3<f32>) -> array<vec3<f32>, 2> {
+    let direction = e1 - e0;
+    let span = dot(direction, direction);
+
+    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++) {
+        var estimate = 0.0;
+
+        if (span > 0.0) {
+            estimate = clamp(round(dot(texels[i] - e0, direction) / span * 7.0), 0.0, 7.0);
+        }
+
+        var best_weight = 0.0;
+        var best_distance = 1e30;
+
+        for (var offset = -1.0; offset <= 1.0; offset += 1.0) {
+            let candidate = clamp(estimate + offset, 0.0, 7.0);
+            let weight = astc_weight3(u32(candidate)) / 64.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>;
+
+    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;
+}
+
+fn astc_with_component(v: vec3<f32>, channel: u32, value: f32) -> vec3<f32> {
+    return vec3<f32>(
+        select(v.x, value, channel == 0u),
+        select(v.y, value, channel == 1u),
+        select(v.z, value, channel == 2u)
+    );
+}
+
+fn astc_encode_block_4x4_rgb(texels: array<vec3<f32>, 16>) -> vec4<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;
+
+    var e0 = mean;
+    var e1 = mean;
+
+    if (max(extent.x, max(extent.y, extent.z)) >= 0.5) {
+        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;
+        }
+
+        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);
+
+            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);
+        }
+
+        e0 = mean + axis * t_min;
+        e1 = mean + axis * t_max;
+
+        for (var round = 0u; round < 2u; round++) {
+            let refined = astc_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 = round(e0);
+    var q1 = round(e1);
+
+    var best = astc_score(scaled, q0, q1);
+
+    // coordinate descent over the six stored bytes, one round
+    for (var component = 0u; component < 6u; component++) {
+        let channel = component % 3u;
+
+        for (var direction = -1.0; direction <= 1.0; direction += 2.0) {
+            var c0 = q0;
+            var c1 = q1;
+
+            if (component < 3u) {
+                c0 = astc_with_component(q0, channel, clamp(q0[channel] + direction, 0.0, 255.0));
+            } else {
+                c1 = astc_with_component(q1, channel, clamp(q1[channel] + direction, 0.0, 255.0));
+            }
+
+            let error = astc_score(scaled, c0, c1);
+
+            if (error < best) {
+                best = error;
+                q0 = c0;
+                q1 = c1;
+            }
+        }
+    }
+
+    var weights: array<u32, 16>;
+
+    for (var i = 0u; i < 16u; i++) {
+        weights[i] = u32(astc_nearest(q0, q1, scaled[i]).x);
+    }
+
+    // mode 8's rule: with the second end's channel sum below the first's, a decoder swaps and
+    // blue-contracts, so such a pair is written the other way up with its weights inverted
+    if (q1.x + q1.y + q1.z < q0.x + q0.y + q0.z) {
+        let swap = q0;
+
+        q0 = q1;
+        q1 = swap;
+
+        for (var i = 0u; i < 16u; i++) {
+            weights[i] = 7u - weights[i];
+        }
+    }
+
+    var endpoints: array<u32, 6>;
+
+    endpoints[0] = u32(q0.x);
+    endpoints[1] = u32(q1.x);
+    endpoints[2] = u32(q0.y);
+    endpoints[3] = u32(q1.y);
+    endpoints[4] = u32(q0.z);
+    endpoints[5] = u32(q1.z);
+
+    return astc_pack_4x4_rgb(endpoints, weights);
+}
+`, [
+        chunk_astc_pack_4x4_rgb,
+    ]);

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

@@ -0,0 +1,17 @@
+/**
+ * One ASTC 4x4 block of the shape this tree writes and reads — block mode `0x53`, one partition,
+ * colour endpoint mode 8 (LDR RGB, direct), six eight-bit endpoint values, sixteen three-bit
+ * weights — as four little-endian words.
+ *
+ * The layout `astc_write_block` states in JavaScript, and which §9.17 confirmed against the
+ * reference encoder's own blocks: the block mode in bits 0..10, the partition count less one in
+ * 11..12, the endpoint mode in 13..16, the endpoints from bit 17 in the order `R0 R1 G0 G1 B0 B1`,
+ * and the weights filling the top of the block with the whole field's bit order reversed — texel
+ * 0's weight ends up in the most significant bits. The mode-8 rule about which way round the
+ * endpoints go is the encoder's to honour, and this does not check it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_astc_pack_4x4_rgb: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_astc_pack_4x4_rgb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_astc_pack_4x4_rgb.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_astc_pack_4x4_rgb.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,sCAFU,SAAS,CAoChB;0BAlDuB,oCAAoC"}

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

@@ -0,0 +1,51 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * One ASTC 4x4 block of the shape this tree writes and reads — block mode `0x53`, one partition,
+ * colour endpoint mode 8 (LDR RGB, direct), six eight-bit endpoint values, sixteen three-bit
+ * weights — as four little-endian words.
+ *
+ * The layout `astc_write_block` states in JavaScript, and which §9.17 confirmed against the
+ * reference encoder's own blocks: the block mode in bits 0..10, the partition count less one in
+ * 11..12, the endpoint mode in 13..16, the endpoints from bit 17 in the order `R0 R1 G0 G1 B0 B1`,
+ * and the weights filling the top of the block with the whole field's bit order reversed — texel
+ * 0's weight ends up in the most significant bits. The mode-8 rule about which way round the
+ * endpoints go is the encoder's to honour, and this does not check it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_astc_pack_4x4_rgb = CodeChunk.from(
+    //language=WGSL
+    `
+fn astc_pack_4x4_rgb(endpoints: array<u32, 6>, weights: array<u32, 16>) -> vec4<u32> {
+    var words = array<u32, 4>(0u, 0u, 0u, 0u);
+
+    // block mode 0x53: a 4x4 grid of three-bit weights on one plane; partition count 1; CEM 8
+    words[0] = 0x53u | (8u << 13u);
+
+    for (var i = 0u; i < 6u; i++) {
+        let bit = 17u + i * 8u;
+
+        for (var k = 0u; k < 8u; k++) {
+            if (((endpoints[i] >> k) & 1u) != 0u) {
+                let at = bit + k;
+
+                words[at >> 5u] |= 1u << (at & 31u);
+            }
+        }
+    }
+
+    // the weight field, built the natural way round and mirrored into the top of the block
+    for (var texel = 0u; texel < 16u; texel++) {
+        for (var k = 0u; k < 3u; k++) {
+            if (((weights[texel] >> k) & 1u) != 0u) {
+                let at = 127u - (texel * 3u + k);
+
+                words[at >> 5u] |= 1u << (at & 31u);
+            }
+        }
+    }
+
+    return vec4<u32>(words[0], words[1], words[2], words[3]);
+}
+`);

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

@@ -0,0 +1,42 @@
+/**
+ * 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;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc1_encode_block.d.ts.map

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

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