When our game is running in a window, we typically don't need to care that much about things like the resolution and refresh rate of that screen. Our window is just one of potentially many that are running on that display.

However, when we're running in exclusive full screen mode, we need to be more aware of the characteristics of that screen, and potentially even change them.

These characteristics are grouped together into a display mode, which includes the resolution (width and height in pixels), refresh rate (how often the screen updates per second, measured in Hz), and pixel format (how color data is stored).

Reasons to Change Display Modes

There are two main reasons why we need to care about display modes:

Optimizing Performance: Choosing an appropriate display mode ensures that the game runs smoothly on the user's hardware. Higher resolutions and refresh rates can be more demanding, while lower settings might improve performance on less powerful systems.
Ensuring Compatibility: Display modes can affect visual fidelity and gameplay responsiveness. For instance, choosing a mode with an unsupported refresh rate might result in tearing or other visual artifacts.

Games typically give players control over some aspects of the display mode, such as the screen resolution:

Screenshot of the Dishonored 2 options menu

SDL provides a collection of functions to manage display modes, including querying the available modes, setting the display mode for a window, and retrieving details about the current configuration.

Starting Point

This lesson builds on our earlier work. To focus on display modes, we will start with a minimal project containing a Window class and a main function with a basic application loop.

We've removed the specific event handling logic from the previous lesson to keep the code focused on this lesson's topic.

Files

src

Select a file to view its content

The `SDL_DisplayMode` Struct

SDL represents display modes using the SDL_DisplayMode type. This is a struct that contains several members, with the most important being:

displayId: The SDL_DisplayID that the display mode is associated with
w, h: integer values representing the width and height of the display mode in screen coordinates.
refresh_rate: A float representing how many times the screen updates per second (in Hz).
pixel_density: A float representing the scaling factor between screen coordinates and pixels. We'll cover this in more detail in the next lesson.
format: The SDL_PixelFormat of the display, describing how colors are represented.

In most cases, we won't be defining the properties of an SDL_DisplayMode directly. More often, we'll just be default-constructing an SDL_DisplayMode, and using various SDL functions to populate it.

Listing all Display Modes

In SDL3, the way to get all available fullscreen display modes for a monitor has changed. Instead of getting a count and then iterating by index, we now get a complete list directly.

First, we get a list of all connected displays using SDL_GetDisplays(), which we introduced earlier in the chapter:

1int DisplayCount{0};
2SDL_DisplayID* Displays{
3  SDL_GetDisplays(&DisplayCount)
4};

Then, for each display, we call SDL_GetFullscreenDisplayModes() to get an array of pointers to SDL_DisplayMode structs. Below, we get the display modes available to the first display returned by SDL_GetDisplays():

1int DisplayCount{0};
2SDL_DisplayID* Displays{
3  SDL_GetDisplays(&DisplayCount)
4};
5
6int ModeCount{0};
7SDL_DisplayMode** Modes{
8  SDL_GetFullscreenDisplayModes(
9    Displays[0], &ModeCount
10  )
11};

Both functions allocate memory that we are responsible for freeing with SDL_free().

Below, we combine all of these techniques to log out information about all of the available display modes, for each of our displays:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8
9  int DisplayCount{0};
10  SDL_DisplayID* Displays{
11    SDL_GetDisplays(&DisplayCount)
12  };
13
14  if (Displays) {
15    for (int i{0}; i < DisplayCount; ++i) {
16      SDL_DisplayID DisplayID{Displays[i]};
17      std::cout << "\n-- Display " << DisplayID << ": "
18        << SDL_GetDisplayName(DisplayID) << " --\n";
19
20      int ModeCount{0};
21      SDL_DisplayMode** Modes{
22        SDL_GetFullscreenDisplayModes(
23          DisplayID, &ModeCount
24        )
25      };
26      if (Modes) {
27        for (int j{0}; j < ModeCount; ++j) {
28          const SDL_DisplayMode* Mode{Modes[j]};
29          std::cout << "  Mode " << j << ": "
30            << int(Mode->w) << 'x' << int(Mode->h)
31            << " @ " << Mode->refresh_rate << "Hz\n";
32        }
33        SDL_free(Modes); // Free the modes array
34      }
35    }
36    SDL_free(Displays); // Free the displays array
37  }
38
51
52  SDL_Quit();
53  return 0;
54}

SDL sorts the modes such that those with higher resolutions are first. Display modes with the same resolution are then sorted by refresh rate. Our program's output might look something like this:

1-- Display 1: LG TV SSCR2 --
2  Mode 0: 4096x2160 @ 120Hz
3  Mode 1: 4096x2160 @ 119.88Hz
4  Mode 2: 4096x2160 @ 100Hz
5  Mode 3: 4096x2160 @ 75Hz
6...

Error Handling

If SDL_GetFullscreenDisplayModes() fails, it will return a nullptr. We can check for this and call SDL_GetError() for an explanation:

1int ModeCount = 0;
2if (!SDL_GetFullscreenDisplayModes(
3  0, // Invalid DisplayID 
4  &ModeCount
5)) {
6  std::cout << "Error getting display modes: "
7    << SDL_GetError();
8}

1Error getting display modes: Invalid display

Managing Window Display Modes

The recommended way to change a display's settings in SDL3 is to associate an SDL_DisplayMode with an SDL_Window. Then, whenever that window is running in fullscreen mode, the display will be updated to adopt that window's display mode.

Finding a Specific Mode

Instead of iterating through all available modes, we can ask SDL to find the best match for our desired settings. The SDL_GetClosestFullscreenDisplayMode() function does this.

Its arguments are:

The SDL_DisplayID of the monitor we're configuring,
The desired resolution width
The desired resolution height
The desired refresh rate
Whether high-DPI modes should be included in the search
The SDL_DisplayMode pointer which will be updated with the best-matching display mode

Below, we ask SDL to search for something close to a 1920x1080 144hz mode for our primary display:

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  SDL_DisplayID DisplayID{SDL_GetPrimaryDisplay()};
9  
10  SDL_DisplayMode Closest;
11  SDL_GetClosestFullscreenDisplayMode(
12    DisplayID, 1920, 1080, 144.0f, true, &Closest
13  );
14
15  std::cout << "Closest Display Mode: "
16    << Closest.w << "x" << Closest.h
17    << " @ " << Closest.refresh_rate << "Hz";
18  
31
32  SDL_Quit();
33  return 0;
34}

On my machine, it found one exactly matching our resolution, but with a slightly slower refresh rate:

1Closest Display Mode: 1920x1080 @ 120Hz

The SDL_GetClosestFullscreenDisplayMode() function returns a bool representing whether or not the search was successful. We can check this and call SDL_GetError() for information as usual:

1SDL_DisplayMode Closest;
2if (!SDL_GetClosestFullscreenDisplayMode(
3  DisplayID, 9999, 9999, 144.0f, true, &Closest
4)) {
5  std::cout << "Error getting display mode:\n  "
6    << SDL_GetError();
7}

1Error getting display mode:
2  Couldn't find any matching video modes

Setting a Window's Fullscreen Mode

Once we have the SDL_DisplayMode we want, we associate it with a window by passing it's pointer to SDL_SetWindowFullscreenMode(). This function tells SDL which mode to use when the window enters fullscreen.

This function does not make the window fullscreen by itself. It only prepares it. To activate full screen mode, we use SDL_SetWindowFullscreen() as we covered in the previous lesson:

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9  SDL_DisplayID DisplayID{
10    SDL_GetDisplayForWindow(GameWindow.GetRaw())
11  };
12  
13  SDL_DisplayMode Closest;
14  if (!SDL_GetClosestFullscreenDisplayMode(
15    DisplayID, 1920, 1080, 144.0f, true, &Closest
16  )) {
17    std::cout << "Error getting display mode:\n  "
18      << SDL_GetError();
19  }
20
21  // Associate the mode with the window
22  SDL_SetWindowFullscreenMode(
23    GameWindow.GetRaw(), &Closest
24  );
25
26  // This will now use the mode we set
27  SDL_SetWindowFullscreen(GameWindow.GetRaw(), true);
28  
40
41  SDL_Quit();
42  return 0;
43}

Using Desktop Fullscreen

Remember, if we haven't set a specific mode with SDL_SetWindowFullscreenMode(), calling SDL_SetWindowFullscreen(SomeWindow, true) will result in a desktop fullscreen window instead.

We can also go back to using desktop fullscreen by passing a nullptr to this function:

1// We no longer want to use a full screen mode
2SDL_SetWindowFullscreenMode(
3  GameWindow.GetRaw(), nullptr
4);
5
6// This will now use the "desktop" / "borderless"
7// fullscreen approach
8SDL_SetWindowFullscreen(GameWindow.GetRaw(), true);

Getting a Window's Fullscreen Mode

We can retrieve the display mode associated with a window using SDL_GetWindowFullscreenMode(). It returns a const pointer to the SDL_DisplayMode, or nullptr if no specific mode is set (meaning it will use desktop fullscreen).

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8  Window GameWindow;
9
10  SDL_DisplayID DisplayID{
11    SDL_GetDisplayForWindow(GameWindow.GetRaw())
12  };
13  
14  SDL_DisplayMode Closest;
15  if (!SDL_GetClosestFullscreenDisplayMode(
16    DisplayID, 1920, 1080, 144.0f, true, &Closest
17  )) {
18    std::cout << "Error getting display mode:\n  "
19      << SDL_GetError();
20  }
21
22  SDL_SetWindowFullscreenMode(
23    GameWindow.GetRaw(), &Closest
24  );
25
26  const SDL_DisplayMode* RetrievedMode{
27    SDL_GetWindowFullscreenMode(GameWindow.GetRaw())
28  };
29  
30  if (RetrievedMode) {
31    std::cout << "Window Fullscreen Mode: "
32      << RetrievedMode->w << "x"
33      << RetrievedMode->h << " @ "
34      << RetrievedMode->refresh_rate << "Hz";
35  }
36  
48
49  SDL_Quit();
50  return 0;
51}

1Window Fullscreen Mode: 1920x1080 @ 120Hz

Retrieving Monitor Display Modes

There are two other important display modes associated with a display:

The current display mode is what the monitor is currently using.
The desktop display mode is what the monitor uses by default when no application is in exclusive fullscreen.

`SDL_GetCurrentDisplayMode()`

SDL_GetCurrentDisplayMode() retrieves the current mode. In SDL3, it takes a SDL_DisplayID and returns a const pointer to the SDL_DisplayMode, or a nullptr on failure:

1SDL_DisplayID Display{SDL_GetPrimaryDisplay()};
2
3const SDL_DisplayMode* Mode{
4  SDL_GetCurrentDisplayMode(Display)
5};
6
7if (Mode) {
8  std::cout << "Current Display Mode: "
9    << Mode->w << "x" << Mode->h << " @ "
10    << Mode->refresh_rate << "Hz";
11} else {
12  std::cout << "Couldn't get Current Display Mode: "
13    << SDL_GetError();
14}

If the display currently has an exclusive fullscreen window, the display mode that SDL_GetCurrentDisplayMode() returns will be equivalent to what SDL_GetWindowFullscreenMode() would return for that window.

`SDL_GetDesktopDisplayMode()`

SDL_GetDesktopDisplayMode() retrieves the monitor's native/default mode. Its API is identical to SDL_GetCurrentDisplayMode().

1SDL_DisplayID Display{SDL_GetPrimaryDisplay()};
2
3const SDL_DisplayMode* DisplayMode{
4  SDL_GetCurrentDisplayMode(Display)
5};
6
7std::cout << "Current Display Mode: "
8  << DisplayMode->w << "x" << DisplayMode->h << " @ "
9  << DisplayMode->refresh_rate << "Hz";
10  
11const SDL_DisplayMode* DesktopMode{
12  SDL_GetCurrentDesktopMode(Display)
13};
14
15std::cout << "\nDesktop Display Mode: "
16  << DesktopMode->w << "x" << DesktopMode->h << " @ "
17  << DesktopMode->refresh_rate << "Hz";

When the display does not have an exclusive fullscreen window, SDL_GetDesktopDisplayMode() and SDL_GetCurrentDisplayMode() are equivalent.

However, when a window is in exclusive fullscreen, they may be different. SDL_GetDesktopDisplayMode() will still report the monitor's native resolution, whilst SDL_GetCurrentDisplayMode() will match the SDL_GetWindowFullscreenMode() for the window currently controlling the display.

1Current Display Mode: 2560x1440 (144Hz)
2Desktop Display Mode: 2560x1440 (144Hz)
3
4// (After entering 1920x1080 exclusive fullscreen)
5Current Display Mode: 1920x1080 (120Hz)
6Desktop Display Mode: 2560x1440 (144Hz)

Summary

Display modes provide a way to manage screen resolution and refresh rate, primarily for exclusive fullscreen games. They allow us to adapt to different hardware, optimize performance, and respond to player preferences. Here are the key points for SDL3:

Listing Modes: Use SDL_GetDisplays() and SDL_GetFullscreenDisplayModes() to explore supported display modes.
Finding a Mode: Use SDL_GetClosestFullscreenDisplayMode() to find the best match for desired settings.
Setting the Mode: Use SDL_SetWindowFullscreenMode() to associate a display mode with a window for exclusive fullscreen. Then, use SDL_SetWindowFullscreen(window, true) to activate it.
Retrieving Modes: Understand the differences between a window's associated mode - SDL_GetWindowFullscreenMode(), the current display mode - SDL_GetCurrentDisplayMode(), and the desktop mode - SDL_GetDesktopDisplayMode().

Fullscreen Display Modes

Reasons to Change Display Modes

Starting Point

Files

The `SDL_DisplayMode` Struct

Listing all Display Modes

src/main.cpp

Error Handling

Managing Window Display Modes

Finding a Specific Mode

Setting a Window's Fullscreen Mode

Using Desktop Fullscreen

Getting a Window's Fullscreen Mode

Retrieving Monitor Display Modes

`SDL_GetCurrentDisplayMode()`

`SDL_GetDesktopDisplayMode()`

Summary

Pixel Density and High-DPI Displays

Game Development with SDL3

Fullscreen Display Modes

Reasons to Change Display Modes

Starting Point

Files

The SDL_DisplayMode Struct

Listing all Display Modes

src/main.cpp

Error Handling

Managing Window Display Modes

Finding a Specific Mode

Setting a Window's Fullscreen Mode

Using Desktop Fullscreen

Getting a Window's Fullscreen Mode

Retrieving Monitor Display Modes

SDL_GetCurrentDisplayMode()

SDL_GetDesktopDisplayMode()

Summary

Pixel Density and High-DPI Displays

The `SDL_DisplayMode` Struct

`SDL_GetCurrentDisplayMode()`

`SDL_GetDesktopDisplayMode()`