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.