281 lines
10 KiB
Markdown
281 lines
10 KiB
Markdown
# 自定义光标支持设计方案
|
||
|
||
**状态：已实现** ✓
|
||
|
||
## 概述
|
||
|
||
扩展远程桌面的光标支持，使其能够显示应用程序自定义光标和动画光标，而不仅仅是 16 种标准系统光标。
|
||
|
||
## 现有实现
|
||
|
||
### 数据流
|
||
|
||
```
|
||
客户端 (ScreenCapture.h):
|
||
getCurrentCursorIndex() → 0-15 或 -1
|
||
帧数据: [算法(1)] [光标位置(8)] [光标索引(1)] [图像数据...]
|
||
|
||
服务端 (ScreenSpyDlg.cpp):
|
||
cursorIndex == -1 → 回退到标准箭头
|
||
cursorIndex 0-15 → 使用 m_CursorInfo.getCursorHandle(index)
|
||
```
|
||
|
||
### 限制
|
||
|
||
- 仅支持 16 种标准系统光标 (IDC_ARROW, IDC_HAND, IDC_IBEAM 等)
|
||
- 自定义光标显示为箭头
|
||
- 动画光标不支持
|
||
|
||
## 设计方案
|
||
|
||
### 方案概述
|
||
|
||
采用**独立命令传输 + 哈希缓存 + 节流机制**：
|
||
|
||
1. 新增 `CMD_CURSOR_IMAGE` 命令传输光标位图
|
||
2. 使用位图哈希避免重复传输
|
||
3. 节流机制防止动画光标过载
|
||
4. 光标索引 `-2` 表示使用已缓存的自定义光标
|
||
|
||
### 光标索引定义
|
||
|
||
| 索引值 | 含义 |
|
||
|-------|------|
|
||
| 0-15 | 标准系统光标（现有） |
|
||
| -1 (255) | 不支持，显示箭头（现有，向后兼容） |
|
||
| -2 (254) | 使用缓存的自定义光标（新增） |
|
||
|
||
### CMD_CURSOR_IMAGE 数据格式
|
||
|
||
```
|
||
字节偏移 大小 字段
|
||
────────────────────────────
|
||
0 1 CMD_CURSOR_IMAGE (命令字节)
|
||
1 4 hash (位图哈希，用于去重)
|
||
5 2 hotspotX (热点X坐标)
|
||
7 2 hotspotY (热点Y坐标)
|
||
9 1 width (光标宽度，最大255)
|
||
10 1 height (光标高度，最大255)
|
||
11 N BGRA位图数据 (N = width * height * 4)
|
||
|
||
典型大小: 32x32光标 = 11 + 4096 = 4107 字节
|
||
```
|
||
|
||
### 客户端逻辑 (ScreenCapture.h / ScreenManager.cpp)
|
||
|
||
```cpp
|
||
// 新增状态变量
|
||
DWORD m_lastCursorHash = 0; // 上次发送的光标哈希
|
||
DWORD m_lastCursorSendTime = 0; // 上次发送时间
|
||
const DWORD CURSOR_THROTTLE = 50; // 最小发送间隔 (ms)
|
||
|
||
// 每帧处理逻辑
|
||
int cursorIndex = getCurrentCursorIndex();
|
||
if (cursorIndex == -1) {
|
||
// 非标准光标，获取位图
|
||
CursorBitmapInfo info;
|
||
if (GetCurrentCursorBitmap(&info)) {
|
||
DWORD hash = CalculateBitmapHash(info);
|
||
DWORD now = GetTickCount();
|
||
|
||
// 哈希变化且超过节流时间 → 发送光标图像
|
||
if (hash != m_lastCursorHash &&
|
||
(now - m_lastCursorSendTime) > CURSOR_THROTTLE) {
|
||
SendCursorImage(info, hash);
|
||
m_lastCursorHash = hash;
|
||
m_lastCursorSendTime = now;
|
||
}
|
||
cursorIndex = -2; // 使用自定义光标
|
||
}
|
||
}
|
||
// 帧数据中写入 cursorIndex
|
||
```
|
||
|
||
### 服务端逻辑 (ScreenSpyDlg.cpp)
|
||
|
||
```cpp
|
||
// 新增成员变量
|
||
HCURSOR m_hCustomCursor = NULL; // 缓存的自定义光标
|
||
DWORD m_customCursorHash = 0; // 当前光标哈希
|
||
|
||
// 处理 CMD_CURSOR_IMAGE
|
||
case CMD_CURSOR_IMAGE: {
|
||
DWORD hash = *(DWORD*)(buffer + 1);
|
||
if (hash != m_customCursorHash) {
|
||
WORD hotX = *(WORD*)(buffer + 5);
|
||
WORD hotY = *(WORD*)(buffer + 7);
|
||
BYTE width = buffer[9];
|
||
BYTE height = buffer[10];
|
||
LPBYTE bitmapData = buffer + 11;
|
||
|
||
// 销毁旧光标
|
||
if (m_hCustomCursor) {
|
||
DestroyCursor(m_hCustomCursor);
|
||
}
|
||
|
||
// 创建新光标
|
||
m_hCustomCursor = CreateCursorFromBitmap(
|
||
hotX, hotY, width, height, bitmapData);
|
||
m_customCursorHash = hash;
|
||
}
|
||
break;
|
||
}
|
||
|
||
// 处理帧数据中的光标索引
|
||
BYTE cursorIndex = buffer[2 + sizeof(POINT)];
|
||
HCURSOR cursor;
|
||
if (cursorIndex == 254) { // -2
|
||
cursor = m_hCustomCursor ? m_hCustomCursor : LoadCursor(NULL, IDC_ARROW);
|
||
} else if (cursorIndex == 255) { // -1
|
||
cursor = LoadCursor(NULL, IDC_ARROW);
|
||
} else {
|
||
cursor = m_CursorInfo.getCursorHandle(cursorIndex);
|
||
}
|
||
```
|
||
|
||
### 获取光标位图实现
|
||
|
||
```cpp
|
||
struct CursorBitmapInfo {
|
||
WORD hotspotX;
|
||
WORD hotspotY;
|
||
BYTE width;
|
||
BYTE height;
|
||
std::vector<BYTE> bgraData; // width * height * 4
|
||
};
|
||
|
||
bool GetCurrentCursorBitmap(CursorBitmapInfo* info) {
|
||
CURSORINFO ci = { sizeof(CURSORINFO) };
|
||
if (!GetCursorInfo(&ci) || ci.flags != CURSOR_SHOWING)
|
||
return false;
|
||
|
||
ICONINFO iconInfo;
|
||
if (!GetIconInfo(ci.hCursor, &iconInfo))
|
||
return false;
|
||
|
||
info->hotspotX = (WORD)iconInfo.xHotspot;
|
||
info->hotspotY = (WORD)iconInfo.yHotspot;
|
||
|
||
BITMAP bm;
|
||
GetObject(iconInfo.hbmColor ? iconInfo.hbmColor : iconInfo.hbmMask,
|
||
sizeof(BITMAP), &bm);
|
||
|
||
info->width = (BYTE)min(bm.bmWidth, 255);
|
||
info->height = (BYTE)min(bm.bmHeight, 255);
|
||
|
||
// 获取 BGRA 位图数据
|
||
// ... (使用 GetDIBits)
|
||
|
||
// 清理
|
||
DeleteObject(iconInfo.hbmColor);
|
||
DeleteObject(iconInfo.hbmMask);
|
||
|
||
return true;
|
||
}
|
||
```
|
||
|
||
### 哈希计算
|
||
|
||
```cpp
|
||
DWORD CalculateBitmapHash(const CursorBitmapInfo& info) {
|
||
// 使用 FNV-1a 或简单的累加哈希
|
||
DWORD hash = 2166136261; // FNV offset basis
|
||
const BYTE* data = info.bgraData.data();
|
||
size_t len = info.bgraData.size();
|
||
|
||
for (size_t i = 0; i < len; i += 16) { // 每16字节采样一次，加速
|
||
hash ^= data[i];
|
||
hash *= 16777619; // FNV prime
|
||
}
|
||
return hash;
|
||
}
|
||
```
|
||
|
||
## 数据流图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 客户端 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ getCurrentCursorIndex() │
|
||
│ │ │
|
||
│ ├─ 0-15 ──→ 帧数据: cursorIndex = 0-15 │
|
||
│ │ │
|
||
│ └─ -1 ──→ GetCurrentCursorBitmap() │
|
||
│ │ │
|
||
│ ├─ 计算哈希 │
|
||
│ │ │
|
||
│ ├─ 哈希变化 && 超过节流? │
|
||
│ │ │ │
|
||
│ │ ├─ Yes ──→ 发送 CMD_CURSOR_IMAGE │
|
||
│ │ │ 更新 lastHash, lastTime │
|
||
│ │ │ │
|
||
│ │ └─ No ──→ 跳过发送 │
|
||
│ │ │
|
||
│ └─ 帧数据: cursorIndex = -2 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 服务端 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 收到 CMD_CURSOR_IMAGE: │
|
||
│ └─ hash != m_customCursorHash? │
|
||
│ ├─ Yes ──→ CreateCursorFromBitmap() → m_hCustomCursor │
|
||
│ └─ No ──→ 忽略 (已缓存) │
|
||
│ │
|
||
│ 收到帧数据: │
|
||
│ └─ cursorIndex: │
|
||
│ ├─ 0-15 ──→ m_CursorInfo.getCursorHandle(index) │
|
||
│ ├─ -1 ──→ LoadCursor(IDC_ARROW) (向后兼容) │
|
||
│ └─ -2 ──→ m_hCustomCursor │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 动画光标支持
|
||
|
||
本方案自然支持动画光标：
|
||
|
||
| 机制 | 说明 |
|
||
|-----|------|
|
||
| **自动检测** | 动画每帧位图哈希不同，自动触发传输 |
|
||
| **节流保护** | 50ms 节流 ≈ 最高 20fps，防止过载 |
|
||
| **带宽控制** | 32x32 动画 @ 10fps ≈ 40 KB/s，可接受 |
|
||
|
||
## 修改文件清单
|
||
|
||
| 文件 | 修改内容 |
|
||
|-----|---------|
|
||
| `common/commands.h` | 新增 `CMD_CURSOR_IMAGE = 75` |
|
||
| `client/CursorInfo.h` | 新增 `GetCurrentCursorBitmap()`, `CalculateBitmapHash()` |
|
||
| `client/ScreenCapture.h` | 发送逻辑：检测、节流、发送 CMD_CURSOR_IMAGE |
|
||
| `client/ScreenManager.cpp` | 处理 CMD_CURSOR_IMAGE（如果服务端发给客户端需要） |
|
||
| `server/2015Remote/ScreenSpyDlg.h` | 新增 `m_hCustomCursor`, `m_customCursorHash` |
|
||
| `server/2015Remote/ScreenSpyDlg.cpp` | 处理 CMD_CURSOR_IMAGE，更新光标显示逻辑 |
|
||
|
||
## 向后兼容性
|
||
|
||
- 旧客户端：继续发送 `-1`，服务端显示箭头（现有行为）
|
||
- 新客户端 + 旧服务端：发送 `-2` 和 CMD_CURSOR_IMAGE，旧服务端忽略新命令，`-2` 当作 `-1` 处理
|
||
- 新客户端 + 新服务端：完整自定义光标支持
|
||
|
||
## 可调参数
|
||
|
||
```cpp
|
||
// client/ScreenCapture.h
|
||
const DWORD CURSOR_THROTTLE = 50; // 节流间隔 (ms)
|
||
// 50ms → 最高 20fps，动画流畅
|
||
// 100ms → 最高 10fps，省带宽
|
||
|
||
const BYTE MAX_CURSOR_SIZE = 64; // 最大光标尺寸
|
||
// 超过此尺寸的光标将被缩放或回退到标准光标
|
||
```
|
||
|
||
## 测试用例
|
||
|
||
1. **标准光标** - 箭头、手形、I形等，应使用索引 0-15
|
||
2. **自定义静态光标** - 应用程序自定义光标，只传输一次
|
||
3. **动画光标** - Windows 忙碌动画，应持续更新（受节流限制）
|
||
4. **快速切换** - 频繁切换光标，节流应生效
|
||
5. **大尺寸光标** - 超过 64x64 的光标，应正确处理或回退
|