Initial import

2026-03-30 22:51:56 -04:00
commit 08e2910b9d
103 changed files with 35475 additions and 0 deletions
@@ -0,0 +1,159 @@
+# MangoHud Position Lab
+
+This is a direct MangoHud test harness for debugging positioning behavior outside MangoTune's
+preview pipeline.
+
+## Why
+
+When right-aligned horizontal preview behavior looks wrong, the first question is whether the
+problem is in MangoTune's preview math or MangoHud itself. This lab runs MangoHud directly
+against a simple test app so the behavior can be compared without preview-only overrides.
+
+## Script
+
+Use:
+
+```bash
+scripts/mangohud-position-lab.sh <config> [glxgears|vkcube] [output_dir]
+```
+
+Examples:
+
+```bash
+scripts/mangohud-position-lab.sh ~/.config/mangotune/profiles/zz_test_right_sparse_top.conf glxgears
+scripts/mangohud-position-lab.sh ~/.config/mangotune/profiles/zz_test_right_full_top.conf vkcube /tmp/mh-lab/full-top
+```
+
+The script:
+- launches MangoHud directly
+- records stdout/stderr to `run.log`
+- tries to dump the X window tree to `xwininfo.tree`
+- tries to capture window geometry and a screenshot when `xdotool`/`import` are available
+- honors `DISPLAY`, `XAUTHORITY`, `WAIT_SECS`, `WIDTH`, and `HEIGHT` from the environment
+
+## Matrix runner
+
+For the standard right-alignment repro set, use:
+
+```bash
+scripts/mangohud-position-matrix.sh [vkcube|glxgears] [output_dir] [profile_dir]
+```
+
+Examples:
+
+```bash
+scripts/mangohud-position-matrix.sh vkcube /tmp/mh-matrix
+DISPLAY=:1 XAUTHORITY=/root/.Xauthority scripts/mangohud-position-matrix.sh vkcube /tmp/mh-matrix /home/aaron/mangotune-test-profiles
+```
+
+This generates both margin-on and margin-off variants for the standard right-alignment test
+profiles and captures each case directly through MangoHud.
+
+## Suggested Test Matrix
+
+Run at least these profile families:
+
+1. `zz_test_right_full_top.conf`
+2. `zz_test_right_sparse_top.conf`
+3. `zz_test_right_sparse_middle.conf`
+4. `zz_test_right_sparse_compact_top.conf`
+5. `zz_test_right_sparse_compact_middle.conf`
+
+Then compare:
+- `hud_no_margin` on vs off
+- `hud_compact` on vs off
+- sparse vs fuller layouts
+- `top-right` vs `middle-right`
+
+Recommended validation order:
+
+1. `full` top-right, margin on
+2. `full` top-right, margin off
+3. `sparse` top-right, margin on
+4. `sparse` top-right, margin off
+5. `sparse_compact` top-right, margin off
+6. `sparse` middle-right, margin off
+7. `sparse_compact` middle-right, margin off
+
+## Isolated Xorg on arch.lan
+
+When local testing would interrupt the user desktop, `arch.lan` can run a separate Xorg on
+another VT and use that for direct MangoHud captures:
+
+```bash
+ssh aaron@arch.lan
+sudo -n xinit /bin/bash -lc 'xsetroot -solid black; while :; do sleep 3600; done' \
+  -- /usr/bin/Xorg :1 vt8 -nolisten tcp -noreset
+```
+
+Then from another shell:
+
+```bash
+ssh aaron@arch.lan '
+  DISPLAY=:1 XAUTHORITY=/root/.Xauthority \
+  /path/to/mangotune/scripts/mangohud-position-matrix.sh \
+    vkcube /tmp/mh-matrix /home/aaron/mangotune-test-profiles
+'
+```
+
+That keeps the direct MangoHud investigation isolated from the main desktop session.
+
+## Expected MangoHud Semantics
+
+From MangoHud's upstream README:
+- `position=` supports `top-right`, `middle-right`, and `bottom-right` directly
+- `horizontal` enables horizontal layout
+- `horizontal_stretch` stretches the background to the screen width in horizontal mode
+- `hud_no_margin` removes margins around MangoHud
+- `offset_x` and `offset_y` are generic HUD position offsets
+- `width=` overrides the automatically computed HUD width
+
+That means MangoTune should be conservative about inventing extra right-anchor behavior. If
+MangoHud itself has a quirk here, MangoTune should document or surface it rather than baking in
+fragile compensations unless absolutely necessary.
+
+## Upstream source findings
+
+From MangoHud upstream `src/overlay.cpp` and `src/overlay_params.cpp`:
+
+- Default edge margin is `10.0f`.
+- The margin is forced to `0.0f` whenever **any** of these are true:
+  - `offset_x > 0`
+  - `offset_y > 0`
+  - `hud_no_margin` is enabled
+- For right-side anchors, MangoHud positions the HUD with:
+
+```cpp
+x = display_width - window_size.x - margin + offset_x
+```
+
+That means:
+- right anchors are native in MangoHud
+- positive `offset_x` pushes a right-anchored HUD farther right, not inward
+- because `offset_x` is parsed as unsigned, MangoHud cannot use a negative right-anchor offset
+  to nudge the HUD left from `top-right` / `middle-right` / `bottom-right`
+
+Also note:
+
+- `horizontal_stretch` defaults to `true` upstream, so `horizontal_stretch=0` must be written
+  explicitly when the user disables it
+- `offset_x` / `offset_y` are parsed as unsigned values upstream
+
+These semantics should be treated as source-of-truth before adding any MangoTune-side
+compensation.
+
+## Capture caveat
+
+On the isolated remote Xorg lab, direct screenshot methods can still miss MangoHud's overlay
+entirely while capturing the app window correctly. This includes:
+
+- ImageMagick `import` against the app window
+- ImageMagick `import -window root` against the full desktop
+- `ffmpeg -f x11grab` style X11 captures
+
+So:
+
+- direct launch/log/geometry capture is reliable there
+- direct pixel capture of the overlay is not yet a trustworthy automated oracle
+- if visual confirmation matters, a manual screenshot on a real desktop session is still the
+  most reliable check