So far, our example programs have been using the mouse to control a pointer within our window, letting users point and click on UI elements. However, many programs, especially first-person games, use the mouse differently. For example:

Rather than controlling a pointer, the mouse controls the direction that the player's character is looking.
The pointer can never leave the window. For example, the player can move their mouse as far as they want in any direction - our program will continue to react appropriately by, for example, continuously rotating their character.

Setting Relative Mouse Mode

SDL supports this interaction mode directly. It is called relative mouse mode, and we can toggle it using the SDL_SetWindowRelativeMouseMode() function. In SDL3, this function is window-specific, requiring the SDL_Window* as its first argument. We pass true as the second argument to enable it.

The following program will immediately enable relative mouse mode. To make quitting easier without a mouse cursor, we'll also let our program be closed using the escape key:

Files

src

Select a file to view its content

We can turn relative mode off by passing false to SDL_SetWindowRelativeMouseMode():

1SDL_SetWindowRelativeMouseMode(GameWindow.GetRaw(), false);

Relative Mode and Input Focus

Relative mouse mode is closely related to input focus. A window with relative mouse mode enabled can only influence the cursor when that window has input focus. If it loses input focus (by the user alt-tabbing, for example) the cursor will return to normal until that window regains focus.

To ensure relative mode is applied correctly, especially in multi-window applications, it's good practice to first give the window input focus using SDL_RaiseWindow():

1void SetRelativeMode(
2  SDL_Window* Window, bool Enable
3) {
4  if (Enable) {
5    SDL_RaiseWindow(Window);
6    SDL_SetWindowRelativeMouseMode(Window, true);
7  } else {
8    SDL_SetWindowRelativeMouseMode(Window, false);
9  }
10}

We cover input focus and SDL_RaiseWindow() in more detail in our lesson on .

Errors when Setting Relative Mode

Enabling relative mode isn't always supported. In SDL3, SDL_SetWindowRelativeMouseMode() returns a bool - true if it succeeds, and false if it fails.

We can check this return value to determine if an error occurred, and use SDL_GetError() for an explanation of the error:

1if (SDL_SetWindowRelativeMouseMode(GameWindow.GetRaw(), true)) {
2  std::cout << "Relative mode enabled\n";
3} else {
4  std::cout << "Error enabling relative mode: "
5    << SDL_GetError() << '\n';
6}

Getting Relative Mouse Mode

We can check if relative mode is currently enabled for a specific window using SDL_GetWindowRelativeMouseMode():

1if (SDL_GetWindowRelativeMouseMode(GameWindow.GetRaw())) {
2  std::cout << "Relative mode is enabled\n";
3} else {
4  std::cout << "Relative mode not enabled\n";
5}

Hybrid Interaction Models

Many applications require switching dynamically between relative and non-relative modes based on the user's context. For instance, a first-person game might use relative mode during gameplay for seamless camera control but switch to non-relative mode for navigating menus.

To implement this, you can toggle relative mode dynamically based on user input. Below is an example where pressing the Tab key toggles between the two modes:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include "Window.h"
4
5void HandleKeyboardEvent(
6  const SDL_KeyboardEvent& E, Window& GameWindow
7) {
8  if (E.key == SDLK_TAB) {
9    bool CurrentMode{SDL_GetWindowRelativeMouseMode(
10      GameWindow.GetRaw()
11    )};
12    SDL_SetWindowRelativeMouseMode(
13      GameWindow.GetRaw(), !CurrentMode
14    );
15  }
16}
17
18int main(int, char**) {
19  SDL_Init(SDL_INIT_VIDEO);
20  Window GameWindow;
21
22  SDL_Event Event;
23  bool IsRunning = true;
24  while (IsRunning) {
25    while (SDL_PollEvent(&Event)) {
26      if (Event.type == SDL_EVENT_KEY_DOWN) {
27        HandleKeyboardEvent(Event.key, GameWindow);
28      } else if (Event.type == SDL_EVENT_QUIT) {
29        IsRunning = false;
30      }
31    }
32    GameWindow.Render();
33    GameWindow.Update();
34  }
35
36  SDL_Quit();
37  return 0;
38}

Mouse Motion Events in Relative Mode

When relative mode is enabled, we typically don't care about where the cursor is in our window. Often, the cursor is just going to be locked in the middle of the window, and will be hidden anyway.

Instead, we care about the relative movement of the mouse - that is, the direction and distance the mouse has moved compared to some previous moment in time.

Within our event loop, these values are available within the xrel and yrel members of the SDL_MouseMotionEvent. In SDL3, these values are floats, providing higher precision. They report where the mouse has moved in relation to the previous SDL_MouseMotionEvent:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleMotionEvent(const SDL_MouseMotionEvent& E) {
7  std::cout << "Relative mouse motion: "
8    << E.xrel << ", " << E.yrel << '\n';
9}
10
11int main(int, char**) {
12  SDL_Init(SDL_INIT_VIDEO);
13  Window GameWindow;
14  SDL_SetWindowRelativeMouseMode(GameWindow.GetRaw(), true);
15
16  SDL_Event Event;
17  bool IsRunning = true;
18  while (IsRunning) {
19    while (SDL_PollEvent(&Event)) {
20      if (Event.type == SDL_EVENT_MOUSE_MOTION) {
21        HandleMotionEvent(Event.motion);
22      } else if (Event.type == SDL_EVENT_QUIT) {
23        IsRunning = false;
24      } else if (Event.type == SDL_EVENT_KEY_DOWN) {
25        if (Event.key.key == SDLK_ESCAPE) {
26          IsRunning = false;
27        }
28      }
29    }
30    GameWindow.Render();
31    GameWindow.Update();
32  }
33
34  SDL_Quit();
35  return 0;
36}

1Relative mouse motion: -1, 0
2Relative mouse motion: 0, -1
3Relative mouse motion: 3, 0

Using the xrel and yrel values doesn't require relative mode to be enabled. We can also use these values if we care about where the cursor moved relative to the previous mouse motion event.

Remember, we can also use SDL_GetWindowRelativeMouseMode() to check whether relative mode is enabled or not. This can help us when the behavior of our event handler needs to adapt accordingly:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleMotionEvent(
7  const SDL_MouseMotionEvent& E, Window& GameWindow
8) {
9  if (SDL_GetWindowRelativeMouseMode(GameWindow.GetRaw())) {
10    std::cout << "Relative mouse motion: "
11      << E.xrel << ", " << E.yrel << '\n';
12  } else {
13    std::cout << "Cursor window position: "
14      << E.x << ", " << E.y << '\n';
15  }
16}
17
18void HandleKeyboardEvent(
19  const SDL_KeyboardEvent& E, Window& GameWindow
20) {
21  if (E.key == SDLK_TAB) {
22    bool CurrentMode{SDL_GetWindowRelativeMouseMode(
23      GameWindow.GetRaw()
24    )};
25    SDL_SetWindowRelativeMouseMode(
26      GameWindow.GetRaw(), !CurrentMode
27    );
28  }
29}
30
31int main(int, char**) {
32  SDL_Init(SDL_INIT_VIDEO);
33  Window GameWindow;
34
35  SDL_Event Event;
36  bool IsRunning = true;
37  while (IsRunning) {
38    while (SDL_PollEvent(&Event)) {
39      if (Event.type == SDL_EVENT_MOUSE_MOTION) {
40        HandleMotionEvent(Event.motion, GameWindow);
41      } else if (Event.type == SDL_EVENT_QUIT) {
42        IsRunning = false;
43      } else if (Event.type == SDL_EVENT_KEY_DOWN) {
44        HandleKeyboardEvent(Event.key, GameWindow);
45      }
46    }
47    GameWindow.Render();
48    GameWindow.Update();
49  }
50  SDL_Quit();
51  return 0;
52}

1Cursor window position: 428, 81
2Cursor window position: 428, 82
3Cursor window position: 428, 83
4[After pressing TAB]:
5Relative mouse motion: -1, 0
6Relative mouse motion: -1, -1
7Relative mouse motion: 0, -2

Relative Speed Scaling

In most scenarios, we'll want to apply some coefficient to the relative mouse movement reported by SDL. For example, if the mouse is being used to control a camera in our game, we can multiply the relative movement by some coefficients to make the camera move slower or faster.

This is often a user-configurable setting (e.g., "Mouse Sensitivity").

We can apply this scaling factor directly to the relative motion data we receive.

`SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE`

In addition to scaling the relative speed on a case-by-case basis, we can prompt SDL to scale the speed before it is reported to us.

We can do this by setting the SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE. This will be used to scale the movement reported by SDL within mouse motion events and SDL_GetRelativeMouseState() when relative mode is enabled. By default, this has a value of 1.0, but we can scale it up or down as desired:

1// Double the relative movement values
2SDL_SetHint(
3  SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE, "2.0");
4
5// Halve the relative movement values
6SDL_SetHint(
7  SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE, "0.5");

`SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE`

When our operating system receives mouse input, the platform typically reinterprets those inputs to tweak the speed and acceleration with which our cursor moves.

These remappings are designed on the assumption our mouse is controlling a cursor. In relative mode, we're usually not controlling a cursor, so this intervention generally degrades the user experience.

As such, by default, SDL ignores these system settings when relative mode is enabled. We can change this by setting the SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE to "1", instead of its default value of "0":

1// Respect system mouse acceleration
2SDL_SetHint(
3  SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE, "1");
4
5// Ignore system mouse acceleration (default)
6SDL_SetHint(
7  SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE, "0");

Relative Mouse State

Previously, we introduced how we could query the mouse state at any time using SDL_GetMouseState(), as covered in our lesson on .

When using relative mode, SDL_GetRelativeMouseState() is likely to be more useful. It reports how far the mouse has moved, relative to the previous invocation of SDL_GetRelativeMouseState().

In SDL3, it operates similarly to SDL_GetMouseState() but provides the relative movement of the mouse as float values. The function updates the provided pointers with the relative x and y values:

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

We can pass a nullptr as either argument if we only care about relative movement in one direction:

1// We only care about horizontal motion
2float x;
3SDL_GetRelativeMouseState(&x, nullptr);

1// We only care about vertical motion
2float y;
3SDL_GetRelativeMouseState(nullptr, &y);

Let's create an object for tracking our mouse, and we'll connect it to our application loop via a Tick() function:

Files

src

Select a file to view its content

1Mouse movement this frame: 0, 1
2Mouse movement this frame: -1, 2
3Mouse movement this frame: 0, 2

Because SDL_GetRelativeMouseState() is sensitive to previous invocations, it is typically the case that we only want a single object monitoring the relative mouse state across our entire application.

If we call the function more than once in a single tick, all invocations except the first will report no further movement. In the following example, TrackerA "consumes" all of our movement data, leaving nothing visible to TrackerB:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5#include "MouseTracker.h"
6
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  Window GameWindow;
10  MouseTracker TrackerA;
11  MouseTracker TrackerB;
12
13  SDL_Event Event;
14  bool IsRunning = true;
15  while (IsRunning) {
16    while (SDL_PollEvent(&Event)) {
17      if (Event.type == SDL_EVENT_QUIT) {
18        IsRunning = false;
19      }
20    }
21    GameWindow.Render();
22    TrackerA.Tick();
23    TrackerB.Tick();
24    std::cout << '\n';
25    GameWindow.Update();
26  }
27  SDL_Quit();
28  return 0;
29}

1Mouse movement this frame: 0, 1
2Mouse movement this frame: 0, 0
3
4Mouse movement this frame: -1, 2
5Mouse movement this frame: 0, 0
6
7Mouse movement this frame: 0, 2
8Mouse movement this frame: 0, 0

SDL_GetRelativeMouseState() doesn't require relative mode to be enabled. Even if the player is controlling a pointer, there are some use cases where we're interested in the relative motion of that pointer, and SDL_GetRelativeMouseState() can help with that.

Mouse Button State

In our previous lesson on mouse state, we covered how to determine if our mouse buttons are currently pressed using the return value of SDL_GetMouseState().

The SDL_GetRelativeMouseState() function returns this same value, so we can use it in the same way:

src/MouseTracker.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <iostream>
4
5struct MouseTracker {
6  void Tick() {
7    float x, y;
8    SDL_MouseButtonFlags Buttons{
9      SDL_GetRelativeMouseState(&x, &y)};
10
11    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_LEFT)) {
12      std::cout << "Left button is pressed\n";
13    }
14    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_MIDDLE)) {
15      std::cout << "Middle button is pressed\n";
16    }
17    if (Buttons & SDL_BUTTON_MASK(SDL_BUTTON_RIGHT)) {
18      std::cout << "Right button is pressed\n";
19    }
20  }
21};

If we don't care about the mouse position and only care about the mouse button state, SDL_GetRelativeMouseState() and SDL_GetMouseState() are equivalent:

1SDL_MouseButtonFlags ButtonsA{
2  SDL_GetRelativeMouseState(nullptr, nullptr)};
3
4// Equivalent:
5SDL_MouseButtonFlags ButtonsB{
6  SDL_GetMouseState(nullptr, nullptr)};

Programattically Moving the Mouse

We can position the user's pointer anywhere on their screen using the SDL_WarpMouseGlobal() function. This the x and y coordinates we want to move the mouse to within their screen space.

The following expression sets the mouse 50 pixels to the right and 100 pixels below the top left corner of their primary display:

1SDL_WarpMouseGlobal(50.0, 100.0);

We can call this function at any time to forcibly move the user's pointer, but it's most useful within a hybrid interaction model to set where the cursor should be whenever the user leaves relative mouse mode.

In the following program, we record where the cursor was when relative mode was enabled, and then move the cursor back to that same position when it ends:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6struct MouseState {
7  float x{0};
8  float y{0};
9};
10
11void HandleKeyboardEvent(
12  const SDL_KeyboardEvent& E, Window& GameWindow,
13  MouseState& Mouse
14) {
15  if (E.key == SDLK_TAB) {
16    bool CurrentMode{SDL_GetWindowRelativeMouseMode(
17      GameWindow.GetRaw()
18    )};
19    
20    if (!CurrentMode) {
21      // About to enable relative mode - save position
22      SDL_GetGlobalMouseState(&Mouse.x, &Mouse.y);
23      SDL_SetWindowRelativeMouseMode(
24        GameWindow.GetRaw(), true
25      );
26    } else {
27      // About to disable relative mode - restore position
28      SDL_SetWindowRelativeMouseMode(
29        GameWindow.GetRaw(), false
30      );
31      SDL_WarpMouseGlobal(Mouse.x, Mouse.y);
32    }
33  }
34}
35
36int main(int, char**) {
37  SDL_Init(SDL_INIT_VIDEO);
38  Window GameWindow;
39  MouseState Mouse;
40
41  SDL_Event Event;
42  bool IsRunning = true;
43  while (IsRunning) {
44    while (SDL_PollEvent(&Event)) {
45      if (Event.type == SDL_EVENT_QUIT) {
46        IsRunning = false;
47      } else if (Event.type == SDL_EVENT_KEY_DOWN) {
48        HandleKeyboardEvent(Event.key, GameWindow, Mouse);
49      }
50    }
51    GameWindow.Render();
52    GameWindow.Update();
53  }
54  SDL_Quit();
55  return 0;
56}

Errors with Mouse Movement

SDL_WarpMouseGlobal() returns a boolean representing whether it was successful. We can use this to handle errors in the usual way:

1if (!SDL_WarpMouseGlobal(50.0, 100.0)) {
2  std::cout << "Error warping mouse: " << SDL_GetError();
3}

The most common reason for mouse warping to fail is that it's not supported in the current platform, but most desktop platforms do allow it.

Warping Mouse Within a Window

A window-based variation for mouse warping is available in the form of the SDL_WarpMouseInWindow() function. This positions the mouse relative to an SDL_Window, rather than relative to the global screen space.

It has a broadly similar API - the only difference is that the first argument will be the SDL_Window* we want to move the pointer within:

1if (!SDL_WarpMouseInWindow(
2  GameWindow.GetRaw(), 50.0, 100.0
3)) {
4  std::cout << "Error warping mouse: " << SDL_GetError();
5}

Summary

Relative mouse mode in SDL3 allows developers to capture continuous mouse motion within a window, particularly useful for first-person games and applications that require precise directional tracking.

This mode differs from traditional pointer-based interactions by focusing on relative movement instead of absolute cursor position. Key takeaways:

SDL_SetWindowRelativeMouseMode(): Enables or disables relative mouse mode for a specific window.
SDL_GetWindowRelativeMouseMode(): Checks if relative mouse mode is currently active for a window.
SDL_GetRelativeMouseState(): Retrieves relative mouse movement (as floats) and button states.
SDL_RaiseWindow(): Ensures the correct window has input focus before enabling relative mode.
SDL_SetHint(): Set hints to control mouse speed scaling.

Relative Mouse Mode

Setting Relative Mouse Mode

Files

Relative Mode and Input Focus

Errors when Setting Relative Mode

Getting Relative Mouse Mode

Hybrid Interaction Models

src/main.cpp

Mouse Motion Events in Relative Mode

src/main.cpp

src/main.cpp

Relative Speed Scaling

`SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE`

`SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE`

Relative Mouse State

Files

src/main.cpp

Mouse Button State

src/MouseTracker.h

Programattically Moving the Mouse

src/main.cpp

Errors with Mouse Movement

Warping Mouse Within a Window

Summary

Customising Mouse Cursors

Game Development with SDL3