# 鼠标回报率测试工具

**Repository Path**: telaker/Mouse-polling-rate-test-tool

## Basic Information

- **Project Name**: 鼠标回报率测试工具
- **Description**: 本仓库由 AI 进行编程，本工具可以用于测量鼠标的回报率。
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鼠标回报率测试仪 v9

一个**零依赖、无需安装驱动**的 Windows 鼠标回报率（轮询率 / Polling Rate）测试小工具。
基于 Windows Raw Input + 高精度计时器（QPC）自打时间戳，实测你鼠标每一秒到底向电脑"汇报"了多少次。

> 适用场景：买了标称 8K / 4K / 2K 的电竞鼠标，想验证真实回报率；排查"为什么设了 8K 实测只有 2K"；对比有线 / 无线 / 蓝牙鼠标的实际表现。

---

## 一、功能特性

- ✅ **支持所有 HID 鼠标**：USB 有线、蓝牙、2.4G 无线、星闪（NearLink）等无线方案均可测，不挑协议。
- ✅ **多设备识别**：下拉框枚举"全部鼠标（N 只）"以及每只鼠标的 VID/PID，自动识别当前活动设备并**锁定单设备统计**（避免多个鼠标混算导致读数异常）。
- ✅ **热插拔自动重识别**：拔掉 / 重新插入接收器后，程序会自动重新枚举，无需重启。
- ✅ **五项关键读数**：平均回报率、最低瞬时（决定卡顿）、最高瞬时、近 1 秒最低、报告数 / 时长。
- ✅ **间隔直方图**：8 档分桶、颜色分级，一眼看出你的鼠标主要稳定在哪个档位。
- ✅ **噪声过滤**：剔除 Windows 消息泵"合并投递"产生的虚假极值，最高瞬时封顶 10000 Hz 显示。
- ✅ **两种模式**：图形界面（默认）+ 控制台模式（`--console`，便于脚本 / 快速验证）。
- ✅ **USBPcap 诊断（可选）**：可直接在界面里抓取 USB 端点 `bInterval`，从底层确认"8K 卡 2K"的根因。
- ✅ **无需管理员、无需驱动**：日常测量双击即用；仅 USBPcap 诊断需要装驱动 + 管理员运行。

---

## 二、下载与运行

- **直接运行**：下载 `mouse_rate_tester_v9.exe`，双击即可打开图形界面。
- **系统要求**：Windows 7 及以上（64 位）。无需安装任何运行时。
- **权限**：日常测量不需要管理员；只有"USBPcap 诊断"功能需要管理员 + 已安装 USBPcap 驱动。

---

## 三、使用步骤（图形界面）

1. 打开程序，下拉框默认选中 **"全部鼠标（N 只）"**。
   - 若想只测某一只鼠标，从下拉框选对应的 `鼠标 VID_xxxx PID_xxxx`；选完后统计会**锁定该设备**。
2. 点击 **「开始测量」**（再次点击变为「停止测量」）。
3. **移动鼠标**（电竞鼠标在静止时会持续发心跳包，但动一下读数最稳）。
4. 观察窗口里的读数变化，重点看 **「最低瞬时」**——它决定你实际会不会感到卡顿。
5. 想重新测一只鼠标 / 对比不同设置时，点 **「清除数据」** 即可清零重来。
6. 任何疑问点 **「关于」** 按钮，里面有完整使用说明与原理。

> 💡 拔插鼠标后程序会自动重新识别，下拉框也会更新，不用关掉重开。

---

## 四、界面读数说明

| 读数 | 含义 | 说明 |
|------|------|------|
| **平均回报率** | 全程平均 Hz | 纸面表现，大致等于你设置的档位。 |
| **最低瞬时** | `1,000,000 ÷ 最长间隔` | **最重要**：最长的一次间隔决定是否卡顿。 |
| **最高瞬时** | `1,000,000 ÷ 最短有效间隔` | 设备上限能力。已过滤虚假极值，超过 10000 Hz 显示为 `>10000 Hz（已过滤噪声）`。 |
| **近 1 秒最低** | 最近 1 秒内的最差瞬时 | 反映"最近这一秒顺不顺"。 |
| **报告数 / 时长** | 累计计数 | 均为 64 位，正常使用不会溢出。 |
| **系统合并投递（已剔除）** | 被过滤的噪声计数 | Windows 有时会把多个 HID 报告合并成一次投递，这类假间隔会被剔除，不污染读数。 |

---

## 五、间隔直方图（分档与配色）

横轴从左到右共 8 档，柱越高表示该档位出现的样本越多：

```
∞(>8K)   4K-8K   2K-4K   1K-2K   500-1K   250-500   125-250   ≤125Hz
```

- **青 / 绿（>8K、8K、4K、2K）**：精英 / 电竞级，丝滑。
- **金（1K）**：竞技标准，也是大众主流水平，足够流畅。
- **橙（500）**：尚可，日常够用。
- **红（≤125）**：明显卡顿。

> 注意：**1K 和 2K 都是"好"的表现**，不必盲目追求最左边。1K 已是绝大多数游戏的竞技标准。

**15% 向上浮动容差**：每档上限在频率上向上放宽 15%（例如 1000 Hz 档实际上延到 1150 Hz），
让仅略超名义值的样本（如 1001 / 1002 Hz）归入更低一档，避免"刚过线就点亮整柱"、更符合直觉。

> 说明：鼠标回报率受电磁干扰、USB 调度、CPU 抢占等多种环境因素影响，实测数值并不一定完全精确；
> 加入这 15% 浮动，正是为了让直方图更贴近人的直觉，而非苛求理论值。

---

## 六、控制台模式（命令行）

适合快速验证或嵌入脚本：

```bat
mouse_rate_tester_v9.exe --console        :: 控制台模式，默认测全部鼠标，每 0.5 秒打印统计
mouse_rate_tester_v9.exe --console 1      :: 指定设备索引（下拉框第 1 只为 0，依次类推）
```

控制台模式隐藏消息窗，只打印统计行，方便看趋势或做批处理。

---

## 七、从源码编译

仓库包含 `main.c`、`usbpcap_diag.c`、`build.bat`。两种工具链任选其一：

### 方式 A：MinGW-w64（gcc）

```bat
gcc -O2 -mwindows -o mouse_rate_tester_v9.exe main.c usbpcap_diag.c ^
    -lsetupapi -lgdi32 -luser32 -lshell32
```

### 方式 B：MSVC（Visual Studio）

用 **"VS 2022 开发人员命令提示符"** 执行：

```bat
cl /O2 /W3 main.c usbpcap_diag.c /link /SUBSYSTEM:WINDOWS ^
    setupapi.lib user32.lib gdi32.lib shell32.lib /out:mouse_rate_tester_v9.exe
```

或直接双击 `build.bat`，脚本会自动探测 `gcc` / `cl` 并编译。

---

## 八、USBPcap 诊断（可选，深挖根因用）

当你怀疑"设了 8K 却跑不到 8K"时，可用此功能从 USB 协议层确认：

1. 到 <https://usbpcap.github.io/> 下载并安装 **USBPcap**（会装一个内核驱动）。
2. **以管理员身份**运行本程序，点击 **「USBPcap 诊断」**。
3. 程序会逐级枚举主机控制器与端点，尝试读取你鼠标端点的 `bInterval`。

> 若提示 `err=259`（ERROR_NO_MORE_ITEMS），通常是 USBPcap 驱动未附加到对应的 USB 主机控制器上，
> 重新运行 USBPcap 安装器、勾选对应控制器后再试即可，并非程序 bug。

---

## 九、"8K 卡 2K"到底是什么回事？

高速 USB 的回报率由端点描述符里的 `bInterval` 决定：

| bInterval | 间隔 | 回报率 |
|-----------|------|--------|
| 1 | 125 µs | **8000 Hz** |
| 3 | 500 µs | **2000 Hz** |

如果你在厂商软件里设了 8K，但本工具实测长期停在 2K，说明**接收器 → 电脑的 USB 端点被限频**了（常见于刚插上、或厂商配置未推送到接收器）。

**解决方法**：
1. 用厂商配套软件（如华为电脑管家 / GoPlay）把 8K 配置**推送给接收器**；
2. 换到**主板后置 USB 口**（前置面板 / 集线器可能限流）；
3. 重新插拔接收器，再用本工具验证是否稳定在 8K。

---

## 十、技术原理简介

1. 注册 `RIDEV_INPUTSINK + RIDEV_DEVNOTIFY` 后，系统在**每个鼠标 HID 报告到达时**向程序投递 `WM_INPUT` 消息。
2. 收到消息的瞬间用 `QueryPerformanceCounter`（QPC，亚微秒级）打时间戳。
3. 相邻两次时间戳之差 = 一次报告间隔 `dt`（微秒）；瞬时回报率 = `1,000,000 ÷ dt`。
4. 仅统计 `dt ≥ 100 µs` 的有效间隔（剔除合并投递噪声），直方图与最高瞬时共用同一道过滤源，保证两者一致。
5. `∞(>8K)` 桶按 `dt < 125 µs`（即 >8000 Hz）严格判定，真实 ≥8K 的样本不会被焊死在 8000。

---

## 十一、常见问题

- **Q：不动鼠标时读数很低 / 为 0？**
  A：正常。鼠标静止时部分型号会降低回报频率。测量时**移动鼠标**即可。

- **Q：需要装驱动或管理员吗？**
  A：日常测量**不需要**，双击即用。仅 USBPcap 诊断需要驱动 + 管理员。

- **Q：蓝牙 / 无线鼠标能测吗？**
  A：能。只要是 HID 鼠标（绝大多数都是），无论 USB / 蓝牙 / 2.4G / 星闪都能测。

- **Q：为什么最高瞬时偶尔显示 `>10000 Hz`？**
  A：这是过滤后的上限提示，表示存在比噪声阈值更短的间隔，已按 10000 Hz 封顶展示，不影响其它读数。

---

## 十二、免责声明

本工具仅用于个人学习与技术验证，读数受系统负载、电磁环境等因素影响，**不作为厂商性能承诺的仲裁依据**。
源码开放，可自行编译审计。

---

*鼠标回报率测试仪 v9 · Raw Input 引擎 · 无需驱动 · 开源可编译*