LINK/DisplayFlow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新README

Browse Source
This commit is contained in:
huanglinhuan
2026-01-13 22:55:43 +08:00
parent e3db1b57a0
commit c3d7753add
5 changed files with 177 additions and 896 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
BUILD_GUIDE.md
View File

@@ -1,180 +0,0 @@
# DisplayFlow 构建指南
## 前置要求
### 通用要求
- CMake 3.15 或更高版本
- C++17 兼容的编译器
- Git（用于下载依赖）
### Windows
- Visual Studio 2019 或更高版本
- Windows SDK 10.0.19041.0 或更高版本
### Android
- Android NDK r21 或更高版本
- Android Studio（可选，用于开发）
### Linux/macOS
- GCC 7+ 或 Clang 8+
- pkg-config（如果启用 VP8 编解码器）
## 快速开始
### Windows
```batch
# 使用构建脚本
scripts\build.bat Release
# 或手动构建
mkdir build
cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release
```
### Linux/macOS
```bash
# 使用构建脚本
chmod +x scripts/build.sh
./scripts/build.sh Release
# 或手动构建
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)
```
### Android
```bash
# 设置 Android NDK 路径
export ANDROID_NDK=/path/to/android-ndk
# 创建构建目录
mkdir build-android
cd build-android
# 配置 CMake
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
-DANDROID_ABI=arm64-v8a \
-DANDROID_PLATFORM=android-21 \
-DCMAKE_BUILD_TYPE=Release
# 编译
cmake --build .
```
## 构建选项
### 主要选项
- `BUILD_TESTS`: 构建测试（默认: OFF）
```bash
cmake .. -DBUILD_TESTS=ON
```
- `BUILD_SHARED_LIBS`: 构建共享库（默认: OFF）
```bash
cmake .. -DBUILD_SHARED_LIBS=ON
```
- `ENABLE_VP8_CODEC`: 启用 VP8 编解码器支持（默认: OFF）
```bash
cmake .. -DENABLE_VP8_CODEC=ON
```
- `USE_SYSTEM_FLATBUFFERS`: 使用系统安装的 FlatBuffers（默认: OFF）
```bash
cmake .. -DUSE_SYSTEM_FLATBUFFERS=ON
```
### 依赖管理
项目使用 CMake FetchContent 自动下载依赖。主要依赖包括：
- **FlatBuffers**: 自动下载（或使用系统版本）
- **Google Test**: 仅在 `BUILD_TESTS=ON` 时下载
- **libvpx**: 仅在 `ENABLE_VP8_CODEC=ON` 时查找
### 使用 vcpkg（可选）
如果使用 vcpkg 管理依赖：
```bash
# 安装 vcpkg
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh # Linux/macOS
# 或
.\bootstrap-vcpkg.bat # Windows
# 安装依赖
./vcpkg install flatbuffers
# 配置 CMake 使用 vcpkg
cmake .. -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
```
## 运行测试
```bash
# 在构建目录中
ctest
# 或运行特定测试
ctest -R test_network_interface
# 详细输出
ctest --verbose
```
## 输出目录
构建输出位于：
- 可执行文件: `build/bin/`
- 库文件: `build/lib/`
- 测试: `build/tests/`
## 常见问题
### CMake 找不到编译器
**Windows**: 确保 Visual Studio 已安装，并在 Visual Studio 开发者命令提示符中运行。
**Linux**: 安装构建工具：
```bash
sudo apt-get install build-essential # Ubuntu/Debian
```
### Android 构建失败
确保设置了正确的 Android NDK 路径：
```bash
export ANDROID_NDK=/path/to/android-ndk
```
### 依赖下载失败
检查网络连接，或使用代理：
```bash
export https_proxy=http://proxy.example.com:8080
```
## 开发模式
对于开发，建议使用 Debug 模式：
```bash
cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build .
```
这会启用调试符号和测试支持。

324
DEVELOPMENT_PLAN.md
View File

@@ -1,324 +0,0 @@
# DisplayFlow 开发计划
## 1. 项目阶段划分
### 阶段一：核心架构搭建（Foundation Phase）
**目标**：建立跨平台核心库的基础架构和构建系统
#### 1.1 构建系统配置
- [ ] 配置 CMake 作为统一构建系统
- [ ] 设置跨平台编译配置（Android NDK、Windows MSVC）
- [ ] 配置依赖管理（FlatBuffers、编解码库等）
- [ ] 建立单元测试框架
#### 1.2 核心库基础模块
- [ ] **网络抽象层（Network Abstraction）**
- 统一网络接口定义
- RNDIS/USB 网络检测
- Wi-Fi 网络管理
- 以太网支持
- 自动连接选择算法
- [ ] **NAT 穿透模块（NAT Traversal）**
- STUN 客户端实现
- TURN 客户端实现
- ICE 协议实现
- 候选地址收集
- 连接检查和路径选择
- 自动连接建立
- [ ] **协议层（Protocol Layer）**
- FlatBuffers Schema 定义
- 消息序列化/反序列化
- 会话建立协议
- 视频帧传输协议
- 输入事件协议
- [ ] **会话管理（Session Management）**
- 会话创建与销毁
- 角色管理（Host/Client/Peer）
- 一对多会话支持
- 会话状态机
- [ ] **编解码抽象（Codec Abstraction）**
- 编解码器接口定义
- H.264 硬件加速支持
- VP8 软件编解码
- MJPEG 支持
- 自适应编解码器选择
- [ ] **文件传输模块（File Transfer）**
- 文件传输协议定义
- 断点续传机制
- 多文件并发传输
- 传输进度跟踪
- 文件校验（MD5/SHA256）
- 传输队列管理
### 阶段二：平台适配层实现（Platform Adaptation Phase）
**目标**：实现各平台的显示捕获和渲染功能
#### 2.1 Android 平台实现
- [ ] **显示捕获**（纯 C++ NDK Native API 实现）
- AImageReader（NDK ImageReader API）集成
- ANativeWindow 窗口操作
- AHardwareBuffer 零拷贝帧获取
- VirtualDisplay 创建（需要 MediaProjection token，仅权限请求）
- 屏幕分辨率检测
- 帧率控制
- GPU 缓冲区直接访问（零拷贝）
- [ ] **摄像头捕获**（纯 C++ NDK Native API 实现）
- NDK Camera API（ACameraManager, ACameraDevice）集成
- 摄像头设备枚举
- 视频流捕获
- 摄像头参数控制（分辨率、帧率、对焦等）
- 多摄像头支持
- [ ] **输入处理**
- 触摸事件捕获
- 输入事件转发
- [ ] **网络层**
- Android USB RNDIS 支持
- Wi-Fi 网络管理
- 网络权限处理
#### 2.2 Windows 平台实现
- [ ] **虚拟显示器**
- IddCx 驱动框架集成
- 虚拟显示器创建
- 分辨率动态调整
- [ ] **摄像头捕获**
- DirectShow / Media Foundation 集成
- 摄像头设备枚举
- 视频流捕获
- 摄像头参数控制
- 多摄像头支持
- [ ] **渲染引擎**
- DirectX 渲染管道
- 视频帧解码与显示
- 性能优化
- [ ] **输入处理**
- 键盘事件捕获
- 鼠标事件捕获
- 输入事件转发
- [ ] **网络层**
- USB RNDIS 检测
- Wi-Fi 网络管理
- 以太网支持
### 阶段三：角色层实现（Role Implementation Phase）
**目标**：实现 Host、Client、Peer 三种角色的完整功能
#### 3.1 主机角色（Host Role）
- [ ] 屏幕捕获集成
- [ ] 视频编码流水线
- [ ] 数据发送逻辑
- [ ] 一对多广播支持
- [ ] 性能监控与自适应
#### 3.2 客户端角色（Client Role）
- [ ] 数据接收逻辑
- [ ] 视频解码流水线
- [ ] 渲染显示集成
- [ ] 输入事件处理
- [ ] 延迟优化
#### 3.3 对等角色（Peer Role）
- [ ] 同时运行 Host 和 Client 逻辑
- [ ] 双向数据流管理
- [ ] 资源竞争处理
- [ ] 性能平衡
### 阶段四：集成与优化（Integration & Optimization Phase）
**目标**：整合各模块，优化性能，完善功能
#### 4.1 系统集成
- [ ] 端到端功能测试
- [ ] 多场景验证
- [ ] 错误处理与恢复
- [ ] 日志系统
#### 4.2 性能优化
- [ ] 延迟优化（目标 < 30ms）
- [ ] 带宽优化
- [ ] CPU/GPU 使用优化
- [ ] 内存管理优化
#### 4.3 稳定性提升
- [ ] 异常处理
- [ ] 网络断线重连
- [ ] 资源清理
- [ ] 压力测试
### 阶段五：测试与文档（Testing & Documentation Phase）
**目标**：完善测试覆盖，编写完整文档
#### 5.1 测试
- [ ] 单元测试覆盖
- [ ] 集成测试
- [ ] 跨平台兼容性测试
- [ ] 性能基准测试
#### 5.2 文档
- [ ] API 文档
- [ ] 架构设计文档
- [ ] 用户使用指南
- [ ] 开发者指南
- [ ] 部署文档
## 2. 技术选型
### 2.1 核心依赖
- **序列化**：Google FlatBuffers
- **编解码**：
- H.264：MediaCodec (Android) / Media Foundation (Windows)
- VP8：libvpx
- MJPEG：自定义实现
- **网络**：原生 Socket API + 平台特定网络库
- **NAT 穿透**：
- STUN/TURN 客户端（自实现或使用 libnice/libjuice）
- ICE 协议实现
- **构建系统**：CMake 3.15+
### 2.2 平台特定依赖
- **Android**：
- NDK r21+
- MediaProjection API
- Camera2 API / NDK Camera API
- USB Host API
- **Windows**：
- Windows SDK 10.0.19041.0+
- DirectX 11/12
- IddCx 1.4+
- DirectShow / Media Foundation（摄像头）
## 3. 开发优先级
### P0（核心功能，必须实现）
1. 核心网络抽象层
2. 基础协议定义
3. Android Host 角色
4. Windows Client 角色
5. USB RNDIS 连接支持
### P1（重要功能，优先实现）
1. 会话管理
2. 编解码器集成
3. 输入事件处理
4. Wi-Fi 连接支持
5. 性能优化
### P2（增强功能，后续实现）
1. Peer 角色支持
2. 一对多广播
3. 多种编解码器
4. 以太网支持
5. 高级性能调优
### P3（扩展功能，可选实现）
1. **文件传输功能**
- 基础文件传输
- 断点续传
- 多文件并发传输
- 传输进度和校验
2. **远程摄像头功能**
- 摄像头设备枚举
- 视频流捕获和传输
- 摄像头参数控制
- 多摄像头切换
3. **NAT 穿透功能（TURN/STUN）**
- STUN 客户端实现
- TURN 客户端实现
- ICE 协议集成
- 互联网连接支持
- 自动路径选择
## 4. 里程碑
### Milestone 1: 核心架构完成（4周）
- CMake 构建系统就绪
- 核心库基础模块框架完成
- 网络抽象层可用
- 协议定义完成
### Milestone 2: Android Host 可用（6周）
- Android 平台适配层完成
- 屏幕捕获功能实现
- 基础编码与发送功能
- 可通过 USB RNDIS 发送视频流
### Milestone 3: Windows Client 可用（8周）
- Windows 平台适配层完成
- 虚拟显示器创建
- 基础解码与渲染功能
- 可接收并显示视频流
### Milestone 4: 端到端可用（10周）
- Host-Client 完整流程打通
- 输入事件双向传输
- 基础性能达标（延迟 < 50ms）
- 稳定性基本保证
### Milestone 5: 生产就绪（12周+）
- 所有核心功能完成
- 性能优化达标（延迟 < 30ms）
- 测试覆盖充分
- 文档完整
### Milestone 6: 扩展功能（16周+）
- 文件传输功能完成
- 远程摄像头功能完成
- 扩展功能测试和优化
- 用户体验优化
## 5. 风险与应对
### 技术风险
1. **跨平台兼容性**
- 风险：不同平台 API 差异大
- 应对：充分抽象，建立完善的适配层
2. **性能瓶颈**
- 风险：延迟或帧率不达标
- 应对：早期性能测试，持续优化
3. **网络稳定性**
- 风险：不同网络环境下的连接问题
- 应对：完善的错误处理和重连机制
### 开发风险
1. **依赖管理**
- 风险：第三方库版本冲突
- 应对：使用 vcpkg/Conan 等包管理器
2. **测试环境**
- 风险：跨平台测试设备不足
- 应对：建立 CI/CD，自动化测试
## 6. 下一步行动
1. **立即开始**：
- 搭建项目目录结构
- 配置 CMake 构建系统
- 设置基础依赖（FlatBuffers）
2. **第一周目标**：
- 完成项目结构搭建
- CMake 可在 Windows 和 Android 上编译通过
- 创建核心库基础框架
- 定义 FlatBuffers Schema
3. **第一个月目标**：
- 网络抽象层实现
- 基础协议完成
- Android 平台适配层框架
- 简单的端到端测试

231
PROJECT_STRUCTURE.md
View File

@@ -1,231 +0,0 @@
# DisplayFlow 项目结构说明
## 目录结构
```
DisplayFlow/
├── CMakeLists.txt # 根 CMake 配置文件
├── .gitignore # Git 忽略文件配置
├── README.md # 项目概述和技术方案
├── DEVELOPMENT_PLAN.md # 详细开发计划
├── README_BUILD.md # 构建指南
├── PROJECT_STRUCTURE.md # 本文件：项目结构说明
│
├── core/ # 跨平台核心库
│ ├── CMakeLists.txt
│ ├── include/
│ │ └── displayflow/
│ │ └── core/
│ │ ├── common/ # 通用类型和常量
│ │ │ ├── types.h
│ │ │ └── constants.h
│ │ ├── network/ # 网络抽象层
│ │ │ ├── network_manager.h
│ │ │ ├── network_interface.h
│ │ │ ├── nat_traversal/ # NAT 穿透模块
│ │ │ │ ├── stun_client.h
│ │ │ │ ├── turn_client.h
│ │ │ │ ├── ice_agent.h
│ │ │ │ ├── candidate.h
│ │ │ │ └── nat_type.h
│ │ ├── protocol/ # 协议层
│ │ │ ├── protocol_handler.h
│ │ │ └── message_serializer.h
│ │ ├── session/ # 会话管理
│ │ │ ├── session_manager.h
│ │ │ └── session.h
│ │ ├── codec/ # 编解码抽象
│ │ │ ├── codec_manager.h
│ │ │ └── codec_interface.h
│ │ ├── role/ # 角色管理
│ │ │ ├── role_manager.h
│ │ │ ├── role_interface.h
│ │ │ ├── host_role.h
│ │ │ ├── client_role.h
│ │ │ └── peer_role.h
│ │ ├── file_transfer/ # 文件传输模块
│ │ │ ├── file_transfer_manager.h
│ │ │ ├── file_transfer_session.h
│ │ │ ├── file_chunk.h
│ │ │ └── transfer_progress.h
│ │ └── utils/ # 工具类
│ │ ├── logger.h
│ │ └── timer.h
│ └── src/ # 对应的源文件实现
│ ├── network/
│ │ └── nat_traversal/
│ ├── protocol/
│ ├── session/
│ ├── codec/
│ ├── role/
│ ├── file_transfer/
│ └── utils/
│
├── platforms/ # 平台适配层
│ ├── android/ # Android 平台实现
│ │ ├── CMakeLists.txt
│ │ ├── include/
│ │ │ └── displayflow/
│ │ │ └── platform/
│ │ │ └── android/
│ │ │ ├── platform_adapter.h
│ │ │ ├── capture/ # 捕获模块
│ │ │ │ ├── screen_capture.h
│ │ │ │ ├── media_projection_wrapper.h
│ │ │ │ └── camera_capture.h # 摄像头捕获
│ │ │ ├── render/ # 渲染引擎
│ │ │ │ └── render_engine.h
│ │ │ ├── input/ # 输入处理
│ │ │ │ └── touch_handler.h
│ │ │ └── network/ # 网络管理
│ │ │ └── android_network_manager.h
│ │ └── src/ # 对应的源文件实现
│ │ ├── capture/
│ │ │ ├── screen_capture.cpp
│ │ │ ├── media_projection_wrapper.cpp
│ │ │ └── camera_capture.cpp
│ │ ├── render/
│ │ ├── input/
│ │ ├── network/
│ │ └── platform_adapter.cpp
│ │
│ └── windows/ # Windows 平台实现
│ ├── CMakeLists.txt
│ ├── include/
│ │ └── displayflow/
│ │ └── platform/
│ │ └── windows/
│ │ ├── platform_adapter.h
│ │ ├── virtual_display/ # 虚拟显示器
│ │ │ ├── virtual_display.h
│ │ │ └── iddcx_wrapper.h
│ │ ├── capture/ # 捕获模块
│ │ │ └── camera_capture.h # 摄像头捕获
│ │ ├── render/ # 渲染引擎
│ │ │ ├── directx_renderer.h
│ │ │ └── d3d11_renderer.h
│ │ ├── input/ # 输入处理
│ │ │ ├── keyboard_handler.h
│ │ │ └── mouse_handler.h
│ │ └── network/ # 网络管理
│ │ └── windows_network_manager.h
│ └── src/ # 对应的源文件实现
│ ├── virtual_display/
│ ├── capture/
│ │ └── camera_capture.cpp
│ ├── render/
│ ├── input/
│ ├── network/
│ └── platform_adapter.cpp
│
├── docs/ # 文档目录
│ ├── ARCHITECTURE.md # 架构设计文档
│ └── API.md # API 文档
│
├── prototypes/ # 原型和测试代码
│ └── README.md
│
└── tools/ # 开发工具脚本
└── README.md
```
## 模块说明
### 核心库 (core/)
100% 跨平台的业务逻辑实现，不依赖任何平台特定 API。
- **common/**: 基础类型定义和常量
- **network/**: 网络抽象层，统一管理 RNDIS、Wi-Fi、以太网
- **nat_traversal/**: NAT 穿透模块（STUN/TURN/ICE）
- **protocol/**: 基于 FlatBuffers 的协议定义和序列化
- **session/**: 会话生命周期管理
- **codec/**: 编解码器抽象接口和管理
- **role/**: 角色（Host/Client/Peer）实现
- **file_transfer/**: 文件传输模块（断点续传、多文件传输）
- **utils/**: 通用工具类（日志、定时器等）
### 平台适配层 (platforms/)
各平台特定功能的薄封装层。
#### Android
- **capture/**:
- 屏幕捕获（MediaProjection API 封装）
- 摄像头捕获（Camera2 API / NDK Camera API）
- **render/**: 渲染引擎（用于 Client 角色）
- **input/**: 触摸输入处理
- **network/**: Android 网络管理（USB RNDIS、Wi-Fi）
#### Windows
- **virtual_display/**: IddCx 驱动框架封装，创建虚拟显示器
- **capture/**:
- 摄像头捕获（DirectShow / Media Foundation）
- **render/**: DirectX 渲染引擎
- **input/**: 键盘和鼠标输入处理
- **network/**: Windows 网络管理（USB RNDIS、Wi-Fi、以太网）
## 命名空间
- `displayflow::core` - 核心库
- `displayflow::platform::android` - Android 平台适配
- `displayflow::platform::windows` - Windows 平台适配
## 构建系统
使用 CMake 作为统一构建系统：
- 根目录 `CMakeLists.txt` 负责平台检测和子目录管理
- 各模块有独立的 `CMakeLists.txt`
- 支持条件编译，根据平台自动选择对应的适配层
## 当前状态
所有基础框架文件已创建，包含：
- ✅ 完整的目录结构
- ✅ 所有头文件和源文件占位符
- ✅ CMake 构建配置
- ✅ 基础类型和接口定义
**下一步**：开始实现核心功能模块。
## 新增功能模块
### 文件传输模块 (core/file_transfer/)
支持在设备间传输文件，特性包括：
- 断点续传
- 多文件并发传输
- 传输进度监控
- 文件校验（MD5/SHA256）
- 传输队列管理
### 远程摄像头模块
支持使用对方的摄像头作为视频源，特性包括：
- 摄像头设备枚举和选择
- 视频流捕获和编码
- 与屏幕共享复用相同的传输通道
- 支持多摄像头切换
- 摄像头参数控制（分辨率、帧率等）
### NAT 穿透模块 (core/network/nat_traversal/)
支持通过互联网连接设备，突破局域网限制，特性包括：
- **STUN 客户端**：NAT 类型检测和公网 IP 发现
- **TURN 客户端**：中继服务器支持（当直连失败时）
- **ICE 协议**：自动选择最佳连接路径
- **候选地址收集**：收集本地、STUN、TURN 候选地址
- **连接建立**：自动尝试多种连接方式，选择最优路径
**连接方式优先级：**
1. 局域网直连（最快）
2. 公网直连（通过 STUN 发现）
3. TURN 中继（最慢但最可靠）
**架构优势：**
- 文件传输复用现有的网络抽象层和协议层
- 摄像头捕获复用现有的编码和传输机制
- NAT 穿透完全透明，上层无需关心连接方式
- 完全集成到现有角色模型中
- 保持跨平台兼容性

299
README.md
View File

@@ -1,150 +1,205 @@
# 跨平台虚拟显示协作系统技术方案
# DisplayFlow - 跨设备无缝互联协作平台
## 1. 项目概述
本项目旨在构建一个高性能、高灵活性的虚拟显示协作系统。其核心目标是打破传统副屏方案在平台、角色和连接方式上的限制，实现任何设备、任何角色、任何网络下的无缝显示扩展与协作。
本项目旨在构建一个高性能、高灵活性的**跨设备无缝互联协作平台**。其核心目标是打破传统设备间的物理与系统边界，不仅实现屏幕的自由扩展，更打通**显示、控制、数据与外设**的隔阂，让多台设备像一个整体一样协同工作。
**核心愿景**：打造一个"显示即服务"的通用平台，让显示资源能够在设备间自由流动。
**核心愿景**：打造一个"无界协同"的通用生态，让显示、输入与数据资源能够在设备间自由流动。
## 2. 核心设计理念与突出优势
---
本方案摒弃了"主机-客户端"的固化思维，采用全新的"角色-平台-连接"解耦设计，从而实现三大核心优势：
## 2. 核心设计理念与优势
### 2.1 真正跨平台：同一套核心代码支持所有目标平台
本方案摒弃了"主机-客户端"的固化思维，采用全新的"角色-平台-连接"解耦设计：
- **核心共享库（Platform-Agnostic Core）**：将所有业务逻辑（协议、会话管理、编解码、网络抽象）封装为100%跨平台的C++核心库。平台相关代码（显示渲染、输入捕获）被严格隔离为薄薄的适配层。
### 2.1 真正跨平台
- **核心共享库（Platform-Agnostic Core）**：将所有业务逻辑（协议、会话管理、编解码、网络抽象）封装为100%跨平台的C++核心库。
- **技术实现**：CMake统一构建，Android NDK / Windows MSVC 条件编译。核心算法、协议在所有平台间完全一致。
- **受益**：一次开发，多平台部署（Android, Windows, 规划中: Linux, macOS）。
- **技术实现**：使用CMake作为统一的构建系统，通过条件编译链接不同的平台适配层。核心算法、数据结构和通信协议在所有平台间完全一致，确保行为统一，极大降低开发和维护成本。
### 2.2 角色灵活
系统内置三种基础角色，设备可动态切换：
1. **主机（Host）**：提供显示内容（如：Android平板共享屏幕）。
2. **客户端（Client）**：接收并显示内容（如：PC将平板作为副屏）。
3. **对等端（Peer）**：同时作为主机和客户端（如：双人互动画板）。
- **受益**：一次开发，多平台部署。目前支持Android、Windows，未来可快速扩展至Linux、macOS乃至嵌入式系统。
### 2.3 连接通用
- **局域网优先**：USB RNDIS（极低延迟）、Wi-Fi（便捷）。
- **互联网穿透**：集成 STUN/TURN/ICE 协议，实现 NAT 穿透，支持公网远程协作。
- **智能切换**：NetworkManager 自动探测并选择最佳链路（RNDIS > Wi-Fi > Relay）。
### 2.2 角色灵活：任何设备可动态充当任何角色
---
- **角色抽象（Role Agnostic）**：系统内置三种基础角色，设备可动态切换或同时兼任：
1. **主机（Host）**：提供显示内容来源。示例：Android平板共享屏幕。
2. **客户端（Client）**：接收并显示内容。示例：Windows电脑将平板屏幕作为副屏。
3. **对等端（Peer）**：同时作为主机和客户端，实现双向屏幕共享。示例：两个安卓设备互作副屏。
## 3. 全景功能规划 (Feature List)
- **技术实现**：通过RoleManager进行动态角色管理和切换。会话协议中携带角色信息，使通信双方能正确理解数据流方向。
### 3.1 核心投屏体验
- [x] **Windows 投屏到 Android**: 将 Android 平板/手机作为 Windows 的扩展副屏或镜像屏。
- [ ] **Android 投屏到 Windows**: 将 Android 屏幕画面实时投射到 Windows 电脑。
- [ ] **Android 投屏到 Android**: 两台移动设备间的屏幕共享与互动。
- **受益**：应用场景极大丰富，从简单的副屏扩展到复杂的多设备协作演示、双向画板等。
### 3.2 高级交互功能
- [ ] **反向触控**: 在 Android 端触摸屏幕，控制 Windows 的鼠标光标（支持多点触控映射）。
- [ ] **反向键鼠**: 在 Windows 端使用键盘鼠标，操作 Android 设备界面。
- [ ] **剪贴板同步**: 跨设备实时的文本/图片剪贴板共享。
- [ ] **音频流传输**: 系统声音随视频画面同步传输（支持 WASAPI Loopback）。
### 2.3 连接通用：支持局域网和互联网连接
### 3.3 生产力扩展
- [ ] **双向文件传输**: 支持拖拽发送文件，断点续传。
- [ ] **摄像头投屏**: 将 Android 手机摄像头作为 Windows 的高清网络摄像头。
- [ ] **虚拟扩展屏驱动**: 基于 IddCx 的虚拟显示器驱动，非镜像模式，真正的第二屏幕。
- **网络抽象层（Network Agnostic）**：设计统一的网络接口，自动选择或同时管理多种连接方式。
- **局域网连接**（优先使用）：
- **USB RNDIS**：优先使用，提供近似有线的高带宽、低延迟体验。
- **Wi-Fi 局域网**：提供无线便利性，支持一对多广播。
- **有线以太网**：为台式机等设备提供稳定连接。
- **互联网连接**（通过 NAT 穿透）：
- **STUN**：NAT 类型检测和公网 IP 发现，支持公网直连。
- **TURN**：中继服务器支持，当直连失败时自动切换。
- **ICE 协议**：自动选择最佳连接路径（局域网 > 公网直连 > TURN 中继）。
### 3.4 网络与连接
- [ ] **mDNS 设备发现**: 局域网内自动发现可连接设备，无需手动输入 IP。
- [ ] **USB 有线连接**: 支持 USB RNDIS 模式，实现 <30ms 的超低延迟。
- [ ] **远程连接**: 支持跨广域网连接，在家连接公司电脑。
- **技术实现**：NetworkManager负责探测可用连接，根据性能（延迟、带宽）自动优选或负载均衡。集成 ICE 协议实现 NAT 穿透，支持局域网和互联网无缝切换。应用层无需关心底层连接方式。
---
- **受益**：用户无需手动配置网络，系统自动选择最佳路径。支持跨网络、跨地域的设备连接，突破局域网限制，实现真正的远程协作。
### 2.4 扩展性强：轻松支持新设备类型与未来场景
- **模块化架构**：核心、平台、角色三大模块界限清晰，通过标准接口通信。
- **易于扩展**：
- **新平台**：实现对应的Platform Adapter（显示、输入）即可接入。
- **新角色**：在角色模型中定义新角色类型及其行为。
- **新功能**：如AR/VR流传输，可在协议中增加新的数据帧类型，无需重构。
- **受益**：技术生命周期长，能快速适应未来新的硬件和设备形态。
## 3. 系统架构设计
### 3.1 软件架构图
## 4. 系统与工程架构
### 4.1 逻辑架构图
```
[ 应用层 ]
|
[ 角色层 (Role Layer) ] <- Host, Client, Peer 角色实现
|
[ 平台适配层 (Platform Adapter) ] <- Android显示捕获 / Windows DirectX渲染
|
[ 核心层 (Core Layer) ] <- 会话管理、协议、编解码、网络抽象 (100%跨平台)
|
[ 传输层 (Transport Layer) ] <- 局域网（RNDIS/USB、Wi-Fi、以太网）、互联网（STUN/TURN/ICE）
[ 应用层 (Qt/Kotlin) ]
|
[ 角色层 (Host/Client/Peer) ]
|
[ 平台适配层 (Platform Adapter) ] <-> (DXGI, MediaCodec, Camera2, IDD)
|
[ 核心层 (Core Shared Lib) ] <-> (Session, Protocol, Codec Interface)
|
[ 传输层 (Transport) ] <-> (UDP/TCP, ICE, WiFi/USB)
```
### 3.2 核心模块说明
1. **核心共享库（Core）**：包含整个系统的"大脑"，完全跨平台。
- **会话管理**：创建、维护、销毁显示会话，支持一对多。
- **通用协议**：基于Google FlatBuffers的跨平台序列化，定义视频帧、输入事件等。
- **编解码器**：支持H.264（硬件加速）/VP8（软件）/MJPEG等多种编解码器，自适应选择。
- **网络抽象**：统一管理RNDIS、WiFi等局域网连接，以及STUN/TURN/ICE互联网连接，提供可靠UDP传输。
2. **平台适配层（Platforms）**：各平台特有功能的薄封装。
- **Android**：通过MediaProjection捕获屏幕，ImageReader获取帧，处理触摸输入。
- **Windows**：使用DirectX进行高效渲染，通过IddCx驱动框架实现真虚拟显示器，处理键鼠输入。
3. **角色层（Roles）**：实现不同的协作模式。
- **主机角色**：负责屏幕捕获、编码、发送。
- **客户端角色**：负责接收、解码、渲染。
- **对等角色**：同时运行主机和客户端逻辑。
## 4. 典型应用场景
**场景一：高效办公（Android -> Windows）**
- **描述**：用户通过USB RNDIS将安卓平板连接至Windows电脑。
- **角色**：Android设备作为主机（Host），Windows电脑作为客户端（Client）。
- **价值**：平板屏幕变为电脑的低延迟副屏，用于扩展显示代码文档、聊天工具，提升桌面工作效率。
**场景二：会议演示（一对多广播）**
- **描述**：讲者的安卓平板通过Wi-Fi将屏幕内容广播到会议室的多台设备。
- **角色**：Android设备作为主机（Host），多台Windows电脑/安卓电视/平板作为客户端（Client）。
- **价值**：无需线缆，即可实现一人屏幕、多人同步观看，适用于教学、培训和会议。
**场景三：移动协作（Android <-> Android，对等模式）**
- **描述**：两名设计师的安卓平板通过Wi-Fi建立对等（Peer）​ 会话。
- **角色**：两台Android设备均作为对等端（Peer），即同时兼任主机和客户端。
- **价值**：每人的平板上同时显示自己和对方的屏幕，实现真正的双向实时画板协作，创意无缝对接。
**场景四：移动协作（Android -> Android，主从模式）**
- **描述**：用户将手中的安卓手机（高性能）屏幕，扩展至另一台安卓平板（大屏幕）上显示。
- **角色**：安卓手机作为主机（Host），安卓平板作为客户端（Client）。
- **价值**：充分发挥设备特性。用户可在手机上进行私密操作（如游戏、使用特定APP），而将主画面投送至平板大屏上进行展示或共享，兼顾隐私与分享需求。这充分体现了角色的灵活性——安卓设备可根据需求，自由扮演主机或客户端的角色。
**场景五：远程协作（跨网络、跨地域）**
- **描述**：用户在家中通过互联网连接到办公室的 Windows 电脑，实现远程显示扩展。
- **角色**：办公室 Windows 电脑作为主机（Host），家中设备作为客户端（Client）。
- **连接方式**：通过 STUN/TURN 服务器实现 NAT 穿透，自动选择最佳连接路径。
- **价值**：突破局域网限制，支持跨网络、跨地域的设备连接。无论设备在哪里，只要有互联网连接，就能实现无缝显示协作。适用于远程办公、技术支持、远程演示等场景。
## 5. 技术规格与指标
- **支持平台**：Android 5.0+， Windows 10/11
- **最大分辨率**：4K（依赖设备性能）
- **最大帧率**：60 FPS
- **端到端延迟**：< 30ms （USB RNDIS模式下）
- **最大客户端数量**：理论上无限制，实践中受网络带宽和主机性能约束（建议≤20）
## 6. Git仓库结构建议
### 4.2 工程目录结构
```
DisplayFlow/
├── core/ # 跨平台核心库
├── platforms/
│ ├── android/ # Android平台实现
│ └── windows/ # Windows平台实现
├── docs/ # 文档
├── prototypes/ # 原型和测试代码
└── tools/ # 开发工具脚本
├── CMakeLists.txt # 根构建脚本 (统一管理多平台)
├── README.md # 本文档
│
├── core/ # [核心库] 100% 跨平台业务逻辑
│ ├── include/displayflow/core/
│ │ ├── common/ # 基础类型 (types.h, constants.h)
│ │ ├── network/ # 网络抽象 (NetworkManager, NAT Traversal)
│ │ ├── protocol/ # 协议定义 (FlatBuffers Schema)
│ │ ├── session/ # 会话管理 (Host/Client Session)
│ │ ├── codec/ # 编解码接口抽象
│ │ ├── role/ # 角色状态机 (Host/Client/Peer)
│ │ ├── file_transfer/ # 文件传输逻辑
│ │ └── utils/ # 日志、工具类
│ └── src/ # 核心库实现 (.cpp)
│
├── platforms/ # [适配层] 平台特定实现
│ ├── android/
│ │ ├── include/ # JNI 接口, MediaCodec 封装
│ │ └── src/ # 屏幕捕获, 音频采集, Touch 注入
│ └── windows/
│ ├── include/ # DXGI, Media Foundation, IDD 封装
│ └── src/ # 鼠标键盘注入, 虚拟显示驱动桥接
│
├── demo/ # [验证原型] 快速验证 Demo
│ ├── android_receiver/ # Android 接收端 App (Kotlin + C++)
│ ├── windows_sender/ # Windows 发送端 App (C++)
│ └── windows_driver/ # IDD 虚拟显示驱动原型
│
├── docs/ # 设计文档
├── tests/ # 单元测试
└── tools/ # 辅助脚本
```
## 7. 技术栈
完全由C++实现
### 4.3 核心模块职责
* **Core (C++ Shared Lib)**: 整个系统的“大脑”。处理握手、协议解析、分包重组、状态管理。它不知道自己运行在 Windows 还是 Android 上，只通过接口与外部交互。
* **Platforms (Adapter)**: 系统的“手脚”。
* **Android**: 负责调用 `MediaProjection` 抓屏，`MediaCodec` 解码，`InputManager` 注入触摸。
* **Windows**: 负责调用 `DXGI` 抓屏，`SendInput` 注入键鼠，`IddCx` 创建虚拟屏。
## 8. 总结
---
本方案通过真正跨平台的核心设计、动态角色分配和多连接方式抽象，突破了现有副屏方案的局限性。它不仅仅是一个"副屏工具"，更是一个为未来多设备协作世界打造的、极具扩展性的通用显示协作平台。该架构确保了项目在性能、灵活性和可持续性上的领先优势。
## 5. 技术栈与选型
### 5.1 核心依赖
- **语言**: C++ 17 (Core), Kotlin (Android UI), C++/WinRT (Windows UI)
- **构建系统**: CMake 3.15+
- **序列化**: Google FlatBuffers (高性能、零拷贝)
- **网络**: BSD Sockets (UDP/TCP), STUN/TURN/ICE (NAT穿透)
### 5.2 编解码方案
- **视频编码**:
- Windows: FFmpeg (x264) / Media Foundation (H.264 Hardware)
- Android: AMediaCodec (NDK Hardware Encoder)
- **视频解码**:
- Windows: FFmpeg / D3D11VA
- Android: AMediaCodec (NDK Hardware Decoder) -> ANativeWindow
### 5.3 平台特定技术
- **Windows**: Desktop Duplication API (DXGI), Indirect Display Driver (IddCx), SendInput API.
- **Android**: MediaProjection API, AImageReader, Android NDK, AccessibilityService (用于全局触控注入).
---
## 6. 开发计划与里程碑
### 阶段一：核心架构搭建 (Foundation Phase) - [已完成]
**目标**：建立跨平台核心库的基础架构和构建系统。
- [x] 配置 CMake 作为统一构建系统。
- [x] 设置跨平台编译配置 (Android NDK, Windows MSVC)。
- [x] 建立核心库目录结构。
- [x] 实现基础 UDP 网络发送与接收 Demo。
### 阶段二：Windows 发送端实现 (Windows Sender) - [已完成]
**目标**：实现高性能 Windows 屏幕抓取与编码。
- [x] **DXGI Capture**: 实现 Desktop Duplication API 零拷贝抓屏。
- [x] **FFmpeg Encoding**: 集成 x264，配置 `zerolatency` 低延迟编码。
- [x] **UDP Transport**: 实现自定义分片协议发送。
- [x] **IDD Simulation**: 验证虚拟显示驱动的管道连通性。
### 阶段三：Android 接收端实现 (Android Receiver) - [进行中]
**目标**：实现 Android 端的高性能接收与渲染。
- [ ] **JNI 桥接**: 建立 Java (Surface) 与 C++ Native 层的通道。
- [ ] **Network Layer**: 移植 Demo 中的 `UdpReceiver` 到 Android NDK 环境。
- [ ] **Decoder**: 实现 `AMediaCodec` (NDK) H.264 硬解码。
- [ ] **Renderer**: 将解码后的 Buffer 直接渲染到 `ANativeWindow` (Surface)。
- [ ] **Latency Optimization**: 调优 Jitter Buffer，目标端到端延迟 < 50ms。
### 阶段四：高级功能迭代 (Advanced Features) - [规划中]
**优先级 P0 (核心体验)**
1. **反向控制**: Android 捕获 Touch 事件 -> TCP -> Windows `SendInput`。
2. **设备发现**: 集成 mDNS (Bonjour/NsdManager)，局域网自动发现。
**优先级 P1 (生产力工具)**
1. **文件传输**: TCP 通道，拖拽发送，断点续传。
2. **剪贴板同步**: 监听系统剪贴板变化，差异同步。
**优先级 P2 (扩展能力)**
1. **虚拟扩展屏**: IddCx 驱动产品化，实现真正的扩展屏模式。
2. **音频同步**: WASAPI Loopback 捕获 -> Opus 编码 -> 传输 -> 解码播放。
3. **摄像头投屏**: Android Camera2 API 采集 -> 视频流传输 -> Windows 虚拟摄像头驱动。
---
## 7. 典型应用场景
1. **高效办公 (Win + Android)**: 平板作为电脑副屏，浏览文档、即时通讯。
2. **会议演示 (One-to-Many)**: 一台设备讲演，多台设备实时同步观看。
3. **远程协助 (Internet)**: 远程控制家中/公司电脑，进行维护或操作。
4. **移动协作 (Android <-> Android)**: 双人画板，创意实时同步。
---
## 8. 技术规格
- **支持平台**：Android 5.0+, Windows 10/11
- **分辨率**：支持 720p, 1080p, 2K, 4K (自适应)
- **帧率**：30/60 FPS
- **延迟**：< 30ms (USB RNDIS), < 60ms (Wi-Fi 5G)
- **并发数**：支持 1 对多广播 (取决于 Host 带宽)
---
## 9. 风险与应对
1. **网络抖动**:
* *应对*: 引入 FEC (前向纠错) 和 NACK 重传机制；Jitter Buffer 自适应调整。
2. **Android 碎片化**:
* *应对*: 优先使用标准 NDK API (AMediaCodec, AImageReader)；建立机型白名单。
3. **驱动签名**:
* *应对*: 开发阶段使用测试签名模式；发布时申请微软 WHQL 认证或 EV 证书。

39
README_BUILD.md
View File

@@ -1,39 +0,0 @@
# DisplayFlow 构建指南
> **注意**: 详细的构建指南请参考 [BUILD_GUIDE.md](BUILD_GUIDE.md)
## 快速开始
### Windows
```batch
scripts\build.bat Release
```
### Linux/macOS
```bash
chmod +x scripts/build.sh
./scripts/build.sh Release
```
### Android
```bash
export ANDROID_NDK=/path/to/android-ndk
mkdir build-android && cd build-android
cmake .. \
-DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
-DANDROID_ABI=arm64-v8a \
-DANDROID_PLATFORM=android-21
cmake --build .
```
## 主要构建选项
- `BUILD_TESTS=ON`: 启用测试
- `ENABLE_VP8_CODEC=ON`: 启用 VP8 编解码器
- `USE_SYSTEM_FLATBUFFERS=ON`: 使用系统 FlatBuffers
详细说明请参考 [BUILD_GUIDE.md](BUILD_GUIDE.md)