文件
dayu-color/自定控件开发交接.md
T

23 KiB
原始文件 Blame 文件历史

大鱼调色自定控件开发交接

更新日期:2026-11-05,Asia/Shanghai。

本轮 1.11.0(73)交付状态

本轮已实现曲线直方图、HSL八色三轴、蜘蛛网格的半透明画布编辑;主检查器默认只显示一级、蜘蛛、基础、HSL四张折叠卡,其它模块由添加菜单或画布入口显示。已有非默认调色和蒙版自动保留为可见模块。全部还原也恢复四卡折叠布局。

肤色保护增加默认开启的人脸限定和“显示肤色保护区域”,使用当前帧 Vision revision3/76点、人脸轮廓、额头及五官排除,并与原色选及用户蒙版相乘;灰度显示实际保护权重。无脸与失败帧为空,不沿用上一镜头。基础与UUID独立层均支持。参考FCP-BeautyGirl的思路与MIT许可见research/FCPBeautyGirl-MIT.txt。

新增“镜头畸变修复”工具,支持正反径向校正、缩放与光学中心,接入独立层、蒙版、预设和撤销。其采样由本项目独立编写,尚无目标GPU逐像素等价证明。人脸选区和镜头修复不能导出到静态Cube,完整预设可保存。

APP正式编译SHA 49d35cb49ab93f5ab6ca3411eaea80f7219be346,Apple公证 348c6e9b-f5d9-4661-bc7f-f192fa770ecf Accepted,票据/Gatekeeper/唯一位置安装及724项正式安装自检通过。用户已实鼠确认画布/肤色/畸变“三项均正常”,详见verification/HostCanvasTools1.11.0.json。交付脚本已完成,Delivery为 verified;旧版恢复APP已清理,交付锁已释放。PKG容器签名、公证Accepted、票据及20项展开验包通过,保存在上级发行包目录,见verification/Package.json。Release最终发布及下载核验见verification/Release.json。

FCP 12.4已成功导入三个验收项目,无导入错误;实际主检查器四张折叠卡与图像已观察到,服务进程使用正式安装路径。事件“大鱼调色_1.11.0_73_画布与空间工具”。工具 tools/create_canvas_host_fixture.py 可重建FCPXML、两项测试预设与网格;真人fixture随源码保存于tools/fixtures,仅用于验收。静态DTD/素材检查通过不等于鼠标功能验收。

新增代码入口:DYFaceRender.inc.h(Vision与镜头渲染),DYCanvasToolsDiagnostics.inc.h(新增29项回归),DYToolGPU.h(人脸覆盖元数据),DYGrade.metal及tools/build_masked_kernel.py(实际肤色选区输出)。旧Uniform完整1312字节前缀不变,仅追加32字节;旧参数ID和预设v7不变。蜘蛛写入使用DYViewerParameterBridge的beginSpider/changeSpider,必须保持冲突检查和一次撤销。

AddressSanitizer完整724项无内存错误,插桩下唯一旧性能阈值失败;正常Release全部通过。修复旧渲染C++引用捕获向异步通知泄漏self栈地址的问题,通知必须通过独立Objective-C方法调度,避免恢复旧写法。

源码和阶段记录已持续推送;实际编译SHA从远端独立恢复549个文件逐字节一致、full/strict fsck及模板合同验证通过。最新明细见research/CanvasTools-20261105.md及verification/CanvasSourceRecovery1.11.0.json。旧1.10.0 Release387草稿不属于本轮新发行,保持原状。

以下为1.10.0基线交接

更新日期:2026-11-04,Asia/Shanghai。下一阶段继续完善「大鱼调色」的画布自定控件与画布外辅助工作区。当前正式版本为 1.10.0(72),曲线拖点与一次撤销、LUT 预览、示波器随播放头更新已由用户实鼠确认。后续可以在这个版本上继续开发。

当前十四个工具都有画布入口,专用图形编辑已覆盖曲线和颜色分级;其它工具主要通过通用参数面板调整。下一阶段的具体控件样式和功能范围尚未确定,下文将现有能力、实现约定与建议顺序分别说明。本次交接只新增文档,不修改插件功能、版本或线上文章。

工程与版本基线

项目 当前记录
工程根目录 /Volumes/备份/大鱼调色/大鱼调色,不是上一级同名目录
工程与方案 大鱼调色.xcodeproj,Wrapper Application,Release
技术 AppKit、Objective-C++、FxPlug 4、Metal;现有工程不以 SwiftUI 实现控件
仓库 https://dayu.media/git/dayu/dayu-color.git,分支 main;保持已有仓库可见性
交接前 main 302b75710b24c52e7c535faa1a5cf92790359272;交接文档另作后续提交
正式 APP 实际编译源码 80dec904bedf5f704b29d16325fa95d639f3a250;后续提交为文档、验证和发布记录
版本标签 v1.10.0-canvas-workspace-20261104 → c0e6f3be0afc310125d2d045a96655db7524f24b,已推送并独立恢复核验
唯一正式安装 /Library/Plug-Ins/FxPlug/大鱼调色.app,1.10.0(72)
产品身份 主 Bundle ID com.dayu.color;内嵌服务 com.dayu.color.XPC
固定构建缓存 /Users/mac/Library/Caches/CodexBuilds/com.dayu.color,其中 DerivedData 用于 Release 构建
产品交付锁 /Users/mac/.codex/app-delivery-locks/com.dayu.color.lock;本次交接读取时未占用
构建与宿主基线 Xcode 27.1、FxPlug SDK 4.3.5;Apple Silicon、macOS 14.6+;已验收宿主 FCP 12.4

接手时先盘点工作区、分支、远程引用和产品锁,再修改明确属于本任务的文件。保留完整 Git 历史和既有标签;不要在源码提交中保存密码、令牌或签名私钥。

用户已经明确的交互方向

  • 画布侧边使用纵向工具排列,工具入口需要直接可见。
  • 曲线等图形控件可以叠在画面上,调整应直接作用于画布里的控件。
  • 工具面板能够拖动位置;可同时打开多个不同工具,保留现有检查器作为参数入口。
  • 画布外需要独立组件承载示波器、LUT 预览等,可参考 Color Finale 的内外分工。
  • 保留现有浅色、深色两种模式。界面主题、面板位置等显示状态与调色数据分开。
  • mFilmLook 和 Color Finale 作为交互参考;产品中的控件由本项目独立实现。

此前“只有一个基础调色”“整个面板不能拖动”对应 69 及更早阶段。70 已加入面板移动与十四工具切换,用户确认正常;随后根据新要求发展为 72 的纵向工具条和独立工作区。继续开发应以 72 为起点。历史过程见屏幕控件研究与工作区实现说明。

当前控件的实际能力

区域 已有能力 继续开发时需要知道的边界
纵向工具条 一级、蜘蛛、基础、肤色、LUT、HSL、曲线、分级、原色、色阶、黑白、平衡、通道、胶片;小画布分页;工作区入口和收起面板 工具条锚定图像可见区域左侧;同一工具按钮再次点击会关闭并移除其面板
浮动面板 标题点击折叠、拖动移动、关闭、置顶;同类图层选择;参数分页 每个工具类型最多一个浮动面板;同类独立层通过图层菜单切换。位置只存在于当前面板对象,未实现关闭重建或重启后恢复布局
曲线 RGB/红/绿/蓝切换,选点、加点、拖点、删除点,图形和参数页切换 使用已有有限参数槽,不是无限点曲线;固定端点另行绘制
颜色分级 阴影、中间调、高光、全局四个色轮;图形和参数页切换 画布色轮直接修改色相与饱和度,其它分级参数继续使用参数页
通用参数 已公开参数的滑杆、开关、循环选项、单项复位和数值显示 当前画布数值显示不是完整文本输入框;选项主要通过点击循环。并未自动覆盖检查器里的资产选择、蜘蛛网格等全部自定义操作
画布外工作区 FxRemoteWindow 宿主窗口,亮度波形、RGB 分列、直方图,风格1 LUT 浏览与真实帧预览 LUT 页目标为当前 manager 对应的 look0,即风格1;不是任意 LUT 槽或任意浮动面板图层选择器

十四工具类型顺序来自 DYToolTypes():primary, spider, base, skin, look, hsl, curve, grading, primaries, levels, blackwhite, balance, mixer, film。工具条名称与类型顺序需要同步维护。

代码入口

下表文件均在本工程内。多数 *.inc.h 是在 .mm 中展开的实现片段,不能当作独立编译单元重复加入目标。

要完善的部分 文件 主要入口
FxPlug 画布坐标、绘制、命中及输入路由 DYToolOSC.inc.h DYToolOSC,drawOSC、partAtPoint:、鼠标回调;同时保留原蒙版与钢笔路由
纵向工具条、面板开关、置顶与捕获 DYViewerControls.inc.h prepareWithSize:scale:atTime:、activateTool:、event:point:atTime:
浮动面板布局、图层目录、滑杆和标题拖动 DYViewerParameterPanel.inc.h prepareWithSize:、clickArea:、movePanelToPointer:、finishCapture
曲线与四个色轮的图形交互 DYViewerGraphics.inc.h curveSlots、layoutGraphicAt:、drawGraphic:、beginGraphicAt:、updateGraphicAt:
快照、主队列写回、撤销与冲突保护 DYViewerParameterBridge.inc.h publishUniforms:、snapshotAtTime:、beginParameters:、changeValues:、endGesture、invalidate
插件发布快照及采集最终输出 DYPlugIn.mm pluginState:atTime: 发布 uniforms/工具文档;成功渲染后调用 captureScopeTile:atTime:
OSC 与插件实例绑定 DYToolHostMethods.inc.h initializeToolHost、tearDownToolHost、scheduleToolCanvasRegistration、viewerParameterBridge
检查器、工作区按钮及现有原生图形控件 DYInspector.mm openWorkspace:;DYCurvePanel、DYColorWheel、DYWheelPanel;原图形手势接口
蜘蛛盘的现有原生实现 DYSpiderDisc.inc.h DYSpiderPanel;网格状态另见 DYSpiderState.h 与 SpiderCore/
画布外窗口和 LUT 应用 DYColorWorkspace.mm showRelativeToView:、layoutWorkspace、pageChanged:、selectionContextAtTime:、selectLUT:、commitLUT:expected:error:、close
示波器采样与异步统计 DYScopeCapture.inc.h setScopeEnabled:、captureScopeTile:atTime:、processPendingScopeSamples;统计和 GPU 采样见 DYScopeMath.hpp、DYScopeSample.mm
参数定义与独立图层 DYModel.mm、DYToolState.mm DYDescriptors()、DYSections()、DYToolTypes()、DYToolDisplayOrder()、DYToolManager
深浅模式与控件表面绘制 DYTheme.mm DYThemeColor、DYDrawThemeSurface、DYDrawSoftControl;尽量复用现有主题能力

画布侧基本链路为:宿主 OSC 输入 → DYToolOSC → DYViewerControls → 对应 DYViewerParameterPanel/图形方法 → DYViewerParameterBridge → 主队列宿主 action → 原参数或稳定 UUID 对应的 DYToolManager。渲染状态再通过快照回到面板。外部工作区通过绑定 manager 的通知打开,由检查器管理生命周期。

新控件必须保留的交互约定

坐标与命中。 布局以真实 OBJECT→CANVAS 图像矩形和画布的交集为准。绘制、命中、拖动应共用几何数据;控件在宿主黑边能画出来不代表能接收鼠标。工具条绘制与命中优先,面板逆序命中,按下面板后置顶。原有蒙版和钢笔仍从同一 OSC 根路由。

捕获与释放。 按下记录目标、时间、起点和原值;超过 2 × scale 的位移后进入拖动。滑杆或图形捕获后,移出轨道继续处理,松开补算最终位置并结束手势。普通按钮在原命中区释放才触发;拖标题后松开不能再折叠面板。mouseExited 清悬停,不直接中止仍捕获的拖动。

线程与快照。 OSC 回调读取当前帧的不可变快照,不同步等待主队列,也不直接改宿主模型。snapshotAtTime: 只返回同一时间的快照;缺帧时保留原 UUID 选择并暂缓编辑。主队列写入前复核当前时间、目标节点、原值和关联开关;发现外部修改或目标消失时结束手势,保留最新外部设置。

多字段写入与撤销。 曲线 X/Y、色轮 H/S 通过 beginParameters: 和完整 changeValues: 成组提交,放在同一次宿主 action 内;一次手势只打开一个撤销组。不要拆成两个单字段手势。宿主拒绝写入时尝试还原受影响字段并结束该组;宿主 API 没有 abortAction。单击开关、复位和删除点也需完整收尾。空闲面板不能结束另一面板的共享写入手势。

参数与显示状态。 面板移动、开合、置顶、分页、通道切换只改变显示状态,不写调色参数、不制造撤销项。基础层使用 base:<type>;独立层使用真实 UUID,不能按面板下标或当前列表序号写参数。保留参数 ID、uniform 布局、预设 v7、CMS nil/v2/v3 的既有兼容约定;本轮图形扩展优先连接现有数据。

生命周期。 播放头变化、插件或面板销毁、manager 失效时必须结束捕获并关闭撤销组。异步操作使用序号/会话校验,关闭窗口后不得继续提交。项目使用手动内存管理,新增 retain/release 和异步 block 时沿用现有生命周期处理。

曲线和色轮的参数映射

曲线显示输出值为 output = x + curveY × 0.01;拖点写回 curveY = (output - x) × 100。curveY 保存的是相对对角线偏移,不能直接填绝对输出值。RGB 主曲线为4个基础槽加4个额外槽,单色通道为2个基础槽加4个额外槽;x < 0 表示未启用槽,删除点写 x = -1, y = 0。绘制使用与现有编辑器一致的单调 Hermite 插值和固定首尾端点。

色轮使用 grade{i}_0 表示角度制色相、grade{i}_1 表示0–100饱和度,i = 0..3 分别为阴影、中间调、高光、全局。画布坐标 Y 轴与色轮数学坐标方向相反,新增圆盘控件时需要同时核对绘制和输入变换。

蜘蛛网格属于自定义资产/图层数据,不能直接套用当前 float 描述符桥接。若将蜘蛛盘搬入画布,应先明确基础层 DYAssetState.spiderMesh 与独立层 spider 数据的目标路由,再扩展安全写入通道、冲突检测和一次撤销。

外部工作区的约定

工作区由 FxRemoteWindow 托管并绑定当前插件实例;DYColorWorkspaceRequested 通知的 object 是对应 manager。LUT 异步准备完成后检查播放头、原风格1选择、全局颜色管理及目标图层是否仍有效,且在 DYToolManager 结束 action 后回读真实保存结果。关闭窗口要取消准备并关闭示波器采样。

工作区示波器采样当前效果的处理输出,不含后续其它效果或宿主显示转换。320×180 采样在已知 ICC 配置下转扩展 sRGB;空间未知时明确显示宿主 RGB 原值参考。波形、RGB 分列、直方图属于显示参考,不替代 HDR/IRE 精密测量。宿主仅提供分块时须保留分块标注。

DYScopeCapture.inc.h 与原 _renderer histogram 分开:后者属于较早的分析/曲线参考缓存,不能直接拿来充当最终输出示波器。宿主输出纹理可能在 render 返回后被复用,因此小幅 GPU 读回在其所有权仍有效时完成;CPU 颜色转换和统计放在后台队列,待处理帧合并为最新帧。

71 曾出现绘图区越界覆盖工作区顶栏,72 已加入根视图、面板裁剪和顶栏位图回归。修改工作区布局时保留这些检查,特别核对窗口缩放和大片 dirty rect 重绘。

建议的后续开发顺序

以下是接手建议,具体工具及样式以用户下一次要求为准。

  1. 先确定要完善的一个工具,检查其在原检查器里的现有实现与数据结构。蜘蛛盘、HSL 等尚无专用画布图形,可作为后续候选;不要把十四个入口当作十四套图形控件均已完成。
  2. 在现有画布框架内实现该工具的布局、绘制和命中。保留通用参数页作为精确参数入口;若新增数值输入、菜单、键盘或修饰键操作,补齐焦点、宿主快捷键和钢笔工具之间的路由约定。
  3. 连接真实参数或自定义资产,覆盖基础层与独立 UUID 层,验证一次撤销/重做和检查器同步。需要修改多项数据时成组提交。
  4. 再完善多面板布局、面板位置恢复或同类多图层同时显示。这些会改变当前“一类型一面板”的行为,需独立设计;纯显示布局不要进入调色预设和撤销历史。
  5. 逐项检查浅深两种模式、窄画布、不同缩放、面板重叠与外窗按钮可读性。现有三项功能验收不能覆盖所有新增交互或后续视觉修改。

验证与正式交付

已通过的基线包括:正式安装版695项原生检查;用户实鼠的曲线拖点与一次撤销、风格1 LUT 真实预览、移动播放头后示波器更新。用户原话为“三项都正常”,见宿主验收。原生检查使用真实 Metal/IOSurface 和模拟 FxPlug 宿主选择器,不能代替真实 FCP 文档操作。

新增图形控件的原生回归主要放在 DYViewerControlsDiagnostics.inc.h;参数批量写入和冲突保护放在 DYViewerParameterDiagnostics.inc.h;外窗、LUT 提交与越界重绘见 DYWorkspaceDiagnostics.inc.h。这些检查由 DYDiagnostics.mm 集成,测试辅助协议见对应 Probe 文件。

需要重跑正式安装自检时,入口为:

'/Library/Plug-Ins/FxPlug/大鱼调色.app/Contents/PlugIns/大鱼调色 XPC Service.pluginkit/Contents/MacOS/大鱼调色 XPC Service' --self-test

功能改动后的交付流程沿用 tools/deliver.py:先保存并正常退出宿主,Release 构建、正式签名、公证 Accepted、票据验证,再替换唯一正式位置并运行正式安装自检,最后进入宿主验收。脚本会在正式安装后等待 complete 或 leave;只有真实验收通过才输入 complete,否则保留诊断和恢复状态。最终还需核验 PluginKit/实际宿主进程路径并清理本任务生成的多余 APP、提交 ZIP 和旧版恢复副本,不能仅凭脚本退出宣称交付完成。

新增控件至少实测:拖动与释放位置、移出控件继续捕获、一次撤销及重做、独立层目标、切换片段/播放头、拖动期间外部改值、面板开合与位置变化、工程重开、深浅模式和缩放。已有缺陷对应的回归按改动范围运行,不为纯文档修改重复构建或验收插件。

代码修改分阶段用 tools/checkpoint.py 对明确文件提交、推送并核验远程;脚本自带仓库锁,不要套同一把锁造成死锁。完整恢复、签名与打包约定见恢复说明。

已完成的发布与遗留事项

  • 正式 APP 和 PKG 均已签名、公证、粘附票据并验证。PKG 位于 /Volumes/备份/大鱼调色/发行包/大鱼调色-1.10.0.pkg,43,090,565字节,SHA-256 ee70461c9b2d2e0ddd78cbcb3371c3b1b36b7f0e5fc69bfccc7ac0f1a3e468d8。PKG 通过20项展开验包,本轮未重复运行系统安装脚本。详情见 Package.json。
  • 资源文章15792已更新为“1.10.0 紧急 UI 更新”,使用新封面和用户提供的深色、浅色两张原始截图,主下载同步新版。50元、有效会员免费及其他商业设置保留。文章图片、SEO及安装包完整下载已验证,见 Article1.10.0.json。发布素材在 /Volumes/备份/大鱼调色/大鱼调色/Publishing/1.10.0/。
  • Git Release387/附件31仍为草稿,未发布。 安装包已上传,但草稿下载需要已登录浏览器;上一会话的电脑操作工具因当前浏览器页面 URL 访问限制终止。尚未取得该 Release 附件的完整下载证明,不可把网站文章的包下载证明替代它。后续恢复正常访问后,复用既有草稿与附件,完整下载核对上述大小和哈希,再由 Packaging/publish_beta.py --verified-download 完成发布与发布后再次下载核验。不要重复上传、删除旧附件或移动现有标签。当前记录见 Release.json 与 CMSReleaseDraft.json。
  • 任务生成的70/71旧安装恢复APP、缓存生成APP、公证ZIP、验证下载副本和源码恢复 checkout 已按记录清理。源码、用户工程/QA媒体及历史发行包保留,见 清理记录。未修改 NAS 后端源码或网站自动更新清单。

给下一会话的接续说明

继续完善大鱼调色的画布自定控件。先读取本文件,再读取工作区研究与对应源码。基于 main 和已验收的正式1.10.0(72),保留纵向工具条、多个可拖动面板、画布内曲线/色轮及画布外示波器/LUT工作区。按用户指定工具继续补齐交互,保留参数、独立图层UUID、一次手势一次撤销和主队列安全写入。已有三项实鼠验收通过,不用退回69或70阶段。新功能仍按正式Release签名、公证、唯一安装、宿主验收、源码推送和安装包Release规则交付。上一版Release草稿的下载核验阻塞另有记录,不要宣称已发布。