Files
QFT/README.md
T
2026-08-10 15:45:04 +08:00

5.8 KiB
Raw Blame History

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。

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。