用途与实际影响
这项功能怎样使用
为什么需要它
虚拟屏重启后可能退回很小的画面；普通显示工具又容易连带改动主屏。这个入口只认项目专用的虚拟屏，先查看它支持什么，再按本人选择调整。
举个实际例子
“把手机用的虚拟屏调成我指定的清晰度和刷新率，别动家里主屏。”先只读查看当前值与可选模式；本人确认后才应用，并分别回读虚拟屏和主屏。
最后我会得到什么
已得到独立参数入口、写前预检、写后回读与失败回滚；实时模式、重枚举后的首选项保持和手机 HDR 画面仍未在本轮验收。
正常时
选定模式得到实际应用和读回；物理屏确实未受影响还要比较它的前后状态。
发现问题时
驱动不支持所选分辨率或刷新率时在修改前停止并说明可选模式。
入口不可用或证据不足时
认不出唯一的项目虚拟屏就拒绝修改任何显示器。
从哪里开始
用项目的 Set-SunshineVddDisplayProfile.ps1 先只读查看专用虚拟屏；确认目标模式后才显式使用 -Apply。
需要准备什么
- 想调整专用虚拟屏的分辨率、刷新率、缩放或 HDR
- 只查看还是应用改变
从开始到拿到结果
- 1
只读认准虚拟屏
先看项目专用虚拟屏现在的画面大小、刷新率和可选范围；主屏和其他小屏不进入修改范围。
- 2
本人确认后才调整
按选定的清晰度、缩放和高动态范围设置预检，再应用；驱动不支持就停。
- 3
回读真实显示
分别查看虚拟屏是否达到目标、主屏是否保持原样；配置成功仍需真实串流画面验收。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
脚本与隔离测试通过；本轮只读，未执行 Apply（应用）或实时显示回读关键规则与设计选择
项目初始 profile（配置组合）保留 2880×1800、60 Hz、150% 缩放与 HDR；后续显式调整可以覆盖。
持久化首选项会把选定模式写在 VDD 驱动模式列表首位，目的是减少驱动重枚举时回退到 800×600；本轮未做重枚举实测。
严格区分 Windows Advanced Color（高级颜色）/HDR 开关与 VDD 驱动内部的 12-bit HDRPlus 能力开关，避免概念混淆造成色彩异常。
脚本默认仅做纯内存预检与状态回读；只有管理员显式传入 -Apply 参数才会执行 Win32 变更与文件原子落盘。
本模块用到的名词
- CDS_TEST（显示设置预检）
- Win32 API 的安全测试标志；只验证系统能否接受该模式，不产生真实的屏幕闪烁或参数改动。
- Advanced Color（高级颜色）
- Windows 官方的 HDR 渲染控制架构；只有在此处开启 HDR，系统才会向串流客户端输出宽色域信号。
专业定义
它把虚拟屏参数从物理主屏中拆开：先认准唯一 MTT1337，再回读，只在显式 Apply（应用）事务中预检并向 VDD 写入；物理屏不变要另做前后验收。
解决什么
降低虚拟显示器分辨率回退、HDR 色彩异常和多屏设置互相影响的风险。
当前怎样实现
- Set-SunshineVddDisplayProfile.ps1 负责参数校验与事务编排；sunshine-vdd-display-settings.psm1 负责身份、计划与 XML 候选。
- Get-SetVddDisplayMode.ps1 实现 ChangeDisplaySettingsEx/CDS_TEST 与模式回读；Get-SetVddScaleHdr.ps1 实现缩放和 Advanced Color（高级颜色）应用/回读。
- tests/Test-SunshineVddDisplaySettings.ps1 与 Test-SunshineVddNativeAdapter.ps1 提供 19 项以上严格测试保障。
- 完整VDD profile按命名参数哈希表分阶段执行实时模式、DPI/HDR及最终XML；完整预检先于效果，原值和回滚结果分别保存。独立模式/DPI适配器也按已尝试字段恢复并精确回读，XML只回滚本次postimage，保留调用方preimage路径与并发变化。回滚前重验GPU/会话/同一VDD，新增阻断保留未恢复项。
执行流程
- 1
用户或上层脚本调用入口并传入期望的宽高、刷新率、缩放与 HDR 模式。
- 2
脚本扫描系统显示设备，严格通过 MTT1337 硬件 ID 锁定专用虚拟屏，拒绝物理屏与水冷屏。
- 3
默认路径只回读身份、当前模式、支持模式、缩放与 HDR，不调用显示写 API。
- 4
若包含 -Apply，事务先调用 ChangeDisplaySettingsEx/CDS_TEST，随后才提交模式、用 DisplayConfigSetDeviceInfo 应用缩放与 HDR，并原子更新持久化 XML。
- 5
执行写后回读，确认生效参数与请求完全一致。
边界
- 入口绝不改写 Sunshine 的 output_name GUID 标识。
- 绝对不触碰物理主屏（PHLC34B 等）、LIAN LI 水冷屏或 HS2 机箱副屏。
- 不强行写入未经驱动支持的非标非常规显示模式。
失败与恢复
- 传入非法或未经支持的分辨率/刷新率
- 预检直接报错退出，不调用 Win32 写入 API，保持现有显示模式。
- 设备名被模拟或重命名为非安全格式
- 安全过滤层拒绝执行并抛出异常，防止向错误显示设备发送指令。
- XML 配置文件写入中途失败
- 原子事务机制回滚至原文件镜像，不留下损坏的截断配置。
真实入口
Set-SunshineVddDisplayProfile.ps1原生显示模式适配器入口
sunshine-vdd-display-settings.psm1设备身份、事务计划与 VDD XML 候选
Get-SetVddDisplayMode.ps1分辨率/刷新率 CDS_TEST、应用与回读
Get-SetVddScaleHdr.ps1缩放和 Windows HDR 原生应用与回读
tests/Test-SunshineVddDisplaySettings.ps1显示设置安全性与预检测试套件
如何验证
- 自动化测试 19/19 全部 PASS（覆盖参数校验、黑名单设备拦截、CDS_TEST 预检与原子持久化）。
- Test-SunshineVddNativeAdapter.ps1 静态核对预期 API 名称、禁止项与调用顺序；它没有真实调用 Win32 或改变显示。
与其他模块的关系
为 VDD 兜底提供独立、可回读的像素与色彩参数；是否真的改善手机画面仍由真实串流验收决定。