From e2452ede6688f17251c1b3e418d3d57b15fab9d9 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sat, 6 Aug 2022 09:19:10 -0400
Subject: [PATCH] include: Added documentation to SDL_CaptureMouse about
auto-capture.
---
include/SDL_mouse.h | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h
index 1d4a2db0d23..c27ec332db9 100644
--- a/include/SDL_mouse.h
+++ b/include/SDL_mouse.h
@@ -245,6 +245,15 @@ extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
* While capturing is enabled, the current window will have the
* `SDL_WINDOW_MOUSE_CAPTURE` flag set.
*
+ * Please note that as of SDL 2.0.22, SDL will attempt to "auto capture"
+ * the mouse while the user is pressing a button; this is to try and make
+ * mouse behavior more consistent between platforms, and deal with the common
+ * case of a user dragging the mouse outside of the window. This means that
+ * if you are calling SDL_CaptureMouse() only to deal with this situation,
+ * you no longer have to (although it is safe to do so). If this causes
+ * problems for your app, you can disable auto capture by setting the
+ * `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.
+ *
* \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
* \returns 0 on success or -1 if not supported; call SDL_GetError() for more
* information.