HiDPI custom cursor support for Windows, MacOS and Linux

[badgyro]

• Tested on all platforms changed
• Added an entry to the changelog module if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality

Adds HiDPI support for image-based custom cursors on Windows, MacOS, X11, and Wayland.

This introduces a new public API for creating custom cursors from multiple image representations, allowing applications to provide cursor bitmaps for different scale factors. The platform backends now select or pass through the best representation for the current display/window scale.

The application example has also been updated with a custom cursor that includes multiple representations.

I tested the updated example on real hardware on Windows 11, MacOS 26, Debian GNOME, and Debian KDE Plasma on X11.

Closes #4094

[kchibisov]

I feel like the original idea was that user reloads the cursor once the DPI changes and internals should respect current scale factor.

Adding custom cursor management would over-complicate things in my opinion.

[badgyro]

Thanks, I understand the concern about keeping the scope small.

My concern with requiring applications to reload cursors after DPI changes is that every Winit user would need to reimplement the same cursor-management logic. Using custom cursors can be a bit trickier, and it might need some digging to get right. Plus, it could make developers want to save this task for later instead of tackling it right away.

If you want precise, pixel perfect cursors then there is effectively one correct flow: provide bitmaps for every size that will be used. Handling this in Winit would let us provide consistent behavior on every supported platform, along with an example showing which assets to prepare and how to use them.

With 4K, 5K, and 6K displays becoming increasingly common, proper cursor scaling is often necessary for a usable result. I think providing this internally would be a meaningful advantage for Winit, while removing a fairly basic burden from applications.

My modifications don’t alter the current API, and you can also provide only one representation using the new from_rgba_representations function. Therefore, anyone interested in developing their own cursor DPI management system can do so.

[kchibisov]

The thing is that winit handling is only really needed on the mixed DPI systems when you constantly move things around, if you only have HiDPI setup, you just load the right asset and it stays the same.

The thing is that while I agree that automatic systems like that are welcome, I'm not quite sure how used it would be outside simple applications. GUI toolkits will likely have their own asset management, so having winit API on top will increase complexity.

That being said, if the current API doesn't really work with if you want to use platform cursor API with non 100% scaling, then it should be changed to allow building such management systems on a user side.

At least Wayland one is rather seam-less here, and the current API works fine with any scaling. The client will reload its assets anyway on DPI change, so reloading cursor doesn't sound like a big deal, given that preloading of it consumes memory which may never be required.

But I don't have that strong opinion if some big toolkits will suggest that this feature in winit is really needed.