From f5cba4c2f1c887ad699e903f29b1093d1e602d3d Mon Sep 17 00:00:00 2001
From: Swung0x48 <swung0x48@outlook.com>
Date: Sat, 18 Jul 2026 07:06:56 -0400
Subject: [PATCH] [Docs] (trace-replay): unify Android trace runner docs

---
 tools/trace_replay/README.md                  | 25 +++---
 .../skills/trace-fixture-authoring.md         | 80 ++++++++++---------
 2 files changed, 57 insertions(+), 48 deletions(-)

diff --git a/tools/trace_replay/README.md b/tools/trace_replay/README.md
index 0c9442eb..d71aef7d 100644
--- a/tools/trace_replay/README.md
+++ b/tools/trace_replay/README.md
@@ -173,11 +173,14 @@ or `--skip-case NAME` for known fatal cases.
 
 ## Android device replay
 
-Build and install a trace APK from the repository root:
+Build and install the generic trace APK from the repository root. Both
+`DirectGLES` and `DirectVulkan` use the same APK and package; select the
+backend with the intent's `backend` extra.
 
 ```sh
-gradle --no-daemon -p android-plugin :app:assembleEsprytTraceDebug
-adb install -r android-plugin/app/build/outputs/apk/esprytTrace/debug/MobileGL-EsprytTrace-debug.apk
+gradle --no-daemon -p android-plugin :app:assembleTraceDebug
+TRACE_APK=$(find android-plugin/app/build/outputs/apk/trace/debug -maxdepth 1 -name '*.apk' -print -quit)
+adb install -r "$TRACE_APK"
 ```
 
 Prepare a fixture and copy it into the app-private directory:
@@ -188,7 +191,7 @@ tar -xzf tools/trace_replay/fixtures/openra.tgz -C /tmp/mobilegl-openra
 adb push /tmp/mobilegl-openra/openra.trace /data/local/tmp/mobilegl-openra.trace
 adb push tools/trace_replay/fixtures/openra.0000031249.png /data/local/tmp/mobilegl-openra.golden.png
 
-PKG=top.mobilegl.plugin.espryt.trace
+PKG=top.mobilegl.plugin.trace
 APP_DIR=/data/user/0/$PKG/files/trace-replay
 adb shell run-as $PKG rm -rf files/trace-replay
 adb shell run-as $PKG mkdir -p files/trace-replay/input files/trace-replay/output
@@ -199,6 +202,7 @@ adb shell run-as $PKG cp /data/local/tmp/mobilegl-openra.golden.png files/trace-
 Launch the standalone trace runner Activity:
 
 ```sh
+adb shell am force-stop $PKG
 adb shell am start -W -a top.mobilegl.plugin.TRACE_REPLAY \
   -n $PKG/top.mobilegl.plugin.trace.TraceReplayActivity \
   --es trace_path $APP_DIR/input/openra.trace \
@@ -224,10 +228,11 @@ adb exec-out run-as $PKG cat files/trace-replay/output/actual.png > openra-actua
 adb exec-out run-as $PKG cat files/trace-replay/output/openra-diff.png > openra-diff.png
 ```
 
-For the Vulkan backend, build and install `:app:assembleMagmaTraceDebug`, set
-`PKG=top.mobilegl.plugin.magma.trace`, and pass `--es backend DirectVulkan`.
-DirectGLES also renders to the Activity surface by default; pass
-`--ez use_pbuffer true` to use the offscreen pbuffer path. For cases registered
-with `coherent_as_flush` (Flywheel-style unflushed persistent maps, e.g. the
-Create fixtures), pass `--ez coherent_as_flush true` so the replay runs with
+For Vulkan replay, keep the same APK and `$PKG`, then pass
+`--es backend DirectVulkan`. DirectGLES also renders to the Activity surface by
+default; pass `--ez use_pbuffer true` to use the offscreen pbuffer path. Always
+`adb shell am force-stop $PKG` before another replay: apitrace snapshot state is
+process-local. For cases registered with `coherent_as_flush` (Flywheel-style
+unflushed persistent maps, e.g. the Create fixtures), pass
+`--ez coherent_as_flush true` so the replay runs with
 `MOBILEGL_COHERENT_AS_FLUSH=1`.
diff --git a/tools/trace_replay/skills/trace-fixture-authoring.md b/tools/trace_replay/skills/trace-fixture-authoring.md
index ccf42a3b..7d7a817c 100644
--- a/tools/trace_replay/skills/trace-fixture-authoring.md
+++ b/tools/trace_replay/skills/trace-fixture-authoring.md
@@ -361,25 +361,29 @@ vulkaninfo | grep -E 'deviceName|VK_EXT_headless_surface'
 
 ## Validate on Android
 
-Build trace APKs:
+Build one generic trace APK. Both backends use this APK and the same package;
+select the backend at replay time with `--backend`.
 
 ```sh
 gradle --no-daemon -p "$REPO/android-plugin" \
-  :app:assembleEsprytTraceRelease \
-  :app:assembleMagmaTraceRelease \
+  :app:assembleTraceRelease \
   -Pmobilegl.abis=all \
   -Pmobilegl.debuggableRelease=true \
   -Pmobilegl.logLevel=MOBILEGL_LOG_LEVEL_INFO \
   --parallel
+
+TRACE_APK=$(find "$REPO/android-plugin/app/build/outputs/apk/trace/release" \
+  -maxdepth 1 -name 'MobileGL-plugin-trace-release-*.apk' -print -quit)
+TRACE_PACKAGE=top.mobilegl.plugin.trace
 ```
 
 Release APKs are only signed when `SIGNING_STORE_PASSWORD`,
 `SIGNING_KEY_ALIAS`, and `SIGNING_KEY_PASSWORD` are set and
 `android-plugin/keystore.jks` exists - an unsigned build still "succeeds" but
-installs fail later with `INSTALL_PARSE_FAILED_NO_CERTIFICATES`. If the
-device or emulator has a trace package from a different keystore, uninstall
-`top.mobilegl.plugin.espryt.trace` / `top.mobilegl.plugin.magma.trace` first
-or the install fails with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
+installs fail later with `INSTALL_PARSE_FAILED_NO_CERTIFICATES`. If the device
+or emulator already has `top.mobilegl.plugin.trace` from a different keystore,
+uninstall that one package first or the install fails with
+`INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
 
 Match the CI environment (`.github/workflows/apk.yml` matrix): the emulator
 boots with `--gpu software` + `MOBILEGL_USE_ANGLE=1` for `DirectGLES`
@@ -399,43 +403,43 @@ result directory before each run, or an earlier failure/success can masquerade
 as the current one (identical-to-the-last-digit ssim across "different" runs
 is the tell).
 
-Run DirectGLES:
+Run both backends against the same APK:
 
 ```sh
-sh "$REPO/android-plugin/trace-replay-ci.sh" \
-  --apk-file "$REPO/android-plugin/app/build/outputs/apk/esprytTrace/release/MobileGL-EsprytTrace-release.apk" \
-  --package top.mobilegl.plugin.espryt.trace \
-  --backend DirectGLES \
-  --result-root "$WORK/$CASE/android-result" \
-  --fixture-root "$WORK/$CASE/android-fixture" \
-  --case "$CASE" \
-  --trace-archive "$REPO/tools/trace_replay/fixtures/$CASE.tgz" \
-  --trace-file trace.trace \
-  --golden "$REPO/tools/trace_replay/fixtures/$CASE.$(printf '%010d' "$TARGET_CALL").png" \
-  --target-call "$TARGET_CALL" \
-  --width "$WIDTH" \
-  --height "$HEIGHT" \
-  --ssim-threshold 0.99 \
-  --crop-x 0 \
-  --crop-y 0 \
-  --crop-width 0 \
-  --crop-height 0 \
-  --timeout-seconds 900
+run_android_retrace() {
+  backend="$1"
+  shift
+  sh "$REPO/android-plugin/trace-replay-ci.sh" \
+    --apk-file "$TRACE_APK" \
+    --package "$TRACE_PACKAGE" \
+    --backend "$backend" \
+    --result-root "$WORK/$CASE/android-result-$backend" \
+    --fixture-root "$WORK/$CASE/android-fixture" \
+    --case "$CASE" \
+    --trace-archive "$REPO/tools/trace_replay/fixtures/$CASE.tgz" \
+    --trace-file trace.trace \
+    --golden "$REPO/tools/trace_replay/fixtures/$CASE.$(printf '%010d' "$TARGET_CALL").png" \
+    --target-call "$TARGET_CALL" \
+    --width "$WIDTH" \
+    --height "$HEIGHT" \
+    --ssim-threshold 0.99 \
+    --crop-x 0 \
+    --crop-y 0 \
+    --crop-width 0 \
+    --crop-height 0 \
+    --timeout-seconds 900 \
+    "$@"
+}
+
+run_android_retrace DirectGLES --use-pbuffer
+run_android_retrace DirectVulkan
 ```
 
-Run DirectVulkan with:
-
-- APK: `MobileGL-MagmaTrace-release.apk`
-- package: `top.mobilegl.plugin.magma.trace`
-- backend: `DirectVulkan`
-
 Inspect:
 
-- `$WORK/$CASE/android-result/$CASE-DirectGLES/result.json`
-- `$WORK/$CASE/android-result/$CASE-DirectGLES/$CASE-DirectGLES-actual.png`
-- `$WORK/$CASE/android-result/$CASE-DirectGLES/$CASE-DirectGLES-diff.png`
-- `$WORK/$CASE/android-result/$CASE-DirectGLES/retrace.log`
-- `$WORK/$CASE/android-result/$CASE-DirectGLES/logcat.txt`
+- `$WORK/$CASE/android-result-DirectGLES/$CASE-DirectGLES/result.json`
+- `$WORK/$CASE/android-result-DirectVulkan/$CASE-DirectVulkan/result.json`
+- Each backend's `*-actual.png`, `*-diff.png`, `retrace.log`, and `logcat.txt`
 
 ## Checklist