gputex 0.3.0 → 0.3.1

package/README.md

@@ -33,10 +33,17 @@ bun add gputex
 | **BC7**      | 16 (8 bpp)        | Color / RGBA on desktop (`texture-compression-bc`)        |
 | **BC5**      | 16 (8 bpp)        | Normal maps — RG only (`texture-compression-bc`)          |
 | **ASTC 4x4** | 16 (8 bpp)        | Color / RGBA on mobile / iOS (`texture-compression-astc`) |
-| **BC1**      | 8 (4 bpp)         | Legacy (never auto-selected)                              |
+| **BC1**      | 8 (4 bpp)         | Opaque color at half BC7's size (opt-in)                  |
 
 Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed RGBA8 fallback otherwise.
 
+BC1 is never picked by default — it's half the memory of BC7 but visibly lower
+quality, a trade-off only the application can make. Opt in per-texture with
+`preferredFormat: 'bc1'`: on BC-capable devices the texture encodes as BC1;
+everywhere else (e.g. ASTC-only mobile) selection proceeds as normal. The
+preference is only honoured with `hint: 'color'`, since BC1 can't carry real
+alpha or a normal map.
+
 ## WebGL fallback
 
 WebGPU is the primary path. When it's unavailable (older Safari, Firefox without WebGPU, locked-down environments) `compressTexture()` automatically falls back to a **WebGL2** path that runs the same family of block encoders as fragment shaders — each 4×4 block is computed in one fragment, written to an `RGBA32UI` render target, and read back. The WebGPU fast paths have since been rewritten for speed (projection assignment, f16), so the two backends are no longer byte-identical, but they implement the same algorithms at the same quality level and the resulting `CompressedTexture` looks the same under either renderer.
@@ -204,13 +211,14 @@ const tex = buildCompressedTexture([bytes], TextureFormat.BC7_SRGB)
 
 ### `compressTexture` options
 
-| Option       | Type                 | Default   | Description                                             |
-| ------------ | -------------------- | --------- | ------------------------------------------------------- |
-| `hint`       | `TextureHint`        | `'color'` | `'color'`, `'colorWithAlpha'`, or `'normal'`            |
-| `colorSpace` | `'srgb' \| 'linear'` | `'srgb'`  | Use the sRGB or linear variant of the chosen format     |
-| `flipY`      | `boolean`            | `true`    | Flip vertically (matches Three.js convention)           |
-| `mipmaps`    | `boolean`            | `false`   | Generate full mip chain down to 1x1                     |
-| `device`     | `GPUDevice`          | —         | Reuse an existing WebGPU device instead of creating one |
+| Option            | Type                 | Default   | Description                                                                                      |
+| ----------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `hint`            | `TextureHint`        | `'color'` | `'color'`, `'colorWithAlpha'`, or `'normal'`                                                     |
+| `preferredFormat` | `'bc1'`              | —         | Prefer BC1 (half of BC7's size) when supported; normal selection otherwise. `hint: 'color'` only |
+| `colorSpace`      | `'srgb' \| 'linear'` | `'srgb'`  | Use the sRGB or linear variant of the chosen format                                              |
+| `flipY`           | `boolean`            | `true`    | Flip vertically (matches Three.js convention)                                                    |
+| `mipmaps`         | `boolean`            | `false`   | Generate full mip chain down to 1x1                                                              |
+| `device`          | `GPUDevice`          | —         | Reuse an existing WebGPU device instead of creating one                                          |
 
 ## Benchmarks
 

package/dist/index.d.ts

@@ -377,9 +377,19 @@ declare function detectWebGLCapabilities(gl: ExtensionProvider): WebGLCapabiliti
  *   • 'normal'         — tangent-space normal map (R=x, G=y, z reconstructed).
  */
 type TextureHint = 'color' | 'colorWithAlpha' | 'normal';
+/**
+ * Optional format preference — a wish, not a demand. Applied when the
+ * device supports the format and the hint is compatible; otherwise
+ * selection proceeds normally (BC7 → ASTC → null). Currently only
+ * 'bc1': half the memory of BC7 (0.5 vs 1 byte/pixel) for opaque
+ * colour, at visibly lower quality on smooth content.
+ */
+type PreferredFormat = 'bc1';
 interface SelectFormatOptions {
     /** Pick the sRGB variant when the format has one. Default 'srgb'. */
     colorSpace?: 'srgb' | 'linear';
+    /** Prefer a specific format when supported. See `PreferredFormat`. */
+    preferredFormat?: PreferredFormat;
 }
 interface FormatSelection {
     /** null = no compressed path on this adapter; caller should fall back. */
@@ -430,4 +440,4 @@ declare function generateMipChain(level0: MipLevel): MipLevel[];
  */
 declare function padToBlockMultiple(level: MipLevel): MipLevel;
 
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, type MipLevel, type RawPixelSource, type SelectFormatOptions, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat };
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, type MipLevel, type PreferredFormat, type RawPixelSource, type SelectFormatOptions, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat };

package/dist/index.js

@@ -631,7 +631,171 @@ var BC5Encoder = class extends Encoder {
 var bc7_default = "// BC7 (BPTC) mode 6 compute shader encoder.\n//\n// One invocation per 4\xD74 block. Emits 16 bytes = 4 u32s into the storage\n// buffer at `dst[block_index * 4 .. + 3]`.\n//\n// QUALITY LEVELS (pipeline-overridable constant `QUALITY_HIGH`)\n//   fast (0, default): O(N) bounding-box seed \u2192 one fused pass that projects\n//     each pixel onto the endpoint line (the 16 palette entries are colinear,\n//     so the nearest index is the rounded projection \u2014 no palette build, no\n//     16-entry search) while accumulating the least-squares refit sums, then\n//     a reprojection against the quantised refit endpoints for the final\n//     indices, packed on the fly into two nibble words.\n//   high (1): farthest-pair seed, exhaustive p-bit search over all four\n//     (p0,p1) \u2208 {0,1}\xB2 combos, full 16-entry nearest search, one LSQ refit \u2014\n//     matches bc7_ref.ts up to FP tie-breaks.\n//\n// The fast/high branch is selected at pipeline-compile time, so the driver\n// eliminates the unused code entirely.\n//\n// MODE 6 LAYOUT (LSB-first, bit 0 = byte 0's bit 0)\n//   bits 0..6    mode field      (0b0000001 \u2014 only bit 6 is 1)\n//   bits 7..13   R0 (7-bit)   bits 14..20 R1   bits 21..27 G0   bits 28..34 G1\n//   bits 35..41  B0   bits 42..48 B1   bits 49..55 A0   bits 56..62 A1\n//   bit  63      P0   bit 64 P1\n//   bits 65..67  pixel 0 index (3 bits; anchor, MSB implicit 0)\n//   bits 68..71  pixel 1 index (4 bits) ... bits 124..127 pixel 15 index\n//\n// Effective 8-bit endpoint channel = (7_bit_value << 1) | p_bit.\n// Palette[i] = ((64 \u2212 W4[i]) \xD7 e0_8 + W4[i] \xD7 e1_8 + 32) >> 6, integer.\n//\n// The block is assembled with straight-line constant shifts (see the layout\n// summary in bc7_fast_f16.wgsl) \u2014 a generic write_bits() helper's dynamic\n// word indexing keeps the output array out of registers.\n\n// 0 = fast (default), 1 = exhaustive/high-quality. Set via pipeline constants.\noverride QUALITY_HIGH: u32 = 0u;\n\nstruct Params {\n  blocks_x: u32,\n  blocks_y: u32,\n  width:    u32,\n  height:   u32,\n};\n\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\n\n// Mode 6 interpolation weights (\xD7 1/64), fixed by the spec (`W4` in bc7_ref.ts).\nfn w4(i: u32) -> u32 {\n  switch i {\n    case 0u:  { return  0u; }\n    case 1u:  { return  4u; }\n    case 2u:  { return  9u; }\n    case 3u:  { return 13u; }\n    case 4u:  { return 17u; }\n    case 5u:  { return 21u; }\n    case 6u:  { return 26u; }\n    case 7u:  { return 30u; }\n    case 8u:  { return 34u; }\n    case 9u:  { return 38u; }\n    case 10u: { return 43u; }\n    case 11u: { return 47u; }\n    case 12u: { return 51u; }\n    case 13u: { return 55u; }\n    case 14u: { return 60u; }\n    default:  { return 64u; }   // case 15u\n  }\n}\n\nfn interp4(e0: vec4<i32>, e1: vec4<i32>, w: i32) -> vec4<i32> {\n  return ((64 - w) * e0 + w * e1 + vec4<i32>(32)) >> vec4<u32>(6u);\n}\n\nfn to8(v: vec4<f32>) -> vec4<i32> {\n  return vec4<i32>(clamp(floor(v * 255.0 + 0.5), vec4<f32>(0.0), vec4<f32>(255.0)));\n}\n\nfn dist2(a: vec4<i32>, b: vec4<i32>) -> i32 {\n  let d = a - b;\n  let e = d * d;\n  return e.x + e.y + e.z + e.w;\n}\n\n// Quantize an 8-bit ideal endpoint to (7-bit value, reconstructed 8-bit) under\n// a fixed p-bit, all four channels at once. q7 = round((ideal8 \u2212 p)/2); used by\n// both paths.\nstruct QuantPair { seven: vec4<i32>, eight: vec4<i32> };\nfn quantize_endpoint(ideal8: vec4<i32>, p: u32) -> QuantPair {\n  let q = vec4<i32>(clamp(\n    floor((vec4<f32>(ideal8) - f32(p)) / 2.0 + 0.5),\n    vec4<f32>(0.0), vec4<f32>(127.0),\n  ));\n  let eff = (q << vec4<u32>(1u)) | vec4<i32>(i32(p));\n  return QuantPair(q, eff);\n}\n\n// ============================ FAST PATH ================================ //\n\n// Endpoint with its chosen p-bit, picked by minimum quantisation error.\nstruct Ep { seven: vec4<i32>, eight: vec4<i32>, p: u32 };\nfn pick_ep(ideal: vec4<i32>) -> Ep {\n  let a = quantize_endpoint(ideal, 0u);\n  let b = quantize_endpoint(ideal, 1u);\n  if (dist2(b.eight, ideal) < dist2(a.eight, ideal)) { return Ep(b.seven, b.eight, 1u); }\n  return Ep(a.seven, a.eight, 0u);\n}\n\n// One pass over the block: project every pixel onto the e0\u2192e1 line and\n// accumulate the least-squares normal-equation sums; solve for the refit\n// endpoints (in 8-bit space). Indices are not produced here \u2014 the caller\n// reprojects against the quantised refit endpoints anyway.\nstruct Fit { e0: vec4<i32>, e1: vec4<i32>, valid: bool };\nfn proj_fit(pixels: ptr<function, array<vec4<i32>, 16>>, e0: vec4<i32>, e1: vec4<i32>) -> Fit {\n  var out: Fit;\n  out.valid = false;\n  let dir = vec4<f32>(e1 - e0);\n  let dd = dot(dir, dir);\n  if (dd == 0.0) { return out; }\n  let e0f = vec4<f32>(e0);\n  let inv = 15.0 / dd;\n  var sAA: f32 = 0.0; var sBB: f32 = 0.0; var sAB: f32 = 0.0;\n  var sAV: vec4<f32> = vec4<f32>(0.0); var sBV: vec4<f32> = vec4<f32>(0.0);\n  var s_min = 15.0; var s_max = 0.0;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let v = vec4<f32>((*pixels)[k]);\n    let s = clamp(floor(dot(v - e0f, dir) * inv + 0.5), 0.0, 15.0);\n    s_min = min(s_min, s); s_max = max(s_max, s);\n    let b = s * (1.0 / 15.0); let a = 1.0 - b;\n    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;\n    sAV = sAV + a * v; sBV = sBV + b * v;\n  }\n  // Rank-1 guard: if every pixel projects to ONE level the system is\n  // singular \u2014 det and the numerators are pure float rounding noise and the\n  // solve returns garbage endpoints. With \u22652 levels det \u2265 15/225 \u2248 0.067.\n  if (s_min == s_max) { return out; }\n  let det = sAA * sBB - sAB * sAB;\n  if (abs(det) < 1e-3) { return out; }\n  out.e0 = vec4<i32>(clamp(round((sBB * sAV - sAB * sBV) / det), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.e1 = vec4<i32>(clamp(round((sAA * sBV - sAB * sAV) / det), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.valid = true;\n  return out;\n}\n\n// ============================ HIGH PATH ================================ //\n\nstruct Pair { a: vec4<i32>, b: vec4<i32> };\nfn farthest_pair(pixels: ptr<function, array<vec4<i32>, 16>>) -> Pair {\n  var best_d: i32 = 0;\n  var pa = (*pixels)[0];\n  var pb = (*pixels)[1];\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let xi = (*pixels)[i];\n    for (var j: u32 = i + 1u; j < 16u; j = j + 1u) {\n      let d = dist2(xi, (*pixels)[j]);\n      if (d > best_d) { best_d = d; pa = xi; pb = (*pixels)[j]; }\n    }\n  }\n  return Pair(pa, pb);\n}\n\nfn build_palette_6(e0: vec4<i32>, e1: vec4<i32>, pal: ptr<function, array<vec4<i32>, 16>>) {\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    (*pal)[i] = interp4(e0, e1, i32(w4(i)));\n  }\n}\n\nfn assign_all(\n  pixels:  ptr<function, array<vec4<i32>, 16>>,\n  pal:     ptr<function, array<vec4<i32>, 16>>,\n  out_idx: ptr<function, array<u32, 16>>,\n) -> i32 {\n  var err: i32 = 0;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let px = (*pixels)[k];\n    var best_i: u32 = 0u;\n    var best_d: i32 = 2147483647;\n    for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n      let d = dist2(px, (*pal)[i]);\n      if (d < best_d) { best_d = d; best_i = i; }\n    }\n    (*out_idx)[k] = best_i;\n    err = err + best_d;\n  }\n  return err;\n}\n\nstruct BestMode6 {\n  e0_7: vec4<i32>, e1_7: vec4<i32>,\n  p0: u32,         p1: u32,\n  indices: array<u32, 16>,\n  err: i32,\n};\n\n// Exhaustive p-bit search (high path); commits to `*best` only on improvement.\nfn try_pbit_combos(\n  pixels: ptr<function, array<vec4<i32>, 16>>,\n  ideal0: vec4<i32>,\n  ideal1: vec4<i32>,\n  best:   ptr<function, BestMode6>,\n) {\n  var local_best = (*best).err;\n  var pal: array<vec4<i32>, 16>;\n  var tmp: array<u32, 16>;\n  for (var p0: u32 = 0u; p0 < 2u; p0 = p0 + 1u) {\n    let q0 = quantize_endpoint(ideal0, p0);\n    for (var p1: u32 = 0u; p1 < 2u; p1 = p1 + 1u) {\n      let q1 = quantize_endpoint(ideal1, p1);\n      build_palette_6(q0.eight, q1.eight, &pal);\n      let err = assign_all(pixels, &pal, &tmp);\n      if (err < local_best) {\n        local_best = err;\n        (*best).e0_7 = q0.seven;\n        (*best).e1_7 = q1.seven;\n        (*best).p0 = p0;\n        (*best).p1 = p1;\n        (*best).indices = tmp;\n        (*best).err = err;\n      }\n    }\n  }\n}\n\n// Exact-weight LSQ refit (high path); matches bc7_ref.ts `refitEndpointsMode6`.\nstruct RefitResult { e0: vec4<i32>, e1: vec4<i32>, valid: bool };\nfn refit_endpoints(\n  pixels: ptr<function, array<vec4<i32>, 16>>,\n  indices: ptr<function, array<u32, 16>>,\n) -> RefitResult {\n  var sAA: f32 = 0.0;\n  var sBB: f32 = 0.0;\n  var sAB: f32 = 0.0;\n  var sAV: vec4<f32> = vec4<f32>(0.0);\n  var sBV: vec4<f32> = vec4<f32>(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let i = (*indices)[k];\n    let a = f32(64u - w4(i)) / 64.0;\n    let b = f32(w4(i)) / 64.0;\n    let v = vec4<f32>((*pixels)[k]);\n    sAA = sAA + a * a;\n    sBB = sBB + b * b;\n    sAB = sAB + a * b;\n    sAV = sAV + a * v;\n    sBV = sBV + b * v;\n  }\n  let det = sAA * sBB - sAB * sAB;\n  var out: RefitResult;\n  if (abs(det) < 1e-9) {\n    out.valid = false;\n    return out;\n  }\n  let e0f = (sBB * sAV - sAB * sBV) / det;\n  let e1f = (sAA * sBV - sAB * sAV) / det;\n  out.e0 = vec4<i32>(clamp(round(e0f), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.e1 = vec4<i32>(clamp(round(e1f), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.valid = true;\n  return out;\n}\n\n// ------------------------------- Entry --------------------------------- //\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) {\n    return;\n  }\n\n  let bx = gid.x;\n  let by = gid.y;\n  let block_index = by * params.blocks_x + bx;\n\n  let base   = vec2<i32>(i32(bx) * 4, i32(by) * 4);\n  let max_xy = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  // Load 16 RGBA pixels (8-bit integer domain) and the per-channel bbox.\n  var pixels: array<vec4<i32>, 16>;\n  var lo = vec4<i32>(255);\n  var hi = vec4<i32>(0);\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let lx = i32(i & 3u);\n    let ly = i32(i >> 2u);\n    let p  = clamp(base + vec2<i32>(lx, ly), vec2<i32>(0, 0), max_xy);\n    let px = to8(textureLoad(src_tex, p, 0));\n    pixels[i] = px;\n    lo = min(lo, px);\n    hi = max(hi, px);\n  }\n\n  // Both branches produce: 7-bit endpoints + p-bits, and the 16 4-bit indices\n  // packed LSB-first into two nibble words (pixel k \u2192 bits 4k..4k+3).\n  var e0_7: vec4<i32>;\n  var e1_7: vec4<i32>;\n  var p0: u32;\n  var p1: u32;\n  var ilo: u32 = 0u;\n  var ihi: u32 = 0u;\n\n  if (QUALITY_HIGH != 0u) {\n    let fp = farthest_pair(&pixels);\n    var best: BestMode6;\n    best.err = 2147483647;\n    try_pbit_combos(&pixels, fp.a, fp.b, &best);\n    let refit = refit_endpoints(&pixels, &best.indices);\n    if (refit.valid) {\n      try_pbit_combos(&pixels, refit.e0, refit.e1, &best);\n    }\n    e0_7 = best.e0_7; e1_7 = best.e1_7; p0 = best.p0; p1 = best.p1;\n    for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n      ilo = ilo | (best.indices[k] << (k * 4u));\n    }\n    for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n      ihi = ihi | (best.indices[k] << ((k - 8u) * 4u));\n    }\n  } else {\n    // Seed the fused LSQ fit from the raw bbox, then quantise the refit\n    // endpoints and reproject for the final indices.\n    let r = proj_fit(&pixels, lo, hi);\n    var ep0: Ep;\n    var ep1: Ep;\n    if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }\n    else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }\n    let dir = vec4<f32>(ep1.eight - ep0.eight);\n    let dd = dot(dir, dir);\n    if (dd > 0.0) {\n      let e0f = vec4<f32>(ep0.eight);\n      let inv = 15.0 / dd;\n      for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n        let s = clamp(floor(dot(vec4<f32>(pixels[k]) - e0f, dir) * inv + 0.5), 0.0, 15.0);\n        ilo = ilo | (u32(s) << (k * 4u));\n      }\n      for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n        let s = clamp(floor(dot(vec4<f32>(pixels[k]) - e0f, dir) * inv + 0.5), 0.0, 15.0);\n        ihi = ihi | (u32(s) << ((k - 8u) * 4u));\n      }\n    }\n    e0_7 = ep0.seven; e1_7 = ep1.seven; p0 = ep0.p; p1 = ep1.p;\n  }\n\n  // Anchor rule \u2014 pixel 0's index MSB must be 0. Swapping endpoints reflects\n  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.\n  if ((ilo & 0x8u) != 0u) {\n    let t7 = e0_7; e0_7 = e1_7; e1_7 = t7;\n    let tp = p0;   p0   = p1;   p1   = tp;\n    ilo = ~ilo; ihi = ~ihi;\n  }\n\n  // Straight-line mode-6 packing (see layout at the top of the file).\n  let e0 = vec4<u32>(e0_7);\n  let e1 = vec4<u32>(e1_7);\n  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);\n  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (p0 << 31u);\n  let w2 = p1 | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);\n  let w3 = ihi;\n\n  let out = block_index * 4u;\n  dst[out + 0u] = w0;\n  dst[out + 1u] = w1;\n  dst[out + 2u] = w2;\n  dst[out + 3u] = w3;\n}\n";
 
 // src/bc7_fast_f16.wgsl
-var bc7_fast_f16_default = '// bc7 "fast" encoder \u2014 f16 variant (requires the shader-f16 feature).\n// Same algorithm family as the f32 fast path in bc7.wgsl (bbox seed \u2192\n// projection-based index assignment with a fused least-squares refit \u2192\n// reproject), tuned for throughput:\n//\n//   \u2022 All projection / refit math in f16 ([0,1] domain, so dot products stay\n//     well inside f16 range). ~2\xD7 ALU throughput on f16-capable GPUs.\n//   \u2022 The LSQ seed pass projects against the RAW bbox endpoints \u2014 quantising\n//     the seed first (pick_ep) costs two extra quantisation searches and\n//     doesn\'t measurably change where the refit lands.\n//   \u2022 Indices are packed into two u32 nibble words ON THE FLY during the\n//     final projection pass \u2014 no array<u32,16> private array. The BC7 anchor\n//     reflection (i \u2192 15\u2212i) is then just a bitwise NOT of both words.\n//   \u2022 The 128-bit block is assembled with straight-line constant shifts\n//     instead of a generic write_bits() helper (whose dynamic word indexing\n//     defeats register promotion of the output array).\n//\n// The host selects this module only when the device reports shader-f16,\n// falling back to bc7.wgsl otherwise. "high" never uses this.\n//\n// MODE 6 BIT LAYOUT (LSB-first): see bc7.wgsl. Summary:\n//   w0: mode(7 bits, 0x40) R0 R1 G0 G1[3:0]\n//   w1: G1[6:4] B0 B1 A0 A1 P0\n//   w2: P1, pixel0 index (3 bits), pixels 1..7 (4 bits each)\n//   w3: pixels 8..15 (4 bits each)\nenable f16;\nstruct Params { blocks_x: u32, blocks_y: u32, width: u32, height: u32, };\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\nalias h = f16;\nalias h4 = vec4<f16>;\n\n// Quantise an ideal endpoint (h4 in [0,1]) to 7-bit + p-bit, choosing the\n// p-bit with the lower quantisation error. `eight` is the decoded value the\n// hardware will interpolate with, back in [0,1].\nstruct Ep { seven: vec4<u32>, eight: h4, p: u32 };\nfn pick_ep(ideal01: h4) -> Ep {\n  let ideal = ideal01 * h(255.0);\n  let q0 = clamp(floor(ideal * h(0.5) + h(0.5)), h4(0.0), h4(127.0));        // p=0\n  let e0 = q0 * h(2.0);\n  let q1 = clamp(floor((ideal - h(1.0)) * h(0.5) + h(0.5)), h4(0.0), h4(127.0)); // p=1\n  let e1 = q1 * h(2.0) + h(1.0);\n  let d0 = e0 - ideal; let d1 = e1 - ideal;\n  if (dot(d1, d1) < dot(d0, d0)) { return Ep(vec4<u32>(q1), e1 * h(1.0 / 255.0), 1u); }\n  return Ep(vec4<u32>(q0), e0 * h(1.0 / 255.0), 0u);\n}\n\n// One pass over the block: project every pixel onto the e0\u2192e1 line and\n// accumulate the least-squares normal-equation sums; solve for the refit\n// endpoints. Indices are NOT produced here \u2014 the caller reprojects against\n// the quantised refit endpoints anyway.\nstruct Fit { e0: h4, e1: h4, valid: bool };\nfn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {\n  var out: Fit;\n  out.valid = false;\n  let dir = e1 - e0;\n  let dd = dot(dir, dir);\n  if (dd == h(0.0)) { return out; }\n  let inv = h(15.0) / dd;\n  var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);\n  var sAV = h4(0.0); var sBV = h4(0.0);\n  var s_min = h(15.0); var s_max = h(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let v = (*pix)[k];\n    let s = clamp(floor(dot(v - e0, dir) * inv + h(0.5)), h(0.0), h(15.0));\n    s_min = min(s_min, s); s_max = max(s_max, s);\n    let b = s * h(1.0 / 15.0); let a = h(1.0) - b;\n    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;\n    sAV = sAV + a * v; sBV = sBV + b * v;\n  }\n  // Rank-1 guard: if every pixel projects to ONE level the system is\n  // singular \u2014 det/numerators are pure f16 rounding noise and the solve\n  // returns garbage endpoints. With \u22652 distinct levels\n  // det = \u03A3_i<j (b_j \u2212 b_i)\xB2 \u2265 15/225 \u2248 0.067, so 0.02 is a safe floor.\n  if (s_min == s_max) { return out; }\n  let det = sAA * sBB - sAB * sAB;\n  if (abs(det) < h(0.02)) { return out; }\n  out.e0 = clamp((sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));\n  out.e1 = clamp((sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));\n  out.valid = true;\n  return out;\n}\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) { return; }\n  let bi = gid.y * params.blocks_x + gid.x;\n  let base = vec2<i32>(i32(gid.x) * 4, i32(gid.y) * 4);\n  let mx = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  var pix: array<h4, 16>;\n  var lo = h4(1.0);\n  var hi = h4(0.0);\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let p = clamp(base + vec2<i32>(i32(i & 3u), i32(i >> 2u)), vec2<i32>(0), mx);\n    let px = h4(textureLoad(src_tex, p, 0));\n    pix[i] = px; lo = min(lo, px); hi = max(hi, px);\n  }\n\n  // Seed fit from the raw bbox, then quantise the refit endpoints.\n  let r = proj_fit(&pix, lo, hi);\n  var ep0: Ep;\n  var ep1: Ep;\n  if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }\n  else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }\n\n  // Final projection against the decoded endpoints, packing the 4-bit indices\n  // into two nibble words as we go (pixel k \u2192 bits 4k..4k+3 of ilo/ihi).\n  var ilo: u32 = 0u;\n  var ihi: u32 = 0u;\n  let dir = ep1.eight - ep0.eight;\n  let dd = dot(dir, dir);\n  if (dd > h(0.0)) {\n    let inv = h(15.0) / dd;\n    for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));\n      ilo = ilo | (u32(s) << (k * 4u));\n    }\n    for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));\n      ihi = ihi | (u32(s) << ((k - 8u) * 4u));\n    }\n  }\n\n  // Anchor rule \u2014 pixel 0\'s index MSB must be 0. Swapping endpoints reflects\n  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.\n  if ((ilo & 0x8u) != 0u) {\n    let t = ep0; ep0 = ep1; ep1 = t;\n    ilo = ~ilo; ihi = ~ihi;\n  }\n\n  // Straight-line mode-6 packing (see layout above).\n  let e0 = ep0.seven;\n  let e1 = ep1.seven;\n  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);\n  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (ep0.p << 31u);\n  let w2 = ep1.p | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);\n  let w3 = ihi;\n\n  let o = bi * 4u;\n  dst[o] = w0; dst[o + 1u] = w1; dst[o + 2u] = w2; dst[o + 3u] = w3;\n}\n';
+var bc7_fast_f16_default = `// bc7 "fast" encoder \u2014 f16 variant (requires the shader-f16 feature).
+// Same algorithm family as the f32 fast path in bc7.wgsl (bbox seed \u2192
+// projection-based index assignment with a fused least-squares refit \u2192
+// reproject), tuned for throughput:
+//
+//   \u2022 All projection / refit math in f16 ([0,1] domain). ~2\xD7 ALU throughput
+//     on f16-capable GPUs. The projection direction is pre-scaled by 32:
+//     a shallow block (endpoints ~1/255 apart) has dd = dot(dir,dir) \u2248 1.5e-5,
+//     where 15/dd \u2248 10\u2076 overflows f16 (max 65504) to +inf and the products
+//     inside the projection dot are subnormal \u2014 the indices and the LSQ refit
+//     feeding on them turn to garbage (visible as banding on smooth
+//     gradients). Scaling dir by 32 multiplies the dots by 32 and dd by 1024;
+//     s = dot\xB7(32\xB715/dd\u2083\u2082) is the same quantity with every intermediate in
+//     f16's normal range (worst case inv = 480/0.0157 \u2248 3.0e4 < 65504).
+//   \u2022 The LSQ seed pass projects against the RAW bbox endpoints \u2014 quantising
+//     the seed first (pick_ep) costs two extra quantisation searches and
+//     doesn't measurably change where the refit lands.
+//   \u2022 Indices are packed into two u32 nibble words ON THE FLY during the
+//     final projection pass \u2014 no array<u32,16> private array. The BC7 anchor
+//     reflection (i \u2192 15\u2212i) is then just a bitwise NOT of both words.
+//   \u2022 The 128-bit block is assembled with straight-line constant shifts
+//     instead of a generic write_bits() helper (whose dynamic word indexing
+//     defeats register promotion of the output array).
+//
+// The host selects this module only when the device reports shader-f16,
+// falling back to bc7.wgsl otherwise. "high" never uses this.
+//
+// MODE 6 BIT LAYOUT (LSB-first): see bc7.wgsl. Summary:
+//   w0: mode(7 bits, 0x40) R0 R1 G0 G1[3:0]
+//   w1: G1[6:4] B0 B1 A0 A1 P0
+//   w2: P1, pixel0 index (3 bits), pixels 1..7 (4 bits each)
+//   w3: pixels 8..15 (4 bits each)
+enable f16;
+struct Params { blocks_x: u32, blocks_y: u32, width: u32, height: u32, };
+@group(0) @binding(0) var src_tex: texture_2d<f32>;
+@group(0) @binding(1) var<storage, read_write> dst: array<u32>;
+@group(0) @binding(2) var<uniform> params: Params;
+alias h = f16;
+alias h4 = vec4<f16>;
+
+// Quantise an ideal endpoint (h4 in [0,1]) to 7-bit + p-bit, choosing the
+// p-bit with the lower quantisation error. \`eight\` is the decoded value the
+// hardware will interpolate with, back in [0,1].
+struct Ep { seven: vec4<u32>, eight: h4, p: u32 };
+fn pick_ep(ideal01: h4) -> Ep {
+  let ideal = ideal01 * h(255.0);
+  let q0 = clamp(floor(ideal * h(0.5) + h(0.5)), h4(0.0), h4(127.0));        // p=0
+  let e0 = q0 * h(2.0);
+  let q1 = clamp(floor((ideal - h(1.0)) * h(0.5) + h(0.5)), h4(0.0), h4(127.0)); // p=1
+  let e1 = q1 * h(2.0) + h(1.0);
+  let d0 = e0 - ideal; let d1 = e1 - ideal;
+  if (dot(d1, d1) < dot(d0, d0)) { return Ep(vec4<u32>(q1), e1 * h(1.0 / 255.0), 1u); }
+  return Ep(vec4<u32>(q0), e0 * h(1.0 / 255.0), 0u);
+}
+
+// One pass over the block: project every pixel onto the e0\u2192e1 line and
+// accumulate the least-squares normal-equation sums; solve for the refit
+// endpoints. Indices are NOT produced here \u2014 the caller reprojects against
+// the quantised refit endpoints anyway.
+//
+// The value sums accumulate v \u2212 e0, not v: the basis is affine (a + b = 1),
+// so fitting the shifted data and adding e0 back is the same fit, but the
+// accumulators scale with the block's span instead of its absolute level \u2014
+// on a shallow dark block, f16 rounding of absolute sums (ulp \u2248 0.12 of an
+// 8-bit level per add) drifts the refit endpoints by \xB11 level.
+struct Fit { e0: h4, e1: h4, valid: bool };
+fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
+  var out: Fit;
+  out.valid = false;
+  // dir pre-scaled by 32 to keep dd and the projection dots in f16's normal
+  // range (see header). Spans below ~0.7 of an 8-bit step (dd\u2083\u2082 < 0.008,
+  // possible only for non-8-bit sources) are treated as flat \u2014 encoding them
+  // flat is under half a level of error, while running the math on them risks
+  // inv overflowing to +inf.
+  let dir = (e1 - e0) * h(32.0);
+  let dd = dot(dir, dir);
+  if (dd < h(0.008)) { return out; }
+  let inv = h(480.0) / dd; // 32\xB715/dd\u2083\u2082 \u2261 15/dd
+  var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);
+  var sAV = h4(0.0); var sBV = h4(0.0);
+  var s_min = h(15.0); var s_max = h(0.0);
+  for (var k: u32 = 0u; k < 16u; k = k + 1u) {
+    let vr = (*pix)[k] - e0;
+    let s = clamp(floor(dot(vr, dir) * inv + h(0.5)), h(0.0), h(15.0));
+    s_min = min(s_min, s); s_max = max(s_max, s);
+    let b = s * h(1.0 / 15.0); let a = h(1.0) - b;
+    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;
+    sAV = sAV + a * vr; sBV = sBV + b * vr;
+  }
+  // Rank-1 guard: if every pixel projects to ONE level the system is
+  // singular \u2014 det/numerators are pure f16 rounding noise and the solve
+  // returns garbage endpoints. With \u22652 distinct levels
+  // det = \u03A3_i<j (b_j \u2212 b_i)\xB2 \u2265 15/225 \u2248 0.067, so 0.02 is a safe floor.
+  if (s_min == s_max) { return out; }
+  let det = sAA * sBB - sAB * sAB;
+  if (abs(det) < h(0.02)) { return out; }
+  out.e0 = clamp(e0 + (sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
+  out.e1 = clamp(e0 + (sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
+  out.valid = true;
+  return out;
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn encode(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) { return; }
+  let bi = gid.y * params.blocks_x + gid.x;
+  let base = vec2<i32>(i32(gid.x) * 4, i32(gid.y) * 4);
+  let mx = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);
+
+  var pix: array<h4, 16>;
+  var lo = h4(1.0);
+  var hi = h4(0.0);
+  for (var i: u32 = 0u; i < 16u; i = i + 1u) {
+    let p = clamp(base + vec2<i32>(i32(i & 3u), i32(i >> 2u)), vec2<i32>(0), mx);
+    let px = h4(textureLoad(src_tex, p, 0));
+    pix[i] = px; lo = min(lo, px); hi = max(hi, px);
+  }
+
+  // Seed fit from the raw bbox, then quantise the refit endpoints.
+  let r = proj_fit(&pix, lo, hi);
+  var ep0: Ep;
+  var ep1: Ep;
+  if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }
+  else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }
+
+  // Final projection against the decoded endpoints, packing the 4-bit indices
+  // into two nibble words as we go (pixel k \u2192 bits 4k..4k+3 of ilo/ihi).
+  var ilo: u32 = 0u;
+  var ihi: u32 = 0u;
+  // Same \xD732 pre-scale as proj_fit; distinct quantised endpoints are \u22651/255
+  // apart, i.e. dd\u2083\u2082 \u2265 0.0157, so the flat-block threshold only catches
+  // truly identical endpoints.
+  let dir = (ep1.eight - ep0.eight) * h(32.0);
+  let dd = dot(dir, dir);
+  if (dd >= h(0.008)) {
+    let inv = h(480.0) / dd;
+    for (var k: u32 = 0u; k < 8u; k = k + 1u) {
+      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));
+      ilo = ilo | (u32(s) << (k * 4u));
+    }
+    for (var k: u32 = 8u; k < 16u; k = k + 1u) {
+      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));
+      ihi = ihi | (u32(s) << ((k - 8u) * 4u));
+    }
+  }
+
+  // Anchor rule \u2014 pixel 0's index MSB must be 0. Swapping endpoints reflects
+  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.
+  if ((ilo & 0x8u) != 0u) {
+    let t = ep0; ep0 = ep1; ep1 = t;
+    ilo = ~ilo; ihi = ~ihi;
+  }
+
+  // Straight-line mode-6 packing (see layout above).
+  let e0 = ep0.seven;
+  let e1 = ep1.seven;
+  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);
+  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (ep0.p << 31u);
+  let w2 = ep1.p | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);
+  let w3 = ihi;
+
+  let o = bi * 4u;
+  dst[o] = w0; dst[o + 1u] = w1; dst[o + 2u] = w2; dst[o + 3u] = w3;
+}
+`;
 
 // src/BC7Encoder.ts
 var BC7Encoder = class extends Encoder {
@@ -669,7 +833,13 @@ var astc4x4_fast_f16_default = `// astc4x4 "fast" encoder \u2014 f16 variant (re
 // projection weight assignment with a fused least-squares refit \u2192
 // reproject), tuned for throughput:
 //
-//   \u2022 All projection / refit math in f16 ([0,1] domain).
+//   \u2022 All projection / refit math in f16 ([0,1] domain). The projection
+//     direction is pre-scaled by 32 \u2014 a shallow block (endpoints ~1/255
+//     apart) has dd \u2248 1.5e-5, where 3/dd \u2248 2e5 overflows f16 (max 65504) to
+//     +inf and the projection dots go subnormal, turning weights and the LSQ
+//     refit to garbage (banding on smooth gradients). Scaling dir by 32 puts
+//     every intermediate in f16's normal range; s = dot\xB7(32\xB73/dd\u2083\u2082) is the
+//     same quantity (worst case inv = 96/0.0157 \u2248 6.1e3).
 //   \u2022 The seed pass only accumulates the LSQ sums (no weight output) \u2014 the
 //     final weights come from reprojecting against the refit endpoints.
 //   \u2022 Endpoint ordering (the blue-contraction rule: sum(e0.rgb) must not
@@ -696,20 +866,27 @@ struct Fit { e0: h4, e1: h4, valid: bool };
 fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
   var out: Fit;
   out.valid = false;
-  let dir = e1 - e0;
+  // dir pre-scaled by 32 to keep dd and the projection dots in f16's normal
+  // range (see header). Spans below ~0.7 of an 8-bit step (dd\u2083\u2082 < 0.008,
+  // possible only for non-8-bit sources) are treated as flat.
+  let dir = (e1 - e0) * h(32.0);
   let dd = dot(dir, dir);
-  if (dd == h(0.0)) { return out; }
-  let inv = h(3.0) / dd;
+  if (dd < h(0.008)) { return out; }
+  let inv = h(96.0) / dd; // 32\xB73/dd\u2083\u2082 \u2261 3/dd
   var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);
   var sAV = h4(0.0); var sBV = h4(0.0);
   var s_min = h(3.0); var s_max = h(0.0);
+  // Value sums accumulate v \u2212 e0 (basis is affine, a + b = 1, so the fit
+  // commutes with the shift): accumulators scale with the block span, keeping
+  // f16 rounding a fraction of the span instead of \xB11 level at high absolute
+  // values.
   for (var k: u32 = 0u; k < 16u; k = k + 1u) {
-    let v = (*pix)[k];
-    let s = clamp(floor(dot(v - e0, dir) * inv + h(0.5)), h(0.0), h(3.0));
+    let vr = (*pix)[k] - e0;
+    let s = clamp(floor(dot(vr, dir) * inv + h(0.5)), h(0.0), h(3.0));
     s_min = min(s_min, s); s_max = max(s_max, s);
     let b = s * h(1.0 / 3.0); let a = h(1.0) - b;
     sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;
-    sAV = sAV + a * v; sBV = sBV + b * v;
+    sAV = sAV + a * vr; sBV = sBV + b * vr;
   }
   // Rank-1 guard: if every pixel projects to ONE level the system is
   // singular \u2014 det/numerators are pure f16 rounding noise and the solve
@@ -718,8 +895,8 @@ fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
   if (s_min == s_max) { return out; }
   let det = sAA * sBB - sAB * sAB;
   if (abs(det) < h(0.5)) { return out; }
-  out.e0 = clamp((sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
-  out.e1 = clamp((sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
+  out.e0 = clamp(e0 + (sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
+  out.e1 = clamp(e0 + (sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
   out.valid = true;
   return out;
 }
@@ -762,10 +939,12 @@ fn encode(@builtin(global_invocation_id) gid: vec3<u32>) {
   // Weight pass, packing on the fly: weight k's lsb at bit 31\u22122k of the last
   // word, msb at bit 30\u22122k.
   var w3: u32 = 0u;
-  let dir = d1 - d0;
+  // Same \xD732 pre-scale as proj_fit; distinct 8-bit endpoints are \u22651/255
+  // apart (dd\u2083\u2082 \u2265 0.0157), so the threshold only catches identical ones.
+  let dir = (d1 - d0) * h(32.0);
   let dd = dot(dir, dir);
-  if (dd > h(0.0)) {
-    let inv = h(3.0) / dd;
+  if (dd >= h(0.008)) {
+    let inv = h(96.0) / dd;
     for (var k: u32 = 0u; k < 16u; k = k + 1u) {
       let s = u32(clamp(floor(dot(pix[k] - d0, dir) * inv + h(0.5)), h(0.0), h(3.0)));
       w3 = w3 | ((s & 1u) << (31u - 2u * k)) | (((s >> 1u) & 1u) << (30u - 2u * k));
@@ -1114,13 +1293,26 @@ function detectWebGLCapabilities(gl) {
 // src/webgl/selectWebGLFormat.ts
 var NONE = { format: null, encoderClass: null, astcNormalRemap: false };
 function selectWebGLFormat(caps, hint, options = {}) {
-  const { colorSpace = "srgb" } = options;
+  const { colorSpace = "srgb", preferredFormat } = options;
   const srgb = colorSpace === "srgb";
   const astc = (astcNormalRemap) => ({
     format: srgb ? TextureFormat.ASTC_4x4_SRGB : TextureFormat.ASTC_4x4,
     encoderClass: ASTC4x4WebGLEncoder,
     astcNormalRemap
   });
+  if (preferredFormat === "bc1") {
+    if (hint !== "color") {
+      console.warn(
+        `[gputex] preferredFormat 'bc1' ignored for hint '${hint}' \u2014 BC1 has no real alpha channel and is unsuitable for normal maps.`
+      );
+    } else if (srgb ? caps.s3tcSrgb : caps.s3tc) {
+      return {
+        format: srgb ? TextureFormat.BC1_SRGB : TextureFormat.BC1,
+        encoderClass: BC1WebGLEncoder,
+        astcNormalRemap: false
+      };
+    }
+  }
   if (hint === "normal") {
     if (caps.rgtc) return { format: TextureFormat.BC5, encoderClass: BC5WebGLEncoder, astcNormalRemap: false };
     if (caps.astc) return astc(true);
@@ -1147,9 +1339,22 @@ function selectWebGLFormat(caps, hint, options = {}) {
 
 // src/selectFormat.ts
 function selectFormat(adapter, hint, options = {}) {
-  const { colorSpace = "srgb" } = options;
+  const { colorSpace = "srgb", preferredFormat } = options;
   const srgb = colorSpace === "srgb";
   const caps = detectCapabilities(adapter);
+  if (preferredFormat === "bc1") {
+    if (hint !== "color") {
+      console.warn(
+        `[gputex] preferredFormat 'bc1' ignored for hint '${hint}' \u2014 BC1 has no real alpha channel and is unsuitable for normal maps.`
+      );
+    } else if (caps.bc) {
+      return {
+        format: srgb ? TextureFormat.BC1_SRGB : TextureFormat.BC1,
+        encoderClass: BC1Encoder,
+        astcNormalRemap: false
+      };
+    }
+  }
   if (caps.bc) {
     if (hint === "normal") {
       return { format: TextureFormat.BC5, encoderClass: BC5Encoder, astcNormalRemap: false };

package/dist/three.d.ts

@@ -1,4 +1,4 @@
-import { TextureHint, EncodeQuality, TextureFormat, Encoder, EncoderImageSource } from './index.js';
+import { TextureHint, PreferredFormat, EncodeQuality, TextureFormat, Encoder, EncoderImageSource } from './index.js';
 export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, Capabilities, EncodeBytesResult, EncodeCallOptions, EncoderConstructor, EncoderOptions, ExtensionProvider, FeatureProvider, FormatSelection, FormatVariant, MipLevel, RawPixelSource, SelectFormatOptions, WebGLBlockEncoder, WebGLCapabilities, WebGLEncodeBytesResult, WebGLEncoderConstructor, WebGLEncoderImageSource, WebGLEncoderOptions, WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat } from './index.js';
 import { Texture, CompressedTexture, Loader, CompressedPixelFormat } from 'three';
 
@@ -11,6 +11,14 @@ type CompressTextureSource = string | Blob | File | ImageBitmap | HTMLImageEleme
 interface CompressOptions {
     /** How the texture will be used. Drives format selection. Default 'color'. */
     hint?: TextureHint;
+    /**
+     * Prefer a specific format over the default choice when the device
+     * supports it; falls back to the normal selection (BC7 → ASTC → RGBA8)
+     * when it doesn't. Currently only 'bc1': half the memory of BC7 for
+     * opaque colour textures, at lower quality. Only honoured with
+     * `hint: 'color'` — BC1 can't carry real alpha or normal maps.
+     */
+    preferredFormat?: PreferredFormat;
     /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
     colorSpace?: 'srgb' | 'linear';
     /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
@@ -63,6 +71,12 @@ declare function compressTexture(source: CompressTextureSource, options?: Compre
 declare class GputexLoader extends Loader<Texture> {
     /** Format-selection hint. Default 'color'. */
     hint: TextureHint;
+    /**
+     * Prefer a specific format (currently only 'bc1') when the device
+     * supports it; normal selection otherwise. See
+     * `CompressOptions.preferredFormat`.
+     */
+    preferredFormat?: PreferredFormat;
     /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
     colorSpace: 'srgb' | 'linear';
     /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
@@ -138,4 +152,4 @@ interface EncodeToTextureOptions {
  */
 declare function encodeToTexture(encoder: Encoder, source: EncoderImageSource, { colorSpace, quality, flipY }?: EncodeToTextureOptions): Promise<EncodeResult>;
 
-export { type CompressOptions, type CompressResult, type CompressTextureSource, EncodeQuality, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, GputexLoader, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };
+export { type CompressOptions, type CompressResult, type CompressTextureSource, EncodeQuality, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, GputexLoader, PreferredFormat, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };

package/dist/three.js

@@ -635,7 +635,171 @@ var BC5Encoder = class extends Encoder {
 var bc7_default = "// BC7 (BPTC) mode 6 compute shader encoder.\n//\n// One invocation per 4\xD74 block. Emits 16 bytes = 4 u32s into the storage\n// buffer at `dst[block_index * 4 .. + 3]`.\n//\n// QUALITY LEVELS (pipeline-overridable constant `QUALITY_HIGH`)\n//   fast (0, default): O(N) bounding-box seed \u2192 one fused pass that projects\n//     each pixel onto the endpoint line (the 16 palette entries are colinear,\n//     so the nearest index is the rounded projection \u2014 no palette build, no\n//     16-entry search) while accumulating the least-squares refit sums, then\n//     a reprojection against the quantised refit endpoints for the final\n//     indices, packed on the fly into two nibble words.\n//   high (1): farthest-pair seed, exhaustive p-bit search over all four\n//     (p0,p1) \u2208 {0,1}\xB2 combos, full 16-entry nearest search, one LSQ refit \u2014\n//     matches bc7_ref.ts up to FP tie-breaks.\n//\n// The fast/high branch is selected at pipeline-compile time, so the driver\n// eliminates the unused code entirely.\n//\n// MODE 6 LAYOUT (LSB-first, bit 0 = byte 0's bit 0)\n//   bits 0..6    mode field      (0b0000001 \u2014 only bit 6 is 1)\n//   bits 7..13   R0 (7-bit)   bits 14..20 R1   bits 21..27 G0   bits 28..34 G1\n//   bits 35..41  B0   bits 42..48 B1   bits 49..55 A0   bits 56..62 A1\n//   bit  63      P0   bit 64 P1\n//   bits 65..67  pixel 0 index (3 bits; anchor, MSB implicit 0)\n//   bits 68..71  pixel 1 index (4 bits) ... bits 124..127 pixel 15 index\n//\n// Effective 8-bit endpoint channel = (7_bit_value << 1) | p_bit.\n// Palette[i] = ((64 \u2212 W4[i]) \xD7 e0_8 + W4[i] \xD7 e1_8 + 32) >> 6, integer.\n//\n// The block is assembled with straight-line constant shifts (see the layout\n// summary in bc7_fast_f16.wgsl) \u2014 a generic write_bits() helper's dynamic\n// word indexing keeps the output array out of registers.\n\n// 0 = fast (default), 1 = exhaustive/high-quality. Set via pipeline constants.\noverride QUALITY_HIGH: u32 = 0u;\n\nstruct Params {\n  blocks_x: u32,\n  blocks_y: u32,\n  width:    u32,\n  height:   u32,\n};\n\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\n\n// Mode 6 interpolation weights (\xD7 1/64), fixed by the spec (`W4` in bc7_ref.ts).\nfn w4(i: u32) -> u32 {\n  switch i {\n    case 0u:  { return  0u; }\n    case 1u:  { return  4u; }\n    case 2u:  { return  9u; }\n    case 3u:  { return 13u; }\n    case 4u:  { return 17u; }\n    case 5u:  { return 21u; }\n    case 6u:  { return 26u; }\n    case 7u:  { return 30u; }\n    case 8u:  { return 34u; }\n    case 9u:  { return 38u; }\n    case 10u: { return 43u; }\n    case 11u: { return 47u; }\n    case 12u: { return 51u; }\n    case 13u: { return 55u; }\n    case 14u: { return 60u; }\n    default:  { return 64u; }   // case 15u\n  }\n}\n\nfn interp4(e0: vec4<i32>, e1: vec4<i32>, w: i32) -> vec4<i32> {\n  return ((64 - w) * e0 + w * e1 + vec4<i32>(32)) >> vec4<u32>(6u);\n}\n\nfn to8(v: vec4<f32>) -> vec4<i32> {\n  return vec4<i32>(clamp(floor(v * 255.0 + 0.5), vec4<f32>(0.0), vec4<f32>(255.0)));\n}\n\nfn dist2(a: vec4<i32>, b: vec4<i32>) -> i32 {\n  let d = a - b;\n  let e = d * d;\n  return e.x + e.y + e.z + e.w;\n}\n\n// Quantize an 8-bit ideal endpoint to (7-bit value, reconstructed 8-bit) under\n// a fixed p-bit, all four channels at once. q7 = round((ideal8 \u2212 p)/2); used by\n// both paths.\nstruct QuantPair { seven: vec4<i32>, eight: vec4<i32> };\nfn quantize_endpoint(ideal8: vec4<i32>, p: u32) -> QuantPair {\n  let q = vec4<i32>(clamp(\n    floor((vec4<f32>(ideal8) - f32(p)) / 2.0 + 0.5),\n    vec4<f32>(0.0), vec4<f32>(127.0),\n  ));\n  let eff = (q << vec4<u32>(1u)) | vec4<i32>(i32(p));\n  return QuantPair(q, eff);\n}\n\n// ============================ FAST PATH ================================ //\n\n// Endpoint with its chosen p-bit, picked by minimum quantisation error.\nstruct Ep { seven: vec4<i32>, eight: vec4<i32>, p: u32 };\nfn pick_ep(ideal: vec4<i32>) -> Ep {\n  let a = quantize_endpoint(ideal, 0u);\n  let b = quantize_endpoint(ideal, 1u);\n  if (dist2(b.eight, ideal) < dist2(a.eight, ideal)) { return Ep(b.seven, b.eight, 1u); }\n  return Ep(a.seven, a.eight, 0u);\n}\n\n// One pass over the block: project every pixel onto the e0\u2192e1 line and\n// accumulate the least-squares normal-equation sums; solve for the refit\n// endpoints (in 8-bit space). Indices are not produced here \u2014 the caller\n// reprojects against the quantised refit endpoints anyway.\nstruct Fit { e0: vec4<i32>, e1: vec4<i32>, valid: bool };\nfn proj_fit(pixels: ptr<function, array<vec4<i32>, 16>>, e0: vec4<i32>, e1: vec4<i32>) -> Fit {\n  var out: Fit;\n  out.valid = false;\n  let dir = vec4<f32>(e1 - e0);\n  let dd = dot(dir, dir);\n  if (dd == 0.0) { return out; }\n  let e0f = vec4<f32>(e0);\n  let inv = 15.0 / dd;\n  var sAA: f32 = 0.0; var sBB: f32 = 0.0; var sAB: f32 = 0.0;\n  var sAV: vec4<f32> = vec4<f32>(0.0); var sBV: vec4<f32> = vec4<f32>(0.0);\n  var s_min = 15.0; var s_max = 0.0;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let v = vec4<f32>((*pixels)[k]);\n    let s = clamp(floor(dot(v - e0f, dir) * inv + 0.5), 0.0, 15.0);\n    s_min = min(s_min, s); s_max = max(s_max, s);\n    let b = s * (1.0 / 15.0); let a = 1.0 - b;\n    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;\n    sAV = sAV + a * v; sBV = sBV + b * v;\n  }\n  // Rank-1 guard: if every pixel projects to ONE level the system is\n  // singular \u2014 det and the numerators are pure float rounding noise and the\n  // solve returns garbage endpoints. With \u22652 levels det \u2265 15/225 \u2248 0.067.\n  if (s_min == s_max) { return out; }\n  let det = sAA * sBB - sAB * sAB;\n  if (abs(det) < 1e-3) { return out; }\n  out.e0 = vec4<i32>(clamp(round((sBB * sAV - sAB * sBV) / det), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.e1 = vec4<i32>(clamp(round((sAA * sBV - sAB * sAV) / det), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.valid = true;\n  return out;\n}\n\n// ============================ HIGH PATH ================================ //\n\nstruct Pair { a: vec4<i32>, b: vec4<i32> };\nfn farthest_pair(pixels: ptr<function, array<vec4<i32>, 16>>) -> Pair {\n  var best_d: i32 = 0;\n  var pa = (*pixels)[0];\n  var pb = (*pixels)[1];\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let xi = (*pixels)[i];\n    for (var j: u32 = i + 1u; j < 16u; j = j + 1u) {\n      let d = dist2(xi, (*pixels)[j]);\n      if (d > best_d) { best_d = d; pa = xi; pb = (*pixels)[j]; }\n    }\n  }\n  return Pair(pa, pb);\n}\n\nfn build_palette_6(e0: vec4<i32>, e1: vec4<i32>, pal: ptr<function, array<vec4<i32>, 16>>) {\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    (*pal)[i] = interp4(e0, e1, i32(w4(i)));\n  }\n}\n\nfn assign_all(\n  pixels:  ptr<function, array<vec4<i32>, 16>>,\n  pal:     ptr<function, array<vec4<i32>, 16>>,\n  out_idx: ptr<function, array<u32, 16>>,\n) -> i32 {\n  var err: i32 = 0;\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let px = (*pixels)[k];\n    var best_i: u32 = 0u;\n    var best_d: i32 = 2147483647;\n    for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n      let d = dist2(px, (*pal)[i]);\n      if (d < best_d) { best_d = d; best_i = i; }\n    }\n    (*out_idx)[k] = best_i;\n    err = err + best_d;\n  }\n  return err;\n}\n\nstruct BestMode6 {\n  e0_7: vec4<i32>, e1_7: vec4<i32>,\n  p0: u32,         p1: u32,\n  indices: array<u32, 16>,\n  err: i32,\n};\n\n// Exhaustive p-bit search (high path); commits to `*best` only on improvement.\nfn try_pbit_combos(\n  pixels: ptr<function, array<vec4<i32>, 16>>,\n  ideal0: vec4<i32>,\n  ideal1: vec4<i32>,\n  best:   ptr<function, BestMode6>,\n) {\n  var local_best = (*best).err;\n  var pal: array<vec4<i32>, 16>;\n  var tmp: array<u32, 16>;\n  for (var p0: u32 = 0u; p0 < 2u; p0 = p0 + 1u) {\n    let q0 = quantize_endpoint(ideal0, p0);\n    for (var p1: u32 = 0u; p1 < 2u; p1 = p1 + 1u) {\n      let q1 = quantize_endpoint(ideal1, p1);\n      build_palette_6(q0.eight, q1.eight, &pal);\n      let err = assign_all(pixels, &pal, &tmp);\n      if (err < local_best) {\n        local_best = err;\n        (*best).e0_7 = q0.seven;\n        (*best).e1_7 = q1.seven;\n        (*best).p0 = p0;\n        (*best).p1 = p1;\n        (*best).indices = tmp;\n        (*best).err = err;\n      }\n    }\n  }\n}\n\n// Exact-weight LSQ refit (high path); matches bc7_ref.ts `refitEndpointsMode6`.\nstruct RefitResult { e0: vec4<i32>, e1: vec4<i32>, valid: bool };\nfn refit_endpoints(\n  pixels: ptr<function, array<vec4<i32>, 16>>,\n  indices: ptr<function, array<u32, 16>>,\n) -> RefitResult {\n  var sAA: f32 = 0.0;\n  var sBB: f32 = 0.0;\n  var sAB: f32 = 0.0;\n  var sAV: vec4<f32> = vec4<f32>(0.0);\n  var sBV: vec4<f32> = vec4<f32>(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let i = (*indices)[k];\n    let a = f32(64u - w4(i)) / 64.0;\n    let b = f32(w4(i)) / 64.0;\n    let v = vec4<f32>((*pixels)[k]);\n    sAA = sAA + a * a;\n    sBB = sBB + b * b;\n    sAB = sAB + a * b;\n    sAV = sAV + a * v;\n    sBV = sBV + b * v;\n  }\n  let det = sAA * sBB - sAB * sAB;\n  var out: RefitResult;\n  if (abs(det) < 1e-9) {\n    out.valid = false;\n    return out;\n  }\n  let e0f = (sBB * sAV - sAB * sBV) / det;\n  let e1f = (sAA * sBV - sAB * sAV) / det;\n  out.e0 = vec4<i32>(clamp(round(e0f), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.e1 = vec4<i32>(clamp(round(e1f), vec4<f32>(0.0), vec4<f32>(255.0)));\n  out.valid = true;\n  return out;\n}\n\n// ------------------------------- Entry --------------------------------- //\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) {\n    return;\n  }\n\n  let bx = gid.x;\n  let by = gid.y;\n  let block_index = by * params.blocks_x + bx;\n\n  let base   = vec2<i32>(i32(bx) * 4, i32(by) * 4);\n  let max_xy = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  // Load 16 RGBA pixels (8-bit integer domain) and the per-channel bbox.\n  var pixels: array<vec4<i32>, 16>;\n  var lo = vec4<i32>(255);\n  var hi = vec4<i32>(0);\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let lx = i32(i & 3u);\n    let ly = i32(i >> 2u);\n    let p  = clamp(base + vec2<i32>(lx, ly), vec2<i32>(0, 0), max_xy);\n    let px = to8(textureLoad(src_tex, p, 0));\n    pixels[i] = px;\n    lo = min(lo, px);\n    hi = max(hi, px);\n  }\n\n  // Both branches produce: 7-bit endpoints + p-bits, and the 16 4-bit indices\n  // packed LSB-first into two nibble words (pixel k \u2192 bits 4k..4k+3).\n  var e0_7: vec4<i32>;\n  var e1_7: vec4<i32>;\n  var p0: u32;\n  var p1: u32;\n  var ilo: u32 = 0u;\n  var ihi: u32 = 0u;\n\n  if (QUALITY_HIGH != 0u) {\n    let fp = farthest_pair(&pixels);\n    var best: BestMode6;\n    best.err = 2147483647;\n    try_pbit_combos(&pixels, fp.a, fp.b, &best);\n    let refit = refit_endpoints(&pixels, &best.indices);\n    if (refit.valid) {\n      try_pbit_combos(&pixels, refit.e0, refit.e1, &best);\n    }\n    e0_7 = best.e0_7; e1_7 = best.e1_7; p0 = best.p0; p1 = best.p1;\n    for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n      ilo = ilo | (best.indices[k] << (k * 4u));\n    }\n    for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n      ihi = ihi | (best.indices[k] << ((k - 8u) * 4u));\n    }\n  } else {\n    // Seed the fused LSQ fit from the raw bbox, then quantise the refit\n    // endpoints and reproject for the final indices.\n    let r = proj_fit(&pixels, lo, hi);\n    var ep0: Ep;\n    var ep1: Ep;\n    if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }\n    else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }\n    let dir = vec4<f32>(ep1.eight - ep0.eight);\n    let dd = dot(dir, dir);\n    if (dd > 0.0) {\n      let e0f = vec4<f32>(ep0.eight);\n      let inv = 15.0 / dd;\n      for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n        let s = clamp(floor(dot(vec4<f32>(pixels[k]) - e0f, dir) * inv + 0.5), 0.0, 15.0);\n        ilo = ilo | (u32(s) << (k * 4u));\n      }\n      for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n        let s = clamp(floor(dot(vec4<f32>(pixels[k]) - e0f, dir) * inv + 0.5), 0.0, 15.0);\n        ihi = ihi | (u32(s) << ((k - 8u) * 4u));\n      }\n    }\n    e0_7 = ep0.seven; e1_7 = ep1.seven; p0 = ep0.p; p1 = ep1.p;\n  }\n\n  // Anchor rule \u2014 pixel 0's index MSB must be 0. Swapping endpoints reflects\n  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.\n  if ((ilo & 0x8u) != 0u) {\n    let t7 = e0_7; e0_7 = e1_7; e1_7 = t7;\n    let tp = p0;   p0   = p1;   p1   = tp;\n    ilo = ~ilo; ihi = ~ihi;\n  }\n\n  // Straight-line mode-6 packing (see layout at the top of the file).\n  let e0 = vec4<u32>(e0_7);\n  let e1 = vec4<u32>(e1_7);\n  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);\n  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (p0 << 31u);\n  let w2 = p1 | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);\n  let w3 = ihi;\n\n  let out = block_index * 4u;\n  dst[out + 0u] = w0;\n  dst[out + 1u] = w1;\n  dst[out + 2u] = w2;\n  dst[out + 3u] = w3;\n}\n";
 
 // src/bc7_fast_f16.wgsl
-var bc7_fast_f16_default = '// bc7 "fast" encoder \u2014 f16 variant (requires the shader-f16 feature).\n// Same algorithm family as the f32 fast path in bc7.wgsl (bbox seed \u2192\n// projection-based index assignment with a fused least-squares refit \u2192\n// reproject), tuned for throughput:\n//\n//   \u2022 All projection / refit math in f16 ([0,1] domain, so dot products stay\n//     well inside f16 range). ~2\xD7 ALU throughput on f16-capable GPUs.\n//   \u2022 The LSQ seed pass projects against the RAW bbox endpoints \u2014 quantising\n//     the seed first (pick_ep) costs two extra quantisation searches and\n//     doesn\'t measurably change where the refit lands.\n//   \u2022 Indices are packed into two u32 nibble words ON THE FLY during the\n//     final projection pass \u2014 no array<u32,16> private array. The BC7 anchor\n//     reflection (i \u2192 15\u2212i) is then just a bitwise NOT of both words.\n//   \u2022 The 128-bit block is assembled with straight-line constant shifts\n//     instead of a generic write_bits() helper (whose dynamic word indexing\n//     defeats register promotion of the output array).\n//\n// The host selects this module only when the device reports shader-f16,\n// falling back to bc7.wgsl otherwise. "high" never uses this.\n//\n// MODE 6 BIT LAYOUT (LSB-first): see bc7.wgsl. Summary:\n//   w0: mode(7 bits, 0x40) R0 R1 G0 G1[3:0]\n//   w1: G1[6:4] B0 B1 A0 A1 P0\n//   w2: P1, pixel0 index (3 bits), pixels 1..7 (4 bits each)\n//   w3: pixels 8..15 (4 bits each)\nenable f16;\nstruct Params { blocks_x: u32, blocks_y: u32, width: u32, height: u32, };\n@group(0) @binding(0) var src_tex: texture_2d<f32>;\n@group(0) @binding(1) var<storage, read_write> dst: array<u32>;\n@group(0) @binding(2) var<uniform> params: Params;\nalias h = f16;\nalias h4 = vec4<f16>;\n\n// Quantise an ideal endpoint (h4 in [0,1]) to 7-bit + p-bit, choosing the\n// p-bit with the lower quantisation error. `eight` is the decoded value the\n// hardware will interpolate with, back in [0,1].\nstruct Ep { seven: vec4<u32>, eight: h4, p: u32 };\nfn pick_ep(ideal01: h4) -> Ep {\n  let ideal = ideal01 * h(255.0);\n  let q0 = clamp(floor(ideal * h(0.5) + h(0.5)), h4(0.0), h4(127.0));        // p=0\n  let e0 = q0 * h(2.0);\n  let q1 = clamp(floor((ideal - h(1.0)) * h(0.5) + h(0.5)), h4(0.0), h4(127.0)); // p=1\n  let e1 = q1 * h(2.0) + h(1.0);\n  let d0 = e0 - ideal; let d1 = e1 - ideal;\n  if (dot(d1, d1) < dot(d0, d0)) { return Ep(vec4<u32>(q1), e1 * h(1.0 / 255.0), 1u); }\n  return Ep(vec4<u32>(q0), e0 * h(1.0 / 255.0), 0u);\n}\n\n// One pass over the block: project every pixel onto the e0\u2192e1 line and\n// accumulate the least-squares normal-equation sums; solve for the refit\n// endpoints. Indices are NOT produced here \u2014 the caller reprojects against\n// the quantised refit endpoints anyway.\nstruct Fit { e0: h4, e1: h4, valid: bool };\nfn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {\n  var out: Fit;\n  out.valid = false;\n  let dir = e1 - e0;\n  let dd = dot(dir, dir);\n  if (dd == h(0.0)) { return out; }\n  let inv = h(15.0) / dd;\n  var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);\n  var sAV = h4(0.0); var sBV = h4(0.0);\n  var s_min = h(15.0); var s_max = h(0.0);\n  for (var k: u32 = 0u; k < 16u; k = k + 1u) {\n    let v = (*pix)[k];\n    let s = clamp(floor(dot(v - e0, dir) * inv + h(0.5)), h(0.0), h(15.0));\n    s_min = min(s_min, s); s_max = max(s_max, s);\n    let b = s * h(1.0 / 15.0); let a = h(1.0) - b;\n    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;\n    sAV = sAV + a * v; sBV = sBV + b * v;\n  }\n  // Rank-1 guard: if every pixel projects to ONE level the system is\n  // singular \u2014 det/numerators are pure f16 rounding noise and the solve\n  // returns garbage endpoints. With \u22652 distinct levels\n  // det = \u03A3_i<j (b_j \u2212 b_i)\xB2 \u2265 15/225 \u2248 0.067, so 0.02 is a safe floor.\n  if (s_min == s_max) { return out; }\n  let det = sAA * sBB - sAB * sAB;\n  if (abs(det) < h(0.02)) { return out; }\n  out.e0 = clamp((sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));\n  out.e1 = clamp((sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));\n  out.valid = true;\n  return out;\n}\n\n@compute @workgroup_size(8, 8, 1)\nfn encode(@builtin(global_invocation_id) gid: vec3<u32>) {\n  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) { return; }\n  let bi = gid.y * params.blocks_x + gid.x;\n  let base = vec2<i32>(i32(gid.x) * 4, i32(gid.y) * 4);\n  let mx = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);\n\n  var pix: array<h4, 16>;\n  var lo = h4(1.0);\n  var hi = h4(0.0);\n  for (var i: u32 = 0u; i < 16u; i = i + 1u) {\n    let p = clamp(base + vec2<i32>(i32(i & 3u), i32(i >> 2u)), vec2<i32>(0), mx);\n    let px = h4(textureLoad(src_tex, p, 0));\n    pix[i] = px; lo = min(lo, px); hi = max(hi, px);\n  }\n\n  // Seed fit from the raw bbox, then quantise the refit endpoints.\n  let r = proj_fit(&pix, lo, hi);\n  var ep0: Ep;\n  var ep1: Ep;\n  if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }\n  else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }\n\n  // Final projection against the decoded endpoints, packing the 4-bit indices\n  // into two nibble words as we go (pixel k \u2192 bits 4k..4k+3 of ilo/ihi).\n  var ilo: u32 = 0u;\n  var ihi: u32 = 0u;\n  let dir = ep1.eight - ep0.eight;\n  let dd = dot(dir, dir);\n  if (dd > h(0.0)) {\n    let inv = h(15.0) / dd;\n    for (var k: u32 = 0u; k < 8u; k = k + 1u) {\n      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));\n      ilo = ilo | (u32(s) << (k * 4u));\n    }\n    for (var k: u32 = 8u; k < 16u; k = k + 1u) {\n      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));\n      ihi = ihi | (u32(s) << ((k - 8u) * 4u));\n    }\n  }\n\n  // Anchor rule \u2014 pixel 0\'s index MSB must be 0. Swapping endpoints reflects\n  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.\n  if ((ilo & 0x8u) != 0u) {\n    let t = ep0; ep0 = ep1; ep1 = t;\n    ilo = ~ilo; ihi = ~ihi;\n  }\n\n  // Straight-line mode-6 packing (see layout above).\n  let e0 = ep0.seven;\n  let e1 = ep1.seven;\n  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);\n  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (ep0.p << 31u);\n  let w2 = ep1.p | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);\n  let w3 = ihi;\n\n  let o = bi * 4u;\n  dst[o] = w0; dst[o + 1u] = w1; dst[o + 2u] = w2; dst[o + 3u] = w3;\n}\n';
+var bc7_fast_f16_default = `// bc7 "fast" encoder \u2014 f16 variant (requires the shader-f16 feature).
+// Same algorithm family as the f32 fast path in bc7.wgsl (bbox seed \u2192
+// projection-based index assignment with a fused least-squares refit \u2192
+// reproject), tuned for throughput:
+//
+//   \u2022 All projection / refit math in f16 ([0,1] domain). ~2\xD7 ALU throughput
+//     on f16-capable GPUs. The projection direction is pre-scaled by 32:
+//     a shallow block (endpoints ~1/255 apart) has dd = dot(dir,dir) \u2248 1.5e-5,
+//     where 15/dd \u2248 10\u2076 overflows f16 (max 65504) to +inf and the products
+//     inside the projection dot are subnormal \u2014 the indices and the LSQ refit
+//     feeding on them turn to garbage (visible as banding on smooth
+//     gradients). Scaling dir by 32 multiplies the dots by 32 and dd by 1024;
+//     s = dot\xB7(32\xB715/dd\u2083\u2082) is the same quantity with every intermediate in
+//     f16's normal range (worst case inv = 480/0.0157 \u2248 3.0e4 < 65504).
+//   \u2022 The LSQ seed pass projects against the RAW bbox endpoints \u2014 quantising
+//     the seed first (pick_ep) costs two extra quantisation searches and
+//     doesn't measurably change where the refit lands.
+//   \u2022 Indices are packed into two u32 nibble words ON THE FLY during the
+//     final projection pass \u2014 no array<u32,16> private array. The BC7 anchor
+//     reflection (i \u2192 15\u2212i) is then just a bitwise NOT of both words.
+//   \u2022 The 128-bit block is assembled with straight-line constant shifts
+//     instead of a generic write_bits() helper (whose dynamic word indexing
+//     defeats register promotion of the output array).
+//
+// The host selects this module only when the device reports shader-f16,
+// falling back to bc7.wgsl otherwise. "high" never uses this.
+//
+// MODE 6 BIT LAYOUT (LSB-first): see bc7.wgsl. Summary:
+//   w0: mode(7 bits, 0x40) R0 R1 G0 G1[3:0]
+//   w1: G1[6:4] B0 B1 A0 A1 P0
+//   w2: P1, pixel0 index (3 bits), pixels 1..7 (4 bits each)
+//   w3: pixels 8..15 (4 bits each)
+enable f16;
+struct Params { blocks_x: u32, blocks_y: u32, width: u32, height: u32, };
+@group(0) @binding(0) var src_tex: texture_2d<f32>;
+@group(0) @binding(1) var<storage, read_write> dst: array<u32>;
+@group(0) @binding(2) var<uniform> params: Params;
+alias h = f16;
+alias h4 = vec4<f16>;
+
+// Quantise an ideal endpoint (h4 in [0,1]) to 7-bit + p-bit, choosing the
+// p-bit with the lower quantisation error. \`eight\` is the decoded value the
+// hardware will interpolate with, back in [0,1].
+struct Ep { seven: vec4<u32>, eight: h4, p: u32 };
+fn pick_ep(ideal01: h4) -> Ep {
+  let ideal = ideal01 * h(255.0);
+  let q0 = clamp(floor(ideal * h(0.5) + h(0.5)), h4(0.0), h4(127.0));        // p=0
+  let e0 = q0 * h(2.0);
+  let q1 = clamp(floor((ideal - h(1.0)) * h(0.5) + h(0.5)), h4(0.0), h4(127.0)); // p=1
+  let e1 = q1 * h(2.0) + h(1.0);
+  let d0 = e0 - ideal; let d1 = e1 - ideal;
+  if (dot(d1, d1) < dot(d0, d0)) { return Ep(vec4<u32>(q1), e1 * h(1.0 / 255.0), 1u); }
+  return Ep(vec4<u32>(q0), e0 * h(1.0 / 255.0), 0u);
+}
+
+// One pass over the block: project every pixel onto the e0\u2192e1 line and
+// accumulate the least-squares normal-equation sums; solve for the refit
+// endpoints. Indices are NOT produced here \u2014 the caller reprojects against
+// the quantised refit endpoints anyway.
+//
+// The value sums accumulate v \u2212 e0, not v: the basis is affine (a + b = 1),
+// so fitting the shifted data and adding e0 back is the same fit, but the
+// accumulators scale with the block's span instead of its absolute level \u2014
+// on a shallow dark block, f16 rounding of absolute sums (ulp \u2248 0.12 of an
+// 8-bit level per add) drifts the refit endpoints by \xB11 level.
+struct Fit { e0: h4, e1: h4, valid: bool };
+fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
+  var out: Fit;
+  out.valid = false;
+  // dir pre-scaled by 32 to keep dd and the projection dots in f16's normal
+  // range (see header). Spans below ~0.7 of an 8-bit step (dd\u2083\u2082 < 0.008,
+  // possible only for non-8-bit sources) are treated as flat \u2014 encoding them
+  // flat is under half a level of error, while running the math on them risks
+  // inv overflowing to +inf.
+  let dir = (e1 - e0) * h(32.0);
+  let dd = dot(dir, dir);
+  if (dd < h(0.008)) { return out; }
+  let inv = h(480.0) / dd; // 32\xB715/dd\u2083\u2082 \u2261 15/dd
+  var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);
+  var sAV = h4(0.0); var sBV = h4(0.0);
+  var s_min = h(15.0); var s_max = h(0.0);
+  for (var k: u32 = 0u; k < 16u; k = k + 1u) {
+    let vr = (*pix)[k] - e0;
+    let s = clamp(floor(dot(vr, dir) * inv + h(0.5)), h(0.0), h(15.0));
+    s_min = min(s_min, s); s_max = max(s_max, s);
+    let b = s * h(1.0 / 15.0); let a = h(1.0) - b;
+    sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;
+    sAV = sAV + a * vr; sBV = sBV + b * vr;
+  }
+  // Rank-1 guard: if every pixel projects to ONE level the system is
+  // singular \u2014 det/numerators are pure f16 rounding noise and the solve
+  // returns garbage endpoints. With \u22652 distinct levels
+  // det = \u03A3_i<j (b_j \u2212 b_i)\xB2 \u2265 15/225 \u2248 0.067, so 0.02 is a safe floor.
+  if (s_min == s_max) { return out; }
+  let det = sAA * sBB - sAB * sAB;
+  if (abs(det) < h(0.02)) { return out; }
+  out.e0 = clamp(e0 + (sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
+  out.e1 = clamp(e0 + (sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
+  out.valid = true;
+  return out;
+}
+
+@compute @workgroup_size(8, 8, 1)
+fn encode(@builtin(global_invocation_id) gid: vec3<u32>) {
+  if (gid.x >= params.blocks_x || gid.y >= params.blocks_y) { return; }
+  let bi = gid.y * params.blocks_x + gid.x;
+  let base = vec2<i32>(i32(gid.x) * 4, i32(gid.y) * 4);
+  let mx = vec2<i32>(i32(params.width) - 1, i32(params.height) - 1);
+
+  var pix: array<h4, 16>;
+  var lo = h4(1.0);
+  var hi = h4(0.0);
+  for (var i: u32 = 0u; i < 16u; i = i + 1u) {
+    let p = clamp(base + vec2<i32>(i32(i & 3u), i32(i >> 2u)), vec2<i32>(0), mx);
+    let px = h4(textureLoad(src_tex, p, 0));
+    pix[i] = px; lo = min(lo, px); hi = max(hi, px);
+  }
+
+  // Seed fit from the raw bbox, then quantise the refit endpoints.
+  let r = proj_fit(&pix, lo, hi);
+  var ep0: Ep;
+  var ep1: Ep;
+  if (r.valid) { ep0 = pick_ep(r.e0); ep1 = pick_ep(r.e1); }
+  else         { ep0 = pick_ep(lo);   ep1 = pick_ep(hi);   }
+
+  // Final projection against the decoded endpoints, packing the 4-bit indices
+  // into two nibble words as we go (pixel k \u2192 bits 4k..4k+3 of ilo/ihi).
+  var ilo: u32 = 0u;
+  var ihi: u32 = 0u;
+  // Same \xD732 pre-scale as proj_fit; distinct quantised endpoints are \u22651/255
+  // apart, i.e. dd\u2083\u2082 \u2265 0.0157, so the flat-block threshold only catches
+  // truly identical endpoints.
+  let dir = (ep1.eight - ep0.eight) * h(32.0);
+  let dd = dot(dir, dir);
+  if (dd >= h(0.008)) {
+    let inv = h(480.0) / dd;
+    for (var k: u32 = 0u; k < 8u; k = k + 1u) {
+      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));
+      ilo = ilo | (u32(s) << (k * 4u));
+    }
+    for (var k: u32 = 8u; k < 16u; k = k + 1u) {
+      let s = clamp(floor(dot(pix[k] - ep0.eight, dir) * inv + h(0.5)), h(0.0), h(15.0));
+      ihi = ihi | (u32(s) << ((k - 8u) * 4u));
+    }
+  }
+
+  // Anchor rule \u2014 pixel 0's index MSB must be 0. Swapping endpoints reflects
+  // every index (i \u2192 15\u2212i), which on packed nibbles is a bitwise NOT.
+  if ((ilo & 0x8u) != 0u) {
+    let t = ep0; ep0 = ep1; ep1 = t;
+    ilo = ~ilo; ihi = ~ihi;
+  }
+
+  // Straight-line mode-6 packing (see layout above).
+  let e0 = ep0.seven;
+  let e1 = ep1.seven;
+  let w0 = 0x40u | (e0.x << 7u) | (e1.x << 14u) | (e0.y << 21u) | (e1.y << 28u);
+  let w1 = (e1.y >> 4u) | (e0.z << 3u) | (e1.z << 10u) | (e0.w << 17u) | (e1.w << 24u) | (ep0.p << 31u);
+  let w2 = ep1.p | ((ilo & 0x7u) << 1u) | (ilo & 0xFFFFFFF0u);
+  let w3 = ihi;
+
+  let o = bi * 4u;
+  dst[o] = w0; dst[o + 1u] = w1; dst[o + 2u] = w2; dst[o + 3u] = w3;
+}
+`;
 
 // src/BC7Encoder.ts
 var BC7Encoder = class extends Encoder {
@@ -673,7 +837,13 @@ var astc4x4_fast_f16_default = `// astc4x4 "fast" encoder \u2014 f16 variant (re
 // projection weight assignment with a fused least-squares refit \u2192
 // reproject), tuned for throughput:
 //
-//   \u2022 All projection / refit math in f16 ([0,1] domain).
+//   \u2022 All projection / refit math in f16 ([0,1] domain). The projection
+//     direction is pre-scaled by 32 \u2014 a shallow block (endpoints ~1/255
+//     apart) has dd \u2248 1.5e-5, where 3/dd \u2248 2e5 overflows f16 (max 65504) to
+//     +inf and the projection dots go subnormal, turning weights and the LSQ
+//     refit to garbage (banding on smooth gradients). Scaling dir by 32 puts
+//     every intermediate in f16's normal range; s = dot\xB7(32\xB73/dd\u2083\u2082) is the
+//     same quantity (worst case inv = 96/0.0157 \u2248 6.1e3).
 //   \u2022 The seed pass only accumulates the LSQ sums (no weight output) \u2014 the
 //     final weights come from reprojecting against the refit endpoints.
 //   \u2022 Endpoint ordering (the blue-contraction rule: sum(e0.rgb) must not
@@ -700,20 +870,27 @@ struct Fit { e0: h4, e1: h4, valid: bool };
 fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
   var out: Fit;
   out.valid = false;
-  let dir = e1 - e0;
+  // dir pre-scaled by 32 to keep dd and the projection dots in f16's normal
+  // range (see header). Spans below ~0.7 of an 8-bit step (dd\u2083\u2082 < 0.008,
+  // possible only for non-8-bit sources) are treated as flat.
+  let dir = (e1 - e0) * h(32.0);
   let dd = dot(dir, dir);
-  if (dd == h(0.0)) { return out; }
-  let inv = h(3.0) / dd;
+  if (dd < h(0.008)) { return out; }
+  let inv = h(96.0) / dd; // 32\xB73/dd\u2083\u2082 \u2261 3/dd
   var sAA = h(0.0); var sBB = h(0.0); var sAB = h(0.0);
   var sAV = h4(0.0); var sBV = h4(0.0);
   var s_min = h(3.0); var s_max = h(0.0);
+  // Value sums accumulate v \u2212 e0 (basis is affine, a + b = 1, so the fit
+  // commutes with the shift): accumulators scale with the block span, keeping
+  // f16 rounding a fraction of the span instead of \xB11 level at high absolute
+  // values.
   for (var k: u32 = 0u; k < 16u; k = k + 1u) {
-    let v = (*pix)[k];
-    let s = clamp(floor(dot(v - e0, dir) * inv + h(0.5)), h(0.0), h(3.0));
+    let vr = (*pix)[k] - e0;
+    let s = clamp(floor(dot(vr, dir) * inv + h(0.5)), h(0.0), h(3.0));
     s_min = min(s_min, s); s_max = max(s_max, s);
     let b = s * h(1.0 / 3.0); let a = h(1.0) - b;
     sAA = sAA + a * a; sBB = sBB + b * b; sAB = sAB + a * b;
-    sAV = sAV + a * v; sBV = sBV + b * v;
+    sAV = sAV + a * vr; sBV = sBV + b * vr;
   }
   // Rank-1 guard: if every pixel projects to ONE level the system is
   // singular \u2014 det/numerators are pure f16 rounding noise and the solve
@@ -722,8 +899,8 @@ fn proj_fit(pix: ptr<function, array<h4, 16>>, e0: h4, e1: h4) -> Fit {
   if (s_min == s_max) { return out; }
   let det = sAA * sBB - sAB * sAB;
   if (abs(det) < h(0.5)) { return out; }
-  out.e0 = clamp((sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
-  out.e1 = clamp((sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
+  out.e0 = clamp(e0 + (sBB * sAV - sAB * sBV) / det, h4(0.0), h4(1.0));
+  out.e1 = clamp(e0 + (sAA * sBV - sAB * sAV) / det, h4(0.0), h4(1.0));
   out.valid = true;
   return out;
 }
@@ -766,10 +943,12 @@ fn encode(@builtin(global_invocation_id) gid: vec3<u32>) {
   // Weight pass, packing on the fly: weight k's lsb at bit 31\u22122k of the last
   // word, msb at bit 30\u22122k.
   var w3: u32 = 0u;
-  let dir = d1 - d0;
+  // Same \xD732 pre-scale as proj_fit; distinct 8-bit endpoints are \u22651/255
+  // apart (dd\u2083\u2082 \u2265 0.0157), so the threshold only catches identical ones.
+  let dir = (d1 - d0) * h(32.0);
   let dd = dot(dir, dir);
-  if (dd > h(0.0)) {
-    let inv = h(3.0) / dd;
+  if (dd >= h(0.008)) {
+    let inv = h(96.0) / dd;
     for (var k: u32 = 0u; k < 16u; k = k + 1u) {
       let s = u32(clamp(floor(dot(pix[k] - d0, dir) * inv + h(0.5)), h(0.0), h(3.0)));
       w3 = w3 | ((s & 1u) << (31u - 2u * k)) | (((s >> 1u) & 1u) << (30u - 2u * k));
@@ -1118,13 +1297,26 @@ function detectWebGLCapabilities(gl) {
 // src/webgl/selectWebGLFormat.ts
 var NONE = { format: null, encoderClass: null, astcNormalRemap: false };
 function selectWebGLFormat(caps, hint, options = {}) {
-  const { colorSpace = "srgb" } = options;
+  const { colorSpace = "srgb", preferredFormat } = options;
   const srgb = colorSpace === "srgb";
   const astc = (astcNormalRemap) => ({
     format: srgb ? TextureFormat.ASTC_4x4_SRGB : TextureFormat.ASTC_4x4,
     encoderClass: ASTC4x4WebGLEncoder,
     astcNormalRemap
   });
+  if (preferredFormat === "bc1") {
+    if (hint !== "color") {
+      console.warn(
+        `[gputex] preferredFormat 'bc1' ignored for hint '${hint}' \u2014 BC1 has no real alpha channel and is unsuitable for normal maps.`
+      );
+    } else if (srgb ? caps.s3tcSrgb : caps.s3tc) {
+      return {
+        format: srgb ? TextureFormat.BC1_SRGB : TextureFormat.BC1,
+        encoderClass: BC1WebGLEncoder,
+        astcNormalRemap: false
+      };
+    }
+  }
   if (hint === "normal") {
     if (caps.rgtc) return { format: TextureFormat.BC5, encoderClass: BC5WebGLEncoder, astcNormalRemap: false };
     if (caps.astc) return astc(true);
@@ -1151,9 +1343,22 @@ function selectWebGLFormat(caps, hint, options = {}) {
 
 // src/selectFormat.ts
 function selectFormat(adapter, hint, options = {}) {
-  const { colorSpace = "srgb" } = options;
+  const { colorSpace = "srgb", preferredFormat } = options;
   const srgb = colorSpace === "srgb";
   const caps = detectCapabilities(adapter);
+  if (preferredFormat === "bc1") {
+    if (hint !== "color") {
+      console.warn(
+        `[gputex] preferredFormat 'bc1' ignored for hint '${hint}' \u2014 BC1 has no real alpha channel and is unsuitable for normal maps.`
+      );
+    } else if (caps.bc) {
+      return {
+        format: srgb ? TextureFormat.BC1_SRGB : TextureFormat.BC1,
+        encoderClass: BC1Encoder,
+        astcNormalRemap: false
+      };
+    }
+  }
   if (caps.bc) {
     if (hint === "normal") {
       return { format: TextureFormat.BC5, encoderClass: BC5Encoder, astcNormalRemap: false };
@@ -1366,6 +1571,7 @@ function wrapUncompressed(bitmap, srgb, flipY) {
 async function compressTexture(source, options = {}) {
   const {
     hint = "color",
+    preferredFormat,
     colorSpace = "srgb",
     flipY = true,
     mipmaps = false,
@@ -1401,7 +1607,7 @@ async function compressTexture(source, options = {}) {
     if (!("gpu" in navigator)) return null;
     const adapter = providedAdapter ?? await navigator.gpu.requestAdapter();
     if (!adapter) return null;
-    const selection = selectFormat(adapter, hint, { colorSpace });
+    const selection = selectFormat(adapter, hint, { colorSpace, preferredFormat });
     if (!selection.format || !selection.encoderClass) return null;
     let encoder;
     if (providedDevice) {
@@ -1474,7 +1680,7 @@ async function compressTexture(source, options = {}) {
     const gl = getSharedWebGLContext();
     if (!gl) return null;
     const caps = detectWebGLCapabilities(gl);
-    const selection = selectWebGLFormat(caps, hint, { colorSpace });
+    const selection = selectWebGLFormat(caps, hint, { colorSpace, preferredFormat });
     if (!selection.format || !selection.encoderClass) return null;
     const encoder = selection.encoderClass.create(gl);
     try {
@@ -1536,6 +1742,12 @@ import { Loader } from "three";
 var GputexLoader = class extends Loader {
   /** Format-selection hint. Default 'color'. */
   hint = "color";
+  /**
+   * Prefer a specific format (currently only 'bc1') when the device
+   * supports it; normal selection otherwise. See
+   * `CompressOptions.preferredFormat`.
+   */
+  preferredFormat;
   /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
   colorSpace = "srgb";
   /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
@@ -1567,6 +1779,7 @@ var GputexLoader = class extends Loader {
     this.manager.itemStart(url);
     compressTexture(url, {
       hint: this.hint,
+      preferredFormat: this.preferredFormat,
       colorSpace: this.colorSpace,
       flipY: this.flipY,
       mipmaps: this.mipmaps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gputex",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "MIT",
   "files": [
     "dist"