DisplayFlow/README.md

# DisplayFlow - 跨设备无缝互联协作平台

## 1. 项目概述

本项目旨在构建一个高性能、高灵活性的**跨设备无缝互联协作平台**。其核心目标是打破传统设备间的物理与系统边界，不仅实现屏幕的自由扩展，更打通**显示、控制、数据与外设**的隔阂，让多台设备像一个整体一样协同工作。

**核心愿景**：打造一个"无界协同"的通用生态，让显示、输入与数据资源能够在设备间自由流动。

---

## 2. 核心设计理念与优势

本方案摒弃了"主机-客户端"的固化思维，采用全新的"角色-平台-连接"解耦设计：

### 2.1 真正跨平台
- **核心共享库（Platform-Agnostic Core）**：将所有业务逻辑（协议、会话管理、编解码、网络抽象）封装为100%跨平台的C++核心库。
- **技术实现**：CMake统一构建，Android NDK / Windows MSVC 条件编译。核心算法、协议在所有平台间完全一致。
- **受益**：一次开发，多平台部署（Android, Windows, 规划中: Linux, macOS）。

### 2.2 角色灵活
系统内置三种基础角色，设备可动态切换：
1.  **主机（Host）**：提供显示内容（如：Android平板共享屏幕）。
2.  **客户端（Client）**：接收并显示内容（如：PC将平板作为副屏）。
3.  **对等端（Peer）**：同时作为主机和客户端（如：双人互动画板）。

### 2.3 连接通用
- **局域网优先**：USB RNDIS（极低延迟）、Wi-Fi（便捷）。
- **互联网穿透**：集成 STUN/TURN/ICE 协议，实现 NAT 穿透，支持公网远程协作。
- **智能切换**：NetworkManager 自动探测并选择最佳链路（RNDIS > Wi-Fi > Relay）。

---

## 3. 全景功能规划 (Feature List)

### 3.1 核心投屏体验
- [x] **Windows 投屏到 Android**: 将 Android 平板/手机作为 Windows 的扩展副屏或镜像屏。
- [ ] **Android 投屏到 Windows**: 将 Android 屏幕画面实时投射到 Windows 电脑。
- [ ] **Android 投屏到 Android**: 两台移动设备间的屏幕共享与互动。

### 3.2 高级交互功能
- [ ] **反向触控**: 在 Android 端触摸屏幕，控制 Windows 的鼠标光标（支持多点触控映射）。
- [ ] **反向键鼠**: 在 Windows 端使用键盘鼠标，操作 Android 设备界面。
- [ ] **剪贴板同步**: 跨设备实时的文本/图片剪贴板共享。
- [ ] **音频流传输**: 系统声音随视频画面同步传输（支持 WASAPI Loopback）。

### 3.3 生产力扩展
- [ ] **双向文件传输**: 支持拖拽发送文件，断点续传。
- [ ] **摄像头投屏**: 将 Android 手机摄像头作为 Windows 的高清网络摄像头。
- [ ] **虚拟扩展屏驱动**: 基于 IddCx 的虚拟显示器驱动，非镜像模式，真正的第二屏幕。

### 3.4 网络与连接
- [ ] **mDNS 设备发现**: 局域网内自动发现可连接设备，无需手动输入 IP。
- [ ] **USB 有线连接**: 支持 USB RNDIS 模式，实现 <30ms 的超低延迟。
- [ ] **远程连接**: 支持跨广域网连接，在家连接公司电脑。

---

## 4. 系统与工程架构

### 4.1 逻辑架构图
```
[ 应用层 (Qt/Kotlin) ]
       |
[ 角色层 (Host/Client/Peer) ]
       |
[ 平台适配层 (Platform Adapter) ] <-> (DXGI, MediaCodec, Camera2, IDD)
       |
[ 核心层 (Core Shared Lib) ]      <-> (Session, Protocol, Codec Interface)
       |
[ 传输层 (Transport) ]            <-> (UDP/TCP, ICE, WiFi/USB)
```

### 4.2 工程目录结构
```
DisplayFlow/
├── 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/                      # 辅助脚本
```

### 4.3 核心模块职责
*   **Core (C++ Shared Lib)**: 整个系统的“大脑”。处理握手、协议解析、分包重组、状态管理。它不知道自己运行在 Windows 还是 Android 上，只通过接口与外部交互。
*   **Platforms (Adapter)**: 系统的“手脚”。
    *   **Android**: 负责调用 `MediaProjection` 抓屏，`MediaCodec` 解码，`InputManager` 注入触摸。
    *   **Windows**: 负责调用 `DXGI` 抓屏，`SendInput` 注入键鼠，`IddCx` 创建虚拟屏。

---

## 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 证书。