📚 课程目录第4章使用PresentMon采集DirectX/Windows帧数据

第4章使用 PresentMon 采集 DirectX/Windows 帧数据：配置、数据字段、CSV 解析

4.1 原理概述

PresentMon 是微软官方开源的工具，通过监听 Windows ETW（Event Tracing for Windows）事件来捕捉 DirectX 应用向显示器提交画面的时刻。其核心原理如下：

ETW 钩子：PresentMon 不注入 DLL，而是通过 ETW 订阅 Microsoft-Windows-D3D9、Microsoft-Windows-DXGI 等内核态事件源，捕获 Present / Present1 的起始和结束时间戳。
帧周期计算：对同一交换链（SwapChain）连续两次 Present 结束时间戳做差，得到单帧间隔（Frame Time），再取倒数即为瞬时帧率（FPS）。
CPU/GPU 边界：通过 Present-Start 和 Present-Stop 之间的时间跨度，分离 CPU 提交延迟与 GPU 实际执行延迟。
同步与 VSync：ETW 事件中携带 SyncInterval 和 Flags 字段，可判断应用是否开启垂直同步及使用何种翻转模式（Flip / Copy / Discard）。

4.2 安装与配置

4.2.1 获取 PresentMon

从 GitHub 官方仓库（microsoft/PresentMon）的 Release 页面下载最新二进制包，或通过以下命令克隆并自行编译：

git clone https://github.com/microsoft/PresentMon.git
cd PresentMon
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

编译产物中包含 PresentMon.exe（CLI 采集工具）和 PresentMonAPI.dll（C/C++ SDK）。

4.2.2 基础配置参数

PresentMon 支持丰富的命令行参数，下表列出最常用的配置选项：

参数	默认值	说明
`-exe`	—	指定目标可执行文件名（如 `notepad.exe`），支持通配符
`-pid`	—	指定目标进程 PID，优先级高于 `-exe`
`-output_file`	PresentMon.csv	CSV 输出路径，路径含空格需用双引号包裹
`-etl_file`	—	将 ETW 事件直接写入 .etl 文件而非实时解析（离线模式）
`-capture_duration`	无限	采集时长，单位秒（如 `3600` 表示 1 小时）
`-simple`	false	启用简化模式，仅输出帧时间与 FPS，减少文件体积
`-verbose`	false	启用详细输出，包含每帧的完整内部状态
`-process_names`	—	逗号分隔的进程名列表，同时监控多个进程

4.2.3 配置文件方式

推荐将常用参数写入 JSON 配置文件，便于团队复用和版本管理。示例：

{
  "exe": "MyGame.exe",
  "output_file": "D:/fcap/frame_data.csv",
  "capture_duration": 300,
  "simple": false,
  "verbose": false,
  "mru": 3
}

通过 -config_file path/to/config.json 加载。

4.3 核心数据字段详解

PresentMon 输出的 CSV 默认包含以下关键字段（按列顺序）：

字段名	类型	说明
Application	string	进程名称，如 `notepad.exe`
ProcessID	uint32	进程标识符
SwapChainAddress	hex64	交换链对象的内存地址，用于区分多窗口/多渲染目标
Runtime	string	图形运行时：`D3D9` / `D3D10` / `D3D11` / `D3D12` / `DXGI`
SyncInterval	uint32	垂直同步间隔（0=关闭 VSync，1=每帧同步，2=每两帧同步）
PresentFlags	uint32	翻转模式标志位：0=Flip，1=Copy，2=Discard
Dropped	bool	该帧是否被丢弃（因 GPU 过载或 VSync 错过）
TimeInSeconds	float64	从采集开始到 Present 结束的时间，单位秒
MsBetweenPresents	float64	连续两帧 Present 结束的时间差（帧间隔），单位毫秒
MsInPresentAPI	float64	Present API 调用本身在 CPU 侧的耗时，单位毫秒
MsBetweenDisplayChanges	float64	实际显示器画面刷新间隔（仅当 VSync 开启时有意义）
FPS	float64	瞬时帧率 = 1000 / MsBetweenPresents

字段选择提示：使用 -simple 模式时仅保留 TimeInSeconds、MsBetweenPresents、FPS 三列，适合快速帧率监控；分析 GPU 瓶颈时务必保留 MsInPresentAPI。

4.4 CSV 输出与解析方法

4.4.1 实时采集命令示例

以下命令启动对 MyGame.exe 的监控，采集 5 分钟，输出到指定路径：

PresentMon.exe -exe MyGame.exe -output_file "D:/captures/frame_data.csv" -capture_duration 300 -simple false -verbose false

若需同时监控多个进程：

PresentMon.exe -process_names "MyGame.exe,Helper.exe" -output_file multi.csv

4.4.2 Python 解析示例

使用 pandas 读取 CSV 并计算聚合统计：

import pandas as pd
import sys

df = pd.read_csv("frame_data.csv", dtype={
    "Application": str,
    "ProcessID": int,
    "MsBetweenPresents": float,
    "FPS": float
})

# 过滤异常帧（剔除 MsBetweenPresents > 200ms 的卡顿帧）
df_clean = df[df["MsBetweenPresents"] < 200.0].copy()

# 计算关键指标
avg_fps = df_clean["FPS"].mean()
p99_frametime = df_clean["MsBetweenPresents"].quantile(0.99)
drop_count = df["Dropped"].sum()

print(f"平均 FPS: {avg_fps:.2f}")
print(f"P99 帧间隔: {p99_frametime:.2f} ms")
print(f"丢弃帧数: {drop_count}")

4.4.3 流式解析（高负载场景）

当采集时长超过 1 小时或帧率极高（>120 FPS）时，CSV 文件可能达到数 GB。推荐使用迭代器逐块读取：

import csv
from collections import deque

def stream_frametimes(csv_path, window=60):
    with open(csv_path, "r") as f:
        reader = csv.DictReader(f)
        buffer = deque(maxlen=window)
        for row in reader:
            ft = float(row["MsBetweenPresents"])
            if ft < 200.0:
                buffer.append(ft)
            if len(buffer) == window:
                yield sum(buffer) / window  # 滑动平均帧间隔

4.5 常见采集场景与配置建议

场景	推荐参数	说明
快速帧率验证	`-simple`	仅输出帧间隔与 FPS，文件小、性能开销最低
GPU 瓶颈分析	默认（含 MsInPresentAPI）	对比 CPU/GPU 耗时，定位短板
长时间稳定性测试	`-capture_duration 86400` + `-etl_file`	先写入 .etl 避免 CSV 单文件过大，事后离线解析
多进程叠加监控	`-process_names`	同屏对比不同进程的帧率表现
离线分析已录制 ETL	运行 PresentMon 时指定 `-etl_file`	通过 `PresentMon.exe -etl_file trace.etl -output_file out.csv` 回放

4.6 调试与性能优化

4.6.1 验证采集是否生效

检查命令行输出：PresentMon 启动后会在控制台打印 Tracking process <PID> (<Name>)，并实时显示当前帧率。
无输出：确认进程名拼写无误，并确保以管理员权限运行（ETW 事件需要 SeDebugPrivilege）。
字段全为 0：目标应用可能使用旧版 D3D9 或 GDI，PresentMon 默认只监控 DXGI/D3D10+，需加 -capture_all 回退到兼容模式。

4.6.2 降低采集开销

使用 -simple 模式跳过额外字段计算，CPU 开销可降低 40%~60%。
增大采样间隔：通过 -process_name 配合 mru 参数限制最大跟踪进程数。
将 CSV 写入高速磁盘（NVMe SSD 或 RAM Disk），避免 IO 成为瓶颈。

4.6.3 常见问题排查

错误：“Access Denied” 或 “Event Trace not found”

原因：当前用户无 ETW 会话权限。解决方法：以管理员身份运行 PresentMon，或在组策略中授予用户 “Perform volume maintenance tasks” 权限。

错误：CSV 中 MsBetweenPresents 出现大量 0 或负数

原因：目标进程创建了多个交换链或 Present 调用有重叠。建议按 SwapChainAddress 列分组分析，只保留主交换链数据。

技巧：自动重启采集

使用批处理或计划任务定时重启 PresentMon，避免长时间进程内存泄漏。示例 PowerShell 循环：while ($true) { PresentMon.exe -exe MyGame.exe -capture_duration 3600; Start-Sleep 5 }

4.7 部署与集成建议

CI/CD 集成：将 PresentMon 放入自动化测试流水线，在性能回归测试中自动采集帧率数据并生成报告。
游戏发行版打包：随游戏分发 PresentMonAPI.dll，利用 SDK 在内部实现帧率统计与异常上报。
日志轮转：通过 -output_file 中嵌入时间戳（如 frame_%Y%m%d_%H%M%S.csv），避免单文件无限膨胀。