132 lines
5.8 KiB
Markdown
132 lines
5.8 KiB
Markdown
# QFT · 超速二维码文件传输 v0.3.0-rc3
|
||
|
||
Windows + Android 双向候选版。两个方向采用不同链路:
|
||
|
||
- **Windows → Android:纯光学**。文件数据只经过 Windows 屏幕 → Android 摄像头;不使用 Wi‑Fi、蓝牙、局域网或互联网。
|
||
- **Android → Windows:扫码本地直连**。Windows 选择保存目录并启动 QFT Direct 临时 Wi‑Fi/接收服务;Android 扫码后请求配网、自动发现电脑,然后并行分块上传。文件不经过外网。
|
||
|
||
> rc3 是性能/兼容性候选版。仓库内的协议、二维码、并行上传、UDP 发现、内存预算与 Kotlin 关键源文件测试已通过;真正的 Windows Wi‑Fi Direct 驱动、Windows 防火墙、60Hz 显示器与不同 Android 相机组合仍必须在真实设备上做验收,详见 `TEST_REPORT.md`。
|
||
|
||
## v0.3.0-rc3 针对性优化
|
||
|
||
### 1. Windows → Android:最高 60 FPS 显示目标
|
||
|
||
- Windows UI 支持 `1~60 FPS`,提供 15/30/60 与“极速预设”。
|
||
- 默认 **4 QR/页 + 60 FPS**,每次刷新最多承载 4 个独立 QFT1 数据帧。
|
||
- 单 QR payload 默认 900 B;理论原始文件载荷约 `900 × 4 × 60 = 216,000 B/s`(约 210.9 KiB/s),实际速度取决于显示器刷新率、Android 相机 FPS、曝光/滚动快门和识别率。
|
||
- Android 光学扫描采用 1280×720 分析帧、4 象限并行 ZXing 解码、`KEEP_ONLY_LATEST`、Y 平面直接读取且不再整帧旋转。
|
||
- Windows 预编码使用 Rayon 多核并行;GPU 纹理复用,不再每帧创建新的纹理对象。
|
||
- UI 动态显示目标 FPS、实际页面 FPS、理论载荷和 Android 实际“相机 FPS / 有效 QR/s”。
|
||
|
||
### 2. 文件与内存优化
|
||
|
||
- Windows 光学源文件不做整文件 mmap;使用定位读取,避免大文件被整体映射/触碰进工作集。
|
||
- 预编码缓存硬设计目标:整进程约 **≤ 1100 MiB**。
|
||
- 4 QR / 960px 模式缓存最多 192 页,估算约 **675 MiB**;另为 UI、WGPU/GPU staging、线程栈、二维码临时对象和系统 I/O 留出余量。
|
||
- Android → Windows 每个文件内部最高 **8 路并行**。
|
||
- 分块根据文件大小自适应:小文件 4 MiB、中型 8 MiB、大文件 16 MiB;每个 worker 仅使用约 1 MiB 应用层 I/O buffer。
|
||
- Windows 端预分配 `.qftpart`,多个独立文件句柄按 offset 写入,完成后 SHA-256 校验并原子改名。
|
||
|
||
### 3. Android → Windows:连接速度/稳定性
|
||
|
||
扫码二维码升级到更短的 `QFTPAIR2`:
|
||
|
||
- 短字段 JSON + Base64URL。
|
||
- 配对 QR 使用中等级纠错,候选测试为 QR version 10。
|
||
- QFT Direct 二维码携带一个快速 endpoint hint,同时保留真实 Wi‑Fi 网关、UDP 发现与当前子网扫描作为 fallback。
|
||
- Android 配对扫描分辨率降到 640×480,优先 GlobalHistogram 快速路径;失败才周期性使用 HybridBinarizer。
|
||
- Android 连接 Wi‑Fi 后不立即假定网络可用,而是等待真实 IPv4/route。
|
||
- 电脑发现顺序:
|
||
1. QR endpoint hint;
|
||
2. `QFTDISC2` UDP 发现;
|
||
3. Android 真实 Wi‑Fi gateway;
|
||
4. 常见 Windows Direct 地址;
|
||
5. 当前实际子网最多 /24 的并发 fallback 扫描。
|
||
- 所有 HTTP 请求绑定到扫码建立的 `Network`,避免手机 4G/5G/其他 Wi‑Fi 抢路由。
|
||
- Android Manifest 同时启用 local cleartext network security config;QFTPAIR 解析器仍只允许 literal private/local IPv4 + 本次 session token。
|
||
|
||
### 4. Android 7 → 最新
|
||
|
||
- `minSdk = 24`(Android 7.0)。
|
||
- Android 10+:`WifiNetworkSpecifier` local-only 配网。
|
||
- Android 7~9:`WifiManager/WifiConfiguration` 兼容路径。
|
||
- Android 13+:`NEARBY_WIFI_DEVICES`。
|
||
- Android 7~12:位置权限兼容。
|
||
- Android 7~9 光学保存:`WRITE_EXTERNAL_STORAGE` + `Downloads/QFT`。
|
||
- Android 10+ 光学保存:MediaStore Downloads。
|
||
|
||
## Windows → Android 使用
|
||
|
||
1. Windows:进入 `电脑 → Android`。
|
||
2. 选择文件。
|
||
3. 建议先用 `30 FPS / 4 码` 验证,再切 `60 FPS / 4 码`。
|
||
4. Android:`电脑 → 手机 → 开始光学接收`。
|
||
5. 让 2×2 QR 区域尽量完整占据手机取景框。
|
||
6. Android UI 会实时显示相机分析 FPS 和有效 QR/s;若识别偏低,靠近屏幕或把 Windows 降为 30 FPS。
|
||
7. 收齐后自动 SHA-256 校验并保存。
|
||
|
||
## Android → Windows 使用
|
||
|
||
1. Windows:`Android → 电脑`。
|
||
2. 选择接收文件夹。
|
||
3. 默认选择 `QFT Direct`。
|
||
4. 点击“启动接收并生成二维码”。
|
||
5. Windows 保持该页面开启。若 Windows Defender Firewall 首次询问网络访问,请允许 QFT 访问**专用网络**。
|
||
6. Android:`手机 → 电脑 → 扫码连接电脑`。
|
||
7. 首次连接具体 QFT Direct AP 时,Android 系统可能要求确认该本地 Wi‑Fi。
|
||
8. App 自动完成 endpoint/UDP/gateway/subnet 发现,出现“已连接电脑”后选择文件并开始传输。
|
||
|
||
如果电脑没有可用 Wi‑Fi Direct 适配器,可切换 Windows 的“当前局域网”备用模式。
|
||
|
||
## 构建
|
||
|
||
### Windows
|
||
|
||
需要 Rust stable MSVC + Visual C++ Build Tools / Windows SDK。
|
||
|
||
```powershell
|
||
cd windows
|
||
cargo check
|
||
cargo build --release
|
||
cargo run --release
|
||
```
|
||
|
||
### Android
|
||
|
||
当前构建栈:compileSdk/targetSdk 35、minSdk 24、JDK 17。
|
||
|
||
```powershell
|
||
cd android
|
||
.\gradlew.bat :app:testDebugUnitTest :app:assembleDebug
|
||
```
|
||
|
||
APK:
|
||
|
||
`android/app/build/outputs/apk/debug/app-debug.apk`
|
||
|
||
## 字体
|
||
|
||
Windows UI 优先读取:
|
||
|
||
`windows/assets/qft-ui.ttf`
|
||
|
||
也可设置 `QFT_FONT_PATH` 指向支持中文的 TTF。项目不会分发第三方字体文件。
|
||
|
||
## 验证
|
||
|
||
开发侧测试:
|
||
|
||
```bash
|
||
python scripts/run_all_selftests.py
|
||
python scripts/optical_image_decode_selftest.py
|
||
python scripts/local_transfer_integration_selftest.py
|
||
```
|
||
|
||
Windows 真机环境可运行根目录:
|
||
|
||
```powershell
|
||
.\VERIFY_WINDOWS_HOST.ps1
|
||
```
|
||
|
||
详细结果与尚未能在当前生成环境自动验证的硬件项目见 `TEST_REPORT.md`。
|