Files

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. The app includes window management, a touch HUD, gamepad and text input, AAudio and lifecycle suspend/resume. Integration does not establish validation on every device.

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_SUBRES=0 Disable disjoint-mip layouts and use the original whole-image path for device A/B; enabled by default
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). AAudio is on by default (DM_AUDIO=0 mutes). UI output follows screen aspect and native height (900–1080 lines); the default 3D target is approximately 720 lines (DM_GAME_RES / DM_3D_SCALE override). 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 the touch HUD and game-state bridge handle gestures, with unclaimed touches available to the raw touchscreen. 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.
  • 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.

Subresource layouts and cross-GPU verification

See VALIDATION.md for this change's completed checks and outstanding device/package validation.

Inspired by dodola/d2r-mobile at 642480b, this backend tracks per-mip layouts for disjoint sampling/rendering on drivers without feedback-layout support. The bounded path covers single-layer 2D color images with 2–16 mips. Every sampled view in both graphics stages must avoid every attachment mip. Overlap, storage images, comparison sampling, depth/stencil, arrays and volumes retain the original path. Whole-image operations consolidate each run using its actual old layout, preserving pixels during upload, copies and readback.

No build91738 addresses, resource paths or input services were imported. The build94012 HUD/save/build integration remains in place. Existing Adreno validation remains the supported scope. Mali requires device validation; a successful capability probe does not prove game compatibility.

Game-free checks (each output directory must be new):

# Host layout regression + ASan/UBSan + NDK test binary build; no device access
python3 dm/android/tests/run_checks.py --output dm/android/build/checks-local
# Host checks only; NDK Vulkan headers are still required
make -C dm/android host-tests
# Explicit device opt-in: runs test binaries, does not install/start the game
python3 dm/android/tests/run_checks.py --output dm/android/build/checks-device --run-device --serial DEVICE_SERIAL

Use --ndk /path/to/ndk and HOST_CC to select toolchains. result.json records commands, exit codes, source/binary SHA-256 and whether device/GPU checks actually ran. t_vk_caps emits system-driver GPU/features/extensions/formats/memory JSON; it does not inspect the app's private driver. t_vk_perf includes cross-stage overlap checks and real GPU multi-mip readback. Run t_vk_perf mips for only the added cases.

Compare DM_VK_SUBRES=0 / 1 on the same build94012 game, character, location, output extent and fixed 3D scale. Record driver, actual refresh rate, SurfaceFlinger display intervals and temperature. Check pixels and save/resume before evaluating speed. Different builds/drivers and submission-only FPS are not controlled comparisons.