Initial import

2026-03-30 22:51:56 -04:00
commit 08e2910b9d
103 changed files with 35475 additions and 0 deletions
@@ -0,0 +1,439 @@
+# MangoHud Schema Reference
+
+Superseded as the user-facing/help-source reference by
+[`docs/MANGOHUD_OPTION_BEHAVIOR.md`](/home/aaron/Programming/mangotune/docs/MANGOHUD_OPTION_BEHAVIOR.md).
+Keep this file only as schema-planning context for `src/config/schema.rs`.
+
+Source: Official MangoHud repository `data/MangoHud.conf` cross-referenced with
+the MangoHud README and source code. Last verified against MangoHud 0.7.x.
+
+This file is no longer the authoritative help text source and does not currently
+cover every upstream MangoHud option.
+
+## Schema Entry Structure
+
+Each option in `schema.rs` must encode:
+```rust
+pub struct SchemaEntry {
+    pub key: &'static str,
+    pub option_type: OptionType,
+    pub default: DefaultValue,
+    pub description: &'static str,
+    pub category: Category,
+    pub dependencies: &'static [&'static str],  // options that must be enabled for this to work
+    pub conflicts_with: &'static [&'static str], // mutually exclusive options
+    pub gpu_vendor_only: Option<GpuVendor>,      // None = all, Some(Amd) = AMD only
+    pub gamescope_only: bool,
+    pub mangoapp_only: bool,
+}
+
+pub enum OptionType {
+    Flag,                          // bare key, no value — presence means enabled
+    Bool,                          // key=0 or key=1
+    Int { min: i64, max: i64 },
+    Float { min: f64, max: f64 },
+    String { max_len: usize },
+    Color,                         // 6-char hex RRGGBB, no #
+    Enum { variants: &'static [&'static str] },
+    FpsLimitList,                  // comma-separated ints e.g. "0,30,60"
+    KeyBind,                       // e.g. "Shift_R+F12"
+    CommaSeparatedInts,
+    CommaSeparatedFloats,
+    CommaSeparatedStrings,
+    Path,                          // filesystem path, validated to exist or be writable
+}
+```
+
+---
+
+## Category: PERFORMANCE
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `fps_limit` | FpsLimitList | `0` | 0 = unlimited; comma-separated list e.g. `0,30,60` |
+| `fps_limit_method` | Enum[`early`,`late`] | `""` | early = wait before present |
+| `vsync` | Int[-1..3] | `-1` | -1=unset; 0=adaptive; 1=off; 2=mailbox; 3=on |
+| `gl_vsync` | Int[-2..N] | `-2` | OpenGL only; -2=unset; 0=off; >=1=wait N vblanks |
+| `picmip` | Int[-17..16] | `-17` | Mip-map LoD bias; negative=sharper |
+| `af` | Int[-1..16] | `-1` | Anisotropic filtering; -1=unset |
+| `bicubic` | Flag | absent | Force bicubic filtering |
+| `trilinear` | Flag | absent | Force trilinear filtering |
+| `retro` | Flag | absent | Disable linear filtering (blocky textures) |
+
+---
+
+## Category: DISPLAY — FPS & FRAMETIME
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `fps` | Flag | present | Show FPS counter — enabled by default |
+| `fps_only` | Flag | absent | CONFLICTS WITH: all other display params |
+| `fps_sampling_period` | Int[100..60000] | `500` | ms |
+| `fps_color_change` | Flag | absent | Enable FPS color thresholds |
+| `fps_value` | CommaSeparatedInts | `30,60` | Two thresholds: warn,ok |
+| `fps_color` | CommaSeparatedStrings | `B22222,FDFD09,39F900` | Three hex colors: low,mid,high |
+| `fps_text` | String | `""` | Custom label for FPS row |
+| `fps_metrics` | CommaSeparatedStrings | `""` | e.g. `avg,0.01,1,97` — `AVG` or decimal percentiles |
+| `frametime` | Flag | present | Show frametime — enabled by default |
+| `frame_count` | Flag | absent | Show frame counter |
+| `frame_timing` | Flag | present | Frametime graph — enabled by default |
+| `frame_timing_detailed` | Flag | absent | More detailed frametime graph |
+| `dynamic_frame_timing` | Flag | absent | Dynamic scale frametime graph |
+| `histogram` | Flag | absent | CONFLICTS WITH frame_timing |
+| `throttling_status` | Flag | present | GPU throttling indicator |
+| `throttling_status_graph` | Flag | absent | Show throttling on frametime graph |
+| `show_fps_limit` | Flag | absent | Display current FPS limit value |
+
+---
+
+## Category: DISPLAY — GPU
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `gpu_stats` | Flag | present | Master GPU section toggle |
+| `gpu_temp` | Flag | absent | |
+| `gpu_junction_temp` | Flag | absent | |
+| `gpu_core_clock` | Flag | absent | |
+| `gpu_mem_temp` | Flag | absent | DEPENDS ON: `vram` |
+| `gpu_mem_clock` | Flag | absent | DEPENDS ON: `vram` |
+| `gpu_power` | Flag | absent | |
+| `gpu_power_limit` | Flag | absent | |
+| `gpu_text` | String[32] | `""` | Custom GPU label |
+| `gpu_load_change` | Flag | absent | Color GPU load |
+| `gpu_load_value` | CommaSeparatedInts | `60,90` | Two load thresholds |
+| `gpu_load_color` | CommaSeparatedStrings | `39F900,FDFD09,B22222` | Three hex colors |
+| `gpu_fan` | Flag | absent | RPM on AMD, percent on NVIDIA |
+| `gpu_voltage` | Flag | absent | AMD ONLY |
+| `gpu_list` | CommaSeparatedInts | `""` | Select GPUs by index e.g. `0,1` |
+| `gpu_efficiency` | Flag | absent | |
+| `gpu_name` | Flag | absent | Show GPU model name |
+| `vulkan_driver` | Flag | absent | Show Vulkan driver string |
+| `engine_version` | Flag | absent | |
+| `engine_short_names` | Flag | absent | |
+| `present_mode` | Flag | absent | |
+| `pci_dev` | String | `""` | Format: `domain:bus:slot.function` e.g. `0000:03:00.0` |
+
+---
+
+## Category: DISPLAY — CPU
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `cpu_stats` | Flag | present | Master CPU section toggle |
+| `cpu_temp` | Flag | absent | |
+| `cpu_power` | Flag | absent | |
+| `cpu_text` | String[32] | `""` | Custom CPU label |
+| `cpu_mhz` | Flag | absent | Average MHz across cores |
+| `cpu_load_change` | Flag | absent | Color CPU load |
+| `cpu_load_value` | CommaSeparatedInts | `60,90` | Two thresholds |
+| `cpu_load_color` | CommaSeparatedStrings | `39F900,FDFD09,B22222` | Three hex colors |
+| `cpu_efficiency` | Flag | absent | |
+| `core_load` | Flag | absent | Per-core load bars |
+| `core_load_change` | Flag | absent | Color per-core load |
+| `core_bars` | Flag | absent | Graphical core bars |
+| `core_type` | Flag | absent | Show P/E core type labels |
+
+---
+
+## Category: DISPLAY — MEMORY
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `vram` | Flag | absent | Required by gpu_mem_clock, gpu_mem_temp |
+| `ram` | Flag | absent | |
+| `swap` | Flag | absent | |
+| `procmem` | Flag | absent | Per-process resident memory |
+| `procmem_shared` | Flag | absent | DEPENDS ON: `procmem` |
+| `procmem_virt` | Flag | absent | DEPENDS ON: `procmem` |
+| `proc_vram` | Flag | absent | Per-process VRAM |
+
+---
+
+## Category: DISPLAY — I/O & NETWORK
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `io_read` | Flag | absent | Per-app I/O read |
+| `io_write` | Flag | absent | Per-app I/O write |
+| `network` | CommaSeparatedStrings | `""` | Network interfaces e.g. `eth0,wlo1`; empty = all |
+
+---
+
+## Category: DISPLAY — MISC INDICATORS
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `wine` | Flag | absent | Wine/Proton version |
+| `winesync` | Flag | absent | Wine sync method |
+| `exec_name` | Flag | absent | Show executable name |
+| `arch` | Flag | absent | MangoHud architecture |
+| `gamemode` | Flag | absent | GameMode running status |
+| `vkbasalt` | Flag | absent | vkBasalt running status |
+| `engine_version` | Flag | absent | |
+| `version` | Flag | absent | Show MangoHud version in overlay |
+| `resolution` | Flag | absent | Current display resolution |
+| `display_server` | Flag | absent | Wayland/X11 indicator |
+| `temp_fahrenheit` | Flag | absent | Use °F instead of °C |
+| `flip_efficiency` | Flag | absent | Joules per frame |
+| `fex_stats` | Flag | absent | FEX-Emu stats (ARM64 only) |
+
+---
+
+## Category: DISPLAY — GRAPHS
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `graphs` | CommaSeparatedStrings | `""` | Valid values: `gpu_load,cpu_load,gpu_core_clock,gpu_mem_clock,vram,ram,cpu_temp,gpu_temp` |
+
+---
+
+## Category: DISPLAY — BATTERY
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `battery` | Flag | absent | |
+| `battery_icon` | Flag | absent | DEPENDS ON: `battery` |
+| `device_battery` | CommaSeparatedStrings | `""` | e.g. `gamepad,mouse` |
+| `device_battery_icon` | Flag | absent | |
+| `battery_watt` | Flag | absent | DEPENDS ON: `battery` |
+| `battery_time` | Flag | absent | DEPENDS ON: `battery` |
+
+---
+
+## Category: DISPLAY — MEDIA PLAYER
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `media_player` | Flag | absent | Enable media player metadata |
+| `media_player_name` | String | `""` | e.g. `spotify` — DEPENDS ON: `media_player` |
+| `media_player_format` | String | `""` | e.g. `{title};{artist};{album}` — DEPENDS ON: `media_player` |
+
+---
+
+## Category: DISPLAY — GAMESCOPE
+
+All options in this category: `gamescope_only = true`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `fsr` | Flag | absent | FSR status |
+| `hide_fsr_sharpness` | Flag | absent | DEPENDS ON: `fsr` |
+| `hdr` | Flag | absent | HDR status |
+| `refresh_rate` | Flag | absent | Current refresh rate |
+| `debug` | Flag | absent | Gamescope app frametimes graph |
+
+---
+
+## Category: DISPLAY — STEAM DECK
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `fan` | Flag | absent | Steam Deck fan RPM |
+| `mangoapp_steam` | Flag | absent | mangoapp only |
+
+---
+
+## Category: DISPLAY — TIME & MISC TEXT
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `time` | Flag | absent | Current time |
+| `time_no_label` | Flag | absent | DEPENDS ON: `time` |
+| `time_format` | String | `"%T"` | strftime format |
+| `custom_text_center` | String | `""` | Centered header text |
+| `custom_text` | String | `""` | Custom text line |
+| `exec` | String | `""` | Shell command — output shown in next column |
+
+---
+
+## Category: APPEARANCE — LAYOUT
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `legacy_layout` | Bool | `0` | |
+| `preset` | Int[-1..4] | `-1` | -1=default; 0=off; 1=fps only; 2=horizontal; 3=extended; 4=high detail |
+| `full` | Flag | absent | Enable most toggleable params |
+| `no_display` | Flag | absent | Start hidden |
+| `horizontal` | Flag | absent | Horizontal layout |
+| `horizontal_stretch` | Flag | absent | DEPENDS ON: `horizontal` |
+| `hud_compact` | Flag | absent | Compact mode |
+| `hud_no_margin` | Flag | absent | Remove margins |
+| `position` | Enum[`top-left`,`top-right`,`bottom-left`,`bottom-right`,`top-center`,`middle-left`,`middle-right`,`bottom-center`] | `top-left` | |
+| `offset_x` | Int[0..9999] | `0` | pixels |
+| `offset_y` | Int[0..9999] | `0` | pixels |
+| `width` | Int[0..9999] | `0` | 0 = auto |
+| `height` | Int[0..9999] | `140` | |
+| `table_columns` | Int[1..10] | `3` | |
+| `cellpadding_y` | Float[-2.0..2.0] | `-0.085` | |
+| `round_corners` | Int[0..50] | `0` | |
+| `background_alpha` | Float[0.0..1.0] | `0.5` | |
+| `alpha` | Float[0.0..1.0] | `1.0` | Overall HUD transparency |
+
+---
+
+## Category: APPEARANCE — COLORS
+
+All color values: 6-char hex string RRGGBB (no `#`). Validate: must match `^[0-9A-Fa-f]{6}$`.
+
+| Key | Default |
+|-----|---------|
+| `text_color` | `FFFFFF` |
+| `gpu_color` | `2E9762` |
+| `cpu_color` | `2E97CB` |
+| `vram_color` | `AD64C1` |
+| `ram_color` | `C26693` |
+| `engine_color` | `EB5B5B` |
+| `io_color` | `A491D3` |
+| `frametime_color` | `00FF00` |
+| `background_color` | `020202` |
+| `media_player_color` | `FFFFFF` |
+| `wine_color` | `EB5B5B` |
+| `battery_color` | `FF9078` |
+| `network_color` | `E07B85` |
+| `horizontal_separator_color` | `AD64C1` |
+
+Also:
+| Key | Type | Default |
+|-----|------|---------|
+| `text_outline` | Flag | present (default on) |
+| `text_outline_color` | Color | `000000` |
+| `text_outline_thickness` | Float[0.5..5.0] | `1.5` |
+
+---
+
+## Category: APPEARANCE — TYPOGRAPHY
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `font_size` | Int[8..72] | `24` | |
+| `font_scale` | Float[0.1..5.0] | `1.0` | |
+| `font_size_text` | Int[8..72] | `24` | For text elements |
+| `font_scale_media_player` | Float[0.1..5.0] | `0.55` | |
+| `no_small_font` | Flag | absent | Disable small font for secondary info |
+| `font_file` | Path | `""` | TTF/OTF path — validated to exist if set |
+| `font_file_text` | Path | `""` | |
+| `font_glyph_ranges` | CommaSeparatedStrings | `""` | Valid: `korean,chinese,chinese_simplified,japanese,cyrillic,thai,vietnamese,latin_ext_a,latin_ext_b` |
+
+---
+
+## Category: BEHAVIOR — KEYBINDINGS
+
+All keybind values: format is `Key` or `Modifier+Key` or `Mod1+Mod2+Key`.
+Valid modifiers: `Shift_L`, `Shift_R`, `Control_L`, `Control_R`, `Alt_L`, `Alt_R`, `Super_L`, `Super_R`.
+
+| Key | Default |
+|-----|---------|
+| `toggle_hud` | `Shift_R+F12` |
+| `toggle_hud_position` | `Shift_R+F11` |
+| `toggle_preset` | `Shift_R+F10` |
+| `toggle_fps_limit` | `Shift_L+F1` |
+| `toggle_logging` | `Shift_L+F2` |
+| `reload_cfg` | `Shift_L+F4` |
+| `upload_log` | `Shift_L+F3` |
+| `reset_fps_metrics` | `Shift_R+F9` |
+
+---
+
+## Category: BEHAVIOR — LOGGING
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `autostart_log` | Int[0..3600] | absent | Seconds before auto-start |
+| `log_duration` | Int[1..86400] | absent | Seconds |
+| `log_interval` | Int[0..10000] | `0` | ms; 0 = default |
+| `output_folder` | Path | `""` | Must be writable directory |
+| `output_file` | String | `""` | |
+| `permit_upload` | Bool | `0` | Upload to flightlessmango.com |
+| `benchmark_percentiles` | CommaSeparatedStrings | `97,AVG` | |
+| `log_versioning` | Flag | absent | |
+| `upload_logs` | Flag | absent | DEPENDS ON: `permit_upload=1` |
+
+---
+
+## Category: BEHAVIOR — MISC
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `blacklist` | CommaSeparatedStrings | `""` | App names to suppress overlay |
+| `control` | String | `-1` | Socket name; -1=disabled; `%p` replaced with PID |
+
+---
+
+## Category: WORKAROUNDS — OPENGL
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `gl_size_query` | Enum[`viewport`,`scissorbox`,`disabled`] | `""` | Default: glXQueryDrawable |
+| `gl_bind_framebuffer` | Int[0..999] | absent | Rebind framebuffer before draw |
+| `gl_dont_flip` | Bool | absent | Don't swap origin for GL_UPPER_LEFT |
+
+---
+
+## Category: ADVANCED — FCAT
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `fcat` | Flag | absent | Enable FCAT overlay |
+| `fcat_overlay_width` | Int[20..200] | `24` | DEPENDS ON: `fcat` |
+| `fcat_screen_edge` | Int[0..3] | `0` | DEPENDS ON: `fcat` |
+
+---
+
+## Category: ADVANCED — FTRACE
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `ftrace` | String | Complex format: `type/event[+type/event2]`; validated by regex |
+
+ftrace format regex: `^(histogram|linegraph|label)/[a-zA-Z0-9_]+(\/[a-zA-Z0-9_]+)?(\+(histogram|linegraph|label)/[a-zA-Z0-9_]+(\/[a-zA-Z0-9_]+)?)*$`
+
+---
+
+## Validation Rules Summary
+
+### Cross-option dependencies (enabling B requires A to also be enabled):
+```
+gpu_mem_clock    → requires vram
+gpu_mem_temp     → requires vram
+hide_fsr_sharpness → requires fsr
+battery_icon     → requires battery
+battery_watt     → requires battery
+battery_time     → requires battery
+media_player_name → requires media_player
+media_player_format → requires media_player
+procmem_shared   → requires procmem
+procmem_virt     → requires procmem
+upload_logs      → requires permit_upload = 1
+horizontal_stretch → requires horizontal
+time_no_label    → requires time
+```
+
+### Mutual exclusions (A and B cannot both be active):
+```
+fps_only  ↔  (any other display param)
+histogram ↔  frame_timing
+```
+
+### Vendor restrictions:
+```
+gpu_voltage → AMD only (warn if non-AMD GPU detected)
+```
+
+### Gamescope-only (warn if not running gamescope):
+```
+fsr, hide_fsr_sharpness, hdr, refresh_rate, debug
+```
+
+### Value format validations:
+- All Color fields: must match `^[0-9A-Fa-f]{6}$`
+- All Path fields: if non-empty, path must exist (for input files) or parent dir must be writable (for output)
+- `fps_limit`: each comma-separated value must be non-negative integer
+- `font_glyph_ranges`: each value must be in the valid set
+- `graphs`: each value must be in the valid set
+- `device_battery`: each value must be in `[gamepad, mouse, controller, headset]`
+- `fps_metrics`: each value must be `AVG` or a valid decimal between 0.0 and 100.0
+- `benchmark_percentiles`: same as fps_metrics
+- `time_format`: must be a valid strftime format string
+- `pci_dev`: must match `^[0-9a-fA-F]{4}:[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-9a-fA-F]$`
+- `control`: must be `-1` or a valid socket name string
+- Keybind fields: must match `^(Shift_[LR]\+|Control_[LR]\+|Alt_[LR]\+|Super_[LR]\+)*(F[1-9]|F1[0-2]|[A-Z])$`