feat: complete FxPlug integration, input-aware auto grade and FCP wrapper

这个提交包含在:
mac 于 2026-10-31 01:24:07 +08:00 提交
1 父节点 2f11e8bd0f
当前提交 2330eb737e
36 个文件已更改
+4320 -131

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

+97
查看文件
@@ -0,0 +1,97 @@
# 颜色查表与接入核验
本记录区分发布二进制静态证据、公开源码和本项目的实现验证。没有将静态调用关系当作实际宿主运行结果。
## 参考身份
- LumiGrade 3.0,构建 56。
- 参考服务:`/Library/Plug-Ins/FxPlug/LumiGrade.app/Contents/PlugIns/LumiGrade XPC Service.pluginkit/Contents/MacOS/LumiGrade XPC Service`。
- 原始 universal Mach-O SHA-256:`33c273d6a58314f5068959fcda911d741884a1937077b41a969a990dd40d0b6d`。
- 只读抽取 arm64 SHA-256:`c04e911e449e888eb0d8c10f7bcf2b6bc2c4153b9ba86c1952ddf210c96c5e97`。
- 本记录的地址属于该 arm64 slice,image base 为 `0x100000000`。使用现有 `otool -arch arm64 -tvV` 输出核对具体 ARM 指令,不需要重新打开 REA 会话。
- REA/Ghidra 提供的相关函数伪代码属于还原结果,不是原始 Swift 源码。关键结论同时以 ARM 调用或资源字节校验确认。
## MIT 查表数据
参考包的 `THIRD-PARTY-NOTICES.txt` 声明,Camera Raw 查表数据与组合行为来自 [Compositor](https://github.com/robbietilton/Compositor),MIT,Copyright 2026 Wonder Assembly LLC。
核对公开源提交 `92f5225afe7e921dbfa4c563462980e45db345fc` 的 `Compositor/Resources/CameraRawTables.bin`,与参考包文件逐字节相同。项目中的 `DayuColorTables.bin` 保存这份必要数学数据,保留 MIT 许可;没有复制参考应用的图标、品牌、授权代码或原始应用程序。
数据 SHA-256:`e67ff4dbcce35cb7765752acff4405be5c934d913ef1396b2ca3fc6dc8a85190`。
格式经公开 `Compositor/Document/CameraRawTables.swift` 和参考 `loadSourceTables` / `sample` 核对:
- `CRT3` 头;维度 17,763 张表,差值量化步长 3。
- 10 字节头之后为 LZMA/xz;解压长度 11,245,857 字节。
- 每张表逐通道保存 running delta,累计值按有符号 Int8 解释;还原到 `round(axis * 255 / 16) + signedDelta * 3` 并钳制 0–255。原 ARM `0x10009bf28` 的 `frinta` 确认这里要四舍五入,不能直接截断。
- 源表顺序为红轴最慢、蓝轴最快;每格 RGB8。读取采用 17³ 三线性插值。
- 组合结果为 33³ RGBA32Float,Metal 纹理红轴最快,alpha 固定 1。
- 白平衡:温度、色调各 -100…100、间隔 25,四张相邻表双线性混合。
- 8 色 HSL:明亮度、饱和度、色相依次组合;表起点 `285 + (kind * 8 + color) * 5`,每项 -100…100、间隔 50。逐项运算保留 `low + (high - low) * fraction`。
- 分级:先阴影、中间调、高光、全局的明度,再全局、中间调、高光、阴影色轮;色轮在相邻色相、饱和度、混合档位间混合。分级 balance 对阴影、高光饱和度份额的系数按公开源及二进制一致恢复。
## 已确认的字段与旁路依赖
944 字节 CPU/GPU ABI 的每字段偏移有 `DYUniforms.h` 的静态断言。
### 白平衡
原 fragment 无条件读取已生成的白平衡 3D 纹理,因此组旁路必须在 CPU 构造纹理时落实。
原渲染器 `0x100077054…0x10007708c`:
1. 从 uniforms `+104/+108` 读取 temperatureEnabled/tintEnabled,分别决定是否使用对应数值。
2. 从 uniforms `+140` 读取 colorSectionEnabled,作为 `whiteBalanceTexture(... enabled:)` 的 enabled 参数。
3. `0x10007708c` 调用白平衡纹理生成方法;未启用时采用中性 LUT。
`DYColorTables` 已按此处理。为使自定义检查器的组旁路与实际字段含义一致,本项目把白平衡与鲜艳度、饱和度放在“白平衡与颜色”组;这是明确的界面分组适配。
HSL 与颜色分级分别以 `hslSectionEnabled`、`colorGradingSectionEnabled` 生成有效或中性纹理,旁路不能复用此前非中性的缓存结果。
纹理、清晰度、去朦胧由原 fragment 的 `baseSectionEnabled` 分支控制,属于基础组。肤色保护 shader 只检查 `skinProtection.x`,应保持独立开关,不能暗示它自动跟随颜色组。
### 肤色保护
原 `applySkinProtection`:
- `.x`:开关,阈值 0.5。
- `.y`:保护程度,乘 0.01 后钳制到 0–1。
- `.z`:中心色相,除以 360 后与像素 HSL 色相做圆周距离计算。
原 `addParameters` 对参数 `0x468` 设置默认 60、范围 0–100;对 `0x469` 设置默认 28、范围 0–60。两项不是色相范围和饱和度范围。对应静态伪代码在 `addParameters.c:504…510`,数值十六进制为 `0x404e000000000000`、`0x403c000000000000`。
### 黑白混色
原 `addParameters` 从 `DAT_1000dc7e8` 读取黑白参数默认值。该 slice 对应文件偏移的 8 个 double 是:
`40, 60, 40, 60, 20, 80, 0, 0`
依次对应红、黄、绿、青、蓝、洋红,以及着色色相、着色饱和度。原 `applyBlackWhite` 直接读取这些六色系数参与灰度计算;六项设成 100 会改变启用黑白后的明度。
### 分级与三原色
- `colorGradingHueSatA.xy` 为中间调 H/S,`.zw` 为阴影 H/S;`HueSatB.xy` 为高光 H/S。
- `colorGradingLuma` 为中间调、阴影、高光明度;`colorGradingGlobal` 为全局 H/S/L。原包装方法 `0x100083320…0x1000833e8` 的向量重排确认此顺序。
- 三原色矩阵是列向量。GPU 将 `r*M0 + g*M1 + b*M2` 相加,无需转置。
- 色相沿灰轴旋转,幅度为 `hue / 100 * 0.5235987305641174`;饱和度沿对应原色相对中性灰的轴变化,系数 `sat / 100 * 0.55`。矩阵保持 D65 白点,并沿用原版过大矩阵偏移的限制。
## 自动调色预览确实应用输入 LUT
这是已确认的静态调用与数学流程,不再只是从函数名称作推测:
1. `capturePreviewFrameIfNeeded` 位于 `0x1000833ec`。它缓存原始预览图,并保存输入 LUT、路径、强度;LUT 路径或强度改变时更新版本、清除已转换缓存。此方法本身没有直接转换图像。
2. `currentPreviewFrame` 位于 `0x10007f4f4`。缓存不命中且有输入 LUT 时,`0x10007f5ec` 明确调用 `imageByApplyingInputLUT(to:lut:strength:)`;`s0` 在前一条指令从保存的强度装入。
3. 自动调色闭包 `0x100075e00` 在 `0x100075e44` 调用 `currentPreviewFrame`,在 `0x100075e54` 把该结果传给 `autoGradeResult`。
4. `imageByApplyingInputLUT` 位于 `0x100090a34`。`0x100090a68/6c` 指定 320×180 的 RGB8 缓冲;`0x100090aec…0x100090b0c` 将 RGB8 除以 255;`0x100090b40` 调用 `CubeLUT.sample`;`0x100090b48…0x100090b50` 计算 `original + (sample - original) * strength`;`0x100090b78` 起钳制、四舍五入回 RGB8。
因此,本项目的自动调色输入应在标准线性→sRGB 编码之后应用输入 LUT 与强度,再进入统计。使用未转换的 Log 原图统计会偏离参考行为。GPU 缩略采样与原版 NSImage/CoreGraphics 320×180 重采样仍可能有量化或重采样差异,不声明逐字节相同。
## LUT 导出与验证边界
原 `lutExportKernel` 输出 `cubeSize³ * 3` 个 float,红轴最快;texture0–8 为输入 LUT、五层风格 LUT、HSL、白平衡、分级,buffer0 uniforms、buffer1 RGB 输出、buffer2 cubeSize。当前接入按此布局,不能按 float4 分配后误读。
导出核接收、输出的是 LUT 的编码域 RGB,空间纹理和清晰度操作不写入 3D LUT。画面相关统计与导出核固定处理也不等同于任意素材的逐帧渲染。
`tools/verify_color_tables.mm` 已通过严格 `-Wall -Wextra -Werror` 编译。验证覆盖数据 SHA、损坏拒绝、独立 double 三线性对照、四表白平衡、纹理轴顺序、24 项 HSL 端点、4 色轮、色相环绕、4 明度端点、6 个三原色控制及 D65 保持。带资源的 CLI 测试 bundle 另验证真实 Metal 纹理接口与非中性缓存后的 WB/HSL/分级旁路;没有运行未公证 GUI 应用。
宿主的半透明表示、图像原点、色彩空间和最终视觉结果仍须用正式安装的已公证版本验收;数学和静态结构验证不能替代宿主验证。