Add animated cursors

[Kontrabant]

Add animated cursors to Cocoa, Wayland, Win32, and X11.

Animated cursors are composed of a series of images, with a duration specified for each.

Cursors are handled as close to the system level as possible:

• On X11, XcursorImagesLoadCursor() is used.
• On Wayland, custom cursors use the same code path as animated system cursors.
• On Windows, there is no API to create an animated cursor, so a resource file is built in memory to create a cursor with the animation sequence.
• On Mac, an NSTimer is used to fire when frame updates are required.

Currently, SDL_CreateAnimatedCursor() falls back to creating a static cursor from the first frame if the platform doesn't support animated cursors. Should it just fail instead?

TODO:

• This can probably be implemented in KMSDRM.
• There is probably a way to handle animated cursors on Emscripten, but someone more familiar with the platform could figure it out more easily.
• Niche platforms and consoles?

Closes #14198
Closes #14248

[slouken]

In general this looks good. Two questions:

1. Do we need the flexibility of each frame having a different duration?
2. Does it make sense to have a fallback (or even primary?) implementation that updates the cursor at the correct time in SDL_PumpEvents()?

[slouken]

Can you update testcustomcursor to also test animated cursors?

[Kontrabant]

In general this looks good. Two questions:

1. Do we need the flexibility of each frame having a different duration?

It's standard among the system level implementations, and adds flexibility without a lot of complexity. The old Windows hourglass wait cursor, for example, uses different durations to make the vertical frame hold longer than the turning frames. It also allows for easily creating one-shot animations by setting the last frame duration to 0 (infinite).

2. Does it make sense to have a fallback (or even primary?) implementation that updates the cursor at the correct time in SDL_PumpEvents()?

The current implementations don't need this, and wouldn't benefit from it, as the cursors are handled as close to the system-level as possible. X and Windows pass the frames to the desktop and get a single Cursor/HCURSOR object that the system animates itself. Wayland does a single buffer pool allocation and commits suballocated wl_buffer objects in the cursor surface frame callback, just as it has to do with animated system cursors on compositors without the cursor shape protocol. Mac needs some manual handling, but that is still a simple matter of using an NSTimer and invalidating the cursor rect when it fires.

Unless some platform eventually needs this functionality generalized, it's not yet worth the time or effort imo.

[slouken]

In general this looks good. Two questions:

1. Do we need the flexibility of each frame having a different duration?

It's standard among the system level implementations, and adds flexibility without a lot of complexity. The old Windows hourglass wait cursor, for example, uses different durations to make the vertical frame hold longer than the turning frames. It also allows for easily creating one-shot animations by setting the last frame duration to 0 (infinite).

Okay, that makes sense, especially if it's supported in all the backends.

2. Does it make sense to have a fallback (or even primary?) implementation that updates the cursor at the correct time in SDL_PumpEvents()?

Unless some platform eventually needs this functionality generalized, it's not yet worth the time or effort imo.

I agree that having the system do the animation is ideal. It might be worth implementing the fallback for the case that is currently a static one frame cursor, and then we can say it's supported everywhere?

[slouken]

It might be worth implementing the fallback for the case that is currently a static one frame cursor, and then we can say it's supported everywhere?

This would be pretty trivial to do, and I'm happy to add that after this PR lands, if you want.

[Kontrabant]

Can you update testcustomcursor to also test animated cursors?

There are two added cases that make the custom arrow cursor flash: a looping animated sample, and a one-shot that slows down and stops.

I'll add loading an image sequence from files a bit later.

[maia-s]

Suggestion: For one shot animations, maybe it could get the fallback static cursor from the last frame instead of the first? Other animations can always be rearranged so they start on a suitable frame, but that's not possible for one shots.

[Kontrabant]

Suggestion: For one shot animations, maybe it could get the fallback static cursor from the last frame instead of the first? Other animations can always be rearranged so they start on a suitable frame, but that's not possible for one shots.

The long term plan is to have a generic fallback that animated cursors at a higher level for backends without animation support, but for now, this is a good idea. Done.

[Kontrabant]

I think this is ready to go. The only additional things to do are add support for more platforms.

Thanks @madebr and @sezero for the build fix.

[slouken]

I added a couple of comments, but this generally looks good to me. Feel free to merge when ready!

[Kontrabant]

Merged!