[Feat] (TraceReplay): add RenderDoc Android capture tools

tools/trace_replay/renderdoc_trace_capture/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: renderdoc-capture-trace-frame
+description: Capture and validate an exact frame from a MobileGL apitrace retrace on a connected Android device with RenderDoc/rdc-cli. Use for DirectVulkan or DirectGLES trace replay, mapping a target API call to an eglSwapBuffers frame, producing an .rdc plus a complete command manifest, checking capture stability, or troubleshooting Android TargetControl timing and replay failures.
+---
+
+# Capture a RenderDoc Trace Frame
+
+Use the repository tool to queue TargetControl before launching the replay activity, keep the connection alive until capture completion, pull the RDC, and write a reproducible JSON manifest.
+
+## Prepare
+
+1. Work from the MobileGL repository root.
+2. Confirm `python`, `adb`, `apitrace`, and `rdc` are on `PATH`.
+3. Confirm the trace replay APK is installed and debuggable:
+
+```powershell
+adb devices -l
+adb -s SERIAL shell pm path top.mobilegl.plugin.trace
+rdc doctor
+```
+
+4. Pass the unpacked `trace.trace`, its golden PNG, the fixture target call, backend, and output path to `tools/trace_replay/capture_android_retrace.py`.
+
+## Capture
+
+Let the tool infer the zero-based target swap from `eglSwapBuffers` calls:
+
+```powershell
+python tools/trace_replay/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectVulkan --output captures/case-vulkan.rdc --serial SERIAL --json
+```
+
+Change only the backend and output for GLES:
+
+```powershell
+python tools/trace_replay/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectGLES --output captures/case-gles.rdc --serial SERIAL --json
+```
+
+Use `--target-swap N` when the mapping is already known. Use `--capture-frame N` only to override the backend rule deliberately.
+
+The default mapping is:
+
+- DirectGLES: capture the zero-based target swap.
+- DirectVulkan: capture `target swap - 1`, so the capture closes at the terminal target Present. Queueing the terminal Vulkan swap itself can never finish when the retrace stops immediately after that Present.
+
+The tool applies a 256 MiB RenderDoc `softMemoryLimit` for Vulkan, installs the GLES layer only for GLES, queues before Activity launch, drains asynchronous TargetControl registration messages, and restores device properties and forwards afterward. Do not replace it with a late `rdc script` call.
+
+## Inspect the Output
+
+Read `<output>.rdc.json`. Require all of the following:
+
+- `success` is `true`.
+- `capture.frame` equals the requested capture frame.
+- `capture.api` matches Vulkan or OpenGLES.
+- `byteSize` is non-zero and `sha256` is present.
+- `retraceResult` says the replay completed; treat its SSIM separately from RDC validity.
+- `commands` and `commandLines` contain the full reproducible command history.
+
+A DirectVulkan SSIM below a GLES golden threshold can be a backend rendering difference. Do not reject the RDC solely for that reason if RenderDoc can replay it and the target render output is present.
+
+## Validate with RenderDoc
+
+Validate GLES locally:
+
+```powershell
+rdc close
+rdc open captures/case-gles.rdc
+rdc info --json
+rdc count events
+rdc count draws
+rdc count passes
+rdc assert-clean --min-severity high --json
+```
+
+Validate device-specific Vulkan captures on the original Android GPU:
+
+```powershell
+rdc android setup --json
+adb -s SERIAL forward --list
+rdc close
+rdc open captures/case-vulkan.rdc --proxy 127.0.0.1:FORWARDED_REMOTE_PORT
+rdc info --json
+rdc count events
+rdc count draws
+rdc count passes
+rdc assert-clean --min-severity high --json
+```
+
+Use the local TCP port mapped to `localabstract:renderdoc_39920` as `FORWARDED_REMOTE_PORT`. Prefer Android remote replay when a desktop GPU lacks the Android capture's memory types.
+
+## Diagnose Failures
+
+Read [references/android-renderdoc-troubleshooting.md](references/android-renderdoc-troubleshooting.md) when capture metadata is missing, a capture times out, the GLES layer does not load, Vulkan stalls on initial contents, `rdc android setup --serial` cannot select a listed device, or desktop replay rejects a Vulkan RDC.

tools/trace_replay/renderdoc_trace_capture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Capture RenderDoc Trace Frame"
+  short_description: "Capture exact Android Vulkan/GLES trace frames"
+  default_prompt: "Use $renderdoc-capture-trace-frame to capture and validate an exact Android retrace frame."

tools/trace_replay/renderdoc_trace_capture/references/android-renderdoc-troubleshooting.md

@@ -0,0 +1,63 @@
+# Android RenderDoc retrace troubleshooting
+
+## TargetControl timing
+
+- Start `tools/trace_replay/queue_android_frame.py` before launching `TraceReplayActivity`. A fast retrace can pass the requested frame before a late client connects.
+- Keep TargetControl connected until `NewCapture` arrives. A queued request alone is not sufficient evidence that the RDC finished.
+- Drain the asynchronous `RegisterAPI` and `CapturableWindowCount` messages before calling `QueueCapture`; otherwise `NewCapture` can be lost.
+- Do not use the daemon-backed `rdc script` path for a capture that may exceed 30 seconds. Its outer RPC times out even when the device later writes a valid RDC. The repository helper imports the RenderDoc module discovered by `rdc` directly and has an independent capture timeout.
+
+## Frame selection
+
+- Map the fixture target call to the exact `eglSwapBuffers` call, or to the first swap after a non-swap target call.
+- Use the zero-based swap index for DirectGLES.
+- Use `target swap - 1` for DirectVulkan when the target swap is the retrace's terminal Present. RenderDoc needs that Present to close the queued frame.
+- Override with `--capture-frame` only after inspecting the trace structure.
+
+## Vulkan capture and replay
+
+- Keep the default 256 MiB `softMemoryLimit`. Large Vulkan initial contents can otherwise create a device memory spike and stall or kill capture. The tool encodes and restores CaptureOptions automatically.
+- Replay Adreno captures on the original Android GPU when a desktop GPU reports an unavailable memory type. This is a replay compatibility issue, not proof that the RDC is corrupt.
+- Use the local port from `adb forward --list` whose remote endpoint is `localabstract:renderdoc_39920` with `rdc open --proxy`.
+- Expect an Android Vulkan render target export to appear vertically flipped when the surface transform is preserved.
+
+## GLES layer injection
+
+The GLES loader must be able to load `libVkLayer_GLES_RenderDoc.so` from the debuggable app directory. The tool copies it from:
+
+```text
+/data/local/debug/vulkan/libVkLayer_GLES_RenderDoc.so
+```
+
+If that source is missing, run `rdc android setup` first. Verify injection with:
+
+```powershell
+adb -s SERIAL shell getprop debug.gles.layers
+adb -s SERIAL shell run-as top.mobilegl.plugin.trace ls -l /data/user/0/top.mobilegl.plugin.trace/libVkLayer_GLES_RenderDoc.so
+```
+
+## Android debug settings
+
+Require these global settings for the replay package:
+
+```text
+gpu_debug_app=top.mobilegl.plugin.trace
+enable_gpu_debug_layers=1
+gpu_debug_layers=VK_LAYER_RENDERDOC_Capture
+```
+
+Some Xiaomi ROMs reject shell writes with `WRITE_SECURE_SETTINGS`. Configure the RenderDoc GPU debug layer through the device developer options or RenderDoc setup flow. The tool avoids rewriting settings that are already correct and restores only keys it actually changed.
+
+## rdc-cli device selection
+
+RenderDoc 1.41 can enumerate a device as a raw serial while `rdc android setup --serial` compares against `adb://SERIAL`. If the explicit command says the listed serial is not found and exactly one device is connected, retry without `--serial`. The repository tool performs this bounded fallback automatically.
+
+## Completion checks
+
+Treat capture as successful only when all checks pass:
+
+1. TargetControl returns `NewCapture` with the expected frame and API.
+2. `adb pull` produces a non-empty RDC and the manifest records its SHA-256.
+3. RenderDoc opens the RDC and reports more than zero events and draws.
+4. `rdc assert-clean --min-severity high` passes.
+5. The retrace result reaches the target call. Evaluate fixture SSIM according to the selected backend.