Mouse State

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:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleButton(SDL_MouseButtonEvent& E) {
6  if (E.button == SDL_BUTTON_LEFT) {
7    if (E.state == SDL_PRESSED) {
8      std::cout << "Left button pressed at ("
9        << E.x << ", " << E.y << ")\n";
10    } else if (E.state == SDL_RELEASED) {
11      std::cout << "Left button released at ("
12        << E.x << ", " << E.y << ")\n";
13    }
14  }
15}
16
17void HandleMotion(SDL_MouseMotionEvent& E) {
18  std::cout << "Mouse moved to ("
19    << E.x << ", " << E.y << ")\n";
20}
21
22int main(int argc, char** argv) {
23  SDL_Init(SDL_INIT_VIDEO);
24  Window GameWindow;
25  SDL_Event E;
26
27  while (true) {
28    while (SDL_PollEvent(&E)) {
29      if (E.type == SDL_MOUSEBUTTONDOWN
30          || E.type == SDL_MOUSEBUTTONUP) {
31        HandleButton(E.button);
32      } else if (E.type == SDL_MOUSEMOTION) {
33        HandleMotion(E.motion);
34      }
35    }
36    GameWindow.Update();
37  }
38
39  SDL_Quit();
40  return 0;
41}

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:

Handling Mouse Input

Learn how to detect and handle mouse input events in SDL, including mouse motion, button clicks, and window entry/exit.

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

SDL_GetMouseState()

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

1int 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 and 0.

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:

1int x, y;
2Uint32 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 constants to use with these bit masks, allowing us to isolate the bit representing the button we’re interested in:

• SDL_BUTTON_LMASK checks if the left button is pressed
• SDL_BUTTON_RMASK checks if the right button is pressed

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

1int x, y;
2Uint32 Buttons { SDL_GetMouseState(&x, &y) };
3
4bool LeftPressed = Buttons & SDL_BUTTON_LMASK;
5bool RightPressed = Buttons & SDL_BUTTON_RMASK;

We cover bit masks and the & operator in more detail in our introductory course:

Bitwise Operators and Bit Flags

Unravel the fundamentals of bitwise operators and bit flags in this practical lesson

1int 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
9Uint32 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:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5void HandleKeyboardEvent(SDL_KeyboardEvent& E) {
6  if (E.type == SDL_KEYDOWN
7    && E.keysym.sym == SDLK_SPACE) {
8    int x, y;
9    Uint32 Buttons{SDL_GetMouseState(&x, &y)};
10
11    std::cout << "\nMouse Position: "
12      << x << ", " << y;
13    if (Buttons & SDL_BUTTON_LMASK) {
14      std::cout << " - Left Button is pressed";
15    }
16    if (Buttons & SDL_BUTTON_RMASK) {
17      std::cout << " - Right Button is pressed";
18    }
19  }
20}
21
main function|Show
22int main(int argc, char** argv) {/*...*/}

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:

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

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 {
3 public:
4  void Tick() {
5    // Return early if tracking isn't enabled
6    if (!shouldTrack) return;
7    
8    // Track Mouse
9    // ...
10  }
11 private:
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 SDL_WindowEvent events to understand when the cursor enters and leaves our window:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5class Object {
6public:
7  void HandleEvent(SDL_Event& E) {
8    if (E.type == SDL_WINDOWEVENT) {
9      HandleWindowEvent(E.window);
10    }
11  }
12
13  void Tick() {
14    if (shouldTrack) { HandleMouse(); }
15  }
16
17private:
18  bool shouldTrack{true};
19
20  void HandleWindowEvent(SDL_WindowEvent& E) {
21    if (E.event ==
22      SDL_WINDOWEVENT_ENTER) {
23      std::cout << "\nTracking Resumed";
24      shouldTrack = true;
25    } else if (E.event ==
26      SDL_WINDOWEVENT_LEAVE) {
27      std::cout << "\nTracking Paused";
28      shouldTrack = false;
29    }
30  }
31
HandleMouse method|Show
32  void HandleMouse() {/*...*/}
46};
47
48int main(int argc, char** argv) {
49  SDL_Init(SDL_INIT_VIDEO);
50  Window GameWindow;
51  Object GameObject;
52  SDL_Event Event;
53
54  while (true) {
55    while (SDL_PollEvent(&Event)) {
56      GameObject.HandleEvent(Event); 
57    }
58
59    GameObject.Tick(); 
60    GameWindow.RenderFrame();
61  }
62
63  SDL_Quit();
64  return 0;
65}

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

Preview: SDL_CaptureMouse()

If we need SDL to track our mouse even outside of our window, we can use the SDL_CaptureMouse() function. We cover this in detail later in the chapter.

Practical Example: Heat-Seeking Missile

Let's create a a more complex example that combines some of the techniques we’ve learned. This practical example will also demonstrate a scenario where querying mouse state is more appropriate than using events.

We'll build a simple projectile that follows the mouse cursor, using continuous position tracking to update its trajectory each frame. First, let's create a Projectile class that manages the projectile's position and appearance.

Our constructor will receive the SDL_Window* as an argument, and initialize the projectile’s position at the center of that window. We’ll also create an SDL_Surface representing the visual appearance of the projectile. We’ll just use a red square in this example:

1// Projectile.h
2#pragma once
3#include <SDL.h>
4
5class Projectile {
6 public:
7  Projectile(SDL_Window* window) {
8    // Get window dimensions
9    int windowWidth, windowHeight;
10    SDL_GetWindowSize(
11      window, &windowWidth, &windowHeight);
12
13    // Start in center of window
14    positionX = windowWidth / 2.0f;
15    positionY = windowHeight / 2.0f;
16
17    // Create a small red square surface
18    surface = SDL_CreateRGBSurface(
19      0, 20, 20, 32, 0, 0, 0, 0);
20    SDL_FillRect(surface, NULL, SDL_MapRGB(
21      surface->format, 255, 0, 0));
22  }
23
24  ~Projectile() { SDL_FreeSurface(surface); }
25
26 private:
27  float positionX{0.0f};
28  float positionY{0.0f};
29  SDL_Surface* surface{nullptr};
30};

Next, let's add the Tick() method that will update the projectile's position based on the current mouse location

Our projectile needs to track its position using floating-point numbers to allow for smooth movement. To accomplish this, we’ll store velocity components that will help create more natural motion over time, rather than having the projectile snap directly to the mouse position.

Don’t worry if the maths in this function doesn’t make sense - we’ll cover physics in a dedicated chapter later in the course:

1// Projectile.h
2#pragma once
3#include <SDL.h>
4#include <cmath>
5
6class Projectile {
7 public:
8  // ...
9  void Tick() {
10    // Get current mouse position
11    int mouseX, mouseY;
12    SDL_GetMouseState(&mouseX, &mouseY);
13
14    // Calculate direction to mouse
15    float directionX = mouseX - positionX;
16    float directionY = mouseY - positionY;
17
18    // Calculate distance to mouse
19    float distance = std::sqrt(
20      directionX * directionX +
21      directionY * directionY);
22
23    // Only move if we're not already at the target
24    if (distance > 1.0f) {
25      // Normalize direction
26      directionX /= distance;
27      directionY /= distance;
28
29      // Update velocity (gradual turn towards mouse)
30      const float turnSpeed = 0.2f;
31      velocityX += directionX * turnSpeed;
32      velocityY += directionY * turnSpeed;
33
34      // Limit maximum speed
35      const float maxSpeed = 5.0f;
36      float currentSpeed = std::sqrt(
37        velocityX * velocityX +
38        velocityY * velocityY);
39
40      if (currentSpeed > maxSpeed) {
41        velocityX = (velocityX / currentSpeed)
42        * maxSpeed;
43        velocityY = (velocityY / currentSpeed)
44        * maxSpeed;
45      }
46
47      // Update position based on velocity
48      positionX += velocityX;
49      positionY += velocityY;
50    }
51  }
52
53 private:
54  // ...
55  float velocityX{0.0f};
56  float velocityY{0.0f};
57};

Here's what's happening in the Tick() method:

1. We get the current mouse position using SDL_GetMouseState()
2. Calculate the direction and distance to the mouse
3. If we're not already at the target, update our velocity to move towards it
4. Apply a speed limit to prevent the projectile from moving too fast
5. Update the position based on our velocity

This continuous tracking creates smooth movement that would be impossible to achieve using mouse events alone, since we need to update our position every frame regardless of whether the mouse has moved.

Finally, we need a method to render our projectile. Here, we’ll apply the techniques we learned earlier in the course and blit our projectile’s surface onto the window surface:

1// Projectile.h
2#pragma once
3#include <SDL.h>
4#include <cmath>
5
6class Projectile {
7  // ...
8  void Render(SDL_Surface* windowSurface) {
9    // Create a rect for positioning our surface
10    SDL_Rect destRect{
11        // Center the square
12        static_cast<int>(positionX - 10),  
13        static_cast<int>(positionY - 10),
14        20,  // Width
15        20   // Height
16    };
17
18    // Draw the projectile to the window surface
19    SDL_BlitSurface(
20      surface, NULL,
21      windowSurface, &destRect
22    );
23  }
24};

Finally, we can put it all together in our main loop:

1#include <SDL.h>
2#include "Projectile.h"
3#include "Window.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  Projectile Missile{GameWindow.SDLWindow};
9  SDL_Event Event;
10
11  while (true) {
12    while (SDL_PollEvent(&Event)) {
13      if (Event.type == SDL_QUIT) {
14        SDL_Quit();
15        return 0;
16      }
17    }
18
19    // Update
20    Missile.Tick();
21
22    // Render
23    GameWindow.Render();
24    Missile.Render(GameWindow.Surface);
25
26    // Swap
27    GameWindow.Update();
28  }
29
30  SDL_Quit();
31  return 0;
32}

This example demonstrates why querying mouse state directly is sometimes preferable to using events. By checking the mouse position every frame, we can create smooth, continuous motion that responds immediately to the player's input.

If we tried to use mouse events instead, we would only receive updates when the mouse moves, making it impossible to implement this kind of fluid tracking behavior.

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
• Practical applications in game development scenarios

Next Lesson

Relative Mouse Mode

Learn how to restrict cursor movement to a window whilst capturing mouse motion continuously.

ContinueView Course