Feature Discussion: iMouse Uniforms for Custom Shaders

[brad-alexander]

Feature Discussion: iMouse Uniforms for Custom Shaders

Summary

I've implemented support for passing mouse position to custom shaders via the iMouse uniform (currently documented as "NOT CURRENTLY SUPPORTED" in the config).

Implementation Details

The implementation adds real-time mouse cursor tracking that passes surface pixel coordinates to custom shaders through the existing uniform system:

• Renderer State: Extended renderer.State.Mouse to track raw surface coordinates
• Surface Events: Updated Surface.cursorPosCallback and mouseRefreshLinks to populate surface coordinates
• Uniform Updates: Modified Renderer.updateCustomShaderUniforms to convert surface coords to framebuffer pixels with proper Y-axis flipping for Metal/OpenGL

The mouse data flows from surface events → render state → framebuffer conversion → uniform buffer, providing vec4 iMouse as (x, y, 0, 0) in surface pixels.

Implementation Concerns

Though I'm an experienced software dev, as a Zig novice I have some concerns about this implementation:

1. Logic Placement: The coordinate conversion and caching happens in mouseRefreshLinks near other mouse handling related to rendering - this may not be the ideal location
2. Render Frequency: The implementation may trigger render requeues more frequently than optimal, but only if custom shaders are enabled. Without the requeues, mouse position was only updated roughly around once per second.
3. Code Quality: Changes were made with assistance of Codex/Amp.

Files Modified

• src/renderer/generic.zig
• src/renderer/State.zig
• src/Surface.zig
• src/config/Config.zig -- comments only

Testing

• Full build completes successfully (zig build)
• Manual validation with diagnostic ShaderToy-style custom shader on OpenGL (Win11/WSL/NixOS backend using WSLg):
  • demo: [uses a combination of cursor position and mouse position]

20251027-0517-53.8232374-2.mp4

Questions for Maintainers

1. Is the coordinate conversion logic appropriately (or just acceptably) placed in mouseRefreshLinks?
2. Are there performance concerns with the current render requeue frequency or is there a better way to go about that?
3. Is this implementation appropriate to consider at this stage? or what could be done to get it to that point?

Branch: main...brad-alexander:ghostty:ba/iMouse

---

AI Assistance Disclosure: This implementation was created with assistance of Codex/Amp with heavy supervision by a Zig novice 😄

[pluiedev]

One thing to note is that iMouse in Shadertoy is only updated after a left click and not on every frame. I think that would alleviate the performance concerns here.