5.8 KiB
5.8 KiB
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。
- 电脑发现顺序:
- QR endpoint hint;
QFTDISC2UDP 发现;- Android 真实 Wi‑Fi gateway;
- 常见 Windows Direct 地址;
- 当前实际子网最多 /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+:
WifiNetworkSpecifierlocal-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 使用
- Windows:进入
电脑 → Android。 - 选择文件。
- 建议先用
30 FPS / 4 码验证,再切60 FPS / 4 码。 - Android:
电脑 → 手机 → 开始光学接收。 - 让 2×2 QR 区域尽量完整占据手机取景框。
- Android UI 会实时显示相机分析 FPS 和有效 QR/s;若识别偏低,靠近屏幕或把 Windows 降为 30 FPS。
- 收齐后自动 SHA-256 校验并保存。
Android → Windows 使用
- Windows:
Android → 电脑。 - 选择接收文件夹。
- 默认选择
QFT Direct。 - 点击“启动接收并生成二维码”。
- Windows 保持该页面开启。若 Windows Defender Firewall 首次询问网络访问,请允许 QFT 访问专用网络。
- Android:
手机 → 电脑 → 扫码连接电脑。 - 首次连接具体 QFT Direct AP 时,Android 系统可能要求确认该本地 Wi‑Fi。
- App 自动完成 endpoint/UDP/gateway/subnet 发现,出现“已连接电脑”后选择文件并开始传输。
如果电脑没有可用 Wi‑Fi Direct 适配器,可切换 Windows 的“当前局域网”备用模式。
构建
Windows
需要 Rust stable MSVC + Visual C++ Build Tools / Windows SDK。
cd windows
cargo check
cargo build --release
cargo run --release
Android
当前构建栈:compileSdk/targetSdk 35、minSdk 24、JDK 17。
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。项目不会分发第三方字体文件。
验证
开发侧测试:
python scripts/run_all_selftests.py
python scripts/optical_image_decode_selftest.py
python scripts/local_transfer_integration_selftest.py
Windows 真机环境可运行根目录:
.\VERIFY_WINDOWS_HOST.ps1
详细结果与尚未能在当前生成环境自动验证的硬件项目见 TEST_REPORT.md。