parsec-vdd 命令行实战指南：用 vdd 命令管理 Parsec 虚拟显示器

• 桌面应用
• 驱动开发

本文是 parsec-vdd（ParsecDisplay）项目 CLI 模式的完整使用指南。vdd命令行工具允许你在 Windows 10+ 上通过纯命令行添加、移除、枚举虚拟显示器，设置分辨率和刷新率，并查询驱动状态与版本——无需打开图形界面。读完本文，你将掌握vdd的全部命令语法、退出码语义、PowerShell 特殊写法，以及 CLI 背后的驱动调用原理，可直接用于脚本化批量管理虚拟显示器。

前置条件：安装驱动与获取 vdd

CLI 工具（vdd）随安装程序一起发布。从项目 Releases 页面获取以-setup.exe结尾的安装程序（v1.0 起提供），安装后即可在命令行环境中直接调用vdd。

在使用任何命令之前，必须确保 Parsec 虚拟显示驱动已正确安装。仓库的 README.md 提供了两种安装方式：

• 下载驱动安装包后，用 7z 解压出驱动文件与nefconwCLI，再通过nefconw安装；
• 直接以静默模式运行驱动安装程序：

.\parsec-vdd-0.45.0.0.exe /S

驱动版本与 Windows 版本存在对应关系（如 v0.45 对应 Windows 10 21H2、IddCx 1.5），详见 PARSEC_VDD_SPECS.md 中的驱动实现说明。

验证安装与命令总览

运行下面命令检查vdd是否已安装：

vdd -h

若安装成功，会输出完整的帮助文本，这也是全部命令的速查表：

vdd command [args...] -a|add - Add a virtual display -r|remove - Remove the last added virtual display X - Remove the virtual display at index X (number) all - Remove all the added virtual displays -l|list - Show all the added virtual displays and specs -s|set X WxH - Set resolution for a virtual display where X is index number, WxH is size, e.g 1920x1080 X @R - Set only the refresh rate R, e.g @60, @120 (hz) on Powershell, you should replace '@' with 'r' X WxH@R - Set full display mode as above, e.g 1920x1080@144 -v|version - Query driver version and status -h|help - Show this help

命令支持短横线（-a）与单词（add）两种等价写法，共六个操作：添加、移除、列出、设置模式、查询版本、显示帮助。这些帮助文本与源码 app/CLI.cs 中的ShowHelp()完全一致。

添加虚拟显示器（add）

使用-a或add添加一个虚拟显示器：

vdd -a

成功时输出：

Added a virtual display with index 0.

退出码即驱动索引：vdd -a的退出码是新增显示器的驱动索引（0–15），之后可以复用它来移除该显示器；负的退出码表示出错。从源码看，AddDisplay()会先检查已添加数量是否达到上限，再打开驱动句柄并发送IOCTL_ADD，成功后将索引作为返回值返回（app/CLI.cs）。

需要注意的是：驱动单适配器实际可创建 16 个虚拟显示器，但应用将上限控制在8个，以避免热插拔延迟，见 app/Vdd/Core.cs 中MAX_DISPLAYS => 8的注释。当数量达到上限时，add会抛出Exceeded limit (8), could not add more displays错误。

移除虚拟显示器（remove）

移除最后添加的显示器（无参数时等价于移除最大索引的显示器）：

vdd -r

按索引移除（例如移除索引 0）：

vdd -r 0

移除全部：

vdd -r all

all也接受*作为等价写法（见 app/CLI.cs）。移除全部时按驱动索引的逆序遍历，这样 Windows 10 的 Connectivity 注册表不会为幸存的显示器子集凭空生成一个新的默认模式配置；单个显示器的移除失败会作为 Warning 输出（Warning: failed to remove display at index X），循环继续，实现"尽力而为"（best-effort）。退出码语义：全部成功为0，存在任一失败为1（并输出Removed M/N displays.）。

源码中的RemoveDisplay()还会处理两种边界情况：没有任何显示器时输出No Parsec Display available.并返回 0；指定索引不存在时抛出Display index X is not found.（app/CLI.cs）。

列出已添加的显示器（list）

列出所有已添加的虚拟显示器及其规格：

vdd -l

退出码是已添加虚拟显示器的数量。示例输出：

Index: 0 - Device: \\.\DISPLAY37 - Number: 2 - Name: PSCCDD0 - Mode: 1600 x 900 @ 60 Hz - Orientation: Landscape (0°)

各字段含义：

若没有虚拟显示器，输出No virtual displays present.，退出码为 0。该命令的字段输出逻辑见 app/CLI.cs。

设置显示模式（set）

"分辨率"指像素尺寸（宽 × 高）；"显示模式"在此基础上再加上刷新率，例如1920 x 1080 @ 60 Hz。set命令支持三种语法，分别对应三种解析模式（源码中的正则见 app/CLI.cs）：

仅设置分辨率（索引 1 设置为 1920x1080）：

vdd set 1 1920x1080

设置完整显示模式（分辨率 + 刷新率 120 Hz）：

vdd set 1 1920x1080 @120

仅设置刷新率（保留当前分辨率，刷新率改为 144 Hz）：

vdd set 1 @144

PowerShell 特例：由于@在 PowerShell 中有特殊含义，应把@替换为字母r：

vdd set 1 1920x1080 r120

注意r前缀是 CLI 对@的等价替换，其解析正则同时接受[r@]（app/CLI.cs），因此上述三种语法在普通终端与 PowerShell 下均可正常使用。

失败行为：若目标显示器索引不存在，抛出Display index X is not found.；若分辨率/刷新率组合不受支持，ChangeMode返回失败并抛出Failed to set, display mode '...' is not supported.，命令以非零退出码结束。分辨率并非任意值，必须落在驱动预设的显示模式表中——完整的支持矩阵见 PARSEC_VDD_SPECS.md，其中默认模式为1920 x 1080 @ 60 Hz，常见预设包括：

注：所有分辨率均兼容 60 Hz；低端 GPU（如 GTX 1650）在 DCI 4K 下串流可能出现异常。

底层实现上，set最终调用ChangeDisplaySettingsEx并携带CDS_UPDATEREGISTRY标志，将模式写入注册表（app/Display.cs）。

查询驱动状态与版本（version）

查询驱动状态和版本：

vdd -v

示例输出：

Parsec Virtual Display Adapter - Status: OK - Version: 0.45

可能的状态码及含义如下，状态码同时也是该命令的退出码：

状态的判定来自 PnP 设备树：CM_Get_DevNode_Status检查驱动加载/启动标志与问题码（如CM_PROB_NEED_RESTART、CM_PROB_DISABLED等），映射到上述枚举，见 app/Device.cs。因此vdd -v返回8（NOT_INSTALLED）时，说明需要先安装驱动。QueryVersion()将IOCTL_VERSION返回的 32 位整数拆成主版本号与次版本号输出，并直接返回状态码作为进程退出码（app/CLI.cs）。

退出码速查与脚本化建议

综合各命令，退出码语义可归纳为：

由于退出码承载了索引、数量、状态码等多重语义，非常适合写进批处理或 PowerShell 脚本做条件判断，例如在游戏串流启动前保证存在一个 1920x1080@60 的虚拟显示器。

源码级实现原理

从源码结构看，CLI 的完整调用链如下：

1. 入口分发：ParsecDisplay.exe收到首个参数-cli时，跳过 GUI 流程，将剩余参数交给CLI.Execute()（app/Program.cs）。Execute先调用AttachConsole(-1)附着到调用方终端，再按args[0]分发命令（app/CLI.cs）。
2. 可执行文件包装：构建工程会在输出目录额外生成vdd.cmd批处理，内容为start /b /wait "" "ParsecDisplay.exe" -cli %*，这就是vdd命令的直接实现（app/ParsecDisplay.csproj）。安装程序将ParsecDisplay.exe与vdd.cmd一并部署到 PATH，从而可以在任意终端调用。
3. 驱动交互：所有命令最终通过DeviceIoControl向驱动发送 IOCTL（IOCTL_ADD、IOCTL_REMOVE、IOCTL_UPDATE、IOCTL_VERSION，代码见 app/Vdd/Core.cs），其中添加与移除成功后都会附带一次IOCTL_UPDATE以刷新驱动会话。IOCTL 的CTL_CODE展开式与驱动实现说明见 PARSEC_VDD_SPECS.md。
4. 前置校验：PrepareVdd()先查询驱动状态——NOT_INSTALLED时提示"请先安装驱动"，非OK状态直接报错；add命令还会调用CheckAppRunning()，通过单实例命名事件（Program.AppId）确认 ParsecDisplay 应用正在运行（app/CLI.cs）。

常见问题与注意事项

• vdd -v返回 8（NOT_INSTALLED）：驱动未安装或安装不完整，按 README 的nefconw/静默安装流程重装。
• vdd -v返回 6（RESTART_REQUIRED）：设备需要重启才能生效，可先尝试重启系统。
• vdd -a报 "Exceeded limit"：已达到 8 个虚拟显示器的应用上限，先vdd -r all清理再添加。
• set的@报错：在 PowerShell 中使用r前缀（如vdd set 1 1920x1080 r120）。
• 设置不受支持的模式：先运行vdd -l查看当前模式，对照 PARSEC_VDD_SPECS.md 的预设矩阵选择合法值。
• CLI 与 GUI 的关系：remove all的逆序移除策略在应用休眠、退出时同样被采用（README 提到"按驱动索引先移除后添加"的恢复顺序），保持一致的注册表行为；GUI 模式下显示器状态的持久化格式为WxH@Hz/O（见 app/Display.cs），理解它有助于排查跨会话恢复问题。

如需深入了解驱动 IOCTL 的底层结构、生命周期与状态码细节，可继续阅读 PARSEC_VDD_RE.md；驱动安装与项目整体说明见 README.md。

• 桌面应用
• 驱动开发