swung0x48/MobileGL
1
0
Fork 0
mirror of https://github.com/MobileGL-Dev/MobileGL synced 2026-09-11 21:58:31 +09:00
Code Issues Packages Projects Releases Wiki Activity

[Docs] (trace-replay): unify Android trace runner docs

Browse Source
This commit is contained in:
swung0x48
2026-07-18 07:06:56 -04:00
parent c2a1db3fcb
commit f5cba4c2f1
2 changed files with 57 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/trace_replay/README.md
+15 -10
View File
@@ -173,11 +173,14 @@ or `--skip-case NAME` for known fatal cases.
## Android device replay ## 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 ```sh
gradle --no-daemon -p android-plugin :app:assembleEsprytTraceDebug gradle --no-daemon -p android-plugin :app:assembleTraceDebug
adb install -r android-plugin/app/build/outputs/apk/esprytTrace/debug/MobileGL-EsprytTrace-debug.apk 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: 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 /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 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 APP_DIR=/data/user/0/$PKG/files/trace-replay
adb shell run-as $PKG rm -rf 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 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: Launch the standalone trace runner Activity:
```sh ```sh
adb shell am force-stop $PKG
adb shell am start -W -a top.mobilegl.plugin.TRACE_REPLAY \ adb shell am start -W -a top.mobilegl.plugin.TRACE_REPLAY \
-n $PKG/top.mobilegl.plugin.trace.TraceReplayActivity \ -n $PKG/top.mobilegl.plugin.trace.TraceReplayActivity \
--es trace_path $APP_DIR/input/openra.trace \ --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 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 For Vulkan replay, keep the same APK and `$PKG`, then pass
`PKG=top.mobilegl.plugin.magma.trace`, and pass `--es backend DirectVulkan`. `--es backend DirectVulkan`. DirectGLES also renders to the Activity surface by
DirectGLES also renders to the Activity surface by default; pass default; pass `--ez use_pbuffer true` to use the offscreen pbuffer path. Always
`--ez use_pbuffer true` to use the offscreen pbuffer path. For cases registered `adb shell am force-stop $PKG` before another replay: apitrace snapshot state is
with `coherent_as_flush` (Flywheel-style unflushed persistent maps, e.g. the process-local. For cases registered with `coherent_as_flush` (Flywheel-style
Create fixtures), pass `--ez coherent_as_flush true` so the replay runs with unflushed persistent maps, e.g. the Create fixtures), pass
`--ez coherent_as_flush true` so the replay runs with
`MOBILEGL_COHERENT_AS_FLUSH=1`. `MOBILEGL_COHERENT_AS_FLUSH=1`.
tools/trace_replay/skills/trace-fixture-authoring.md
+42 -38
View File
@@ -361,25 +361,29 @@ vulkaninfo | grep -E 'deviceName|VK_EXT_headless_surface'
## Validate on Android ## 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 ```sh
gradle --no-daemon -p "$REPO/android-plugin" \ gradle --no-daemon -p "$REPO/android-plugin" \
:app:assembleEsprytTraceRelease \ :app:assembleTraceRelease \
:app:assembleMagmaTraceRelease \
-Pmobilegl.abis=all \ -Pmobilegl.abis=all \
-Pmobilegl.debuggableRelease=true \ -Pmobilegl.debuggableRelease=true \
-Pmobilegl.logLevel=MOBILEGL_LOG_LEVEL_INFO \ -Pmobilegl.logLevel=MOBILEGL_LOG_LEVEL_INFO \
--parallel --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`, Release APKs are only signed when `SIGNING_STORE_PASSWORD`,
`SIGNING_KEY_ALIAS`, and `SIGNING_KEY_PASSWORD` are set and `SIGNING_KEY_ALIAS`, and `SIGNING_KEY_PASSWORD` are set and
`android-plugin/keystore.jks` exists - an unsigned build still "succeeds" but `android-plugin/keystore.jks` exists - an unsigned build still "succeeds" but
installs fail later with `INSTALL_PARSE_FAILED_NO_CERTIFICATES`. If the installs fail later with `INSTALL_PARSE_FAILED_NO_CERTIFICATES`. If the device
device or emulator has a trace package from a different keystore, uninstall or emulator already has `top.mobilegl.plugin.trace` from a different keystore,
`top.mobilegl.plugin.espryt.trace` / `top.mobilegl.plugin.magma.trace` first uninstall that one package first or the install fails with
or the install fails with `INSTALL_FAILED_UPDATE_INCOMPATIBLE`. `INSTALL_FAILED_UPDATE_INCOMPATIBLE`.
Match the CI environment (`.github/workflows/apk.yml` matrix): the emulator Match the CI environment (`.github/workflows/apk.yml` matrix): the emulator
boots with `--gpu software` + `MOBILEGL_USE_ANGLE=1` for `DirectGLES` 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 as the current one (identical-to-the-last-digit ssim across "different" runs
is the tell). is the tell).
Run DirectGLES: Run both backends against the same APK:
```sh ```sh
sh "$REPO/android-plugin/trace-replay-ci.sh" \ run_android_retrace() {
--apk-file "$REPO/android-plugin/app/build/outputs/apk/esprytTrace/release/MobileGL-EsprytTrace-release.apk" \ backend="$1"
--package top.mobilegl.plugin.espryt.trace \ shift
--backend DirectGLES \ sh "$REPO/android-plugin/trace-replay-ci.sh" \
--result-root "$WORK/$CASE/android-result" \ --apk-file "$TRACE_APK" \
--fixture-root "$WORK/$CASE/android-fixture" \ --package "$TRACE_PACKAGE" \
--case "$CASE" \ --backend "$backend" \
--trace-archive "$REPO/tools/trace_replay/fixtures/$CASE.tgz" \ --result-root "$WORK/$CASE/android-result-$backend" \
--trace-file trace.trace \ --fixture-root "$WORK/$CASE/android-fixture" \
--golden "$REPO/tools/trace_replay/fixtures/$CASE.$(printf '%010d' "$TARGET_CALL").png" \ --case "$CASE" \
--target-call "$TARGET_CALL" \ --trace-archive "$REPO/tools/trace_replay/fixtures/$CASE.tgz" \
--width "$WIDTH" \ --trace-file trace.trace \
--height "$HEIGHT" \ --golden "$REPO/tools/trace_replay/fixtures/$CASE.$(printf '%010d' "$TARGET_CALL").png" \
--ssim-threshold 0.99 \ --target-call "$TARGET_CALL" \
--crop-x 0 \ --width "$WIDTH" \
--crop-y 0 \ --height "$HEIGHT" \
--crop-width 0 \ --ssim-threshold 0.99 \
--crop-height 0 \ --crop-x 0 \
--timeout-seconds 900 --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: Inspect:
- `$WORK/$CASE/android-result/$CASE-DirectGLES/result.json` - `$WORK/$CASE/android-result-DirectGLES/$CASE-DirectGLES/result.json`
- `$WORK/$CASE/android-result/$CASE-DirectGLES/$CASE-DirectGLES-actual.png` - `$WORK/$CASE/android-result-DirectVulkan/$CASE-DirectVulkan/result.json`
- `$WORK/$CASE/android-result/$CASE-DirectGLES/$CASE-DirectGLES-diff.png` - Each backend's `*-actual.png`, `*-diff.png`, `retrace.log`, and `logcat.txt`
- `$WORK/$CASE/android-result/$CASE-DirectGLES/retrace.log`
- `$WORK/$CASE/android-result/$CASE-DirectGLES/logcat.txt`
## Checklist ## Checklist