Add animated cursor support

Adds support for animated cursors on Cocoa, Wayland, Win32, and X11.

testcursor can take a semicolon separated list of filenames and load an animated cursor from them.

include/SDL3/SDL_mouse.h

@@ -130,6 +130,17 @@ typedef enum SDL_MouseWheelDirection
     SDL_MOUSEWHEEL_FLIPPED    /**< The scroll direction is flipped / natural */
 } SDL_MouseWheelDirection;
 
+/**
+ * Animated cursor frame info.
+ *
+ * \since This struct is available since SDL 3.4.0.
+ */
+typedef struct SDL_CursorFrameInfo
+{
+    SDL_Surface *surface; /**< The surface data for this frame */
+    Uint32 duration;      /**< The frame duration in milliseconds (a duration of 0 is infinite) */
+} SDL_CursorFrameInfo;
+
 /**
  * A bitmask of pressed mouse buttons, as reported by SDL_GetMouseState, etc.
  *
@@ -565,6 +576,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_CaptureMouse(bool enabled);
  *
  * \since This function is available since SDL 3.2.0.
  *
+ * \sa SDL_CreateAnimatedCursor
  * \sa SDL_CreateColorCursor
  * \sa SDL_CreateSystemCursor
  * \sa SDL_DestroyCursor
@@ -600,6 +612,7 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateCursor(const Uint8 *data,
  * \since This function is available since SDL 3.2.0.
  *
  * \sa SDL_AddSurfaceAlternateImage
+ * \sa SDL_CreateAnimatedCursor
  * \sa SDL_CreateCursor
  * \sa SDL_CreateSystemCursor
  * \sa SDL_DestroyCursor
@@ -609,6 +622,57 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_CreateColorCursor(SDL_Surface *surf
                                                           int hot_x,
                                                           int hot_y);
 
+/**
+ * Create an animated color cursor.
+ *
+ * Animated cursors are composed of a sequential array of frames, specified
+ * as surfaces and durations in an array of SDL_CursorFrameInfo structs.
+ * The hot spot coordinates are universal to all frames, and all frames must
+ * have the same dimensions.
+ *
+ * Frame durations are specified in milliseconds. A duration of 0 implies an
+ * infinite frame time, and the animation will stop on that frame. To create
+ * a one-shot animation, set the duration of the last frame in the sequence
+ * to 0.
+ *
+ * If this function is passed surfaces with alternate representations added
+ * with SDL_AddSurfaceAlternateImage(), the surfaces will be interpreted as the
+ * content to be used for 100% display scale, and the alternate
+ * representations will be used for high DPI situations. For example, if the
+ * original surfaces are 32x32, then on a 2x macOS display or 200% display scale
+ * on Windows, a 64x64 version of the image will be used, if available. If a
+ * matching version of the image isn't available, the closest larger size
+ * image will be downscaled to the appropriate size and be used instead, if
+ * available. Otherwise, the closest smaller image will be upscaled and be
+ * used instead.
+ *
+ * If the underlying platform does not support animated cursors, this function
+ * will fall back to creating a static color cursor using the first frame in
+ * the sequence.
+ *
+ * \param frames an array of cursor images composing the animation.
+ * \param frame_count the number of frames in the sequence.
+ * \param hot_x the x position of the cursor hot spot.
+ * \param hot_y the y position of the cursor hot spot.
+ * \returns the new cursor on success or NULL on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \threadsafety This function should only be called on the main thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ *
+ * \sa SDL_AddSurfaceAlternateImage
+ * \sa SDL_CreateCursor
+ * \sa SDL_CreateColorCursor
+ * \sa SDL_CreateSystemCursor
+ * \sa SDL_DestroyCursor
+ * \sa SDL_SetCursor
+ */
+extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_CreateAnimatedCursor(SDL_CursorFrameInfo *frames,
+                                                                 int frame_count,
+                                                                 int hot_x,
+                                                                 int hot_y);
+
 /**
  * Create a system cursor.
  *
@@ -687,6 +751,7 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetDefaultCursor(void);
  *
  * \since This function is available since SDL 3.2.0.
  *
+ * \sa SDL_CreateAnimatedCursor
  * \sa SDL_CreateColorCursor
  * \sa SDL_CreateCursor
  * \sa SDL_CreateSystemCursor