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>
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
CommandBufferWaitEventis 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_blockedinWAIT_PROFILE). - Build the shader pack with
SB_ALIGN=64(thedmsh_vk.pydefault). Shaders then derive SSBO offsets frombase & -64, and vkmeta flag bit 1 lets the host bind storage buffers directly fromaddr & -64with no copy. vkmeta storage flag bit 0 means writable. Packs built withSB_ALIGN=16still 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_KHRon 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.