add hint for user-managed cursor redraw

include/SDL3/SDL_hints.h

@@ -2652,6 +2652,21 @@ extern "C" {
  */
 #define SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE "SDL_MOUSE_RELATIVE_CURSOR_VISIBLE"
 
+/**
+ * A variable controlling whether SDL should leave cursor redraws to be manually
+ * issued by usercode instead of automatically refreshing on state changes.
+ *
+ * This variable can be set to the following values:
+ *
+ * - "0": SDL will issue redraws automatically when focus changes (default)
+ * - "1": The usercode is responsible for updating the cursor on focus change.
+ *
+ * This hint can be set anytime.
+ *
+ * \since This hint is available since SDL 3.4.0.
+ */
+#define SDL_HINT_MOUSE_CURSOR_SUSPEND_REDRAW "SDL_MOUSE_CURSOR_SUSPEND_REDRAW"
+
 /**
  * A variable controlling whether mouse events should generate synthetic touch
  * events.

src/events/SDL_mouse.c

@@ -234,6 +234,13 @@ static void SDLCALL SDL_MouseRelativeCursorVisibleChanged(void *userdata, const
     SDL_RedrawCursor(); // Update cursor visibility
 }
 
+static void SDLCALL SDL_MouseCursorSuspendRedrawChanged(void *userdata, const char *name, const char *oldValue, const char *hint)
+{
+    SDL_Mouse *mouse = (SDL_Mouse *)userdata;
+
+    mouse->cursor_auto_redraw = !(SDL_GetStringBoolean(hint, false));
+}
+
 static void SDLCALL SDL_MouseIntegerModeChanged(void *userdata, const char *name, const char *oldValue, const char *hint)
 {
     SDL_Mouse *mouse = (SDL_Mouse *)userdata;
@@ -299,6 +306,9 @@ bool SDL_PreInitMouse(void)
     SDL_AddHintCallback(SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE,
                         SDL_MouseRelativeCursorVisibleChanged, mouse);
 
+    SDL_AddHintCallback(SDL_HINT_MOUSE_CURSOR_SUSPEND_REDRAW,
+                        SDL_MouseCursorSuspendRedrawChanged, mouse);
+
     SDL_AddHintCallback("SDL_MOUSE_INTEGER_MODE",
                         SDL_MouseIntegerModeChanged, mouse);
 
@@ -1158,6 +1168,9 @@ void SDL_QuitMouse(void)
     SDL_RemoveHintCallback(SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE,
                         SDL_MouseRelativeCursorVisibleChanged, mouse);
 
+    SDL_RemoveHintCallback(SDL_HINT_MOUSE_CURSOR_SUSPEND_REDRAW,
+                        SDL_MouseCursorSuspendRedrawChanged, mouse);
+
     SDL_RemoveHintCallback("SDL_MOUSE_INTEGER_MODE",
                         SDL_MouseIntegerModeChanged, mouse);
 
@@ -1599,11 +1612,17 @@ SDL_Cursor *SDL_CreateSystemCursor(SDL_SystemCursor id)
     return cursor;
 }
 
+// Cursor redraw command used by SDL internally
+// which checks whether or not to auto-redraw.
 void SDL_RedrawCursor(void)
 {
     SDL_Mouse *mouse = SDL_GetMouse();
     SDL_Cursor *cursor;
 
+    if (!mouse->cursor_auto_redraw) {
+        return;
+    }
+
     if (mouse->focus) {
         cursor = mouse->cur_cursor;
     } else {
@@ -1649,7 +1668,21 @@ bool SDL_SetCursor(SDL_Cursor *cursor)
         mouse->cur_cursor = cursor;
     }
 
-    SDL_RedrawCursor();
+    // user-called SDL_SetCursor(NULL) are manually issued redraws,
+    // so code for SDL_RedrawCursor should be mirrored here.
+    if (mouse->focus) {
+        cursor = mouse->cur_cursor;
+    } else {
+        cursor = mouse->def_cursor;
+    }
+
+    if (mouse->focus && (!mouse->cursor_visible || (mouse->relative_mode && mouse->relative_mode_hide_cursor))) {
+        cursor = NULL;
+    }
+
+    if (mouse->ShowCursor) {
+        mouse->ShowCursor(cursor);
+    }
 
     return true;
 }

src/events/SDL_mouse_c.h

@@ -149,6 +149,7 @@ typedef struct
     SDL_Cursor *def_cursor;
     SDL_Cursor *cur_cursor;
     bool cursor_visible;
+    bool cursor_auto_redraw;
 
     // Driver-dependent data.
     void *internal;