@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,346 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bc6h_pack_mode11 } from "./chunk_bc6h_pack_mode11.js";
+
+/**
+ * Encode sixteen HDR RGB texels as one BC6H block in mode 11, the unsigned format.
+ *
+ * **The line is fitted in the half-float bit domain, because that is the domain the decoder
+ * interpolates in.** A BC6H endpoint is a half-float bit pattern quantised to ten bits; the decoder
+ * unquantises it to a sixteen-bit integer, interpolates the two ends linearly with BC7's four-bit
+ * weights, scales the result by 31/64 and reinterprets the integer *as a half*. So the palette is
+ * linear in bit patterns, not in values — which is a log-like scale, sixteen steps between two
+ * ends a few octaves apart being spaced by ratio rather than by difference. Fitting in that domain
+ * is what Narkowicz's real-time BC6H does with `f32tof16` before anything else, and it is why an
+ * error measured there is a relative error, which is what an HDR image wants judged.
+ *
+ * The fit is {@link chunk_bc1_encode_block}'s line in that domain: the principal axis, the extreme
+ * projections, two rounds of least squares with the sixteen decode weights, then quantisation to
+ * ten bits and one round of coordinate descent over the six stored components, every candidate
+ * scored against the palette the decoder builds. The anchor is honoured by writing the block the
+ * other way up when texel 0 lands in the upper half.
+ *
+ * **Mode 11 only.** It has the finest endpoints of the one-region modes and no delta to fit; the
+ * two-region modes are where a hard edge inside a block would gain, and they are a later chunk. On
+ * the environment maps the format exists for, Narkowicz measured his mode-11-only fast path within
+ * reach of offline encoders' fast presets.
+ *
+ * Half floats hold no infinity or NaN here and no sign: a negative texel clamps to zero, and
+ * anything over the largest finite half to that. The conversion to half bits is written out rather
+ * than taken from `pack2x16float`, so that the emulator and every device round the same way.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc6h_encode_block_mode11 = CodeChunk.from(
+    //language=WGSL
+    `
+// the bit pattern of the half nearest a non-negative finite value, ties to even, as f32tof16 gives
+fn bc6h_half_bits(x: f32) -> f32 {
+    let v = clamp(select(x, 0.0, x != x), 0.0, 65504.0);
+
+    if (v == 0.0) {
+        return 0.0;
+    }
+
+    let bits = bitcast<u32>(v);
+    let exponent = i32((bits >> 23u) & 0xFFu) - 127;
+
+    // a half's subnormals count in units of 2^-24; the tie goes to even, written out because the
+    // emulator's round is half-up and a device's is half-even
+    if (exponent < -14) {
+        let scaled = v * 16777216.0;
+        let whole = floor(scaled);
+        let fraction = scaled - whole;
+
+        let up = fraction > 0.5 || (fraction == 0.5 && (u32(whole) & 1u) == 1u);
+
+        return whole + select(0.0, 1.0, up);
+    }
+
+    let mantissa = bits & 0x7FFFFFu;
+    let kept = mantissa >> 13u;
+    let dropped = mantissa & 0x1FFFu;
+
+    var pattern = (u32(exponent + 15) << 10u) | kept;
+
+    if (dropped > 0x1000u || (dropped == 0x1000u && (kept & 1u) == 1u)) {
+        pattern += 1u;
+    }
+
+    return f32(min(pattern, 0x7BFFu));
+}
+
+// BC7's four-bit interpolation weights, which BC6H shares
+fn bc6h_weight4(index: u32) -> f32 {
+    var weights = array<f32, 16>(0.0, 4.0, 9.0, 13.0, 17.0, 21.0, 26.0, 30.0, 34.0, 38.0, 43.0, 47.0, 51.0, 55.0, 60.0, 64.0);
+
+    return weights[index];
+}
+
+// a ten-bit endpoint as the decoder unquantises it before interpolating
+fn bc6h_unquantize(q: vec3<f32>) -> vec3<f32> {
+    let scaled = floor((q * 65536.0 + 32768.0) / 1024.0);
+
+    return select(select(scaled, vec3<f32>(65535.0), q >= vec3<f32>(1023.0)), vec3<f32>(0.0), q <= vec3<f32>(0.0));
+}
+
+// a palette entry, as half bits, from two unquantised ends
+fn bc6h_palette_entry(u0: vec3<f32>, u1: vec3<f32>, index: u32) -> vec3<f32> {
+    let w = bc6h_weight4(index);
+
+    let interpolated = floor((u0 * (64.0 - w) + u1 * w + 32.0) / 64.0);
+
+    return floor(interpolated * 31.0 / 64.0);
+}
+
+// a value in half bits quantised to the ten bits the block stores
+fn bc6h_quantize(bits: vec3<f32>) -> vec3<f32> {
+    return clamp(round(bits * 1024.0 / 31744.0), vec3<f32>(0.0), vec3<f32>(1023.0));
+}
+
+// the index whose palette entry is nearest a texel, and the squared distance in half bits
+fn bc6h_nearest(u0: vec3<f32>, u1: vec3<f32>, texel: vec3<f32>) -> vec2<f32> {
+    let p0 = bc6h_palette_entry(u0, u1, 0u);
+    let p15 = bc6h_palette_entry(u0, u1, 15u);
+
+    let direction = p15 - p0;
+    let span = dot(direction, direction);
+
+    var estimate = 0.0;
+
+    if (span > 0.0) {
+        estimate = clamp(round(dot(texel - p0, direction) / span * 15.0), 0.0, 15.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, 15.0);
+
+        let delta = bc6h_palette_entry(u0, u1, u32(candidate)) - texel;
+        let distance = dot(delta, delta);
+
+        if (distance < best_distance) {
+            best_distance = distance;
+            best = candidate;
+        }
+    }
+
+    return vec2<f32>(best, best_distance);
+}
+
+fn bc6h_score(texels: array<vec3<f32>, 16>, q0: vec3<f32>, q1: vec3<f32>) -> f32 {
+    let u0 = bc6h_unquantize(q0);
+    let u1 = bc6h_unquantize(q1);
+
+    var error = 0.0;
+
+    for (var i = 0u; i < 16u; i++) {
+        error += bc6h_nearest(u0, u1, texels[i]).y;
+    }
+
+    return error;
+}
+
+// the ends that best reproduce the texels at the weights they are nearest to on a real line
+fn bc6h_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 * 15.0), 0.0, 15.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, 15.0);
+            let weight = bc6h_weight4(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 bc6h_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 bc6h_encode_block_mode11(texels: array<vec3<f32>, 16>) -> vec4<u32> {
+    var bits: array<vec3<f32>, 16>;
+
+    var low = vec3<f32>(65535.0);
+    var high = vec3<f32>(0.0);
+    var mean = vec3<f32>(0.0);
+
+    for (var i = 0u; i < 16u; i++) {
+        let v = vec3<f32>(bc6h_half_bits(texels[i].x), bc6h_half_bits(texels[i].y), bc6h_half_bits(texels[i].z));
+
+        bits[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 = bits[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(bits[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 = bc6h_refine(bits, e0, e1);
+
+            e0 = clamp(refined[0], vec3<f32>(0.0), vec3<f32>(31743.0));
+            e1 = clamp(refined[1], vec3<f32>(0.0), vec3<f32>(31743.0));
+        }
+    }
+
+    var q0 = bc6h_quantize(e0);
+    var q1 = bc6h_quantize(e1);
+
+    var best = bc6h_score(bits, q0, q1);
+
+    // coordinate descent over the six stored components, 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 = bc6h_with_component(q0, channel, clamp(q0[channel] + direction, 0.0, 1023.0));
+            } else {
+                c1 = bc6h_with_component(q1, channel, clamp(q1[channel] + direction, 0.0, 1023.0));
+            }
+
+            let error = bc6h_score(bits, c0, c1);
+
+            if (error < best) {
+                best = error;
+                q0 = c0;
+                q1 = c1;
+            }
+        }
+    }
+
+    var indices: array<u32, 16>;
+
+    let u0 = bc6h_unquantize(q0);
+    let u1 = bc6h_unquantize(q1);
+
+    for (var i = 0u; i < 16u; i++) {
+        indices[i] = u32(bc6h_nearest(u0, u1, bits[i]).x);
+    }
+
+    // the anchor: texel 0's top bit is implied zero
+    if (indices[0] >= 8u) {
+        let swap = q0;
+
+        q0 = q1;
+        q1 = swap;
+
+        for (var i = 0u; i < 16u; i++) {
+            indices[i] = 15u - indices[i];
+        }
+    }
+
+    return bc6h_pack_mode11(vec3<u32>(q0), vec3<u32>(q1), indices);
+}
+`, [
+        chunk_bc6h_pack_mode11,
+    ]);

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

@@ -0,0 +1,10 @@
+/**
+ * One BC6H mode 11 block from its two ten-bit endpoints and sixteen indices, as four little-endian
+ * words — the layout `bc6h_write_block_mode11` states in JavaScript, bit by bit for the same reason
+ * the BC7 packer is.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc6h_pack_mode11: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc6h_pack_mode11.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc6h_pack_mode11.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc6h_pack_mode11.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qCAFU,SAAS,CA8ChB;0BArDuB,oCAAoC"}

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

@@ -0,0 +1,54 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * One BC6H mode 11 block from its two ten-bit endpoints and sixteen indices, as four little-endian
+ * words — the layout `bc6h_write_block_mode11` states in JavaScript, bit by bit for the same reason
+ * the BC7 packer is.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc6h_pack_mode11 = CodeChunk.from(
+    //language=WGSL
+    `
+fn bc6h_pack_mode11(first: vec3<u32>, second: vec3<u32>, indices: array<u32, 16>) -> vec4<u32> {
+    var values: array<u32, 23>;
+    var counts: array<u32, 23>;
+
+    // mode 11 is the five bits 00011, least significant first
+    values[0] = 3u;
+    counts[0] = 5u;
+
+    for (var channel = 0u; channel < 3u; channel++) {
+        values[1u + channel] = first[channel] & 1023u;
+        counts[1u + channel] = 10u;
+        values[4u + channel] = second[channel] & 1023u;
+        counts[4u + channel] = 10u;
+    }
+
+    for (var texel = 0u; texel < 16u; texel++) {
+        values[7u + texel] = indices[texel] & 15u;
+        counts[7u + texel] = select(4u, 3u, texel == 0u);
+    }
+
+    var words = array<u32, 4>(0u, 0u, 0u, 0u);
+
+    var bit = 0u;
+
+    for (var field = 0u; field < 23u; field++) {
+        let value = values[field];
+        let count = counts[field];
+
+        for (var k = 0u; k < count; k++) {
+            if (((value >> k) & 1u) != 0u) {
+                let at = bit + k;
+
+                words[at >> 5u] |= 1u << (at & 31u);
+            }
+        }
+
+        bit += count;
+    }
+
+    return vec4<u32>(words[0], words[1], words[2], words[3]);
+}
+`);

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

@@ -0,0 +1,36 @@
+/**
+ * Encode sixteen RGBA texels as one BC7 block in mode 6.
+ *
+ * **Mode 6 is BC1's line with everything turned up**: one subset, so one line through colour
+ * space, but in four dimensions with alpha, sixteen points on it instead of four, and the ends
+ * stored at seven bits plus a parity bit each — an eight-bit value whose low bit is shared by the
+ * endpoint's four channels. It is the mode `bc7enc`'s "mode 6 only" setting, DirectXTex's
+ * `BC7_QUICK`, and the mode the UASTC transcoder carries single-subset blocks into, and on its own
+ * it beats BC1 by a wide margin on everything but sharply partitioned blocks. The partitioned modes
+ * are a later quality step and a separate chunk, not a change to this one.
+ *
+ * The fit is {@link chunk_bc1_encode_block}'s in four dimensions:
+ *
+ * 1. The principal axis by power iteration on the 4x4 covariance, seeded with the box diagonal;
+ *    the extreme projections as the ends.
+ * 2. Two rounds of least squares with the sixteen decode weights shared across channels, each
+ *    texel assigned by its projection and the neighbouring weight checked by distance.
+ * 3. **Quantisation with every parity.** Each end's low bit is one of two values, so the pair has
+ *    four parity combinations; each is rounded to and scored against the decoder's own palette,
+ *    and the best is kept. Then one round of coordinate descent over the eight stored components,
+ *    stepping by two so the parity holds, keeping any step that lowers the block's error.
+ * 4. **The anchor.** Texel 0's index is stored a bit short, so its top bit must be zero: when it
+ *    is not, the ends are swapped and every index inverted, which is the same block the other way
+ *    up.
+ *
+ * Every score is against the palette the decoder builds — `(a (64 - w) + b w + 32) >> 6` on the
+ * eight-bit ends, with BC7's own four-bit weights, which are not evenly spaced — and alpha counts
+ * like any other channel: an opaque source's alpha is a constant the fit may land a level off
+ * where that buys colour, as the reference transcoder does (plan §9.12), because this encoder does
+ * not know what its consumer will do with alpha and is not the place to decide it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bc7_encode_block_mode6: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bc7_encode_block_mode6.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bc7_encode_block_mode6.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_bc7_encode_block_mode6.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,2CAFU,SAAS,CAoSZ;0BAtUmB,oCAAoC"}