From d66e2d0cbd4aa16c648d778dd16a586335633f41 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 9 Sep 2026 10:19:31 -0400
Subject: [PATCH] cocoa: Added SDL_HINT_MAC_USE_GCMOUSE.
Reference Issue #16241.
---
include/SDL3/SDL_hints.h | 20 ++++++++++++++++++++
src/video/cocoa/SDL_cocoamouse.m | 4 ++++
2 files changed, 24 insertions(+)
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 7e05a0b3f5d75..c371ef8ed92ed 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -2837,6 +2837,26 @@ extern "C" {
*/
#define SDL_HINT_MAC_SCROLL_MOMENTUM "SDL_MAC_SCROLL_MOMENTUM"
+/**
+ * A variable controlling whether the GCMouse API will be used on macOS.
+ *
+ * On supported versions of macOS, GCMouse is usually a better way to
+ * read mouse input, but may cause problems in some scenarios (remote control
+ * software that wants to send non-GCMouse input events, etc).
+ *
+ * When GCMouse is disabled, SDL will use standard Cocoa mouse events.
+ *
+ * The variable can be set to the following values:
+ *
+ * - "0": GCMouse won't be used.
+ * - "1": GCMouse will be used if available. (default)
+ *
+ * This hint needs to be set before SDL_Init().
+ *
+ * \since This hint is available since SDL 3.6.0.
+ */
+#define SDL_HINT_MAC_USE_GCMOUSE "SDL_MAC_USE_GCMOUSE"
+
/**
* A variable controlling whether holding down a key will repeat the pressed
* key or open the accents menu on macOS.
diff --git a/src/video/cocoa/SDL_cocoamouse.m b/src/video/cocoa/SDL_cocoamouse.m
index 2b476e5956b91..3e77fee049346 100644
--- a/src/video/cocoa/SDL_cocoamouse.m
+++ b/src/video/cocoa/SDL_cocoamouse.m
@@ -451,6 +451,10 @@ static void Cocoa_OnGCMouseDisconnected(GCMouse *mouse)
void Cocoa_InitGCMouse(void)
{
+ if (!SDL_GetHintBoolean(SDL_HINT_MAC_USE_GCMOUSE, true)) {
+ return;
+ }
+
@autoreleasepool {
// These APIs are available starting in macOS Big Sur, but we don't enable
// GCMouse until Sonoma due to broken motion and button events on MacBooks