_{NATIVE · COMPOSITOR · VISUAL ERGONOMICS · GLSL · ICC}

🇬🇧 English (UK) · 🇧🇷 Português (BR) · 🇵🇹 Português (PT) · 🇪🇸 Español (ES) · 🇨🇳 简体中文 · CHANGELOG

Native visual-ergonomics manager for Hyprland — declarative colour profiles with GLSL shaders, gamma/temperature/brightness calibration, optional ICC profiles, and composable overlays behind an adaptive Rofi surface. Operates entirely inside the compositor's Lua runtime: no daemon, no Python.

---

01 / AT A GLANCE

HyprVision keeps the user surface clean and minimalist while executing colour management and shader pipeline composition directly within Hyprland's native Lua runtime.

---

02 / CAPABILITIES

What is actually happening?

• Visual profiles: defined in declarative Lua (profiles/*.lua) configuring shader pipeline, colour temperature, brightness, gamma, and optional ICC profiles.
• Composable overlays: applied modularly on top of any active profile:
  • Paper Texture (light / medium / heavy) — simulated paper substrate featuring two-octave grain, pulp mottling, anisotropic fibres, and warm shadow lifting.
  • Extra Dim (10–50%) — shader-based display attenuation extending well below monitor backlight minimums.
• Anti-banding for 8-bit panels: ~1 LSB dither always engaged in composed shaders alongside render:use_fp16 (internal FP16 curves) and render:icc_vcgt_enabled (hardware VCGT ramps via KMS).
• Adaptive scheduling (zero daemon): automatic profile transitions driven by time of day and battery states (with state restoration on battery recovery) via Hyprland's native hl.timer.
• True reload persistence: profiles survive hyprctl reload without flickering — when the Lua runtime is recreated, init.lua restores session state seamlessly.
• Community extra shaders: dynamic integration of the shaders/extras/ library directly into the menu surface.
• Tonal Rofi menu: follows system locale (English UK, PT-BR, PT-PT, ES-ES, ZH-CN) and inherits the dynamic palette of Noctalia or Caelestia across containers, elevation, and typography.
• Architectural glass surface: translucent backdrop leveraging compositor blur, sharing the 4px grid, concentric radii, verified OKLCH contrast (≥4.5:1), and top-edge glass highlight designed for Hypr.AI.
• Recoverable emergency reset (Super+Shift+H): instantaneously returns display output to neutral and archives previous configuration to state.bak, unlocking the "Recover last state" menu option.
• Smooth transitions: gradual ramping for temperature, brightness, and gamma via wl-gammarelay-rs (spawned on demand).

---

03 / PROFILE ATLAS

Full profile reference catalogue

Profile	Category	Purpose
✨ Cinema Desktop	correction	Subtle micro-contrast enhancement for daily desktop usage
🖥️ TN Recovery	correction	Gamut and contrast compensation for washed-out TN panels
🌌 Cinema OLED	experience	Crushed deep blacks with selective vibrance: OLED aesthetics on LCD panels
🧡 Cinema OLED Warm	experience	Cinema OLED balanced with warm colour temperature for evening viewing
🎬 Cinema Film	experience	Cinematic S-curve tonality, vignette, and film grain emulation
📖 E-Ink	experience	High-legibility monochrome desaturation (pairs with Paper Texture)
🕯️ E-Ink Warm Dark	experience	Candlelit warm E-Ink rendering with deeper black floor
🎯 Focus	experience	Distraction reduction through muted tonal contrast
🌙 Night	experience	Low eye-strain warm evening profile
📄 Paper	experience	Organic aged paper substrate for extended reading and writing
🌿 Paper Soft	experience	Warmer, softened paper tonality for long reading sessions
⚡ Reset	system	Strict neutral baseline with all shaders and calibration cleared

---

04 / INSTALL

Requirements

• Hyprland ≥ 0.55 with Lua config (~/.config/hypr/hyprland.lua). For legacy hyprland.conf setups, use v4 / tag v4.1.0.
• rofi
• Recommended: wl-gammarelay-rs (smooth transitions).
• Optional: libnotify (desktop notifications); lua5.4 and glslangValidator (required solely for the test suite).

Fast path

git clone https://github.com/mastermaiolo/hyprvision && cd hyprvision
./install.sh

The interactive installer handles:

• Verification of rofi, wl-gammarelay-rs, and libnotify, prompting package installation across pacman/apt/dnf/AUR (paru/yay).
• Conflict detection for Super+H and Super+Shift+H, permitting custom key rebinding.
• Schedule configuration (manual switching versus automated day/night cycles).
• Installation to ~/.config/hypr/hyprvision, appending require("init") to hyprland.lua (or ~/.config/hypr/user.lua in modular setups like Ryoku), and executing a compositor reload.

To uninstall and reset the display to neutral:

./uninstall.sh

To run the automated test suite (state, profiles, GLSL shaders, schedules, battery):

lua5.4 test_hyprvision.lua

---

05 / CONTROL SURFACE

The menu binds to Super+H by default; Super+Shift+H executes the safe emergency reset. The same operations can be invoked directly from scripts:

hyprctl eval "hv.apply('night')"             # Apply named profile
hyprctl eval "hv.overlay('paper','medium')"  # off | light | medium | heavy
hyprctl eval "hv.overlay('dim', 30)"         # 0 | 10 | 20 | 30 | 40 | 50
hyprctl eval "hv.apply_extra('x.glsl')"      # Load extra shader from shaders/extras/
hyprctl eval "hv.safe_reset()"               # Trigger emergency neutral reset
hyprctl eval "hv.restore_backup()"           # Recover archived state from backup

Active state remains readable as key=value pairs at ~/.config/hypr/hyprvision/state/state.

---

06 / CONFIGURATION

Configuration options reside in ~/.config/hypr/hyprvision/config.lua. Run hyprctl reload after editing:

-- ~/.config/hypr/hyprvision/config.lua
return {
    keybinds = {
        menu = "$mainMod, H",
        safe_reset = "$mainMod SHIFT, H",
    },
    battery = {
        enabled = true,
        threshold = 20,
        low_profile = "night",
        restore_after_low = true,
    },
    schedule = {
        enabled = false,
        apply_on_start = false,
        slots = {
            { hour = 7,  minute = 0, profile = "cinema_desktop" },
            { hour = 21, minute = 30, profile = "night" },
        },
    },
}

• profile = "none": Instructs the scheduler or battery monitor to perform no action.
• battery.restore_after_low: Automatically restores the profile active prior to low-battery state.
• schedule.apply_on_start: Defaults to false (startup honours the saved profile; schedules trigger upon crossing time thresholds).
• Empty key strings ("") disable specific keybindings.

Rofi layout customization

To adjust position, width, or fonts without installer overwrites, create ~/.config/hypr/hyprvision/rofi/user.rasi:

/* ~/.config/hypr/hyprvision/rofi/user.rasi */
window {
    location: north;
    y-offset: 120px;
}

---

07 / CREATING A PROFILE

Add customized profiles under profiles/<profile_name>.lua:

-- profiles/my_profile.lua
return {
    name = "My Profile",
    icon = "🔥",
    category = "experience",
    temperature = 5800,                        -- 2500–9000 K
    brightness  = 0.95,                        -- 0.05–1.5
    gamma       = 1.0,                         -- 0.5–2.0
    shader      = "experience/my_profile.glsl",-- in shaders/; nil = no shader
    -- icc      = "my_monitor.icc",            -- optional, in icc/
}

Warning

Shader authoring requirement: Always specify precision highp float;. Under mediump, noise patterns such as fract(sin(x) * 43758.5) exceed 16-bit float limits on AMD/Mesa drivers and evaluate to NaN, rendering the display completely black.

---

08 / ARCHITECTURE

init.lua        Compositor initialization: keybinds, timers, state restoration
core.lua        Engine: state management, GLSL composition, gamma application
config.lua      User preferences (keybinds, automated schedules, battery rules)
profiles/*.lua  Declarative profile configurations
ui/launcher.sh  Rofi launcher script (reads state/, issues hyprctl eval "hv.*")
rofi/*.rasi     Menu theme: 4px grid, concentric radii, architectural glass
theme/*.tmpl    Dynamic colour palette bridge evaluated on wallpaper change

Because hyprctl eval does not return command output, the Lua runtime persists state/state and state/profiles.menu as readable IPC interfaces for the launcher script. Composed shaders are generated on the fly under $XDG_RUNTIME_DIR/hyprvision/. All code executed inside the compositor is wrapped in pcall; faulty profiles report errors without disrupting Hyprland.

---

09 / FAILURE MODES

Detailed troubleshooting procedures

• Screen turned completely black or unreadable: Press Super+Shift+H for a safe reset to neutral. Once accessible, select "Recover last state" in the menu if desired.
• Profile disappeared following configuration or theme edits: State restores automatically upon reload; examine ~/.config/hypr/hyprvision/state/hyprvision.log.
• Compositor warning: uniform 'time': Animated shaders necessitate debug:damage_tracking 0 (increased GPU load); HyprVision coordinates this parameter automatically in the appropriate sequence.
• Log inspection: Review diagnostic runtime logs at ~/.config/hypr/hyprvision/state/hyprvision.log.

---

10 / PROVENANCE

Community shaders included in shaders/extras/ are preserved with minimal compatibility adjustments (highp):

Author	Project	Included Shaders
snes19xx	surface-dots	amano, art_canvas, cinema, clarity_inefficient, crt_mode, dither, focus, fuji_acros, gameboy, greens, IBM5151, main, matte, night, night_vision, outdoor, reading_mode, silent_hill, smart_invert, soft, vhs
0x15BA88FF	hyprshaders	chromatic_abberation, colors, contrast, crt, drugs, extradark, grain, invert, retro, solarized
Sijan-Bhusal	HyprShades	amoled, blue-light-filter, cyberpunk, matrix, retro
ManofJELLO	HyprWindowShade	chromaGlitch, pixelate, wireframe

Sources documented within shader headers:

• 0x15BA88FF_crt.frag — © 2023 Maxim Samoliuk, MIT licence.
• 0x15BA88FF_colors.glsl — adapted from Hyprland issue discussion and SweetFX Vibrance.fx.
• 0x15BA88FF_retro.glsl — adapted from wessles/GLSL-CRT.
• 0x15BA88FF_extradark.frag — parameters adapted from ReShade community discussions.
• ManofJELLO's HyprWindowShade is a per-window C++ compositor plugin providing context for the shader implementations credited to him.

If you authored any of these shaders and require attribution updates, licensing notes, or removal, please open an issue.

---

11 / LICENCE

MIT — see LICENSE. Third-party shaders in shaders/extras/ retain their individual licensing terms as detailed in Provenance.

Version history: CHANGELOG.md.

---

_{MAIOLO / SYSTEMS LAB · HYPRVISION · HV / 01 · 食}