docs: organize Color Finale migration research and remove prior target descriptions from current tree

这个提交包含在:
mac 于 2026-10-31 16:16:47 +08:00 提交
1 父节点 29dc4d385c
当前提交 719229ddd8
24 个文件已更改
+1012 -3028

没有与搜索条件相匹配的文件

+7 -7
查看文件
@@ -1,12 +1,12 @@
# 可重建调色内核
生产构建只读取本目录的 LLVM AIR 文本和项目的 `DYGrade.metal`,不读取原厂 App、原始 metallib、网络或授权状态。来源、原始模块范围和改动见 `PROVENANCE.json`。这些文本是从已交付着色器还原的指令图,不是原始 Metal 源码。
生产构建只读取本目录的 LLVM AIR 文本和项目的 `DYGrade.metal`,无需外部应用、原始 metallib 或网络。来源、原始模块范围和改动见 `PROVENANCE.json`。这些文本是从已交付着色器还原的指令图,不是原始 Metal 源码。
```sh
python3 tools/build_kernels.py --output /absolute/default.metallib --intermediates /absolute/cache
```
`DYGradeKernel.ll` 保留参考颜色数学:线性输入转 sRGB 编码域 → 输入 LUT → RGB 三原色矩阵 → 曝光 → 白平衡 LUT → 对比/高光/阴影 → 自适应白场 → 黑场 → 局部纹理/清晰度/去雾 → 主及 RGB 曲线 → 主及 RGB 色阶 → 色彩平衡 → 8 色 HSL LUT 与自定义 HSL → 分级 LUT → 自然饱和/饱和度 → 黑白 → 5 层风格 LUT → 肤色保护 → 线性输出。中性参数直接返回输入;各章节和单项旁路保留。原许可、水印、字形表及其参数已移除。
`DYGradeKernel.ll` 执行颜色处理链:线性输入转 sRGB 编码域 → 输入 LUT → RGB 三原色矩阵 → 曝光 → 白平衡 LUT → 对比/高光/阴影 → 自适应白场 → 黑场 → 局部纹理/清晰度/去雾 → 主及 RGB 曲线 → 主及 RGB 色阶 → 色彩平衡 → 8 色 HSL LUT 与自定义 HSL → 分级 LUT → 自然饱和/饱和度 → 黑白 → 5 层风格 LUT → 肤色保护 → 线性输出。中性参数直接返回输入;各章节和单项旁路保留。调色核只包含颜色处理;所需第三方许可随项目资源保留。
CPU 和 Metal 共用 `DYUniforms.h`。大小 944 字节、16 字节对齐,102 个字段逐一检查偏移。普通调整中性为 0;色阶 white 为 255、gamma 为 1;黑白模式默认关闭;额外曲线点的 X 小于 0 表示该点不存在。白平衡、8 色 HSL 和分级由 CPU 生成 3D LUT,不能拿 identity 占位声称完成这些功能。
@@ -25,19 +25,19 @@ fragment buffer0 为 `DYUniforms`,buffer1 为 `float sceneLevel`,buffer2 必
`dyPreview` 为每实例缩略采样核:texture0 straight linear source、buffer0 写 `float4[4096]`;调度64×64,每格按归一化中心采样,RGB使用标准sRGB分段编码,alpha原样保留。不夹断HDR或负值;CPU用途自行决定显示、统计的有效范围。
`dyAnalysis` 使用相同契约,尺寸为320×180、buffer0写`float4[57600]`,匹配自动调色参考算法的分析分辨率。自动调色将样本量化至UInt8域再计算分位数和灰样本权重;Metal双线性采样与NSImage/CoreGraphics重采样不声称逐字节相同。
`dyAnalysis` 使用相同契约,尺寸为320×180、buffer0写`float4[57600]`,用于当前自动调色算法的分析分辨率。自动调色将样本量化至UInt8域再计算分位数和灰样本权重;Metal双线性采样与NSImage/CoreGraphics重采样不声称逐字节相同。
局部滤镜最大采样半径 18×1.7=30.6 像素;tile 请求至少 32 像素 halo,并设置正确的 UV。自适应白场必须采用全帧统计;不能逐 tile 算独立白场。
`dyWhitesSceneStatistics` 绑定 texture0 source、texture1 白平衡 LUT、buffer0 uniforms、buffer1 写 float。必须只调度 1 个 threadgroup、每组 256 个线程。固定取 256×256 均匀网格,跳过 alpha<=0;统计 96%–99.5% 亮度区间,结果钳制 0.35–1。此路径按参考行为不执行输入 LUT/三原色矩阵。
`dyWhitesSceneStatistics` 绑定 texture0 source、texture1 白平衡 LUT、buffer0 uniforms、buffer1 写 float。必须只调度 1 个 threadgroup、每组 256 个线程。固定取 256×256 均匀网格,跳过 alpha<=0;统计 96%–99.5% 亮度区间,结果钳制 0.35–1。此路径不执行输入 LUT/三原色矩阵。
`dyLUTExportKernel` 绑定 texture0–8 为上表 1–9;buffer0 uniforms、buffer1 写 float RGB、buffer2 uint cubeSize;调度 cubeSize³ 个线性线程。输出 red-fastest RGB triples(每格3个float)。空间纹理/清晰度无法写进 3D LUT,参考导出路径本身也省略这些操作。自适应白场按导出核既定逻辑处理,不能把导出 LUT 等同于任意画面渲染。
`dyLUTExportKernel` 绑定 texture0–8 为上表 1–9;buffer0 uniforms、buffer1 写 float RGB、buffer2 uint cubeSize;调度 cubeSize³ 个线性线程。输出 red-fastest RGB triples(每格3个float)。空间纹理/清晰度无法写进 3D LUT,导出路径省略这些操作。自适应白场按导出核既定逻辑处理,不能把导出 LUT 等同于任意画面渲染。
GPU 检查只运行命令行,不启动测试 App:
```sh
xcrun clang++ -std=c++17 -fobjc-arc -framework Foundation -framework Metal tools/verify_gpu.mm -o /absolute/cache/verify_gpu
/absolute/cache/verify_gpu /absolute/default.metallib verification/GPU.json
/absolute/cache/verify_gpu /absolute/default.metallib /absolute/report.json /absolute/reference.metallib
```
验证工具只读加载安装的原厂着色器作为独立数学对照,不把其库放进交付物。测试状态、设备、哈希、最大误差和未覆盖范围保存在报告中。原 GPU 的 half 输入/输出在此保留,不能将报告解释为原生 32 位 HDR 精度或宿主导出验收。
验证工具通过第三个参数显式指定数值对照库,只读加载;对照库不纳入交付物。其输入摘要与历史来源记录见 `PROVENANCE.json`,Color Finale 相关研究及当前实现的来源区分见 `research/ALGORITHM_SOURCES.md`。测试状态、设备、哈希、最大误差和未覆盖范围保存在报告中。GPU 的 half 输入/输出在此保留,不能将报告解释为原生 32 位 HDR 精度或宿主导出验收。