In our earlier lessons on mouse events and tracking, we focused on what the mouse does while hovering over our windows-that is, when one of our windows has mouse focus.

However, in certain scenarios, we may need to know what's happening with the mouse even when it's outside our application's windows. This lesson covers the techniques for accomplishing this and explores scenarios where these capabilities are useful.

Global Mouse State

Previously, we introduced the SDL_GetMouseState() function, which allows us to determine the mouse's position within our window.

The similar SDL_GetGlobalMouseState() function lets us find the cursor's position anywhere on the user's desktop. It has a familiar API: it accepts two pointers to float variables and updates them with the horizontal and vertical positions of the cursor.

1float x, y;
2SDL_GetGlobalMouseState(&x, &y);

While SDL_GetMouseState() reports the position relative to the top-left of our window, SDL_GetGlobalMouseState() reports it relative to the top-left corner of the primary display.

Note that this means either coordinate can be negative. This can happen in multi-monitor setups where the user has a display positioned above or to the left of their primary display.

Similar to SDL_GetMouseState(), SDL_GetGlobalMouseState() allows us to pass a nullptr for either argument if we're only interested in one of the coordinates:

1// We only care about the horizontal position
2float x;
3SDL_GetGlobalMouseState(&x, nullptr);

1// We only care about the vertical position
2float y;
3SDL_GetGlobalMouseState(nullptr, &y);

Button State

In addition to reporting the mouse's position, the SDL_GetGlobalMouseState() function lets us determine which buttons are currently pressed. It does this by returning a SDL_MouseButtonFlags (an alias for Uint32), which acts as a bitmask. We can use the & operator to examine individual bits and determine if specific buttons are pressed.

SDL provides the SDL_BUTTON_MASK() macro to help us isolate the bits associated with each mouse button. For example, SDL_BUTTON_MASK(SDL_BUTTON_LEFT) checks if the left button is pressed.

The following program logs out some information about the mouse state on every tick:

Files

src

Select a file to view its content

Mouse Capture

Previously, we covered how SDL reports mouse events like movement and button presses only if the event happens while one of our windows has mouse focus - that is, when the user's cursor is hovering over one of our windows:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleWindowEvent(const SDL_WindowEvent& E) {
7  if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
8    std::cout << "Mouse Entered Window - "
9      "Tracking Resumed\n";
10  } else if (E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE) {
11    std::cout << "Mouse Left Window - "
12      "Tracking Stopped\n";
13  }
14}
15
16void HandleMouseMotion(const SDL_MouseMotionEvent& E) {
17  std::cout << "Mouse moved to "
18    << E.x << ", " << E.y << '\n';
19}
20
21int main(int, char**) {
22  SDL_Init(SDL_INIT_VIDEO);
23  Window GameWindow;
24  SDL_Event E;
25
26  bool IsRunning = true;
27  while (IsRunning) {
28    while (SDL_PollEvent(&E)) {
29      if (E.type == SDL_EVENT_QUIT) {
30        IsRunning = false;
31      } else if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER ||
32                 E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE
33      ) {
34        HandleWindowEvent(E.window);
35      } else if (E.type == SDL_EVENT_MOUSE_MOTION) {
36        HandleMouseMotion(E.motion);
37      }
38    }
39    
40    GameWindow.Render();
41    GameWindow.Update();
42  }
43  SDL_Quit();
44  return 0;
45}

1Mouse moved to 2, 120
2Mouse moved to 0, 120
3Mouse Left Window - Tracking Stopped
4Mouse Entered Window - Tracking Resumed
5Mouse moved to 1, 108
6Mouse moved to 2, 107

In some situations, we prefer that mouse events are reported even when none of our windows have mouse focus. SDL refers to this as mouse capture, which we can enable using the SDL_CaptureMouse() function.

We pass true to enable capturing or false to disable it:

1// Enable mouse capture
2SDL_CaptureMouse(true);
3
4// Disable mouse capture
5SDL_CaptureMouse(false);

Enabling mouse capture for prolonged periods is not recommended, as it can interfere with other applications the user might be interacting with. Instead, we typically enable mouse capture briefly for certain actions and then disable it when those actions are complete.

The most common use case for mouse capture is to support drag-and-drop interactions. For example, if we want to allow the user to drag something from one of our windows to another, there will be a point where neither of our windows has mouse focus.

Even if the user is dragging and dropping within the same window, their mouse may temporarily move outside the window.

Without mouse capture, we would not be able to track the cursor when our windows lack mouse focus. So, we typically enable mouse capture throughout such actions to remove that restriction.

Getting Capture State

Enabling mouse capture requires one of our windows to have input focus (i.e., keyboard focus). Additionally, if we lose input focus, mouse capture is automatically disabled.

The SDL_WindowFlags bit set includes an SDL_WINDOW_MOUSE_CAPTURE flag. While it's unusual to enable this when creating a window, this flag is still helpful, as we can retrieve the flags at any time and examine the SDL_WINDOW_MOUSE_CAPTURE bit to see if we're currently capturing the mouse.

The following program begins mouse capture when the user presses space, and stops when they press escape. It also logs the capture state on every tick:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  SDL_Event E;
11  bool IsRunning = true;
12  while (IsRunning) {
13    while (SDL_PollEvent(&E)) {
14      if (E.type == SDL_EVENT_QUIT) {
15        IsRunning = false;
16      } else if (E.type == SDL_EVENT_KEY_DOWN) {
17        if (E.key.key == SDLK_SPACE) {
18          SDL_CaptureMouse(true);
19        }
20      } else if (E.type == SDL_EVENT_KEY_UP) {
21        if (E.key.key == SDLK_ESCAPE) {
22          SDL_CaptureMouse(false);
23        }
24      }
25    }
26
27    bool HasCaptureFlag =
28      SDL_GetWindowFlags(GameWindow.GetRaw()) & 
29      SDL_WINDOW_MOUSE_CAPTURE;
30
31    std::cout << "Window has capture flag: "
32      << (HasCaptureFlag ? "YES" : "NO") << "\n";
33
34    GameWindow.Render();
35    GameWindow.Update();
36  }
37
38  SDL_Quit();
39  return 0;
40}

1Window has capture flag: NO
2Window has capture flag: NO
3Window has capture flag: YES
4...

Error Handling

SDL_CaptureMouse() now returns a bool in SDL3. It returns true if it was successful, or false otherwise. We can use this to react to errors and call SDL_GetError() for a description of what went wrong.

The most common reasons for SDL_CaptureMouse() to fail are that no window has input focus when we try to enable it, or the platform does not support it at all.

1if (!SDL_CaptureMouse(true)) {
2  std::cout << "Error: " << SDL_GetError();
3}

1Error: No window has focus

Mouse Auto Capture

The drag-and-drop use case for enabling mouse capture is so common that SDL automatically enables mouse capture when the user holds down one of their mouse buttons.

The following program demonstrates this in action:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  SDL_Event E;
11  bool IsRunning = true;
12  while (IsRunning) {
13    while (SDL_PollEvent(&E)) {
14      if (E.type == SDL_EVENT_QUIT) {
15        IsRunning = false;
16      } else if (E.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
17        std::cout << "Mouse button down\n";
18      } else if (E.type == SDL_EVENT_MOUSE_BUTTON_UP) {
19        std::cout << "Mouse button up\n";
20      }
21    }
22
23    std::cout << "Capturing Mouse: ";
24    if (SDL_GetWindowFlags(GameWindow.GetRaw()) &
25      SDL_WINDOW_MOUSE_CAPTURE
26    ) {
27      std::cout << "true\n";
28    } else {
29      std::cout << "false\n";
30    }
31    
32    GameWindow.Render();
33    GameWindow.Update();
34  }
35
36  SDL_Quit();
37  return 0;
38}

1Capturing Mouse: false
2Capturing Mouse: false
3Mouse button down
4Capturing Mouse: true
5Capturing Mouse: true
6Mouse button up
7Capturing Mouse: false

This behavior is controlled by the SDL_HINT_MOUSE_AUTO_CAPTURE hint. By default, it is set to "1", meaning auto-capture is enabled.

We can disable auto-capture by setting it to "0" using SDL_SetHint():

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_SetHint(SDL_HINT_MOUSE_AUTO_CAPTURE, "0");
8  SDL_Init(SDL_INIT_VIDEO);
9  Window GameWindow;
10
11  SDL_Event E;
12  bool IsRunning = true;
13  while (IsRunning) {
14    while (SDL_PollEvent(&E)) {
15      if (E.type == SDL_EVENT_QUIT) {
16        IsRunning = false;
17      } else if (E.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
18        std::cout << "Mouse button down\n";
19      } else if (E.type == SDL_EVENT_MOUSE_BUTTON_UP) {
20        std::cout << "Mouse button up\n";
21      }
22    }
23
24    std::cout << "Capturing Mouse: ";
25    if (SDL_GetWindowFlags(GameWindow.GetRaw()) &
26      SDL_WINDOW_MOUSE_CAPTURE
27    ) {
28      std::cout << "true\n";
29    } else {
30      std::cout << "false\n";
31    }
32    
33    GameWindow.Render();
34    GameWindow.Update();
35  }
36  SDL_Quit();
37  return 0;
38}

1Capturing Mouse: false
2Capturing Mouse: false
3Mouse button down
4Capturing Mouse: false
5Capturing Mouse: false
6Mouse button up
7Capturing Mouse: false

Summary

SDL's mouse capture and global mouse state features allow us to track mouse movement and button states beyond our window boundaries. This lets us implement advanced mouse interactions like drag-and-drop. Key topics covered:

Using SDL_GetGlobalMouseState() to track mouse position and button states across the entire desktop.
Understanding the difference between window-relative and global mouse coordinates.
Implementing mouse capture to maintain mouse event tracking outside window boundaries.
Managing automatic mouse capture during drag operations using SDL hints.
Handling common error cases and platform-specific considerations.
Distinguishing between mouse capture and mouse grab functionality.

Mouse Capture and Global Mouse State

Global Mouse State

Button State

Files

Mouse Capture

src/main.cpp

Getting Capture State

Error Handling

Mouse Auto Capture

src/main.cpp

src/main.cpp

Summary

Relative Mouse Mode

Game Development with SDL3