From c3d7753add60d636e983465794938d8ae82a8fb6 Mon Sep 17 00:00:00 2001 From: huanglinhuan Date: Tue, 13 Jan 2026 22:55:43 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BUILD_GUIDE.md | 180 ------------------------ DEVELOPMENT_PLAN.md | 324 ------------------------------------------- PROJECT_STRUCTURE.md | 231 ------------------------------ README.md | 299 +++++++++++++++++++++++---------------- README_BUILD.md | 39 ------ 5 files changed, 177 insertions(+), 896 deletions(-) delete mode 100644 BUILD_GUIDE.md delete mode 100644 DEVELOPMENT_PLAN.md delete mode 100644 PROJECT_STRUCTURE.md delete mode 100644 README_BUILD.md diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md deleted file mode 100644 index f877505..0000000 --- a/BUILD_GUIDE.md +++ /dev/null @@ -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 . -``` - -这会启用调试符号和测试支持。 - - - diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md deleted file mode 100644 index c95f04b..0000000 --- a/DEVELOPMENT_PLAN.md +++ /dev/null @@ -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 平台适配层框架 - - 简单的端到端测试 - diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md deleted file mode 100644 index bb4621f..0000000 --- a/PROJECT_STRUCTURE.md +++ /dev/null @@ -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 穿透完全透明，上层无需关心连接方式 -- 完全集成到现有角色模型中 -- 保持跨平台兼容性 - diff --git a/README.md b/README.md index 1c91a5e..8e88eb2 100644 --- a/README.md +++ b/README.md @@ -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 证书。 diff --git a/README_BUILD.md b/README_BUILD.md deleted file mode 100644 index 13af391..0000000 --- a/README_BUILD.md +++ /dev/null @@ -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) -