Previously, we introduced how SDL dispatches events when the player moves their mouse within our window, or when they click their mouse buttons when our window has input focus:

Files

src

Select a file to view its content

1Mouse moved to (226, 4)
2Left button pressed at (226, 4)
3Mouse moved to (227, 4)
4Mouse moved to (228, 5)
5Left button released at (228, 5)

This allows us to react to our user's mouse input, but it is not the only approach that we can use. Instead of reacting to events, we are free to query the mouse's current position and which buttons are pressed at any time.

We covered how to track mouse motion and clicking through the event loop in our introductory lesson on .

This lesson covers techniques for tracking the mouse independently of the event loop, and practical examples of why we'd want to.

Using `SDL_GetMouseState()`

SDL_GetMouseState accepts two float pointers, which it will update with the mouse's current x and y coordinates.

1float x, y;
2SDL_GetMouseState(&x, &y);
3std::cout << "Mouse is at " << x << ", " << y;

Just like with mouse events, these values are relative to the top left of the window. If the player's cursor is at the extreme top left corner, then x and y will be updated to have values 0.0f and 0.0f.

To get the state of the buttons, we use the return value of SDL_GetMouseState(). The function returns a 32-bit unsigned integer representing a bit mask:

1float x, y;
2Uint32 Buttons{SDL_GetMouseState(&x, &y)};

SDL3 provides the SDL_MouseButtonFlags alias for Uint32, allowing us to be more descriptive about what this variable represents:

1float x, y;
2SDL_MouseButtonFlags Buttons{SDL_GetMouseState(&x, &y)};

A bit mask uses individual bits within a number to store multiple yes/no (boolean) values efficiently. Think of it like a row of switches - each bit represents one switch that can be either on (1) or off (0).

In our case, each bit represents whether a specific mouse button is pressed (1) or not pressed (0). This lets us track multiple button states using a single number. SDL provides helper macros to use with these bit masks, allowing us to isolate the bit representing the button we're interested in:

SDL_BUTTON_MASK(SDL_BUTTON_LEFT) checks if the left button is pressed
SDL_BUTTON_MASK(SDL_BUTTON_RIGHT) checks if the right button is pressed

We use the & (bitwise AND) operator to test if a specific button is pressed:

1float x, y;
2SDL_MouseButtonFlags Buttons{SDL_GetMouseState(&x, &y)};
3
4bool LeftPressed{
5  Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT)};
6bool RightPressed{
7  Buttons & SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)};

We cover bit masks and the & operator in more detail in our .

Passing `nullptr` to `SDL_GetMouseState()`

If we don't care about the mouse's x or y position, we can pass nullptr to either (or both) of those parameters:

1float x, y;
2
3// We only care about the x (horizontal) position
4SDL_GetMouseState(&x, nullptr);
5
6// We only care about the y (vertical) position
7SDL_GetMouseState(nullptr, &y);
8
9SDL_MouseButtonFlags Buttons{
10  // We only care about the buttons
11  SDL_GetMouseState(nullptr, nullptr)
12};

Example: Retrieving Mouse State on Keyboard Event

Naturally, if we wanted to be notified when the player moves their mouse or clicks a mouse button, we'd monitor the event loop for those specific events.

Querying the state of the mouse directly using SDL_GetMouseState() is for scenarios when we need to understand what's going on with the mouse when some other event happens.

For example, we might have a gameplay behavior where the player shoots in the direction of their cursor when they press a button on their keyboard. Rather than tracking the cursor continuously through the event loop, we can instead just wait for the space bar event, and then find out where the cursor is.

Here's an example where we get and print the mouse state when the user presses their space bar:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6void HandleKeyboardEvent(const SDL_KeyboardEvent& E) {
7  if (E.key == SDLK_SPACE) {
8    float x, y;
9    SDL_MouseButtonFlags Buttons{SDL_GetMouseState(&x, &y)};
10
11    std::cout << "\nMouse Position: "
12      << x << ", " << y;
13    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT)) {
14      std::cout << " - Left Button is pressed";
15    }
16    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)) {
17      std::cout << " - Right Button is pressed";
18    }
19  }
20}
21
22int main(int, char**) {
23  SDL_Init(SDL_INIT_VIDEO);
24  Window GameWindow;
25  SDL_Event Event;
26
27  bool IsRunning = true;
28  while (IsRunning) {
29    while (SDL_PollEvent(&Event)) {
30      if (Event.type == SDL_EVENT_KEY_DOWN) {
31        HandleKeyboardEvent(Event.key);
32      } else if (Event.type == SDL_EVENT_QUIT) {
33        IsRunning = false;
34      }
35    }
36    GameWindow.Render();
37    GameWindow.Update();
38  }
39
40  SDL_Quit();
41  return 0;
42}

1Mouse Position: 289, 101
2Mouse Position: 525, 150 - Left Button is pressed
3Mouse Position: 64, 210 - Left Button is pressed - Right Button is pressed

Getting Mouse State from Tick Functions

Another use case for querying the mouse state rather than using the event loop is for game objects that need to continuously track the mouse.

For example, we might be working on a drag-and-drop interaction that needs to continuously track the cursor whilst the player is holding down their mouse button.

In these scenarios, we'd typically use those objects' Tick() function to implement the required behaviors:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6class Object {
7 public:
8  void Tick() {
9    float x, y;
10    Uint32 Buttons{SDL_GetMouseState(&x, &y)};
11
12    std::cout << "\nMouse Position: "
13      << x << ", " << y;
14    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT)) {
15      std::cout << " - Left Button is pressed";
16    }
17    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)) {
18      std::cout << " - Right Button is pressed";
19    }
20  }
21};
22
23int main(int, char**) {
24  SDL_Init(SDL_INIT_VIDEO);
25  Window GameWindow;
26  Object GameObject;
27  SDL_Event Event;
28
29  bool IsRunning = true;
30  while (IsRunning) {
31    while (SDL_PollEvent(&Event)) {
32      if (Event.type == SDL_EVENT_QUIT) {
33        IsRunning = false;
34      }
35    }
36    GameWindow.Render();
37    GameObject.Tick(); 
38    GameWindow.Update();
39  }
40
41  SDL_Quit();
42  return 0;
43}

1Mouse Position: 308, 108
2Mouse Position: 308, 107
3Mouse Position: 308, 107
4Mouse Position: 308, 106 - Left Button is pressed
5Mouse Position: 308, 106 - Left Button is pressed
6Mouse Position: 307, 106 - Left Button is pressed - Right Button is pressed

Remember, the more logic we have executing in Tick() functions, the slower our application will take to produce each frame, reducing responsiveness.

We should strive to only perform these checks when they're required. One possible solution is a simple if check:

1// ...
2class Object {
3public:
4  void Tick() {
5    // Return early if tracking isn't enabled
6    if (!shouldTrack) return;
7
8    // Track Mouse
9    // ...
10  }
11private:
12  // Only enable tracking when necessary
13  bool shouldTrack{false};
14};

Mouse State and Focus

By default, SDL will stop tracking our mouse when our pointer leaves the window. The x and y values updated by SDL_GetMouseState() will continue to report the position the cursor had before leaving the window.

In most situations, objects that are using this function to continuously track the mouse will want to pause that tracking when the cursor is outside the window.

As we covered in the previous lesson, we can monitor the event loop and examine top-level window events to understand when the cursor enters and leaves our window:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6class Object {
7public:
8  void HandleEvent(const SDL_Event& E) {
9    if (E.type == SDL_EVENT_WINDOW_MOUSE_ENTER) {
10      std::cout << "\nTracking Resumed";
11      shouldTrack = true;
12    } else if (E.type == SDL_EVENT_WINDOW_MOUSE_LEAVE) {
13      std::cout << "\nTracking Paused";
14      shouldTrack = false;
15    }
16  }
17
18  void Tick() {
19    if (shouldTrack) { HandleMouse(); }
20  }
21
22private:
23  bool shouldTrack{true};
24
25  void HandleMouse() {
26    float x, y;
27    Uint32 Buttons{SDL_GetMouseState(&x, &y)};
28
29    std::cout << "\nMouse Position: "
30      << x << ", " << y;
31    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT)) {
32      std::cout << " - Left Button is pressed";
33    }
34    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)) {
35      std::cout << " - Right Button is pressed";
36    }
37  }
38};
39
40int main(int, char**) {
41  SDL_Init(SDL_INIT_VIDEO);
42  Window GameWindow;
43  Object GameObject;
44  SDL_Event Event;
45
46  bool IsRunning = true;
47  while (IsRunning) {
48    while (SDL_PollEvent(&Event)) {
49      if (Event.type == SDL_EVENT_QUIT) {
50        IsRunning = false;
51      }
52      GameObject.HandleEvent(Event); 
53    }
54    
55    GameWindow.Render();
56    GameObject.Tick(); 
57    GameWindow.Update();
58  }
59
60  SDL_Quit();
61  return 0;
62}

1Mouse Position: 25, 196
2Mouse Position: 25, 196
3Tracking Paused
4Tracking Resumed
5Mouse Position: 14, 238
6Mouse Position: 14, 238

Summary

SDL provides functions for querying mouse state directly, giving us flexibility in how we handle mouse input beyond just responding to events. Key topics covered:

Using SDL_GetMouseState() to get current mouse position and button states
Working with bit masks to check mouse button states
Understanding when to use state queries vs event handling
Handling mouse tracking when cursor leaves window

Mouse State

Files

Using SDL_GetMouseState()

Passing nullptr to SDL_GetMouseState()

Example: Retrieving Mouse State on Keyboard Event

src/main.cpp

Getting Mouse State from Tick Functions

src/main.cpp

Mouse State and Focus

src/main.cpp

Summary

Using `SDL_GetMouseState()`

Passing `nullptr` to `SDL_GetMouseState()`