88 lines
6.4 KiB
Markdown
88 lines
6.4 KiB
Markdown
# NESLite 架构(M4 基线)
|
||
|
||
## 边界与线程
|
||
|
||
界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://`
|
||
地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。
|
||
|
||
FCEUmm 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入
|
||
`load/run/pause/reset/stop/mute/volume/audio_rebuild/fast`
|
||
命令,命令携带单调递增的会话号。旧会话、重复命令和当前状态不允许的命令不会触碰内核,并在
|
||
状态快照的完成通知中报告 `stale` 或 `ignored`。状态集合固定为 Idle、Loading、Paused、
|
||
Running、Pausing、Stopping 和 Error。
|
||
|
||
## ROM 和索引
|
||
|
||
系统文件选择器的输入流先写入 `files/roms/.import-<uuid>.tmp`。导入过程限制为 64 MiB,校验
|
||
iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/<sha256>.nes`。Room 以哈希
|
||
作为主键,因此相同内容去重、同名不同内容分别登记。写文件后、写数据库前中断留下的有效正式
|
||
文件会在下次启动恢复为索引项;残留导入临时文件会清除;索引缺少文件时标记为 `MISSING`,重新
|
||
导入相同内容可恢复文件和状态。
|
||
|
||
## libretro 宿主
|
||
|
||
固定 FCEUmm 提交见 `third_party/manifest.json`,构建定义在 `app/src/main/cpp/cmake/fceumm.cmake`。
|
||
环境协商清单如下;不在清单中的请求统一返回 `false`。
|
||
|
||
| 类别 | 处理 |
|
||
| --- | --- |
|
||
| 私有目录 | system、save、content,必须可建立,否则阻止加载 |
|
||
| 视频 | 固定核心使用的 RGB565 与重复帧;其他像素格式拒绝 |
|
||
| 选项 | core-options version 0 与 `SET_VARIABLES/GET_VARIABLE` 默认值 |
|
||
| 输入 | player 1 joypad、bitmask、输入/控制器描述 |
|
||
| 前端信息 | 日志、英语、60 Hz/48 kHz 目标、动态 geometry/AV、消息接口 v1、性能级别、内存映射、成就/内容声明 |
|
||
| 明确不支持 | VFS、扩展 game-info、硬件渲染以及未列出的请求 |
|
||
|
||
宿主在加载前核对 libretro API 版本和私有目录;必要能力缺失进入 Error。当前固定 FCEUmm 不把上述
|
||
明确不支持的请求作为加载必要条件。
|
||
|
||
加载、`retro_run`、重置、卸载和保存内存访问均在内核线程执行。时序来自
|
||
`retro_get_system_av_info`,以 `steady_clock` 调度;M3 在此边界内把核心音频转换并送往输出线程。
|
||
|
||
## 音频、时钟与快进
|
||
|
||
固定 Oboe 1.10.0 源码由 `app/src/main/cpp/cmake/oboe.cmake` 引入。打开顺序为独占低延迟、共享低延迟、
|
||
共享安全模式;每次都检查实际 float/stereo 格式、采样率、burst 和 callback 参数。全部失败时保持
|
||
内核的单调时钟调度,不因没有音频而无限追帧。
|
||
|
||
FCEUmm 的 int16 stereo 数据先经跨批次连续的线性重采样转成设备实际采样率,再写入 4096 帧 SPSC
|
||
环形缓冲。Oboe 回调只操作预分配内存和原子计数:正常取样、应用 0~1 增益,欠载补零,满缓冲丢弃
|
||
新数据并计数;不加锁、不分配、不记录文件。暂停、失焦和快进转换均停止输出并清空旧缓冲。
|
||
|
||
正常速度由 `steady_clock`、核心 FPS 和缓冲水位的 ±2% 有界校正共同调度;音频不可用时只使用单调
|
||
时钟;目标水位按设备采样率折算为约一个模拟帧并限制在安全范围。计时器分别累计加载、暂停、正常和快进时间,并保留最多 240 个帧工作耗时样本的平均值与
|
||
最大值。按住快进使用 2× 周期并静音;释放时清缓冲、重置重采样和时钟基线,再恢复正常输出。
|
||
|
||
Android 音频焦点丢失会暂停并清输入,重新获得焦点不会自行继续。音频设备增删或 Oboe
|
||
`Disconnected` 由内核线程关闭并按上述回退顺序重建,成功或失败都停在 Paused,防止旧会话回调
|
||
复活。状态 JSON 展示核心/设备采样率、callback/burst、缓冲水位、欠载/溢出、重建次数、速度和帧
|
||
时间;诊断只存计数与固定窗口。
|
||
|
||
## 视频、输入和电池存档
|
||
|
||
视频回调逐行按 pitch 复制到原生 latest-only 缓冲;`data == nullptr` 表示重复帧并保留上一完整帧。
|
||
GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
|
||
原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。
|
||
|
||
M4 输入层按物理来源维护状态,来源键包含本次设备 ID、按键/轴/触屏类别、代码和轴方向。多个来源
|
||
映射到同一动作时只合成一次;释放一个来源不会清除仍按住的另一个来源。相反方向同时成立时对应轴
|
||
归零。轴使用可配置的按下/释放双阈值,跨向时先释放旧方向再按下新方向,避免边界抖动和瞬时冲突。
|
||
|
||
标准 Android 手柄使用通用映射:方向键/X-Y 轴控制方向,A/B 对应 NES A/B,X/Y 对应 A/B 软件
|
||
连发,Start/Select 保持原义,右摇杆按下切换暂停菜单,RB 按住 2× 快进。暂停和快进只按合成动作
|
||
边沿发命令,系统重复 KeyEvent 不会重复切换;Guide、Mode、肩键组合和快速读档均不占用。软件连发
|
||
在原生核心线程按模拟秒生成 15 Hz 门控,NTSC/PAL 不依赖墙钟频率,离开 Running 即清零。
|
||
|
||
自定义设置可逐动作捕获按键或轴方向,冲突必须确认替换,并支持取消、恢复默认、A/B 交换及死区
|
||
调整。DataStore 以 VID/PID 加 descriptor(不可用时回退规范化名称)的 SHA-256 指纹保存档案,不写入
|
||
临时 deviceId;设备重连后按稳定特征恢复。X5 Lite 专属映射注册只接受 M1 实测的完整签名和事件表,
|
||
在该证据缺失时保持空表并使用通用档案,防止按名称误套。
|
||
|
||
运行态输入送入 JNI 的基础掩码和独立连发掩码。暂停菜单、游戏列表及设置均使用可聚焦原生控件;
|
||
非运行态不消费方向导航,手柄 B 可从设置返回、从暂停菜单继续。失焦、暂停、断柄和退出同步清除
|
||
来源、轴滞回、基础掩码及连发掩码。
|
||
|
||
电池存档按 ROM 哈希隔离为 `files/saves/<sha256>/battery/battery.sav`。暂停和正常退出时在内核线程
|
||
取得保存内存并以临时文件替换提交,状态通知用 `paused_saved`/`stopped_saved` 报告成功。更完整的
|
||
备份、故障注入和恢复保证属于 M5,不在此处提前声明。
|