《计算机图形学》卷二《着色、光照与纹理》附录 A · 着色公式、材质参数表与数据集索引

#!/usr/bin/env python3
# file: lantern/sim/cg_shade_appendix_a.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/cg_shade_appendix_a.py
"""附录 A 的数据源：全卷共用的 Q16.16 定点常数表与量级上界。

这些常数被第 1、2、6、7 章反复引用，集中列在这里。第二部分是**量级上界**：
它决定某一层能用 `Number` 还是必须用 `BigInt`——这是全卷最容易出错的地方，
因为 JS 的 `Number` 只在 2^53 以内能精确表示整数，而矩阵链的中间量远超这个界。

脚本只用整数运算（算术右移与 `bit_length`），与 Python / TypeScript 两侧一致。
"""

import sys

ONE = 65536

CONSTANTS = [
    ("ONE", 65536, "Q16.16 的 1.0"),
    ("SUB", 6, "屏幕子像素位数"),
    ("SUB1", 64, "1 像素 = 64 单位"),
    ("TWO_PI", 411775, "2π（π = 205887）"),
    ("INV_PI", 20861, "1/π，Lambert 的归一化系数"),
    ("PHONG_NORM", 187749, "9/π，n = 16 的归一化 Phong"),
    ("BLINN_NORM", 62583, "3/π，n = 16 的归一化 Blinn"),
]

# 逐像素层：屏幕 Q6 最大 320×64，边函数是两个坐标差的乘积
MAX_SCREEN = 320 * 64
MAX_EDGE = 2 * MAX_SCREEN * MAX_SCREEN
MAX_INTERP = MAX_EDGE * ONE

MAGNITUDE = [
    ("屏幕坐标（Q6）", MAX_SCREEN, "画布宽 320，1 像素 = 64 单位"),
    ("边函数", MAX_EDGE, "两个坐标差的乘积"),
    ("法线插值分子", MAX_INTERP, "边函数 × Q16.16 法线"),
    ("三项累加", 3 * MAX_INTERP, "重心坐标三项求和"),
]

LIMIT = 1 << 53


def main():
    print("== 定点常数 ==")
    for name, value, note in CONSTANTS:
        print(f"{name:<12} {value:>8}  {note}")
    print()
    print(f"== 量级上界（Number 精确上界 2^53 = {LIMIT}）==")
    for name, value, note in MAGNITUDE:
        bits = value.bit_length()
        safe = "OK" if value < LIMIT else "OVERFLOW"
        print(f"{name:<14} {value:>20}  2^{bits:<3} {safe:<9} {note}")
    print()
    worst = MAGNITUDE[-1][1]
    print(f"最大中间量 / 2^53 = {worst * 1000 // LIMIT}‰")
    print(f"结论：逐像素层可以用 Number + Math.floor；矩阵链必须留在 BigInt 里。")
    return 0


if __name__ == "__main__":
    sys.exit(main())

# snippet: sim/cg_shade_appendix_a.py 的实跑输出（本机，exit 0）
== 定点常数 ==
ONE             65536  Q16.16 的 1.0
SUB                 6  屏幕子像素位数
SUB1               64  1 像素 = 64 单位
TWO_PI         411775  2π（π = 205887）
INV_PI          20861  1/π，Lambert 的归一化系数
PHONG_NORM     187749  9/π，n = 16 的归一化 Phong
BLINN_NORM      62583  3/π，n = 16 的归一化 Blinn

== 量级上界（Number 精确上界 2^53 = 9007199254740992）==
屏幕坐标（Q6）                      20480  2^15  OK        画布宽 320，1 像素 = 64 单位
边函数                       838860800  2^30  OK        两个坐标差的乘积
法线插值分子               54975581388800  2^46  OK        边函数 × Q16.16 法线
三项累加                164926744166400  2^48  OK        重心坐标三项求和

最大中间量 / 2^53 = 18‰
结论：逐像素层可以用 Number + Math.floor；矩阵链必须留在 BigInt 里。

逐顶点 (Gouraud)  sha256 bac659770178037ad3f6a6ad184945a96ff37a7fe4d754ef1ebc5b0aaa538ced
逐像素 (per-pixel) sha256 0d997343ca547ed5cada5e4b1f75ce1782d79e524dba817278853de77307a6de
覆盖               43731 像素（569‰）  剔除 290  丢弃 0
着色频率差异       41261 像素（537.2526‰）  MAE 3.5764  PSNR 37.06 dB  最大通道差 48
覆盖掩码差异       0.0‰

# snippet: 本卷的复现命令（全部在 lantern/ 目录下执行）
cd ~/.cgbook/lantern

# 卷二入口：双基线 + 着色频率差异
/opt/homebrew/bin/python3 sim/render_shade.py
node core/tools/render_shade_ts.ts          # 断言与 Python 侧 sha256 逐字节相同

# 本附录的数据源
/opt/homebrew/bin/python3 sim/cg_shade_appendix_a.py

# P 层测试（本卷全部章节）
node --test 'core/test/cg_shade_*.test.ts'