Add controller input and a laser-pointer-driven menu quad

- xr_input.c/h: an OpenXR action set (aim pose, trigger/select click, a
  menu-toggle button) plus ray/quad hit-testing, and a visible
  laser-pointer line drawn from the controller toward the hit point.
- xr_menu.c/h + MenuOverlay.java: a second composition-layer quad,
  toggled by a controller button, showing an off-screen, never-attached
  Android View tree (one "Keyboard" button so far) driven by synthetic
  touch events computed from the laser ray's hit UV.
- Migrate gl4es from a prebuilt binary baked into the Docker build-image
  to a vendored source snapshot (android/gl4es-src/) compiled from
  source at APK build time via CMake add_subdirectory(), patched through
  a new android/gl4es-patches/ (mirrors the existing engine-patches/
  pattern). This was needed to track down and fix a bug hit while
  building the menu: gl4es's fixed-pipeline emulation (fpe.c) was
  unconditionally substituting its own shader onto the menu's draw call
  (fpe_ReleventState() always sets alphafunc to a nonzero sentinel, so
  its fpe_IsEmpty() check could never see the state as empty), making
  the menu quad show the game's own rendering instead of its own
  content. Fixed by routing the menu's blit through a real
  glBlitFramebuffer() call instead of a shader-based draw, which gl4es's
  fpe.c has nothing to intercept - documented in README.md's new
  "Debugging notes" section.
- Renumber android/engine-patches/ to close the gap left by removing an
  unrelated diagnostic-only patch, and strip investigation-journal
  comments and dead diagnostic code (temporary tracing, env-var probes)
  left over from finding the bug above.
- Restructure README.md into numbered sections, document every
  engine/gl4es patch, add Android Studio dev/testing-cycle instructions,
  and generalize Quest-specific wording to any OpenXR headset. Update
  NOTICE.txt to match (gl4es is now vendored/patched source, not a
  prebuilt binary; add the OpenXR-SDK loader).

build-image/Dockerfile

@@ -56,7 +56,21 @@ ARG ANDROID_16KB_LDFLAGS="-Wl,-z,max-page-size=16384"
 # GL4ES (https://github.com/ptitSeb/gl4es) - translates the engine's
 # desktop-style immediate-mode OpenGL calls into real GLES/EGL calls, so
 # engine/src/MacSrc/OpenGL.cc needs no immediate-mode rewrite on Android.
-ARG ANDROID_GL4ES_VERSION=1.1.6
+# Vendored directly into android/gl4es-src/ (currently tag v1.1.6, gl4es's
+# latest release) rather than fetched at build time, same rationale as
+# engine/: lets android/gl4es-patches/ instrument it directly (this is
+# Android/GLES-only, with no desktop build depending on it, so unlike
+# engine/ there's no shared tree to protect - see that patch's own comment
+# for why this was needed, tracking down the OpenXR menu-quad texture bug).
+# Re-vendoring a newer tag later: re-clone into android/gl4es-src/, then
+# reapply/update the patches in android/gl4es-patches/.
+# Unlike SDL2/SDL2_mixer/fluidsynth-lite/OpenXR below, gl4es is NOT
+# prebuilt in this image - it's compiled from a scratch, patched copy as a
+# CMake subdirectory of the engine's own native build (see
+# build-image/prepare-android-project.sh and
+# android/engine-patches/02-android-opengl-es.patch), so gl4es-patches/
+# changes only need a normal Android Studio/gradlew rebuild, not a
+# build-image rebuild.
 # Khronos' own OpenXR loader (https://github.com/KhronosGroup/OpenXR-SDK) -
 # the vendor-neutral loader, not Meta's redistributed copy, per this
 # project's "favor OpenXR" rule (see README's Design principles). Only the
@@ -92,17 +106,12 @@ ENV DEBIAN_FRONTEND=noninteractive
 # build cache for this layer - and vice versa, adding a package here only
 # ever costs a rebuild of the (slow) layers below it, not a re-download
 # of packages that didn't change.
-# patchelf: fixes up GL4ES's built-in ELF SONAME below (see the gl4es
-# build step) - the Android APK packager (AGP) refuses to bundle a
-# jniLibs file whose name doesn't literally end in ".so", but the
-# dynamic linker resolves NEEDED entries by embedded SONAME, not
-# filename - patchelf lets both agree on "libGL.so".
 RUN apt-get update && apt-get install -y --no-install-recommends \
         build-essential cmake make git curl ca-certificates pkg-config gosu \
         libgl1-mesa-dev libglx-dev libxext-dev libx11-dev libxrandr-dev \
         libxi-dev libxfixes-dev libxss-dev libxinerama-dev libxcursor-dev \
         libogg-dev libvorbis-dev libasound2-dev openssh-client \
-        openjdk-17-jdk-headless unzip patchelf \
+        openjdk-17-jdk-headless unzip \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /opt/prebuilt
@@ -252,34 +261,6 @@ RUN git clone https://github.com/EtherTyper/fluidsynth-lite.git fluidsynth-lite-
         /opt/prebuilt/android/fluidsynth-lite/include/fluidsynth/version.h \
     && rm -rf fluidsynth-lite-android build-fluidsynth-android
 
-# gl4es's own CMakeLists.txt writes its output straight to
-# ${CMAKE_SOURCE_DIR}/lib (the source tree, not the build dir) and gives
-# the GL target a ".so.1" suffix, both in filename and in its embedded
-# ELF SONAME - stage explicitly rather than `cmake --install` (which it
-# doesn't support for this target anyway). Renaming the *file* to
-# "libGL.so" isn't enough on its own: the dynamic linker resolves
-# libmain.so's NEEDED entry by the *embedded* SONAME, not by whatever
-# filename it was linked against, so a bare rename would link fine but
-# fail to dlopen on-device. And keeping the real "libGL.so.1" filename
-# isn't an option either - AGP's jniLibs packaging silently drops any
-# native library whose filename doesn't literally end in ".so". So
-# patchelf the embedded SONAME to "libGL.so" too, making the rename
-# consistent both at link time and at runtime.
-RUN git clone --branch "v${ANDROID_GL4ES_VERSION}" --depth 1 \
-        https://github.com/ptitSeb/gl4es.git gl4es-android \
-    && rm -rf gl4es-android/.git \
-    && cmake -S gl4es-android -B build-gl4es-android \
-        -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_TOOLCHAIN}" \
-        -DANDROID_ABI="${ANDROID_ABI}" -DANDROID_PLATFORM="android-${ANDROID_PLATFORM_VERSION}" \
-        -DANDROID=ON -DUSE_ANDROID_LOG=ON -DSTATICLIB=OFF \
-        -DCMAKE_SHARED_LINKER_FLAGS="${ANDROID_16KB_LDFLAGS}" \
-    && cmake --build build-gl4es-android -j"$(nproc)" \
-    && mkdir -p /opt/prebuilt/android/gl4es/lib /opt/prebuilt/android/gl4es/include \
-    && cp -a gl4es-android/lib/libGL.so.1 /opt/prebuilt/android/gl4es/lib/libGL.so \
-    && patchelf --set-soname libGL.so /opt/prebuilt/android/gl4es/lib/libGL.so \
-    && cp -a gl4es-android/include/. /opt/prebuilt/android/gl4es/include/ \
-    && rm -rf gl4es-android build-gl4es-android
-
 # OpenXR loader, for the immersive VR mode (android/app/src/main/cpp/
 # xr_session.c and friends) - see android/engine-patches/
 # 11-android-openxr-cmake.patch for how the engine links it.

build-image/build-apk.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 # Builds the Quest APK - see build-image/prepare-android-project.sh (which
-# this calls) for how android/ gets a scratch, patched copy of engine/,
-# the Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es prebuilts, and bundled
-# assets staged in. Run via ../run-image.sh (or directly, if already
-# inside this image - see the Makefile's `apk` target).
+# this calls) for how android/ gets scratch, patched copies of engine/ and
+# gl4es-src/, the Android SDL2/SDL2_mixer/fluidsynth-lite/openxr prebuilts,
+# and bundled assets staged in. Run via ../run-image.sh (or directly, if
+# already inside this image - see the Makefile's `apk` target).
 #
 # Unlike build-engine.sh, this step needs network access: Gradle/AGP's
 # own dependency resolution isn't prebuilt into the image (see

build-image/prepare-android-project.sh

@@ -1,11 +1,17 @@
 #!/usr/bin/env bash
 # Prepares android/ to be built: a scratch, patched copy of engine/ (see
-# android/engine-patches/ - engine/ itself is never modified), the
-# Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es/openxr prebuilts staged
-# into jniLibs, bundled assets, and android/engine.properties (engineDir/
-# prebuiltDir, read by android/app/build.gradle). Always run inside this
-# image (via ../run-image.sh, or directly if already inside it) - it
-# reads from /opt/prebuilt/android/*, which only exists there.
+# android/engine-patches/) and of android/gl4es-src/ (see
+# android/gl4es-patches/) - neither vendored tree itself is ever modified -
+# the Android SDL2/SDL2_mixer/fluidsynth-lite/openxr prebuilts staged into
+# jniLibs, bundled assets, and android/engine.properties (engineDir/
+# gl4esDir/prebuiltDir, read by android/app/build.gradle). gl4es itself is
+# NOT prebuilt here - it's compiled from this scratch copy as a CMake
+# subdirectory of the engine's own native build (see
+# android/engine-patches/02-android-opengl-es.patch), so gl4es-patches/
+# changes only need a normal rebuild, not a build-image rebuild. Always
+# run inside this image (via ../run-image.sh, or directly if already
+# inside it) - it reads from /opt/prebuilt/android/*, which only exists
+# there.
 #
 # Two modes:
 #   (no args)      - for build-apk.sh's own gradlew, invoked in this same
@@ -30,6 +36,7 @@ fi
 REPO_ROOT="$(pwd)"
 ANDROID_DIR="$REPO_ROOT/android"
 SCRATCH_ENGINE="$REPO_ROOT/build/android-engine"
+SCRATCH_GL4ES="$REPO_ROOT/build/android-gl4es"
 PREBUILT_EXPORT_DIR="$REPO_ROOT/build/android-prebuilt"
 
 echo "== Preparing a scratch, patched copy of engine/ =="
@@ -40,6 +47,13 @@ for p in "$ANDROID_DIR"/engine-patches/*.patch; do
     patch -p1 -d "$SCRATCH_ENGINE" < "$p"
 done
 
+echo "== Preparing a scratch, patched copy of android/gl4es-src/ =="
+rm -rf "$SCRATCH_GL4ES"
+cp -a "$ANDROID_DIR/gl4es-src" "$SCRATCH_GL4ES"
+for p in "$ANDROID_DIR"/gl4es-patches/*.patch; do
+    patch -p1 -d "$SCRATCH_GL4ES" < "$p"
+done
+
 echo "== Wiring up prebuilt Android SDL2_mixer/fluidsynth-lite (BUNDLED mode, like the desktop build) =="
 mkdir -p "$SCRATCH_ENGINE/build_ext/built_sdl_mixer" "$SCRATCH_ENGINE/build_ext/fluidsynth-lite"
 cp -a /opt/prebuilt/android/sdl2_mixer/. "$SCRATCH_ENGINE/build_ext/built_sdl_mixer/"
@@ -49,18 +63,21 @@ cp -a /opt/prebuilt/android/fluidsynth-lite/include/. "$SCRATCH_ENGINE/build_ext
 
 if [ "$HOST_PATHS" -eq 1 ]; then
     : "${HOST_REPO_ROOT:?--host-paths needs HOST_REPO_ROOT set - run via ./run-image.sh, not directly}"
-    echo "== Exporting prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es for host-side use =="
+    echo "== Exporting prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/openxr for host-side use =="
     rm -rf "$PREBUILT_EXPORT_DIR"
     cp -a /opt/prebuilt/android "$PREBUILT_EXPORT_DIR"
     ENGINE_DIR_PROP="$HOST_REPO_ROOT/build/android-engine"
+    GL4ES_DIR_PROP="$HOST_REPO_ROOT/build/android-gl4es"
     PREBUILT_DIR_PROP="$HOST_REPO_ROOT/build/android-prebuilt"
 else
     ENGINE_DIR_PROP="$SCRATCH_ENGINE"
+    GL4ES_DIR_PROP="$SCRATCH_GL4ES"
     PREBUILT_DIR_PROP="/opt/prebuilt/android"
 fi
 
 {
     echo "engineDir=$ENGINE_DIR_PROP"
+    echo "gl4esDir=$GL4ES_DIR_PROP"
     echo "prebuiltDir=$PREBUILT_DIR_PROP"
 } > "$ANDROID_DIR/engine.properties"
 
@@ -75,16 +92,22 @@ cp -a "$ANDROID_DIR/gles-shaders/." "$ASSETS_DIR/shaders/"
 cp "/opt/prebuilt/soundfont/default.sf2" "$ASSETS_DIR/res/soundfont.sf2"
 cp "$REPO_ROOT/res/assets/GET_ASSETS_QUEST.txt" "$ASSETS_DIR/GET_ASSETS_QUEST.txt"
 
-echo "== Staging prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/gl4es/openxr .so's into jniLibs =="
+echo "== Staging prebuilt Android SDL2/SDL2_mixer/fluidsynth-lite/openxr .so's into jniLibs =="
+# gl4es is deliberately absent here - it's no longer prebuilt, it's compiled
+# from $SCRATCH_GL4ES as part of the engine's own native build (see
+# android/engine-patches/02-android-opengl-es.patch); AGP's own native-build
+# packaging picks up its compiled libGL.so directly, without needing it
+# staged into jniLibs by this script.
 JNI_LIBS_DIR="$ANDROID_DIR/app/src/main/jniLibs/arm64-v8a"
 rm -rf "$ANDROID_DIR/app/src/main/jniLibs"
 mkdir -p "$JNI_LIBS_DIR"
 find /opt/prebuilt/android/sdl2/lib /opt/prebuilt/android/sdl2_mixer/lib /opt/prebuilt/android/fluidsynth-lite/lib \
-    /opt/prebuilt/android/gl4es/lib /opt/prebuilt/android/openxr/lib \
+    /opt/prebuilt/android/openxr/lib \
     -name '*.so' -exec cp -a {} "$JNI_LIBS_DIR/" \;
 
 echo "== Done =="
 echo "engineDir=$ENGINE_DIR_PROP"
+echo "gl4esDir=$GL4ES_DIR_PROP"
 echo "prebuiltDir=$PREBUILT_DIR_PROP"
 if [ "$HOST_PATHS" -eq 1 ]; then
     echo "android/ is ready to open and build natively in Android Studio on the host."