Relative Mouse Mode

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.

SDL_SetRelativeMouseMode()

SDL supports this interaction mode directly. It is called relative mouse mode, and we can toggle it using the SDL_SetRelativeMouseMode() function. We pass SDL_TRUE to enable it:

1#include <SDL.h>
2#include "Window.h"
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  Window GameWindow;
7  SDL_SetRelativeMouseMode(SDL_TRUE);
8
9  SDL_Event E;
Game Loop|Show
10  while (true) {/*...*/}
21}

We can turn relative mode off again by passing SDL_FALSE to SDL_SetRelativeMouseMode():

1SDL_SetRelativeMouseMode(SDL_FALSE);

When enabling relative mouse mode, the SDL_Window that currently has keyboard focus is used. We can ensure the correct SDL_Window is used by raising it before enabling relative mode:

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

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

Managing Window Input Focus

Learn how to manage and control window input focus in SDL applications, including how to create, detect, and manipulate window focus states.

1SDL_SetWindowRelativeMouseMode(
2  Window, SDL_TRUE
3);

Error Handling

Enabling relative mode isn’t always supported. The SDL_SetRelativeMouseMode() function returns a negative error code if it fails, or 0 if it succeeds.

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

1if (SDL_SetRelativeMouseMode(SDL_TRUE) == 0) {
2  std::cout << "Relative mode enabled\n";
3} else {
4  std::cout << "Error enabling relative mode: "
5    << SDL_GetError() << '\n';
6}

SDL_GetRelativeMouseMode()

We can check if relative mode is currently enabled using SDL_GetRelativeMouseMode():

1if (SDL_GetRelativeMouseMode()) {
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:

1#include <SDL.h>
2#include "Window.h"
3
4void HandleKeyboardEvent(SDL_KeyboardEvent& E) {
5  if (E.keysym.sym == SDLK_TAB) {
6    SDL_SetRelativeMouseMode(
7      SDL_GetRelativeMouseMode()
8        ? SDL_FALSE
9        : SDL_TRUE
10    );
11  }
12}
13
14int main(int argc, char** argv) {
15  SDL_Init(SDL_INIT_VIDEO);
16  Window GameWindow;
17
18  SDL_Event E;
19  while (true) {
20    while (SDL_PollEvent(&E)) {
21      if (E.type == SDL_KEYDOWN) {
22        HandleKeyboardEvent(E.key);
23      } else if (E.type == SDL_QUIT) {
24        SDL_Quit();
25        return 0;
26      }
27    }
28    GameWindow.Update();
29    GameWindow.Render();
30  }
31}

Cursor Visibility and Position

Since the player typically doesn’t control a cursor in relative mode, it makes sense to hide the cursor and constrain it to the center of the window. This is the default behavior in SDL, however we can change it by setting appropriate hints.

SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE

This hint determines whether the cursor is visible when relative mode is on. By default, it is set to "0", corresponding to the cursor being invisible.

We can change it to "1" to show the cursor:

1SDL_SetHint(
2  SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE, "1"
3);

SDL_HINT_MOUSE_RELATIVE_MODE_CENTER

When relative mode is enabled, this hint controls whether the cursor is constrained to the center of the window, or can move anywhere within the window. By default, it is set to "1", locking the cursor to the center.

We can change it to "0" to let the cursor move anywhere within the window:

1SDL_SetHint(
2  SDL_HINT_MOUSE_RELATIVE_MODE_CENTER, "0"
3);

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 typically 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. These values report where the mouse has moved in relation to the previous SDL_MouseMotionEvent:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleMotionEvent(SDL_MouseMotionEvent& E) {
6  std::cout << "Relative mouse motion: "
7    << E.xrel << ", " << E.yrel << '\n';
8}
9
Main Function|Show
10int main(int argc, char** argv) {/*...*/}

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_GetRelativeMouseMode() to check whether relative mode is enabled or not. This can help us when the behavior of our event handler needs to adapt accordingly:

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleMotionEvent(SDL_MouseMotionEvent& E) {
6  if (SDL_GetRelativeMouseMode()) {
7    std::cout << "Relative mouse motion: "
8      << E.xrel << ", " << E.yrel << '\n';
9  } else {
10    std::cout << "Cursor window position: "
11      << E.x << ", " << E.y << '\n';
12  }
13}
14
Main Function|Show
15int main(int argc, char** argv) {/*...*/}

1Cursor window position: 428, 81
2Cursor window position: 428, 82
3Cursor window position: 428, 83

Relative Mouse State

Previously, we introduced how we could query the mouse state at any time using SDL_GetMouseState():

Mouse State

Learn how to monitor mouse position and button states in real-time using SDL's state query functions

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().

It operates similarly to SDL_GetMouseState() but provides the relative movement of the mouse since the last call, along with the button state. The function updates the provided integer pointers with the relative x and y values:

1int 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
2int x;
3SDL_GetRelativeMouseState(&x, nullptr);

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

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:

1// MouseTracker.h
2#pragma once
3#include <SDL.h>
4#include <iostream>
5
6struct MouseTracker {
7  void Tick() {
8    int x, y;
9    SDL_GetRelativeMouseState(&x, &y);
10    std::cout << "Mouse movement this frame: "
11      << x << ", " << y << '\n';
12  }
13};

1#include <SDL.h>
2#include "Window.h"
3#include "MouseTracker.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  MouseTracker Tracker;
9
10  SDL_Event E;
11  while (true) {
Event Loop|Show
12    while (SDL_PollEvent(&E)) {/*...*/}
19    GameWindow.Update();
20    Tracker.Tick();
21    GameWindow.Render();
22  }
23}

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

If we call the function more than once in a single tick, all invocations except the first will report no further movement:

1#include <SDL.h>
2#include "Window.h"
3#include "MouseTracker.h"
4
5int main(int argc, char** argv) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8  MouseTracker TrackerA;
9  MouseTracker TrackerB;
10
11  SDL_Event E;
12  while (true) {
Event Loop|Show
13    while (SDL_PollEvent(&E)) {/*...*/}
20    GameWindow.Update();
21    TrackerA.Tick();
22    TrackerB.Tick();
23    std::cout << '\n';
24    GameWindow.Render();
25  }
26}

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:

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

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

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

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:

1#include <SDL.h>
2#include "Window.h"
3
4struct Camera {
5  void HandleMotion(SDL_MouseMotionEvent& E) {
6    xPosition += E.xrel * CameraSpeed;
7    yPosition += E.yrel * CameraSpeed;
8  }
9
10  // Make the camera move at double speed
11  float CameraSpeed{2.0f};
12
13  // Make the camera move at half speed
14  // float CameraSpeed{0.5f};
15
16  int xPosition;
17  int yPosition;
18};
19
Main Function|Show
20int main(int argc, char** argv) {/*...*/}

In more complex games, we’d let the player define this coefficient within an options menu. This lets them specify the exact level of mouse reponsiveness that they prefer.

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_GetMouseStateRelative() 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");

Summary

Relative mouse mode in SDL2 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_SetRelativeMouseMode(): Enables or disables relative mouse mode
• SDL_GetRelativeMouseMode(): Checks if relative mouse mode is currently active
• SDL_GetRelativeMouseState(): Retrieves relative mouse movement and button states
• SDL_RaiseWindow(): Ensures the correct window has input focus
• SDL_SetHint(): Set hints to control cursor visibility and movement characteristics

Next Lesson

Reading Data from Files

Learn how to read and parse game data stored in external files using SDL_RWops

ContinueView Course