Merge pull request #141 from Droid-Deck/release/0.3.0

Release 0.3.0: version bump, Deck mode for everyone, release notes and media, Updates page fix

.coderabbit.yaml

@@ -1,67 +0,0 @@
-language: en-US
-early_access: false
-tone_instructions: >-
-  Prioritize actionable correctness, security, and runtime regressions. Keep
-  feedback concise. Do not request explanatory code comments; preserve license
-  headers and compiler-consumed annotations.
-reviews:
-  profile: chill
-  request_changes_workflow: false
-  high_level_summary: true
-  high_level_summary_in_walkthrough: true
-  poem: false
-  sequence_diagrams: false
-  tools:
-    github-checks:
-      enabled: false
-  auto_review:
-    enabled: true
-    auto_incremental_review: true
-    auto_pause_after_reviewed_commits: 0
-    drafts: false
-  pre_merge_checks:
-    docstrings:
-      mode: "off"
-    title:
-      mode: "off"
-    description:
-      mode: "off"
-  finishing_touches:
-    docstrings:
-      enabled: false
-    unit_tests:
-      enabled: false
-    simplify:
-      enabled: false
-    autofix:
-      enabled: false
-    fix_ci:
-      enabled: false
-    resolve_merge_conflict:
-      enabled: false
-  path_instructions:
-    - path: "**/*"
-      instructions: >-
-        For cleanup changes, compare executable behavior against the PR merge
-        base. Check for removed guards, changed return values, weakened compiler
-        flags, and deleted regression tests. A passing APK build alone does not
-        establish behavior preservation. Avoid style-only or comment-coverage
-        requests.
-    - path: "app/src/main/**"
-      instructions: >-
-        Review Android lifecycle, external-display visibility, input cancellation,
-        permissions, threading, and Compose state. For JNI, native, and Rust
-        changes, check ABI compatibility, resource ownership, synchronization,
-        and error paths. Preserve persisted user settings and existing runtime
-        contracts.
-    - path: "tools/**"
-      instructions: >-
-        Check shell quoting, error handling, path and filesystem semantics, and
-        Python helper behavior. Preserve MSI same-file protection and strict
-        compiler checks. Verify downstream patches apply to their pinned sources
-        and retain intended executable behavior, including embedded scripts.
-    - path: ".github/workflows/**"
-      instructions: >-
-        Check job permissions, triggers, merge validation, build variants,
-        signing, artifact paths, and release conditions. Verify checks apply to
-        the current PR head and keep review configuration advisory.

.gitattributes

@@ -1,12 +0,0 @@
-tools/linuxfs/** text=auto eol=lf
-tools/mangoapp/** text=auto eol=lf
-tools/comet/LICENSE whitespace=-blank-at-eof
-tools/comet/droiddeck.patch whitespace=-blank-at-eol,-blank-at-eof
-
-# These helpers are packaged verbatim and executed inside the Linux runtime.
-tools/linuxfs/overlay/** text eol=lf
-tools/linuxfs/desktop/** text eol=lf
-tools/mangoapp/mangoapp text eol=lf
-app/src/main/assets/desktop-removal/*.json text eol=lf
-app/src/main/assets/desktop-removal/*.txt text eol=lf
-*.pdf binary

.github/workflows/authorship.yml

@@ -1,40 +0,0 @@
-name: Build validation
-
-on:
-  pull_request_target:
-    branches: [main]
-    types: [opened, synchronize, reopened, edited, ready_for_review]
-  push:
-    branches: [main]
-  workflow_run:
-    workflows: [Build APK]
-    types: [completed]
-  workflow_dispatch:
-    inputs:
-      pr_number:
-        description: Pull request to validate; empty for main
-        required: false
-
-permissions:
-  contents: read
-  actions: read
-  pull-requests: read
-  statuses: write
-
-jobs:
-  validate:
-    name: Build APK
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.workflow_sha }}
-          fetch-depth: 0
-          persist-credentials: false
-      - name: Validate source and APK compilation
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh auth setup-git
-          python3 tools/release/validate_apk.py

.github/workflows/build-aaudio-sink.yml

@@ -1,5 +1,7 @@
 name: Build AAudio sink module
 
+# A quick check of tools/aaudio-sink on its own; the APK build compiles the same module into the
+# audio bundle. Runs on pushes that touch the module.
 on:
   push:
     paths:

.github/workflows/build-desktop-kde.yml

@@ -1,96 +0,0 @@
-name: Build desktop package (KDE Plasma)
-
-on:
-  push:
-    paths:
-      - 'tools/desktop-kde/**'
-      - '.github/workflows/build-desktop-kde.yml'
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag to publish as (e.g. desktop-kde-r1); empty = artifact only'
-        required: false
-        default: ''
-
-permissions:
-  contents: write
-
-jobs:
-  kwin:
-    runs-on: ubuntu-24.04-arm
-    timeout-minutes: 90
-    steps:
-      - uses: actions/checkout@v4
-      - name: Build KWin with nested desktop scaling
-        run: |
-          sudo apt-get update -qq && sudo apt-get install -y -qq zstd xz-utils gpgv patch binutils >/dev/null
-          bash tools/desktop-kde/build-kwin.sh out/kwin
-      - uses: actions/upload-artifact@v4
-        with:
-          name: desktop-kde-kwin
-          retention-days: 7
-          path: out/kwin/
-  build:
-    needs: kwin
-    runs-on: ubuntu-24.04
-    timeout-minutes: 90
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
-        with:
-          name: desktop-kde-kwin
-          path: out/kwin
-      - uses: actions/create-github-app-token@v2
-        id: components-token
-        if: github.event_name == 'workflow_dispatch' && inputs.tag != ''
-        with:
-          app-id: ${{ vars.DROIDDECK_CI_APP_ID }}
-          private-key: ${{ secrets.DROIDDECK_CI_APP_KEY }}
-          owner: Droid-Deck
-          repositories: DroidDeck-Components
-      - name: Refuse a published tag
-        if: github.event_name == 'workflow_dispatch' && inputs.tag != ''
-        env:
-          GH_TOKEN: ${{ steps.components-token.outputs.token }}
-        run: |
-          if gh release view '${{ inputs.tag }}' -R Droid-Deck/DroidDeck-Components >/dev/null 2>&1; then
-            echo "::error::${{ inputs.tag }} is already published, and published tags are never replaced: use a new tag"
-            exit 1
-          fi
-      - name: Build
-        run: |
-          set -euo pipefail
-          sudo apt-get update -qq && sudo apt-get install -y -qq zstd xz-utils gpgv >/dev/null
-          KDE_KWIN_OVERRIDE="$PWD/out/kwin" tools/desktop-kde/build.sh out
-          cp out/kwin/desktop-kde.kwin.txt out/
-          echo "size $(stat -c %s out/desktop-kde.tar.zst) sha256 $(cat out/desktop-kde.sha256)"
-          echo "language packs $(ls out/desktop-kde-i18n-*.tar.zst | wc -l)"
-      - uses: actions/upload-artifact@v4
-        with:
-          name: desktop-kde
-          retention-days: 7
-          compression-level: 0
-          path: |
-            out/desktop-kde.tar.zst
-            out/desktop-kde.packages.txt
-            out/desktop-kde.kwin.txt
-            out/desktop-kde.sha256
-            out/desktop-kde.i18n.txt
-            out/desktop-kde-i18n-*.tar.zst
-      - name: Publish
-        if: github.event_name == 'workflow_dispatch' && inputs.tag != ''
-        env:
-          GH_TOKEN: ${{ steps.components-token.outputs.token }}
-          GH_REPO: Droid-Deck/DroidDeck-Components
-        run: |
-          set -euo pipefail
-          TAG='${{ inputs.tag }}'
-          if gh release view "$TAG" >/dev/null 2>&1; then
-            echo "::error::$TAG is already published in DroidDeck-Components, and published tags are never replaced: use a new tag"
-            exit 1
-          fi
-          gh release create "$TAG" --latest=false --prerelease=false --title "$TAG" \
-            --notes "KDE Plasma desktop package for DroidDeck's Linux runtime ($GITHUB_REPOSITORY tools/desktop-kde, $GITHUB_SHA). size $(stat -c %s out/desktop-kde.tar.zst), sha256 $(cat out/desktop-kde.sha256). desktop-kde.packages.txt lists the signature-checked Arch Linux ARM packages it was built from." \
-            out/desktop-kde.tar.zst out/desktop-kde.sha256 out/desktop-kde.packages.txt out/desktop-kde.kwin.txt \
-            out/desktop-kde.i18n.txt out/desktop-kde-i18n-*.tar.zst
-          gh release edit "$TAG" --latest=false --prerelease=false

.github/workflows/build-fex.yml

@@ -1,49 +0,0 @@
-name: Build FEX (x86-64 Steam client)
-
-# Checks tools/fex: the same build DroidDeck-Components' build-fex.yml runs from this repository to publish FEX
-# (its single `fex` release and fex.json, which the app follows). Nothing is published from here.
-
-on:
-  push:
-    paths:
-      - 'tools/fex/**'
-      - '.github/workflows/build-fex.yml'
-  workflow_dispatch:
-    inputs:
-      thunks:
-        description: 'Build the host thunks (Vulkan/GL/X11/... to the runtime arm64 libraries)'
-        required: false
-        default: 'false'
-      cxxflags:
-        description: 'Extra CXXFLAGS for a diagnostic build (e.g. -DDEBUG_STRACE)'
-        required: false
-        default: ''
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    runs-on: ubuntu-24.04-arm
-    timeout-minutes: 120
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-      - name: Build in Arch Linux ARM
-        # Inputs reach the shell as environment variables, never pasted into the script.
-        env:
-          FEX_EXTRA_CXXFLAGS: ${{ inputs.cxxflags }}
-          FEX_THUNKS: ${{ inputs.thunks == 'true' && '1' || '0' }}
-        run: |
-          set -euo pipefail
-          docker run --rm -e FEX_EXTRA_CXXFLAGS="$FEX_EXTRA_CXXFLAGS" -e FEX_THUNKS="$FEX_THUNKS" -v "$PWD:/work" -w /work menci/archlinuxarm:base-devel bash tools/fex/build-in-arch.sh
-          sudo chown -R "$(id -u):$(id -g)" .
-      - uses: actions/upload-artifact@v4
-        with:
-          name: fex
-          path: |
-            fex.tzst
-            fex.tzst.sha256
-            fex-needed.txt
-            fex-files.txt

.github/workflows/build-gamescope.yml

@@ -1,5 +1,9 @@
 name: Build gamescope (patched)
 
+# The runtime's own gamescope (Arch Linux ARM's 3.16.29 package) rebuilt with the patches under
+# tools/gamescope/patches, in an Arch Linux ARM container on an arm64 runner, then published as a
+# release asset the apk build fetches (tools/gamescope/release.env names the tag and sha). The
+# hosted runtime image is never changed: the apk stages the binary over /usr/local/bin.
 on:
   push:
     paths:
@@ -39,4 +43,6 @@ jobs:
         run: |
           set -euo pipefail
           gh release create "${{ inputs.tag }}" --latest=false --prerelease=false --title "${{ inputs.tag }}" --notes "gamescope 3.16.29 with tools/gamescope/patches; staged by the apk over /usr/local/bin/gamescope. sha256 $(cut -d' ' -f1 gamescope.tzst.sha256)" gamescope.tzst gamescope.tzst.sha256 || gh release upload "${{ inputs.tag }}" gamescope.tzst gamescope.tzst.sha256 --clobber
+          # A component the apk fetches by tag, never something users install: it must not
+          # become the repo's Latest release or appear as a pre-release, also when re-uploaded.
           gh release edit "${{ inputs.tag }}" --latest=false --prerelease=false

.github/workflows/build-wlroots.yml

@@ -0,0 +1,49 @@
+name: Build wlroots (patched)
+
+# The desktop's wlroots (Arch Linux ARM's wlroots0.20, what the desktop package's labwc links)
+# rebuilt with tools/wlroots/patches: a Vulkan DMA-BUF allocator for the Adreno node, which is not
+# a DRM device, so labwc's vulkan and gles2 renderers can start. Built in an Arch Linux ARM
+# container on an arm64 runner and published as a release asset the apk build fetches
+# (tools/wlroots/release.env names the tag and sha). The hosted desktop package is never changed.
+on:
+  push:
+    paths:
+      - 'tools/wlroots/**'
+      - '.github/workflows/build-wlroots.yml'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to publish as (e.g. wlroots-0.20.2-p1); empty = artifact only'
+        required: false
+        default: ''
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build in Arch Linux ARM
+        run: |
+          set -euo pipefail
+          docker run --rm -v "$PWD:/work" -w /work menci/archlinuxarm:base-devel bash tools/wlroots/build-in-arch.sh
+          sudo chown -R "$(id -u):$(id -g)" .
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wlroots-patched
+          path: |
+            wlroots.tzst
+            wlroots.tzst.sha256
+      - name: Publish
+        if: github.event_name == 'workflow_dispatch' && inputs.tag != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          gh release create "${{ inputs.tag }}" --latest=false --prerelease=false --title "${{ inputs.tag }}" --notes "wlroots 0.20.2 with tools/wlroots/patches (Vulkan DMA-BUF allocator for non-DRM GPU nodes); staged by the apk at /usr/local/lib/droiddeck-wlroots for the desktop's GPU renderers. sha256 $(cut -d' ' -f1 wlroots.tzst.sha256)" wlroots.tzst wlroots.tzst.sha256 || gh release upload "${{ inputs.tag }}" wlroots.tzst wlroots.tzst.sha256 --clobber
+          # A component the apk fetches by tag, never something users install: it must not
+          # become the repo's Latest release or appear as a pre-release, also when re-uploaded.
+          gh release edit "${{ inputs.tag }}" --latest=false --prerelease=false

.github/workflows/build.yml

@@ -22,72 +22,17 @@ permissions:
   pull-requests: write
 
 concurrency:
+  # Replace older builds only for the same PR. Each push/dispatch gets its own group so one main
+  # build cannot cancel another before it signs and publishes.
   group: build-${{ github.event.pull_request.number || github.run_id }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 env:
-  PRELOAD_CACHE_VERSION: v6
+  PRELOAD_CACHE_VERSION: v2
 
 jobs:
-  xbox:
-    name: Xbox ARM64 backend
-    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
-    runs-on: ubuntu-24.04-arm
-    timeout-minutes: 30
-    outputs:
-      base-sha: ${{ steps.merge.outputs.base-sha }}
-      tree-sha: ${{ steps.source.outputs.tree-sha }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          fetch-depth: 0
-          persist-credentials: false
-      - name: Pin and merge the APK source
-        id: merge
-        if: github.event_name == 'pull_request'
-        run: |
-          set -euo pipefail
-          git fetch --no-tags origin main
-          echo "base-sha=$(git rev-parse origin/main)" >> "$GITHUB_OUTPUT"
-          git config user.name "ci"
-          git config user.email "[email protected]"
-          git merge --no-ff --no-edit origin/main
-      - name: Record backend source tree
-        id: source
-        run: echo "tree-sha=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_OUTPUT"
-      - uses: actions/cache@v4
-        id: xbox-cache
-        with:
-          path: |
-            app/src/main/assets/linuxfs/usr/local/lib/droiddeck-xbox
-            app/build/xbox/xodus-droiddeck-source.tar.xz
-            app/build/xbox/runtime/*-source.tar.xz
-          key: xbox-arm64-${{ hashFiles('tools/xbox/**') }}
-      - name: Build Xbox backend
-        if: steps.xbox-cache.outputs.cache-hit != 'true'
-        run: |
-          rustup toolchain install 1.99.0 --profile minimal
-          sudo apt-get update -qq
-          sudo apt-get install -y build-essential pkg-config libssl-dev protobuf-compiler cmake xz-utils
-          bash tools/xbox/build.sh
-      - uses: actions/upload-artifact@v4
-        with:
-          name: xbox-arm64
-          path: app/src/main/assets/linuxfs/usr/local/lib/droiddeck-xbox
-          retention-days: 14
-      - uses: actions/upload-artifact@v4
-        with:
-          name: xbox-corresponding-source
-          path: |
-            app/build/xbox/xodus-droiddeck-source.tar.xz
-            app/build/xbox/runtime/*-source.tar.xz
-          if-no-files-found: error
-          retention-days: 14
-
   build:
-    needs: xbox
-    name: Compile and test APK
+    name: Build APK
     if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
     runs-on: ubuntu-24.04
     timeout-minutes: 45
@@ -98,25 +43,6 @@ jobs:
         with:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 0
-          persist-credentials: false
-
-      - name: Check human authorship
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          BEFORE: ${{ github.event.before }}
-        run: |
-          set -euo pipefail
-          if [ "$EVENT_NAME" = pull_request ]; then
-            git fetch --no-tags origin main
-            base=$(git merge-base origin/main HEAD)
-            checker="$RUNNER_TEMP/droiddeck-check-authorship.py"
-            git show origin/main:tools/release/check_authorship.py > "$checker"
-            python3 "$checker" "$base..HEAD" --event "$GITHUB_EVENT_PATH"
-          elif [ "$EVENT_NAME" = push ] && [ "$BEFORE" != 0000000000000000000000000000000000000000 ]; then
-            python3 tools/release/check_authorship.py "$BEFORE..HEAD"
-          else
-            python3 tools/release/check_authorship.py HEAD
-          fi
 
       - name: The packages a signed build ships as
         id: variants
@@ -131,35 +57,16 @@ jobs:
             exit 1
           fi
 
-      - name: Version bumps are isolated
-        if: github.event_name == 'pull_request'
-        run: |
-          set -euo pipefail
-          git fetch --no-tags origin main
-          base=$(git merge-base origin/main HEAD)
-          diff=$(git diff -U0 "$base..HEAD" -- app/build.gradle)
-          grep -Eq '^[+-][[:space:]]*version(Code|Name)[[:space:]]' <<<"$diff" || exit 0
-          other_files=$(git diff --name-only "$base..HEAD" | grep -v '^app/build.gradle$' || true)
-          other_gradle=$(grep -E '^[+-]' <<<"$diff" | grep -Ev '^(---|\+\+\+)' | grep -Ev '^[+-][[:space:]]*version(Code|Name)[[:space:]]' || true)
-          if [[ -n "$other_files" || -n "$other_gradle" ]]; then
-            echo "::error::versionCode/versionName changes must be isolated in their own PR"
-            echo "A version PR may only change the versionCode/versionName lines in app/build.gradle." >> "$GITHUB_STEP_SUMMARY"
-            exit 1
-          fi
-
       - name: Merge onto main, or say what conflicts
         if: github.event_name == 'pull_request'
-        env:
-          BUILD_BASE_SHA: ${{ needs.xbox.outputs.base-sha }}
         run: |
           set -uo pipefail
           git config user.name "ci"
           git config user.email "[email protected]"
           git fetch --no-tags origin main
-          git fetch --no-tags origin "$BUILD_BASE_SHA"
-          BASE=$(git rev-parse --short FETCH_HEAD)
+          BASE=$(git rev-parse --short origin/main)
           HEAD=$(git rev-parse --short HEAD)
-          if git merge --no-ff --no-edit FETCH_HEAD >/tmp/merge.out 2>&1; then
+          if git merge --no-ff --no-edit origin/main >/tmp/merge.out 2>&1; then
             {
               echo "###  Mergeable"
               echo
@@ -206,11 +113,6 @@ jobs:
           echo "::error::the pull request conflicts with main: $(echo $FILES | tr '\n' ' ')"
           exit 1
 
-      - name: Verify backend and APK source match
-        env:
-          XBOX_SOURCE_TREE: ${{ needs.xbox.outputs.tree-sha }}
-        run: test "$(git rev-parse 'HEAD^{tree}')" = "$XBOX_SOURCE_TREE"
-
       - uses: actions/setup-java@v4
         with:
           distribution: temurin
@@ -255,15 +157,16 @@ jobs:
         uses: actions/cache@v4
         with:
           path: app/src/main/assets/linuxfs
-          key: preloads-${{ env.PRELOAD_CACHE_VERSION }}-${{ hashFiles('app/src/main/cpp/fakeinput_steam.cpp', 'app/src/main/cpp/adrenotools/src/hook/kgsl.h', 'tools/quest/*', 'tools/linuxfs/preload/*.c', 'tools/linuxfs/build-x86-preloads.sh', 'tools/linuxfs/fex/*', 'tools/linuxfs/clipboard/*.c', 'tools/linuxfs/ssbs/*.c', 'tools/proot/fastpath/*.c', 'tools/linuxfs/overlay/usr/local/bin/*', 'tools/linuxfs/overlay/usr/bin/**', 'tools/linuxfs/desktop/*', 'tools/gamescope/release.env', 'tools/wlroots/release.env', 'tools/linuxfs/uruntime.env', 'tools/linuxfs/licenses/*', 'tools/mangoapp/*', 'tools/msitools/**', 'tools/comet/**', 'tools/xbox/**', 'tools/linuxfs/debian-image.env', 'tools/vr/**') }}
+          key: preloads-${{ env.PRELOAD_CACHE_VERSION }}-${{ hashFiles('app/src/main/cpp/fakeinput_steam.cpp', 'tools/linuxfs/preload/*.c', 'tools/proot/fastpath/*.c', 'tools/linuxfs/overlay/usr/local/bin/*', 'tools/linuxfs/overlay/usr/bin/**', 'tools/linuxfs/desktop/*', 'tools/gamescope/release.env', 'tools/wlroots/release.env', 'tools/mangoapp/*') }}
 
       - name: Build libfakeinput.so and libblsession.so (glibc aarch64)
         if: steps.preloads.outputs.cache-hit != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
-          sudo apt-get -o Dir::Etc::sourcelist=sources.list.d/ubuntu.sources \
-            -o Dir::Etc::sourceparts=- -o Acquire::Retries=3 update -qq
-          sudo apt-get install -y -qq gcc-aarch64-linux-gnu g++-aarch64-linux-gnu libvulkan1 mesa-vulkan-drivers >/dev/null
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq gcc-aarch64-linux-gnu g++-aarch64-linux-gnu >/dev/null
           D=app/src/main/assets/linuxfs
           mkdir -p "$D"
           aarch64-linux-gnu-g++ -shared -fPIC -O2 -Wall -Wno-attributes -Wno-nonnull-compare \
@@ -276,18 +179,7 @@ jobs:
           aarch64-linux-gnu-gcc -shared -fPIC -O2 -Wall -pthread \
             -o "$D/libblfastpath.so" tools/proot/fastpath/fastpath.c -ldl
           aarch64-linux-gnu-strip --strip-unneeded "$D/libblfastpath.so"
-          aarch64-linux-gnu-gcc -shared -fPIC -O2 -Wall -nostdlib -ffreestanding -fno-stack-protector \
-            -fno-tree-loop-distribute-patterns -Wl,-z,defs -o "$D/libblaudit.so" tools/proot/fastpath/audit.c
-          aarch64-linux-gnu-strip --strip-unneeded "$D/libblaudit.so"
-          aarch64-linux-gnu-gcc -shared -fPIC -O2 -Wall -pthread \
-            -o "$D/libssbs.so" tools/linuxfs/ssbs/ssbs_adapter.c -ldl
-          aarch64-linux-gnu-strip --strip-unneeded "$D/libssbs.so"
-          mkdir -p "$D/usr/local/bin"
-          aarch64-linux-gnu-gcc -O2 -Wall -Wextra -o "$D/usr/local/bin/droiddeck-clipboard" tools/linuxfs/clipboard/clipboard.c -ldl
-          aarch64-linux-gnu-strip --strip-unneeded "$D/usr/local/bin/droiddeck-clipboard"
-          VK_INCLUDE=$(ls -d "${ANDROID_NDK_LATEST_HOME:-${ANDROID_NDK_HOME:-$ANDROID_NDK_ROOT}}"/toolchains/llvm/prebuilt/*/sysroot/usr/include | head -1) \
-            tools/vr/build.sh --native "$D/usr/local/lib/droiddeck-vr"
-          for script in tools/linuxfs/overlay/usr/local/bin/droiddeck-* tools/linuxfs/overlay/usr/local/bin/steam-compatibility; do
+          for script in tools/linuxfs/overlay/usr/local/bin/bannerlator-*; do
             install -Dm644 "$script" "$D/usr/local/bin/$(basename "$script")"
           done
           for f in tools/linuxfs/overlay/usr/bin/* tools/linuxfs/overlay/usr/bin/steamos-polkit-helpers/*; do
@@ -295,18 +187,20 @@ jobs:
           done
           if [ -f tools/gamescope/release.env ]; then
             . tools/gamescope/release.env
-            curl -fsSL --retry 3 -o gamescope.tzst "https://github.com/${GAMESCOPE_REPO:-${GITHUB_REPOSITORY}}/releases/download/${GAMESCOPE_TAG}/gamescope.tzst"
+            gh release download "${GAMESCOPE_TAG}" -R "${GITHUB_REPOSITORY}" -p gamescope.tzst -O gamescope.tzst
             echo "${GAMESCOPE_SHA256}  gamescope.tzst" | sha256sum -c -
             tar --use-compress-program=unzstd -xf gamescope.tzst -C "$D"
             test -f "$D/usr/local/bin/gamescope"
             rm gamescope.tzst
           fi
-          . tools/linuxfs/uruntime.env
-          curl -fsSL --retry 3 -o uruntime "https://github.com/VHSgunzo/uruntime/releases/download/${URUNTIME_VERSION}/${URUNTIME_ASSET}"
-          echo "${URUNTIME_SHA256}  uruntime" | sha256sum -c -
-          install -Dm644 uruntime "$D/usr/local/lib/droiddeck/uruntime"
-          install -Dm644 tools/linuxfs/licenses/uruntime-LICENSE "$D/usr/local/share/licenses/uruntime/LICENSE"
-          rm uruntime
+          if [ -f tools/wlroots/release.env ]; then
+            . tools/wlroots/release.env
+            gh release download "${WLROOTS_TAG}" -R "${GITHUB_REPOSITORY}" -p wlroots.tzst -O wlroots.tzst
+            echo "${WLROOTS_SHA256}  wlroots.tzst" | sha256sum -c -
+            tar --use-compress-program=unzstd -xf wlroots.tzst -C "$D"
+            test -f "$D/usr/local/lib/droiddeck-wlroots/libwlroots-0.20.so"
+            rm wlroots.tzst
+          fi
           M="$D/usr/local/lib/mangoapp"
           mkdir -p "$M" mango-pkgs
           grep -v '^#' tools/mangoapp/packages.txt | while read -r sum url; do
@@ -320,119 +214,22 @@ jobs:
           for so in libfmt.so.10 libspdlog.so.1.13 libglfw.so.3 libtraceevent.so.1; do
             cp -L "mango-pkgs/usr/lib/$so" "$M/$so"
           done
+          # Ours, not the package's: GPU memory without tracefs (tools/mangoapp/libtracefs-shim.c).
           aarch64-linux-gnu-gcc -shared -fPIC -O2 -Wall -Wl,-soname,libtracefs.so.1 \
             -o "$M/libtracefs.so.1" tools/mangoapp/libtracefs-shim.c
           aarch64-linux-gnu-strip --strip-unneeded "$M/libtracefs.so.1"
           install -Dm644 tools/mangoapp/mangoapp "$D/usr/local/bin/mangoapp"
           rm -rf mango-pkgs
           ls -l "$M"
-          mkdir -p pw-pkgs
-          grep -v '^#' tools/pipewire/packages.txt | while read -r sum url; do
-            [ -n "$url" ] || continue
-            curl -fsSL --retry 3 -o pw-pkgs/pkg.tar.zst "$url"
-            echo "$sum  pw-pkgs/pkg.tar.zst" | sha256sum -c -
-            tar --use-compress-program=unzstd -xf pw-pkgs/pkg.tar.zst -C pw-pkgs
-            rm pw-pkgs/pkg.tar.zst
-          done
-          tools/pipewire/assemble.sh pw-pkgs "$D/usr/local/lib/droiddeck-pipewire.tzst"
-          rm -rf pw-pkgs
-          ls -l "$D/usr/local/lib/droiddeck-pipewire.tzst"
-          T="$D/usr/local/lib/droiddeck-msitools"
-          mkdir -p "$T" msi-pkgs
-          grep -v '^#' tools/msitools/packages.txt | while read -r sum url; do
-            [ -n "$url" ] || continue
-            curl -fsSL --retry 3 -o msi-pkgs/pkg.tar.xz "$url"
-            echo "$sum  msi-pkgs/pkg.tar.xz" | sha256sum -c -
-            tar -xJf msi-pkgs/pkg.tar.xz -C msi-pkgs
-            rm msi-pkgs/pkg.tar.xz
-          done
-          install -m644 msi-pkgs/usr/bin/msiinfo "$T/msiinfo"
-          install -m644 msi-pkgs/usr/bin/cabextract "$T/cabextract"
-          install -m644 msi-pkgs/usr/lib/7zip/7z "$T/7z"
-          install -m644 msi-pkgs/usr/lib/7zip/7z.so "$T/7z.so"
-          for so in libmsi-1.0.so.0 libgsf-1.so.114 libgcab-1.0.so.0; do
-            cp -L "msi-pkgs/usr/lib/$so" "$T/$so"
-          done
-          for f in NOTICE GPL-2 GPL-3 LGPL-2.1 7zip-License 7zip-unRarLicense; do
-            install -Dm644 "tools/msitools/licenses/$f" "$D/usr/local/share/licenses/droiddeck-msitools/$f"
-          done
-          rm -rf msi-pkgs
-          ls -l "$T"
           install -Dm644 tools/linuxfs/desktop/droiddeck-desktop "$D/usr/local/bin/droiddeck-desktop"
           install -Dm644 tools/linuxfs/desktop/droiddeck-gpu "$D/usr/local/bin/droiddeck-gpu"
           install -Dm644 tools/linuxfs/desktop/droiddeck-desktop-gpu "$D/usr/local/bin/droiddeck-desktop-gpu"
-          install -Dm644 tools/linuxfs/desktop/kwin_wayland_wrapper "$D/usr/local/bin/kwin_wayland_wrapper"
+          install -Dm644 tools/linuxfs/desktop/autostart "$D/etc/xdg/labwc/autostart"
+          install -Dm644 tools/linuxfs/desktop/rc.xml "$D/etc/xdg/labwc/rc.xml"
+          install -Dm644 tools/linuxfs/desktop/panel.conf "$D/etc/xdg/lxqt/panel.conf"
           install -Dm644 tools/linuxfs/desktop/firefox-droiddeck.js "$D/usr/lib/firefox/defaults/pref/droiddeck.js"
           ls -lR "$D"
 
-      - name: Fetch the Debian image the preloads build in
-        if: steps.preloads.outputs.cache-hit != 'true'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          set -euo pipefail
-          . tools/linuxfs/debian-image.env
-          image=public.ecr.aws/docker/library/debian:bullseye
-          if gh release download "$DEBIAN_IMAGE_TAG" -R "$GITHUB_REPOSITORY" -p "$DEBIAN_IMAGE_ASSET" -O /tmp/debian-image.tar.zst \
-             && { [ -z "$DEBIAN_IMAGE_SHA256" ] || echo "$DEBIAN_IMAGE_SHA256  /tmp/debian-image.tar.zst" | sha256sum -c -; }; then
-            zstd -dc /tmp/debian-image.tar.zst | docker load
-            rm -f /tmp/debian-image.tar.zst
-          else
-            echo "::warning::the hosted Debian image could not be fetched; pulling from the registry instead"
-            for attempt in 1 2 3 4 5; do
-              docker pull "$image" && break
-              [ "$attempt" -lt 5 ] || { echo "::error::could not pull $image after $attempt attempts"; exit 1; }
-              echo "pull attempt $attempt failed (registry busy?); retrying in $((attempt * 30)) s"
-              sleep $((attempt * 30))
-            done
-          fi
-          docker image ls "$image"
-
-      - name: Build the x86 preloads FEX guests load (glibc 2.31)
-        if: steps.preloads.outputs.cache-hit != 'true'
-        run: |
-          set -euo pipefail
-          docker run --rm -v "$PWD:/src" -w /src public.ecr.aws/docker/library/debian:bullseye bash -c '
-            set -euo pipefail
-            install_compilers() {
-              apt-get -o Acquire::Check-Valid-Until=false update -qq &&
-                DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends gcc g++ gcc-multilib g++-multilib binutils >/dev/null
-            }
-            printf "deb http://deb.debian.org/debian bullseye main\ndeb http://security.debian.org/debian-security bullseye-security main\n" > /etc/apt/sources.list
-            if ! install_compilers; then
-              printf "deb http://archive.debian.org/debian bullseye main\ndeb http://archive.debian.org/debian-security bullseye-security main\n" > /etc/apt/sources.list
-              install_compilers
-            fi
-            tools/linuxfs/build-x86-preloads.sh app/src/main/assets/linuxfs
-          '
-          sudo chown -R "$(id -u):$(id -g)" app/src/main/assets/linuxfs
-          ls -l app/src/main/assets/linuxfs/x86_64 app/src/main/assets/linuxfs/i386
-
-      - name: Bundle the droiddeck-esync packs
-        run: |
-          set -euo pipefail
-          if [ -f tools/droiddeck-esync/release.env ]; then
-            . tools/droiddeck-esync/release.env
-            release_url="https://github.com/${SYNC_BUNDLE_REPO}/releases/download/${SYNC_BUNDLE_TAG}"
-            curl -fsSL --retry 3 -o sync-bundle.tzst "$release_url/$SYNC_BUNDLE_ASSET"
-            echo "$SYNC_BUNDLE_SHA256  sync-bundle.tzst" | sha256sum -c -
-            mkdir -p app/src/main/assets/droiddeck-esync
-            tar --use-compress-program=unzstd -xf sync-bundle.tzst -C app/src/main/assets/droiddeck-esync
-            rm sync-bundle.tzst
-            curl -fsSL --retry 3 -o sync-index.json "$release_url/index.json"
-            revoked=$(python3 -c 'import json, sys; print(" ".join(p["id"] for p in json.load(open(sys.argv[1]))["packs"] if p.get("revoked") is True))' sync-index.json)
-            for id in $revoked; do
-              if [ -e "app/src/main/assets/droiddeck-esync/packs/$id.tzst" ]; then
-                echo "::warning::$SYNC_BUNDLE_ASSET carries revoked pack $id; it is left out of the APK (point tools/droiddeck-esync/release.env at a newer bundle)"
-                rm -f "app/src/main/assets/droiddeck-esync/packs/$id.tzst"
-              fi
-            done
-            rm sync-index.json
-            test -f app/src/main/assets/droiddeck-esync/index.json
-            test -f app/src/main/assets/droiddeck-esync/index.json.sig
-            ls -lR app/src/main/assets/droiddeck-esync
-          fi
-
       - name: Cache PulseAudio 13.0 source
         id: pa-src
         uses: actions/cache@v4
@@ -445,8 +242,6 @@ jobs:
           set -euo pipefail
           curl -fsSL -o pa.tar.gz https://github.com/pulseaudio/pulseaudio/archive/refs/tags/v13.0.tar.gz
           mkdir -p pa13 && tar -xzf pa.tar.gz -C pa13 --strip-components=1 && rm pa.tar.gz
-      - name: Fetch DirectAudio (tools/directaudio/release.env)
-        run: tools/directaudio/fetch.sh "$PWD" "$PWD/sink-out"
       - name: Build the AAudio sink into the audio bundle
         run: |
           set -euo pipefail
@@ -456,12 +251,12 @@ jobs:
           tar --use-compress-program=unzstd -xf app/src/main/assets/pulseaudio.tzst -C pa-bundle
           test ! -f pa-bundle/modules/arm64/module-aaudio-sink.so
           install -m755 sink-out/module-aaudio-sink.so pa-bundle/modules/arm64/module-aaudio-sink.so
-          install -m755 sink-out/module-directaudio-native-sink.so pa-bundle/modules/arm64/module-directaudio-native-sink.so
+          install -m755 sink-out/module-directaudio-sink.so pa-bundle/modules/arm64/module-directaudio-sink.so
           (cd pa-bundle && tar --use-compress-program='zstd -19' -cf ../pulseaudio.tzst .)
-          mkdir -p app/build/prepared-assets
-          mv pulseaudio.tzst app/build/prepared-assets/pulseaudio.tzst
-          tar --use-compress-program=unzstd -tf app/build/prepared-assets/pulseaudio.tzst | grep -c '\.so$'
+          mv pulseaudio.tzst app/src/main/assets/pulseaudio.tzst
+          tar --use-compress-program=unzstd -tf app/src/main/assets/pulseaudio.tzst | grep -c '\.so$'
           rm -rf pa-bundle sink-out
+
       - name: Cache proot
         id: proot
         uses: actions/cache@v4
@@ -480,60 +275,30 @@ jobs:
       - name: Check the preloads
         run: |
           set -euo pipefail
-          bash tools/linuxfs/check-preloads.sh app/src/main/assets/linuxfs
-
-      - name: Check Quest tracking IPC
-        run: |
-          set -euo pipefail
-          NDK="${ANDROID_NDK_LATEST_HOME:-${ANDROID_NDK_HOME:-$ANDROID_NDK_ROOT}}"
-          VK_INCLUDE=$(ls -d "$NDK"/toolchains/llvm/prebuilt/*/sysroot/usr/include | head -1)
-          mkdir -p build/vr/include
-          cp -R "$VK_INCLUDE/vulkan" build/vr/include/
-          if [ -d "$VK_INCLUDE/vk_video" ]; then cp -R "$VK_INCLUDE/vk_video" build/vr/include/; fi
-          g++ -std=c++17 -Wall -Wextra -Werror -pthread tools/vr/tests/test_xr_tracking.cpp -o /tmp/test-xr-tracking
-          /tmp/test-xr-tracking
-          g++ -std=c++17 -Wall -Wextra -Werror tools/vr/tests/test_xr_touch.cpp -o /tmp/test-xr-touch
-          /tmp/test-xr-touch
-          g++ -std=c++17 -Wall -Wextra -Werror tools/vr/tests/test_pad_controller_config.cpp -o /tmp/test-pad-controller-config
-          /tmp/test-pad-controller-config
-          g++ -std=c++17 -Wall -Wextra -Werror -pthread tools/vr/tests/test_xr_vsync.cpp -o /tmp/test-xr-vsync
-          /tmp/test-xr-vsync
-          g++ -std=c++17 -Wall -Wextra -Werror -pthread tools/vr/tests/test_xr_frames.cpp -o /tmp/test-xr-frames
-          /tmp/test-xr-frames
-          cc -Itools/vr/third_party/wayland -c tools/vr/src/wayland_client_stub.c -o /tmp/test-wayland-stub.o
-          cc -Itools/vr/third_party/wayland -c app/src/main/cpp/waylandcomp/generated/xdg-shell-protocol.c -o /tmp/test-xdg-shell.o
-          g++ -std=c++17 -Wall -Wextra -Werror -Wno-unused-parameter -Wno-missing-field-initializers -pthread -Ibuild/vr/include \
-            -Itools/vr/third_party/wayland -Iapp/src/main/cpp/waylandcomp/generated \
-            tools/vr/tests/test_presenter_shutdown.cpp tools/vr/src/presenter.cpp /tmp/test-wayland-stub.o /tmp/test-xdg-shell.o \
-            -ldl -o /tmp/test-presenter-shutdown
-          timeout 10 /tmp/test-presenter-shutdown
-
-      - name: Rust toolchain for the store engines (aarch64-linux-android)
-        id: rust
-        run: |
-          set -euo pipefail
-          rustup target add aarch64-linux-android
-          echo "rustc=$(rustc -V | awk '{print $2}')" >> "$GITHUB_OUTPUT"
-          rustc -V; cargo -V
-
-      - name: Cache cargo registry and the store engines' target
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry/index
-            ~/.cargo/registry/cache
-            ~/.cargo/git/db
-            ~/.cargo/bin/cargo-ndk
-            app/src/main/rust/stores/target
-          key: stores-${{ steps.rust.outputs.rustc }}-${{ hashFiles('app/src/main/rust/stores/Cargo.lock') }}
-          restore-keys: |
-            stores-${{ steps.rust.outputs.rustc }}-
-
-      - name: cargo-ndk
-        run: |
-          set -euo pipefail
-          command -v cargo-ndk >/dev/null || cargo install cargo-ndk --locked
-          cargo ndk --version
+          D=app/src/main/assets/linuxfs
+          NEED=$(readelf -d "$D/libfakeinput.so" | sed -n 's/.*NEEDED.*\[\(.*\)\]/\1/p')
+          for bad in libstdc++.so.6 libgcc_s.so.1; do
+            if printf '%s\n' "$NEED" | grep -qx "$bad"; then
+              echo "::error::libfakeinput.so links $bad - the C++ runtime must stay static"; exit 1
+            fi
+          done
+          syms() { readelf -Ws "$1" | awk '$4 == "FUNC" && $5 == "GLOBAL" {sub(/@.*/, "", $8); print $8}'; }
+          FAKE=$(syms "$D/libfakeinput.so")
+          for sym in open openat ioctl read close poll ppoll select stat fstat access scandir; do
+            grep -qx "$sym" <<<"$FAKE" || { echo "::error::libfakeinput.so does not export $sym"; exit 1; }
+          done
+          # The static C++ runtime stays private: every session process preloads this library,
+          # and an exported personality routine takes over other programs' unwinding (shadPS4
+          # aborted in pthread_exit).
+          if grep -qxE '__gxx_personality_v0|__cxa_throw|_Unwind_Resume' <<<"$FAKE"; then
+            echo "::error::libfakeinput.so exports the C++ runtime"; exit 1
+          fi
+          SESSION=$(syms "$D/libblsession.so")
+          for sym in socket bind getsockname setsockopt statfs statvfs; do
+            grep -qx "$sym" <<<"$SESSION" || { echo "::error::libblsession.so does not export $sym"; exit 1; }
+          done
+          test -f "$D/usr/local/bin/bannerlator-session"
+          test -f "$D/usr/local/bin/bannerlator-proton-extra"
 
       - name: Cache the CMake build tree
         uses: actions/cache@v4
@@ -541,90 +306,44 @@ jobs:
           path: |
             app/.cxx
             app/build/intermediates/cxx
-          key: cxx-${{ env.NDK_VERSION }}-${{ hashFiles('app/src/main/cpp/**', 'tools/vr/src/xr_*.h') }}
+          key: cxx-${{ env.NDK_VERSION }}-${{ hashFiles('app/src/main/cpp/**') }}
           restore-keys: |
             cxx-${{ env.NDK_VERSION }}-
 
-      - uses: actions/download-artifact@v4
-        with:
-          name: xbox-arm64
-          path: app/src/main/assets/linuxfs/usr/local/lib/droiddeck-xbox
-
-      - name: Build GOG Galaxy companion
-        if: steps.preloads.outputs.cache-hit != 'true'
-        run: |
-          rustup toolchain install 1.90.0 --profile minimal
-          rustup target add --toolchain 1.90.0 aarch64-unknown-linux-gnu
-          RUSTUP_TOOLCHAIN=1.90.0 bash tools/comet/build.sh
-
-      - name: Build the add-on packs
-        run: bash tools/packs/build.sh app/build/packs
-
       - name: Build
         id: build
         env:
           DROIDDECK_BUILD_LABEL: ${{ steps.build-label.outputs.label }}
-          SGDB_API_KEY: ${{ secrets.SGDB_API_KEY }}
         run: |
           set -o pipefail
-          python3 tools/quest/build-driver.py "$ANDROID_HOME/ndk/$NDK_VERSION"
-          python3 tools/release/runtime_inputs.py record
           ./gradlew assembleRelease --console=plain -PndkVersion="$NDK_VERSION" 2>&1 | tee /tmp/build.log
-          python3 tools/release/check_session_assets.py app/build/outputs/apk/release/app-release.apk
-          python3 tools/release/runtime_inputs.py apk app/build/outputs/apk/release/app-release.apk
-
-      - name: Check the store engines' library
-        run: |
-          set -euo pipefail
-          NDK="${ANDROID_NDK_LATEST_HOME:-${ANDROID_NDK_HOME:-$ANDROID_NDK_ROOT}}"
-          python3 tools/release/check_android_libraries.py app/build/outputs/apk/release/app-release.apk \
-            --readelf "$NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-readelf"
-          git diff --stat -- app/src/main/rust/stores/Cargo.lock
-          git diff --exit-code -- app/src/main/rust/stores/Cargo.lock \
-            || { echo "::error::Cargo.lock changed during the build; commit the regenerated lockfile (uploaded as stores-cargo-lock)"; exit 1; }
-
-      - name: Store engines host unit tests
-        timeout-minutes: 10
-        continue-on-error: true
-        run: |
-          cd app/src/main/rust/stores
-          cargo test --locked 2>&1 | tail -60
-
-      - name: Upload the regenerated Cargo.lock
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: stores-cargo-lock
-          path: app/src/main/rust/stores/Cargo.lock
-          if-no-files-found: ignore
-
-      - name: Install Python test dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y -qq python3-yaml
 
       - name: Steam import and game environment tests
         run: python3 -m unittest discover -s tools/tests -p 'test_*.py'
 
       - name: Unit tests
-        id: unit-tests
-        run: |
-          set -o pipefail
-          mkdir -p app/build
-          ./gradlew testReleaseUnitTest --console=plain --info --stacktrace -Drobolectric.logging=stderr -PndkVersion="$NDK_VERSION" 2>&1 | tee app/build/unit-tests.log
+        run: ./gradlew testReleaseUnitTest --console=plain -PndkVersion="$NDK_VERSION"
 
-      - name: Upload unit test diagnostics
-        id: unit-test-diagnostics
-        if: always() && steps.unit-tests.outcome != 'skipped'
-        uses: actions/upload-artifact@v4
-        with:
-          name: unit-test-results
-          path: |
-            app/build/unit-tests.log
-            app/build/test-results/testReleaseUnitTest/
-            app/build/reports/tests/testReleaseUnitTest/
-          if-no-files-found: ignore
-          retention-days: 14
+      - name: Check the native dependency closure
+        run: |
+          set -euo pipefail
+          APK=$(find app/build/outputs/apk -name '*.apk' | head -1)
+          WORK=$(mktemp -d)
+          unzip -q "$APK" 'lib/arm64-v8a/*' -d "$WORK"
+          cd "$WORK/lib/arm64-v8a"
+          SYSTEM="libc.so libm.so libdl.so liblog.so libandroid.so libz.so libvulkan.so libstdc++.so
+                  libGLESv2.so libEGL.so libnativewindow.so libjnigraphics.so libaaudio.so
+                  libOpenSLES.so libmediandk.so libcamera2ndk.so libsync.so libneuralnetworks.so"
+          fail=0
+          for so in *.so; do
+            for need in $(readelf -d "$so" | sed -n 's/.*NEEDED.*\[\(.*\)\]/\1/p'); do
+              [ -f "$need" ] && continue
+              case " $(echo $SYSTEM) " in *" $need "*) continue ;; esac
+              echo "::error::$so needs $need, which is neither in the apk nor a platform library"
+              fail=1
+            done
+          done
+          exit $fail
 
       - name: Sign with the testkey (v1 + v2 + v3)
         run: |
@@ -654,23 +373,6 @@ jobs:
           grep -qi "CN=Android, OU=Android, O=Android" /tmp/sig.txt \
             || { echo "::error::apk is not signed with the AOSP testkey"; exit 1; }
 
-      - uses: actions/upload-artifact@v4
-        id: apk-upload
-        with:
-          name: droiddeck-apk
-          path: app/build/outputs/apk/release/*.apk
-          if-no-files-found: error
-          retention-days: 30
-          compression-level: 0
-
-      - uses: actions/upload-artifact@v4
-        with:
-          name: droiddeck-packs
-          path: app/build/packs/*.tar.zst
-          if-no-files-found: error
-          retention-days: 30
-          compression-level: 0
-
       - name: Report on the pull request
         if: always() && github.event_name == 'pull_request'
         continue-on-error: true
@@ -679,9 +381,6 @@ jobs:
           PR: ${{ github.event.pull_request.number }}
           RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
           BUILD_OUTCOME: ${{ steps.build.outcome }}
-          UNIT_TEST_OUTCOME: ${{ steps.unit-tests.outcome }}
-          TEST_DIAGNOSTICS_URL: ${{ steps.unit-test-diagnostics.outputs.artifact-url }}
-          APK_OUTCOME: ${{ steps.apk-upload.outcome }}
           SAME_REPO: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
         run: |
           set -uo pipefail
@@ -692,8 +391,8 @@ jobs:
             echo
             [ -f /tmp/pr-merge.md ] && cat /tmp/pr-merge.md
             echo
-            case "$BUILD_OUTCOME:$UNIT_TEST_OUTCOME:$APK_OUTCOME" in
-              success:success:success)
+            case "$BUILD_OUTCOME" in
+              success)
                 echo "###  Build passed"
                 echo
                 echo "The \`droiddeck-apk\` artifact is [on this run]($RUN_URL), signed with the public test key."
@@ -706,28 +405,7 @@ jobs:
                 echo
                 echo "Fallback: [open **PR Release Publish**]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/workflows/pr-release-publish.yml) on \`main\` and enter PR \`$PR\`."
                 ;;
-              success:success:*)
-                echo "###  APK publication incomplete"
-                echo
-                echo "Compilation and unit tests passed, but APK publication did not complete. See [the run]($RUN_URL)."
-                ;;
-              success:failure:*)
-                echo "### ERROR: Unit tests failed"
-                echo
-                echo "The APK compiled, but unit tests failed. No installable artifact was published."
-                echo
-                if [ -n "$TEST_DIAGNOSTICS_URL" ]; then
-                  echo "The [unit-test-results]($TEST_DIAGNOSTICS_URL) artifact contains the test log and any generated reports."
-                else
-                  echo "The test diagnostics upload did not complete. See [the test log]($RUN_URL)."
-                fi
-                ;;
-              success:*)
-                echo "###  Build incomplete"
-                echo
-                echo "The APK compiled, but unit tests did not complete successfully. See [the run]($RUN_URL)."
-                ;;
-              failure:*)
+              failure)
                 echo "### ERROR: Build failed"
                 echo
                 echo "The compiler's errors ([full log]($RUN_URL)):"
@@ -745,7 +423,7 @@ jobs:
                 echo '```'
                 echo "</details>"
                 ;;
-              skipped:*|cancelled:*)
+              skipped|cancelled)
                 echo "###  Not built"
                 echo
                 echo "The build did not run (see above, or [the run]($RUN_URL))."
@@ -761,6 +439,14 @@ jobs:
             gh api -X POST "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" -F body=@/tmp/pr-report.md >/dev/null
           fi
 
+      - uses: actions/upload-artifact@v4
+        with:
+          name: droiddeck-apk
+          path: app/build/outputs/apk/release/*.apk
+          if-no-files-found: error
+          retention-days: 30
+          compression-level: 0
+
   sign:
     needs: build
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
@@ -773,17 +459,14 @@ jobs:
       variants: ${{ needs.build.outputs.variants }}
     secrets: inherit
 
-  packs:
-    needs: build
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
-    permissions:
-      contents: read
-      actions: read
-    uses: ./.github/workflows/publish-packs.yml
-    secrets: inherit
-
+  # Each signed main build as a prerelease of the public Droid-Deck/DroidDeck-CI (main-<sha>, the
+  # last KEEP kept), where anyone can download it without a GitHub account, then a post in the
+  # Discord's builds channel linking to it. The release is made with a token of the org's
+  # "DroidDeck CI Publisher" app (installed on DroidDeck-CI only, Contents: write): its ID in the
+  # DROIDDECK_CI_APP_ID variable, its private key in the DROIDDECK_CI_APP_KEY secret.
+  # DISCORD_BUILDS_WEBHOOK is the channel's webhook URL.
   announce:
-    needs: [build, sign, packs]
+    needs: [build, sign]
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-24.04
     timeout-minutes: 10
@@ -808,6 +491,8 @@ jobs:
           owner: Droid-Deck
           repositories: DroidDeck-CI
 
+      # What this build is, for the top of the release notes: the merged PR's title and the first
+      # paragraph of its description, or the commit's subject for a push made without a PR.
       - name: Describe the change
         env:
           GH_TOKEN: ${{ github.token }}
@@ -857,12 +542,15 @@ jobs:
           gh release delete "$tag" -R "$CI_REPO" --yes --cleanup-tag 2>/dev/null || true
           gh release create "$tag" -R "$CI_REPO" --target main --prerelease \
             --title "main ${GITHUB_SHA::7}" --notes "$notes" signed/*
+          # Keep the newest main builds by publication time. GitHub App releases can share createdAt.
           gh release list -R "$CI_REPO" -L 200 --json tagName,publishedAt \
             --jq '[.[] | select(.tagName | startswith("main-"))] | sort_by(.publishedAt) | reverse | .['"$KEEP"':][] | .tagName' |
             while IFS= read -r old; do
+              # Never remove this run's release, even if the API returns an unexpected ordering.
               if [ "$old" = "$tag" ]; then
                 continue
               fi
+              # Another main publish may have removed the same old release concurrently.
               if ! gh release delete "$old" -R "$CI_REPO" --yes --cleanup-tag 2>/dev/null; then
                 if gh release view "$old" -R "$CI_REPO" >/dev/null 2>&1; then
                   echo "::error::Could not delete old release $old"
@@ -878,7 +566,7 @@ jobs:
           echo "apk=$GITHUB_SERVER_URL/$CI_REPO/releases/download/$tag/$apk" >> "$GITHUB_OUTPUT"
           echo "Published $url"
 
-      - name: Post the Preview build to Discord
+      - name: Post to Discord
         env:
           WEBHOOK: ${{ secrets.DISCORD_BUILDS_WEBHOOK }}
           GH_TOKEN: ${{ github.token }}
@@ -892,6 +580,8 @@ jobs:
           fi
           commit=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA")
           subject=$(jq -r '.commit.message | split("\n")[0]' <<<"$commit")
+          # A merge commit's subject is "Merge pull request #N from ..."; its body's first line is
+          # the PR's title, which says more.
           title=$(jq -r '.commit.message | split("\n") | map(select(length > 0)) | .[1] // ""' <<<"$commit")
           pr=$(sed -n 's/^Merge pull request #\([0-9]*\).*/\1/p' <<<"$subject")
           if [ -n "$pr" ]; then
@@ -900,7 +590,7 @@ jobs:
             what="[\`${GITHUB_SHA::7}\`]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/commit/$GITHUB_SHA): $subject"
           fi
           get=$(printf 'Download: [standard APK](<%s>) · [all variants](<%s>)' "$APK" "$RELEASE")
-          content=$(printf '**New signed Preview build** `main-%s`\n%s\nIn the app: **Updates → Preview**\n%s' "${GITHUB_SHA::7}" "$what" "$get")
+          content=$(printf '**New signed build** `main-%s`\n%s\n%s' "${GITHUB_SHA::7}" "$what" "$get")
           jq -n --arg content "$content" '{content: $content, allowed_mentions: {parse: []}}' |
             curl -fsS -H 'Content-Type: application/json' -d @- "$WEBHOOK" -o /dev/null
           echo "Posted: $content"

.github/workflows/ci-debian-image.yml

@@ -1,51 +0,0 @@
-name: Publish the CI Debian image
-
-
-on:
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Release tag to publish to (a new -rN tag for a refresh; builds pin the one in tools/linuxfs/debian-image.env)'
-        required: true
-        default: 'ci-debian-bullseye-r2'
-      replace:
-        description: 'Overwrite the asset if the release already has one (changes its checksum: re-pin it in debian-image.env)'
-        type: boolean
-        default: false
-
-permissions:
-  contents: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-24.04
-    timeout-minutes: 30
-    steps:
-      - name: Pull, save and publish
-        env:
-          GH_TOKEN: ${{ github.token }}
-          TAG: ${{ inputs.tag }}
-          REPLACE: ${{ inputs.replace }}
-        run: |
-          set -euo pipefail
-          image=public.ecr.aws/docker/library/debian:bullseye
-          if [ "$REPLACE" != true ] && gh release view "$TAG" -R "$GITHUB_REPOSITORY" --json assets -q '.assets[].name' 2>/dev/null | grep -qx debian-bullseye.tar.zst; then
-            echo "::error::$TAG already carries debian-bullseye.tar.zst; publish to a new tag, or set replace and re-pin tools/linuxfs/debian-image.env"
-            exit 1
-          fi
-          for attempt in 1 2 3 4 5 6; do
-            docker pull "$image" && break
-            [ "$attempt" -lt 6 ] || { echo "::error::could not pull $image"; exit 1; }
-            echo "pull attempt $attempt failed (registry busy?); retrying in $((attempt * 30)) s"
-            sleep $((attempt * 30))
-          done
-          docker image inspect "$image" --format 'image id {{.Id}} created {{.Created}}'
-          docker save "$image" | zstd -19 -T0 -o debian-bullseye.tar.zst
-          sha256sum debian-bullseye.tar.zst | tee SHA256SUMS
-          ls -l debian-bullseye.tar.zst
-          if ! gh release view "$TAG" -R "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-            gh release create "$TAG" -R "$GITHUB_REPOSITORY" --title "CI Debian 11 image ($TAG)" --latest=false \
-              --notes "The debian:bullseye image build.yml compiles the x86 preloads in (glibc 2.31), saved with docker save and compressed with zstd. Pulled from public.ecr.aws/docker/library/debian:bullseye on $(date -u +%Y-%m-%d); image id $(docker image inspect "$image" --format '{{.Id}}'). Pinned in tools/linuxfs/debian-image.env."
-          fi
-          gh release upload "$TAG" -R "$GITHUB_REPOSITORY" debian-bullseye.tar.zst SHA256SUMS --clobber
-          { echo "Published \`$TAG\`:"; echo; echo '```'; cat SHA256SUMS; echo '```'; } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/pr-release-cleanup.yml

@@ -1,9 +1,9 @@
 name: PR Release Cleanup
-run-name: remove PR
-
-
-
+run-name: remove PR #${{ github.event.pull_request.number }}'s test build
 
+# A merged or closed PR's test build leaves DroidDeck-CI, so the app's Updates page stops offering it
+# (a merged fix is in the next Preview). pull_request_target for the publisher app's secrets; nothing
+# from the PR is checked out or run.
 on:
   pull_request_target:
     types: [ closed ]
@@ -13,27 +13,13 @@ permissions:
   contents: read
   pull-requests: read
 
-concurrency:
-  group: pr-release-${{ github.event.pull_request.number }}
-  cancel-in-progress: false
-  queue: max
-
 jobs:
   cleanup:
     runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - name: Check the current PR state
-        id: state
-        env:
-          GH_TOKEN: ${{ github.token }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: |
-          set -euo pipefail
-          state=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq .state)
-          echo "closed=$([ "$state" = closed ] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+      # A token of the org's "DroidDeck CI Publisher" app, as build.yml's announce job uses.
       - uses: actions/create-github-app-token@v2
-        if: ${{ steps.state.outputs.closed == 'true' }}
         id: ci-token
         with:
           app-id: ${{ vars.DROIDDECK_CI_APP_ID }}
@@ -41,7 +27,6 @@ jobs:
           owner: Droid-Deck
           repositories: DroidDeck-CI
       - name: Delete the test build
-        if: ${{ steps.state.outputs.closed == 'true' }}
         env:
           GH_TOKEN: ${{ steps.ci-token.outputs.token }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
@@ -57,19 +42,6 @@ jobs:
           done
           [ "$found" = 1 ] || echo "No test build for PR #$PR_NUMBER"
 
-      - uses: actions/checkout@v4
-        if: ${{ steps.state.outputs.closed == 'true' }}
-        with:
-          ref: main
-          persist-credentials: false
-      - name: Retire the Discord PR announcement
-        if: ${{ steps.state.outputs.closed == 'true' }}
-        env:
-          WEBHOOK: ${{ secrets.DISCORD_PR_BUILDS_WEBHOOK }}
-          GH_TOKEN: ${{ github.token }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-        run: python3 tools/release/pr_discord.py retire
-
   catalog:
     needs: cleanup
     if: ${{ always() }}

.github/workflows/pr-release-publish.yml

@@ -11,6 +11,8 @@ on:
   pull_request_target:
     types: [labeled]
     branches: [main]
+  # A PR from a branch of this repo is signed on its own after each green build: only people who
+  # can push here can change it. A fork's PR waits for a maintainer's publish-test label.
   workflow_run:
     workflows: [Build APK]
     types: [completed]
@@ -24,7 +26,6 @@ permissions:
 concurrency:
   group: pr-release-${{ github.event_name == 'pull_request_target' && github.event.pull_request.number || github.event_name == 'workflow_run' && github.event.workflow_run.pull_requests[0].number || inputs.pr_number }}
   cancel-in-progress: false
-  queue: max
 
 jobs:
   authorize:
@@ -51,6 +52,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           persist-credentials: false
+      # Every variant a main build ships, so a PR build can be tried under any of them.
       - name: The packages a signed build ships as
         id: variants
         run: echo "list=$(awk '!/^#/ && NF { print $1 }' tools/release/variants.txt | jq -R . | jq -sc .)" >> "$GITHUB_OUTPUT"
@@ -65,6 +67,8 @@ jobs:
         run: |
           set -euo pipefail
           [[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "::error::Invalid PR number '$PR_NUMBER'"; exit 1; }
+          # The automatic path stands down quietly, never failing: a draft, a PR labelled
+          # no-test-build, or a build that a later push has already overtaken.
           skip() { echo "::notice::Not publishing PR #$PR_NUMBER: $1"; echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0; }
           if [ "$EVENT_NAME" = workflow_run ]; then
             echo "automatic=true" >> "$GITHUB_OUTPUT"
@@ -89,6 +93,9 @@ jobs:
           head=$(jq -r '.head.sha' <<<"$pr")
           base=$(jq -r '.base.sha' <<<"$pr")
 
+          # The label is often added while the PR's build is still running, or just after a push
+          # before it has started: wait for the latest build of the head commit to finish (a PR
+          # build takes about 4 minutes) rather than fail and need the label added again.
           run_id=
           for attempt in $(seq 1 60); do
             latest=$(gh run list -R "$GITHUB_REPOSITORY" --workflow build.yml \
@@ -108,6 +115,8 @@ jobs:
             sleep 30
           done
           [[ -n "$run_id" ]] || { echo '::error::The PR build did not finish within 30 minutes'; exit 1; }
+          # GitHub leaves a run's pull_requests empty when its head is in a fork, so the build is
+          # tied to this PR by its head repository, branch and commit instead.
           run=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run_id")
           jq -e --arg head "$head" --arg repo "$(jq -r .head.repo.full_name <<<"$pr")" --arg ref "$(jq -r .head.ref <<<"$pr")" '
             .event == "pull_request" and .head_sha == $head and .conclusion == "success" and
@@ -117,6 +126,8 @@ jobs:
 
           sdk=${ANDROID_HOME:-${ANDROID_SDK_ROOT:-}}
           tools=$(find "$sdk/build-tools" -mindepth 1 -maxdepth 1 -type d | sort -V | tail -1)
+          # A PR build is made from the PR merged onto main, so it must install over main's own
+          # build. main is what this job checked out; no release has to exist or be marked latest.
           main_code=$(sed -n 's/^[[:space:]]*versionCode[[:space:]][[:space:]]*\([0-9][0-9]*\)[[:space:]]*$/\1/p' app/build.gradle)
           [[ "$main_code" =~ ^[0-9]+$ ]] || { echo "::error::No numeric versionCode in main's app/build.gradle"; exit 1; }
           mkdir -p "$RUNNER_TEMP/pr"
@@ -167,36 +178,13 @@ jobs:
       issues: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: main
-          persist-credentials: false
       - uses: actions/download-artifact@v4
         with:
           pattern: droiddeck-pr-signed-*
           merge-multiple: true
           path: signed
-      - name: The add-on packs main has not published
-        env:
-          GH_TOKEN: ${{ github.token }}
-          RUN: ${{ needs.authorize.outputs.run_id }}
-        run: |
-          set -euo pipefail
-          gh run download "$RUN" -R "$GITHUB_REPOSITORY" -n droiddeck-packs -D packs
-          mkdir -p pr-packs
-          for file in packs/*.tar.zst; do
-            name=$(basename "$file" .tar.zst)
-            sha=$(sha256sum "$file" | cut -d' ' -f1)
-            tag="pack-$name-${sha:0:16}"
-            digest=$({ gh api "repos/Droid-Deck/DroidDeck-Components/releases/tags/$tag" 2>/dev/null || echo '{}'; } |
-              jq -r --arg n "$name.tar.zst" '.assets // [] | .[] | select(.name == $n) | .digest // empty')
-            if [ "$digest" = "sha256:$sha" ]; then
-              echo "$name: served from DroidDeck-Components $tag"
-            else
-              cp "$file" "pr-packs/$tag.tar.zst"
-              echo "$name: attached to the PR release as $tag.tar.zst"
-            fi
-          done
+      # What this build is, for the top of the release notes: the PR's title and the first
+      # paragraph of its description.
       - name: Describe the change
         env:
           GH_TOKEN: ${{ github.token }}
@@ -215,6 +203,7 @@ jobs:
             fi
           } > notes-head.md
           cat notes-head.md
+      # A token of the org's "DroidDeck CI Publisher" app, as build.yml's announce job uses.
       - uses: actions/create-github-app-token@v2
         id: ci-token
         with:
@@ -254,9 +243,9 @@ jobs:
             first=true
           fi
           echo "first=$first" >> "$GITHUB_OUTPUT"
-          cp pr-packs/* signed/ 2>/dev/null || true
           gh release upload "$tag" signed/* -R "$repo" --clobber
           gh release edit "$tag" -R "$repo" --title "PR #$PR_NUMBER" --notes "$notes" --prerelease
+          # Drop the previous build's files: anything this build did not just upload.
           keep=$(cd signed && ls | jq -R . | jq -sc .)
           gh api "repos/$repo/releases/tags/$tag" |
             jq -r --argjson keep "$keep" '.assets[] | select(.name as $n | $keep | index($n) | not) | .id' |
@@ -318,27 +307,39 @@ jobs:
           $NEXT
           EOF
           )
-          comment=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --paginate --slurp | \
-            jq "[.[][] | select(.user.login == \"github-actions[bot]\") | select(.body | startswith(\"$mark\"))] | first // {}")
-          id=$(jq -r '.id // empty' <<<"$comment")
+          id=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --paginate \
+            --jq ".[] | select(.body | startswith(\"$mark\")) | .id" | head -1 || true)
           if [ -n "$id" ]; then
-            state=$(jq -r '.body | split("\n")[] | select(startswith("<!-- droiddeck-discord: ") and endswith(" -->"))' <<<"$comment")
-            if [ -n "$state" ]; then body=$(printf '%s\n%s' "$body" "$state"); fi
             gh api -X PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$id" -f body="$body" >/dev/null
           else
             gh api -X POST "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" -f body="$body" >/dev/null
           fi
 
-      - name: Update the Discord PR announcement
-        if: ${{ always() && steps.publish.outcome == 'success' }}
+      # Asked for (the label, a manual run): always announced. Signed on its own after a push:
+      # only a PR's first test build is, and later ones update its release quietly.
+      - name: Post to Discord
+        if: ${{ always() && steps.publish.outcome == 'success' && (needs.authorize.outputs.automatic != 'true' || steps.publish.outputs.first == 'true') }}
         env:
-          WEBHOOK: ${{ secrets.DISCORD_PR_BUILDS_WEBHOOK }}
+          WEBHOOK: ${{ secrets.DISCORD_BUILDS_WEBHOOK }}
           GH_TOKEN: ${{ github.token }}
           PR_NUMBER: ${{ needs.authorize.outputs.pr_number }}
           HEAD_SHA: ${{ needs.authorize.outputs.head_sha }}
           RELEASE: ${{ steps.publish.outputs.release }}
           APK: ${{ steps.publish.outputs.apk }}
-        run: python3 tools/release/pr_discord.py publish
+        run: |
+          set -euo pipefail
+          if [ -z "$WEBHOOK" ]; then
+            echo "::notice::No DISCORD_BUILDS_WEBHOOK secret; nothing posted"
+            exit 0
+          fi
+          short=${HEAD_SHA:0:7}
+          title=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq .title)
+          what="[#$PR_NUMBER]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/pull/$PR_NUMBER): $title"
+          get=$(printf 'Download: [standard APK](<%s>) · [all variants](<%s>)' "$APK" "$RELEASE")
+          content=$(printf '**New signed PR test build** \`pr-%s\` · \`%s\`\n%s\n_Not merged — for testing._\n%s' "$PR_NUMBER" "$short" "$what" "$get")
+          jq -n --arg content "$content" '{content: $content, allowed_mentions: {parse: []}}' |
+            curl -fsS -H 'Content-Type: application/json' -d @- "$WEBHOOK" -o /dev/null
+          echo "Posted: $content"
 
   catalog:
     needs: publish

.github/workflows/publish-packs.yml

@@ -1,83 +0,0 @@
-name: Publish add-on packs
-
-# The add-on packs (tools/packs/build.sh) a Build APK run made, published to DroidDeck-Components under
-# content-addressed tags (pack-<name>-<first 16 hex of sha256>). The APK from that run pins each pack's
-# SHA-256 and downloads it from that tag. A tag is created once and never replaced.
-# Only main and release builds publish here; a PR test build attaches the packs main has not published
-# to its pr-N release on DroidDeck-CI (pr-release-publish.yml), which is deleted when the PR closes.
-
-on:
-  workflow_call:
-    inputs:
-      run_id:
-        description: The Build APK run whose packs to publish; empty for the calling run's own
-        type: string
-        default: ''
-
-permissions:
-  contents: read
-  actions: read
-
-jobs:
-  publish:
-    name: publish add-on packs
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-    concurrency:
-      group: publish-packs
-      cancel-in-progress: false
-    steps:
-      - name: The packs (this run's build)
-        if: inputs.run_id == ''
-        uses: actions/download-artifact@v4
-        with:
-          name: droiddeck-packs
-          path: packs
-
-      - name: The packs (another Build APK run)
-        if: inputs.run_id != ''
-        env:
-          GH_TOKEN: ${{ github.token }}
-          RUN: ${{ inputs.run_id }}
-        run: gh run download "$RUN" -R "$GITHUB_REPOSITORY" -n droiddeck-packs -D packs
-
-      - uses: actions/create-github-app-token@v2
-        id: components-token
-        with:
-          app-id: ${{ vars.DROIDDECK_CI_APP_ID }}
-          private-key: ${{ secrets.DROIDDECK_CI_APP_KEY }}
-          owner: Droid-Deck
-          repositories: DroidDeck-Components
-
-      - name: Publish
-        env:
-          GH_TOKEN: ${{ steps.components-token.outputs.token }}
-          REPO: Droid-Deck/DroidDeck-Components
-          BUILD_RUN: ${{ inputs.run_id || github.run_id }}
-        run: |
-          set -euo pipefail
-          published_digest() {
-            { gh api "repos/$REPO/releases/tags/$1" 2>/dev/null || echo '{}'; } |
-              jq -r --arg n "$2" '.assets // [] | .[] | select(.name == $n) | .digest // empty'
-          }
-          commit=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$BUILD_RUN" --jq .head_sha 2>/dev/null || echo "$GITHUB_SHA")
-          for name in proot directaudio tracking xbox comet; do
-            file="packs/$name.tar.zst"
-            [ -f "$file" ] || { echo "::error::$name.tar.zst is missing from Build APK run $BUILD_RUN"; exit 1; }
-            sha=$(sha256sum "$file" | cut -d' ' -f1)
-            tag="pack-$name-${sha:0:16}"
-            digest=$(published_digest "$tag" "$name.tar.zst")
-            if [ -z "$digest" ]; then
-              notes="DroidDeck add-on pack \`$name\`, built by [Build APK run $BUILD_RUN]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$BUILD_RUN) from \`$commit\` with tools/packs/build.sh and published by [run $GITHUB_RUN_ID]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID).
-
-          Size: $(stat -c %s "$file") bytes. SHA-256: $sha. APKs built in the same run pin this digest."
-              gh release create "$tag" -R "$REPO" --title "$tag" --notes "$notes" --latest=false "$file" \
-                || echo "::warning::creating $tag failed; checking whether another run published it"
-              digest=$(published_digest "$tag" "$name.tar.zst")
-            fi
-            if [ "$digest" != "sha256:$sha" ]; then
-              echo "::error::$tag holds ${digest:-nothing} for $name.tar.zst, not sha256:$sha"
-              exit 1
-            fi
-            echo "- \`$name\`: [$tag]($GITHUB_SERVER_URL/$REPO/releases/tag/$tag) \`$sha\`" >> "$GITHUB_STEP_SUMMARY"
-          done

.github/workflows/release.yml

@@ -63,19 +63,10 @@ jobs:
       artifact: droiddeck-release
     secrets: inherit
 
-  packs:
-    needs: find
-    permissions:
-      contents: read
-      actions: read
-    uses: ./.github/workflows/publish-packs.yml
-    with:
-      run_id: ${{ needs.find.outputs.run_id }}
-    secrets: inherit
-
+  # The release is made here, from the apks this run signed, so it traces back to its Build APK run.
   publish:
     name: publish the release
-    needs: [find, sign, packs]
+    needs: [find, sign]
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     permissions:
@@ -103,6 +94,7 @@ jobs:
           if gh release view "$VERSION" -R "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
             echo "::error::release $VERSION already exists"; exit 1
           fi
+          # The notes' first line is the title; media paths become raw URLs at this release's tag.
           title=$(sed -n '1s/^# *//p' "$notes")
           [ -n "$title" ] || title="DroidDeck $VERSION"
           raw="https://raw.githubusercontent.com/$GITHUB_REPOSITORY/$VERSION/docs/releases/media/"
@@ -118,6 +110,7 @@ jobs:
             --target "$GITHUB_SHA" --title "$title" --notes-file "$RUNNER_TEMP/body.md" --latest
           echo "Published [$title]($GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/tag/$VERSION)" >> "$GITHUB_STEP_SUMMARY"
 
+  # A release made with this run's token fires no release event, so the in-app catalog is refreshed here.
   catalog:
     needs: publish
     uses: ./.github/workflows/update-catalog.yml

.github/workflows/update-catalog.yml

@@ -13,13 +13,13 @@ permissions:
 concurrency:
   group: update-app-catalog
   cancel-in-progress: false
-  queue: max
 
 jobs:
   catalog:
     runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
+      # Always use the current trusted generator, even when a release event points at an older tag.
       - uses: actions/checkout@v4
         with:
           ref: main

.gitignore

@@ -8,17 +8,18 @@ captures/
 .externalNativeBuild/
 .cxx/
 .kotlin/
+# Built in CI from tools/linuxfs and app/src/main/cpp/fakeinput.cpp, never committed, so the two
+# copies cannot drift.
 app/src/main/assets/linuxfs/
 app/src/main/jniLibs/arm64-v8a/libproot.so
 app/src/main/jniLibs/arm64-v8a/.proot-inputs
-app/src/main/jniLibs/arm64-v8a/.proot-outputs
 app/src/main/jniLibs/arm64-v8a/libproot-loader.so
-app/src/main/jniLibs/arm64-v8a/libdirectaudiorelay.so
-app/src/main/rust/stores/target/
-app/src/main/assets/droiddeck-esync/
 
+# Kotlin compiler session files (build-tool state, never source).
 .kotlin/
 
+# Signing keys never enter the repo (DroidDeck's lives in GitHub environment secrets; see
+# tools/release/make-release-key.sh). keystore/testkey.p12 is the public AOSP testkey.
 *.jks
 *.keystore
 *.p12
@@ -30,6 +31,5 @@ droiddeck-release-key/
 password.txt
 __pycache__/
 
+# Local signing with the release key (tools/build_local.sh); holds a password.
 .signing.env
-app/src/main/assets/directaudio/
-/tools/vr/out/

AGENTS.md

@@ -1,3 +0,0 @@
-# Rules
-
-- Comments should be rare, factual, and explain only non-obvious external constraints or business invariants.

README.md

@@ -11,48 +11,24 @@ DroidDeck brings the SteamOS experience to Android: Valve's Steam client in Big
 
 <p align="center"><img src="docs/releases/media/0.2.0/launch-into-steam.gif" width="80%" alt="Tapping DroidDeck on the Android home screen and landing in Steam Big Picture"></p>
 
-> Note: DroidDeck does not have a stand-alone website. Do not click on any download links from websites claiming to be the DroidDeck team. 
-
 ## Requirements and install
 
-Use Android 9 or newer on a supported Adreno device (730 or newer, or 8xx). Adreno 6xx is experimental: DirectX 11 uses DXVK 2 and may run, and DirectX 12 games can still crash. Mali, Xclipse, PowerVR, and Adreno 710 are unsupported. No root is required. Allow about 3 GB for the runtime and 1.1 GB more for the desktop and emulators. Install the APK from [Releases](https://github.com/Droid-Deck/DroidDeck/releases), install the Linux runtime, then press **Play** and sign in. Steam downloads on first launch. Install **Desktop & apps** to use the desktop and emulators. The **Store** installs Linux apps and games from Flathub (ARM64 builds) with Flatpak; with additional options to install Appimages and set up scripts. **Stores** (Setup › Stores › "Show Stores in the rail") signs in to GOG, Epic Games and Amazon Games and downloads games into the Games storage. Epic keeps its direct API install path. Opening Epic Stores prepares Epic’s official Linux launcher preview. When installed, Epic games launched from DroidDeck use that client, and games installed in the client are imported into DroidDeck’s library and shortcuts. The x86-64 client runs through FEX on ARM and DroidDeck retains its Proton hooks; this preview and ARM setup are outside Epic’s listed Linux support. The cog on a store’s chip row sets its opening tab and download speed tier.
+Use Android 9 or newer on a supported Adreno device (730 or newer, or 8xx). Mali, Xclipse, PowerVR, and Adreno 710 are unsupported. No root is required. Allow about 3 GB for the runtime and 1.1 GB more for the desktop and emulators. Install the APK from [Releases](https://github.com/Droid-Deck/DroidDeck/releases), install the Linux runtime, then press **Play** and sign in. Steam downloads on first launch. Install **Desktop & apps** to use the desktop and emulators. The **Store** installs Linux apps and games from Flathub (ARM64 builds) with Flatpak; see [docs/development/flatpak.md](docs/development/flatpak.md).
 
-On Android 14 and newer, before Steam launches, you must turn on **Disable child process restrictions** in Developer options. If this option is not available in developer settings (Android 12 and 13 devices), first launch of Steam will present a "Fix it for me" button, which will help automate the setup process.
-
-## Smart glasses
-
-Use **Setup → Smart glasses** for app-wide virtual-screen settings across DroidDeck menus, launchers, desktop sessions, and games. Supported VITURE, RayNeo, XREAL, and Rokid connections provide 3DoF; Luma Ultra adds optional experimental 6DoF and stereo-assisted hand/Joy-Con tracking. Model support and SDK requirements differ: see the [smart-glasses support matrix](docs/smart-glasses-support.md) for supported devices, controls, setup, and limitations.
+On Android 12+, if Steam exits without a log, turn off **Restrict child processes** in Developer options.
 
 ## Community
 
-Join the [DroidDeck Discord](https://discord.gg/JRGAvawjsm) for help, Preview builds, and device reports. Bug reports go in its **#bug-reports** forum; attach the zip from **Share logs** (Setup, or the session drawer) so the logs come with it.
+Join the [DroidDeck Discord](https://discord.gg/JRGAvawjsm) for help, Preview builds, and device reports. Bug reports go in its **#bug-reports** forum; attach the session folder from `Download/DroidDeck/` so the logs come with it.
 
 ## Build
 
-Run `tools/build_local.sh` with Docker, Java 17, the Android SDK/NDK, Rust through rustup, GitHub CLI, Python 3, and `zstd` installed. It prepares the same native libraries, pinned components and audio sinks as CI, then checks the APK's assets, JNI exports and dependencies. The APK is at `app/build/outputs/apk/release/app-release.apk`. Set `DROIDDECK_PA13_SOURCE_DIR` to an existing PulseAudio 13.0 source directory to skip downloading it. Set `DROIDDECK_SIGNING_ENV` to a signing environment file to install over a release build; relative keystore paths resolve beside that file. To install on an attached device, run `tools/deploy_local.sh`.
-
-After preparation, ordinary `./gradlew :app:assembleRelease` builds can reuse the verified inputs. If native sources, component pins or staged files change, packaging stops with instructions to rerun the helper. Generated audio stays under `app/build/`; the tracked base bundle is never modified. `./gradlew -PskipRust=true :app:testDebugUnitTest` needs no native preparation. For an APK without store engines, use `DROIDDECK_SKIP_RUST=1 tools/build_local.sh`; it omits cached engine libraries too.
-
-For the prepared Windows checkout, run `./tools/run_windows.ps1` (optionally with `-Serial <adb-serial>`), or select **DroidDeck XR** in Android Studio and run the **app** module on the connected phone. Machine-specific options live in the ignored `local.properties`: `droiddeck.python` selects a Python executable, `droiddeck.skipRust=true` omits the optional store download engines, and `droiddeck.debugApplicationIdSuffix=.xr` installs **DroidDeck XR Dev** alongside the signed release. The development app has its own runtime and Steam login. The local Java selection is in `.gradle/config.properties`.
-
-`python tools/prepare_windows_runtime.py` restores this checkout's audited runtime inputs from the pinned CI APK, three locally rebuilt preload libraries, and the checksum-pinned Gamescope archive in `build/windows-setup/`. Start Docker Desktop's Linux engine first: preparation now rebuilds DroidDeck's ARM64 VR driver and Vulkan layer from current source and runs their native regression tests. The compiler image is built automatically on first use. Vulkan headers come from the NDK beside `--llvm-strip`, or from an explicit `--vk-include <NDK-sysroot-include>` directory.
-
-To reuse that build, pass `--rebuilt-vr build/windows-setup/vr`. Preparation verifies its `vr-build.json` against the current Git revision, source files, Vulkan headers, output checksums, and ARM64 architecture; missing or stale builds fail instead of falling back to the donor's VR libraries. The script checks the actual donor CI merge tree, still rejects unrelated unaudited runtime changes, and records component provenance in `app/build/windows-runtime-provenance.json`. Preserve these ignored preparation files when rebuilding locally; `clean` removes the prepared assets and their verification manifest.
-
-Run the helper and preload regression suite with `bash tools/test_local.sh`. On macOS it runs in Linux through Docker, matching the helpers' runtime and CI instead of compiling Linux preloads against macOS headers.
+Run `tools/build_local.sh` with Docker, Java 17, the Android SDK/NDK, and `zstd` installed. It builds the ARM64 audio sinks from PulseAudio 13.0 and packages them into the APK at `app/build/outputs/apk/release/app-release.apk`. Set `DROIDDECK_PA13_SOURCE_DIR` to an existing PulseAudio 13.0 source directory to skip downloading it. To install the APK on an attached device, run `tools/deploy_local.sh`.
 
 ## Limits
 
-Compatibility and performance vary by device; hardware validation is limited. Desktop compositing uses software rendering. Firefox sandboxing is reduced under proot. Logs are kept app-private (`files/logs/`, the last 30 sessions); **Share logs** packs the newest session, with the stores and tool logs, into one scrubbed zip.
+Compatibility and performance vary by device; hardware validation is limited. Desktop compositing uses software rendering. Firefox sandboxing is reduced under proot. See the session logs in `Download/DroidDeck/` when diagnosing problems.
 
 ## Credits and licence
 
-GPL-3.0. Runtime, shim, input, and controller work build on WinNative and Bannerlator (maxjivi05). Epic Games and GOG support build on [Phobos’s](https://github.com/phobos665) adaptation of [Legendary](https://github.com/legendary-gl/legendary) and [gogdl](https://github.com/Heroic-Games-Launcher/heroic-gogdl), respectively. The registry entries a GOG game's install script (`goggame-<id>.script`) sets are read the way [Heroic Games Launcher](https://github.com/Heroic-Games-Launcher/HeroicGamesLauncher)'s GOG setup (GPL-3.0) reads them. LSFG frame generation is from the work of Camille LaVey and the [Eden](https://eden-emu.dev) emulator project, following [lsfg-vk](https://github.com/PancakeTAS/lsfg-vk), ported to WinNative and DroidDeck by [@maxjivi05](https://github.com/maxjivi05); it needs your own copy of [Lossless Scaling](https://store.steampowered.com/app/993090/) and ships none of its shaders. x86 AppImages, and any whose own runtime cannot unpack them, are unpacked with [uruntime](https://github.com/VHSgunzo/uruntime) by VHSgunzo (MIT), shipped unmodified with its licence, which also starts the arm64 emulator AppImages whose own runtime cannot run its extractor on Android. The Steam client's audio goes through [@The412Banner](https://github.com/The412Banner)'s [DirectAudio](https://github.com/The412Banner/directaudio) PulseAudio sink (LGPL-2.1-or-later), built from `tools/directaudio/sink` with its request size kept to its ring so clients are not asked to queue 100 ms ahead. mmap ring-buffer controller input was developed by ribbit384 ([WinNative #345](https://github.com/WinNative-Emu/WinNative/pull/345)). Why the x86-64 Steam client refused the arm64 client's sign-in was checked by reading Steam's saved token with the `ConnectCache` format from [deadlock-api-ingest](https://github.com/deadlock-api/deadlock-api-ingest). x86 programs that link OpenSSL 3 under FEX use the copy in the [Steam Linux Runtime 4.0](https://gitlab.steamos.cloud/steamrt/steamrt) platform. Hooks written with `WriteProcessMemory` into code [FEX](https://github.com/FEX-Emu/FEX) has translated go through `/proc/<pid>/mem` again when the kernel refuses `process_vm_writev`, as [Wine](https://gitlab.winehq.org/wine/wine)'s `server/ptrace.c` wrote them before Wine 11. x86 Linux games under FEX get the same `/etc/asound.conf` that [pressure-vessel](https://gitlab.steamos.cloud/steamrt/steam-runtime-tools) writes into the Steam Linux Runtime, so ALSA plays through PulseAudio. Games render with [Mesa](https://gitlab.freedesktop.org/mesa/mesa) Turnip's own per-render-pass choice between tile memory and system memory, while the Steam client keeps `TU_DEBUG=sysmem`; [FEX](https://github.com/FEX-Emu/FEX)'s code disk cache was checked in its source and is already on through Proton. The proot fast path picks the guest name of a host file bound under several names in the order [PRoot](https://github.com/proot-me/proot)'s `path/binding.c` (GPL-2.0-or-later) sorts its bindings, so links and `/proc/self/fd` read back as they do through proot. See [LICENSE](LICENSE). Steam and Proton belong to Valve Corporation; this project is not affiliated with Valve.
-
-XR glasses support builds on WinNative's VITURE glasses work. VITURE protocol details were checked against [XRLinuxDriver](https://github.com/wheaney/XRLinuxDriver) by [@wheaney](https://github.com/wheaney), including the VITURE protocol header it ships, [ar-drivers-rs](https://github.com/badicsalex/ar-drivers-rs) by [@badicsalex](https://github.com/badicsalex) and the [go-macos/iokit VITURE package](https://pkg.go.dev/github.com/go-macos/iokit/viture); the optional VITURE SDK belongs to VITURE and is not included. RayNeo support adapts [@informalTechCode](https://github.com/informalTechCode)'s [RayNeo-Air-Series-3DoF-Scaffold](https://github.com/informalTechCode/RayNeo-Air-Series-3DoF-Scaffold) (Apache-2.0) and references [@verncat](https://github.com/verncat)'s [RayNeo-Air-3S-Pro-OpenVR](https://github.com/verncat/RayNeo-Air-3S-Pro-OpenVR) (MIT) and [Monado](https://gitlab.freedesktop.org/monado/monado) (BSL-1.0); see [docs/third-party/rayneo](docs/third-party/rayneo/README.md). XREAL 1S support references [XRLinuxDriver](https://github.com/wheaney/XRLinuxDriver) and [xrealOneDeviceKit](https://github.com/wheaney/xrealOneDeviceKit) by @wheaney, [xreal_one_driver](https://github.com/rohitsangwan01/xreal_one_driver) by [@rohitsangwan01](https://github.com/rohitsangwan01) (MIT) and [xr-tools](https://github.com/0xcaff/xr-tools) by [@0xcaff](https://github.com/0xcaff). Rokid support follows the Rokid protocol notes in [ar-drivers-rs](https://github.com/badicsalex/ar-drivers-rs) and @badicsalex's [Void Computing write-ups](https://voidcomputing.hu/blog/worse-better-prettier/), and [Monado](https://gitlab.freedesktop.org/monado/monado)'s Rokid driver. The REDMAGIC glasses-display findings draw on [@mekhontsev](https://github.com/mekhontsev)'s [MagicDesk investigation](https://github.com/mekhontsev/magicdesk/blob/main/docs/xr-resolution-fix.md) and [@Coding-BR](https://github.com/Coding-BR)'s [decompiled Nubia kernel](https://github.com/Coding-BR/android_kernel_nubia_sm8850_qwjujube). VITURE, RayNeo, XREAL, Rokid and REDMAGIC are trademarks of their owners; this project is not affiliated with them.
-
-Joy-Con VR controllers port the arm model of Google's [Google VR SDK for Unity](https://github.com/googlevr/gvr-unity-sdk) (Apache-2.0), adapt the hand skeleton of Valve's [OpenVR](https://github.com/ValveSoftware/openvr) `handskeletonsimulation` sample (BSD-3-Clause), which follows Moshi Turner's hand simulation in [Monado](https://gitlab.freedesktop.org/monado/monado), and use the Index controller offsets from Monado's `vive_poses.c` (BSL-1.0). Joy-Con behaviour was researched in Linux's [hid-nintendo](https://github.com/torvalds/linux/blob/master/drivers/hid/hid-nintendo.c) driver by Daniel J. Ogorchock, [@dekuNukem](https://github.com/dekuNukem)'s [Nintendo_Switch_Reverse_Engineering](https://github.com/dekuNukem/Nintendo_Switch_Reverse_Engineering), [SDL](https://github.com/libsdl-org/SDL) and the Android Open Source Project, and checked against [ALVR](https://github.com/alvr-org/ALVR), [OpenComposite](https://gitlab.com/znixian/OpenOVR), [PSMoveSteamVRBridge](https://github.com/HipsterSloth/PSMoveSteamVRBridge), [@F8LEFT](https://github.com/F8LEFT)'s [JoyConVr](https://github.com/F8LEFT/JoyConVr), [@krnelpan1c](https://github.com/krnelpan1c)'s [Daydream-Controller-SteamVR](https://github.com/krnelpan1c/Daydream-Controller-SteamVR), [@yoyobuae](https://github.com/yoyobuae)'s [joyconvr](https://github.com/yoyobuae/joyconvr), [Moonlight](https://github.com/moonlight-stream/moonlight-android) and [Dolphin](https://github.com/dolphin-emu/dolphin); see [docs/third-party/joycon](docs/third-party/joycon/README.md). Nintendo Switch and Joy-Con are trademarks of Nintendo; this project is not affiliated with Nintendo.
-
-Camera hand tracking runs Google's [MediaPipe](https://github.com/google-ai-edge/mediapipe) Tasks Vision library with its Pose Landmarker (Lite) model, BlazePose GHUM 3D, and its Hand Landmarker model (all Apache-2.0), on frames from AndroidX [CameraX](https://developer.android.com/jetpack/androidx/releases/camera) (Apache-2.0); MediaPipe's usage reports are switched off. The design was checked against [@F8LEFT](https://github.com/F8LEFT)'s [JoyConVr](https://github.com/F8LEFT/JoyConVr) camera app (MIT), and the short Joy-Con movements follow the accelerometer mode of the [Google VR SDK for Unity](https://github.com/googlevr/gvr-unity-sdk)'s arm model, Eric Foxlin's zero-velocity updates and Frosio, Pedersini and Borghese's accelerometer autocalibration, and the camera and Joy-Con are joined by a Kalman filter (R. E. Kalman, 1960). Bare camera hands take their gestures after [ALVR](https://github.com/alvr-org/ALVR)'s `hand_gestures.rs` (MIT) and Meta Quest's menu pinch, with distances checked on photos from the [HaGRID](https://github.com/hukenovs/hagrid) gesture set (CC BY-SA 4.0, not included), fit the palm with Horn's quaternion method (1987) and smooth it with the 1€ filter (Casiez, Roussel and Vogel, 2012); the white glove model follows Valve's OpenVR render model reference and Index controller poses, is meshed with surface nets (Gibson, 1998; Mikola Lysenko) and blends and shades it with Inigo Quilez's smooth minimum and distance-field ambient occlusion, porting his polygon distance (MIT); see [docs/third-party/handtracking](docs/third-party/handtracking/README.md).
-
-The Store installs and runs apps with [Flatpak](https://github.com/flatpak/flatpak) (LGPL-2.1). Its sandbox goes through DroidDeck's own bubblewrap shim, which follows how Flatpak hands bwrap its environment. Chromium and Electron apps from Flathub start their browser processes through [zypak](https://github.com/refi64/zypak) by [@refi64](https://github.com/refi64) (BSD-3-Clause); its source was read to see that it always spawns them through Flatpak's spawn portal, which is why DroidDeck starts them directly without Chromium's sandbox instead.
+GPL-3.0. Runtime, shim, input, and controller work build on WinNative and Bannerlator (maxjivi05). LSFG frame generation is from the work of Camille LaVey and the [Eden](https://eden-emu.dev) emulator project, following [lsfg-vk](https://github.com/PancakeTAS/lsfg-vk), ported to WinNative and DroidDeck by [@maxjivi05](https://github.com/maxjivi05); it needs your own copy of [Lossless Scaling](https://store.steampowered.com/app/993090/) and ships none of its shaders. See [LICENSE](LICENSE). Steam and Proton belong to Valve Corporation; this project is not affiliated with Valve.

app/build.gradle

@@ -4,32 +4,6 @@ plugins {
 apply plugin: 'kotlin-android'
 apply plugin: 'org.jetbrains.kotlin.plugin.compose'
 
-// Machine-specific tooling and optional CI-prepared inputs stay out of version control.
-def localBuildOptions = new Properties()
-def localBuildOptionsFile = rootProject.layout.projectDirectory.file('local.properties')
-if (localBuildOptionsFile.asFile.exists()) {
-    localBuildOptions.load(new StringReader(providers.fileContents(localBuildOptionsFile).asText.get()))
-}
-def pythonExecutable = project.findProperty('pythonExecutable')
-    ?: localBuildOptions.getProperty('droiddeck.python', 'python3')
-def vitureSdkDir = project.hasProperty('vitureSdkDir') ? project.property('vitureSdkDir') : localBuildOptions.getProperty('droiddeck.vitureSdk', '')
-def uvcDir = project.hasProperty('uvcDir') ? project.property('uvcDir') : localBuildOptions.getProperty('droiddeck.uvcDir', '')
-if (uvcDir) {
-    ['arm64-v8a/libusb.so', 'arm64-v8a/libuvc.a', 'include/libusb.h', 'include/libuvc/libuvc.h',
-     'licenses/libusb-COPYING', 'licenses/libuvc-LICENSE.txt'].each { required ->
-        if (!new File(uvcDir, required).isFile()) throw new GradleException("Incomplete UVC build: missing ${required}")
-    }
-}
-if (vitureSdkDir) {
-    ['android/arm64-v8a/libglasses.so', 'android/arm64-v8a/libcarina_vio.so',
-     'android/arm64-v8a/libcloud_protocol.so', 'include/viture_glasses_provider.h',
-     'android/LICENSE', 'android/NOTICE'].each { required ->
-        if (!new File(vitureSdkDir, required).isFile()) {
-            throw new GradleException("Incomplete VITURE Android SDK: missing ${required}")
-        }
-    }
-}
-
 def gitValue = { List<String> arguments ->
     try {
         def output = providers.exec {
@@ -75,39 +49,17 @@ if (!(treeState in ['clean', 'dirty'])) {
 buildLabel = "${buildOrigin} ${treeState} · ${buildLabel}"
 def escapedBuildLabel = buildLabel.replace('\\', '\\\\').replace('"', '\\"')
 
+// What the in-app updater compares against the published builds: the commit this build is of (a PR
+// build's head, not the merge CI makes of it), its PR, and whether CI made it at all.
 def sourceCommit = providers.environmentVariable('DROIDDECK_SOURCE_COMMIT').getOrNull()
     ?: providers.environmentVariable('GITHUB_SHA').getOrNull() ?: gitValue(['rev-parse', 'HEAD']) ?: ''
 def prNumber = (providers.environmentVariable('DROIDDECK_PR_NUMBER').getOrNull() ?: '0').with { it.isInteger() ? it : '0' }
 def ciBuild = providers.environmentVariable('GITHUB_ACTIONS').getOrNull() == 'true'
+// The release key's certificate: a build signed with it, from CI or a computer, updates in place.
 def releaseSigner = rootProject.file('keystore/release-signer.sha256').text.trim()
+// When the source was committed, for "built 3 hours ago": fixed per commit, so it costs no rebuilds.
 def commitTime = (gitValue(['show', '-s', '--format=%ct', 'HEAD']) ?: '0').with { it.isLong() ? it : '0' }
-def desktopKde = rootProject.file('tools/desktop-kde/release.env').readLines()
-    .findAll { it.contains('=') && !it.startsWith('#') }
-    .collectEntries { def kv = it.split('=', 2); [(kv[0].trim()): kv[1].trim()] }
-def trackingPack = rootProject.file('tools/packs/tracking/release.env').readLines()
-    .findAll { it.contains('=') && !it.startsWith('#') }
-    .collectEntries { def kv = it.split('=', 2); [(kv[0].trim()): kv[1].trim()] }
-def addonPacks = ['proot', 'directaudio', 'tracking', 'xbox', 'comet'].collectEntries { name ->
-    def pack = file("build/packs/${name}.tar.zst")
-    if (!pack.isFile()) {
-        if (ciBuild) throw new GradleException("Add-on pack ${pack} is missing: run tools/packs/build.sh app/build/packs")
-        return [(name): [sha256: '', size: 0L]]
-    }
-    def digest = java.security.MessageDigest.getInstance('SHA-256')
-    pack.withInputStream { input ->
-        byte[] buffer = new byte[1 << 20]
-        int n
-        while ((n = input.read(buffer)) > 0) digest.update(buffer, 0, n)
-    }
-    [(name): [sha256: digest.digest().encodeHex().toString(), size: pack.length()]]
-}
-def desktopRemovalSources = new groovy.json.JsonSlurper().parse(file('src/main/assets/desktop-removal/sources.json'))
-if (desktopRemovalSources.archives[desktopKde.DESKTOP_KDE_TAG] != desktopKde.DESKTOP_KDE_SHA256) {
-    throw new GradleException('Desktop removal inventories do not match the pinned archive')
-}
-if (!file('src/main/assets/desktop-removal/versions.txt').readLines().contains(desktopKde.DESKTOP_KDE_TAG)) {
-    throw new GradleException('Regenerate desktop removal inventories for ' + desktopKde.DESKTOP_KDE_TAG)
-}
+// tools/release/variants.txt as "package=suffix;...", so the updater picks the apk of the package it runs as.
 def variantSuffixes = rootProject.file('tools/release/variants.txt').readLines()
     .findAll { it.trim() && !it.startsWith('#') }
     .collect { def f = it.trim().split(/\s+/); "${f[1]}=${f[2] == '-' ? '' : f[2]}" }
@@ -116,14 +68,19 @@ def variantSuffixes = rootProject.file('tools/release/variants.txt').readLines()
 android {
     namespace 'com.droiddeck.launcher'
     compileSdk 34
+    // The NDK is pinned by property so CI can hand in whatever the runner already has rather than
+    // downloading a second copy; see gradle.properties.
     ndkVersion project.findProperty('ndkVersion') ?: '27.3.13750724'
 
     defaultConfig {
         applicationId "com.droiddeck.launcher"
         minSdkVersion 26
+        // 28 is not a leftover. An app on targetSdk 29+ runs in a domain that may not execute a
+        // file out of its own data directory, and this app's entire job is to exec a rootfs:
+        // proot, gamescope, the Steam client and everything it launches all live under files/.
         targetSdkVersion 28
-        versionCode 14
-        versionName "0.5.0"
+        versionCode 10
+        versionName "0.3.0"
         buildConfigField "String", "BUILD_LABEL", "\"${escapedBuildLabel}\""
         buildConfigField "String", "SOURCE_COMMIT", "\"${sourceCommit}\""
         buildConfigField "int", "PR_NUMBER", "${prNumber}"
@@ -131,15 +88,6 @@ android {
         buildConfigField "String", "RELEASE_SIGNER", "\"${releaseSigner}\""
         buildConfigField "long", "COMMIT_TIME", "${commitTime}L * 1000L"
         buildConfigField "String", "VARIANT_SUFFIXES", "\"${variantSuffixes}\""
-        buildConfigField "String", "SGDB_API_KEY", "\"${System.getenv("SGDB_API_KEY") ?: project.findProperty("sgdbApiKey") ?: ""}\""
-        buildConfigField "String", "DESKTOP_KDE_TAG", "\"${desktopKde.DESKTOP_KDE_TAG}\""
-        buildConfigField "String", "DESKTOP_KDE_URL", "\"https://github.com/${desktopKde.DESKTOP_KDE_REPO}/releases/download/${desktopKde.DESKTOP_KDE_TAG}/desktop-kde.tar.zst\""
-        buildConfigField "String", "DESKTOP_KDE_SHA256", "\"${desktopKde.DESKTOP_KDE_SHA256}\""
-        buildConfigField "long", "DESKTOP_KDE_SIZE", "${desktopKde.DESKTOP_KDE_SIZE}L"
-        addonPacks.each { name, pack ->
-            buildConfigField "String", "PACK_${name.toUpperCase()}_SHA256", "\"${pack.sha256}\""
-            buildConfigField "long", "PACK_${name.toUpperCase()}_SIZE", "${pack.size}L"
-        }
 
         ndk {
             abiFilters 'arm64-v8a'
@@ -147,8 +95,6 @@ android {
         externalNativeBuild {
             cmake {
                 arguments '-DANDROID_STL=c++_shared'
-                arguments "-DDROIDDECK_VITURE_SDK_DIR=${vitureSdkDir.toString().replace('\\', '/')}"
-                arguments "-DDROIDDECK_UVC_DIR=${uvcDir.toString().replace('\\', '/')}"
             }
         }
     }
@@ -161,6 +107,10 @@ android {
     }
 
     signingConfigs {
+        // AOSP testkey ([email protected]), the same key Bannerlator ships with. It is publicly
+        // known, so it proves nothing about who built the apk - what it buys is ONE stable
+        // signature: every build installs over the last one instead of asking the user to
+        // uninstall first. v1 (JAR) + v2 + v3 so every installer and Android version accepts it.
         testkey {
             storeFile file("${rootDir}/keystore/testkey.p12")
             storeType "PKCS12"
@@ -177,11 +127,6 @@ android {
         debug {
             minifyEnabled false
             signingConfig signingConfigs.testkey
-            def localSuffix = localBuildOptions.getProperty('droiddeck.debugApplicationIdSuffix')
-            if (localSuffix) {
-                applicationIdSuffix localSuffix
-                resValue 'string', 'app_name', 'DroidDeck XR Dev'
-            }
         }
         release {
             minifyEnabled false
@@ -190,41 +135,36 @@ android {
     }
 
     lint {
+        // targetSdk 28 is deliberate and structural: an app on 29+ may not execute a file out of
+        // its own data directory, and executing a rootfs is the whole of what this app does. Lint
+        // fails a release build over it because Google Play will not accept an sdk that old -
+        // true, and not something this app can trade away. Every other check stays on.
         disable 'ExpiredTargetSdkVersion'
     }
 
-    androidResources {
-        // aapt's default ignore list, plus the trees shipped as add-on packs (tools/packs).
-        ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:<dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~:<dir>droiddeck-xbox:<dir>droiddeck-comet:<dir>directaudio'
-    }
-
     packagingOptions {
         resources {
+            // Kadb's Bouncy Castle artifacts repeat the same multi-release JAR manifest.
             excludes += ['META-INF/versions/9/OSGI-INF/MANIFEST.MF']
         }
         jniLibs {
+            // The PulseAudio daemon is executed from the native library directory and its
+            // libraries are read out of the apk by the class loader: both want the old,
+            // uncompressed-and-extracted layout.
             useLegacyPackaging = true
+            // Prefer the PTY helper built by this app's NDK target over Termux's prebuilt copy.
             pickFirsts += ['**/libtermux.so']
-            // Shipped in the proot and tracking packs (tools/packs) and run or loaded from there.
-            excludes += ['**/libproot.so', '**/libproot-loader.so', '**/libopencv_java4.so', '**/libmediapipe_tasks_jni.so']
         }
     }
 
     buildFeatures {
-        prefab true
         compose true
         buildConfig true
     }
 
     testOptions {
+        // Plain JVM tests: a stray android.util.Log call returns a default instead of throwing.
         unitTests.returnDefaultValues = true
-        unitTests.includeAndroidResources = true
-        unitTests.all {
-            // Robolectric keeps a sandbox per SDK level the tests ask for; seven no longer fit in Gradle's default 512 MB.
-            maxHeapSize = '2g'
-            def logTarget = providers.systemProperty('robolectric.logging').orNull
-            if (logTarget != null) systemProperty 'robolectric.logging', logTarget
-        }
     }
 
     compileOptions {
@@ -236,109 +176,28 @@ android {
     }
 }
 
-// Vendor binaries remain in the user's SDK directory; never vendor them into Git.
-if (vitureSdkDir) {
-    android.sourceSets.main.jniLibs.srcDir(new File(vitureSdkDir, 'android'))
-    def stageVitureNotices = tasks.register('stageVitureNotices', Copy) {
-        from(new File(vitureSdkDir, 'android')) { include 'LICENSE', 'NOTICE' }
-        into(layout.buildDirectory.dir('vitureAssets/licenses/viture'))
-    }
-    tasks.named('preBuild').configure { dependsOn(stageVitureNotices) }
-}
-
-def stageSessionScripts = tasks.register('stageSessionScripts', Copy) {
-    from(rootProject.file('tools/linuxfs/overlay')) {
-        include 'usr/local/bin/droiddeck-*', 'usr/local/bin/steam-compatibility', 'usr/bin/**'
-    }
-    into(layout.projectDirectory.dir('src/main/assets/linuxfs'))
-}
-tasks.named('preBuild').configure { dependsOn(stageSessionScripts) }
-
-def runtimeAssetsDir = layout.buildDirectory.dir('runtimeAssets')
-def stageRuntimeAssets = tasks.register('stageRuntimeAssets', Sync) {
-    dependsOn(stageSessionScripts)
-    from(layout.projectDirectory.dir('src/main/assets')) { exclude 'pulseaudio.tzst' }
-    from(layout.buildDirectory.dir('prepared-assets'))
-    into(runtimeAssetsDir)
-}
-android.sourceSets.main.assets.setSrcDirs([runtimeAssetsDir])
-if (vitureSdkDir) android.sourceSets.main.assets.srcDir(layout.buildDirectory.dir('vitureAssets'))
-if (uvcDir) {
-    def stageUvcNotices = tasks.register('stageUvcNotices', Copy) {
-        from(new File(uvcDir, 'licenses'))
-        into(layout.buildDirectory.dir('uvcAssets/licenses/uvc'))
-    }
-    tasks.named('preBuild').configure { dependsOn(stageUvcNotices) }
-    android.sourceSets.main.assets.srcDir(layout.buildDirectory.dir('uvcAssets'))
-}
-tasks.named('preBuild').configure { dependsOn(stageRuntimeAssets) }
-
-def verifyRuntimeInputs = tasks.register('verifyRuntimeInputs', Exec) {
-    mustRunAfter(stageSessionScripts, stageRuntimeAssets)
-    workingDir rootProject.projectDir
-    commandLine pythonExecutable, 'tools/release/runtime_inputs.py', 'verify'
-}
-tasks.configureEach { task ->
-    if (task.name in ['packageDebug', 'packageRelease']) task.dependsOn(verifyRuntimeInputs)
-}
-
-def rustCrateDir = layout.projectDirectory.dir('src/main/rust/stores')
-def rustJniLibsDir = layout.buildDirectory.dir('rustJniLibs')
-def skipRust = (project.findProperty('skipRust')
-    ?: localBuildOptions.getProperty('droiddeck.skipRust', 'false')).toString().toBoolean()
-def buildRustStores = tasks.register('buildRustStores', Exec) {
-    description = 'Cross-compiles the store download engines (libdroiddeckstores.so) with cargo-ndk.'
-    onlyIf { !skipRust }
-    inputs.dir(rustCrateDir.dir('src'))
-    inputs.files(rustCrateDir.file('Cargo.toml'), rustCrateDir.file('Cargo.lock'))
-    inputs.property('ndkVersion', android.ndkVersion)
-    if (!skipRust) inputs.property('rustToolchain', providers.exec {
-        environment 'PATH', "${System.getProperty('user.home')}/.cargo/bin${File.pathSeparator}${System.getenv('PATH')}"
-        commandLine 'rustup', 'run', 'stable', 'rustc', '-Vv'
-    }.standardOutput.asText)
-    outputs.dir(rustJniLibsDir)
-    workingDir rustCrateDir
-    def cargoBin = "${System.getProperty('user.home')}/.cargo/bin"
-    environment 'PATH', "${cargoBin}${File.pathSeparator}${System.getenv('PATH')}"
-    environment 'ANDROID_NDK_HOME', android.ndkDirectory.absolutePath
-    environment 'CARGO_TERM_COLOR', 'never'
-    if (!skipRust) environment 'RUSTC', providers.exec {
-        commandLine 'rustup', 'which', '--toolchain', 'stable', 'rustc'
-    }.standardOutput.asText.get().trim()
-    commandLine 'rustup', 'run', 'stable', 'cargo', 'ndk', '--target', 'arm64-v8a', '--platform', '26',
-        '--output-dir', rustJniLibsDir.get().asFile.absolutePath,
-        'build', '--release', '--locked'
-}
-if (!skipRust) android.sourceSets.main.jniLibs.srcDir(rustJniLibsDir)
-tasks.named('preBuild').configure { dependsOn(buildRustStores) }
-
 dependencies {
-    implementation "org.opencv:opencv:${trackingPack.OPENCV_VERSION}"
-    implementation 'org.khronos.openxr:openxr_loader_for_android:1.1.49'
-    implementation 'com.github.luben:zstd-jni:1.5.7-4@aar'
+    // The runtime tarball is a zstd-compressed tar.
+    implementation 'com.github.luben:zstd-jni:1.5.2-3@aar'
     implementation 'org.apache.commons:commons-compress:1.27.1'
-    implementation 'org.tukaani:xz:1.10'
+    // The UI: every menu, dialog and overlay is Compose. The session's SurfaceView and the
+    // on-screen pad are Views underneath it, which is what they are in every Compose app.
     implementation platform('androidx.compose:compose-bom:2024.02.00')
     implementation 'androidx.compose.ui:ui'
     implementation 'androidx.compose.material3:material3'
-    implementation 'androidx.compose.ui:ui-tooling-preview'
-    debugImplementation 'androidx.compose.ui:ui-tooling'
     implementation 'androidx.activity:activity-compose:1.8.2'
+    // The File Manager, Bannerlator's: its icon set, image thumbnails and the coroutines it
+    // copies on. Same versions as Bannerlator so the screen stays a straight copy.
     implementation 'androidx.compose.material:material-icons-extended'
     implementation 'io.coil-kt:coil-compose:2.6.0'
     implementation 'com.caverock:androidsvg-aar:1.4'
     implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
+    // ADB-over-Wi-Fi pairing and authenticated shell client. Users still approve pairing from
+    // Android's Wireless debugging screen; DroidDeck only runs its one fixed setting command.
     implementation 'com.flyfishxu:kadb-android:1.2.1'
+    // Android terminal view/emulator used by the in-session secondary-display Linux shell.
     implementation 'com.termux.termux-app:terminal-view:0.118.0'
-    implementation 'androidx.camera:camera-camera2:1.4.2'
-    implementation 'androidx.camera:camera-lifecycle:1.4.2'
-    implementation 'androidx.webkit:webkit:1.12.1'
-    implementation("com.google.mediapipe:tasks-vision:${trackingPack.MEDIAPIPE_VERSION}") {
-        exclude group: 'com.google.auto.value', module: 'auto-value'
-    }
 
     testImplementation 'junit:junit:4.13.2'
     testImplementation 'org.robolectric:robolectric:4.16.1'
-    testImplementation 'androidx.compose.ui:ui-test-junit4'
-    testRuntimeOnly 'com.github.luben:zstd-jni:1.5.7-4@jar'
 }

app/src/debug/AndroidManifest.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application>
+        <!-- Debug builds only. Android grants DUMP to adb shell; release APKs have no bridge. -->
+        <activity
+            android:name=".agent.AgentStartActivity"
+            android:exported="true"
+            android:excludeFromRecents="true"
+            android:noHistory="true"
+            android:permission="android.permission.DUMP"
+            android:theme="@style/SessionTheme" />
+        <provider
+            android:name=".agent.AgentBridgeProvider"
+            android:authorities="${applicationId}.agent"
+            android:exported="true"
+            android:permission="android.permission.DUMP"
+            android:grantUriPermissions="false" />
+    </application>
+</manifest>

app/src/debug/java/com/droiddeck/launcher/agent/AgentBridgeProvider.kt

@@ -0,0 +1,166 @@
+package com.droiddeck.launcher.agent
+
+import android.Manifest
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.content.Context
+import android.content.pm.PackageManager
+import android.database.Cursor
+import android.net.Uri
+import android.os.Binder
+import android.os.Bundle
+import android.os.Process
+import com.droiddeck.launcher.BuildConfig
+import com.droiddeck.launcher.runtime.LinuxRuntime
+import com.droiddeck.launcher.runtime.LinuxRuntimeInstaller
+import com.droiddeck.launcher.session.SessionArtifacts
+import com.droiddeck.launcher.session.SessionEvents
+import com.droiddeck.launcher.session.SessionPhase
+import com.droiddeck.launcher.session.SessionPaths
+import com.droiddeck.launcher.session.SessionService
+import com.droiddeck.launcher.session.SessionState
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/** A shell-only control surface, installed only by debug builds. */
+class AgentBridgeProvider : ContentProvider() {
+    override fun onCreate(): Boolean {
+        val appContext = context?.applicationContext ?: return false
+        Thread({
+            try {
+                SessionArtifacts.finishAbandoned(appContext)
+            } finally {
+                recoveryComplete.countDown()
+            }
+        }, "agent-recover-artifacts").start()
+        return true
+    }
+
+    override fun call(method: String, arg: String?, extras: Bundle?): Bundle {
+        val context = requireNotNull(context)
+        if (Binder.getCallingUid() != Process.myUid() &&
+            context.checkCallingPermission(Manifest.permission.DUMP) != PackageManager.PERMISSION_GRANTED
+        ) {
+            throw SecurityException("android.permission.DUMP is required")
+        }
+
+        val response = try {
+            when (method) {
+                "state" -> state(context).put("ok", true)
+                "start" -> error("USE_DROIDDECKCTL", "Start sessions with tools/droiddeckctl so Android launches a visible Activity")
+                "stop" -> stop(context)
+                "resume" -> resume(context)
+                else -> error("UNKNOWN_COMMAND", "Unknown agent command '$method'")
+            }
+        } catch (e: Exception) {
+            error("COMMAND_FAILED", e.message ?: e.javaClass.simpleName)
+        }
+        return Bundle().apply { putString(RESULT_JSON, response.toString()) }
+    }
+
+    private fun state(context: Context): JSONObject {
+        val runtimeVersion = LinuxRuntimeInstaller.installedVersion(context)
+        val dir = SessionState.logDirectory ?: SessionState.logFile?.parentFile ?: latestSessionDirectory()
+        val session = JSONObject()
+            .put("id", SessionState.sessionId ?: dir?.name ?: JSONObject.NULL)
+            .put("phase", SessionState.phase.name)
+            .put("running", SessionState.running)
+            .put("mode", SessionState.mode)
+            .put("program", SessionState.program ?: JSONObject.NULL)
+            .put("steamUi", SessionState.steamUi ?: JSONObject.NULL)
+            .put("steamUrl", SessionState.steamUrl ?: JSONObject.NULL)
+            .put("suspended", SessionState.suspended)
+            .put("firstFrame", SessionState.firstFrameSeen)
+            .put("output", JSONArray().put(SessionState.outputSize.first).put(SessionState.outputSize.second))
+            .put("refreshHz", SessionState.refreshHz.toDouble())
+            .put("lastTransitionAt", SessionState.lastTransitionAt)
+            .put("guestPid", SessionState.guestPid.takeIf { it > 1 } ?: JSONObject.NULL)
+            .put("installing", SessionState.installing ?: JSONObject.NULL)
+            .put("logDir", dir?.absolutePath ?: JSONObject.NULL)
+            .put("eventsFile", dir?.let { File(it, "events.jsonl").absolutePath } ?: JSONObject.NULL)
+            .put("artifactsAvailable", dir?.isDirectory ?: false)
+            .put("artifactsComplete", dir?.let { File(it, ".complete").isFile } ?: false)
+
+        val failure = if (SessionState.failureCode == null) JSONObject.NULL else JSONObject()
+            .put("code", SessionState.failureCode)
+            .put("message", SessionState.failureMessage ?: JSONObject.NULL)
+            .put("status", SessionState.failureStatus ?: JSONObject.NULL)
+        session.put("failure", failure)
+
+        return JSONObject()
+            .put("schema", 1)
+            .put("build", BuildConfig.BUILD_LABEL)
+            .put("appVersion", context.packageManager.getPackageInfo(context.packageName, 0).versionName)
+            .put("runtime", JSONObject()
+                .put("installed", LinuxRuntime.isInstalled(context))
+                .put("version", runtimeVersion ?: JSONObject.NULL))
+            .put("session", session)
+    }
+
+    private fun latestSessionDirectory(): File? {
+        val parent = LinuxRuntime.debugLogDir()
+        return parent.listFiles { file -> file.isDirectory && file.name.startsWith("session-") }
+            ?.maxWithOrNull(compareBy<File> { it.lastModified() }.thenBy { it.name })
+    }
+
+    private fun stop(context: Context): JSONObject {
+        if (SessionState.running) {
+            SessionService.stop(context)
+            return JSONObject().put("ok", true).put("command", "stop")
+        }
+        if (SessionState.phase == SessionPhase.STOPPING) {
+            return JSONObject().put("ok", true).put("command", "stop")
+        }
+        if (SessionState.phase in STARTING_PHASES) {
+            SessionState.stopRequested = true
+            SessionEvents.transition(SessionPhase.STOPPING, "session.stop_requested")
+            return JSONObject().put("ok", true).put("command", "stop")
+        }
+        return error("NO_ACTIVE_SESSION", "There is no session to stop")
+    }
+
+    private fun resume(context: Context): JSONObject {
+        if (!SessionState.running || !SessionState.suspended) {
+            return error("SESSION_NOT_SUSPENDED", "There is no suspended session to resume")
+        }
+        SessionService.resume(context)
+        return JSONObject().put("ok", true).put("command", "resume")
+    }
+
+    private fun error(code: String, message: String) = JSONObject()
+        .put("ok", false)
+        .put("error", JSONObject().put("code", code).put("message", message))
+
+    override fun query(uri: Uri, projection: Array<out String>?, selection: String?, selectionArgs: Array<out String>?, sortOrder: String?): Cursor? = null
+    override fun getType(uri: Uri): String? = null
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+    override fun update(uri: Uri, values: ContentValues?, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+    companion object {
+        const val RESULT_JSON = "json"
+        private val recoveryComplete = CountDownLatch(1)
+
+        fun awaitRecovery() {
+            try {
+                if (!recoveryComplete.await(90, TimeUnit.SECONDS)) {
+                    throw IllegalStateException("Session artifact recovery did not finish")
+                }
+            } catch (e: InterruptedException) {
+                Thread.currentThread().interrupt()
+                throw IllegalStateException("Interrupted while recovering session artifacts", e)
+            }
+        }
+
+        private val STARTING_PHASES = setOf(
+            SessionPhase.PREPARING,
+            SessionPhase.INSTALLING_RUNTIME,
+            SessionPhase.STARTING_COMPOSITOR,
+            SessionPhase.STARTING_GUEST,
+            SessionPhase.STARTING_STEAM,
+        )
+    }
+}

app/src/debug/java/com/droiddeck/launcher/agent/AgentStartActivity.kt

@@ -10,10 +10,10 @@ import com.droiddeck.launcher.session.SessionService
 import org.json.JSONArray
 import org.json.JSONObject
 
+/** Shell-launched trampoline: Android permits the shell to start this protected debug Activity. */
 class AgentStartActivity : Activity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
-        requestedOrientation = com.droiddeck.launcher.session.SessionPrefs.orientation(this)
         val request = decodeRequest(intent.getStringExtra(EXTRA_REQUEST))
         if (request == null) {
             finish()
@@ -38,10 +38,6 @@ class AgentStartActivity : Activity() {
             Log.e(TAG, "missing agent start request")
             return null
         }
-        if (encoded.length > AgentAccess.MAX_REQUEST_CHARS) {
-            Log.w(TAG, "agent start request is too large")
-            return null
-        }
         return try {
             JSONObject(String(Base64.decode(encoded, Base64.DEFAULT), Charsets.UTF_8))
         } catch (e: Exception) {
@@ -51,13 +47,6 @@ class AgentStartActivity : Activity() {
     }
 
     private fun startSession(request: JSONObject) {
-        try {
-            AgentAccess.requireStart(this, request)
-        } catch (e: AgentException) {
-            Log.w(TAG, e.code)
-            finish()
-            return
-        }
         val requestedMode = request.optString("mode")
         val sessionMode = when (requestedMode) {
             "steam" -> SessionService.MODE_STEAM
@@ -97,7 +86,6 @@ class AgentStartActivity : Activity() {
                 request.optString("steamUrl").takeIf { it.startsWith("steam://") }?.let {
                     putExtra(SessionService.EXTRA_STEAM_URL, it)
                 }
-                if (request.optBoolean("steamVr")) putExtra(SessionActivity.EXTRA_STEAMVR, true)
             }
         }
         startActivity(sessionIntent)

app/src/main/AndroidManifest.xml

@@ -1,38 +1,36 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Session logs go to Downloads so a failed run can be handed over as one folder. -->
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
     <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
-    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
-    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- The session keeps running while the app is not on screen: a foreground service holds the
+         process at perceptible priority, and a high-performance WiFi lock keeps a backgrounded
+         download from being throttled to nothing by the radio's power-save. -->
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
-    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
-    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
     <uses-permission android:name="android.permission.VIBRATE" />
+    <!-- Ends background processes of another app that holds the Steam login. GameHub starts
+         itself with the phone via boot receivers and signs this client out seconds after every
+         login; a normal permission, and it cannot touch anything in the foreground. -->
     <uses-permission android:name="android.permission.KILL_BACKGROUND_PROCESSES" />
+    <!-- The microphone for the Linux session, only when the user turns it on: the DirectAudio
+         relay helper opens the input stream under this uid, and PulseAudio exposes it to the
+         Steam client as DirectAudioMic. -->
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <!-- Installs DroidDeck's own updates (Updates page) over itself, after the user allows it. -->
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
-    <uses-permission android:name="android.permission.BLUETOOTH" />
-    <uses-permission android:name="android.permission.CAMERA" />
 
     <uses-feature android:name="android.hardware.vulkan.version" android:version="0x401000" android:required="true" />
     <uses-feature android:name="android.hardware.gamepad" android:required="false" />
-    <uses-feature android:name="android.hardware.camera" android:required="false" />
-    <uses-feature android:name="android.hardware.camera.front" android:required="false" />
-    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
-    <uses-feature android:name="android.hardware.vr.headtracking" android:version="1" android:required="false" />
 
     <application
         android:name=".App"
         android:localeConfig="@xml/locales_config"
-        android:networkSecurityConfig="@xml/network_security_config"
         android:allowBackup="false"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
@@ -43,71 +41,28 @@
         android:appCategory="game"
         android:isGame="true">
 
+        <!-- A game, to the OS: Android 12+ routes the category through GameManager and the OEM
+             performance frameworks (Game Booster, Game Turbo, Game Space) key off it. Without it
+             a regular flagship runs the session under its "app" power profile - a conservative
+             governor and GPU DVFS - which is why the same chipset feels slower here than in a
+             gaming phone whose mode is on for everything. The config says what the OS may do. -->
         <meta-data android:name="android.game_mode_config" android:resource="@xml/game_mode_config" />
-        <service android:name=".glasses.LumaRgbCaptureService" android:exported="false"
-            android:process=":rgb_diagnostic" />
-        <meta-data android:name="com.oculus.supportedDevices" android:value="quest2|quest3|quest3s" />
-        <activity android:name=".QuestXrActivity" android:exported="true" android:launchMode="singleTask"
-            android:permission="android.permission.DUMP"
-            android:resizeableActivity="false" android:screenOrientation="landscape"
-            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|keyboard|navigation|uiMode"
-            android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen">
-            <meta-data android:name="android.app.lib_name" android:value="droiddeckxr" />
-            <intent-filter>
-                <action android:name="com.droiddeck.launcher.XR" />
-                <category android:name="com.oculus.intent.category.VR" />
-                <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />
-            </intent-filter>
-        </activity>
 
         <activity
             android:name=".MainActivity"
             android:exported="true"
             android:screenOrientation="sensorLandscape"
-            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|density|keyboard|keyboardHidden|navigation">
+            android:configChanges="keyboard|keyboardHidden|navigation">
             <intent-filter>
-                <action android:name="android.intent.action.VIEW" />
-                <category android:name="android.intent.category.DEFAULT" />
-                <category android:name="android.intent.category.BROWSABLE" />
-                <category android:name="android.intent.category.CAR_LAUNCHER" />
-                <data android:scheme="droiddeck" android:host="game" />
-            </intent-filter>
-            <intent-filter>
-                <action android:name="android.intent.action.CREATE_SHORTCUT" />
-                <category android:name="android.intent.category.DEFAULT" />
-            </intent-filter>
-            <intent-filter>
-                <action android:name="com.droiddeck.launcher.LAUNCH_GAME" />
-                <category android:name="android.intent.category.DEFAULT" />
-                <category android:name="android.intent.category.CAR_LAUNCHER" />
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
         </activity>
 
-        <activity-alias
-            android:name=".LauncherDark"
-            android:targetActivity=".MainActivity"
-            android:icon="@mipmap/ic_launcher"
-            android:exported="true">
-            <intent-filter>
-                <action android:name="android.intent.action.MAIN" />
-                <category android:name="android.intent.category.LAUNCHER" />
-                <category android:name="android.intent.category.CAR_LAUNCHER" />
-            </intent-filter>
-        </activity-alias>
-
-        <activity-alias
-            android:name=".LauncherLight"
-            android:targetActivity=".MainActivity"
-            android:icon="@mipmap/ic_launcher_light"
-            android:enabled="false"
-            android:exported="true">
-            <intent-filter>
-                <action android:name="android.intent.action.MAIN" />
-                <category android:name="android.intent.category.LAUNCHER" />
-                <category android:name="android.intent.category.CAR_LAUNCHER" />
-            </intent-filter>
-        </activity-alias>
-
+        <!-- Android owns the Home key. This small translucent Home handler routes the resulting
+             Home launch either back into a running Steam session or to the regular front end.
+             Off until the user turns on "Use as a Home screen" (Setup): while it is disabled the
+             app is not a Home app at all - not offered, not in the "choose Home" list. -->
         <activity
             android:name=".HomeActivity"
             android:enabled="false"
@@ -124,7 +79,16 @@
             </intent-filter>
         </activity>
 
+        <!--
+            A session keeps a Surface, a compositor thread and a proot tree alive; a configuration
+            change must not tear that down and rebuild it, so the activity handles them itself.
+            Landscape only: gamescope is told one output size when it starts.
 
+            Resizable, deliberately: a foldable opening or closing changes the window, and the
+            compositor re-fits the picture with bars. Declared non-resizable, the system keeps a
+            fixed-shape window instead and STRETCHES it onto the other panel - the app never sees a
+            size change, so nothing it does can help.
+        -->
         <activity
             android:name=".input.ControllerEditorActivity"
             android:exported="false"
@@ -137,70 +101,42 @@
             android:name=".files.FileManagerActivity"
             android:exported="false"
             android:screenOrientation="sensorLandscape"
-            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|density"
             android:theme="@style/AppTheme" />
 
         <activity
             android:name=".files.FilePickerActivity"
             android:exported="false"
             android:screenOrientation="sensorLandscape"
-            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|density"
             android:theme="@style/AppTheme" />
 
-        <activity android:name=".stores.xbox.XboxLoginActivity" android:exported="false"
-            android:process=":xboxlogin" android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|density"
-            android:theme="@style/AppTheme" />
-
-        <activity
-            android:name=".stores.StoreLoginActivity"
-            android:exported="false"
-            android:screenOrientation="sensorLandscape"
-            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|density"
-            android:theme="@style/AppTheme" />
-
-        <activity
-            android:name=".agent.AgentStartActivity"
-            android:exported="true"
-            android:excludeFromRecents="true"
-            android:noHistory="true"
-            android:permission="android.permission.DUMP"
-            android:theme="@style/SessionTheme" />
-
         <activity
             android:name=".SessionActivity"
             android:exported="false"
-            android:supportsPictureInPicture="true"
-            android:launchMode="singleTask"
+            android:launchMode="singleTop"
             android:theme="@style/SessionTheme"
             android:preferMinimalPostProcessing="true"
             android:screenOrientation="sensorLandscape"
             android:resizeableActivity="true"
             android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboard|keyboardHidden|navigation|uiMode|density" />
 
-        <activity
-            android:name=".gpu.SteamVrRestartActivity"
-            android:exported="false"
-            android:process=":vr_recovery"
-            android:taskAffinity="${applicationId}.vr_recovery"
-            android:excludeFromRecents="true"
-            android:screenOrientation="sensorLandscape"
-            android:configChanges="orientation|screenSize|screenLayout|smallestScreenSize|keyboard|keyboardHidden|navigation|uiMode|density"
-            android:theme="@style/SessionTheme" />
-
+        <!--
+            Owns the session - gamescope, the Steam client, audio - so it survives the activity
+            going away. Without it Android demotes the process as soon as the last visible
+            activity goes, and the low-memory killer reaps the guest: leaving Big Picture to
+            answer a message would come back to a dead Steam and a half-finished download.
+        -->
         <service
             android:name=".session.SessionService"
             android:exported="false"
             android:stopWithTask="false" />
+        <!-- Holds the process in the foreground while the Linux runtime downloads and unpacks. -->
         <service
             android:name=".runtime.RuntimeInstallService"
             android:exported="false" />
         <service
             android:name=".core.WirelessAdbPairingService"
             android:exported="false" />
-        <service
-            android:name=".stores.download.StoreDownloadService"
-            android:exported="false"
-            android:foregroundServiceType="dataSync" />
+        <!-- Hands a zipped session folder to the share sheet; nothing else is exposed. -->
         <provider
             android:name="androidx.core.content.FileProvider"
             android:authorities="${applicationId}.logs"
@@ -210,6 +146,8 @@
                 android:name="android.support.FILE_PROVIDER_PATHS"
                 android:resource="@xml/log_share_paths" />
         </provider>
+        <!-- The app's data folder in Android's file picker ("Open from" > DroidDeck). Only the
+             system's documents UI may bind it; apps get a file only when the user picks it. -->
         <provider
             android:name=".files.AppFilesProvider"
             android:authorities="${applicationId}.documents"
@@ -220,19 +158,5 @@
                 <action android:name="android.content.action.DOCUMENTS_PROVIDER" />
             </intent-filter>
         </provider>
-        <provider
-            android:name=".agent.AgentBridgeProvider"
-            android:authorities="${applicationId}.agent"
-            android:exported="true"
-            android:permission="android.permission.DUMP"
-            android:grantUriPermissions="false" />
-        <activity android:name=".ui.SpatialTrackingActivity" android:exported="false" />
-        <service
-            android:name="com.google.android.datatransport.runtime.backends.TransportBackendDiscovery"
-            tools:node="merge">
-            <meta-data
-                android:name="backend:com.google.android.datatransport.cct.CctBackendFactory"
-                tools:node="remove" />
-        </service>
     </application>
 </manifest>

app/src/main/assets/calibration/luma-ultra-640x480.json

@@ -1,102 +0,0 @@
-{
-  "version": 1,
-  "identity": "luma-ultra-base-v1",
-  "width": 640,
-  "height": 480,
-  "fisheye": false,
-  "error": 1.1209395390660726,
-  "verified": false,
-  "k1": {
-    "rows": 3,
-    "cols": 3,
-    "data": [
-      226.0499636040297,
-      0,
-      321.62348950766386,
-      0,
-      228.36987999988767,
-      242.2674105020684,
-      0,
-      0,
-      1
-    ]
-  },
-  "d1": {
-    "rows": 5,
-    "cols": 1,
-    "data": [
-      -0.28622915867944043,
-      0.1194613930041054,
-      0.007984341063494766,
-      -0.0008220922923559441,
-      -0.025579805296512992
-    ]
-  },
-  "k2": {
-    "rows": 3,
-    "cols": 3,
-    "data": [
-      240.3338202496282,
-      0,
-      320.8790079027563,
-      0,
-      241.14047924325277,
-      260.45566640784716,
-      0,
-      0,
-      1
-    ]
-  },
-  "d2": {
-    "rows": 5,
-    "cols": 1,
-    "data": [
-      -0.27073208928390136,
-      0.08065508519805098,
-      -0.001460778493930769,
-      -0.0003694718992635806,
-      -0.011452505620454932
-    ]
-  },
-  "r": {
-    "rows": 3,
-    "cols": 3,
-    "data": [
-      0.900501479835182,
-      0.04473903344740378,
-      -0.43254537762047496,
-      -0.08255720039597626,
-      0.9941919046988283,
-      -0.06904176485356042,
-      0.4269442510181227,
-      0.0978819468416306,
-      0.8989648107712929
-    ]
-  },
-  "t": {
-    "rows": 3,
-    "cols": 1,
-    "data": [
-      -0.14117171913441395,
-      0.0014051874404824838,
-      -0.007555740272006347
-    ]
-  },
-  "cameraToHead": [
-    -0.05607918,
-    0.023585627,
-    -0.07998472,
-    0.01024512,
-    0.9945703,
-    0.005859665,
-    -0.10339546
-  ],
-  "deviceModel": "VITURE Luma Ultra",
-  "cameraPair": "left0-right0",
-  "sourceValidation": {
-    "exportDate": "2026-10-16",
-    "sourceDeviceVerified": true,
-    "capturedViews": 25,
-    "scope": "Starting geometry from one calibrated Luma Ultra; other units have not been individually validated."
-  }
-}

app/src/main/assets/desktop-removal/sources.json

@@ -1,49 +0,0 @@
-{
-  "archives": {
-    "lxqt-r1": "c2bb860b3b1688287451e2495be5db313ec07f8c8af501dfac2768a9f417bc86",
-    "desktop-kde-r1": "55747e75d0ec055ab7ea1e92a757f3be227cc3205bb9101f5b53cadef6318579",
-    "desktop-kde-r2": "9ba832677b498654136c69d8c8330434d17e4d53cd099acac9bde3ba429b35bf",
-    "emulators-r1": "a1f4806a9663d28f424b4cab1277e0ede80a92e69de5bc063cdc8b45af220164"
-  },
-  "desktopApplications": {
-    "ark-26.08.1-1-aarch64.pkg.tar.xz": "93e2c2b75ff20cd29b4f312ed1979ef6f27255b93232b93bfcdb31239903c1d4",
-    "breeze-6.7.5-1-aarch64.pkg.tar.xz": "1d7f4eb9d8d234caaea23621909f5233d19462c2f058afeeb54bed7b81bd03bd",
-    "breeze-gtk-6.7.5-1-any.pkg.tar.xz": "a0f59bc4fc426879c8f8a97f6dcc707fb7d1b52913da5eb7e9db83777b6957b7",
-    "breeze-icons-6.30.0-1-aarch64.pkg.tar.xz": "4bae4689032501156687a227024e56554820747644953c67fc8d2e2b6b0b045a",
-    "dolphin-26.08.1-1-aarch64.pkg.tar.xz": "fef738ab8132d3eba1156b98c116699ce0a5efcb4cb462efbacdcf4c47f79a23",
-    "firefox-157.0.1-1-aarch64.pkg.tar.xz": "d142fdb8a339a65eca7cea6a2bba5b29202386166abd9d59851d6757c9eb2163",
-    "gwenview-26.08.1-1-aarch64.pkg.tar.xz": "a9dc7d5ab73fa677905d5a57248b1b9b404b6b16e862958cc7443d387f684a47",
-    "kate-26.08.1-1-aarch64.pkg.tar.xz": "acf50710042746f243a3b219a1ae0f788e338f3dd9d75093e8bb671a618b83b6",
-    "kde-cli-tools-6.7.5-1-aarch64.pkg.tar.xz": "af466398a912a994a97fadfe46aff401d88a90d7fdce7e843dc4218098fa38ac",
-    "kde-gtk-config-6.7.5-1-aarch64.pkg.tar.xz": "ba6cb4cb01dbb3f2c247f2f6973ede3b64c0849f89340217b51dfbf11cb8cb5c",
-    "kinfocenter-6.7.5-1-aarch64.pkg.tar.xz": "f3d5416db96b50f9a5b8a284d82ae21d834a8cce646010abdd7087491c399b0b",
-    "konsole-26.08.1-1-aarch64.pkg.tar.xz": "1ecf87c0d11d620ebe4aeafb02788e0d5f4fe9019ad9c5d9f1011c43237dd5ec",
-    "kscreen-6.7.5-1-aarch64.pkg.tar.xz": "8fbaa6fedf93edeba021a5416b551663654919b27c2ee237d696ec0b0ce7d5b7",
-    "kwin-6.7.5-1-aarch64.pkg.tar.xz": "a7535710c74b90359f80306134b2b7581132cbac508dc84b7e07ef275cc8c3fe",
-    "mpv-1:0.41.0-6-aarch64.pkg.tar.xz": "6c89d00736820210a3c7f32af4cf95d155191d463f9df8bd22137c45f30a554a",
-    "plasma-desktop-6.7.5-1-aarch64.pkg.tar.xz": "b266dd42cea965b5ab1cc1ae600877e9d3bc83ec642c61fe1669c4457e641a55",
-    "plasma-integration-6.7.5-1-aarch64.pkg.tar.xz": "daa96da14d9a4d12c0d9c0341e1be6836a9a437c469d61da5e9844d51e2606cf",
-    "plasma-pa-6.7.5-1-aarch64.pkg.tar.xz": "02dbefe9d3e0069b2bb37cac2a6be18b8f0a1887c87704a0716e7a9268eadcd8",
-    "plasma-workspace-6.7.5-1-aarch64.pkg.tar.xz": "3a1455857afaa9ccf342ab6167f0f15794ee9d248b0925398ea6f62f12730a86",
-    "spectacle-1:6.7.5-1-aarch64.pkg.tar.xz": "0c9837412ea6119edef18bcb0a8fceb74634cb35be0ca78b3e1dd1ff2443866e",
-    "systemsettings-6.7.5-1-aarch64.pkg.tar.xz": "b02b6a726857d5125c92d1ec95379216c7a3bc1f187a3b46e88c0d056b29ce70",
-    "xdg-desktop-portal-kde-6.7.5-1-aarch64.pkg.tar.xz": "2c57d17d34d577023eb9cd7b0fca1ba9163549afe60450f6271aa148af099ef2"
-  },
-  "legacyApplications": {
-    "featherpad-1.6.3-1-aarch64.pkg.tar.xz": "fcac55215815c0b712453f9bcc09abfe4b518e36025a111a7a7598ef04913f3d",
-    "labwc-0.20.2-1-aarch64.pkg.tar.xz": "bcd4cc3945165b0fdd33c0117cd7b9dfd05cf8c327326c37f3c3a27ef23ee5ca",
-    "lximage-qt-2.4.0-1-aarch64.pkg.tar.xz": "5d6bdd5472ea6bcb4b993b36df3ab7010bb2e62b36a78a649708fc9a52cb0928",
-    "lxqt-config-2.4.0-1-aarch64.pkg.tar.xz": "4b601d798fc7689ee76787dbef8c8958c02429ee60248cd99d950c919dbefba5",
-    "lxqt-panel-2.4.1-1-aarch64.pkg.tar.xz": "a141e0f8049e73f859d843510c6f45d6ed9087c990bcebf44f5f2430621024c4",
-    "lxqt-qtplugin-2.4.0-3-aarch64.pkg.tar.xz": "61c8f828be73111ee0bd5e3163b0d64c2098dd0189710a190f42be11137695cf",
-    "lxqt-runner-2.4.0-1-aarch64.pkg.tar.xz": "5afa74652a37366ea4e7774cf33379977582fbdca599cef1005ebf637cbcae4b",
-    "lxqt-session-2.4.0-2-aarch64.pkg.tar.xz": "e9c7c8a0011859029622ad202e0d3826e4e5bc8d64659031f6efa211456ff6eb",
-    "lxqt-themes-2.4.0-1-any.pkg.tar.xz": "7ea16c62a1fa70cdac13cb3f8fdcdaad299ae1f5bd514acfda671484755787bf",
-    "lxqt-wayland-session-0.4.1-1-any.pkg.tar.xz": "cd8dc11f5035469d23b6bbd937a90593402428c43de37517412aa43fe1fc6b10",
-    "papirus-icon-theme-20260801-1-any.pkg.tar.xz": "4aae3f47b800a60d6fd360e55adc581408ceaafc481c5a420a681741a3966510",
-    "pcmanfm-qt-2.4.1-1-aarch64.pkg.tar.xz": "7ec1a6b39dd0e4055b39f0e2c0549ea263d83004e1b821fb9e42f1d7f5fff0f9",
-    "qterminal-2.4.0-1-aarch64.pkg.tar.xz": "aa4adc9c9d47641b9452ec8d879038a9cb4762c3b6b5299045fac968fd0ed22d",
-    "swaybg-1.2.2-1-aarch64.pkg.tar.xz": "a26caa16ca7d581b5ca05758677058b4b60af10dc8d83e447ad6824b762b48b8",
-    "wlr-randr-0.5.0-1-aarch64.pkg.tar.xz": "58c3651c6a15dc8f95a310c7e225f759aa766be2fb3c0981a9a8b567854675b3"
-  }
-}

app/src/main/assets/desktop-removal/versions.txt

@@ -1,2 +0,0 @@
-desktop-kde-r1
-desktop-kde-r2

app/src/main/assets/directaudio/linux-wine11/README.md

@@ -0,0 +1,115 @@
+# DirectAudio for the Linux Steam client (relay build)
+
+This is the driver for games that run under **Valve's ARM64 Proton inside a Linux
+runtime on Android** - Bannerlator's linuxfs session with the native Steam client -
+where the game process is a glibc process and cannot touch Android's audio
+libraries itself.
+
+Two pieces, both required:
+
+| piece | what it is | where it runs |
+|---|---|---|
+| `aarch64-unix/winedirectaudio.so` + the two PE shells | the Wine `mmdevapi` driver, glibc build, **no AAudio inside** | in the game, inside the Linux rootfs |
+| `directaudio-relay` | a small bionic program that owns the AAudio output and microphone streams | on the Android side, under the app's uid |
+
+They meet over a unix socket. The driver connects, sends its launch config, and
+gets back two shared-memory rings: one it fills with mixed game audio, one the
+helper fills with microphone audio. The helper plays and records; the driver
+keeps doing everything else it always did.
+
+## Which Proton
+
+Built inside `ValveSoftware/wine` at `proton_11.0`. The private `mmdevapi`
+interface it implements is byte-identical across **Proton 11.0 (ARM64)**,
+**Proton Experimental (ARM64)** and our own Wine-11 layers (checked 2026-09-19),
+so this one build serves any of them. A future Proton on a Wine 12 base will
+need a rebuild - the interface is not versioned, and a mismatch is silence, not
+an error.
+
+## Installing the driver next to Proton (not into it)
+
+Steam verifies and updates its Proton depots, so files added under
+`steamapps/common/Proton .../files/lib/wine/` will not survive. Put the driver
+in a directory of its own and point Wine at it:
+
+```
+<somewhere>/directaudio/lib/wine/aarch64-unix/winedirectaudio.so
+<somewhere>/directaudio/lib/wine/aarch64-windows/winedirectaudio.drv
+<somewhere>/directaudio/lib/wine/i386-windows/winedirectaudio.drv
+```
+
+and set, for the game process:
+
+```
+WINEDLLPATH=<somewhere>/directaudio/lib/wine
+```
+
+Wine searches `WINEDLLPATH` entries with the per-arch subdirectories appended,
+so both the PE shell and the unixlib are found there. In Bannerlator's runtime
+the natural place to export it is the `bannerlator-proton` compatibility-tool
+wrapper, which every Proton launch goes through.
+
+## Selecting the driver
+
+`mmdevapi` only tries the drivers named in the registry (or its built-in
+`pulse,alsa,oss,coreaudio` list, which does not know about this one). Set, in the
+game's prefix:
+
+```
+wine reg add "HKCU\Software\Wine\Drivers" /v Audio /d directaudio /f
+```
+
+Under Proton the prefix is `compatdata/<appid>/pfx`; run the command with that
+prefix as `WINEPREFIX` using Proton's own `bin-arm64/wine`, or write the key from
+the wrapper before it hands off to Proton.
+
+## Running the helper
+
+```
+directaudio-relay --socket <path> [--log]
+```
+
+- Run it **under the app's uid**, the way the app already runs its PulseAudio
+  daemon. Android checks `RECORD_AUDIO` against the calling uid, so a helper
+  started any other way can play but cannot record.
+- Start it **before** the game: the driver asks "is a helper there?" once, when
+  Wine picks an audio driver, and falls back to unavailable if not.
+- The socket path must be reachable from inside the Linux rootfs. Bannerlator
+  binds the app's files directory and its runtime directory into the session at
+  their own paths, so any socket under either works unchanged on both sides.
+- The helper serves any number of game processes; each gets its own streams.
+  It exits on `SIGTERM`; a game exiting tears down that game's streams only.
+
+## Telling the driver where the helper is
+
+```
+BANNER_AUDIO_DIRECT_RELAY=<the same socket path>
+```
+
+Unset, the driver looks for `$XDG_RUNTIME_DIR/directaudio-relay`.
+
+## Everything else is unchanged
+
+All `BANNER_AUDIO_DIRECT_*` knobs mean what they mean in the in-process build:
+`_PERF`, `_ADAPTIVE`, `_DECAY`, `_MS`, `_MAXMS`, `_BF`, `_MBF`, `_EXCLUSIVE`,
+`_WATCHDOG`, `_STALL_MS`, `_DECAY_*`, `_LOG`, `_PERIOD_MS`, `_MINPERIOD_MS`, and
+the live-config mailbox `_RUNTIME` (the helper watches the file; it must be a
+path the helper can read on the Android side). **`BANNER_AUDIO_DIRECT_MIC=1`**
+exposes the capture endpoint exactly as before: the helper opens the input
+stream (`VOICE_COMMUNICATION` preset) when the game connects and makes it hot on
+the game's first capture start.
+
+One thing is different: there is one extra hand-off, the ring. The helper's
+callback pulls a burst from it, so the driver keeps two bursts queued (about 8 ms
+on a 192-frame device) on top of the AAudio buffer the presets control, and the
+helper raises that if a callback ever finds the ring short. `get_latency` reports
+the sum, so a game that sizes its own buffers from it still sees the truth.
+
+## Proving it is running
+
+- Helper side: `logcat -s DA-Relay:I` shows `hello from <exe>`, then `open: buffer
+  ... ring target ...`, then `capture open` / `capture start` for the mic.
+- Game side: the session log carries `DirectAudio: relay: connected - ...`.
+- The game process's `/proc/<pid>/maps` shows `winedirectaudio.so` and **no**
+  `libaaudio.so` (it is in the helper's maps instead). The AudioFlinger track is
+  owned by the helper's pid.

app/src/main/assets/directaudio/linux-wine11/version.txt

@@ -0,0 +1,4 @@
+directaudio linux-wine11 relay build
+source 3548a4a730e8d01cb0cb0268d51a2fb8f23dcd33
+wine ValveSoftware/wine@proton_11.0
+unixlib.h sha256 fdbed263338d0719c4d12e02b045c23721de33219ec8878e4c2d7ebc9efcbe09

app/src/main/assets/licenses/viture-v2/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Holger Bartnick
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

app/src/main/cpp/CMakeLists.txt

@@ -1,65 +1,49 @@
+# The app's native side: the Wayland compositor the session presents into, the adrenotools loader
+# it opens Turnip with, and one small library for the fake-input ring's memory fence.
 cmake_minimum_required(VERSION 3.22.1)
 project(droiddeck C CXX)
 
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2 -Wno-unused-function -Wimplicit-function-declaration")
 
+# Every library the app builds is linked with 16 KB-aligned LOAD segments. A 16 KB-page kernel
+# (Android 15+ devices) refuses to load a 4 KB-only ELF; a 4 KB kernel loads a 16 KB-aligned one
+# unchanged (the alignment is a multiple of its page), so this costs nothing on today's devices
+# but a little padding in the file. Prebuilt libraries under jniLibs/ carry their own alignment.
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 
 add_subdirectory(adrenotools)
 
-# DXVK's DXBC->SPIR-V translator is zlib licensed (vendored under thirdparty/dxbc).
+# DXVK's DXBC->SPIR-V translator (zlib licence), vendored under thirdparty/dxbc from the same
+# subset upstream lsfg-vk uses. Native LSFG frame generation needs it: the Lossless Scaling
+# shader chain is DXBC in every build downloadable from Steam.
 add_subdirectory(thirdparty/dxbc)
 
-set(DDFG_UPSTREAM "v0.3.0")
-set(DDFG_CHAIN_SRC
-        framegen/ddfg/framegen.cpp
-        framegen/ddfg/framegen.hpp
-        framegen/ddfg/record_impl.inc
-        framegen/ddfg/config.hpp
-        framegen/ddfg/embedded_shaders.hpp
-        framegen/ddfg/ddfg_engine.cpp
+# The Win-FG chain self-identifies by two halves: the upstream tag it was copied from (hand-set,
+# UPDATE IT when re-copying) and a hash over the sources themselves, computed here, which cannot
+# rot. The compositor's frame-generation leg (waylandcomp/CMakeLists.txt) stamps both in.
+set(WINFG_UPSTREAM "v0.3.0")
+set(WINFG_CHAIN_SRC
+        framegen/winfg/framegen.cpp
+        framegen/winfg/framegen.hpp
+        framegen/winfg/record_impl.inc
+        framegen/winfg/config.hpp
+        framegen/winfg/embedded_shaders.hpp
+        framegen/winfg/winfg_engine.cpp
 )
-set(DDFG_HASH_INPUT "")
-foreach(f ${DDFG_CHAIN_SRC})
+set(WINFG_HASH_INPUT "")
+foreach(f ${WINFG_CHAIN_SRC})
     file(SHA256 "${CMAKE_CURRENT_SOURCE_DIR}/${f}" _h)
-    string(APPEND DDFG_HASH_INPUT "${_h}")
+    string(APPEND WINFG_HASH_INPUT "${_h}")
 endforeach()
-string(SHA256 DDFG_CHAIN_HASH_FULL "${DDFG_HASH_INPUT}")
-string(SUBSTRING "${DDFG_CHAIN_HASH_FULL}" 0 12 DDFG_CHAIN_HASH)
-message(STATUS "dd-fg chain: win-fg ${DDFG_UPSTREAM} (src ${DDFG_CHAIN_HASH})")
+string(SHA256 WINFG_CHAIN_HASH_FULL "${WINFG_HASH_INPUT}")
+string(SUBSTRING "${WINFG_CHAIN_HASH_FULL}" 0 12 WINFG_CHAIN_HASH)
+message(STATUS "win-fg chain: ${WINFG_UPSTREAM} (src ${WINFG_CHAIN_HASH})")
 
 add_subdirectory(waylandcomp)
-add_subdirectory(questxr)
 add_library(sdnative SHARED sdnative/sdnative.c)
 target_link_libraries(sdnative log)
 
-add_library(deviceinfo SHARED deviceinfo/vkinfo.c)
-target_link_libraries(deviceinfo dl)
-
+# Rebuild Termux terminal-emulator's PTY JNI helper with the app's NDK instead of carrying its
+# prebuilt libtermux.so with a redundant libstdc++.so dependency.
 add_library(termux SHARED termux/termux.c)
-
-add_library(ddvenc SHARED venc/venc_server.cpp)
-target_compile_features(ddvenc PRIVATE cxx_std_17)
-target_link_libraries(ddvenc mediandk log)
-
-# The optional proprietary SDK is supplied locally; its headers/libraries are not vendored.
-if(DROIDDECK_VITURE_SDK_DIR)
-    add_library(droiddeck_viture SHARED viture/sdk_bridge.cpp)
-    target_compile_features(droiddeck_viture PRIVATE cxx_std_17)
-    target_include_directories(droiddeck_viture PRIVATE "${DROIDDECK_VITURE_SDK_DIR}/include")
-    target_link_directories(droiddeck_viture PRIVATE "${DROIDDECK_VITURE_SDK_DIR}/android/${ANDROID_ABI}")
-    target_link_libraries(droiddeck_viture PRIVATE glasses log)
-endif()
-
-if(DROIDDECK_UVC_DIR)
-    add_library(rgb_usb SHARED IMPORTED)
-    set_target_properties(rgb_usb PROPERTIES IMPORTED_LOCATION "${DROIDDECK_UVC_DIR}/${ANDROID_ABI}/libusb.so")
-    add_library(rgb_uvc STATIC IMPORTED)
-    set_target_properties(rgb_uvc PROPERTIES IMPORTED_LOCATION "${DROIDDECK_UVC_DIR}/${ANDROID_ABI}/libuvc.a")
-    add_library(droiddeck_uvc SHARED viture/uvc_bridge.cpp)
-    target_compile_features(droiddeck_uvc PRIVATE cxx_std_17)
-    target_include_directories(droiddeck_uvc PRIVATE "${DROIDDECK_UVC_DIR}/include")
-    target_link_libraries(droiddeck_uvc PRIVATE rgb_uvc rgb_usb log)
-    target_link_options(droiddeck_uvc PRIVATE -Wl,-z,max-page-size=16384)
-endif()

app/src/main/cpp/adrenotools/build_asm.sh

@@ -3,6 +3,7 @@
 aarch64-linux-gnu-gcc -c src/bcenabler_patch.s -o /tmp/patch.o
 aarch64-linux-gnu-objcopy -O binary -j .text /tmp/patch.o /tmp/patch.bin
 
+# Must be smaller than a single page
 bin2c -o gen/bcenabler_patch.h -n PatchRawData /tmp/patch.bin
 
 rm /tmp/patch.o

app/src/main/cpp/adrenotools/gen/bcenabler_patch.h

@@ -1,4 +1,6 @@
+/* Generated by bin2c, do not edit manually */
 
+/* Contents of file /tmp/patch.bin */
 const long int PatchRawData_size = 264;
 const unsigned char PatchRawData[264] = {
     0x1F, 0x0C, 0x02, 0x71, 0x61, 0x00, 0x00, 0x54, 0xE0, 0x08, 0x80, 0x52, 0x3E, 0x00, 0x00, 0x14,

app/src/main/cpp/adrenotools/include/adrenotools/bcenabler.h

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #ifdef __cplusplus
@@ -12,14 +11,29 @@ extern "C" {
 
 #include <stdint.h>
 
+/**
+ * @brief Describes the level of BCeNabler support for a driver
+ */
 enum adrenotools_bcn_type {
-    ADRENOTOOLS_BCN_INCOMPATIBLE,
-    ADRENOTOOLS_BCN_BLOB,
-    ADRENOTOOLS_BCN_PATCH
+    ADRENOTOOLS_BCN_INCOMPATIBLE, //!< Driver isn't supported by BCeNabler
+    ADRENOTOOLS_BCN_BLOB, //!< Driver already supports BCn textures so BCeNabler isn't necessary
+    ADRENOTOOLS_BCN_PATCH //!< Driver can be patched with BCeNabler to support BCn textures
 };
 
+/**
+ * @brief Checks the status of BCn support in the supplied driver
+ * @param major The major part of VkPhysicalDeviceProperties::driverVersion
+ * @param minor The minor part of VkPhysicalDeviceProperties::driverVersion
+ * @param vendorId VkPhysicalDeviceProperties::vendorId
+ */
 enum adrenotools_bcn_type adrenotools_get_bcn_type(uint32_t major, uint32_t minor, uint32_t vendorId);
 
+/**
+ * @brief Patches the Adreno graphics driver to enable support for BCn compressed formats
+ * @note adrenotools_get_bcn_type MUST be checked to equal ADRENOTOOLS_BCN_PATCH before calling this
+ * @param vkGetPhysicalDeviceFormatPropertiesFn A pointer to vkGetPhysicalDeviceFormatProperties obtained through vkGetInstanceProcAddr. This is used to find the correct function to patch
+ * @return If the patching succeeded, if false the driver will be in an undefined state
+ */
 bool adrenotools_patch_bcn(void *vkGetPhysicalDeviceFormatPropertiesFn);
 
 #ifdef __cplusplus

app/src/main/cpp/adrenotools/include/adrenotools/driver.h

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #ifdef __cplusplus
@@ -11,16 +10,60 @@ extern "C" {
 #include <stdbool.h>
 #include "priv.h"
 
+/**
+ * @brief Opens a new libvulkan.so instance according to `flags`
+ * @remark IMPORTANT: The app MUST be packaged w/ useLegacyPackaging = true. The reason for this is
+ * that we install the hook in hookLibDir; but this folder won't be set correctly when useLegacyPackaging == false
+ * because Android expects to read the *.so directly from the apk (instead of decompressing them into nativeLibraryDir).
+ * @param dlopenMode The dlopen mode to use when opening libvulkan
+ * @param featureFlags Which adrenotools driver features to enable
+ * @param tmpLibDir A writable directory to hold patched libraries, only used on api < 29 due to the lack of memfd support. If nullptr is passed and the API version is < 29 memfd usage will be attempted and if unsupported nullptr will be returned
+ * @param hookLibDir The directory holding the built hooks.
+ * IMPORTANT: This path MUST point to whatever `getApplicationInfo().nativeLibraryDir` (Kotlin code) returns.
+ * Failing to do so will result in this function returning a valid ptr but then the hook will fail and either the original driver is loaded as fallback, or vkEnumeratePhysicalDevices returns 0 devices.
+ * @param customDriverDir The directory to load a custom GPU driver named according to `customDriverName` from. Only used if ADRENOTOOLS_DRIVER_CUSTOM is set in `featureFlags`.
+ * IMPORTANT: This path MUST NOT be on sdcard/storage. i.e. use ANativeActivity::internalDataPath and often looks like "/data/user/0/com.example.app/files/".
+ * Otherwise you will get permission denied because dlopen() can't be done on *.so libraries that any random user or application can manipulate (which would be a security risk).
+ * @param customDriverName The soname of the custom driver to load. Only used if ADRENOTOOLS_DRIVER_CUSTOM is set in `featureFlags`
+ * @param fileRedirectDir The directory which to redirect all file accesses performed by the driver to. Only used if ADRENOTOOLS_DRIVER_FILE_REDIRECT is set in `featureFlags`
+ * @param userMappingHandle A pointer to a void* which will be set to the mapping handle if ADRENOTOOLS_DRIVER_GPU_MAPPING_IMPORT is set in `featureFlags`
+ */
 void *adrenotools_open_libvulkan(int dlopenMode, int featureFlags, const char *tmpLibDir, const char *hookLibDir, const char *customDriverDir, const char *customDriverName, const char *fileRedirectDir, void **userMappingHandle);
 
+/**
+ * @brief Imports the given CPU mapped memory range into the GSL allocator. This should then be followed by a call to vkAllocateMemory with a matching size which will return a VkDeviceMemory view over the input region
+ * @param handle Mapping handle that was returned by adrenotools_open_libvulkan
+ * @param hostPtr The host pointer to import
+ * @param size The size of the region to import
+ * @return True on success
+ */
 bool adrenotools_import_user_mem(void *handle, void *hostPtr, uint64_t size);
 
+/**
+ * @brief Maps GPU memory and imports it into the GSL allocator. This should then be followed by a call to adrenotools_mem_cpu_map to map the memory on the CPU, then finally vkAllocateMemory with a matching size
+ * @param handle Mapping handle that was returned by adrenotools_open_libvulkan
+ * @param size Pointer to a variable containing the size of the region to import, will be updated to contain the required size of the region to allocate CPU side
+ * @return true on success
+ */
 bool adrenotools_mem_gpu_allocate(void *handle, uint64_t *size);
 
+/**
+ * @brief Maps the last mapping allocated using adrenotools_mem_gpu_allocate into the given host memory region, such that vkAllocateMemory can then be called
+ * @param handle Mapping handle that was returned by adrenotools_open_libvulkan
+ * @param hostPtr A pointer to where the mapping should be mapped
+ * @param size The size of the mapping. MUST be equal to the size returned by adrenotools_mem_gpu_allocate
+ */
 bool adrenotools_mem_cpu_map(void *handle, void *hostPtr, uint64_t size);
 
+/**
+ * @note This function should be called after adrenotools_open_libvulkan and Vulkan driver init to check if the mapping import hook loaded successfully
+ * @return True if the mapping was successfully imported (or initialization succeeded)
+ */
 bool adrenotools_validate_gpu_mapping(void *handle);
 
+/**
+ * @brief Provides a way to force the GPU to run at the maximum possible clocks (thermal constraints will still be applied)
+ */
 void adrenotools_set_turbo(bool turbo);
 
 #ifdef __cplusplus

app/src/main/cpp/adrenotools/include/adrenotools/priv.h

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #include <stdint.h>
 
+/**
+ * @brief Bitfield enum of additional driver features that can be used with adrenotools_open_libvulkan
+ */
 enum {
     ADRENOTOOLS_DRIVER_CUSTOM = 1 << 0,
     ADRENOTOOLS_DRIVER_FILE_REDIRECT = 1 << 1,
@@ -14,9 +16,12 @@ enum {
 
 #define ADRENOTOOLS_GPU_MAPPING_SUCCEEDED_MAGIC 0xDEADBEEF
 
+/**
+ * @brief A replacement GPU memory mapping for use with ADRENOTOOLS_DRIVER_GPU_MAPPING_IMPORT
+ */
 struct adrenotools_gpu_mapping {
     void *host_ptr;
-    uint64_t gpu_addr;
+    uint64_t gpu_addr; //!< The GPU address of the mapping to import, if mapping import/init succeeds this will be set to ADRENOTOOLS_GPU_MAPPING_SUCCEEDED_MAGIC
     uint64_t size;
     uint64_t flags;
 };

app/src/main/cpp/adrenotools/lib/linkernsbypass/android_linker_ns.cpp

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #include <array>
 #include <cstdio>
 #include <cstdlib>
@@ -22,6 +21,7 @@ static loader_android_create_namespace_t loader_android_create_namespace;
 static bool lib_loaded;
 
 
+/* Public API */
 bool linkernsbypass_load_status() {
     return lib_loaded;
 }
@@ -55,6 +55,8 @@ android_link_namespaces_all_libs_t android_link_namespaces_all_libs;
 android_link_namespaces_t android_link_namespaces;
 
 bool linkernsbypass_link_namespace_to_default_all_libs(android_namespace_t *to) {
+    // Creating a shared namespace with the default parent will give a copy of the default namespace that we can actually access
+    // This is needed since there is no way to access a direct handle to the default namespace as it's not exported
     static auto defaultNs{android_create_namespace_escape("default_copy", nullptr, nullptr, ANDROID_NAMESPACE_TYPE_SHARED, nullptr, nullptr)};
     return android_link_namespaces_all_libs(to, defaultNs);
 }
@@ -79,6 +81,7 @@ void *linkernsbypass_namespace_dlopen(const char *filename, int flags, android_n
 void *linkernsbypass_namespace_dlopen_unique(const char *libPath, const char *libTargetDir, int flags, android_namespace_t *ns) {
     static std::array<char, PATH_MAX> PathBuf{};
 
+    // Used as a unique ID for overwriting soname and creating target lib files
     static uint16_t TargetId{};
 
     int libTargetFd{[&] () {
@@ -86,6 +89,7 @@ void *linkernsbypass_namespace_dlopen_unique(const char *libPath, const char *li
             snprintf(PathBuf.data(), PathBuf.size(), "%s/%d_patched.so", libTargetDir, TargetId);
             return open(PathBuf.data(), O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
         } else {
+            // If memfd isn't supported errno will contain ENOSYS after calling
             errno = 0;
             int fd{static_cast<int>(syscall(__NR_memfd_create, libPath, 0))};
             if (errno == ENOSYS || fd < 0)
@@ -97,18 +101,21 @@ void *linkernsbypass_namespace_dlopen_unique(const char *libPath, const char *li
     if (libTargetFd == -1)
         return nullptr;
 
+    // Partially overwrite soname with 3 digits (replacing lib...) with to make sure a cached so isn't loaded
     std::array<char, 3> sonameOverwrite{};
     snprintf(sonameOverwrite.data(), sonameOverwrite.size(), "%03u", TargetId++);
 
     if (!elf_soname_patch(libPath, libTargetFd, sonameOverwrite.data()))
         return nullptr;
 
+    // Load our patched library into the hook namespace
     android_dlextinfo hookExtInfo{
         .flags = ANDROID_DLEXT_USE_NAMESPACE | ANDROID_DLEXT_USE_LIBRARY_FD,
         .library_fd = libTargetFd,
         .library_namespace = ns
     };
 
+    // Make a path that looks about right
     snprintf(PathBuf.data(), PathBuf.size(), "/proc/self/fd/%d", libTargetFd);
 
     return android_dlopen_ext(PathBuf.data(), flags, &hookExtInfo);
@@ -118,19 +125,21 @@ static void *align_ptr(void *ptr) {
     return reinterpret_cast<void *>(reinterpret_cast<uintptr_t>(ptr) & ~(getpagesize() - 1));
 }
 
+/* Private */
 __attribute__((constructor)) static void resolve_linker_symbols() {
     using loader_dlopen_t = void *(*)(const char *, int, const void *);
 
     if (android_get_device_api_level() < 28)
         return;
 
+    // ARM64 specific function walking to locate the internal dlopen handler
     auto loader_dlopen{[]() {
         union BranchLinked {
             uint32_t raw;
 
             struct {
-                int32_t offset : 26;
-                uint8_t sig : 6;
+                int32_t offset : 26; //!< 26-bit branch offset
+                uint8_t sig : 6;  //!< 6-bit signature
             };
 
             bool Verify() {
@@ -139,8 +148,10 @@ __attribute__((constructor)) static void resolve_linker_symbols() {
         };
         static_assert(sizeof(BranchLinked) == 4, "BranchLinked is wrong size");
 
+        // Some devices ship with --X mapping for exexecutables so work around that
         mprotect(align_ptr(reinterpret_cast<void *>(&dlopen)), getpagesize(), PROT_WRITE | PROT_READ | PROT_EXEC);
 
+        // dlopen is just a wrapper for __loader_dlopen that passes the return address as the third arg hence we can just walk it to find __loader_dlopen
         auto blInstr{reinterpret_cast<BranchLinked *>(&dlopen)};
         while (!blInstr->Verify())
             blInstr++;
@@ -148,8 +159,10 @@ __attribute__((constructor)) static void resolve_linker_symbols() {
         return reinterpret_cast<loader_dlopen_t>(blInstr + blInstr->offset);
     }()};
 
+    // Protect the loader_dlopen function to remove the BTI attribute (since this is an internal function that isn't intended to be jumped indirectly to)
     mprotect(align_ptr(reinterpret_cast<void *>(&loader_dlopen)), getpagesize(), PROT_WRITE | PROT_READ | PROT_EXEC);
 
+    // Passing dlopen as a caller address tricks the linker into using the internal unrestricted namespace letting us access libraries that are normally forbidden in the classloader namespace imposed on apps
     auto ldHandle{loader_dlopen("ld-android.so", RTLD_LAZY, reinterpret_cast<void *>(&dlopen))};
     if (!ldHandle)
         return;
@@ -174,5 +187,6 @@ __attribute__((constructor)) static void resolve_linker_symbols() {
     if (!android_get_exported_namespace)
         return;
 
+    // Lib is now safe to use
     lib_loaded = true;
 }

app/src/main/cpp/adrenotools/lib/linkernsbypass/android_linker_ns.h

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #ifdef __cplusplus
@@ -10,6 +9,7 @@ extern "C" {
 
 #include <stdint.h>
 
+// https://cs.android.com/android/platform/superproject/+/0a492a4685377d41fef2b12e9af4ebfa6feef9c2:art/libnativeloader/include/nativeloader/dlext_namespaces.h;l=25;bpv=1;bpt=1
 enum {
   ANDROID_NAMESPACE_TYPE_REGULAR = 0,
   ANDROID_NAMESPACE_TYPE_ISOLATED = 1,
@@ -19,8 +19,14 @@ enum {
   ANDROID_NAMESPACE_TYPE_SHARED_ISOLATED = ANDROID_NAMESPACE_TYPE_SHARED | ANDROID_NAMESPACE_TYPE_ISOLATED,
 };
 
+/**
+ * @brief Checks if linkernsbypass loaded successfully and is safe to use
+ * @note IMPORTANT: This should be called before any calls to the rest of the library are made
+ * @return true if loading succeeded
+ */
 bool linkernsbypass_load_status();
 
+// https://cs.android.com/android/platform/superproject/+/0a492a4685377d41fef2b12e9af4ebfa6feef9c2:art/libnativeloader/include/nativeloader/dlext_namespaces.h;l=86;bpv=1;bpt=1
 struct android_namespace_t *android_create_namespace(const char *name,
                                                      const char *ld_library_path,
                                                      const char *default_library_path,
@@ -35,19 +41,39 @@ struct android_namespace_t *android_create_namespace_escape(const char *name,
                                                             const char *permitted_when_isolated_path,
                                                             struct android_namespace_t *parent_namespace);
 
+// https://cs.android.com/android/platform/superproject/+/dcb01ef31026b3b8aeb72dada3370af63fe66bbd:bionic/linker/linker.cpp;l=3554
 typedef struct android_namespace_t *(*android_get_exported_namespace_t)(const char *);
 extern android_get_exported_namespace_t android_get_exported_namespace;
 
+// https://cs.android.com/android/platform/superproject/+/dcb01ef31026b3b8aeb72dada3370af63fe66bbd:bionic/linker/linker.cpp;l=2499
 typedef bool (*android_link_namespaces_all_libs_t)(struct android_namespace_t *, struct android_namespace_t *);
 extern android_link_namespaces_all_libs_t android_link_namespaces_all_libs;
 
+// https://cs.android.com/android/platform/superproject/+/dcb01ef31026b3b8aeb72dada3370af63fe66bbd:bionic/linker/linker.cpp;l=2473
 typedef bool (*android_link_namespaces_t)(struct android_namespace_t *, struct android_namespace_t *, const char *);
 extern android_link_namespaces_t android_link_namespaces;
 
+/**
+ * @brief Like android_link_namespaces_all_libs but links from the default namespace
+ */
 bool linkernsbypass_link_namespace_to_default_all_libs(struct android_namespace_t *to);
 
+/**
+ * @brief Loads a library into a namespace
+ * @note IMPORTANT: If `filename` is compiled with the '-z global' linker flag and RTLD_GLOBAL is supplied in `flags` the library will be added to the namespace's LD_PRELOAD list
+ * @param filename The name of the library to load
+ * @param flags The rtld flags for `filename`
+ * @param ns The namespace to dlopen into
+ */
 void *linkernsbypass_namespace_dlopen(const char *filename, int flags, struct android_namespace_t *ns);
 
+/**
+ * @brief Force loads a unique instance of a library into a namespace
+ * @param libPath The path to the library to load with hooks applied
+ * @param libTargetDir A temporary directory to hold the soname patched library at `libPath`, will attempt to use memfd if nullptr
+ * @param flags The rtld flags for `libName`
+ * @param ns The namespace to dlopen into
+ */
 void *linkernsbypass_namespace_dlopen_unique(const char *libPath, const char *libTargetDir, int flags, struct android_namespace_t *ns);
 
 #ifdef __cplusplus

app/src/main/cpp/adrenotools/lib/linkernsbypass/elf_soname_patcher.cpp

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #include <initializer_list>
 #include <cstdint>
 #include <errno.h>
@@ -21,6 +20,7 @@ bool elf_soname_patch(const char *libPath, int targetFd, const char *sonamePatch
     if (ftruncate(targetFd, libStat.st_size) == -1)
         return false;
 
+    // Map the memory so we can read our elf into it
     auto mappedLib{reinterpret_cast<uint8_t *>(mmap(nullptr, libStat.st_size, PROT_READ | PROT_WRITE, MAP_SHARED, targetFd, 0))};
     if (!mappedLib)
         return false;
@@ -29,25 +29,30 @@ bool elf_soname_patch(const char *libPath, int targetFd, const char *sonamePatch
     if (libFd == false)
         return false;
 
+    // Read lib elf into target file
     if (read(libFd, mappedLib, libStat.st_size) != libStat.st_size)
         return false;
 
+    // No longer needed
     close(libFd);
 
     auto eHdr{reinterpret_cast<ElfW(Ehdr) *>(mappedLib)};
     auto sHdrEntries{reinterpret_cast<ElfW(Shdr) *>(mappedLib + eHdr->e_shoff)};
 
+    // Iterate over section headers to find the .dynamic section
     for (ElfW(Half) i{}; i < eHdr->e_shnum; i++) {
         auto &sHdr{sHdrEntries[i]};
         if (sHdr.sh_type == SHT_DYNAMIC) {
             auto strTab{reinterpret_cast<char *>(mappedLib + sHdrEntries[sHdr.sh_link].sh_offset)};
             auto dynHdrEntries{reinterpret_cast<ElfW(Dyn) *>(mappedLib + sHdr.sh_offset)};
 
+            // Iterate over .dynamic entries to find DT_SONAME
             for (ElfW(Xword) k{}; k < (sHdr.sh_size / sHdr.sh_entsize); k++) {
                 auto &dynHdrEntry{dynHdrEntries[k]};
                 if (dynHdrEntry.d_tag == DT_SONAME) {
                     char *soname{strTab + dynHdrEntry.d_un.d_val};
 
+                    // Partially replace the old soname with the soname patch
                     size_t charIdx{};
                     for (; soname[charIdx] != 0 && sonamePatch[charIdx] != 0; charIdx++)
                         soname[charIdx] = sonamePatch[charIdx];

app/src/main/cpp/adrenotools/lib/linkernsbypass/elf_soname_patcher.h

@@ -1,13 +1,19 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @brief  Overwrites a portion of the soname in an elf by loading it into shared memory and modifying .dynstr
+ * @note   IMPORTANT: The supplied soname patch will overwrite the first strlen(sonamePatch) chars of the soname
+ * @param  elfPath Full path to the elf to patch
+ * @param  targetFd FD to use for storing the patched library
+ * @return True on success
+ */
 bool elf_soname_patch(const char *elfPath, int targetFd, const char *newSoname);
 
 #ifdef __cplusplus

app/src/main/cpp/adrenotools/lib/linkernsbypass/meson.build

@@ -11,3 +11,8 @@ linkernsbypass_lib = static_library (
     include_directories: ([linkernsbypass_inc, adrenotools_inc]),
     dependencies: ([libandroid_dep, libdl_dep])
 )
+
+# linkernsbypass_include = static_library('linkernsbypass', sources)
+# target_compile_options(['linkernsbypass', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_libraries(['linkernsbypass', 'android', 'dl'])
+# target_include_directories(['linkernsbypass', 'PUBLIC', '.'])

app/src/main/cpp/adrenotools/meson.build

@@ -33,3 +33,18 @@ adrenotools_lib = shared_library(
 )
 
 subdir('src/hook')
+
+# target_include_directories(['adrenotools', 'PUBLIC', 'include'])
+# target_include_directories(['adrenotools', 'PRIVATE', '.'])
+# target_compile_options(['adrenotools', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_libraries(['adrenotools', 'android', 'linkernsbypass'])
+# hooks_deb = subproject('src/hook')
+# if build_shared_libs
+  # target_link_options(['adrenotools', 'PRIVATE', '-Wl,-s,--exclude-libs,liblinkernsbypass.a'])
+# endif
+# if gen_install_target
+  # configure_file(['adrenotools.pc.in', 'adrenotools.pc', '@ONLY'])
+  # install(['FILES', cmake_binary_dir, '/adrenotools.pc', 'DESTINATION', 'lib/pkgconfig'])
+  # install(['TARGETS', 'adrenotools', 'main_hook', 'file_redirect_hook', 'gsl_alloc_hook', 'hook_impl'])
+  # install(['DIRECTORY', 'include/', 'DESTINATION', 'include', 'FILES_MATCHING', 'PATTERN', '*.h*'])
+# endif

app/src/main/cpp/adrenotools/src/bcenabler.cpp

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #include <fstream>
 #include <string>
 #include <cstring>
@@ -20,6 +19,7 @@ enum adrenotools_bcn_type adrenotools_get_bcn_type(uint32_t major, uint32_t mino
     return ADRENOTOOLS_BCN_PATCH;
 }
 
+// Searches /proc/self/maps for the first free page after the given address
 static void *find_free_page(uintptr_t address) {
     std::ifstream procMaps("/proc/self/maps");
 
@@ -45,48 +45,62 @@ static void *align_ptr(void *ptr) {
 bool adrenotools_patch_bcn(void *vkGetPhysicalDeviceFormatPropertiesFn) {
     union Branch {
         struct {
-            int32_t offset : 26;
-            uint8_t sig : 6;
+            int32_t offset : 26; //!< 26-bit branch offset
+            uint8_t sig : 6;  //!< 6-bit signature (0x25 for linked, 0x5 for jump)
         };
 
         uint32_t raw{};
     };
     static_assert(sizeof(Branch) == 4, "Branch size is invalid");
 
+    // Find the nearest unmapped page where we can place patch code
     void *patchPage{find_free_page(reinterpret_cast<uintptr_t>(vkGetPhysicalDeviceFormatPropertiesFn))};
     if (!patchPage)
         return false;
 
+    // Map patch region
     void *ptr{mmap(patchPage, getpagesize(),  PROT_READ | PROT_WRITE | PROT_EXEC, MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED, 0, 0)};
     if (ptr != patchPage)
         return false;
 
+    // Allow reading from the blob's .text section since some devices enable ---X
+    // Protect two pages just in case we happen to land on a page boundary
     if (mprotect(align_ptr(vkGetPhysicalDeviceFormatPropertiesFn), getpagesize() * 2, PROT_WRITE | PROT_READ | PROT_EXEC))
         return false;
 
+    // First branch in this function is targeted at the function we want to patch
     Branch *blInst{reinterpret_cast<Branch *>(vkGetPhysicalDeviceFormatPropertiesFn)};
 
     constexpr uint8_t BranchLinkSignature{0x25};
 
+    // Search for first instruction with the BL signature
     while (blInst->sig != BranchLinkSignature)
         blInst++;
 
+    // Internal QGL format conversion function that we need to patch
     uint32_t *convFormatFn{reinterpret_cast<uint32_t *>(blInst) + blInst->offset};
 
+    // See mprotect call above
+    // This time we also set PROT_WRITE so we can write our patch to the page
     if (mprotect(align_ptr(convFormatFn), getpagesize() * 2, PROT_WRITE | PROT_READ | PROT_EXEC))
         return false;
 
+    // This would normally set the default result to 0 (error) in the format not found case
     constexpr uint32_t ClearResultSignature{0x2a1f03e0};
 
+    // We replace it with a branch to our own extended if statement which adds in the extra things for BCn
     uint32_t *clearResultPtr{convFormatFn};
     while (*clearResultPtr != ClearResultSignature)
         clearResultPtr++;
 
+    // Ensure we don't write out of bounds
     if (PatchRawData_size > getpagesize())
         return false;
 
+    // Copy the patch function to our mapped page
     memcpy(patchPage, PatchRawData, PatchRawData_size);
 
+    // Fixup the patch code so it correctly returns back to the driver after running
     constexpr uint32_t PatchReturnFixupMagic{0xffffffff};
     constexpr uint8_t BranchSignature{0x5};
 
@@ -116,5 +130,6 @@ bool adrenotools_patch_bcn(void *vkGetPhysicalDeviceFormatPropertiesFn) {
 
     asm volatile("ISB");
 
+    // Done!
     return true;
 }

app/src/main/cpp/adrenotools/src/bcenabler_patch.s

@@ -80,4 +80,4 @@
 .L18:
         mov     w0, 0
 .L3:
-        .word   0xffffffff
+        .word   0xffffffff  // Branch fixup

app/src/main/cpp/adrenotools/src/driver.cpp

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #include <string>
 #include <string_view>
 #include <sys/stat.h>
@@ -18,14 +17,17 @@
 #include <unistd.h>
 
 void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *tmpLibDir, const char *hookLibDir, const char *customDriverDir, const char *customDriverName, const char *fileRedirectDir, void **userMappingHandle) {
+    // Bail out if linkernsbypass failed to load, this probably means we're on api < 28
     if (!linkernsbypass_load_status()) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "Could not load linkernsbypass\n");
         return nullptr;
     }    
 
+    // Use memfd on Q+ since it's guaranteed to work, but only if tmpLibDir wasn't set
     if (android_get_device_api_level() >= 29 && !tmpLibDir)
         tmpLibDir = nullptr;
 
+    // Verify that params for specific features are only passed if they are enabled
     if (!(featureFlags & ADRENOTOOLS_DRIVER_FILE_REDIRECT) && fileRedirectDir) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "ADRENOTOOLS_DRIVER_FILE_REDIRECT present but no file redirect folder found\n");
         return nullptr;
@@ -41,6 +43,7 @@ void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *
         return nullptr;
     }   
 
+    // Verify that params for enabled features are correct
     struct stat buf{};
 
     if (featureFlags & ADRENOTOOLS_DRIVER_CUSTOM) {
@@ -55,6 +58,7 @@ void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *
          }   
     }
 
+    // Verify that params for enabled features are correct
     if (featureFlags & ADRENOTOOLS_DRIVER_FILE_REDIRECT) {
         if (!fileRedirectDir) {
             __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "ADRENOTOOLS_DRIVER_REDIRECT_DIR present but no folder parameter was found\n");
@@ -67,18 +71,22 @@ void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *
          }   
     }
 
+    // Create a namespace that can isolate our hook from the classloader namespace
     auto hookNs{android_create_namespace("adrenotools-libvulkan", hookLibDir, nullptr, ANDROID_NAMESPACE_TYPE_SHARED, nullptr, nullptr)};
 
+    // Link it to the default namespace so the hook can use libandroid etc
     if (!linkernsbypass_link_namespace_to_default_all_libs(hookNs)) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "Failed to hook our namespace to the default one\n");
         return nullptr;
      }
+    // Preload the hook implementation, otherwise we get a weird issue where despite being in NEEDED of the hook lib the hook's symbols will overwrite ours and cause an infinite loop
     auto hookImpl{linkernsbypass_namespace_dlopen("libhook_impl.so", RTLD_NOW, hookNs)};
     if (!hookImpl) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "Couldn't preload the hook implementation\n");
         return nullptr;
     }    
 
+    // Pass parameters to the hook implementation
     auto initHookParam{reinterpret_cast<void (*)(const void *)>(dlsym(hookImpl, "init_hook_param"))};
     if (!initHookParam) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "Couldn't init hook params\n");
@@ -87,6 +95,7 @@ void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *
 
     auto importMapping{[&]() -> adrenotools_gpu_mapping * {
         if (featureFlags & ADRENOTOOLS_DRIVER_GPU_MAPPING_IMPORT) {
+            // This will be leaked, but it's not a big deal since it's only a few bytes
             adrenotools_gpu_mapping *mapping{new adrenotools_gpu_mapping{}};
             *userMappingHandle = mapping;
             return mapping;
@@ -98,6 +107,7 @@ void *adrenotools_open_libvulkan(int dlopenFlags, int featureFlags, const char *
 
     initHookParam(new HookImplParams(featureFlags, tmpLibDir, hookLibDir, customDriverDir, customDriverName, fileRedirectDir, importMapping));
 
+    // Load the libvulkan hook into the isolated namespace
     if (!linkernsbypass_namespace_dlopen("libmain_hook.so", RTLD_GLOBAL, hookNs)) {
         __android_log_print( ANDROID_LOG_ERROR, "adrenotools", "Failed to load libvulkan into the isolated namespace\n");
         return nullptr;
@@ -140,7 +150,7 @@ bool adrenotools_import_user_mem(void *handle, void *hostPtr, uint64_t size) {
     importMapping->host_ptr = hostPtr;
     importMapping->gpu_addr = info.gpuaddr;
     importMapping->size = size;
-    importMapping->flags = 0xc2600;
+    importMapping->flags = 0xc2600; //!< Unknown flags, but they are required for the mapping to work
 
     close(kgslFd);
     return true;
@@ -179,7 +189,7 @@ bool adrenotools_mem_gpu_allocate(void *handle, uint64_t *size) {
     mapping->host_ptr = nullptr;
     mapping->gpu_addr = info.gpuaddr;
     mapping->size = *size;
-    mapping->flags = 0xc2600;
+    mapping->flags = 0xc2600; //!< Unknown flags, but they are required for the mapping to work
 
     close(kgslFd);
     return true;

app/src/main/cpp/adrenotools/src/hook/hook_impl.cpp

@@ -15,7 +15,7 @@
 #define TAG "hook_impl"
 #define LOGI(fmt, ...) __android_log_print(ANDROID_LOG_INFO, TAG, fmt, ##__VA_ARGS__)
 
-const HookImplParams *hook_params;
+const HookImplParams *hook_params; //!< Bunch of info needed to load/patch the driver
 int (*gsl_memory_alloc_pure_sym)(uint32_t, uint32_t, void *);
 int (*gsl_memory_alloc_pure_64_sym)(uint64_t, uint32_t, void *);
 int (*gsl_memory_free_pure_sym)(void *);
@@ -43,6 +43,7 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
 
     LOGI("hook_android_dlopen_ext: filename: %s", filename);
 
+    // Ignore non-vulkan libraries
     if (!strstr(filename, "vulkan."))
         return android_dlopen_ext(filename, flags, extinfo);
 
@@ -51,6 +52,7 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
         return fallback();
     }
 
+    // customDriverDir will be empty if ADRENOTOOLS_DRIVER_CUSTOM isn't set therefore it's fine to have either way
     auto driverNs{android_create_namespace(filename, hook_params->customDriverDir.c_str(),
                                            hook_params->hookLibDir.c_str(), ANDROID_NAMESPACE_TYPE_SHARED,
                                            nullptr, extinfo->library_namespace)};
@@ -59,12 +61,16 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
         return fallback();
     }
 
+    // We depend on libandroid which is unlikely to be in the supplied driver namespace so we have to link it over
     android_link_namespaces(driverNs, nullptr, "libandroid.so");
 
+    // Preload ourself, a new instance will be created since we have different linker ancestory
+    // If we don't preload we get a weird issue where despite being in NEEDED of the hook lib the hook's symbols will overwrite ours and cause an infinite loop
     auto hookImpl{linkernsbypass_namespace_dlopen("libhook_impl.so", RTLD_NOW, driverNs)};
     if (!hookImpl)
         return nullptr;
 
+    // Pass parameters to ourself
     auto initHookParam{reinterpret_cast<void (*)(const void *)>(dlsym(hookImpl, "init_hook_param"))};
     if (!initHookParam)
         return nullptr;
@@ -80,6 +86,7 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
         LOGI("hook_android_dlopen_ext: applied libfile_redirect_hook");
     }
 
+    // Use our new namespace to load the vulkan driver
     auto newExtinfo{*extinfo};
     newExtinfo.library_namespace = driverNs;
 
@@ -115,6 +122,8 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
             LOGI("hook_android_dlopen_ext: hook failed: failed to apply libgsl_alloc_hook!");
     }
 
+    // TODO: If there is already an instance of a Vulkan driver loaded hooks won't be applied, this will only be the case for skiavk generally
+    // To fix this we would need to search /proc/self/maps for the file to a loaded instance of the library in order to read it to patch the soname and load it uniquely
     if (hook_params->featureFlags & ADRENOTOOLS_DRIVER_CUSTOM) {
         LOGI("hook_android_dlopen_ext: loading custom driver: %s%s", hook_params->customDriverDir.c_str(), hook_params->customDriverName.c_str());
         void *handle{android_dlopen_ext(hook_params->customDriverName.c_str(), flags, &newExtinfo)};
@@ -133,6 +142,7 @@ __attribute__((visibility("default"))) void *hook_android_dlopen_ext(const char
 __attribute__((visibility("default"))) void *hook_android_load_sphal_library(const char *filename, int flags) {
     LOGI("hook_android_load_sphal_library: filename: %s", filename);
 
+    // https://android.googlesource.com/platform/system/core/+/master/libvndksupport/linker.cpp
     for (const char *name : {"sphal", "vendor", "default"}) {
         if (auto vendorNs{android_get_exported_namespace(name)}) {
             android_dlextinfo dlextinfo{

app/src/main/cpp/adrenotools/src/hook/hook_impl.h

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #ifdef __cplusplus

app/src/main/cpp/adrenotools/src/hook/hook_impl_params.h

@@ -1,12 +1,15 @@
 // SPDX-License-Identifier: BSD-2-Clause
 // Copyright © 2021 Billy Laws
 
-
 #pragma once
 
 #include <string>
 #include <adrenotools/priv.h>
 
+/**
+ * @brief Holds the parameters needed for all hooks
+ * @note See comments for adrenotools_open_libvulkan as a reference for member variables
+ */
 struct HookImplParams {
     int featureFlags;
     std::string tmpLibDir;

app/src/main/cpp/adrenotools/src/hook/meson.build

@@ -1,12 +1,32 @@
 hook_impl_files = files(['hook_impl.cpp', 'hook_impl.h', 'hook_impl_params.h'])
 hook_impl_inc = include_directories('../../include')
 
+# hook_impl_lib = shared_library('hook_impl', 'hook_impl.cpp', 'hook_impl.h', 'hook_impl_params.h')
+# target_compile_options(['hook_impl', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_libraries(['hook_impl', 'linkernsbypass', 'log'])
+# target_include_directories(['hook_impl', 'PRIVATE', '../../include'])
+# set_target_properties(['hook_impl', 'PROPERTIES', 'CXX_VISIBILITY_PRESET', 'hidden'])
 
 main_hook_files = files(['main_hook.c'])
+# main_hook_lib = shared_library('main_hook', 'main_hook.c')
+# target_compile_options(['main_hook', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_options(['main_hook', 'PRIVATE', '-z', 'global'])
+# target_link_libraries(['main_hook', 'hook_impl'])
+# set_target_properties(['main_hook', 'PROPERTIES', 'CXX_VISIBILITY_PRESET', 'hidden'])
 
 file_redirect_hook_files = files(['file_redirect_hook.c'])
+# file_redirect_hook_lib = shared_library('file_redirect_hook', 'file_redirect_hook.c')
+# target_compile_options(['file_redirect_hook', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_options(['file_redirect_hook', 'PRIVATE', '-z', 'global'])
+# target_link_libraries(['file_redirect_hook', 'hook_impl'])
+# set_target_properties(['file_redirect_hook', 'PROPERTIES', 'CXX_VISIBILITY_PRESET', 'hidden'])
 
 gsl_alloc_hook_files = files(['gsl_alloc_hook.c'])
+# gsl_alloc_hook_lib = shared_library('gsl_alloc_hook', 'gsl_alloc_hook.c')
+# target_compile_options(['gsl_alloc_hook', 'PRIVATE', '-Wall', '-Wextra'])
+# target_link_options(['gsl_alloc_hook', 'PRIVATE', '-z', 'global'])
+# target_link_libraries(['gsl_alloc_hook', 'hook_impl'])
+# set_target_properties(['gsl_alloc_hook', 'PROPERTIES', 'CXX_VISIBILITY_PRESET', 'hidden'])
 
 hook_impl_lib = shared_library(
     'hook_impl',

app/src/main/cpp/adrenotools/tools/acc-shim/vk_acc_shim.cpp

@@ -5,6 +5,7 @@
 
 thread_local int satisfy_driver_emutls;
 
+// Check libllvm-glnext.so in older drivers for a full list of these, newer ones are slightly more awkward due to the split
 enum class OptionType : uint32_t {
     ArgsStringList = 1,
     QcArgsString = 4,
@@ -20,6 +21,7 @@ struct StringListVal {
 struct Option
 {
     OptionType type;
+    // PAD
     union {
         bool boolVal;
         int intVal;
@@ -47,6 +49,7 @@ int CompileHook(void *state, OptionsSet *opts) {
     Option replacementOpts[ReplacementOptsNum];
     uint32_t patchedOptNum{};
 
+    // Insert your desired args here - results will be written to stderr
     const char *argv[] = {"-help", "-help-hidden", "", NULL };
     StringListVal listVal{
         .len = 3,
@@ -80,6 +83,7 @@ int CompileHook(void *state, OptionsSet *opts) {
 
 struct LlvmInterface {
   uint32_t unk0[3];
+  // PAD
   void *makeContext;
   void *delContext;
   decltype(CompileHook) *compile;

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/QtiGrallocDefs.h

@@ -30,31 +30,53 @@
 #ifndef __QTIGRALLOCDEFS_H__
 #define __QTIGRALLOCDEFS_H__
 
+// From gralloc_priv.h
 
+/* Gralloc usage bits indicating the type of allocation that should be used */
+/* Refer to BufferUsage in hardware/interfaces/graphics/common/<ver>/types.hal */
 
+/* The bits below are in officially defined vendor space
+ * i.e bits 28-31 and 48-63*/
+/* Non linear, Universal Bandwidth Compression */
 #define GRALLOC_USAGE_PRIVATE_ALLOC_UBWC (UINT32_C(1) << 28)
 
+/* Set this for allocating uncached memory (using O_DSYNC),
+ * cannot be used with noncontiguous heaps */
 #define GRALLOC_USAGE_PRIVATE_UNCACHED (UINT32_C(1) << 29)
 
+/* This flag is used to indicate 10 bit format.
+ * When both GRALLOC_USAGE_PRIVATE_ALLOC_UBWC & GRALLOC_USAGE_PRIVATE_10BIT
+ * are set then it will indicate UBWC_TP10 format.
+ * When only GRALLOC_USAGE_PRIVATE_10BIT is set it will indicate linear P010 format.
+ */
 #define GRALLOC_USAGE_PRIVATE_10BIT (UINT32_C(1) << 30)
 
+/* This flag is used for SECURE display usecase */
 #define GRALLOC_USAGE_PRIVATE_SECURE_DISPLAY (UINT32_C(1) << 31)
 
+/* This flag is used to indicate video NV21 format */
 #define GRALLOC_USAGE_PRIVATE_VIDEO_NV21_ENCODER 1ULL << 48
 
+/* unused legacy flags */
 #define GRALLOC_USAGE_PRIVATE_MM_HEAP 0
 #define GRALLOC_USAGE_PRIVATE_IOMMU_HEAP 0
 
+/* This flag is set for WFD usecase */
 #define GRALLOC_USAGE_PRIVATE_WFD 1ULL << 51
 
+/* This flag is set for HEIF usecase */
 #define GRALLOC_USAGE_PRIVATE_HEIF (UINT32_C(1) << 27)
 
+/* TODO(user): Remove when clients stop referencing this flag */
 #define GRALLOC_USAGE_PRIVATE_10BIT_TP 0
 
+/* This flag indicates PI format is being used */
 #define GRALLOC_USAGE_PRIVATE_ALLOC_UBWC_PI 1ULL << 49
 
+/* This flag is set while CDSP accesses the buffer */
 #define GRALLOC_USAGE_PRIVATE_CDSP 1ULL << 50
 
+// OEM specific HAL formats
 #define HAL_PIXEL_FORMAT_RGBA_5551 6
 #define HAL_PIXEL_FORMAT_RGBA_4444 7
 #define HAL_PIXEL_FORMAT_NV12_ENCODEABLE 0x102
@@ -76,6 +98,7 @@
 #define HAL_PIXEL_FORMAT_RAW8 0x123
 #define HAL_PIXEL_FORMAT_NV12_HEIF 0x116
 
+// 10 bit
 #define HAL_PIXEL_FORMAT_ARGB_2101010 0x117
 #define HAL_PIXEL_FORMAT_RGBX_1010102 0x118
 #define HAL_PIXEL_FORMAT_XRGB_2101010 0x119
@@ -83,7 +106,7 @@
 #define HAL_PIXEL_FORMAT_ABGR_2101010 0x11B
 #define HAL_PIXEL_FORMAT_BGRX_1010102 0x11C
 #define HAL_PIXEL_FORMAT_XBGR_2101010 0x11D
-#define HAL_PIXEL_FORMAT_YCbCr_420_P010 0x36
+#define HAL_PIXEL_FORMAT_YCbCr_420_P010 0x36  // HAL_PIXEL_FORMAT_YCBCR_P010
 #define HAL_PIXEL_FORMAT_YCbCr_420_P010_UBWC 0x124
 #define HAL_PIXEL_FORMAT_YCbCr_420_P010_VENUS 0x7FA30C0A
 
@@ -92,6 +115,7 @@
 
 #define HAL_PIXEL_FORMAT_INTERLACE 0x180
 
+// Camera utils format
 #define HAL_PIXEL_FORMAT_NV12_LINEAR_FLEX 0x125
 #define HAL_PIXEL_FORMAT_NV12_UBWC_FLEX 0x126
 #define HAL_PIXEL_FORMAT_MULTIPLANAR_FLEX 0x127
@@ -99,16 +123,22 @@
 #define HAL_PIXEL_FORMAT_NV12_UBWC_FLEX_4_BATCH 0x129
 #define HAL_PIXEL_FORMAT_NV12_UBWC_FLEX_8_BATCH 0x130
 
+// FSC Formats
 #define HAL_PIXEL_FORMAT_RGB888_UBWC_FSC 0x131
 #define HAL_PIXEL_FORMAT_RGB101010_UBWC_FSC 0x132
 
+// v4l2_fourcc('Y', 'U', 'Y', 'L'). 24 bpp YUYV 4:2:2 10 bit per component
 #define HAL_PIXEL_FORMAT_YCbCr_422_I_10BIT 0x4C595559
 
+// v4l2_fourcc('Y', 'B', 'W', 'C'). 10 bit per component. This compressed
+// format reduces the memory access bandwidth
 #define HAL_PIXEL_FORMAT_YCbCr_422_I_10BIT_COMPRESSED 0x43574259
 
+// UBWC aligned Venus format
 #define HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS_UBWC 0x7FA30C06
 #define HAL_PIXEL_FORMAT_YCbCr_420_TP10_UBWC 0x7FA30C09
 
+// Khronos ASTC formats
 #define HAL_PIXEL_FORMAT_COMPRESSED_RGBA_ASTC_4x4_KHR 0x93B0
 #define HAL_PIXEL_FORMAT_COMPRESSED_RGBA_ASTC_5x4_KHR 0x93B1
 #define HAL_PIXEL_FORMAT_COMPRESSED_RGBA_ASTC_5x5_KHR 0x93B2
@@ -140,4 +170,4 @@
 
 enum { BUFFER_TYPE_UI = 0, BUFFER_TYPE_VIDEO };
 
-#endif
+#endif  //__QTIGRALLOCDEFS_H__

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/common.h

@@ -26,6 +26,7 @@
 using namespace android::hardware;
 using namespace android;
 
+/* Simplified version of hidl::base::V1_0::IBase */
 struct IBase : virtual public RefBase {
   virtual bool isRemote() const;
 

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gr_adreno_info.cpp

@@ -80,6 +80,8 @@ AdrenoMemInfo::AdrenoMemInfo() {
     ALOGE(" Failed to load libadreno_utils.so");
   }
 
+  // Check if the overriding property debug.gralloc.gfx_ubwc_disable
+  // that disables UBWC allocations for the graphics stack is set
   char property[PROPERTY_VALUE_MAX];
   property_get(DISABLE_UBWC_PROP, property, "0");
   if (!(strncmp(property, "1", PROPERTY_VALUE_MAX)) ||
@@ -121,13 +123,16 @@ void AdrenoMemInfo::AlignUnCompressedRGB(int width, int height, int format, int
       break;
   }
 
-  int raster_mode = 0;
-  int padding_threshold = 512;
-
-
+  int raster_mode = 0;          // Adreno unknown raster mode.
+  int padding_threshold = 512;  // Threshold for padding surfaces.
+  // the function below computes aligned width and aligned height
+  // based on linear or macro tile mode selected.
   if (LINK_adreno_compute_fmt_aligned_width_and_height) {
+    // We call into adreno_utils only for RGB formats. So plane_id is 0 and
+    // num_samples is 1 always. We may  have to add uitility function to
+    // find out these if there is a need to call this API for YUV formats.
     LINK_adreno_compute_fmt_aligned_width_and_height(
-        width, height, 0  , GetGpuPixelFormat(format), 1  , tile_enabled,
+        width, height, 0 /*plane_id*/, GetGpuPixelFormat(format), 1 /*num_samples*/, tile_enabled,
         raster_mode, padding_threshold, reinterpret_cast<int*>(aligned_w),
         reinterpret_cast<int*>(aligned_h));
   } else if (LINK_adreno_compute_aligned_width_and_height) {
@@ -135,7 +140,7 @@ void AdrenoMemInfo::AlignUnCompressedRGB(int width, int height, int format, int
         width, height, bpp, tile_enabled, raster_mode, padding_threshold,
         reinterpret_cast<int*>(aligned_w), reinterpret_cast<int*>(aligned_h));
   } else if (LINK_adreno_compute_padding) {
-    int surface_tile_height = 1;
+    int surface_tile_height = 1;  // Linear surface
     *aligned_w = UINT(LINK_adreno_compute_padding(width, bpp, surface_tile_height, raster_mode,
                                                   padding_threshold));
     ALOGW("%s: Warning!! Old GFX API is used to calculate stride", __FUNCTION__);
@@ -152,9 +157,9 @@ void AdrenoMemInfo::AlignCompressedRGB(int width, int height, int format, unsign
                                        unsigned int* aligned_h) {
   if (LINK_adreno_compute_compressedfmt_aligned_width_and_height) {
     int bytesPerPixel = 0;
-    int raster_mode = 0;
-    int padding_threshold = 512;
-
+    int raster_mode = 0;          // Adreno unknown raster mode.
+    int padding_threshold = 512;  // Threshold for padding
+    // surfaces.
 
     LINK_adreno_compute_compressedfmt_aligned_width_and_height(
         width, height, format, 0, raster_mode, padding_threshold, reinterpret_cast<int*>(aligned_w),
@@ -336,4 +341,4 @@ bool AdrenoMemInfo::IsPISupportedByGPU(int format, uint64_t usage) {
   return false;
 }
 
-}
+}  // namespace gralloc

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gr_adreno_info.h

@@ -35,10 +35,11 @@
 
 namespace gralloc {
 
+// Adreno Pixel Formats
 typedef enum {
   ADRENO_PIXELFORMAT_UNKNOWN = 0,
   ADRENO_PIXELFORMAT_R16G16B16A16_FLOAT = 10,
-  ADRENO_PIXELFORMAT_R10G10B10A2_UNORM = 24,
+  ADRENO_PIXELFORMAT_R10G10B10A2_UNORM = 24,  // Vertex, Normalized GL_UNSIGNED_INT_10_10_10_2_OES
   ADRENO_PIXELFORMAT_R8G8B8A8 = 28,
   ADRENO_PIXELFORMAT_R8G8B8A8_SRGB = 29,
   ADRENO_PIXELFORMAT_D32_FLOAT = 40,
@@ -54,87 +55,140 @@ typedef enum {
   ADRENO_PIXELFORMAT_P010 = 104,
   ADRENO_PIXELFORMAT_YUY2 = 107,
   ADRENO_PIXELFORMAT_B4G4R4A4 = 115,
-  ADRENO_PIXELFORMAT_NV12_EXT = 506,
-  ADRENO_PIXELFORMAT_R8G8B8X8 = 507,
-  ADRENO_PIXELFORMAT_R8G8B8 = 508,
-  ADRENO_PIXELFORMAT_A1B5G5R5 = 519,
-  ADRENO_PIXELFORMAT_R8G8B8X8_SRGB = 520,
-  ADRENO_PIXELFORMAT_R8G8B8_SRGB = 521,
+  ADRENO_PIXELFORMAT_NV12_EXT = 506,       // NV12 with non-std alignment and offsets
+  ADRENO_PIXELFORMAT_R8G8B8X8 = 507,       //  GL_RGB8 (Internal)
+  ADRENO_PIXELFORMAT_R8G8B8 = 508,         //  GL_RGB8
+  ADRENO_PIXELFORMAT_A1B5G5R5 = 519,       //  GL_RGB5_A1
+  ADRENO_PIXELFORMAT_R8G8B8X8_SRGB = 520,  //  GL_SRGB8
+  ADRENO_PIXELFORMAT_R8G8B8_SRGB = 521,    //  GL_SRGB8
   ADRENO_PIXELFORMAT_A2B10G10R10_UNORM = 532,
+  // Vertex, Normalized GL_UNSIGNED_INT_10_10_10_2_OES
   ADRENO_PIXELFORMAT_R10G10B10X2_UNORM = 537,
   ADRENO_PIXELFORMAT_D24_UNORM_X8_UINT = 548,
   ADRENO_PIXELFORMAT_D24_UNORM = 549,
   ADRENO_PIXELFORMAT_D32_FLOAT_X24S8_UINT = 551,
   ADRENO_PIXELFORMAT_S8_UINT = 552,
-  ADRENO_PIXELFORMAT_ASTC_4X4 = 568,
-  ADRENO_PIXELFORMAT_ASTC_5X4 = 569,
-  ADRENO_PIXELFORMAT_ASTC_5X5 = 570,
-  ADRENO_PIXELFORMAT_ASTC_6X5 = 571,
-  ADRENO_PIXELFORMAT_ASTC_6X6 = 572,
-  ADRENO_PIXELFORMAT_ASTC_8X5 = 573,
-  ADRENO_PIXELFORMAT_ASTC_8X6 = 574,
-  ADRENO_PIXELFORMAT_ASTC_8X8 = 575,
-  ADRENO_PIXELFORMAT_ASTC_10X5 = 576,
-  ADRENO_PIXELFORMAT_ASTC_10X6 = 577,
-  ADRENO_PIXELFORMAT_ASTC_10X8 = 578,
-  ADRENO_PIXELFORMAT_ASTC_10X10 = 579,
-  ADRENO_PIXELFORMAT_ASTC_12X10 = 580,
-  ADRENO_PIXELFORMAT_ASTC_12X12 = 581,
-  ADRENO_PIXELFORMAT_ASTC_4X4_SRGB = 582,
-  ADRENO_PIXELFORMAT_ASTC_5X4_SRGB = 583,
-  ADRENO_PIXELFORMAT_ASTC_5X5_SRGB = 584,
-  ADRENO_PIXELFORMAT_ASTC_6X5_SRGB = 585,
-  ADRENO_PIXELFORMAT_ASTC_6X6_SRGB = 586,
-  ADRENO_PIXELFORMAT_ASTC_8X5_SRGB = 587,
-  ADRENO_PIXELFORMAT_ASTC_8X6_SRGB = 588,
-  ADRENO_PIXELFORMAT_ASTC_8X8_SRGB = 589,
-  ADRENO_PIXELFORMAT_ASTC_10X5_SRGB = 590,
-  ADRENO_PIXELFORMAT_ASTC_10X6_SRGB = 591,
-  ADRENO_PIXELFORMAT_ASTC_10X8_SRGB = 592,
-  ADRENO_PIXELFORMAT_ASTC_10X10_SRGB = 593,
-  ADRENO_PIXELFORMAT_ASTC_12X10_SRGB = 594,
-  ADRENO_PIXELFORMAT_ASTC_12X12_SRGB = 595,
-
-  ADRENO_PIXELFORMAT_R5G6B5 = 610,
-  ADRENO_PIXELFORMAT_R5G5B5A1 = 611,
-  ADRENO_PIXELFORMAT_R4G4B4A4 = 612,
-  ADRENO_PIXELFORMAT_UYVY = 614,
+  ADRENO_PIXELFORMAT_ASTC_4X4 = 568,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_5X4 = 569,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_5X5 = 570,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_6X5 = 571,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_6X6 = 572,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X5 = 573,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X6 = 574,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X8 = 575,         // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X5 = 576,        // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X6 = 577,        // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X8 = 578,        // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X10 = 579,       // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_12X10 = 580,       // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_12X12 = 581,       // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_4X4_SRGB = 582,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_5X4_SRGB = 583,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_5X5_SRGB = 584,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_6X5_SRGB = 585,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_6X6_SRGB = 586,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X5_SRGB = 587,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X6_SRGB = 588,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_8X8_SRGB = 589,    // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X5_SRGB = 590,   // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X6_SRGB = 591,   // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X8_SRGB = 592,   // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_10X10_SRGB = 593,  // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_12X10_SRGB = 594,  // ASTC Compressed
+  ADRENO_PIXELFORMAT_ASTC_12X12_SRGB = 595,  // ASTC Compressed
+  // Vertex, Normalized GL_UNSIGNED_INT_10_10_10_2_OES
+  ADRENO_PIXELFORMAT_R5G6B5 = 610,    //  RGBA version of B5G6R5
+  ADRENO_PIXELFORMAT_R5G5B5A1 = 611,  //  RGBA version of B5G5R5A1
+  ADRENO_PIXELFORMAT_R4G4B4A4 = 612,  //  RGBA version of B4G4R4A4
+  ADRENO_PIXELFORMAT_UYVY = 614,      //  YUV 4:2:2 packed progressive (1 plane)
   ADRENO_PIXELFORMAT_NV21 = 619,
-  ADRENO_PIXELFORMAT_Y8U8V8A8 = 620,
-  ADRENO_PIXELFORMAT_Y8 = 625,
-  ADRENO_PIXELFORMAT_TP10 = 654,
+  ADRENO_PIXELFORMAT_Y8U8V8A8 = 620,  // YUV 4:4:4 packed (1 plane)
+  ADRENO_PIXELFORMAT_Y8 = 625,        //  Single 8-bit luma only channel YUV format
+  ADRENO_PIXELFORMAT_TP10 = 654,      // YUV 4:2:0 planar 10 bits/comp (2 planes)
 } ADRENOPIXELFORMAT;
 
 typedef enum {
-  SURFACE_TILE_MODE_DISABLE = 0x0,
-  SURFACE_TILE_MODE_ENABLE = 0x1
+  SURFACE_TILE_MODE_DISABLE = 0x0,  // used for linear surface
+  SURFACE_TILE_MODE_ENABLE = 0x1    // used for tiled surface
 } surface_tile_mode_t;
 
 class AdrenoMemInfo {
  public:
+  /*
+   * Function to compute aligned width and aligned height based on
+   * width, height, format and usage flags.
+   *
+   * @return aligned width, aligned height
+   */
   void GetAlignedWidthAndHeight(int width, int height, int format, int usage,
                                 unsigned int* aligned_w, unsigned int* aligned_h, bool ubwc_enabled,
                                 bool tile_enabled);
 
+  /*
+   * Function to compute the adreno aligned width and aligned height
+   * based on the width and format.
+   *
+   * @return aligned width, aligned height
+   */
   void AlignUnCompressedRGB(int width, int height, int format, int tileEnabled,
                             unsigned int* aligned_w, unsigned int* aligned_h);
 
+  /*
+   * Function to compute the adreno aligned width and aligned height
+   * based on the width and format.
+   *
+   * @return aligned width, aligned height
+   */
   void AlignCompressedRGB(int width, int height, int format, unsigned int* aligned_w,
                           unsigned int* aligned_h);
 
+  /*
+   * Function to compute the pixel alignment requirement.
+   *
+   * @return alignment
+   */
   uint32_t GetGpuPixelAlignment();
 
+  /*
+   * Function to query whether GPU supports UBWC for given HAL format
+   * @return > 0 : supported
+   *           0 : not supported
+   */
   bool IsUBWCSupportedByGPU(int format);
 
+  /*
+   * Function to check if GPU supports PI or not
+   */
   bool IsPISupportedByGPU(int format, uint64_t usage);
+  /*
+   * Function to get the corresponding Adreno format for given HAL format
+   */
   ADRENOPIXELFORMAT GetGpuPixelFormat(int hal_format);
 
+  /*
+   * Function to get graphics metadata blob size
+   * @return graphics metadata size
+   */
   uint32_t AdrenoGetMetadataBlobSize();
 
+  /*
+   * Function to populate the graphics metadata blob
+   * @return 1 : Successful
+   *         2 : Unsuccessful
+   */
   int AdrenoInitMemoryLayout(void* metadata_blob, int width, int height, int depth, int format,
                              int num_samples, int isUBWC, uint64_t usage, uint32_t num_planes);
+  /*
+   * Function to get buffer size for based on graphcis metadata
+   * @return buffer size
+   */
   uint32_t AdrenoGetAlignedGpuBufferSize(void* metadata_blob);
 
+  /*
+   * Function to check if adreno size calculation APIs are avaliable
+   * @return true  : Avaliable
+   *         false : Unavaliable
+   */
   bool AdrenoSizeAPIAvaliable();
 
   static AdrenoMemInfo* GetInstance();
@@ -142,6 +196,7 @@ class AdrenoMemInfo {
  private:
   AdrenoMemInfo();
   ~AdrenoMemInfo();
+  // link(s)to adreno surface padding library.
   int (*LINK_adreno_compute_padding)(int width, int bpp, int surface_tile_height,
                                      int screen_tile_height, int padding_threshold) = NULL;
   void (*LINK_adreno_compute_aligned_width_and_height)(int width, int height, int bpp,
@@ -174,6 +229,6 @@ class AdrenoMemInfo {
   static AdrenoMemInfo* s_instance;
 };
 
-}
+}  // namespace gralloc
 
-#endif
+#endif  // __GR_ADRENO_INFO_H__

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gr_priv_handle.h

@@ -57,27 +57,29 @@ struct private_handle_t {
     PRIV_FLAGS_CAMERA_READ = 0x00040000,
     PRIV_FLAGS_HW_COMPOSER = 0x00080000,
     PRIV_FLAGS_HW_TEXTURE = 0x00100000,
-    PRIV_FLAGS_ITU_R_601 = 0x00200000,
-    PRIV_FLAGS_ITU_R_601_FR = 0x00400000,
-    PRIV_FLAGS_ITU_R_709 = 0x00800000,
+    PRIV_FLAGS_ITU_R_601 = 0x00200000,     // Unused from display
+    PRIV_FLAGS_ITU_R_601_FR = 0x00400000,  // Unused from display
+    PRIV_FLAGS_ITU_R_709 = 0x00800000,     // Unused from display
     PRIV_FLAGS_SECURE_DISPLAY = 0x01000000,
     PRIV_FLAGS_TILE_RENDERED = 0x02000000,
     PRIV_FLAGS_CPU_RENDERED = 0x04000000,
     PRIV_FLAGS_UBWC_ALIGNED = 0x08000000,
     PRIV_FLAGS_DISP_CONSUMER = 0x10000000,
-    PRIV_FLAGS_CLIENT_ALLOCATED = 0x20000000,
-    PRIV_FLAGS_UBWC_ALIGNED_PI = 0x40000000,
+    PRIV_FLAGS_CLIENT_ALLOCATED = 0x20000000,  // Ion buffer allocated outside of gralloc
+    PRIV_FLAGS_UBWC_ALIGNED_PI = 0x40000000,   // PI format
   };
 
+  // file-descriptors dup'd over IPC
   int fd;
   int fd_metadata;
 
+  // values sent over IPC
   int magic;
   int flags;
-  int width;
-  int height;
-  int unaligned_width;
-  int unaligned_height;
+  int width;             // holds width of the actual buffer allocated
+  int height;            // holds height of the  actual buffer allocated
+  int unaligned_width;   // holds width client asked to allocate
+  int unaligned_height;  // holds height client asked to allocate
   int format;
   int buffer_type;
   unsigned int layer_count;
@@ -124,6 +126,7 @@ struct private_handle_t {
     numFds = kNumFds;
   }
 
+  // Legacy constructor used by some clients
   private_handle_t(int fd, unsigned int size, int usage, int buf_type, int format, int w, int h)
       : private_handle_t(fd, -1, PRIV_FLAGS_CLIENT_ALLOCATED, w, h, 0, 0, format, buf_type, size,
                          static_cast<uint64_t>(usage)) {}
@@ -173,6 +176,7 @@ struct private_handle_t {
   unsigned int GetLayerCount() const { return layer_count; }
 
   int GetStride() const {
+    // In handle we currently store aligned width after allocation.
     return width;
   }
 
@@ -183,4 +187,4 @@ struct private_handle_t {
 };
 #pragma pack(pop)
 
-#endif
+#endif  // __GR_PRIV_HANDLE_H__

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gr_utils.cpp

@@ -162,6 +162,7 @@ bool CpuCanRead(uint64_t usage) {
 
 bool CpuCanWrite(uint64_t usage) {
   if (usage & BufferUsage::CPU_WRITE_MASK) {
+    // Application intends to use CPU for rendering
     return true;
   }
 
@@ -176,6 +177,7 @@ uint32_t GetDataAlignment(int format, uint64_t usage) {
 
   if (usage & BufferUsage::PROTECTED) {
     if ((usage & BufferUsage::CAMERA_OUTPUT) || (usage & GRALLOC_USAGE_PRIVATE_SECURE_DISPLAY)) {
+      // The alignment here reflects qsee mmu V7L/V8L requirement
       align = SZ_2M;
     } else {
       align = SECURE_ALIGN;
@@ -200,6 +202,7 @@ bool IsGPUFlagSupported(uint64_t usage) {
   return ret;
 }
 
+// Returns the final buffer size meant to be allocated with ion
 unsigned int GetSize(const BufferInfo& info, unsigned int alignedw, unsigned int alignedh) {
   unsigned int size = 0;
   int format = info.format;
@@ -220,6 +223,7 @@ unsigned int GetSize(const BufferInfo& info, unsigned int alignedw, unsigned int
   } else if (IsCompressedRGBFormat(format)) {
     size = alignedw * alignedh * ASTC_BLOCK_SIZE;
   } else {
+    // Below switch should be for only YUV/custom formats
     switch (format) {
       case HAL_PIXEL_FORMAT_RAW16:
       case HAL_PIXEL_FORMAT_Y16:
@@ -233,15 +237,15 @@ unsigned int GetSize(const BufferInfo& info, unsigned int alignedw, unsigned int
       case HAL_PIXEL_FORMAT_Y8:
         size = alignedw * alignedh * 1;
         break;
-
-      case HAL_PIXEL_FORMAT_YCrCb_420_SP_ADRENO:
+        // adreno formats
+      case HAL_PIXEL_FORMAT_YCrCb_420_SP_ADRENO:  // NV21
         size = ALIGN(alignedw * alignedh, SIZE_4K);
         size += (unsigned int)ALIGN(2 * ALIGN(width / 2, 32) * ALIGN(height / 2, 32), SIZE_4K);
         break;
-      case HAL_PIXEL_FORMAT_YCbCr_420_SP_TILED:
-
-
-
+      case HAL_PIXEL_FORMAT_YCbCr_420_SP_TILED:  // NV12
+        // The chroma plane is subsampled,
+        // but the pitch in bytes is unchanged
+        // The GPU needs 4K alignment, but the video decoder needs 8K
         size = ALIGN(alignedw * alignedh, SIZE_8K);
         size += ALIGN(alignedw * (unsigned int)ALIGN(height / 2, 32), SIZE_8K);
         break;
@@ -292,6 +296,7 @@ unsigned int GetSize(const BufferInfo& info, unsigned int alignedw, unsigned int
   return size;
 }
 
+// Explicitly defined UBWC formats
 bool IsUBwcFormat(int format) {
   switch (format) {
     case HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS_UBWC:
@@ -304,6 +309,7 @@ bool IsUBwcFormat(int format) {
 }
 
 bool IsUBwcSupported(int format) {
+  // Existing HAL formats with UBWC support
   switch (format) {
     case HAL_PIXEL_FORMAT_BGR_565:
     case HAL_PIXEL_FORMAT_RGBA_8888:
@@ -330,6 +336,7 @@ bool IsUBwcPISupported(int format, uint64_t usage) {
     return false;
   }
 
+  // As of now only two formats
   switch (format) {
     case HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS_UBWC:
     case HAL_PIXEL_FORMAT_YCbCr_420_TP10_UBWC: {
@@ -347,21 +354,27 @@ bool IsUBwcPISupported(int format, uint64_t usage) {
 }
 
 bool IsUBwcEnabled(int format, uint64_t usage) {
+  // Allow UBWC, if client is using an explicitly defined UBWC pixel format.
   if (IsUBwcFormat(format)) {
     return true;
   }
 
+  // Allow UBWC, if an OpenGL client sets UBWC usage flag and GPU plus MDP
+  // support the format. OR if a non-OpenGL client like Rotator, sets UBWC
+  // usage flag and MDP supports the format.
   if (((usage & GRALLOC_USAGE_PRIVATE_ALLOC_UBWC) ||
        (usage & GRALLOC_USAGE_PRIVATE_ALLOC_UBWC_PI) ||
        (usage & BufferUsage::COMPOSER_CLIENT_TARGET)) &&
       IsUBwcSupported(format)) {
     bool enable = true;
+    // Query GPU for UBWC only if buffer is intended to be used by GPU.
     if ((usage & BufferUsage::GPU_TEXTURE) || (usage & BufferUsage::GPU_RENDER_TARGET)) {
       if (AdrenoMemInfo::GetInstance()) {
         enable = AdrenoMemInfo::GetInstance()->IsUBWCSupportedByGPU(format);
       }
     }
 
+    // Allow UBWC, only if CPU usage flags are not set
     if (enable && !(CpuCanAccess(usage))) {
       return true;
     }
@@ -405,10 +418,13 @@ unsigned int GetRgbUBwcMetaBufferSize(int width, int height, uint32_t bpp) {
     return size;
   }
 
+  // Align meta buffer height to 16 blocks
   meta_height = ALIGN(((height + block_height - 1) / block_height), 16);
 
+  // Align meta buffer width to 64 blocks
   meta_width = ALIGN(((width + block_width - 1) / block_width), 64);
 
+  // Align meta buffer size to 4K
   size = (unsigned int)ALIGN((meta_width * meta_height), 4096);
 
   return size;
@@ -484,10 +500,12 @@ bool UseUncached(int format, uint64_t usage) {
     return true;
   }
 
+  // CPU read rarely
   if ((usage & BufferUsage::CPU_READ_MASK) == static_cast<uint64_t>(BufferUsage::CPU_READ_RARELY)) {
     return true;
   }
 
+  // CPU  write rarely
   if ((usage & BufferUsage::CPU_WRITE_MASK) ==
       static_cast<uint64_t>(BufferUsage::CPU_WRITE_RARELY)) {
     return true;
@@ -558,6 +576,8 @@ uint64_t GetHandleFlags(int format, uint64_t usage) {
 int GetImplDefinedFormat(uint64_t usage, int format) {
   int gr_format = format;
 
+  // If input format is HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED then based on
+  // the usage bits, gralloc assigns a format.
   if (format == HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED ||
       format == HAL_PIXEL_FORMAT_YCbCr_420_888) {
     if ((usage & GRALLOC_USAGE_PRIVATE_ALLOC_UBWC || usage & GRALLOC_USAGE_PRIVATE_ALLOC_UBWC_PI) &&
@@ -565,30 +585,33 @@ int GetImplDefinedFormat(uint64_t usage, int format) {
       gr_format = HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS_UBWC;
     } else if (usage & BufferUsage::VIDEO_ENCODER) {
       if (usage & GRALLOC_USAGE_PRIVATE_VIDEO_NV21_ENCODER) {
-        gr_format = HAL_PIXEL_FORMAT_NV21_ENCODEABLE;
+        gr_format = HAL_PIXEL_FORMAT_NV21_ENCODEABLE;  // NV21
       } else if (usage & GRALLOC_USAGE_PRIVATE_HEIF) {
         gr_format = HAL_PIXEL_FORMAT_NV12_HEIF;
       } else if (format == HAL_PIXEL_FORMAT_YCbCr_420_888) {
         gr_format = HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS;
       } else {
-        gr_format = HAL_PIXEL_FORMAT_NV12_ENCODEABLE;
+        gr_format = HAL_PIXEL_FORMAT_NV12_ENCODEABLE;  // NV12
       }
     } else if (usage & BufferUsage::CAMERA_INPUT) {
       if (usage & BufferUsage::CAMERA_OUTPUT) {
-
-        gr_format = HAL_PIXEL_FORMAT_NV21_ZSL;
+        // Assumed ZSL if both producer and consumer camera flags set
+        gr_format = HAL_PIXEL_FORMAT_NV21_ZSL;  // NV21
       } else {
-        gr_format = HAL_PIXEL_FORMAT_YCrCb_420_SP;
+        gr_format = HAL_PIXEL_FORMAT_YCrCb_420_SP;  // NV21
       }
     } else if (usage & BufferUsage::CAMERA_OUTPUT) {
       if (format == HAL_PIXEL_FORMAT_YCbCr_420_888) {
-        gr_format = HAL_PIXEL_FORMAT_NV21_ZSL;
+        gr_format = HAL_PIXEL_FORMAT_NV21_ZSL;  // NV21
       } else {
-        gr_format = HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS;
+        gr_format = HAL_PIXEL_FORMAT_YCbCr_420_SP_VENUS;  // NV12 preview
       }
     } else if (usage & BufferUsage::COMPOSER_OVERLAY) {
+      // XXX: If we still haven't set a format, default to RGBA8888
       gr_format = HAL_PIXEL_FORMAT_RGBA_8888;
     } else if (format == HAL_PIXEL_FORMAT_YCbCr_420_888) {
+      // If no other usage flags are detected, default the
+      // flexible YUV format to NV21_ZSL
       gr_format = HAL_PIXEL_FORMAT_NV21_ZSL;
     }
   }
@@ -614,7 +637,7 @@ bool HasAlphaComponent(int32_t format) {
 }
 
 void GetRGBPlaneInfo(const BufferInfo& info, int32_t format, int32_t width, int32_t height,
-                     int32_t  , int* plane_count, PlaneLayoutInfo* plane_info) {
+                     int32_t /* flags */, int* plane_count, PlaneLayoutInfo* plane_info) {
   uint64_t usage = info.usage;
   *plane_count = 1;
   uint32_t bpp = 0;
@@ -636,4 +659,4 @@ void GetRGBPlaneInfo(const BufferInfo& info, int32_t format, int32_t width, int3
   plane_info->scanlines = height;
 }
 
-}
+}  // namespace gralloc

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gr_utils.h

@@ -42,7 +42,7 @@
 
 #ifdef SLAVE_SIDE_CP
 #define SECURE_ALIGN SZ_1M
-#else
+#else  // MASTER_SIDE_CP
 #define SECURE_ALIGN SZ_4K
 #endif
 
@@ -68,38 +68,59 @@ inline Type1 ALIGN(Type1 x, Type2 align) {
 }
 
 enum PlaneComponent {
+  /* luma */
   PLANE_COMPONENT_Y = 1 << 0,
+  /* chroma blue */
   PLANE_COMPONENT_Cb = 1 << 1,
+  /* chroma red */
   PLANE_COMPONENT_Cr = 1 << 2,
 
+  /* red */
   PLANE_COMPONENT_R = 1 << 10,
+  /* green */
   PLANE_COMPONENT_G = 1 << 11,
+  /* blue */
   PLANE_COMPONENT_B = 1 << 12,
 
+  /* alpha */
   PLANE_COMPONENT_A = 1 << 20,
 
+  /* raw data plane */
   PLANE_COMPONENT_RAW = 1 << 30,
 
+  /* meta information plane */
   PLANE_COMPONENT_META = 1 << 31,
 };
 
 struct PlaneLayoutInfo {
+  /** Components represented the type of plane. */
   PlaneComponent component;
 
+  /** horizontal subsampling. Must be a positive power of 2. */
   uint32_t h_subsampling;
 
+  /** vertical subsampling. Must be a positive power of 2. */
   uint32_t v_subsampling;
 
+  /** offset to the first byte of the top-left pixel of the plane
+   *  and it is calculated from the start of the buffer.
+   *  Add base of the handle with offset to get the first byte of the plane.
+   */
   uint32_t offset;
 
+  /** step is the distance in bytes from one pixel value to the next. */
   int32_t step;
 
+  /** stride of the plane in pixels */
   int32_t stride;
 
+  /** stride of the plane in in bytes */
   int32_t stride_bytes;
 
+  /** plane height or vertical stride */
   int32_t scanlines;
 
+  /** size of the plane in bytes */
   uint32_t size;
 };
 
@@ -130,6 +151,6 @@ int GetImplDefinedFormat(uint64_t usage, int format);
 int GetCustomFormatFlags(int format, uint64_t usage, int* custom_format, uint64_t* priv_flags);
 bool IsGPUFlagSupported(uint64_t usage);
 bool HasAlphaComponent(int32_t format);
-}
+}  // namespace gralloc
 
-#endif
+#endif  // __GR_UTILS_H__

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/gralloc_priv.h

@@ -26,6 +26,7 @@
 #include "QtiGrallocDefs.h"
 #include "gr_priv_handle.h"
 
+//#pragma message "Warning: gralloc_priv.h is deprecated"
 
 #define GRALLOC_PROP_PREFIX "vendor.gralloc."
 #define GRALLOC_PROP(prop_name) GRALLOC_PROP_PREFIX prop_name
@@ -41,6 +42,8 @@ inline int roundUpToPageSize(int x) {
   return (x + (getpagesize() - 1)) & ~(getpagesize() - 1);
 }
 
+/* Legacy gralloc1 definitions */
+/* Some clients may still be using the old flags */
 #define GRALLOC1_PRODUCER_USAGE_PRIVATE_ADSP_HEAP GRALLOC_USAGE_PRIVATE_ADSP_HEAP
 #define GRALLOC1_PRODUCER_USAGE_PRIVATE_ALLOC_UBWC GRALLOC_USAGE_PRIVATE_ALLOC_UBWC
 #define GRALLOC1_PRODUCER_USAGE_PRIVATE_UNCACHED GRALLOC_USAGE_PRIVATE_UNCACHED
@@ -51,6 +54,7 @@ inline int roundUpToPageSize(int x) {
 #define GRALLOC1_CONSUMER_USAGE_PRIVATE_10BIT_TP GRALLOC_USAGE_PRIVATE_10BIT_TP
 #define GRALLOC1_PRODUCER_USAGE_PRIVATE_VIDEO_NV21_ENCODER GRALLOC_USAGE_PRIVATE_VIDEO_NV21_ENCODER
 
+// for PERFORM API :
 #define GRALLOC_MODULE_PERFORM_CREATE_HANDLE_FROM_BUFFER 1
 #define GRALLOC_MODULE_PERFORM_GET_STRIDE 2
 #define GRALLOC_MODULE_PERFORM_GET_CUSTOM_STRIDE_FROM_HANDLE 3
@@ -68,9 +72,11 @@ inline int roundUpToPageSize(int x) {
 #define GRALLOC1_MODULE_PERFORM_GET_INTERLACE_FLAG 15
 #define GRALLOC_MODULE_PERFORM_GET_GRAPHICS_METADATA 16
 
+/* possible values for inverse gamma correction */
 #define HAL_IGC_NOT_SPECIFIED 0
 #define HAL_IGC_s_RGB 1
 
+/* Color Space: Values maps to ColorSpace_t in qdMetadata.h */
 #define HAL_CSC_ITU_R_601 0
 #define HAL_CSC_ITU_R_601_FR 1
 #define HAL_CSC_ITU_R_709 2
@@ -78,16 +84,20 @@ inline int roundUpToPageSize(int x) {
 #define HAL_CSC_ITU_R_2020 4
 #define HAL_CSC_ITU_R_2020_FR 5
 
+/* possible formats for 3D content*/
 enum {
   HAL_NO_3D = 0x0,
   HAL_3D_SIDE_BY_SIDE_L_R = 0x1,
   HAL_3D_SIDE_BY_SIDE_R_L = 0x2,
   HAL_3D_TOP_BOTTOM = 0x4,
-  HAL_3D_IN_SIDE_BY_SIDE_L_R = 0x10000,
+  HAL_3D_IN_SIDE_BY_SIDE_L_R = 0x10000,  // unused legacy format
 };
 
+/* Flag to determine interlaced content
+ * Value maps to Flags presents in types.hal of QtiMapperextensions
+ */
 enum {
   LAYOUT_INTERLACED_FLAG = 1 << 0,
 };
 
-#endif
+#endif  // __GRALLOC_PRIV_H__

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/mapper.h

@@ -60,43 +60,43 @@ struct IMapper : public IBase {
     int32_t height __attribute__((aligned(4)));
   };
 
-  static sp<IMapper> getService(const std::string&  , const bool  );
+  static sp<IMapper> getService(const std::string& /* serviceName */, const bool /* getStub */);
 };
 
-}
+}  // namespace V2_0
 namespace V3_0 {
 
 struct IMapper : public IBase {
-  static sp<IMapper> getService(const std::string&  , const bool  );
+  static sp<IMapper> getService(const std::string& /* serviceName */, const bool /* getStub */);
 };
 
-}
+}  // namespace V3_0
 namespace V4_0 {
 
 struct IMapper : public IBase {
-  static sp<IMapper> getService(const std::string&  , const bool  );
+  static sp<IMapper> getService(const std::string& /* serviceName */, const bool /* getStub */);
 };
 
-}
-}
+}  // namespace V4_0
+}  // namespace android::hardware::graphics::mapper
 
 namespace vendor::qti::hardware::display::mapper {
 namespace V4_0 {
 
 struct IQtiMapper : public IBase {
-  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V4_0::IMapper>&  ,
-                                         bool  );
+  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V4_0::IMapper>& /* parent */,
+                                         bool /* emitError */);
 };
 
-}
+}  // namespace V4_0
 namespace V3_0 {
 
 struct IQtiMapper : public IBase {
-  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V3_0::IMapper>&  ,
-                                         bool  );
+  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V3_0::IMapper>& /* parent */,
+                                         bool /* emitError */);
 };
 
-}
+}  // namespace V3_0
 namespace V2_0 {
 
 struct IQtiMapper : public IBase {
@@ -175,9 +175,9 @@ struct IQtiMapper : public IBase {
                                                  V1_0::IQtiMapperExtensions>& extensions)>;
   virtual Return<void> getMapperExtensions(getMapperExtensions_cb _hidl_cb);
 
-  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V2_0::IMapper>&  ,
-                                         bool  );
+  static Return<sp<IQtiMapper>> castFrom(const sp<graphics::mapper::V2_0::IMapper>& /* parent */,
+                                         bool /* emitError */);
 };
 
-}
-}
+}  // namespace V2_0
+}  // namespace vendor::qti::hardware::display::mapper

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/mapperextensions.h

@@ -45,7 +45,7 @@ struct IQtiMapperExtensions : public IBase {
   IQtiMapperExtensions(){};
 };
 
-}
+}  // namespace V1_0
 namespace V1_1 {
 using Error = V1_0::Error;
 using PlaneLayout = V1_0::PlaneLayout;
@@ -64,6 +64,7 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, passthrough
   using getInterlacedFlag_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, bool interlaced)>;
   virtual ::android::hardware::Return<void> getInterlacedFlag(void* buffer,
@@ -78,6 +79,7 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, passthrough
   using getRgbDataAddress_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, void* rgb_data)>;
   virtual ::android::hardware::Return<void> getRgbDataAddress(void* buffer,
@@ -93,6 +95,7 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, passhthrough
   using getColorSpace_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t color_space)>;
   virtual ::android::hardware::Return<void> getColorSpace(void* buffer, getColorSpace_cb _hidl_cb) {
@@ -100,6 +103,7 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, passthrough with hidl fixups
   using getYuvPlaneInfo_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error,
       const ::android::hardware::hidl_vec<
@@ -126,22 +130,27 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, cast private data with no passthrough
   using getFd_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t fd)>;
   virtual ::android::hardware::Return<void> getFd(void* buffer, getFd_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getWidth_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t width)>;
   virtual ::android::hardware::Return<void> getWidth(void* buffer, getWidth_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getHeight_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t height)>;
   virtual ::android::hardware::Return<void> getHeight(void* buffer, getHeight_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getOffset_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, uint64_t offset)>;
   virtual ::android::hardware::Return<void> getOffset(void* buffer, getOffset_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getSize_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, uint64_t size)>;
   virtual ::android::hardware::Return<void> getSize(void* buffer, getSize_cb _hidl_cb);
@@ -170,10 +179,12 @@ struct IQtiMapperExtensions : public IBase {
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, uint64_t usage)>;
   virtual ::android::hardware::Return<void> getUsageFlags(void* buffer, getUsageFlags_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getFormat_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t format)>;
   virtual ::android::hardware::Return<void> getFormat(void* buffer, getFormat_cb _hidl_cb);
 
+  // Used, cast private data with no passthrough
   using getPrivateFlags_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, int32_t flags)>;
   virtual ::android::hardware::Return<void> getPrivateFlags(void* buffer,
@@ -187,6 +198,7 @@ struct IQtiMapperExtensions : public IBase {
     std::terminate();
   }
 
+  // Used, PAIN
   using getFormatLayout_cb = std::function<void(
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error error, uint64_t size,
       const ::android::hardware::hidl_vec<
@@ -196,6 +208,7 @@ struct IQtiMapperExtensions : public IBase {
                                                             int32_t height,
                                                             getFormatLayout_cb _hidl_cb);
 
+  // V1.1, Used, passthrough
   virtual ::android::hardware::Return<
       ::vendor::qti::hardware::display::mapperextensions::V1_0::Error>
   getSurfaceMetadata_V1(void* buffer, void* metadata) {
@@ -204,8 +217,8 @@ struct IQtiMapperExtensions : public IBase {
   }
 
   static Return<sp<IQtiMapperExtensions>> castFrom(
-      android::sp<V1_0::IQtiMapperExtensions> const&  , bool  );
+      android::sp<V1_0::IQtiMapperExtensions> const& /* parent */, bool /* emitError */);
 };
 
-}
-}
+}  // namespace V1_1
+}  // namespace vendor::qti::hardware::display::mapperextensions

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/types/mapper.h

@@ -12,6 +12,7 @@ namespace graphics {
 namespace mapper {
 namespace V2_0 {
 
+// Forward declaration for forward reference support:
 enum class Error : int32_t;
 struct YCbCrLayout;
 
@@ -24,8 +25,34 @@ enum class Error : int32_t {
   UNSUPPORTED = 7,
 };
 
+/**
+ * A buffer descriptor is an implementation-defined opaque data returned by
+ * createDescriptor. It describes the properties of a buffer and is consumed
+ * by the allocator.
+ */
 typedef ::android::hardware::hidl_vec<uint32_t> BufferDescriptor;
 
+/**
+ * Structure for describing YCbCr formats for consumption by applications.
+ * This is used with PixelFormat::YCBCR_*_888.
+ *
+ * Buffer chroma subsampling is defined in the format.
+ * e.g. PixelFormat::YCBCR_420_888 has subsampling 4:2:0.
+ *
+ * Buffers must have a 8 bit depth.
+ *
+ * y, cb, and cr point to the first byte of their respective planes.
+ *
+ * Stride describes the distance in bytes from the first value of one row of
+ * the image to the first value of the next row. It includes the width of the
+ * image plus padding.
+ * yStride is the stride of the luma plane.
+ * cStride is the stride of the chroma planes.
+ *
+ * chromaStep is the distance in bytes from one chroma pixel value to the
+ * next. This is 2 bytes for semiplanar (because chroma values are interleaved
+ * and each chroma value is one byte) and 1 for planar.
+ */
 struct YCbCrLayout final {
   void* y;
   void* cb;
@@ -35,6 +62,9 @@ struct YCbCrLayout final {
   uint32_t chromaStep;
 };
 
+//
+// type declarations for package
+//
 
 template <typename>
 static inline std::string toString(int32_t o);
@@ -77,7 +107,11 @@ constexpr int32_t& operator&=(int32_t& v,
 
 static inline std::string toString(
     const ::android::hardware::graphics::mapper::V2_0::YCbCrLayout& o);
+// operator== and operator!= are not generated for YCbCrLayout
 
+//
+// type header definitions for package
+//
 
 template <>
 inline std::string toString<::android::hardware::graphics::mapper::V2_0::Error>(int32_t o) {
@@ -184,17 +218,17 @@ static inline std::string toString(
   return os;
 }
 
+// operator== and operator!= are not generated for YCbCrLayout
 
+}  // namespace V2_0
+}  // namespace mapper
+}  // namespace graphics
+}  // namespace hardware
+}  // namespace android
 
-}
-}
-}
-}
-}
-
-
-
-
+//
+// global type declarations for package
+//
 
 namespace android {
 namespace hardware {
@@ -209,8 +243,8 @@ constexpr std::array<::android::hardware::graphics::mapper::V2_0::Error, 6>
         ::android::hardware::graphics::mapper::V2_0::Error::NO_RESOURCES,
         ::android::hardware::graphics::mapper::V2_0::Error::UNSUPPORTED,
 };
-}
-}
-}
+}  // namespace details
+}  // namespace hardware
+}  // namespace android
 
-#endif
+#endif  // HIDL_GENERATED_ANDROID_HARDWARE_GRAPHICS_MAPPER_V2_0_TYPES_H

app/src/main/cpp/adrenotools/tools/qtimapper-shim/ext/types/mapperextensions.h

@@ -13,6 +13,7 @@ namespace display {
 namespace mapperextensions {
 namespace V1_0 {
 
+// Forward declaration for forward reference support:
 enum class Error : int32_t;
 struct YCbCrLayout;
 enum class PlaneComponent : uint32_t;
@@ -35,22 +36,61 @@ struct YCbCrLayout final {
   uint32_t chromaStep;
 };
 
+/**
+ * Plane Component type definitions.
+ */
 enum class PlaneComponent : uint32_t {
-  PLANE_COMPONENT_Y = 1u  ,
-  PLANE_COMPONENT_Cb = 2u  ,
-  PLANE_COMPONENT_Cr = 4u  ,
-  PLANE_COMPONENT_R = 1024u  ,
-  PLANE_COMPONENT_G = 2048u  ,
-  PLANE_COMPONENT_B = 4096u  ,
-  PLANE_COMPONENT_A = 1048576u  ,
-  PLANE_COMPONENT_RAW = 1073741824u  ,
-  PLANE_COMPONENT_META = 2147483648u  ,
+  PLANE_COMPONENT_Y = 1u /* (1 << 0) */,
+  PLANE_COMPONENT_Cb = 2u /* (1 << 1) */,
+  PLANE_COMPONENT_Cr = 4u /* (1 << 2) */,
+  PLANE_COMPONENT_R = 1024u /* (1 << 10) */,
+  PLANE_COMPONENT_G = 2048u /* (1 << 11) */,
+  PLANE_COMPONENT_B = 4096u /* (1 << 12) */,
+  PLANE_COMPONENT_A = 1048576u /* (1 << 20) */,
+  PLANE_COMPONENT_RAW = 1073741824u /* (1 << 30) */,
+  PLANE_COMPONENT_META = 2147483648u /* (1 << 31) */,
 };
 
+/**
+ * Flags to send with getFormatLayout for extra information for e.g. interlaced,
+ * otherwise send 0.
+ */
 enum class Flags : int32_t {
-  LAYOUT_INTERLACED_FLAG = 1  ,
+  LAYOUT_INTERLACED_FLAG = 1 /* (1 << 0) */,
 };
 
+/**
+ * Structure for describing plane layout information for YUVA/RGBA/RAW formats
+ * YUV formats can be planar or semi-planar.
+ *
+ * This layout structure is used with any pixel format that can be
+ * represented by it, such as:
+ *  - HAL_PIXEL_FORMAT_YCbCr_*
+ *  - HAL_PIXEL_FORMAT_RGB*_*
+ *  - even implementation defined formats that can be represented by
+ *    the structures
+ *
+ * Each plane can be made up of one or more PlaneComponents depending on
+ * the format.
+ *
+ * Each plane can be subsampled either vertically or horizontally by
+ * a power-of-two factor.
+ *
+ * Pixel increment describes the distance in bytes from one pixel to the
+ * next pixel (to the right) on the same row for the component plane.
+ * This can be negative.
+ *
+ * Stride is provided in both pixels and bytes.
+ * Stride_bytes describes the distance in bytes from the first pixel of
+ * one row to the first pixel of the next row (below) for the component plane.
+ * This can be negative.
+ *
+ * Scanlines describes the height of the plane in terms of number of rows.
+ *
+ * Size of plane is stride_bytes * scanlines + any padding required for
+ * alignment as per format specification.
+ *
+ */
 struct PlaneLayout final {
   ::android::hardware::hidl_bitfield<
       ::vendor::qti::hardware::display::mapperextensions::V1_0::PlaneComponent>
@@ -97,6 +137,9 @@ static_assert(sizeof(::vendor::qti::hardware::display::mapperextensions::V1_0::P
 static_assert(__alignof(::vendor::qti::hardware::display::mapperextensions::V1_0::PlaneLayout) == 4,
               "wrong alignment");
 
+//
+// type declarations for package
+//
 
 template <typename>
 static inline std::string toString(int32_t o);
@@ -142,6 +185,7 @@ constexpr int32_t& operator&=(
 
 static inline std::string toString(
     const ::vendor::qti::hardware::display::mapperextensions::V1_0::YCbCrLayout& o);
+// operator== and operator!= are not generated for YCbCrLayout
 
 template <typename>
 static inline std::string toString(uint32_t o);
@@ -240,6 +284,9 @@ static inline bool operator!=(
     const ::vendor::qti::hardware::display::mapperextensions::V1_0::PlaneLayout& lhs,
     const ::vendor::qti::hardware::display::mapperextensions::V1_0::PlaneLayout& rhs);
 
+//
+// type header definitions for package
+//
 
 template <>
 inline std::string toString<::vendor::qti::hardware::display::mapperextensions::V1_0::Error>(
@@ -332,6 +379,7 @@ static inline std::string toString(
   return os;
 }
 
+// operator== and operator!= are not generated for YCbCrLayout
 
 template <>
 inline std::string
@@ -594,13 +642,16 @@ static inline bool operator!=(
   return !(lhs == rhs);
 }
 
-}
-}
-}
-}
-}
-}
+}  // namespace V1_0
+}  // namespace mapperextensions
+}  // namespace display
+}  // namespace hardware
+}  // namespace qti
+}  // namespace vendor
 
+//
+// global type declarations for package
+//
 
 namespace android {
 namespace hardware {
@@ -613,9 +664,9 @@ constexpr std::array<::vendor::qti::hardware::display::mapperextensions::V1_0::E
         ::vendor::qti::hardware::display::mapperextensions::V1_0::Error::NO_RESOURCES,
         ::vendor::qti::hardware::display::mapperextensions::V1_0::Error::UNSUPPORTED,
 };
-}
-}
-}
+}  // namespace details
+}  // namespace hardware
+}  // namespace android
 
 namespace android {
 namespace hardware {
@@ -637,9 +688,9 @@ constexpr std::array<::vendor::qti::hardware::display::mapperextensions::V1_0::P
         ::vendor::qti::hardware::display::mapperextensions::V1_0::PlaneComponent::
             PLANE_COMPONENT_META,
 };
-}
-}
-}
+}  // namespace details
+}  // namespace hardware
+}  // namespace android
 
 namespace android {
 namespace hardware {
@@ -649,8 +700,8 @@ constexpr std::array<::vendor::qti::hardware::display::mapperextensions::V1_0::F
     hidl_enum_values<::vendor::qti::hardware::display::mapperextensions::V1_0::Flags> = {
         ::vendor::qti::hardware::display::mapperextensions::V1_0::Flags::LAYOUT_INTERLACED_FLAG,
 };
-}
-}
-}
+}  // namespace details
+}  // namespace hardware
+}  // namespace android
 
-#endif
+#endif  // HIDL_GENERATED_VENDOR_QTI_HARDWARE_DISPLAY_MAPPEREXTENSIONS_V1_0_TYPES_H

app/src/main/cpp/adrenotools/tools/qtimapper-shim/shim.cpp

@@ -46,13 +46,14 @@
 using namespace android::hardware;
 using namespace android;
 
+// These two functions are used by the blob and aren't present on Q so weakly stub them
 extern "C" uint64_t __attribute__((weak)) atrace_get_enabled_tags() {
   return 0;
 }
 
 namespace android::hardware::details {
 void __attribute__((weak)) return_status::onValueRetrieval() const {}
-}
+}  // namespace android::hardware::details
 
 bool IBase::isRemote() const {
   return false;
@@ -145,7 +146,7 @@ sp<IMapper> IMapper::getService(const std::string& serviceName, const bool getSt
   return nullptr;
 }
 
-}
+}  // namespace V2_0
 namespace V3_0 {
 
 sp<IMapper> IMapper::getService(const std::string& serviceName, const bool getStub) {
@@ -153,7 +154,7 @@ sp<IMapper> IMapper::getService(const std::string& serviceName, const bool getSt
   return nullptr;
 }
 
-}
+}  // namespace V3_0
 namespace V4_0 {
 
 sp<IMapper> IMapper::getService(const std::string& serviceName, const bool getStub) {
@@ -161,8 +162,8 @@ sp<IMapper> IMapper::getService(const std::string& serviceName, const bool getSt
   return nullptr;
 }
 
-}
-}
+}  // namespace V4_0
+}  // namespace android::hardware::graphics::mapper
 namespace vendor::qti::hardware::display {
 namespace mapper {
 namespace V4_0 {
@@ -173,7 +174,7 @@ Return<sp<IQtiMapper>> IQtiMapper::castFrom(const sp<graphics::mapper::V4_0::IMa
   return nullptr;
 }
 
-}
+}  // namespace V4_0
 namespace V3_0 {
 
 Return<sp<IQtiMapper>> IQtiMapper::castFrom(const sp<graphics::mapper::V3_0::IMapper>& parent,
@@ -182,7 +183,7 @@ Return<sp<IQtiMapper>> IQtiMapper::castFrom(const sp<graphics::mapper::V3_0::IMa
   return nullptr;
 }
 
-}
+}  // namespace V3_0
 namespace V2_0 {
 
 Return<sp<IQtiMapper>> IQtiMapper::castFrom(const sp<graphics::mapper::V2_0::IMapper>& parent,
@@ -199,8 +200,8 @@ Return<void> IQtiMapper::getMapperExtensions(getMapperExtensions_cb _hidl_cb) {
   return Void();
 }
 
-}
-}
+}  // namespace V2_0
+}  // namespace mapper
 namespace mapperextensions {
 namespace V1_1 {
 
@@ -466,6 +467,6 @@ Return<void> IQtiMapperExtensions::getFormatLayout(int32_t format, uint64_t usag
   return Void();
 }
 
-}
-}
-}
+}  // namespace V1_1
+}  // namespace mapperextensions
+}  // namespace vendor::qti::hardware::display

app/src/main/cpp/deviceinfo/vkinfo.c

@@ -1,107 +0,0 @@
-#include <dlfcn.h>
-#include <jni.h>
-#include <stdio.h>
-#include <string.h>
-#define VK_NO_PROTOTYPES
-#include <vulkan/vulkan.h>
-
-#define LINE(...) do { if (used < sizeof(out)) used += snprintf(out + used, sizeof(out) - used, __VA_ARGS__); } while (0)
-
-static const char *const EXTENSIONS[] = {
-    "VK_EXT_robustness2", "VK_EXT_transform_feedback", "VK_EXT_custom_border_color",
-    "VK_KHR_dynamic_rendering", "VK_EXT_extended_dynamic_state3", "VK_EXT_descriptor_indexing",
-    "VK_KHR_timeline_semaphore", "VK_EXT_mesh_shader", "VK_KHR_ray_query",
-};
-
-static const char *type_name(VkPhysicalDeviceType type) {
-    switch (type) {
-        case VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU: return "integrated GPU";
-        case VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU: return "discrete GPU";
-        case VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU: return "virtual GPU";
-        case VK_PHYSICAL_DEVICE_TYPE_CPU: return "CPU";
-        default: return "other";
-    }
-}
-
-JNIEXPORT jstring JNICALL
-Java_com_droiddeck_launcher_gpu_VulkanInfo_nativeQuery(JNIEnv *env, jclass clazz) {
-    static char out[4096];
-    size_t used = 0;
-    out[0] = 0;
-    void *lib = dlopen("libvulkan.so", RTLD_NOW | RTLD_LOCAL);
-    if (!lib) { LINE("error=no Vulkan loader\n"); return (*env)->NewStringUTF(env, out); }
-    PFN_vkGetInstanceProcAddr gipa = (PFN_vkGetInstanceProcAddr) dlsym(lib, "vkGetInstanceProcAddr");
-    PFN_vkCreateInstance create = gipa ? (PFN_vkCreateInstance) gipa(NULL, "vkCreateInstance") : NULL;
-    PFN_vkEnumerateInstanceVersion instanceVersion = gipa ? (PFN_vkEnumerateInstanceVersion) gipa(NULL, "vkEnumerateInstanceVersion") : NULL;
-    if (!create) { LINE("error=no vkCreateInstance\n"); dlclose(lib); return (*env)->NewStringUTF(env, out); }
-    uint32_t loader = VK_API_VERSION_1_0;
-    if (instanceVersion) instanceVersion(&loader);
-    LINE("loader=%u.%u.%u\n", VK_API_VERSION_MAJOR(loader), VK_API_VERSION_MINOR(loader), VK_API_VERSION_PATCH(loader));
-
-    VkApplicationInfo app = { .sType = VK_STRUCTURE_TYPE_APPLICATION_INFO, .pApplicationName = "DroidDeck device info",
-                              .apiVersion = loader >= VK_API_VERSION_1_1 ? VK_API_VERSION_1_1 : VK_API_VERSION_1_0 };
-    VkInstanceCreateInfo info = { .sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO, .pApplicationInfo = &app };
-    VkInstance instance = VK_NULL_HANDLE;
-    if (create(&info, NULL, &instance) != VK_SUCCESS) { LINE("error=vkCreateInstance failed\n"); dlclose(lib); return (*env)->NewStringUTF(env, out); }
-
-#define GET(name) PFN_##name name = (PFN_##name) gipa(instance, #name)
-    GET(vkDestroyInstance); GET(vkEnumeratePhysicalDevices); GET(vkGetPhysicalDeviceProperties);
-    GET(vkGetPhysicalDeviceProperties2); GET(vkGetPhysicalDeviceMemoryProperties);
-    GET(vkEnumerateDeviceExtensionProperties); GET(vkGetPhysicalDeviceFeatures);
-    uint32_t count = 1;
-    VkPhysicalDevice device = VK_NULL_HANDLE;
-    VkResult listed = vkEnumeratePhysicalDevices ? vkEnumeratePhysicalDevices(instance, &count, &device) : VK_ERROR_INITIALIZATION_FAILED;
-    if ((listed != VK_SUCCESS && listed != VK_INCOMPLETE) || count == 0 || !device || !vkGetPhysicalDeviceProperties) {
-        LINE("error=no Vulkan device\n");
-    } else {
-        VkPhysicalDeviceProperties p;
-        vkGetPhysicalDeviceProperties(device, &p);
-        LINE("device=%s\n", p.deviceName);
-        LINE("type=%s\n", type_name(p.deviceType));
-        LINE("api=%u.%u.%u\n", VK_API_VERSION_MAJOR(p.apiVersion), VK_API_VERSION_MINOR(p.apiVersion), VK_API_VERSION_PATCH(p.apiVersion));
-        LINE("driver_version=%u.%u.%u\n", p.driverVersion >> 22, (p.driverVersion >> 12) & 0x3ff, p.driverVersion & 0xfff);
-        LINE("vendor_id=0x%04x\ndevice_id=0x%08x\n", p.vendorID, p.deviceID);
-        LINE("max_image_2d=%u\n", p.limits.maxImageDimension2D);
-
-        uint32_t extCount = 0;
-        if (vkEnumerateDeviceExtensionProperties) vkEnumerateDeviceExtensionProperties(device, NULL, &extCount, NULL);
-        static VkExtensionProperties exts[512];
-        if (extCount > 512) extCount = 512;
-        if (extCount && vkEnumerateDeviceExtensionProperties) vkEnumerateDeviceExtensionProperties(device, NULL, &extCount, exts);
-        int driverProps = p.apiVersion >= VK_API_VERSION_1_2;
-        for (uint32_t i = 0; i < extCount; i++)
-            if (!strcmp(exts[i].extensionName, "VK_KHR_driver_properties")) driverProps = 1;
-        if (driverProps && vkGetPhysicalDeviceProperties2) {
-            VkPhysicalDeviceDriverProperties driver = { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DRIVER_PROPERTIES };
-            VkPhysicalDeviceProperties2 p2 = { .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PROPERTIES_2, .pNext = &driver };
-            vkGetPhysicalDeviceProperties2(device, &p2);
-            LINE("driver_name=%s\n", driver.driverName);
-            LINE("driver_info=%s\n", driver.driverInfo);
-            LINE("conformance=%u.%u.%u.%u\n", driver.conformanceVersion.major, driver.conformanceVersion.minor,
-                 driver.conformanceVersion.subminor, driver.conformanceVersion.patch);
-        }
-        LINE("extension_count=%u\n", extCount);
-        for (size_t e = 0; e < sizeof(EXTENSIONS) / sizeof(*EXTENSIONS); e++) {
-            int has = 0;
-            for (uint32_t i = 0; i < extCount && !has; i++) has = !strcmp(exts[i].extensionName, EXTENSIONS[e]);
-            LINE("ext.%s=%s\n", EXTENSIONS[e], has ? "yes" : "no");
-        }
-        if (vkGetPhysicalDeviceFeatures) {
-            VkPhysicalDeviceFeatures f;
-            vkGetPhysicalDeviceFeatures(device, &f);
-            LINE("geometry_shader=%s\ntessellation_shader=%s\ntexture_bc=%s\n",
-                 f.geometryShader ? "yes" : "no", f.tessellationShader ? "yes" : "no", f.textureCompressionBC ? "yes" : "no");
-        }
-        if (vkGetPhysicalDeviceMemoryProperties) {
-            VkPhysicalDeviceMemoryProperties m;
-            vkGetPhysicalDeviceMemoryProperties(device, &m);
-            VkDeviceSize largest = 0;
-            for (uint32_t i = 0; i < m.memoryHeapCount; i++)
-                if ((m.memoryHeaps[i].flags & VK_MEMORY_HEAP_DEVICE_LOCAL_BIT) && m.memoryHeaps[i].size > largest) largest = m.memoryHeaps[i].size;
-            LINE("device_heap_mb=%llu\n", (unsigned long long) (largest >> 20));
-        }
-    }
-    if (vkDestroyInstance) vkDestroyInstance(instance, NULL);
-    dlclose(lib);
-    return (*env)->NewStringUTF(env, out);
-}

app/src/main/cpp/framegen/VulkanRendererContext.h

@@ -84,11 +84,12 @@ struct VkTable {
     PFN_vkCmdSetScissor CmdSetScissor;
     PFN_vkCmdPipelineBarrier CmdPipelineBarrier;
     PFN_vkCmdCopyImage CmdCopyImage;
-    PFN_vkCmdBlitImage CmdBlitImage;
-
+    PFN_vkCmdBlitImage CmdBlitImage;   // frame-gen capture resolution: composite -> swapchain upscale
+    // Compute: the native LSFG chain is 25 compute dispatches.
     PFN_vkCmdDispatch CmdDispatch;
     PFN_vkCreateComputePipelines CreateComputePipelines;
     PFN_vkUnmapMemory UnmapMemory;
+    // win-fg native: clears its flow scratch, resets its scratch pool on resize.
     PFN_vkCmdClearColorImage CmdClearColorImage;
     PFN_vkResetDescriptorPool ResetDescriptorPool;
     PFN_vkCmdCopyBufferToImage CmdCopyBufferToImage;
@@ -124,94 +125,103 @@ struct VkTable {
 #include <condition_variable>
 #include <chrono>
 
+// Renderer-neutral direct-scanout impl (owns the SurfaceControl/AHB state).
+// Included after SCANOUT_LOG is defined above; its own definition is guarded.
 #include "../scanout/ScanoutContext.h"
 
+// Native (compositor-side) LSFG frame generation - capability gate.
 #include "lsfg/lsfg_probe.h"
 #include <memory>
 #include <string>
 
 namespace lsfg { class Engine; }
-namespace ddfg { class Engine; }
+namespace winfg { class Engine; }
 
 static constexpr uint32_t MAX_FRAMES_IN_FLIGHT = 2;
 
-
-
-
-struct SgsrPushConstants {
+// Push-constant layouts for the spatial-upscaler post passes. The leading vec4
+// `ndc` matches upscale.vert; the remaining members are read only by the
+// fragment stage. std430 offsets line up with these C structs.
+struct SgsrPushConstants {                 // 36 bytes
     float ndc[4];
-    float viewportInfo[4];
-    float edgeSharpness;
+    float viewportInfo[4];                 // xy = 1/inputSize, zw = inputSize px
+    float edgeSharpness;                   // SGSR EdgeSharpness, from the slider
 };
-struct NisPushConstants {
+struct NisPushConstants {                  // 36 bytes
     float ndc[4];
-    float viewportInfo[4];
-    float sharpness;
+    float viewportInfo[4];                 // xy = 1/inputSize, zw = inputSize px
+    float sharpness;                       // NIS sharpness [0..1], from the slider
 };
-struct EasuPushConstants {
+struct EasuPushConstants {                 // 88 bytes
     float    ndc[4];
     uint32_t con0[4], con1[4], con2[4], con3[4];
     float    outW, outH;
 };
-struct RcasPushConstants {
+struct RcasPushConstants {                 // 40 bytes
     float    ndc[4];
-    uint32_t con[4];
+    uint32_t con[4];                       // con.x = bit-packed sharpness
     float    outW, outH;
 };
-
-
-struct CasPushConstants {
+// Composable post effects (AMD CAS sharpen + fake-HDR). Both lead with vec4 ndc
+// (offset 0) like the upscaler PCs and stay well under the 88-byte PC range.
+struct CasPushConstants {                  // 32 bytes
     float ndc[4];
-    float resolution[2];
-    float sharpness;
+    float resolution[2];                   // input texture size in px
+    float sharpness;                       // CAS SHARPNESS term [0..1]
     float _pad;
 };
-struct HdrPushConstants {
+struct HdrPushConstants {                  // 24 bytes
     float ndc[4];
-    float resolution[2];
+    float resolution[2];                   // input texture size in px
 };
-
-
-struct FxaaPushConstants {
+// Phase 2 screen effects ported from the GL EffectComposer. Each leads with vec4
+// ndc (offset 0) like the upscaler PCs and stays well under the 88-byte PC range.
+struct FxaaPushConstants {                 // 24 bytes
     float ndc[4];
-    float resolution[2];
+    float resolution[2];                   // input texture size in px
 };
-struct ToonPushConstants {
+struct ToonPushConstants {                 // 24 bytes
     float ndc[4];
-    float resolution[2];
+    float resolution[2];                   // input texture size in px
 };
-struct ColorPushConstants {
+struct ColorPushConstants {                // 32 bytes
     float ndc[4];
-    float brightness;
-    float contrast;
-    float gamma;
-    float saturation;
-
-
+    float brightness;                      // additive [-1,1]
+    float contrast;                        // [0,2]
+    float gamma;                           // [0.1,5]
+    float saturation;                      // [0,2]; 1 = unchanged, 0 = greyscale.
+                                           // APPENDED last so the three offsets above
+                                           // stay where color.frag already had them.
 };
-struct NtscPushConstants {
+struct NtscPushConstants {                 // 28 bytes
     float ndc[4];
-    float resolution[2];
-    float frameCount;
+    float resolution[2];                   // screen size in px (TextureSize/resolution)
+    float frameCount;                      // animated chroma-phase counter
 };
-struct CrtPushConstants {
+struct CrtPushConstants {                  // 24 bytes
     float ndc[4];
-    float resolution[2];
+    float resolution[2];                   // input texture size in px (unused by shader)
 };
-struct DebandPushConstants {
+struct DebandPushConstants {               // 28 bytes
     float ndc[4];
-    float resolution[2];
-    float strength;
+    float resolution[2];                   // input texture size in px (layout parity)
+    float strength;                        // dither amplitude in LSBs (1.0 = +/-1/255)
 };
 
 class VulkanRendererContext {
 public:
+    // `lsfgVk11Compat` (experimental) lets the LSFG capability probe accept a
+    // Vulkan 1.1/1.2 device that offers the extensions the chain needs; it has
+    // to be known before vkCreateDevice, hence a constructor argument.
     VulkanRendererContext(ANativeWindow* window, int cWidth, int cHeight, void* adrenotoolsHandle = nullptr,
                           bool lsfgVk11Compat = false);
     ~VulkanRendererContext();
 
     void onSurfaceResized(int width, int height);
     void setTransform(float ox, float oy, float sx, float sy);
+    // #413: game-region clip rect (surface px). Stored and applied as the swapchain scissor in
+    // recordCmdBuf so a FILL/STRETCH game confined to a half (TOP/BOTTOM alignment) can't bleed into
+    // the on-screen-controls half. A full-surface (or w<=0) rect means "no clip" (CENTER).
     void setClipRegion(int x, int y, int w, int h);
     void updatePointerPosition(short x, short y);
     void updateWindowContent(int64_t id, void* pixels, short w, short h, short stride, int x, int y);
@@ -231,7 +241,13 @@ public:
     void scanoutSetBuffer(AHardwareBuffer* ahb, int x, int y, int w, int h, int fenceFd = -1);
     void scanoutSetCursorImage(void* pixels, short w, short h, short stride);
     void scanoutSetCursorPos(short x, short y, short hotX, short hotY);
+    // The renderer-neutral scanout implementation. The scanout methods above are
+    // thin forwarders to this (see VulkanRendererScanout.cpp); the cursor render-
+    // thread signalling stays in the forwarders, not in ScanoutContext.
     ScanoutContext scanout;
+    // Bound to scanout's atomics so the existing JNI ABI (r->scanoutActive /
+    // r->gameFrameDelivered direct member access) keeps compiling against a
+    // single source of truth. Must be declared after `scanout`.
     std::atomic<bool>& scanoutActive = scanout.scanoutActive;
     std::atomic<bool>& gameFrameDelivered = scanout.gameFrameDelivered;
     std::atomic<bool> surfaceDetached{false};
@@ -270,17 +286,48 @@ public:
     void setPresentMode(VkPresentModeKHR mode);
     std::vector<int> getSupportedPresentModes() const;
 
+    // --- Native LSFG frame generation -------------------------------------
+    // Capability verdict for the compositor-side LSFG engine. Filled at device
+    // creation and completed once the swapchain format is known; read by the
+    // UI (through JNI) to grey the engine out with a reason.
     const lsfg::Caps& lsfgCaps() const { return lsfgCaps_; }
 
+    // Arm/disarm native LSFG frame generation for this session. Changing the
+    // armed state recreates the swapchain, because the composite path needs
+    // TRANSFER_DST usage and a deeper image queue that a normal session does
+    // not pay for.
     void setFrameGenArmed(bool armed, int multiplier);
     bool frameGenArmed() const { return fgArmed_.load(std::memory_order_relaxed); }
+    // Live frame-gen telemetry for the in-game readout:
+    //   [0] generations the governor currently trusts
+    //   [1] generations actually planned for the last source frame
+    //   [2] measured source (real) frames per second
+    //   [3] measured presented frames per second
+    //   [4] thermal status, -1 when the device gives no signal
+    //   [5] GPU milliseconds the chain spends per generated frame, -1 unknown
     void frameGenStats(float out[6]) const;
+    // Why the selected native frame-gen engine cannot run here, for the UI:
+    // -1 not known yet (caps not probed), 0 fine, 1 this driver lacks what the
+    // engine needs (lsfgCaps().reason says which gate), 2 the engine failed to start.
     int frameGenProblem() const;
+    // Path to the SPIR-V cache built from the user's Lossless.dll. Setting it
+    // drops any existing engine so the next armed frame rebuilds from it.
     void setLsfgCachePath(const char* path);
+    // Flow scale (0.25-1.0) and the panel's real refresh rate. The pacer never
+    // generates above the refresh rate.
+    // Experimental: `captureHeight` sizes the composite ring the chain runs on,
+    // the width following the swapchain's aspect, so a phone GPU generates at
+    // game-like resolution and the result is blitted up. 0 = panel;
+    // kFgCaptureGame = the X screen's height (containerHeight), which already
+    // carries the per-game override and render scale; otherwise a pixel height.
     static constexpr int32_t kFgCaptureGame = -1;
     void setFrameGenTuning(float flowScale, float refreshHz, int32_t captureHeight = 0);
+    // Which native engine generates: 0 = LSFG (needs the cache built from the
+    // user's Lossless.dll), 1 = win-fg (our own chain, embedded, needs nothing).
+    // Switching drops the other engine so only one ever holds GPU resources.
     void setFrameGenEngine(int kind);
-    void setDdFgTuning(int model, int perfPreset);
+    // win-fg only: interpolation model (3/4) and performance preset (0..2).
+    void setWinFgTuning(int model, int perfPreset);
 
 private:
     struct WinTex {
@@ -312,9 +359,11 @@ private:
 
     ANativeWindow* window;
     int surfaceWidth, surfaceHeight, containerWidth, containerHeight;
+    // #413 compositor clip rect (surface px). clipRegionW<=0 => disabled (whole swapchain). Written from
+    // the renderer thread (setClipRegion), read from the render thread (recordCmdBuf) -> atomic.
     std::atomic<int> clipRegionX{0}, clipRegionY{0}, clipRegionW{0}, clipRegionH{0};
     void* adrenotoolsHandle = nullptr;
-    bool  lsfgVk11Compat_   = false;
+    bool  lsfgVk11Compat_   = false;   // see the constructor
     int filterMode = 0;
     bool swapRB = false;
     float maxAnisotropy           = 1.0f;
@@ -337,6 +386,9 @@ private:
     std::vector<VkImageMemoryBarrier>  framePreUpload;
     std::vector<VkImageMemoryBarrier>  framePostUpload;
 
+    // [P0] All SurfaceControl / AHardwareBuffer scanout state moved to
+    // ScanoutContext (member `scanout` above). Dead members (lastDst*,
+    // ScanoutPending/scanoutPending*, fnSTSetBackPressure) were dropped.
 
     std::atomic<int>  pointerX{0}, pointerY{0};
     float sceneOffsetX=0.f, sceneOffsetY=0.f, sceneScaleX=1.f, sceneScaleY=1.f;
@@ -376,69 +428,138 @@ private:
 
     VkPipeline            pipeline    = VK_NULL_HANDLE;
 
+    // ---- Spatial upscaler (SGSR / FSR1) ----
+    // upscalerMode enum (mirrored by JNI nativeSetUpscaler):
+    //   0 = none     (passthrough; current sampler governs scaling)
+    //   1 = linear   (rebuild base sampler LINEAR; no shader pass)
+    //   2 = nearest  (rebuild base sampler NEAREST; no shader pass)
+    //   3 = sgsr     (Snapdragon GSR 1.0; single pass; aspect-fit / letterbox)
+    //   4 = fsr      (AMD FSR1 EASU+RCAS; two passes; fill / stretch)
+    //   5 = fsr_fit  (AMD FSR1 EASU+RCAS; two passes; aspect-fit / letterbox)
+    //   6 = sharpen  (RCAS-only; any resolution; aspect-fit / letterbox)
+    //   7 = nis      (NVIDIA Image Scaling NVScaler; single pass; aspect-fit)
+    //   8 = sgsr_quality (SGSR 1 edge-direction variant; single pass; aspect-fit)
+    // Shader upscaling only engages for modes 3-8 AND when the game render
+    // resolution (container) is smaller than the swapchain. Otherwise the
+    // existing direct-to-swapchain path is used unchanged.
     int               upscalerMode      = 0;
+    // Independent of upscalerMode: high-quality Lanczos downscale for the
+    // supersampling case (game render res > display res). When enabled and the
+    // render res exceeds the swapchain, replaces the bilinear minify with a
+    // proper downscale pass. Supersampling and the upscale modes are mutually
+    // exclusive in practice (one is render>display, the other render<display).
     bool              hqDownscale       = false;
 
+    // Composable post effects, independent of the scaling mode. CAS layers a sharpen
+    // on top of any mode (incl. native res); HDR is a binary fake-HDR. The upscaler
+    // sharpness (RCAS lobe scale / SGSR EdgeSharpness) is driven by its own slider as a
+    // linear 0..1 value: 0 = neutral (no sharpening; the upscale still runs), 1 = max.
     bool              casEnabled        = false;
-    int               casSharpness      = 60;
+    int               casSharpness      = 60;     // slider 0..100 -> CAS SHARPNESS
     bool              hdrEnabled        = false;
-    float             upscaleSharpness01 = 0.75f;
-
+    float             upscaleSharpness01 = 0.75f; // slider/100; RCAS lobe scale, SGSR edge derived
+    // Debanding: terminal TPDF/IGN dither pass before the 8-bit swapchain quantize.
     bool              debandEnabled     = false;
-    int               debandStrength    = 100;
+    int               debandStrength    = 100;    // slider 0..200 -> strength/100 LSBs
 
+    // Phase 2 screen effects (GL EffectComposer parity). FXAA/Toon/CRT/NTSC are
+    // binary; Color is the brightness/contrast/gamma grade (always-applied via the
+    // sliders, no toggle) and is "enabled" only when not at neutral (0,0,1).
     bool              fxaaEnabled       = false;
     bool              toonEnabled       = false;
     bool              crtEnabled        = false;
     bool              ntscEnabled       = false;
-    bool              colorEnabled      = false;
-    float             colorBrightness   = 0.0f;
-    float             colorContrast     = 0.0f;
-    float             colorGamma        = 1.0f;
-    float             colorSaturation   = 1.0f;
-    uint32_t          ntscFrameCounter  = 0;
+    bool              colorEnabled      = false;   // derived: !neutral grade
+    float             colorBrightness   = 0.0f;    // [-1,1] (slider/100, clamped)
+    float             colorContrast     = 0.0f;    // [0,2]  (slider/100, clamped)
+    float             colorGamma        = 1.0f;    // [0.1,5]
+    float             colorSaturation   = 1.0f;    // [0,2]  (slider/100, clamped)
+    uint32_t          ntscFrameCounter  = 0;       // animates NTSC chroma phase
 
-    VkSampler         upscaleSampler    = VK_NULL_HANDLE;
+    VkSampler         upscaleSampler    = VK_NULL_HANDLE; // linear clamp; offscreen/mid input
 
+    // === Native LSFG: composite target ring ===================================
+    // Frame generation cannot composite straight into a swapchain image: the
+    // finished frame has to be READABLE (it becomes the next frame's LSFG
+    // input) and generated frames have to be STORAGE-WRITABLE by a compute
+    // dispatch. Android swapchain images are COLOR_ATTACHMENT only, and
+    // storage support on a swapchain format is not something a driver owes us.
+    //
+    // So when frame gen is armed the whole existing recording is redirected at
+    // a composite image we own - format-identical to the swapchain, so every
+    // existing pipeline stays render-pass compatible - and a copy moves it into
+    // the acquired swapchain image at the end. With frame gen off, not one of
+    // these objects is created and the direct-to-swapchain path is untouched.
     struct CompositeTarget {
         VkImage         img         = VK_NULL_HANDLE;
         VkDeviceMemory  mem         = VK_NULL_HANDLE;
-        VkImageView     view        = VK_NULL_HANDLE;
-        VkImageView     storageView = VK_NULL_HANDLE;
+        VkImageView     view        = VK_NULL_HANDLE;  // colour attachment + sampled
+        VkImageView     storageView = VK_NULL_HANDLE;  // compute writes (generate)
         VkFramebuffer   fb          = VK_NULL_HANDLE;
-        VkDescriptorSet ds          = VK_NULL_HANDLE;
+        VkDescriptorSet ds          = VK_NULL_HANDLE;  // sampled, for later passes
     };
+    // Hard ceiling: (max generations + 1) presentable frames per source frame,
+    // times a queue depth of 2, capped so the footprint stays bounded.
     static constexpr uint32_t kMaxCompositeTargets = 7;
 
     std::vector<CompositeTarget> compositeTargets;
-    VkRenderPass compositeRenderPass = VK_NULL_HANDLE;
+    VkRenderPass compositeRenderPass = VK_NULL_HANDLE;  // CLEAR -> GENERAL
     uint32_t     compositeW = 0, compositeH = 0;
-    uint32_t     compositeIndex = 0;
-    bool         compositeArmed = false;
-    bool         swapchainTransferDst = false;
+    uint32_t     compositeIndex = 0;      // rotates per composite; gives history for free
+    bool         compositeArmed = false;  // targets exist AND this frame uses them
+    bool         swapchainTransferDst = false; // swapchain was created with TRANSFER_DST
 
+    // Set from the app when the native LSFG engine is selected for this
+    // session. Read on the render thread; false keeps every path as it was.
     std::atomic<bool> fgArmed_{false};
     std::atomic<int>  fgMultiplier_{0};
+    // Tuning is written by the UI thread and consumed by the render thread, so
+    // it is published through atomics and applied to the engine at the top of
+    // the frame-gen block. The UI thread never touches the engine itself.
     std::atomic<float> fgFlowScale_{1.0f};
     std::atomic<float> fgRefreshHz_{0.0f};
     std::atomic<bool>  fgConfigDirty_{true};
+    // Experimental (see setFrameGenTuning): capture height of the composite
+    // ring. 0 = panel resolution, kFgCaptureGame = the X screen's height.
     std::atomic<int32_t> fgCaptureHeight_{0};
+    // Extent the composite ring should have for the current swapchain and
+    // capture height (width follows the swapchain aspect, both even).
     void compositeExtentFor(uint32_t& w, uint32_t& h) const;
+    // The extent the scene is rendered at this frame: the composite ring while
+    // frame gen runs on a ring smaller than the swapchain (experimental capture
+    // resolution), otherwise the swapchain. Every full-target pass (the effect
+    // chain, the spatial upscalers, the render-scale downscale) sizes itself by
+    // this, so those keep working below panel resolution and their
+    // intermediates shrink with the ring.
     VkExtent2D renderExtent() const {
         if (compositeActive() && (compositeW != swapchainExt.width || compositeH != swapchainExt.height))
             return VkExtent2D{compositeW, compositeH};
         return swapchainExt;
     }
+    // Copy (same extent) or blit (composite smaller than the swapchain) a
+    // composite-ring image, already in TRANSFER_SRC, into a swapchain image
+    // already in TRANSFER_DST.
     void recordCompositeToSwapchainTransfer(VkCommandBuffer cb, VkImage src, uint32_t imgIdx);
 
     bool  createCompositeRenderPass();
     bool  ensureCompositeTargets(uint32_t w, uint32_t h, uint32_t count);
     void  destroyCompositeTargets();
+    // True when this frame should composite off-swapchain. Call on the render
+    // thread; every gate must hold or we fall back to the untouched path.
     bool  compositeActive() const;
+    // Render pass / framebuffer this frame draws its FINAL pass into.
     VkRenderPass  targetRenderPass() const;
     VkFramebuffer targetFramebuffer(uint32_t imgIdx) const;
+    // Copy the finished composite into the acquired swapchain image and leave
+    // it in PRESENT_SRC. No-op when the composite path is not active.
     void  copyCompositeToSwapchain(VkCommandBuffer cb, uint32_t imgIdx);
 
+    // === Native LSFG: the software cursor ====================================
+    // LSFG interpolates whatever it is given, so a cursor composited into the
+    // frame gets warped along the flow field and smears. It is therefore
+    // excluded from the composite while frame gen is armed and drawn once into
+    // EVERY presented image instead - real and generated alike - through a
+    // load-op render pass that leaves the image ready to present.
     VkRenderPass cursorOverlayRenderPass = VK_NULL_HANDLE;
     struct CursorOverlay {
         bool  draw = false;
@@ -448,16 +569,19 @@ private:
     CursorOverlay cursorOverlay_{};
 
     bool createCursorOverlayRenderPass();
+    // Draw the cursor into an already-copied swapchain image and leave it in
+    // PRESENT_SRC. Takes over the final transition from the copy helpers.
     void recordCursorOverlay(VkCommandBuffer cb, uint32_t imgIdx);
+    // True when the cursor is being drawn per present rather than composited.
     bool cursorDrawnPerPresent() const;
 
-
-
-
-
-
-
-    static constexpr uint32_t kMaxPresentsPerFrame = 4;
+    // === Native LSFG: the per-source-frame present plan =======================
+    // Interpolation produces frames that belong BETWEEN N-1 and N, so the
+    // generated frames are presented FIRST and real frame N is held back one
+    // slot. All presents for one source frame are queued together: with FIFO
+    // the driver then shows them on consecutive vblanks, so the pacing falls
+    // out of the present mode for free - no sleeps, no render-mode change.
+    static constexpr uint32_t kMaxPresentsPerFrame = 4;   // 1 real + up to 3 generated
     struct FrameGenPlan {
         uint32_t generations = 0;
         uint32_t presents    = 1;
@@ -468,19 +592,32 @@ private:
     uint64_t    fgSourceFrames_ = 0;
     std::string lsfgCachePath_;
     bool        lsfgEngineTried_ = false;
-    std::unique_ptr<ddfg::Engine> ddfgEngine_;
-    bool        ddfgEngineTried_ = false;
-    std::atomic<int> fgEngineKind_{0};
+    std::unique_ptr<winfg::Engine> winfgEngine_;
+    bool        winfgEngineTried_ = false;
+    std::atomic<int> fgEngineKind_{0};     // 0 = lsfg, 1 = win-fg
     std::atomic<int> fgModel_{4};
     std::atomic<int> fgPerfPreset_{1};
-    bool ensureDdFgEngine();
+    bool ensureWinFgEngine();
+    // Capability gate for the SELECTED engine. win-fg's shaders need only a
+    // storage-capable swapchain format; the LSFG chain also needs the fp16 /
+    // memory-model feature set, which some otherwise capable GPUs lack.
     bool fgCapsOk() const;
 
+    // Sync objects are indexed per PRESENT, not per composite: each pending
+    // present needs its own image-available and render-finished semaphore.
     uint32_t syncSlot(uint32_t k) const { return currentFrame * kMaxPresentsPerFrame + k; }
+    // Destroy and rebuild every acquire/present semaphore. Called with the
+    // swapchain, so no stale pending signal can survive into the new one.
     void recreateSyncObjects();
     uint32_t fgAcquireFailLog_ = 0;
 
+    // Measured PRESENTS per second - the rate that actually reaches the panel,
+    // counting generated frames. The pacer's own "loop rate" cannot serve this
+    // purpose: it is sampled once per SOURCE frame, so it always equals the
+    // guest rate and contains no evidence that generation happened at all.
     float    fgPresentedRate_   = 0.0f;
+    // Measured SOURCE frames per second over the same window, for engines that
+    // do not measure it themselves (win-fg).
     float    fgSourceRate_      = 0.0f;
     uint32_t fgSourceAccum_     = 0;
     uint32_t fgPresentAccum_    = 0;
@@ -489,10 +626,22 @@ private:
     void     trackPresentedRate(uint32_t presents);
 
     bool ensureLsfgEngine();
+    // One command buffer per pending present: slot 0 carries the composite,
+    // the chain's shared passes and generated frame 0; each later generated
+    // frame and the real frame are recorded and submitted on their own, so a
+    // finished frame reaches the presentation engine without waiting for the
+    // rest of the chain.
     uint32_t cmdSlot(uint32_t k) const { return currentFrame * kMaxPresentsPerFrame + k; }
+    // Shared chain passes (the 24 shaders every generated frame depends on).
     void recordFrameGenProcess(VkCommandBuffer cb);
+    // Generated frame g: synthesise into a spare composite target and copy it
+    // into the swapchain image reserved for it.
     void recordFrameGenGeneration(VkCommandBuffer cb, uint32_t g);
 
+    // Chain cost: a timestamp pair per frame slot, start before the shared
+    // passes, end after the last generation's compute (before its copy, so a
+    // vblank wait on the swapchain image is not counted). Read back after the
+    // slot's fence wait, one frame later.
     VkQueryPool fgQueryPool_        = VK_NULL_HANDLE;
     bool        fgTimestampsOk_     = false;
     float       fgTimestampPeriodNs_ = 0.0f;
@@ -505,21 +654,22 @@ private:
     void readFgQueryResult();
 
     VkFormat          offscreenFmt      = VK_FORMAT_R8G8B8A8_UNORM;
-    VkRenderPass      offscreenRenderPass = VK_NULL_HANDLE;
+    VkRenderPass      offscreenRenderPass = VK_NULL_HANDLE; // CLEAR -> SHADER_READ_ONLY
     VkPipelineLayout  postPipeLayout    = VK_NULL_HANDLE;
     VkPipeline        sgsrPipeline      = VK_NULL_HANDLE;
-    VkPipeline        nisPipeline       = VK_NULL_HANDLE;
-    VkPipeline        sgsrQualityPipeline = VK_NULL_HANDLE;
+    VkPipeline        nisPipeline       = VK_NULL_HANDLE; // NVIDIA Image Scaling (mode 7)
+    VkPipeline        sgsrQualityPipeline = VK_NULL_HANDLE; // SGSR 1 edge-direction (mode 8)
     VkPipeline        easuPipeline      = VK_NULL_HANDLE;
     VkPipeline        rcasPipeline      = VK_NULL_HANDLE;
     VkPipeline        downscalePipeline = VK_NULL_HANDLE;
-
-
-
-    VkPipeline        casPipelineOff    = VK_NULL_HANDLE;
-    VkPipeline        casPipelineSwap   = VK_NULL_HANDLE;
+    // CAS/HDR can be either a non-final pass (writes an fx target via
+    // offscreenRenderPass) or the final pass (writes the swapchain via renderPass);
+    // a pipeline is render-pass-specific, so keep one variant of each.
+    VkPipeline        casPipelineOff    = VK_NULL_HANDLE; // -> fx target (offscreenRenderPass)
+    VkPipeline        casPipelineSwap   = VK_NULL_HANDLE; // -> swapchain (renderPass)
     VkPipeline        hdrPipelineOff    = VK_NULL_HANDLE;
     VkPipeline        hdrPipelineSwap   = VK_NULL_HANDLE;
+    // Phase 2 effects: same Off (-> fx target) / Swap (-> swapchain) variant pair.
     VkPipeline        fxaaPipelineOff   = VK_NULL_HANDLE;
     VkPipeline        fxaaPipelineSwap  = VK_NULL_HANDLE;
     VkPipeline        toonPipelineOff   = VK_NULL_HANDLE;
@@ -530,8 +680,10 @@ private:
     VkPipeline        ntscPipelineSwap  = VK_NULL_HANDLE;
     VkPipeline        crtPipelineOff    = VK_NULL_HANDLE;
     VkPipeline        crtPipelineSwap   = VK_NULL_HANDLE;
+    // Debanding is always the LAST effect (terminal) -> only a swapchain variant.
     VkPipeline        debandPipelineSwap = VK_NULL_HANDLE;
 
+    // offscreen composite target @ game/container resolution
     VkImage           offscreenImg  = VK_NULL_HANDLE;
     VkDeviceMemory    offscreenMem  = VK_NULL_HANDLE;
     VkImageView       offscreenView = VK_NULL_HANDLE;
@@ -539,6 +691,7 @@ private:
     VkDescriptorSet   offscreenDS   = VK_NULL_HANDLE;
     int               offscreenW = 0, offscreenH = 0;
 
+    // FSR intermediate (EASU output) @ upscale output resolution
     VkImage           midImg  = VK_NULL_HANDLE;
     VkDeviceMemory    midMem  = VK_NULL_HANDLE;
     VkImageView       midView = VK_NULL_HANDLE;
@@ -546,6 +699,8 @@ private:
     VkDescriptorSet   midDS   = VK_NULL_HANDLE;
     int               midW = 0, midH = 0;
 
+    // Effect-chain intermediates @ swapchain resolution. fx1 holds the scaled (or
+    // composited) image fed into CAS/HDR; fx2 ping-pongs when both effects run.
     VkImage           fx1Img  = VK_NULL_HANDLE;
     VkDeviceMemory    fx1Mem  = VK_NULL_HANDLE;
     VkImageView       fx1View = VK_NULL_HANDLE;
@@ -560,18 +715,21 @@ private:
     VkDescriptorSet   fx2DS   = VK_NULL_HANDLE;
     int               fx2W = 0, fx2H = 0;
 
+    // Per-frame upscale plan, computed in renderFrame, consumed by recordCmdBuf.
+    // upFrame.mode reuses the upscalerMode enum (3=sgsr,4=fsr,5=fsr_fit,6=sharpen,7=nis,8=sgsr_quality)
+    // plus an internal sentinel (UPMODE_DOWNSCALE) for the supersampling path.
     struct UpscaleFrame {
         bool active = false;
         int  mode = 0;
         int  outX = 0, outY = 0, outW = 0, outH = 0;
-        bool cas = false;
-        bool hdr = false;
-        bool fxaa = false;
-        bool toon = false;
-        bool color = false;
-        bool ntsc = false;
-        bool crt = false;
-        bool deband = false;
+        bool cas = false;   // run CAS this frame (snapshot of casEnabled)
+        bool hdr = false;   // run HDR this frame (snapshot of hdrEnabled)
+        bool fxaa = false;  // snapshot of fxaaEnabled
+        bool toon = false;  // snapshot of toonEnabled
+        bool color = false; // snapshot of colorEnabled (non-neutral grade)
+        bool ntsc = false;  // snapshot of ntscEnabled
+        bool crt = false;   // snapshot of crtEnabled
+        bool deband = false;// snapshot of debandEnabled (terminal dither)
         SgsrPushConstants      sgsrPC{};
         NisPushConstants       nisPC{};
         EasuPushConstants      easuPC{};

app/src/main/cpp/framegen/ddfg/config.hpp

@@ -1,295 +0,0 @@
-#pragma once
-#include <cstdint>
-#include <cstdlib>
-#include <cstring>
-#include <string>
-#include <fstream>
-#include <sstream>
-
-namespace ddfg {
-
-struct Config {
-    bool     enabled     = false;
-
-
-
-
-
-
-
-    bool     debug       = false;
-    bool     pacing      = false;
-    int      model       = 4;
-    int      multiplier  = 2;
-
-
-
-
-
-
-
-
-
-
-
-
-
-    int      extraImages = 2;
-
-
-
-
-
-
-
-
-
-
-
-    int      perfPreset  = 1;
-    float    flowScale   = 1.0f;
-
-
-
-
-
-
-    int      gmMode      = 0;
-
-
-
-
-
-
-
-
-
-    int      frMode      = 0;
-    int      frIters     = 4;
-    float    frLambda    = 2.0f;
-    float    frDt        = 0.25f;
-    float    frEdge      = 8.0f;
-    float    frEps       = 0.05f;
-
-    float    beta        = 8.0f;
-    float    lambda      = 0.6f;
-
-
-
-
-
-
-
-
-
-
-    float    epsilon     = 0.07f;
-    float    photoScale  = 7.5f;
-
-
-
-
-
-
-    float    hudX0       = 0.0f;
-    float    hudY0       = 0.0f;
-    float    hudX1       = 0.0f;
-    float    hudY1       = 0.0f;
-
-    bool     capture       = false;
-    int      captureW      = 1280;
-    int      captureH      = 720;
-    int      capMode       = 0;
-    int      capPatches    = 3;
-    int      capPatchSize  = 256;
-
-
-    float    capMotion     = 2.0f;
-    std::string capDir;
-    int      capShardMB    = 1024;
-
-    void sanitize() {
-        if (model < 3) model = 3; if (model > 4) model = 4;
-        if (multiplier < 2) multiplier = 2; if (multiplier > 4) multiplier = 4;
-        if (extraImages < 0) extraImages = 0; if (extraImages > 8) extraImages = 8;
-        if (perfPreset < 0 || perfPreset > 2) perfPreset = 1;
-        if (gmMode < 0) gmMode = 0; if (gmMode > 2) gmMode = 2;
-        if (frMode < 0) frMode = 0; if (frMode > 2) frMode = 2;
-        if (frIters < 0) frIters = 0; if (frIters > 16) frIters = 16;
-        if (frLambda < 0.0f) frLambda = 0.0f;
-        if (frDt < 0.01f) frDt = 0.01f; if (frDt > 4.0f) frDt = 4.0f;
-        if (frEdge < 0.0f) frEdge = 0.0f;
-        if (frEps < 1e-3f) frEps = 1e-3f;
-        if (flowScale < 0.05f) flowScale = 0.05f; if (flowScale > 4.0f) flowScale = 4.0f;
-        if (beta < 0.0f) beta = 0.0f; if (lambda < 0.0f) lambda = 0.0f;
-        if (captureW < 16) captureW = 16; if (captureW > 7680) captureW = 7680;
-        if (captureH < 16) captureH = 16; if (captureH > 4320) captureH = 4320;
-        if (capMode < 0) capMode = 0; if (capMode > 1) capMode = 1;
-        if (capPatches < 1) capPatches = 1; if (capPatches > 16) capPatches = 16;
-        if (capPatchSize < 16) capPatchSize = 16; if (capPatchSize > 1024) capPatchSize = 1024;
-        if (capMotion < 0.0f) capMotion = 0.0f;
-        if (capShardMB < 16) capShardMB = 16; if (capShardMB > 65536) capShardMB = 65536;
-    }
-};
-
-static inline float envf(const char* k, float d) {
-    const char* v = std::getenv(k); return v ? std::strtof(v, nullptr) : d;
-}
-static inline int envi(const char* k, int d) {
-    const char* v = std::getenv(k); return v ? std::atoi(v) : d;
-}
-
-static inline int parse_tristate(const std::string& v, int dflt) {
-    if (v.empty()) return dflt;
-    if (v == "auto") return 0;
-    if (v == "on"  || v == "1" || v == "force" || v == "true"  || v == "yes") return 1;
-    if (v == "off" || v == "0" || v == "false" || v == "no")                  return 2;
-    return dflt;
-}
-
-static inline bool parse_bool(const std::string& v, bool dflt) {
-    int t = parse_tristate(v, dflt ? 1 : 2);
-    return t == 1;
-}
-static inline int parse_capmode(const std::string& v, int dflt) {
-    if (v == "patch" || v == "patches" || v == "0") return 0;
-    if (v == "frame" || v == "frames"  || v == "1") return 1;
-    return dflt;
-}
-
-static inline void apply_toml(Config& c, const std::string& path) {
-    std::ifstream f(path);
-    if (!f) return;
-    std::string line;
-    while (std::getline(f, line)) {
-        auto h = line.find('#'); if (h != std::string::npos) line = line.substr(0, h);
-        auto eq = line.find('='); if (eq == std::string::npos) continue;
-        auto trim = [](std::string s){
-            size_t a = s.find_first_not_of(" \t\r\n"); size_t b = s.find_last_not_of(" \t\r\n");
-            return (a == std::string::npos) ? std::string() : s.substr(a, b - a + 1); };
-        std::string k = trim(line.substr(0, eq)), v = trim(line.substr(eq + 1));
-        if (k.empty() || v.empty()) continue;
-        if      (k == "enabled")    c.enabled = (v == "1" || v == "true");
-        else if (k == "debug")      c.debug = parse_bool(v, c.debug);
-        else if (k == "pacing")     c.pacing = parse_bool(v, c.pacing);
-        else if (k == "model")      c.model = std::atoi(v.c_str());
-        else if (k == "multiplier") c.multiplier = std::atoi(v.c_str());
-        else if (k == "extra_images") c.extraImages = std::atoi(v.c_str());
-        else if (k == "perf_preset") c.perfPreset = std::atoi(v.c_str());
-        else if (k == "global_motion") c.gmMode = parse_tristate(v, c.gmMode);
-        else if (k == "flow_reg")   c.frMode = parse_tristate(v, c.frMode);
-        else if (k == "fr_iters")   c.frIters = std::atoi(v.c_str());
-        else if (k == "fr_lambda")  c.frLambda = std::strtof(v.c_str(), nullptr);
-        else if (k == "fr_dt")      c.frDt = std::strtof(v.c_str(), nullptr);
-        else if (k == "fr_edge")    c.frEdge = std::strtof(v.c_str(), nullptr);
-        else if (k == "fr_eps")     c.frEps = std::strtof(v.c_str(), nullptr);
-        else if (k == "flowScale")  c.flowScale = std::strtof(v.c_str(), nullptr);
-        else if (k == "beta")       c.beta = std::strtof(v.c_str(), nullptr);
-        else if (k == "lambda")     c.lambda = std::strtof(v.c_str(), nullptr);
-        else if (k == "epsilon")    c.epsilon = std::strtof(v.c_str(), nullptr);
-        else if (k == "photoScale") c.photoScale = std::strtof(v.c_str(), nullptr);
-        else if (k == "capture")        c.capture = parse_bool(v, c.capture);
-        else if (k == "capture_dir")    c.capDir = v;
-        else if (k == "capture_width")  c.captureW = std::atoi(v.c_str());
-        else if (k == "capture_height") c.captureH = std::atoi(v.c_str());
-        else if (k == "capture_mode")   c.capMode = parse_capmode(v, c.capMode);
-        else if (k == "capture_patches")    c.capPatches = std::atoi(v.c_str());
-        else if (k == "capture_patch_size") c.capPatchSize = std::atoi(v.c_str());
-        else if (k == "capture_motion")     c.capMotion = std::strtof(v.c_str(), nullptr);
-        else if (k == "capture_shard_mb")   c.capShardMB = std::atoi(v.c_str());
-        else if (k == "hudRect") {
-            float r[4] = {0,0,0,0}; int n = 0;
-            size_t start = 0; std::string s = v;
-            for (; n < 4; ++n) {
-                size_t comma = s.find(',', start);
-                std::string tok = s.substr(start, comma == std::string::npos ? std::string::npos : comma - start);
-                r[n] = std::strtof(tok.c_str(), nullptr);
-                if (comma == std::string::npos) break;
-                start = comma + 1;
-            }
-            c.hudX0 = r[0]; c.hudY0 = r[1]; c.hudX1 = r[2]; c.hudY1 = r[3];
-        }
-    }
-}
-
-static inline std::string conf_path() {
-    if (const char* p = std::getenv("DD_FG_CONF")) return p;
-    const char* home = std::getenv("HOME");
-    return home ? std::string(home) + "/.config/dd-fg/conf.toml" : std::string();
-}
-
-static inline std::string capture_root(const Config& c) {
-    if (!c.capDir.empty()) return c.capDir;
-    if (const char* home = std::getenv("HOME")) return std::string(home) + "/.cache/ddfg-capture";
-    return std::string("/tmp/ddfg-capture");
-}
-
-static inline Config load_config() {
-    Config c;
-    c.enabled    = envi("DD_FG_ENABLE", 0) != 0;
-    if (const char* d = std::getenv("DD_FG_DEBUG")) c.debug = parse_bool(d, c.debug);
-    if (const char* pc = std::getenv("DD_FG_PACING")) c.pacing = parse_bool(pc, c.pacing);
-    c.model      = envi("DD_FG_MODEL", c.model);
-    c.multiplier = envi("DD_FG_MULT", c.multiplier);
-    c.extraImages = envi("DD_FG_EXTRA_IMAGES", c.extraImages);
-    c.perfPreset  = envi("DD_FG_PERF_PRESET", c.perfPreset);
-    if (const char* g = std::getenv("DD_FG_GM")) c.gmMode = parse_tristate(g, c.gmMode);
-    if (const char* r = std::getenv("DD_FG_FLOWREG")) c.frMode = parse_tristate(r, c.frMode);
-    c.frIters    = envi("DD_FG_FR_ITERS", c.frIters);
-    c.frLambda   = envf("DD_FG_FR_LAMBDA", c.frLambda);
-    c.frDt       = envf("DD_FG_FR_DT", c.frDt);
-    c.frEdge     = envf("DD_FG_FR_EDGE", c.frEdge);
-    c.frEps      = envf("DD_FG_FR_EPS", c.frEps);
-    c.flowScale  = envf("DD_FG_FLOWSCALE", c.flowScale);
-    c.beta       = envf("DD_FG_BETA", c.beta);
-    c.lambda     = envf("DD_FG_LAMBDA", c.lambda);
-    c.epsilon    = envf("DD_FG_EPSILON", c.epsilon);
-    c.photoScale = envf("DD_FG_PHOTOSCALE", c.photoScale);
-    if (const char* cc = std::getenv("DD_FG_CAPTURE")) c.capture = parse_bool(cc, c.capture);
-    c.captureW     = envi("DD_FG_CAPTURE_W", c.captureW);
-    c.captureH     = envi("DD_FG_CAPTURE_H", c.captureH);
-    if (const char* cm = std::getenv("DD_FG_CAPTURE_MODE")) c.capMode = parse_capmode(cm, c.capMode);
-    c.capPatches   = envi("DD_FG_CAPTURE_PATCHES", c.capPatches);
-    c.capPatchSize = envi("DD_FG_CAPTURE_PATCH", c.capPatchSize);
-    c.capMotion    = envf("DD_FG_CAPTURE_MOTION", c.capMotion);
-    c.capShardMB   = envi("DD_FG_CAPTURE_SHARD_MB", c.capShardMB);
-    if (const char* cd = std::getenv("DD_FG_CAPTURE_DIR")) c.capDir = cd;
-    if (const char* h = std::getenv("DD_FG_HUD_RECT")) {
-        float r[4] = {0,0,0,0}; int n = 0;
-        std::string s = h; size_t start = 0;
-        for (; n < 4; ++n) {
-            size_t comma = s.find(',', start);
-            r[n] = std::strtof(s.substr(start, comma == std::string::npos ? std::string::npos : comma - start).c_str(), nullptr);
-            if (comma == std::string::npos) break;
-            start = comma + 1;
-        }
-        c.hudX0 = r[0]; c.hudY0 = r[1]; c.hudX1 = r[2]; c.hudY1 = r[3];
-    }
-    const char* home = std::getenv("HOME");
-    if (home) apply_toml(c, std::string(home) + "/.config/dd-fg/conf.toml");
-    if (const char* p = std::getenv("DD_FG_CONF")) apply_toml(c, p);
-    c.sanitize();
-    return c;
-}
-
-struct SynthUBO {
-    float flowScale, alpha, beta, lambda, epsilon, photoScale, pad0, pad1;
-    float hudX0, hudY0, hudX1, hudY1;
-};
-struct FlowUBO { float flowScale; uint32_t level; float occlLo; float occlHi; };
-
-struct GMUBO {
-    float lin[4];
-    float linT[4];
-    float app[4];
-    float appT[4];
-};
-
-struct FlowRegUBO {
-    float dt;
-    float lambda;
-    float edgeAlpha;
-    float epsTV;
-};
-
-}

app/src/main/cpp/framegen/ddfg/ddfg_engine.h

@@ -1,69 +0,0 @@
-#pragma once
-#include <cstdint>
-#include <vulkan/vulkan.h>
-#include "framegen.hpp"
-#include "vk_dispatch.hpp"
-
-struct VkTable;
-
-namespace ddfg {
-
-constexpr uint32_t kMaxGenerations = 3;
-
-class Engine {
-public:
-    Engine();
-    ~Engine();
-    Engine(const Engine&) = delete;
-    Engine& operator=(const Engine&) = delete;
-
-    bool init(const VkTable& table, VkPhysicalDevice phys, VkDevice dev,
-              uint32_t queueFamily, VkQueue queue);
-    bool valid() const { return fg_.valid() && !unavailable_; }
-    bool unavailable() const { return unavailable_; }
-
-    void configure(uint32_t multiplier, int model, int perfPreset, float flowScale);
-
-    bool prepare(uint32_t width, uint32_t height, VkFormat format);
-
-    uint32_t plan(uint32_t capacity) const;
-
-    void process(VkCommandBuffer cmd, VkImage source, uint32_t width, uint32_t height,
-                 uint32_t generations);
-
-    void generateInto(VkCommandBuffer cmd, uint32_t generation, uint32_t count,
-                      VkImage targetImage, VkImageView targetView,
-                      uint32_t width, uint32_t height);
-
-    void reset();
-
-private:
-    struct Slot { VkImage img = VK_NULL_HANDLE; VkDeviceMemory mem = VK_NULL_HANDLE;
-                  VkImageView view = VK_NULL_HANDLE; bool valid = false; };
-    bool  makeSlot(Slot& s, uint32_t w, uint32_t h, VkFormat fmt);
-    void  destroySlot(Slot& s);
-    void  destroyRing();
-    uint32_t memType(uint32_t bits, VkMemoryPropertyFlags props) const;
-
-    DeviceDispatch   dd_{};
-    InstanceDispatch id_{};
-    VkPhysicalDevice phys_ = VK_NULL_HANDLE;
-    VkDevice         dev_  = VK_NULL_HANDLE;
-    uint32_t         qf_   = 0;
-    VkQueue          queue_ = VK_NULL_HANDLE;
-    VkPhysicalDeviceMemoryProperties memProps_{};
-
-    FrameGen fg_;
-    Config   cfg_;
-    bool     unavailable_ = false;
-
-    Slot     ring_[2];
-    int      curr_ = 0;
-    uint32_t history_ = 0;
-    uint32_t gmSlot_ = 0;
-    uint32_t builtW_ = 0, builtH_ = 0;
-    VkFormat builtFmt_ = VK_FORMAT_UNDEFINED;
-    uint64_t frames_ = 0;
-};
-
-}

app/src/main/cpp/framegen/ddfg/ddfg_vkd.h

@@ -1,4 +0,0 @@
-#pragma once
-#include "vk_dispatch.hpp"
-struct VkTable;
-bool ddfgVkdInit(const VkTable& table, ddfg::DeviceDispatch& dd, ddfg::InstanceDispatch& id);

app/src/main/cpp/framegen/ddfg/framegen.hpp

@@ -1,112 +0,0 @@
-#pragma once
-#include "vk_dispatch.hpp"
-#include "config.hpp"
-#include <vector>
-
-namespace ddfg {
-
-class FrameGen {
-public:
-    bool init(const DeviceDispatch* dd, const InstanceDispatch* id,
-              VkPhysicalDevice phys, VkDevice dev, uint32_t queueFamily, VkQueue queue);
-    void configure(const Config& c);
-    bool onResize(VkExtent2D extent, VkFormat colorFormat, bool force = false);
-    void record(VkCommandBuffer cmd, VkImageView prevView, VkImageView currView,
-                VkImageView outView, float alpha, uint32_t gmSlot = 0,
-                uint32_t synthSlot = 0, bool reuseFlow = false);
-    void destroy();
-    bool valid() const { return device_ != VK_NULL_HANDLE && ready_; }
-    const Config& config() const { return cfg_; }
-
-    struct Img { VkImage image = VK_NULL_HANDLE; VkDeviceMemory mem = VK_NULL_HANDLE;
-                 VkImageView view = VK_NULL_HANDLE; VkExtent2D extent{}; VkFormat fmt{}; };
-    struct Pipe { VkPipeline pipeline = VK_NULL_HANDLE; VkPipelineLayout layout = VK_NULL_HANDLE;
-                  VkDescriptorSetLayout setLayout = VK_NULL_HANDLE; VkShaderModule module = VK_NULL_HANDLE; };
-
-
-
-    static constexpr int kGmSlots   = 3;
-    static constexpr int kSynthSlots = 3;
-    static constexpr int kGmLevel   = 3;
-    static constexpr int kGmThreads = 512;
-    static constexpr int kGmStride  = 32;
-
-
-
-
-
-
-
-    static constexpr int kFlowFinestDefault = 2;
-
-
-
-    static int flowFinestForPreset(int preset) {
-        switch (preset) {
-            case 0: return 1;
-            case 2: return 3;
-            case 1: default: return kFlowFinestDefault;
-        }
-    }
-    int flowFinest() const { return flowFinest_; }
-
-private:
-    uint32_t findMemType(uint32_t bits, VkMemoryPropertyFlags props) const;
-    bool makeImage(Img& out, VkExtent2D ext, VkFormat fmt, VkImageUsageFlags usage);
-    void destroyImage(Img& i);
-    bool makeGmBuffers();
-
-
-
-    bool updateGlobalMotion(uint32_t gmSlot, VkExtent2D fullExtent);
-    bool makePipe(Pipe& p, int shaderId,
-                  const std::vector<VkDescriptorType>& bindings);
-    void destroyPipe(Pipe& p);
-    void barrier(VkCommandBuffer cmd, VkImage img, VkImageLayout from, VkImageLayout to);
-
-    const DeviceDispatch*   dd_ = nullptr;
-    const InstanceDispatch*  id_ = nullptr;
-    VkPhysicalDevice phys_ = VK_NULL_HANDLE;
-    VkDevice         device_ = VK_NULL_HANDLE;
-    VkQueue          queue_ = VK_NULL_HANDLE;
-    uint32_t         queueFamily_ = 0;
-    VkPhysicalDeviceMemoryProperties memProps_{};
-    VkSampler        linear_ = VK_NULL_HANDLE;
-    VkDescriptorPool descPool_ = VK_NULL_HANDLE;
-
-    Config    cfg_;
-    VkExtent2D extent_{};
-    bool ready_ = false;
-    int  flowFinest_ = kFlowFinestDefault;
-
-    Pipe pLuma_, pDown_, pFlow_, pFlowM4_, pExpand_, pExpandM4_, pSynth_;
-    Pipe pGmReduce_, pGmPrewarp_;
-    Pipe pFlowReg_;
-
-    static const int kLevels = 7;
-    std::vector<Img> pyrA_, pyrB_;
-    std::vector<Img> pyrAs_;
-    std::vector<Img> flowLvl_;
-    Img flowExpA_, flowExpB_;
-
-
-
-
-
-    Img flowRegA_, flowRegB_;
-
-    VkBuffer       gmSsbo_[kGmSlots]   {};
-    VkDeviceMemory gmSsboMem_[kGmSlots]{};
-    void*          gmSsboPtr_[kGmSlots]{};
-    bool           gmBuffersReady_ = false;
-    double gmRun_[6]              {};
-    double gmLinAt_[kGmSlots][6] {};
-    bool   gmSlotValid_[kGmSlots]{};
-    bool   gmHaveEst_      = false;
-    int    gmStableCount_  = 0;
-    bool   gmEngaged_      = false;
-    float  gmLastTransPx_  = 0.0f;
-    unsigned long long gmFrames_ = 0;
-};
-
-}

app/src/main/cpp/framegen/ddfg/log.hpp

@@ -1,12 +0,0 @@
-#pragma once
-#if defined(__ANDROID__)
-  #include <android/log.h>
-  #define DDFG_LOGI(...) __android_log_print(ANDROID_LOG_INFO,  "dd-fg", __VA_ARGS__)
-  #define DDFG_LOGE(...) __android_log_print(ANDROID_LOG_ERROR, "dd-fg", __VA_ARGS__)
-#else
-  #include <cstdio>
-  #define DDFG_LOGI(...) do { std::fprintf(stderr, "[dd-fg] " __VA_ARGS__); std::fprintf(stderr, "\n"); } while(0)
-  #define DDFG_LOGE(...) do { std::fprintf(stderr, "[dd-fg][E] " __VA_ARGS__); std::fprintf(stderr, "\n"); } while(0)
-#endif
-
-#define DDFG_LOGD(cond, ...) do { if (cond) DDFG_LOGI(__VA_ARGS__); } while(0)

app/src/main/cpp/framegen/ddfg/record_impl.inc

@@ -1,538 +0,0 @@
-
-namespace {
-struct ScratchState {
-    VkBuffer synthUbo[ddfg::FrameGen::kSynthSlots]{};
-    VkDeviceMemory synthUboMem[ddfg::FrameGen::kSynthSlots]{};
-    void* synthUboPtr[ddfg::FrameGen::kSynthSlots]{};
-    std::vector<VkBuffer> flowUbo; std::vector<VkDeviceMemory> flowUboMem; std::vector<void*> flowUboPtr;
-    VkBuffer expandUbo = VK_NULL_HANDLE; VkDeviceMemory expandUboMem = VK_NULL_HANDLE; void* expandUboPtr = nullptr;
-    VkBuffer flowRegUbo = VK_NULL_HANDLE; VkDeviceMemory flowRegUboMem = VK_NULL_HANDLE; void* flowRegUboPtr = nullptr;
-    VkBuffer gmUbo[ddfg::FrameGen::kGmSlots]{};
-    VkDeviceMemory gmUboMem[ddfg::FrameGen::kGmSlots]{};
-    void* gmUboPtr[ddfg::FrameGen::kGmSlots]{};
-    VkDescriptorSet sLumaCurr = VK_NULL_HANDLE, sLumaPrev = VK_NULL_HANDLE;
-    std::vector<VkDescriptorSet> sDownA, sDownB, sFlow;
-    VkDescriptorSet sExpand[ddfg::FrameGen::kGmSlots]{};
-
-
-
-    VkDescriptorSet sFlowReg0 = VK_NULL_HANDLE, sFlowRegAB = VK_NULL_HANDLE, sFlowRegBA = VK_NULL_HANDLE;
-    VkDescriptorSet sSynth[ddfg::FrameGen::kSynthSlots]{};
-    VkDescriptorSet sGmReduce[ddfg::FrameGen::kGmSlots]{};
-    std::vector<VkDescriptorSet> sGmPrewarp[ddfg::FrameGen::kGmSlots];
-    VkExtent2D builtFor{0,0};
-    bool built = false;
-    bool flowInited = false;
-    bool flowReady = false;
-};
-ScratchState g_scratch;
-}
-
-static bool makeUbo(const ddfg::DeviceDispatch* dd, VkDevice dev,
-                    const VkPhysicalDeviceMemoryProperties& mp,
-                    VkDeviceSize size, VkBuffer& buf, VkDeviceMemory& mem, void*& ptr) {
-    VkBufferCreateInfo bi{VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO};
-    bi.size = size; bi.usage = VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT; bi.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
-    if (dd->CreateBuffer(dev, &bi, nullptr, &buf) != VK_SUCCESS) return false;
-    VkMemoryRequirements mr; dd->GetBufferMemoryRequirements(dev, buf, &mr);
-    uint32_t idx = 0; VkMemoryPropertyFlags want = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
-    for (uint32_t i = 0; i < mp.memoryTypeCount; ++i)
-        if ((mr.memoryTypeBits & (1u<<i)) && (mp.memoryTypes[i].propertyFlags & want) == want) { idx = i; break; }
-    VkMemoryAllocateInfo ai{VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO}; ai.allocationSize = mr.size; ai.memoryTypeIndex = idx;
-    if (dd->AllocateMemory(dev, &ai, nullptr, &mem) != VK_SUCCESS) return false;
-    if (dd->BindBufferMemory(dev, buf, mem, 0) != VK_SUCCESS) return false;
-    return dd->MapMemory(dev, mem, 0, size, 0, &ptr) == VK_SUCCESS;
-}
-
-static VkDescriptorSet allocSet(const ddfg::DeviceDispatch* dd, VkDevice dev,
-                                VkDescriptorPool pool, VkDescriptorSetLayout layout) {
-    VkDescriptorSetAllocateInfo ai{VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO};
-    ai.descriptorPool = pool; ai.descriptorSetCount = 1; ai.pSetLayouts = &layout;
-    VkDescriptorSet s = VK_NULL_HANDLE; dd->AllocateDescriptorSets(dev, &ai, &s); return s;
-}
-
-static void wImg(const ddfg::DeviceDispatch* dd, VkDevice dev, VkDescriptorSet set, uint32_t binding,
-                 VkDescriptorType type, VkImageView view, VkSampler samp, VkImageLayout layout) {
-    VkDescriptorImageInfo ii{}; ii.imageView = view; ii.sampler = samp; ii.imageLayout = layout;
-    VkWriteDescriptorSet w{VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET};
-    w.dstSet = set; w.dstBinding = binding; w.descriptorCount = 1; w.descriptorType = type; w.pImageInfo = &ii;
-    dd->UpdateDescriptorSets(dev, 1, &w, 0, nullptr);
-}
-static void wUbo(const ddfg::DeviceDispatch* dd, VkDevice dev, VkDescriptorSet set, uint32_t binding,
-                 VkBuffer buf, VkDeviceSize range) {
-    VkDescriptorBufferInfo bi{}; bi.buffer = buf; bi.range = range;
-    VkWriteDescriptorSet w{VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET};
-    w.dstSet = set; w.dstBinding = binding; w.descriptorCount = 1;
-    w.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER; w.pBufferInfo = &bi;
-    dd->UpdateDescriptorSets(dev, 1, &w, 0, nullptr);
-}
-static void wSsbo(const ddfg::DeviceDispatch* dd, VkDevice dev, VkDescriptorSet set, uint32_t binding,
-                  VkBuffer buf, VkDeviceSize range) {
-    VkDescriptorBufferInfo bi{}; bi.buffer = buf; bi.range = range;
-    VkWriteDescriptorSet w{VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET};
-    w.dstSet = set; w.dstBinding = binding; w.descriptorCount = 1;
-    w.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_BUFFER; w.pBufferInfo = &bi;
-    dd->UpdateDescriptorSets(dev, 1, &w, 0, nullptr);
-}
-
-static bool cholSolve6(double A[6][6], const double b[6], double x[6]) {
-    double L[6][6] = {{0}};
-    for (int i = 0; i < 6; ++i) {
-        for (int j = 0; j <= i; ++j) {
-            double s = A[i][j];
-            for (int k = 0; k < j; ++k) s -= L[i][k] * L[j][k];
-            if (i == j) {
-                if (s <= 1e-20) return false;
-                L[i][j] = std::sqrt(s);
-            } else {
-                L[i][j] = s / L[j][j];
-            }
-        }
-    }
-    double y[6];
-    for (int i = 0; i < 6; ++i) { double s = b[i]; for (int k = 0; k < i; ++k) s -= L[i][k]*y[k]; y[i] = s / L[i][i]; }
-    for (int i = 5; i >= 0; --i) { double s = y[i]; for (int k = i+1; k < 6; ++k) s -= L[k][i]*x[k]; x[i] = s / L[i][i]; }
-    return true;
-}
-static void affFromParams(const double p[6], double M[3][3]) {
-    M[0][0]=1.0+p[0]; M[0][1]=p[2];     M[0][2]=p[4];
-    M[1][0]=p[1];     M[1][1]=1.0+p[3]; M[1][2]=p[5];
-    M[2][0]=0.0;      M[2][1]=0.0;      M[2][2]=1.0;
-}
-static void paramsFromAff(const double M[3][3], double p[6]) {
-    p[0]=M[0][0]-1.0; p[2]=M[0][1]; p[4]=M[0][2];
-    p[1]=M[1][0];     p[3]=M[1][1]-1.0; p[5]=M[1][2];
-}
-static bool invAff(const double M[3][3], double out[3][3]) {
-    double a=M[0][0], b=M[0][1], tx=M[0][2], c=M[1][0], d=M[1][1], ty=M[1][2];
-    double det = a*d - b*c;
-    if (std::fabs(det) < 1e-12) return false;
-    double id = 1.0/det;
-    out[0][0]= d*id;  out[0][1]= -b*id; out[0][2]= (b*ty - d*tx)*id;
-    out[1][0]= -c*id; out[1][1]= a*id;  out[1][2]= (c*tx - a*ty)*id;
-    out[2][0]=0.0; out[2][1]=0.0; out[2][2]=1.0;
-    return true;
-}
-static void mulAff(const double A[3][3], const double B[3][3], double out[3][3]) {
-    for (int i = 0; i < 2; ++i)
-        for (int j = 0; j < 3; ++j)
-            out[i][j] = A[i][0]*B[0][j] + A[i][1]*B[1][j] + A[i][2]*B[2][j];
-    out[2][0]=0.0; out[2][1]=0.0; out[2][2]=1.0;
-}
-
-namespace ddfg {
-
-static bool ensureScratch(FrameGen* fg, const DeviceDispatch* dd, VkDevice dev,
-                          const VkPhysicalDeviceMemoryProperties& mp, VkDescriptorPool pool,
-                          VkSampler samp, VkExtent2D ext,
-                          std::vector<FrameGen::Img>& pyrA, std::vector<FrameGen::Img>& pyrB,
-                          std::vector<FrameGen::Img>& pyrAs,
-                          std::vector<FrameGen::Img>& flowLvl, FrameGen::Img& expA, FrameGen::Img& expB,
-                          const FrameGen::Pipe& pLuma, const FrameGen::Pipe& pDown,
-                          const FrameGen::Pipe& pFlow, const FrameGen::Pipe& pExpand,
-                          const FrameGen::Pipe& pSynth, const FrameGen::Pipe& pGmReduce,
-                          const FrameGen::Pipe& pGmPrewarp, const FrameGen::Pipe& pFlowReg,
-                          FrameGen::Img& flowRegA, FrameGen::Img& flowRegB, VkBuffer* gmSsbo,
-                          int kLevels, const Config& cfg);
-
-static void destroyScratch(const DeviceDispatch* dd, VkDevice dev, VkDescriptorPool pool) {
-    auto freeUbo = [&](VkBuffer& b, VkDeviceMemory& m, void*& p) {
-        if (m) dd->UnmapMemory(dev, m);
-        if (b) dd->DestroyBuffer(dev, b, nullptr);
-        if (m) dd->FreeMemory(dev, m, nullptr);
-        b = VK_NULL_HANDLE; m = VK_NULL_HANDLE; p = nullptr;
-    };
-    auto& S = g_scratch;
-    for (int s = 0; s < FrameGen::kSynthSlots; ++s) freeUbo(S.synthUbo[s], S.synthUboMem[s], S.synthUboPtr[s]);
-    freeUbo(S.expandUbo,  S.expandUboMem,  S.expandUboPtr);
-    freeUbo(S.flowRegUbo, S.flowRegUboMem, S.flowRegUboPtr);
-    for (size_t i = 0; i < S.flowUbo.size(); ++i) freeUbo(S.flowUbo[i], S.flowUboMem[i], S.flowUboPtr[i]);
-    for (int s = 0; s < FrameGen::kGmSlots; ++s) freeUbo(S.gmUbo[s], S.gmUboMem[s], S.gmUboPtr[s]);
-    if (pool && dd->ResetDescriptorPool) dd->ResetDescriptorPool(dev, pool, 0);
-    S = ScratchState{};
-}
-
-void FrameGen::configure(const Config& c) {
-    cfg_ = c; cfg_.sanitize();
-    int want = flowFinestForPreset(cfg_.perfPreset);
-    const int maxFinest = kLevels - 2;
-    if (want > maxFinest) {
-        DDFG_LOGE("perf-preset=%d wants kFlowFinest=%d but only %d pyramid levels exist "
-                 "(need >=2 solved) - clamping to %d", cfg_.perfPreset, want, kLevels, maxFinest);
-        want = maxFinest;
-    }
-    if (want < 1) want = 1;
-
-    const int prevFinest = flowFinest_;
-    flowFinest_ = want;
-    const bool live = (flowFinest_ != prevFinest) && ready_;
-    DDFG_LOGI("perf-preset=%d -> kFlowFinest=%d (was %d) live-rebuild=%d ready=%d",
-             cfg_.perfPreset, flowFinest_, prevFinest, live ? 1 : 0, ready_ ? 1 : 0);
-
-    if (!live) return;
-
-
-
-
-    dd_->DeviceWaitIdle(device_);
-    destroyScratch(dd_, device_, descPool_);
-    if (!onResize(extent_, VK_FORMAT_UNDEFINED,  true))
-        DDFG_LOGE("perf-preset live rebuild: onResize FAILED at %ux%u - FG disabled until next resize",
-                 extent_.width, extent_.height);
-    for (int i = 0; i < 6; ++i) gmRun_[i] = 0.0;
-    for (int s = 0; s < kGmSlots; ++s) { gmSlotValid_[s] = false; for (int i = 0; i < 6; ++i) gmLinAt_[s][i] = 0.0; }
-    gmHaveEst_ = false; gmEngaged_ = false; gmStableCount_ = 0; gmLastTransPx_ = 0.0f;
-    DDFG_LOGI("perf-preset live rebuild DONE (kFlowFinest=%d, flow predictor reset)", flowFinest_);
-}
-
-bool FrameGen::updateGlobalMotion(uint32_t gmSlot, VkExtent2D fullExtent) {
-    ++gmFrames_;
-    if (!gmBuffersReady_ || cfg_.gmMode == 2  ) {
-
-        gmEngaged_ = false; gmStableCount_ = 0;
-        for (int i = 0; i < 6; ++i) gmRun_[i] = 0.0;
-        for (int i = 0; i < 6; ++i) gmLinAt_[gmSlot][i] = gmRun_[i];
-        gmLastTransPx_ = 0.0f;
-        return false;
-    }
-
-    bool good = false;
-    if (gmSlotValid_[gmSlot]) {
-        const float* pt = (const float*)gmSsboPtr_[gmSlot];
-        double sums[32]; for (int k = 0; k < 32; ++k) sums[k] = 0.0;
-        for (int t = 0; t < kGmThreads; ++t) {
-            const float* row = pt + (size_t)t * kGmStride;
-            for (int k = 0; k < kGmStride; ++k) sums[k] += (double)row[k];
-        }
-        double coverage = sums[27];
-        double lvlpx = double((fullExtent.width >> kGmLevel) * (fullExtent.height >> kGmLevel));
-        double minCov = 0.03 * (lvlpx > 0 ? lvlpx : 1.0);
-        if (coverage > minCov && coverage > 64.0) {
-            double H[6][6]; int idx = 0;
-            for (int r = 0; r < 6; ++r) for (int c = r; c < 6; ++c) { H[r][c] = H[c][r] = sums[idx]; ++idx; }
-            double b[6]; for (int i = 0; i < 6; ++i) b[i] = sums[21 + i];
-            for (int i = 0; i < 6; ++i) H[i][i] += 1e-3 * H[i][i] + 1e-9;
-            double dp[6];
-            if (cholSolve6(H, b, dp)) {
-                bool bounded = std::fabs(dp[0]) < 0.5 && std::fabs(dp[1]) < 0.5 &&
-                               std::fabs(dp[2]) < 0.5 && std::fabs(dp[3]) < 0.5 &&
-                               std::fabs(dp[4]) < 0.25 && std::fabs(dp[5]) < 0.25;
-                if (bounded) {
-                    double Mlin[3][3], Md[3][3], Mdi[3][3], Mnew[3][3];
-                    affFromParams(gmLinAt_[gmSlot], Mlin);
-                    affFromParams(dp, Md);
-                    if (invAff(Md, Mdi)) {
-                        mulAff(Mlin, Mdi, Mnew);
-                        double pnew[6]; paramsFromAff(Mnew, pnew);
-                        bool sane = std::fabs(pnew[0]) < 0.6 && std::fabs(pnew[1]) < 0.6 &&
-                                    std::fabs(pnew[2]) < 0.6 && std::fabs(pnew[3]) < 0.6 &&
-                                    std::fabs(pnew[4]) < 0.5 && std::fabs(pnew[5]) < 0.5;
-                        if (sane) { for (int i = 0; i < 6; ++i) gmRun_[i] = pnew[i]; good = true; gmHaveEst_ = true; }
-                    }
-                }
-            }
-        }
-    }
-
-    if (good) ++gmStableCount_; else gmStableCount_ = 0;
-
-    switch (cfg_.gmMode) {
-        case 1: gmEngaged_ = gmHaveEst_; break;
-        case 2: gmEngaged_ = false; break;
-        default: gmEngaged_ = (gmStableCount_ >= 3); break;
-    }
-
-    for (int i = 0; i < 6; ++i) gmLinAt_[gmSlot][i] = gmRun_[i];
-    gmSlotValid_[gmSlot] = true;
-
-    gmLastTransPx_ = (float)std::sqrt(
-        (gmRun_[4]*fullExtent.width) * (gmRun_[4]*fullExtent.width) +
-        (gmRun_[5]*fullExtent.height) * (gmRun_[5]*fullExtent.height));
-    return gmEngaged_;
-}
-
-void FrameGen::record(VkCommandBuffer cmd, VkImageView prevView, VkImageView currView,
-                      VkImageView outView, float alpha, uint32_t gmSlot, uint32_t synthSlot, bool reuseFlow) {
-    if (!valid()) return;
-    if (gmSlot >= (uint32_t)kGmSlots) gmSlot = 0;
-    if (synthSlot >= (uint32_t)kSynthSlots) synthSlot = 0;
-    const bool m4 = (cfg_.model == 4);
-    const Pipe& flowP   = m4 ? pFlowM4_   : pFlow_;
-    const Pipe& expandP = m4 ? pExpandM4_ : pExpand_;
-
-    if (!g_scratch.built || g_scratch.builtFor.width != extent_.width || g_scratch.builtFor.height != extent_.height) {
-        ensureScratch(this, dd_, device_, memProps_, descPool_, linear_, extent_,
-                      pyrA_, pyrB_, pyrAs_, flowLvl_, flowExpA_, flowExpB_,
-                      pLuma_, pDown_, flowP, expandP, pSynth_, pGmReduce_, pGmPrewarp_,
-                      pFlowReg_, flowRegA_, flowRegB_, gmSsbo_, kLevels, cfg_);
-    }
-
-    // Every generation of one real frame is recorded into the same command buffer, so the flow
-    // between prev and curr is computed once and each generation gets its own synth UBO and set.
-    if (reuseFlow && !g_scratch.flowReady) return;
-    if (!reuseFlow) {
-        bool gmEngaged = updateGlobalMotion(gmSlot, extent_);
-        if (g_scratch.gmUboPtr[gmSlot]) {
-            GMUBO g{};
-            g.lin[0]=(float)gmRun_[0]; g.lin[1]=(float)gmRun_[1]; g.lin[2]=(float)gmRun_[2]; g.lin[3]=(float)gmRun_[3];
-            g.linT[0]=(float)gmRun_[4]; g.linT[1]=(float)gmRun_[5]; g.linT[2]=gmEngaged?1.0f:0.0f; g.linT[3]=0.0f;
-            if (gmEngaged) {
-                g.app[0]=(float)gmRun_[0]; g.app[1]=(float)gmRun_[1]; g.app[2]=(float)gmRun_[2]; g.app[3]=(float)gmRun_[3];
-                g.appT[0]=(float)gmRun_[4]; g.appT[1]=(float)gmRun_[5];
-            }
-            std::memcpy(g_scratch.gmUboPtr[gmSlot], &g, sizeof(g));
-        }
-        {
-            static int lastEng = -1;
-            if (gmEngaged != (lastEng == 1) || (gmFrames_ % 300ull) == 0) {
-                DDFG_LOGI("C1 global-motion: engaged=%d mode=%d stable=%d transPx=%.1f (model=%d)",
-                         gmEngaged ? 1 : 0, cfg_.gmMode, gmStableCount_, gmLastTransPx_, cfg_.model);
-                lastEng = gmEngaged ? 1 : 0;
-            }
-        }
-
-        wImg(dd_, device_, g_scratch.sLumaCurr, 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, currView, linear_, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
-        wImg(dd_, device_, g_scratch.sLumaPrev, 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, prevView, linear_, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
-    }
-
-    SynthUBO su{cfg_.flowScale, alpha, cfg_.beta, cfg_.lambda, cfg_.epsilon, cfg_.photoScale, 0, 0,
-                cfg_.hudX0, cfg_.hudY0, cfg_.hudX1, cfg_.hudY1};
-    if (g_scratch.synthUboPtr[synthSlot]) std::memcpy(g_scratch.synthUboPtr[synthSlot], &su, sizeof(su));
-
-    const VkDescriptorSet synthSet = g_scratch.sSynth[synthSlot];
-    wImg(dd_, device_, synthSet, 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, prevView, linear_, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
-    wImg(dd_, device_, synthSet, 33, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, currView, linear_, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
-    wImg(dd_, device_, synthSet, 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, outView, VK_NULL_HANDLE, VK_IMAGE_LAYOUT_GENERAL);
-
-    auto disp = [&](const Pipe& p, VkDescriptorSet set, VkExtent2D e) {
-        dd_->CmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, p.pipeline);
-        dd_->CmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, p.layout, 0, 1, &set, 0, nullptr);
-        dd_->CmdDispatch(cmd, (e.width + 15) / 16, (e.height + 15) / 16, 1);
-    };
-    auto bar = [&](FrameGen::Img& i){ barrier(cmd, i.image, VK_IMAGE_LAYOUT_GENERAL, VK_IMAGE_LAYOUT_GENERAL); };
-
-    if (!reuseFlow) {
-        for (auto& i : pyrA_)    barrier(cmd, i.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        for (auto& i : pyrB_)    barrier(cmd, i.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        for (int l = flowFinest_; l < kLevels; ++l) barrier(cmd, pyrAs_[l].image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        barrier(cmd, flowExpA_.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        barrier(cmd, flowExpB_.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        barrier(cmd, flowRegA_.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        barrier(cmd, flowRegB_.image, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_GENERAL);
-        {
-            VkClearColorValue zero{};
-            VkImageSubresourceRange rng{VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
-            for (int l = flowFinest_; l < kLevels; ++l) {
-                VkImageMemoryBarrier b{VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER};
-                b.oldLayout = VK_IMAGE_LAYOUT_UNDEFINED; b.newLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
-                b.srcAccessMask = 0; b.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
-                b.image = flowLvl_[l].image; b.subresourceRange = rng;
-                b.srcQueueFamilyIndex = b.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
-                dd_->CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 0, nullptr, 0, nullptr, 1, &b);
-                dd_->CmdClearColorImage(cmd, flowLvl_[l].image, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, &zero, 1, &rng);
-                b.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL; b.newLayout = VK_IMAGE_LAYOUT_GENERAL;
-                b.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT; b.dstAccessMask = VK_ACCESS_SHADER_READ_BIT | VK_ACCESS_SHADER_WRITE_BIT;
-                dd_->CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT, 0, 0, nullptr, 0, nullptr, 1, &b);
-            }
-        }
-
-        disp(pLuma_, g_scratch.sLumaCurr, levelExtent(extent_, 0));
-        disp(pLuma_, g_scratch.sLumaPrev, levelExtent(extent_, 0));
-        bar(pyrA_[0]); bar(pyrB_[0]);
-        for (int l = 1; l < kLevels; ++l) {
-            disp(pDown_, g_scratch.sDownA[l - 1], levelExtent(extent_, l));
-            disp(pDown_, g_scratch.sDownB[l - 1], levelExtent(extent_, l));
-            bar(pyrA_[l]); bar(pyrB_[l]);
-        }
-        if (gmBuffersReady_ && g_scratch.sGmReduce[gmSlot]) {
-            dd_->CmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, pGmReduce_.pipeline);
-            dd_->CmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, pGmReduce_.layout, 0, 1, &g_scratch.sGmReduce[gmSlot], 0, nullptr);
-            dd_->CmdDispatch(cmd, (uint32_t)(kGmThreads / 64), 1, 1);
-            VkMemoryBarrier mb{VK_STRUCTURE_TYPE_MEMORY_BARRIER};
-            mb.srcAccessMask = VK_ACCESS_SHADER_WRITE_BIT; mb.dstAccessMask = VK_ACCESS_HOST_READ_BIT;
-            dd_->CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_HOST_BIT,
-                                    0, 1, &mb, 0, nullptr, 0, nullptr);
-        }
-        for (int l = flowFinest_; l < kLevels; ++l) {
-            disp(pGmPrewarp_, g_scratch.sGmPrewarp[gmSlot][l], levelExtent(extent_, l));
-            bar(pyrAs_[l]);
-        }
-        for (int l = kLevels - 1; l >= flowFinest_; --l) {
-            disp(flowP, g_scratch.sFlow[l], levelExtent(extent_, l));
-            bar(flowLvl_[l]);
-        }
-
-        const bool frEngaged = (cfg_.frMode != 2) && (cfg_.frIters > 0);
-        if (frEngaged) {
-            const int F = flowFinest_;
-            const VkExtent2D fe = levelExtent(extent_, F);
-            if (g_scratch.flowRegUboPtr) {
-                FlowRegUBO fu{cfg_.frDt, cfg_.frLambda, cfg_.frEdge, cfg_.frEps};
-                std::memcpy(g_scratch.flowRegUboPtr, &fu, sizeof(fu));
-            }
-            FrameGen::Img* last = nullptr;
-            for (int it = 0; it < cfg_.frIters; ++it) {
-                VkDescriptorSet set; FrameGen::Img* outImg;
-                if      (it == 0)      { set = g_scratch.sFlowReg0;  outImg = &flowRegA_; }
-                else if (it % 2 == 1)  { set = g_scratch.sFlowRegAB; outImg = &flowRegB_; }
-                else                   { set = g_scratch.sFlowRegBA; outImg = &flowRegA_; }
-                dd_->CmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, pFlowReg_.pipeline);
-                dd_->CmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_COMPUTE, pFlowReg_.layout, 0, 1, &set, 0, nullptr);
-                dd_->CmdDispatch(cmd, (fe.width + 15) / 16, (fe.height + 15) / 16, 1);
-                bar(*outImg);
-                last = outImg;
-            }
-            VkMemoryBarrier mb{VK_STRUCTURE_TYPE_MEMORY_BARRIER};
-            mb.srcAccessMask = VK_ACCESS_SHADER_READ_BIT | VK_ACCESS_SHADER_WRITE_BIT;
-            mb.dstAccessMask = VK_ACCESS_TRANSFER_READ_BIT | VK_ACCESS_TRANSFER_WRITE_BIT;
-            dd_->CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT,
-                                    0, 1, &mb, 0, nullptr, 0, nullptr);
-            VkImageCopy region{};
-            region.srcSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1};
-            region.dstSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1};
-            region.extent = {fe.width, fe.height, 1};
-            dd_->CmdCopyImage(cmd, last->image, VK_IMAGE_LAYOUT_GENERAL,
-                              flowLvl_[F].image, VK_IMAGE_LAYOUT_GENERAL, 1, &region);
-            VkMemoryBarrier mb2{VK_STRUCTURE_TYPE_MEMORY_BARRIER};
-            mb2.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
-            mb2.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
-            dd_->CmdPipelineBarrier(cmd, VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_COMPUTE_SHADER_BIT,
-                                    0, 1, &mb2, 0, nullptr, 0, nullptr);
-        }
-        {
-            static int lastFr = -1;
-            int fe = frEngaged ? 1 : 0;
-            if (fe != lastFr || (gmFrames_ % 300ull) == 0) {
-                DDFG_LOGI("C2 flow-reg: engaged=%d mode=%d iters=%d lambda=%.2f dt=%.2f edge=%.1f eps=%.3f (model=%d)",
-                         fe, cfg_.frMode, cfg_.frIters, cfg_.frLambda, cfg_.frDt, cfg_.frEdge, cfg_.frEps, cfg_.model);
-                lastFr = fe;
-            }
-        }
-
-        disp(expandP, g_scratch.sExpand[gmSlot], levelExtent(extent_, 0));
-        bar(flowExpA_); bar(flowExpB_);
-        g_scratch.flowReady = true;
-    }
-    disp(pSynth_, synthSet, levelExtent(extent_, 0));
-}
-
-static bool ensureScratch(FrameGen* fg, const DeviceDispatch* dd, VkDevice dev,
-                          const VkPhysicalDeviceMemoryProperties& mp, VkDescriptorPool pool,
-                          VkSampler samp, VkExtent2D ext,
-                          std::vector<FrameGen::Img>& pyrA, std::vector<FrameGen::Img>& pyrB,
-                          std::vector<FrameGen::Img>& pyrAs,
-                          std::vector<FrameGen::Img>& flowLvl, FrameGen::Img& expA, FrameGen::Img& expB,
-                          const FrameGen::Pipe& pLuma, const FrameGen::Pipe& pDown,
-                          const FrameGen::Pipe& pFlow, const FrameGen::Pipe& pExpand,
-                          const FrameGen::Pipe& pSynth, const FrameGen::Pipe& pGmReduce,
-                          const FrameGen::Pipe& pGmPrewarp, const FrameGen::Pipe& pFlowReg,
-                          FrameGen::Img& flowRegA, FrameGen::Img& flowRegB, VkBuffer* gmSsbo,
-                          int kLevels, const Config& cfg) {
-    auto& S = g_scratch;
-    S = ScratchState{};
-    const auto GEN = VK_IMAGE_LAYOUT_GENERAL;
-
-    for (int s = 0; s < FrameGen::kSynthSlots; ++s)
-        makeUbo(dd, dev, mp, sizeof(SynthUBO), S.synthUbo[s], S.synthUboMem[s], S.synthUboPtr[s]);
-    makeUbo(dd, dev, mp, sizeof(FlowUBO), S.expandUbo, S.expandUboMem, S.expandUboPtr);
-    if (S.expandUboPtr) { FlowUBO u{cfg.flowScale, 0, 0.6f, 1.6f}; std::memcpy(S.expandUboPtr, &u, sizeof(u)); }
-    makeUbo(dd, dev, mp, sizeof(FlowRegUBO), S.flowRegUbo, S.flowRegUboMem, S.flowRegUboPtr);
-    if (S.flowRegUboPtr) { FlowRegUBO fu{cfg.frDt, cfg.frLambda, cfg.frEdge, cfg.frEps}; std::memcpy(S.flowRegUboPtr, &fu, sizeof(fu)); }
-    S.flowUbo.resize(kLevels); S.flowUboMem.resize(kLevels); S.flowUboPtr.resize(kLevels);
-    for (int l = 0; l < kLevels; ++l) {
-        makeUbo(dd, dev, mp, sizeof(FlowUBO), S.flowUbo[l], S.flowUboMem[l], S.flowUboPtr[l]);
-        if (S.flowUboPtr[l]) { FlowUBO u{cfg.flowScale, (uint32_t)l, 0.6f, 1.6f}; std::memcpy(S.flowUboPtr[l], &u, sizeof(u)); }
-    }
-    for (int s = 0; s < FrameGen::kGmSlots; ++s) {
-        makeUbo(dd, dev, mp, sizeof(GMUBO), S.gmUbo[s], S.gmUboMem[s], S.gmUboPtr[s]);
-        if (S.gmUboPtr[s]) { GMUBO g{}; std::memcpy(S.gmUboPtr[s], &g, sizeof(g)); }
-    }
-
-    S.sLumaCurr = allocSet(dd, dev, pool, pLuma.setLayout);
-    S.sLumaPrev = allocSet(dd, dev, pool, pLuma.setLayout);
-    wImg(dd, dev, S.sLumaCurr, 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, pyrA[0].view, VK_NULL_HANDLE, GEN);
-    wImg(dd, dev, S.sLumaPrev, 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, pyrB[0].view, VK_NULL_HANDLE, GEN);
-
-    S.sDownA.resize(kLevels - 1); S.sDownB.resize(kLevels - 1);
-    for (int l = 1; l < kLevels; ++l) {
-        S.sDownA[l-1] = allocSet(dd, dev, pool, pDown.setLayout);
-        S.sDownB[l-1] = allocSet(dd, dev, pool, pDown.setLayout);
-        wImg(dd, dev, S.sDownA[l-1], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrA[l-1].view, samp, GEN);
-        wImg(dd, dev, S.sDownA[l-1], 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, pyrA[l].view, VK_NULL_HANDLE, GEN);
-        wImg(dd, dev, S.sDownB[l-1], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrB[l-1].view, samp, GEN);
-        wImg(dd, dev, S.sDownB[l-1], 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, pyrB[l].view, VK_NULL_HANDLE, GEN);
-    }
-
-    S.sFlow.resize(kLevels);
-    for (int l = 0; l < kLevels; ++l) {
-        S.sFlow[l] = allocSet(dd, dev, pool, pFlow.setLayout);
-        int pred = (l + 1 < kLevels) ? l + 1 : l;
-        VkImageView currLvl = (l >= fg->flowFinest()) ? pyrAs[l].view : pyrA[l].view;
-        wUbo(dd, dev, S.sFlow[l], 0, S.flowUbo[l], sizeof(FlowUBO));
-        wImg(dd, dev, S.sFlow[l], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrB[l].view, samp, GEN);
-        wImg(dd, dev, S.sFlow[l], 33, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, currLvl, samp, GEN);
-        wImg(dd, dev, S.sFlow[l], 34, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowLvl[pred].view, samp, GEN);
-        wImg(dd, dev, S.sFlow[l], 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, flowLvl[l].view, VK_NULL_HANDLE, GEN);
-    }
-
-    if (gmSsbo) {
-        for (int s = 0; s < FrameGen::kGmSlots; ++s) {
-            if (!gmSsbo[s]) continue;
-            S.sGmReduce[s] = allocSet(dd, dev, pool, pGmReduce.setLayout);
-            wUbo (dd, dev, S.sGmReduce[s], 1,  S.gmUbo[s], sizeof(GMUBO));
-            wSsbo(dd, dev, S.sGmReduce[s], 16, gmSsbo[s], VK_WHOLE_SIZE);
-            wImg (dd, dev, S.sGmReduce[s], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrB[FrameGen::kGmLevel].view, samp, GEN);
-            wImg (dd, dev, S.sGmReduce[s], 33, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrA[FrameGen::kGmLevel].view, samp, GEN);
-        }
-    }
-
-    for (int s = 0; s < FrameGen::kGmSlots; ++s) {
-        S.sGmPrewarp[s].assign(kLevels, VK_NULL_HANDLE);
-        for (int l = fg->flowFinest(); l < kLevels; ++l) {
-            S.sGmPrewarp[s][l] = allocSet(dd, dev, pool, pGmPrewarp.setLayout);
-            wUbo(dd, dev, S.sGmPrewarp[s][l], 1,  S.gmUbo[s], sizeof(GMUBO));
-            wImg(dd, dev, S.sGmPrewarp[s][l], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrA[l].view, samp, GEN);
-            wImg(dd, dev, S.sGmPrewarp[s][l], 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, pyrAs[l].view, VK_NULL_HANDLE, GEN);
-        }
-    }
-
-    for (int s = 0; s < FrameGen::kGmSlots; ++s) {
-        S.sExpand[s] = allocSet(dd, dev, pool, pExpand.setLayout);
-        wUbo(dd, dev, S.sExpand[s], 0, S.expandUbo, sizeof(FlowUBO));
-        wUbo(dd, dev, S.sExpand[s], 1, S.gmUbo[s], sizeof(GMUBO));
-        wImg(dd, dev, S.sExpand[s], 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowLvl[fg->flowFinest()].view, samp, GEN);
-        wImg(dd, dev, S.sExpand[s], 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, expA.view, VK_NULL_HANDLE, GEN);
-        wImg(dd, dev, S.sExpand[s], 49, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, expB.view, VK_NULL_HANDLE, GEN);
-    }
-
-    {
-        const int F = fg->flowFinest();
-        S.sFlowReg0  = allocSet(dd, dev, pool, pFlowReg.setLayout);
-        S.sFlowRegAB = allocSet(dd, dev, pool, pFlowReg.setLayout);
-        S.sFlowRegBA = allocSet(dd, dev, pool, pFlowReg.setLayout);
-        VkDescriptorSet all3[3] = {S.sFlowReg0, S.sFlowRegAB, S.sFlowRegBA};
-        for (VkDescriptorSet s : all3) {
-            wUbo(dd, dev, s, 0,  S.flowRegUbo, sizeof(FlowRegUBO));
-            wImg(dd, dev, s, 33, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowLvl[F].view, samp, GEN);
-            wImg(dd, dev, s, 34, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, pyrB[F].view,    samp, GEN);
-        }
-        wImg(dd, dev, S.sFlowReg0,  32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowLvl[F].view, samp, GEN);
-        wImg(dd, dev, S.sFlowReg0,  48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,          flowRegA.view,   VK_NULL_HANDLE, GEN);
-        wImg(dd, dev, S.sFlowRegAB, 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowRegA.view,   samp, GEN);
-        wImg(dd, dev, S.sFlowRegAB, 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,          flowRegB.view,   VK_NULL_HANDLE, GEN);
-        wImg(dd, dev, S.sFlowRegBA, 32, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, flowRegB.view,   samp, GEN);
-        wImg(dd, dev, S.sFlowRegBA, 48, VK_DESCRIPTOR_TYPE_STORAGE_IMAGE,          flowRegA.view,   VK_NULL_HANDLE, GEN);
-    }
-
-    for (int s = 0; s < FrameGen::kSynthSlots; ++s) {
-        S.sSynth[s] = allocSet(dd, dev, pool, pSynth.setLayout);
-        wUbo(dd, dev, S.sSynth[s], 0, S.synthUbo[s], sizeof(SynthUBO));
-        wImg(dd, dev, S.sSynth[s], 34, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, expA.view, samp, GEN);
-        wImg(dd, dev, S.sSynth[s], 35, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, expB.view, samp, GEN);
-    }
-
-    S.builtFor = ext; S.built = true;
-    return true;
-}
-
-}

app/src/main/cpp/framegen/lsfg/lsfg_alpha.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_alpha.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_alpha.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_beta.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_beta.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_beta.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_chain.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_chain.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_chain.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_common.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_common.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_common.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_delta.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_delta.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_delta.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_dll.cpp

@@ -1,5 +1,9 @@
-// LSFG from Camille LaVey / the Eden Emulator Project, following upstream lsfg-vk (PancakeTAS).
-// Ported to WinNative and DroidDeck by @maxjivi05. GPL-3.0-or-later.
+// See lsfg_dll.h. PE resource walk + on-device SPIR-V cache for the Lossless
+// Scaling frame-generation chain.
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk (PancakeTAS). Ported to WinNative (lsfg_dll.c) and DroidDeck
+// by @maxjivi05. GPL-3.0-or-later.
 
 #include "lsfg_dll.h"
 #include "lsfg_dxbc.h"
@@ -21,9 +25,9 @@
 namespace lsfg {
 namespace {
 
-
-constexpr uint16_t kDosMagic       = 0x5A4Du;
-constexpr uint32_t kPeSignature    = 0x00004550u;
+// ---- PE constants ---------------------------------------------------------
+constexpr uint16_t kDosMagic       = 0x5A4Du;   // "MZ"
+constexpr uint32_t kPeSignature    = 0x00004550u; // "PE\0\0"
 constexpr uint16_t kPe32Magic      = 0x010Bu;
 constexpr uint16_t kPe32PlusMagic  = 0x020Bu;
 
@@ -43,6 +47,7 @@ constexpr size_t   kResourceEntrySize       = 8u;
 constexpr uint32_t kResourceSubdirectoryBit = 0x80000000u;
 constexpr uint32_t kResourceTypeRcData      = 10u;
 
+// ---- SPIR-V constants -----------------------------------------------------
 constexpr uint32_t kSpirvMagic          = 0x07230203u;
 constexpr size_t   kSpirvHeaderWords    = 5u;
 constexpr uint32_t kSpirvWordCountShift = 16u;
@@ -59,7 +64,7 @@ constexpr uint32_t kVariantFp32Offset = 98u;
 constexpr uint32_t kMaxResourceId = 512u;
 constexpr size_t   kMaxSpirvWords = 16u * 1024u * 1024u;
 
-constexpr uint32_t kCacheMagic   = 0x4C534642u;
+constexpr uint32_t kCacheMagic   = 0x4C534642u;  // "BFSL" little-endian
 constexpr uint32_t kCacheVersion = 1u;
 
 struct CacheHeader {
@@ -78,6 +83,7 @@ struct PeSection {
     uint32_t rawSize        = 0;
 };
 
+// Read-only mapping of the DLL. Closes itself; the DLL is never executed.
 class PeImage {
 public:
     ~PeImage() { close(); }
@@ -162,6 +168,7 @@ private:
     std::vector<PeSection> sections_;
 };
 
+// RCDATA id -> blob, for the ids we care about.
 struct ResourceTable {
     const uint8_t* data[kMaxResourceId] = {};
     uint32_t       size[kMaxResourceId] = {};
@@ -210,6 +217,7 @@ bool resourceReadLeaf(const PeImage& img, size_t leafOffset,
     return true;
 }
 
+// Walk type -> name -> language and keep the first language of every RCDATA id.
 bool collectRcData(const PeImage& img, size_t resourceBase, ResourceTable& out) {
     size_t typeTotal = 0;
     if (!resourceEntryCount(img, resourceBase, typeTotal)) return false;
@@ -248,7 +256,7 @@ bool collectRcData(const PeImage& img, size_t resourceBase, ResourceTable& out)
                 if (!resourceReadLeaf(img, resourceBase + langOffset, blob, blobSize)) continue;
                 out.data[nameId] = blob;
                 out.size[nameId] = blobSize;
-                break;
+                break;   // first language wins
             }
         }
     }
@@ -281,6 +289,7 @@ DllStatus parseResources(PeImage& img, ResourceTable& table) {
     return DllStatus::Ok;
 }
 
+// ---- SPIR-V adoption (precompiled-variant path) ---------------------------
 
 bool isSpirvModule(const uint8_t* blob, uint32_t size) {
     if (!blob || size < kSpirvHeaderWords * sizeof(uint32_t)) return false;
@@ -306,6 +315,9 @@ uint32_t lookupDescriptorSet(const std::vector<uint32_t>& w, uint32_t targetId)
     return 0;
 }
 
+// Precompiled blobs are renumbered into set/binding order - that is the
+// convention they were built with. The DXBC path uses encounter order instead
+// (see lsfg_dxbc), which is what DXVK's output pairs with. Do not merge them.
 bool renumberBindingsSetOrder(std::vector<uint32_t>& w) {
     struct Slot { uint32_t set; uint32_t binding; size_t literalOffset; };
     std::vector<Slot> slots;
@@ -387,6 +399,8 @@ bool writeCache(const std::string& cachePath, const CacheHeader& header, const M
     if (ok) ok = fsync(fileno(f)) == 0;
     fclose(f);
 
+    // Temp file + rename, so a failed or interrupted build can never leave a
+    // half-written cache that would later be loaded as if it were complete.
     if (!ok || rename(tempPath.c_str(), cachePath.c_str()) != 0) {
         unlink(tempPath.c_str());
         return false;
@@ -402,8 +416,9 @@ bool readCacheHeader(const std::string& cachePath, CacheHeader& out) {
     return ok && out.magic == kCacheMagic && out.version == kCacheVersion;
 }
 
-}
+} // namespace
 
+// ---- public API -----------------------------------------------------------
 
 const std::vector<uint32_t>& shaderIds() {
     static const std::vector<uint32_t> ids = [] {
@@ -569,6 +584,7 @@ DllStatus loadModules(const std::string& cachePath, ModuleSet& outSet) {
     return status;
 }
 
+// ---- SPIR-V version lowering (Vulkan 1.1/1.2 compat) ----------------------
 
 namespace {
 
@@ -577,14 +593,14 @@ constexpr uint32_t kSpirvOpExtInstImport= 11u;
 constexpr uint32_t kSpirvOpMemoryModel  = 14u;
 constexpr uint32_t kSpirvOpCapability   = 17u;
 
-
-
-constexpr uint32_t kCapVulkanMemoryModel            = 5345u;
-constexpr uint32_t kCapVulkanMemoryModelDeviceScope = 5346u;
-constexpr uint32_t kCapDemoteToHelperInvocation     = 5379u;
+// Capabilities that are core in the version the translator emits but not in
+// the versions we lower to.
+constexpr uint32_t kCapVulkanMemoryModel            = 5345u;  // core from 1.5
+constexpr uint32_t kCapVulkanMemoryModelDeviceScope = 5346u;  // core from 1.5
+constexpr uint32_t kCapDemoteToHelperInvocation     = 5379u;  // core from 1.6
 
 std::vector<uint32_t> encodeOpExtension(const char* name) {
-    const size_t len = strlen(name) + 1;
+    const size_t len = strlen(name) + 1;                 // incl. NUL
     const size_t strWords = (len + 3) / 4;
     std::vector<uint32_t> ins(1 + strWords, 0u);
     ins[0] = ((uint32_t)(1 + strWords) << kSpirvWordCountShift) | kSpirvOpExtension;
@@ -608,13 +624,17 @@ bool hasOpExtension(const std::vector<uint32_t>& w, const char* name) {
     return false;
 }
 
-}
+} // namespace
 
 bool downgradeSpirv(std::vector<uint32_t>& w, uint32_t targetVersion) {
     if (w.size() < kSpirvHeaderWords || w[0] != kSpirvMagic) return false;
     if (targetVersion < kSpirv14) return false;
-    if (w[1] <= targetVersion) return true;
+    if (w[1] <= targetVersion) return true;             // already low enough
 
+    // Walk the preamble first and only touch the module once it is known to
+    // be lowerable: note which extension-gated capabilities are declared and
+    // where the capability block ends (OpExtension must follow every
+    // OpCapability and precede OpExtInstImport / OpMemoryModel).
     bool needMemoryModel = false;
     size_t insertAt = kSpirvHeaderWords;
     size_t off = kSpirvHeaderWords;
@@ -625,6 +645,9 @@ bool downgradeSpirv(std::vector<uint32_t>& w, uint32_t targetVersion) {
         if (opcode == kSpirvOpCapability && length >= 2) {
             const uint32_t cap = w[off + 1];
             if (cap == kCapVulkanMemoryModel || cap == kCapVulkanMemoryModelDeviceScope) needMemoryModel = true;
+            // Core only in 1.6, and VK_EXT_shader_demote_to_helper_invocation
+            // is never enabled on the compat path: refuse rather than hand the
+            // driver a module that is not legal at the lowered version.
             if (cap == kCapDemoteToHelperInvocation) return false;
             insertAt = off + length;
         } else if (opcode == kSpirvOpExtension) {
@@ -636,6 +659,7 @@ bool downgradeSpirv(std::vector<uint32_t>& w, uint32_t targetVersion) {
         off += length;
     }
 
+    // 1.5 has the memory model as core; only 1.4 needs it declared.
     if (targetVersion < kSpirv15 && needMemoryModel
         && !hasOpExtension(w, "SPV_KHR_vulkan_memory_model")) {
         const auto e = encodeOpExtension("SPV_KHR_vulkan_memory_model");
@@ -645,4 +669,4 @@ bool downgradeSpirv(std::vector<uint32_t>& w, uint32_t targetVersion) {
     return true;
 }
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_dll.h

@@ -1,7 +1,35 @@
-// LSFG from Camille LaVey / the Eden Emulator Project, following upstream lsfg-vk (PancakeTAS).
-// Ported to WinNative and DroidDeck by @maxjivi05. GPL-3.0-or-later.
-
 #pragma once
+// ============================================================================
+// lsfg_dll - extract the Lossless Scaling frame-generation shader chain from
+// the user's own Lossless.dll, and cache it on device as SPIR-V.
+//
+// The 25 compute shaders that make up LSFG 3.1 are NOT redistributable. They
+// ship as RCDATA resources inside Lossless.dll from the user's own paid copy
+// of Lossless Scaling (Steam app 993090). Every implementation - upstream
+// lsfg-vk, LSFG-Android, eden, WinNative - requires the user to supply their
+// own DLL and extracts the resources on device. DroidDeck does the same, and
+// bundles nothing.
+//
+// The DLL is mmap'd READ-ONLY and parsed as data. It is never loaded as a
+// library and never executed.
+//
+// Resource layout, measured against real installs:
+//   * The base chain lives at RCDATA ids 255, 256 and 280-302 (25 modules),
+//     and is DXBC. It has always been DXBC.
+//   * Lossless Scaling MAY additionally carry precompiled SPIR-V copies at
+//     base+49 (native fp16) and base+98 (native fp32). No build currently
+//     downloadable from Steam carries them - public buildId 19655272 was
+//     measured with zero SPIR-V anywhere in the 311 MB install - so the DXBC
+//     path is the normal path and the translator is not optional. The SPIR-V
+//     path is kept because it costs nothing and a future build may ship them.
+//
+// Both producers fill the same shader-id -> SPIR-V words map, so everything
+// downstream of this file is source-agnostic.
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk (PancakeTAS). Ported to WinNative (lsfg_dll.c) and DroidDeck
+// by @maxjivi05. GPL-3.0-or-later.
+// ============================================================================
 
 #include <cstdint>
 #include <string>
@@ -11,37 +39,44 @@ namespace lsfg {
 
 enum class DllStatus {
     Ok = 0,
-    NotInstalled,
-    UnreadableFile,
+    NotInstalled,        // no such file / cannot open
+    UnreadableFile,      // opens but cannot be mapped or is empty
     NotPortableExecutable,
-    MissingShaders,
-    TranslationFailed,
-    CacheUnusable
+    MissingShaders,      // parses, but the base chain is not all there
+    TranslationFailed,   // a shader failed DXBC->SPIR-V or SPIR-V adoption
+    CacheUnusable        // cache could not be written or read back
 };
 
+// SPIR-V version words. The translator emits 1.6; a Vulkan 1.1 device takes
+// 1.4 (via VK_KHR_spirv_1_4) and a 1.2 device 1.5. One definition for the
+// probe, the engine and the shader loader.
 constexpr uint32_t kSpirv14 = 0x00010400u;
 constexpr uint32_t kSpirv15 = 0x00010500u;
 constexpr uint32_t kSpirv16 = 0x00010600u;
 
 enum class Variant {
     None = 0,
-    SpirvFp16,
-    SpirvFp32,
-    DxbcTranslated
+    SpirvFp16,      // precompiled fp16 blobs at base+49
+    SpirvFp32,      // precompiled fp32 blobs at base+98
+    DxbcTranslated  // base chain, translated on device (the normal case)
 };
 
+// The 25 shader ids that make up the chain.
 constexpr uint32_t kShaderMipmaps   = 255u;
 constexpr uint32_t kShaderGenerate  = 256u;
 constexpr uint32_t kShaderChainFirst= 280u;
 constexpr uint32_t kShaderChainLast = 302u;
 constexpr uint32_t kShaderCount     = 25u;
 
+// Upstream spelling for the two ids the ported chain files refer to by name.
+// Kept so those files stay byte-close to their upstream form; these alias the
+// constants above rather than being a second source of truth.
 constexpr uint32_t LSFG_SHADER_MIPMAPS  = kShaderMipmaps;
 constexpr uint32_t LSFG_SHADER_GENERATE = kShaderGenerate;
 
 struct Module {
     uint32_t              id = 0;
-    std::vector<uint32_t> words;
+    std::vector<uint32_t> words;   // SPIR-V
 };
 
 struct ModuleSet {
@@ -52,19 +87,41 @@ struct ModuleSet {
     bool complete() const;
 };
 
+// The canonical shader-id list, in dispatch-independent order.
 const std::vector<uint32_t>& shaderIds();
 
 const char* statusName(DllStatus s);
 const char* variantName(Variant v);
 
+// Does this file look like a usable Lossless.dll? Checks the base chain only,
+// so a DLL without the SPIR-V variants (i.e. every build on Steam today) is
+// reported as valid - the translator handles it.
 DllStatus validateDll(const std::string& dllPath);
 
+// Parse the DLL, produce all 25 SPIR-V modules, and write them to cachePath
+// (via temp file + rename, so a failed build cannot leave a half-written
+// cache behind). Records which producer ran in the cache header.
 DllStatus buildCache(const std::string& dllPath, const std::string& cachePath, bool preferFp16);
 
+// Load a previously built cache.
 DllStatus loadModules(const std::string& cachePath, ModuleSet& outSet);
 
+// Which producer built an existing cache, without loading the modules.
 DllStatus cacheVariant(const std::string& cachePath, Variant& outVariant);
 
+// Experimental Vulkan 1.1 / 1.2 compat: lower a DXBC-translated module's
+// declared SPIR-V version to `targetVersion` (kSpirv14 or kSpirv15). Below 1.5
+// the Vulkan memory model is not core, so SPV_KHR_vulkan_memory_model is
+// declared for it (the device side enables VK_KHR_vulkan_memory_model). The
+// cache is built without a device in hand, always at the translator's native
+// 1.6, so this runs at load time against whatever the device can take. A
+// module already at or below the target is left untouched. Returns false,
+// leaving the module untouched, for a malformed module, a target below 1.4, or
+// a module declaring DemoteToHelperInvocation: that capability is core only in
+// 1.6 and its extension is never enabled on the compat path, so such a module
+// cannot be made legal here (DXVK emits it for pixel-shader discard only, so
+// the 25 compute shaders never carry it). Whether the device then accepts the
+// result is vkCreateShaderModule's / vkCreateComputePipelines' verdict.
 bool downgradeSpirv(std::vector<uint32_t>& words, uint32_t targetVersion);
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_dxbc.cpp

@@ -1,5 +1,10 @@
-// Ported to WinNative and DroidDeck by @maxjivi05 from Camille LaVey / the Eden Emulator Project (GPL-3.0-or-later).
-// DXVK's translator is zlib licensed; vendored under cpp/thirdparty/dxbc.
+// See lsfg_dxbc.h. DXBC -> SPIR-V via DXVK's vendored translator.
+//
+// Follows upstream lsfg-vk's src/extract/trans.cpp, including its
+// encounter-order binding renumber. Ported to WinNative (lsfg_dxbc.cpp) and
+// DroidDeck by @maxjivi05 from the work of Camille LaVey / the Eden Emulator
+// Project (GPL-3.0-or-later); the translator itself is DXVK's, zlib licensed,
+// vendored under cpp/thirdparty/dxbc.
 
 #include "lsfg_dxbc.h"
 
@@ -16,12 +21,12 @@ namespace {
 
 struct BindingSlot {
     uint32_t bindingIndex  = 0;
-    uint32_t bindingOffset = 0;
+    uint32_t bindingOffset = 0;   // word offset of the Binding literal
     uint32_t setIndex      = 0;
     uint32_t setOffset     = 0;
 };
 
-}
+} // namespace
 
 bool translateDxbc(const uint8_t* bytecode, uint32_t size, std::vector<uint32_t>& outWords) {
     outWords.clear();
@@ -33,6 +38,9 @@ bool translateDxbc(const uint8_t* bytecode, uint32_t size, std::vector<uint32_t>
         const dxvk::DxbcModuleInfo info{};
         auto code = module.compile(info, "CS");
 
+        // Collect the descriptor decorations in the order the Binding
+        // decorations appear. Everything before the first OpFunction is the
+        // decoration block, so the scan stops there.
         std::vector<BindingSlot> slotsByVarId;
         std::vector<uint32_t>    varIdsInOrder;
         for (auto ins : code) {
@@ -52,6 +60,7 @@ bool translateDxbc(const uint8_t* bytecode, uint32_t size, std::vector<uint32_t>
             if (ins.opCode() == spv::OpFunction) break;
         }
 
+        // Renumber to a dense 0..n range, in encounter order.
         uint32_t next = 0;
         for (const uint32_t varId : varIdsInOrder) {
             const BindingSlot& slot = slotsByVarId[varId];
@@ -66,9 +75,11 @@ bool translateDxbc(const uint8_t* bytecode, uint32_t size, std::vector<uint32_t>
         std::memcpy(outWords.data(), code.data(), byteSize);
         return true;
     } catch (...) {
+        // DXVK's compiler signals malformed bytecode by throwing. A bad
+        // resource must degrade to "this DLL is unusable", never to a crash.
         outWords.clear();
         return false;
     }
 }
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_dxbc.h

@@ -1,11 +1,39 @@
 #pragma once
-// DXVK's dxbc subset is zlib licensed; vendored under cpp/thirdparty/dxbc.
+// ============================================================================
+// lsfg_dxbc - DXBC -> SPIR-V for the Lossless Scaling shader chain.
+//
+// Why this exists at all: the base chain inside Lossless.dll is DXBC, and has
+// always been DXBC. Lossless Scaling 3.2.2's release note ("Added shaders
+// intended for use by the lsfg-vk project") describes precompiled SPIR-V
+// copies at RCDATA base+49 / base+98 - but no build downloadable from Steam
+// carries them. Measured against the current public build (buildId 19655272,
+// 2025-08-19; linux_testing byte-identical on depot 993091): the whole 311 MB
+// install contains zero occurrences of the SPIR-V magic word, and the DLL's
+// 202 RCDATA entries are all DXBC.
+//
+// So a translator is required, not optional. Upstream lsfg-vk reaches the same
+// conclusion and links DXVK's `dxbc` in src/extract/trans.cpp; we vendor the
+// same subset (zlib licence) under cpp/thirdparty/dxbc and follow its
+// trans.cpp step for step.
+//
+// The binding renumber here is ENCOUNTER ORDER - the order in which Binding
+// decorations appear in DXVK's output - which is what DXVK's own layout pairs
+// with. The precompiled-SPIR-V path in lsfg_dll.cpp uses a set/binding sort
+// instead, because those blobs were built with that convention. The two must
+// not be merged.
+// ============================================================================
 
 #include <cstdint>
 #include <vector>
 
 namespace lsfg {
 
+// Translate one DXBC compute shader to SPIR-V, renumbering descriptor bindings
+// into a dense 0..n range in encounter order. Returns false (leaving outWords
+// empty) on any malformed input - DXVK's compiler throws, and everything is
+// caught here.
+// Emits DXVK's native SPIR-V 1.6; lowering for a Vulkan 1.1/1.2 device happens
+// at load time (lsfg_dll.h downgradeSpirv).
 bool translateDxbc(const uint8_t* bytecode, uint32_t size, std::vector<uint32_t>& outWords);
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_engine.cpp

@@ -1,3 +1,8 @@
+// See lsfg_engine.h.
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative (vkr_lsfg.cpp) and DroidDeck by
+// @maxjivi05, where it runs on gamescope's output in the compositor.
 
 #include "lsfg_engine.h"
 
@@ -16,6 +21,9 @@
 namespace lsfg {
 namespace {
 
+// The chain needs two real frames in its history before anything it produces
+// is meaningful, and we require the plan to stay warm for a couple of frames
+// so a single settled sample cannot start generation from garbage.
 constexpr uint64_t kRequiredFrames    = 2;
 constexpr uint32_t kRecurrenceFrames  = 2;
 constexpr uint64_t kTelemetryInterval = 120;
@@ -42,6 +50,8 @@ VkImageMemoryBarrier makeTransition(VkImage image, VkAccessFlags srcAccess,
     return b;
 }
 
+// Copy the just-composited frame into the chain's input ring. `source` is the
+// composite target, which the composite render pass leaves in GENERAL.
 void copyPresentedFrame(VkCommandBuffer cmd, VkImage source, LsfgImage& destination,
                         VkExtent2D extent) {
     const VkImageMemoryBarrier before[] = {
@@ -78,7 +88,7 @@ void copyPresentedFrame(VkCommandBuffer cmd, VkImage source, LsfgImage& destinat
     destination.SetLayout(VK_IMAGE_LAYOUT_GENERAL);
 }
 
-}
+} // namespace
 
 Engine::Engine() = default;
 
@@ -132,6 +142,9 @@ void Engine::setGuestExtent(uint32_t width, uint32_t height) {
     peakGuestExtent_.height = std::max(peakGuestExtent_.height, height);
 }
 
+// The flow pyramid is the expensive part, so its resolution is scaled relative
+// to the largest guest surface seen: a game running well below panel
+// resolution does not need a panel-resolution flow field.
 float Engine::effectiveFlowScale(uint32_t width) const {
     if (width == 0 || peakGuestExtent_.width == 0) return flowScale_;
     const float ratio = (float)peakGuestExtent_.width / (float)width;
@@ -158,6 +171,8 @@ bool Engine::prepare(uint32_t width, uint32_t height, VkFormat format) {
     chain_ = std::make_unique<LsfgChain>(device_, *shaders_, VkExtent2D{width, height}, format,
                                          scale);
     if (!chain_->Valid()) {
+        // A device that cannot build the chain reports unsupported once and
+        // stops trying, rather than thrashing allocations every frame.
         LSFG_LOGW("chain build failed at %ux%u; frame generation unavailable", width, height);
         chain_.reset();
         unavailable_ = true;
@@ -189,9 +204,17 @@ uint32_t Engine::plan(uint32_t capacity, uint64_t sourceFrames) {
 
     plan_ = pacer_.Plan(std::min<size_t>(capacity, kMaxGenerations), sourceFrames);
 
+    // The pacer says how many frames FIT in the panel's budget. The governor
+    // says how many this device can actually afford right now - on a handheld
+    // the chain competes with the game for one GPU, so an extra generation has
+    // to prove it improves total output without collapsing the real frame rate.
     if (governorEnabled_) {
         const LsfgPacerStats s = pacer_.Stats();
         governor_.configure((uint32_t)std::min<size_t>(pacer_.MaxGenerations(), kMaxGenerations));
+        // presentedRate_, NOT the pacer's loop rate. The pacer samples its loop
+        // once per SOURCE frame, so its "loop rate" is the guest rate by
+        // construction and can never show that generation added anything - the
+        // governor could not accept a probe on any hardware.
         plan_.generations = governor_.cap((uint32_t)plan_.generations, s.source_rate,
                                           presentedRate_);
     }
@@ -200,6 +223,12 @@ uint32_t Engine::plan(uint32_t capacity, uint64_t sourceFrames) {
     warmStreak_ = warm_ ? warmStreak_ + 1 : 0;
     generating_ = warm_ && warmStreak_ >= kRecurrenceFrames && plan_.generations > 0;
 
+    // The ring is only seeded while generating, so the first frame after any
+    // gap - arming, or a pacer discontinuity after a hitch - would interpolate
+    // between this frame and whatever the other slot held when generation last
+    // stopped. That is a visible warp, and it happens every time the engine
+    // starts. Spend this frame filling the ring instead and generate from the
+    // next one, when both slots are genuinely consecutive.
     primeHistory_ = false;
     if (generating_ && !historyFresh()) {
         primeHistory_ = true;
@@ -236,6 +265,11 @@ void Engine::process(VkCommandBuffer cmd, VkImage source, uint32_t width, uint32
     lastCount_ = count;
     lastGenerations_ = generations;
 
+    // Seeding the input ring is a full-resolution image copy every frame, so it
+    // is NOT free at 100 fps - it was costing real frame rate while producing
+    // nothing. Copy only when generating, on the one priming frame that
+    // precedes generation, or while the governor is warming up towards a
+    // probe - so the ring is populated by the time it is needed.
     const bool needHistory = generations > 0 || primeHistory_ || followEveryFrame()
         || (governorEnabled_ && governor_.wantsHistory());
     if (needHistory) {
@@ -244,6 +278,13 @@ void Engine::process(VkCommandBuffer cmd, VkImage source, uint32_t width, uint32
         haveCopied_ = true;
     }
 
+    // The SHARED chain is 24 of the 25 shaders - the whole flow pyramid - and
+    // only `generate` runs per generated frame. Running it while producing
+    // nothing spends almost the entire cost of frame generation for no frames
+    // at all, every frame. That is what pinned the GPU at 100% on device
+    // regardless of the game's own settings, and it fed straight back into the
+    // governor: the chain made the source rate collapse, the governor saw the
+    // collapse and refused to generate, and refusing did not stop the chain.
     if (warm_ && (generations > 0 || followEveryFrame())) chain_->DispatchShared(cmd, count);
 }
 
@@ -277,4 +318,4 @@ void Engine::reset() {
     plan_ = {};
 }
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_engine.h

@@ -1,4 +1,25 @@
 #pragma once
+// ============================================================================
+// lsfg_engine - the compositor's handle on native LSFG frame generation.
+//
+// Owns the shader modules, the interpolation chain and the pacer, and exposes
+// the small contract the render loop needs:
+//
+//   prepare(w, h, format)                 build/rebuild the chain for this size
+//   plan(capacity, sourceFrames)          how many frames to generate this time
+//   process(cmd, source, w, h, gens)      take frame N in, run the shared chain
+//   generateInto(cmd, g, i, img, view)    synthesise generated frame g
+//
+// Ordering matters and is not obvious: interpolation produces frames that
+// belong BETWEEN N-1 and N, so the generated frames are presented FIRST and
+// the real frame N is held back one slot. That one output interval is the
+// unavoidable cost of interpolating rather than extrapolating; no placement of
+// this code changes it.
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative (vkr_lsfg.cpp) and DroidDeck by
+// @maxjivi05, where it runs on gamescope's output in the compositor.
+// ============================================================================
 
 #include <cstdint>
 #include <memory>
@@ -7,7 +28,7 @@
 #include <vulkan/vulkan.h>
 
 #include "lsfg_common.hpp"
-#include "lsfg_dll.h"
+#include "lsfg_dll.h"      // kSpirv16
 #include "lsfg_governor.h"
 #include "lsfg_pacer.hpp"
 
@@ -16,16 +37,27 @@ namespace lsfg {
 class LsfgShaders;
 class LsfgChain;
 
+// Hard ceiling on generated frames per source frame (2x..4x -> 1..3).
 constexpr uint32_t kMaxGenerations = 3;
 
 class Engine {
 public:
+    // Both the constructor and destructor are out-of-line ON PURPOSE. The
+    // shader set and the chain are held by unique_ptr to forward-declared
+    // types, and an inline constructor would make the compiler emit the
+    // exception-cleanup path for those members at every construction site -
+    // which needs the complete types there. Keeping both here confines that to
+    // lsfg_engine.cpp, where the types are complete.
     Engine();
     ~Engine();
 
     Engine(const Engine&) = delete;
     Engine& operator=(const Engine&) = delete;
 
+    // Build the shader modules from a cache produced by lsfg_dll::buildCache.
+    // Returns false if the cache does not yield all 25 modules. `spirvTarget`
+    // is the highest SPIR-V version the device accepts (lsfg_probe.h); the
+    // cached 1.6 modules are lowered to it when it is below that.
     bool init(VkDevice device, VkPhysicalDevice physicalDevice, const std::string& cachePath,
               uint32_t spirvTarget = kSpirv16);
 
@@ -39,18 +71,28 @@ public:
     bool needsRebuild(uint32_t width, uint32_t height, VkFormat format) const;
     bool prepare(uint32_t width, uint32_t height, VkFormat format);
 
+    // How many frames to generate for this source frame. Returns 0 until the
+    // history slots are valid and the rates have settled, so the first frames
+    // after a start or a resize are never interpolated from garbage.
     uint32_t plan(uint32_t capacity, uint64_t sourceFrames);
 
+    // Take the just-composited frame as LSFG input and run the shared part of
+    // the chain (everything except `generate`). `source` must be in GENERAL.
     void process(VkCommandBuffer cmd, VkImage source, uint32_t width, uint32_t height,
                  uint32_t generations);
 
+    // Synthesise generated frame `generation` into the given storage image.
     void generateInto(VkCommandBuffer cmd, uint32_t generation, uint32_t targetIndex,
                       VkImage targetImage, VkImageView targetView,
                       uint32_t width, uint32_t height);
 
+    // What the probe governor currently trusts, and the latest thermal
+    // reading (-1 = no signal). Surfaced for the HUD and diagnostics.
     uint32_t acceptedGenerations() const { return governor_.accepted(); }
     int      thermalStatus() const { return governor_.thermalStatus(); }
     float    sourceRate() const;
+    // The rate that actually reaches the panel, generated frames included.
+    // Supplied by the renderer, which is the only thing that counts presents.
     float    loopRate() const { return presentedRate_; }
     void     setPresentedRate(float fps) { presentedRate_ = fps; }
 
@@ -60,8 +102,16 @@ public:
 private:
     float effectiveFlowScale(uint32_t width) const;
 
+    // A generated frame is a blend of the last two REAL frames, so the input
+    // ring - which is two images deep - only holds usable history when the
+    // other slot was filled by the frame immediately before this one. It is
+    // not, every time generation resumes after a pause: the ring is seeded
+    // only while generating, so the slot still carries whatever was there when
+    // generation last stopped.
     bool historyFresh() const { return haveCopied_ && lastCopiedCount_ + 1 == frameCount_; }
 
+    // With a target rate the pacer plans 0..3 generations frame by frame, so the ring and the
+    // shared chain have to follow every frame it keeps warm, not just the ones that generate.
     bool followEveryFrame() const { return warm_ && pacer_.Config().target_rate != 0; }
 
     Device      device_{};
@@ -70,6 +120,12 @@ private:
     std::unique_ptr<LsfgChain>   chain_;
     LsfgPacer      pacer_;
     ProbeGovernor  governor_;
+    // The governor is OFF by default: the device's own thermal management is
+    // the authority, and a probe loop that can veto the user's setting is not
+    // wanted here. The multiplier is then what was asked for, still clamped by
+    // what the panel can show. Kept behind a flag rather than deleted because
+    // the probe/backoff logic is the right answer for a device WITHOUT decent
+    // native throttling, and this is the only thing that would have to change.
     bool           governorEnabled_ = false;
     LsfgPlan    plan_{};
 
@@ -95,4 +151,4 @@ private:
     bool     unavailable_{};
 };
 
-}
+} // namespace lsfg

app/src/main/cpp/framegen/lsfg/lsfg_gamma.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_gamma.hpp"
 #include "lsfg_shaders.hpp"

app/src/main/cpp/framegen/lsfg/lsfg_gamma.hpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #pragma once
 

app/src/main/cpp/framegen/lsfg/lsfg_generate.cpp

@@ -3,6 +3,10 @@
 
 // SPDX-FileCopyrightText: Copyright 2025 lsfg-vk
 // SPDX-License-Identifier: GPL-3.0-or-later
+//
+// LSFG from the work of Camille LaVey / the Eden Emulator Project, following
+// upstream lsfg-vk. Ported to WinNative and DroidDeck by @maxjivi05; only the
+// Vulkan dispatch differs here (see lsfg_vkd.h).
 
 #include "lsfg_generate.hpp"
 #include "lsfg_dll.h"