mangotune/docs/MANGOHUD_POSITION_LAB.md

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:

scripts/mangohud-position-lab.sh <config> [glxgears|vkcube] [output_dir]

Examples:

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:

scripts/mangohud-position-matrix.sh [vkcube|glxgears] [output_dir] [profile_dir]

Examples:

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:

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:

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:

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