8.2 过滤与 mipmap 的构造

// snippet: lantern/core/src/lantern/cg_shade_08_filter.ts
export function sampleBilinear(tex, n, u, v) {
  const fu = u * n - F_ONE / 2;              // texel 中心在 (i + 0.5) / n
  const fv = v * n - F_ONE / 2;
  const iu = Math.floor(fu / F_ONE);         // 不用 `>> 16`：JS 的移位只对 32 位有效
  const iv = Math.floor(fv / F_ONE);
  const gu = fu - iu * F_ONE;                // 两个 Q16.16 的分数位
  const gv = fv - iv * F_ONE;
  const a = F_ONE - gu, b = gu, c = F_ONE - gv, d = gv;
  const x0 = iu & (n - 1), x1 = (iu + 1) & (n - 1);   // n 为 2 的幂，位与即回绕
  const y0 = iv & (n - 1), y1 = (iv + 1) & (n - 1);
  for (let ch = 0; ch < 3; ch += 1) {
    const s = tex[(y0 * n + x0) * 3 + ch] * a * c
            + tex[(y0 * n + x1) * 3 + ch] * b * c
            + tex[(y1 * n + x0) * 3 + ch] * a * d
            + tex[(y1 * n + x1) * 3 + ch] * b * d;
    out[ch] = Math.floor(s / 4294967296);    // 四个权重累加后一次 >> 32
  }
  return out;
}

#!/usr/bin/env python3
# file: lantern/sim/cg_shade_08_2_kernel.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_shade_08_2_kernel.py
"""8.2 的内核：最近邻 / 双线性 / mip 链 / 三线性，全部在整数域完成。

被 sim/cg_shade_08_2_filter_mip.py 调用；单独成文件是为了让正文里的 `file:` 块
就是本节真正在跑的那段代码。

  1. **双线性**：texel 中心在 (i + 0.5) / n，四个权重是 Q16.16 的互补对，累加后
     `>> 32` 降精度（不是两次 `>> 16`，那会在每个中间项上各丢一次低位）。
  2. **mip 链**：下一级 = 上一级 2x2 盒式平均 `(a+b+c+d) >> 2`。尺寸为 2 的幂时
     干净利落；**奇数尺寸**要决定最后一行/列怎么办 —— 这里两种做法都给：`(n+1)//2`
     且索引钳位（保留边界），对 `n//2` 截断（丢掉最后一行/列）。
  3. **LOD 选择**：`floor(log2)` 用整数位长求（不用浮点 log）；分数部分是分段线性
     近似。本文件不含浮点。
"""

import os
import sys

import numpy as np

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import cglib  # noqa: E402

ONE = cglib.ONE


def make_noise(n, seed=0x0C7A):
    """程序化高频纹理：每 2x2 texel 共享一个整数哈希值（`cglib._hash_noise`）。"""
    tex = np.zeros((n, n, 3), dtype=np.int64)
    for ty in range(n):
        for tx in range(n):
            for ch in range(3):
                tex[ty, tx, ch] = cglib._hash_noise(tx >> 1, ty >> 1, seed + ch) >> 8
    return tex


def build_mips(tex):
    """2x2 盒式平均：`(a+b+c+d) >> 2`，尺寸减半到 1x1（n 为 2 的幂）。"""
    chain, cur = [tex], tex
    while cur.shape[0] > 1:
        cur = (cur[0::2, 0::2] + cur[0::2, 1::2] + cur[1::2, 0::2] + cur[1::2, 1::2]) >> 2
        chain.append(cur)
    return chain


def build_mips_odd(tex, clamp):
    """奇数尺寸的 mip 链：clamp=True 保留边界（(n+1)//2 且索引钳位），
    clamp=False 直接 n//2 截断 —— 后者会丢掉最后一行/列。"""
    chain, cur = [tex], tex
    while cur.shape[0] > 1:
        n = cur.shape[0]
        m = (n + 1) // 2 if clamp else n // 2
        idx = (np.minimum(2 * np.arange(m) + 1, n - 1) if clamp else 2 * np.arange(m) + 1)
        cur = (cur[np.ix_(2 * np.arange(m), 2 * np.arange(m))]
               + cur[np.ix_(2 * np.arange(m), idx)]
               + cur[np.ix_(idx, 2 * np.arange(m))]
               + cur[np.ix_(idx, idx)]) >> 2
        chain.append(cur)
    return chain


def sample_nearest(tex, n, u, v):
    """最近邻：`(u * n) >> 16` 就是 floor(u * n)，`& (n - 1)` 即 repeat 回绕。"""
    iu, iv = ((u * n) >> 16) & (n - 1), ((v * n) >> 16) & (n - 1)
    return [int(tex[iv, iu, ch]) for ch in range(3)]


def sample_bilinear(tex, n, u, v):
    """texel 中心在 (i+0.5)/n；四个 Q16.16 权重累加后 `>> 32` 降精度。"""
    fu, fv = u * n - (ONE >> 1), v * n - (ONE >> 1)
    iu, iv = fu >> 16, fv >> 16
    gu, gv = fu - (iu << 16), fv - (iv << 16)
    a, b, c, d = ONE - gu, gu, ONE - gv, gv
    x0, x1 = iu & (n - 1), (iu + 1) & (n - 1)
    y0, y1 = iv & (n - 1), (iv + 1) & (n - 1)
    return [(int(tex[y0, x0, ch]) * a * c + int(tex[y0, x1, ch]) * b * c
             + int(tex[y1, x0, ch]) * a * d + int(tex[y1, x1, ch]) * b * d) >> 32
            for ch in range(3)]


def ilog2(x):
    """floor(log2(x))：整数位长求法，不用浮点 log。"""
    return int(x).bit_length() - 1


def lod_q16(fp):
    """log2(fp) 的 Q16.16 分段线性近似：以 2^b 为断点，断点间线性插值。"""
    if fp < 1:
        return 0
    b = ilog2(fp)
    return ((b - 16) << 16) + (((fp - (1 << b)) << 16) // (1 << b))


def trilinear(chain, lod, u, v):
    """相邻两级各双线性一次，再按分数位长插值。"""
    l0 = max(0, min(len(chain) - 2, lod >> 16))
    f = lod - (l0 << 16)
    c0 = sample_bilinear(chain[l0], chain[l0].shape[0], u, v)
    c1 = sample_bilinear(chain[l0 + 1], chain[l0 + 1].shape[0], u, v)
    return [(c0[ch] * (ONE - f) + c1[ch] * f) >> 16 for ch in range(3)]


if __name__ == "__main__":
    t = make_noise(8)
    ch = build_mips(t)
    c = ONE * 7 // 16  # u = 0.4375 = (3 + 0.5) / 8，正落在 texel 中心
    print("8x8 链尺寸        :", [int(l.shape[0]) for l in ch])
    print("链尾均值          :", [int(l.mean()) for l in ch])
    print("texel 中心双线性   :", sample_bilinear(t, 8, c, c))
    print("同点最近邻        :", sample_nearest(t, 8, c, c))
    print("二者相等          :", sample_bilinear(t, 8, c, c) == sample_nearest(t, 8, c, c))
    print("lod_q16(1 texel)  :", lod_q16(ONE), "  (2 texel):", lod_q16(2 * ONE))
    print("lod_q16(1.5 texel):", lod_q16(3 * ONE // 2), "  真值 log2(1.5) = 0.585 级")

8x8 链尺寸        : [8, 4, 2, 1]
链尾均值          : [132, 132, 131, 131]
texel 中心双线性   : [177, 141, 240]
同点最近邻        : [177, 141, 240]
二者相等          : True
lod_q16(1 texel)  : 0   (2 texel): 65536
lod_q16(1.5 texel): 32768   真值 log2(1.5) = 0.585 级

✔ 自描述纹理与 mip 链逐字节相同（含逐级 sha256）
✔ 【核心】覆盖数、LOD 直方图与整数 LOD 选择一致
✔ 【核心】五种过滤模式的像素缓冲 sha256 与 Python 侧逐字节相同
✔ 4x4 超采样参考解逐字节相同，且 MAE 表一致
✔ 负例：LOD 选错一级必须被 1.0 的容差判据抓住
ℹ tests 5  ℹ pass 5  ℹ fail 0