Files
d2r-mobile/dm/android/README.md
T
shenleiandClaude Opus 5.5 3c25cd89fc Android: move the shell to dm/android and the Vulkan backend to dm/gfx/vulkan
Mirror the iOS layout instead of nesting Android inside dm/host:
- dm/android/app       GameActivity app (manifest, java, res, build_apk.sh)
- dm/android/Sources   front_app.c, touch_app.c, front_headless.c
- dm/android/Makefile  entry point (apk / lib / install / headless / tests);
                       rules in build.mk (was dm/host/Makefile.android),
                       run with dm/host as cwd; outputs in dm/android/build/
- dm/android/tests     t_vk_perf
- dm/gfx/vulkan        nvn_vk.c and friends, next to the Metal backend

Only include paths, build paths and docs change; no code changes.
The Mac / iOS source lists do not pick up gfx/vulkan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 16:59:36 +09:00

79 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Android shell (Adreno devices only)
中文: [README.zh-CN.md](README.zh-CN.md)
Layout (a sibling of `dm/ios/`):
| Path | Contents |
|---|---|
| `app/` | The GameActivity app: `AndroidManifest.xml`, `java/`, `res/`, the packaging script `build_apk.sh`, `art_from_ipa.py` |
| `Sources/` | Front ends: `front_app.c` (app), `touch_app.c` (touch HUD), `front_headless.c` (adb headless host) |
| `Makefile`, `build.mk` | Build entry point and rules; the shared host sources come from `dm/host/`, outputs go to `build/` (not in git) |
| `tests/` | Vulkan backend device test `t_vk_perf` |
| `../gfx/vulkan/` | The Vulkan graphics backend `nvn_vk.c` (counterpart of the Metal backend `gfx/nvn/nvn_mtl.m`) |
The backend (`gfx/vulkan/nvn_vk.c`) retains the NVN recorder's `mtl_*` interface. Headless rendering is verified on OnePlus 13 / Adreno 830. A minimal GameActivity app (window, raw touch, gamepad, text input) is in `app/`; AAudio and the touch HUD remain subsequent work.
## Build and test
Run from the repository root with generated host headers and your own rewritten game files:
```sh
make -C dm/android headless -j8 # headless host dm/android/build/dmhost
make -C dm/android tests
adb push dm/android/build/tests/t_vk_perf /data/local/tmp/d2r/t_vk_perf
adb shell /data/local/tmp/d2r/t_vk_perf
```
Use `NDK=...` or `ANDROID_NDK_HOME` to override the newest local SDK NDK. The device test uses real Vulkan and checks hash collisions, reused CPU input addresses, GPU writebacks, fence rotation, event publication during memory polling, descriptor pool growth and capacity splits. Success prints `VK_PERF_TEST_PASS`.
| Environment variable | Purpose |
|---|---|
| `DM_VK_SHADERS` | Vulkan shader pack generated by `dmsh_vk.py` |
| `DM_VK_PIPELINE_CACHE` | Driver cache file; defaults to the shader directory with vendor / device / driver version in its name |
| `DM_DISABLE_PIPELINE_CACHE=1` | Disable the driver cache; the state-to-pipeline memory cache remains active |
| `DM_VK_SYNC=1` | Submit and wait at every logical commit for comparison |
| `DM_FRAME_DIR` | Existing PPM frame capture and requested diagnostics |
| `DM_VULKAN_VALIDATION=1` | Request the Khronos layer, which must be discoverable by Android's loader |
| `DM_VK_PASSPROF=N` | Timestamp every render pass / dispatch of frame N and print per-pass GPU time (`PASSPROF` lines) at frame N+3 |
| `DM_VK_VRS=WxH[:hash,...]` | Pipeline fragment shading rate for the listed pixel shaders (default: forward+ lighting `5c1ca4e7c3e4657c`); needs `VK_KHR_fragment_shading_rate`, otherwise ignored |
| `DM_VK_AHB_POOL=1` | Try AHardwareBuffer BLOBs for memory-pool remapping before OPAQUE_FD. Off by default: on OnePlus 13 a large BLOB crashes the vendor allocator service (and the display stack with it), and it never succeeded on tested devices |
| `DM_3D_SCALE=0.5–1.0` | 3D internal render scale (the game's own upscale shader brings it back to the output size; the UI stays at output resolution). Android default 0.8: 3D at 720 lines under a 900-line output. Dynamic levels 0.72 / 0.70 kick in only on sustained dropped frames |
| `DM_FPS=30\|60` | Pin the frame rate. Otherwise it follows the Custom page's power-saving mode (`eco_fps`): 30 fps uses a software 30 Hz tick and hints the panel down with `ANativeWindow_setFrameRate` |
| `DM_VK_EVENT_SYNC=1` | Restore the old WaitEvent behavior (commit and CPU-wait for all prior GPU work) for comparison |
Following the [Vulkan cache header contract](https://docs.vulkan.org/spec/latest/chapters/pipelines.html), loading checks size, header version, vendor / device and UUID, and falls back to an empty cache. New compilation data is saved every 60 frames and on Finish / Drain using a temporary file and rename. Cache I/O failure does not stop rendering.
## App (GameActivity)
```sh
make -C dm/android -j8 # libd2r.so + dm/android/build/app/d2r.apk, no Gradle
make -C dm/android install # adb install -r (ends a running game)
```
`APP=1` builds the host as `libd2r.so` with `Sources/front_app.c` in place of `Sources/front_headless.c`. `build_apk.sh` uses javac (Android Studio's JBR by default), d8, aapt2, zipalign and apksigner with the debug keystore. The app is debuggable so game data can be copied in with `run-as`:
```sh
adb shell run-as org.d2rmobile.app sh -c 'mkdir -p files/d2r && cp -r /data/local/tmp/d2r/dm /data/local/tmp/d2r/romfs /data/local/tmp/d2r/romfs_overlay /data/local/tmp/d2r/rt64 /data/local/tmp/d2r/save files/d2r/'
adb shell am start -n org.d2rmobile.app/.GameActivity
adb shell run-as org.d2rmobile.app cat files/d2r/run.log
```
The data root is `files/d2r` (`dm/main.patched.bin`, `romfs`, `rt64` required). stderr goes to `run.log`; optional `env.txt` lines `KEY=VALUE` are exported before start (e.g. `DM_VK_VRS=2x2`). Audio is off (`DM_AUDIO=0`) until AAudio lands. Render resolution is 720 lines times the screen aspect (`DM_GAME_RES` overrides). Without a window (app in background) the render thread holds at Present and resumes when a new surface arrives. On front-end pages (main menu, character select / creation) the first finger becomes UI mouse clicks via `dm_ui_touch` (tap = click at the lift point, vertical drag = scroll), as on iOS; in a run touch goes to the game's raw touchscreen until the touch HUD is ported. Gamepad buttons and sticks go to the pad.
## Implementation and boundaries
- Graphics and compute pipelines use effective Vulkan state keys with full equality after hash lookup. Dynamic viewport / scissor / blend constants and resource addresses are excluded; shaders, vertex input, topology, blend, depth / stencil, feedback flags and attachment compatibility are included. Pipelines and layouts live with the device.
- Render passes cache attachment descriptions; framebuffers cache images, mip / layer, extent and pass. Ordinary consecutive draws retain a pass. Layout transitions, copies, barriers, storage writes and feedback sampling preserve required boundaries. Texture release drains work and clears framebuffers. Adreno's GENERAL feedback path retains pass boundaries.
- Logical NVN commits can continue recording until Present, QueueFlush, a CPU wait or capacity boundary. Eight slots (`BATCH_SLOTS`) reuse command buffers, descriptor / query pools and fences; transient resources retire only after GPU completion. A completion worker publishes events / counters for guests that only poll memory and flushes report-bearing work after 2 ms of idle time.
- NVN `CommandBufferWaitEvent` is a GPU-side wait. If the event condition is already met by memory plus the signals queued in pending / recording batches (in submit order), the host records only a barrier and does not wait on the CPU. Only an event that no queued work can satisfy falls back to commit + CPU wait (`event_blocked` in `WAIT_PROFILE`).
- Build the shader pack with `SB_ALIGN=64` (the `dmsh_vk.py` default). Shaders then derive SSBO offsets from `base & -64`, and vkmeta flag bit 1 lets the host bind storage buffers directly from `addr & -64` with no copy. vkmeta storage flag bit 0 means writable. Packs built with `SB_ALIGN=16` still work through the copy path.
- CPU inputs use immutable snapshots. GPU-authored inputs stay in shared GPU buffers; ordered staging copies supply uncovered CPU bytes. Each batch snapshots its GPU writebacks to prevent subsequent batches contaminating earlier results.
- Capacity splits retain the logical fence until the final piece completes. Explicit Flush / wait boundaries prevent a strict one-submit-per-frame guarantee.
- The current real-window path still waits for presentation and queue idle to preserve temporary WSI semaphore lifetimes. This performance work targets headless rendering.
- Windowed present does not drain: each batch slot reuses its acquire semaphore and each swapchain image has its own present semaphore. `VK_ERROR_OUT_OF_DATE_KHR` on acquire recreates the swapchain and retries; on present it marks the swapchain for recreation at the next frame. Surface changes wait for the queue to idle before the swapchain is dropped.
`RENDER_PROFILE` counts actual Vulkan submissions including Present; the old counter excluded Present. `RENDER_CACHE_PROFILE` records cache reuse, pass count, pass breaks, transient buffer use and `gpu_ms` (GPU time of the interval from timestamp queries). `RENDER_INPUT_PROFILE` records uploads and shared GPU reads. `WAIT_PROFILE` splits CPU-side GPU wait time by origin (sync / event / present / slot / readtex / texrel / sampler / pooldel / finish / capture, as `ms/count`), plus `sync_lag_max` and `event_queued` / `event_blocked`.
See [PERFORMANCE.md](PERFORMANCE.md) for measurements and validation limits. Keep binaries, caches, logs and game screenshots under ignored `dm/android/build/` or device test directories.