manual_slop/docs/guide_shaders_and_window.md

Custom Shaders and Window Frame Architecture

1. Shader Injection Strategy

Evaluation

• Dear PyGui (Legacy): Does not natively support raw GLSL/HLSL shader injection into the UI layer. It relies heavily on fixed-function vertex/fragment shaders compiled into the C++ core. Faux-shaders via DrawList are the only viable path without modifying the DPG source.
• imgui-bundle (Current): imgui-bundle utilizes hello_imgui as its application runner, which provides robust lifecycle callbacks (e.g., callbacks.custom_background, callbacks.post_init). Because hello_imgui exposes the underlying OpenGL context, we can use PyOpenGL alongside it to execute raw GLSL shaders.

Chosen Approach: Hybrid Faux-Shader & PyOpenGL FBO

Given the Python environment, we will adopt a hybrid approach:

1. Faux-Shaders (ImDrawList Batching): Continue using imgui.ImDrawList primitives for simple effects like soft shadows, glows, and basic gradients (as seen in src/shaders.py). This is highly performant for UI elements and requires no external dependencies.
2. True GPU Shaders (PyOpenGL + FBO): For complex post-processing (CRT curvature, bloom, dynamic noise backgrounds), we will integrate PyOpenGL.
   • We will compile GLSL shaders during post_init.
   • We will render the effect into a Framebuffer Object (FBO).
   • We will display the resulting texture ID using imgui.image() or inject it into the custom_background callback.

Note: This approach introduces PyOpenGL as a dependency, which is standard for advanced Python graphics.

2. Custom Window Frame Strategy

Evaluation

• Native DWM Overloading (PyWin32): It is possible to use pywin32 to subclass the application window, intercept WM_NCHITTEST, and return HTCAPTION for a custom ImGui-drawn title bar region. This preserves Windows snap layouts and native drop shadows. However, it is strictly Windows-only and can conflict with GLFW/SDL2 event loops used by hello_imgui.
• Borderless Window Mode (ImGui/GLFW): hello_imgui allows configuring the main window as borderless/undecorated (runner_params.app_window_params.borderless = True). We must then manually draw the title bar, minimize/maximize/close buttons, and handle window dragging by updating the OS window position based on ImGui mouse drag deltas.

Chosen Approach: Pure ImGui Borderless Implementation

To ensure cross-platform compatibility and avoid brittle Win32 hook collisions with hello_imgui, we will use the Borderless Window Mode approach.

1. Initialization: Configure hello_imgui.RunnerParams to disable OS window decorations.
2. Title Bar Rendering: Dedicate the top ~30 pixels of the ImGui workspace to a custom title bar that matches the current theme (e.g., NERV or standard).
3. Window Controls: Implement custom ImGui buttons for _, [], and X, which will call native window management functions exposed by hello_imgui or glfw.
4. Drag Handling: Detect imgui.is_mouse_dragging() on the title bar region and dynamically adjust the application window position.

3. Integration with Event Metrics

Both the shader uniforms (time, resolution) and window control events will be hooked into the existing dag_engine and events systems to ensure minimal performance overhead and centralized configuration via config.toml.

---

4. NERV Theme Effects

The NERV Technical Console theme (src/theme_nerv.py, src/theme_nerv_fx.py) is a selectable high-density visual variant that uses the shader and window-frame infrastructure above to produce a CRT-style "Tactical Console" aesthetic.

Visual Characteristics

• Black Void Palette: Near-black backgrounds with sharp, high-contrast accents.
• Zero-Rounding Geometry: No rounded corners on panels, buttons, or frames. Sharp rectangles.
• CRT Scanlines: A repeating horizontal line overlay applied via the custom_background callback. The scanline intensity is configurable via config.toml → [nerv].scanline_alpha.
• Status Flickering: The active tier indicator and other "operational status" elements flicker at a low frequency (configurable rate) to simulate a tactical display.
• Alert Animations: When MMA state transitions to "blocked" or "error", a red border pulse animation runs for ~1.5 seconds.

Implementation Files

• src/theme_nerv.py — Color palette, geometry overrides, font selection.
• src/theme_nerv_fx.py — Scanline overlay, status flickering, alert animations.
• src/bg_shader.py — Custom background shader (uses the FBO pipeline described in Section 1).

Activation

The NERV theme is selected via the GUI's theme picker (User Menu → Theme → NERV). When activated, theme_nerv.py swaps the active color set, geometry style, and font. The FX layer is enabled/disabled via the [nerv].fx_enabled config flag.

Performance Considerations

CRT scanlines use the FBO pipeline and run at full window resolution. On a 1920×1080 display, the scanline pass adds ~1-2ms per frame. For lower-end GPUs, reduce [nerv].scanline_alpha (cheaper blending) or disable FX entirely ([nerv].fx_enabled = false).

See guide_nerv_theme.md (placeholder; written in Task 10) for the full theme API, configuration keys, and customization options.