Files
d2r-mobile/dm/android
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
..

Android shell (Adreno devices only)

中文: 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:

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, 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)

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:

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 for measurements and validation limits. Keep binaries, caches, logs and game screenshots under ignored dm/android/build/ or device test directories.