SDL_CaptureMouse(3)

💖 SDL_CaptureMouse(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where today's main character is SDL_CaptureMouse(3) — she's a lil function with big opinions about where your mouse events are allowed to go. 🐭✨

---

✨ NAME ✨

SDL_CaptureMouse — capture the mouse and to track input outside an SDL window. 🎀

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_mouse.h>

bool SDL_CaptureMouse(bool enabled);

---

🦋 DESCRIPTION 🦋

so like, capturing is the vibe where your app gets mouse events globally, instead of just the ones that happen inside your window. not every video target supports this function tho — so don't come for her if it's a no. 😭 when capturing is enabled, the current window gets all the mouse events, but — and this is the important part — unlike relative mode, no change is made to the cursor and it is not restrained to your window. cursor is free, she's just being watched. 👀

⚠️ also this function may straight up deny mouse input to other windows — both the ones in your own application and other windows on the system — so please use it sparingly, and in small bursts. like, blink-and-you-miss-it bursts. 🙈

for example, you might want to track the mouse while the user is dragging something, until the user releases a mouse button. that's the ideal little window of use. 🫶 it is not recommended that you capture the mouse for long periods of time, such as the entire time your app is running. for that, you should probably use SDL_SetWindowRelativeMouseMode() or SDL_SetWindowMouseGrab(), depending on your goals. pick your fighter. 💅

while captured, mouse events still report coordinates relative to the current (foreground) window, but those coordinates may be outside the bounds of the window (including negative values, yes, negative, she goes there). capturing is only allowed for the foreground window. and if the window loses focus while capturing, the capture will be disabled automatically. no cap, it just lets go. 💀

while capturing is enabled, the current window will have the SDL_WINDOW_MOUSE_CAPTURE flag set. slay, a flag. 🚩✨

okay now the plot twist: please note that SDL will attempt to "auto capture" the mouse while the user is pressing a button. why? to try and make mouse behavior more consistent between platforms, and to deal with the common case of a user dragging the mouse outside of the window. which means — if you're calling SDL_CaptureMouse() only to deal with this situation, you do not have to (although it is safe to do so 🫶). and if this causes problems for your app, you can disable auto capture by setting the SDL_HINT_MOUSE_AUTO_CAPTURE hint to zero. boom, problem solved, icon behavior. 👑

---

🎀 FUNCTION PARAMETERS 🎀

• enabled — true to enable capturing, false to disable. it's giving on/off switch, and honestly? we love a simple binary. ✨

---

💜 RETURN VALUE 💜

returns true on success or false on failure — and if it fails, call SDL_GetError() for more information, because she will tell you what went wrong if you just ask nicely. 😭

---

🧚 THREAD SAFETY 🧚

this function should only be called on the main thread. do not pass go, do not collect $200, do not try it from a worker thread. main thread only, periodt. 💅

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. she's new-ish and she knows it. 💖

---

⭐ SEE ALSO ⭐

• SDL_GetGlobalMouseState(3) — go read her next, iykyk. 👑

---

and that's the whole page, bestie!! this little masterpiece came to you courtesy of the Simple Directmedia Layer girlies, running SDL 3.4.18. go capture something (briefly!!) and stay iconic. 💅💖✨🦋🌸🎀