Lunar 5.3.1 深度解析：Color Gain 范围扩展、唤醒重应用控制与颜色保真修复

本文以 ReleaseNotes/5.3.1.md 为核心，结合 Lunar 仓库中 Lunar/Data/Display.swift、Lunar/DDC/DDC.swift 等源码实现，深入解读 5.3.1 版本在 Color Gain（色彩增益）管理上的三项重要更新：为 Wacom Cintiq Pro 等专业显示器扩展 Color Gain 调节范围、新增"唤醒时重新应用"开关，以及修复因显示器端与 Lunar 存储值不一致导致画面发白（washed out）的问题。读者读完可掌握 Color Gain 的底层 DDC 实现原理、新版本各项开关的实际作用，以及如何在源码层面验证这些行为。

一、5.3.1 版本更新概览

Lunar 5.3.1 是一个以 Color Gain 管理完善 与 稳定性修复 为核心的迭代版本，官方发布说明（ReleaseNotes/5.3.1.md）共包含三大改进与一项关键修复：

• 改进 1：为 Wacom Cintiq Pro 这类专业显示器提供 Color Gain 范围扩展能力；
• 改进 2：新增**禁用"唤醒时重新应用（re-apply on wake）"**的选项，用于控制 Color Gain；
• 改进 3：对依赖组件进行安全更新；
• 修复：解决显示器端 Color Gain 实际值与 Lunar 内部存储值不一致，导致**画面颜色被冲淡（washed out）**的问题。

下面逐项深入，并结合源码说明其实现细节。

二、认识 Color Gain：从 DDC 协议到 Lunar 的存储模型

2.1 什么是 Color Gain

Color Gain（色彩增益）对应显示器 OSD 菜单中常见的 RGB 增益（Gain）调节，它直接控制显示器背光/面板在红、绿、蓝三个通道上的信号放大强度。增益过高会让画面发亮偏白，过低则会偏暗偏色。在 DDC/CI 协议中，增益属于显示器端持久化的颜色设置（Lunar 界面中的原文描述为 "Persistent color settings that affect the LED backlight of the monitor"，见 Lunar/Base.lproj/Main.storyboard），它和亮度、对比度一样，可以通过标准 DDC 命令读写。

2.2 底层的 DDC VCP 代码

在 Lunar/DDC/DDC.swift 的 ControlID 枚举中，三个通道的增益对应标准的 VCP（Virtual Control Panel）代码：

通道	ControlID 枚举	VCP 代码（十六进制）
Red Gain	RED_GAIN	0x16
Green Gain	GREEN_GAIN	0x18
Blue Gain	BLUE_GAIN	0x1A

DDC 层提供了完整的读写封装（Lunar/DDC/DDC.swift 与 Lunar/DDC/DDC.swift）：

static func setRedGain(for displayID: CGDirectDisplayID, redGain: UInt16) -> Bool {
    write(displayID: displayID, controlID: ControlID.RED_GAIN, newValue: redGain)
}
static func getRedGain(for displayID: CGDirectDisplayID) -> UInt16? {
    DDC.getValue(for: displayID, controlID: ControlID.RED_GAIN)
}

getGreenGain / getBlueGain 与 setGreenGain / setBlueGain 结构一致，分别操作 0x18 与 0x1A。

2.3 Control 抽象层：多种后端统一接口

在抽象层 Lunar/Control/Control.swift 中，Control 协议为每个通道定义了 getXxxGain() / setXxxGain(_:) 接口。不同控制后端提供不同实现：

• AppleNativeControl（原生 macOS 控制，主要面向 Apple 内置屏幕）：在 Lunar/Control/AppleNativeControl.swift 中，将调用转发给底层 CoreGraphics 的 control.setRedGain(...) 等原生接口；
• DDCCTLControl（面向外接显示器）：在 Lunar/Control/DDCCTLControl.swift 中，通过 ddcctlSet(.RED_GAIN, value: gain) 写入 DDC，读取方向则返回 nil（部分显示器不支持回读，见 Lunar/Control/DDCCTLControl.swift）。

2.4 Lunar 端的存储模型

在 Lunar/Data/Display.swift 中，每个显示器对象维护三个 @Published @objc dynamic 属性 redGain、greenGain、blueGain，默认值为 DEFAULT_COLOR_GAIN = 50（Lunar/Data/Display.swift）。其 didSet 观察器在值变化时立即 save() 持久化，并通过当前 control 后端将新值写入显示器（Lunar/Data/Display.swift）：

@Published @objc dynamic var redGain: NSNumber = DEFAULT_COLOR_GAIN.ns {
    didSet {
        save()
        guard DDC.apply else { return }
        if let control, !control.setRedGain(redGain.uint16Value) {
            log.warning("Error writing RedGain using \(control.str)", context: context)
        }
    }
}

编码/解码时这三个属性通过 redGain / greenGain / blueGain 键持久化到本地设置（Lunar/Data/Display.swift 与 Lunar/Data/Display.swift），因此每个显示器各自的增益值会被独立记住。

三、新特性一：为专业显示器扩展 Color Gain 范围

3.1 为什么需要范围扩展

大多数普通显示器 OSD 的 RGB Gain 取值范围是 0–100，但部分专业级显示器（例如 Wacom Cintiq Pro 系列绘图屏）允许增益值突破 100、最高达到 255。Lunar 默认的滑块上限是 100，此前无法将这类显示器的增益调满，从而限制了色彩校准空间。5.3.1 为此引入了 extendedColorGain（扩展增益）开关。

3.2 实现原理

源码中通过一个计算属性联动滑块上限（Lunar/Data/Display.swift）：

@objc dynamic lazy var maxColorGain = extendedColorGain ? 255 : 100

而 extendedColorGain 本身是一个持久化属性，其 didSet 会同步刷新滑块上限（Lunar/Data/Display.swift）：

@objc dynamic var extendedColorGain = false {
    didSet {
        maxColorGain = extendedColorGain ? 255 : 100
    }
}

在界面层（Lunar/Base.lproj/Main.storyboard），Color Gain 面板中提供了一个标题为 "Extend" 的按钮，其绑定目标正是 self.display.extendedColorGain；三个增益滑块（Red/Green/Blue）的 maxValue 均绑定到 self.display.maxColorGain（见 Lunar/Base.lproj/Main.storyboard 等连接）。

3.3 使用方式

1. 打开 Lunar 设置中对应显示器的 Color Gain 面板；
2. 点击 "Extend" 按钮启用扩展模式；
3. 滑块上限由 100 变为 255，此时可将 Wacom Cintiq Pro 等设备的 RGB Gain 调节到 100–255 区间；
4. 调节后 Lunar 会通过 setRedGain/setGreenGain/setBlueGain 将值写入显示器并持久化。

需要注意的是：扩展模式适用于"滑块原生支持 0–255 增益值"的专业显示器。若普通显示器被强制写入超过 100 的值，可能不会生效或行为未定义，建议仅按需开启。

四、新特性二：禁用"唤醒时重新应用"（Re-apply on wake）

4.1 背景

macOS 的显示器唤醒（wake）事件可能触发显示器内部状态复位，导致之前写入的 RGB Gain 丢失。Lunar 默认会在系统唤醒时自动把存储的增益值重新写回显示器，以维持色彩一致。但对于某些用户，这一自动写回行为可能与显示器 OSD 的手动调节或第三方校色流程冲突，因此 5.3.1 提供了关闭选项。

4.2 实现原理

每个显示器对象拥有持久化布尔属性 reapplyColorGain（默认 false，见 Lunar/Data/Display.swift 与 Lunar/Data/Display.swift）。界面层在 Color Gain 面板中提供了 "Re-apply on wake" 复选框，绑定到 self.display.reapplyColorGain（Lunar/Base.lproj/Main.storyboard）。

唤醒流程的实现在 Lunar/AppDelegate.swift（另一处并行的唤醒处理见 Lunar/AppDelegate.swift）：

for display in DC.activeDisplayList.filter({ !$0.blackOutEnabled && $0.reapplyColorGain }) {
    _ = display.control?.setRedGain(display.redGain.uint16Value)
    _ = display.control?.setGreenGain(display.greenGain.uint16Value)
    _ = display.control?.setBlueGain(display.blueGain.uint16Value)
}

这段代码的含义很清晰：系统唤醒时，仅对满足 reapplyColorGain == true 且未处于黑屏（blackOutEnabled）状态的显示器重新写入三个通道的增益值。换言之：

• 勾选 "Re-apply on wake"：唤醒后强制把 Lunar 中存储的 RGB Gain 写回显示器，确保始终一致；
• 取消勾选（默认）：唤醒后不做任何写入，保留显示器当前的实际增益状态，把控制权交还给显示器 OSD 或外部校色硬件。

4.3 适用场景

• 使用硬件校色器（如 X-Rite、Spyder）且不希望软件唤醒时覆盖校色结果的用户；
• 显示器 OSD 增益可被稳定记忆、无需软件重复写入的环境；
• 与 Blackout（黑屏）功能组合使用时，被排除在重新应用之外，避免黑屏恢复瞬间的增益抖动。

五、关键修复：解决画面被冲淡（washed out）问题

5.1 问题成因

5.3.1 修复了"显示器 Color Gain 实际值 ≠ Lunar 存储值导致画面发白"的问题。成因可以理解为：Lunar 内部保存的 RGB Gain 与显示器当前真实增益不一致（例如用户曾在 OSD 中手动调整、或显示器被其他软件/固件复位过），此时若 Lunar 按照旧值做后续计算或渲染 Gamma 映射，就会在低中灰度区域出现过曝发白的效果。

5.2 修复方式：从显示器回读并校正

源码中通过 refreshColors() 实现"回读-校正"闭环，包含回调与异步两种形态（Lunar/Data/Display.swift）。核心逻辑为：

1. 通过 readRedGain()/readGreenGain()/readBlueGain() 从显示器回读三个通道的实际增益（Lunar/Data/Display.swift，底层调用 control?.getRedGain() 等）；
2. 若回读值与本地存储值不同，则在主线程中静默更新本地值——注意它使用 withoutSmoothTransition { withoutDDC { ... } }，即只更新本地状态、不触发 DDC 写入，避免写入风暴；
3. 若三个通道均回读失败（显示器不支持回读），记录 "Can't read color gain" 警告并返回 false。

func refreshColors() async -> Bool {
    guard !isTestID(id), !isSmartBuiltin,
          !DC.screensSleeping, !DC.locked
    else { return false }

    let newRedGain = self.readRedGain()
    let newGreenGain = self.readGreenGain()
    let newBlueGain = self.readBlueGain()
    guard newRedGain != nil || newGreenGain != nil || newBlueGain != nil else {
        log.warning("Can't read color gain for \(self.description)")
        return false
    }
    ...
}

与之配套，界面上的 "Read colors from monitor" 按钮提供手动触发入口（Lunar/Base.lproj/Main.storyboard），其 toolTip 明确说明"尝试通过 DDC 从显示器获取颜色增益值"，并附带警示：极少数情况下可能引发内核崩溃、需要重启设备。

5.3 对用户的含义

• 若之前遇到"Lunar 调节后颜色发白/发灰"的异常，升级到 5.3.1 后应优先使用 "Read colors from monitor" 手动回读一次，使本地存储值与显示器实际值对齐；
• 该修复对支持 DDC 增益回读的显示器生效；对于不支持回读的型号，Lunar 会安全降级（记录警告而非强行写入）。

六、依赖安全更新

5.3.1 同时完成了对项目依赖组件的安全更新。从仓库结构看，Lunar 的底层控制链路包含 DDC/CI 通信（Lunar/DDC/DDC.c）、SSH/SFTP 远程管理（Lunar/Shout 模块基于 libssh2，见 Lunar/CSSH/libssh2）等 C 级依赖；在 Lunar/Control/NetworkControl.swift 等模块中也会通过网络与外部设备通信。官方发布说明未披露具体 CVE 清单，本次安全更新属于常规依赖加固，建议用户从官方渠道获取并安装最新版本以保持运行环境安全。

七、小结与验证建议

Lunar 5.3.1 的三项 Color Gain 相关改动共同构成了更完整的色彩管理链路：

能力	入口（UI）	核心属性/方法	源码位置
增益范围扩展	Color Gain 面板的 "Extend"	extendedColorGain / maxColorGain	Lunar/Data/Display.swift
唤醒重应用开关	"Re-apply on wake" 复选框	reapplyColorGain	Lunar/AppDelegate.swift
颜色冲淡修复	"Read colors from monitor" 按钮	refreshColors()	Lunar/Data/Display.swift

如果你希望进一步验证这些行为，可在本地完成以下动作：

1. 阅读 ReleaseNotes/5.3.1.md 原始发布说明，核对更新条目；
2. 在 Lunar/Data/Display.swift 中搜索 extendedColorGain、reapplyColorGain、refreshColors，追踪属性定义与调用点；
3. 在 Lunar/DDC/DDC.swift 中查看 ControlID 枚举，理解 0x16/0x18/0x1A 与 OSD 菜单 RGB Gain 的对应关系。

整体而言，5.3.1 定位于专业用户色彩管理与稳定性：扩展范围照顾了绘图屏/设计屏用户，唤醒开关照顾了校色流程，回读校正则从根源上消除了"软件值 ≠ 硬件值"带来的发白观感，值得所有使用 Lunar 管理外接显示器色彩的用户升级。