Modern games and applications often require precise control over display management. In this lesson, you'll learn to retrieve monitor counts, display names, and manage window placement across different displays using SDL3.

In the context of games, the concepts we cover in this lesson are primarily useful for letting players choose which monitor they want our game to run on:

Screenshot of the Dishonored 2 options menu

Starting Point

This lesson is the first in a new chapter focused on advanced windowing and display topics. To keep the examples clear and focused, we'll start with a minimal project structure similar to what we used at the beginning of the course.

This includes a main.cpp with a basic application loop and a simplified Window.h class:

Files

src

Select a file to view its content

Getting Display Information

SDL associates an SDL_DisplayID with every connected display. This type is a simple integer, which we pass to various other SDL functions when we're querying or configuring our displays.

We can get the SDL_DisplayID of the primary display using the SDL_GetPrimaryDisplay() function:

1SDL_DisplayID DisplayID{SDL_GetPrimaryDisplay()};

An SDL_DisplayID is a simple integer, and the SDL API uses the 0 value to represent errors. So, if SDL_GetPrimaryDisplay() fails, it will return 0:

1SDL_DisplayID DisplayID{SDL_GetPrimaryDisplay()};
2
3if (!DisplayID) {
4  std::cout << "Couldn't get primary display: "
5    << SDL_GetError();
6}

Working with Multiple Displays

To understand how many displays we're working with, and what IDs we use to identify them, we can call the SDL_GetDisplays() function.

The SDL_GetDisplays() function returns a pointer to a C-style array of SDL_DisplayIDs and provides the count of displays through an output parameter.

We need to prompt SDL to free this memory when we no longer require it, by passing the pointer to SDL_free():

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
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    std::cout << "Displays: " << DisplayCount;
16    
17    // Remember to free the memory!
18    SDL_free(Displays);
19  }
20
33
34  SDL_Quit();
35  return 0;
36}

We can see how many IDs are in the array - that is, how many monitors are detected on the system we're running on - by examining the output parameter.

If we have 4 connected displays, for example, our program should detect that:

1Displays: 4

Handling `SDL_GetDisplays()` Errors

If SDL_GetDisplays() fails, it will return a nullptr. This typically indicates an error, which can be further investigated using SDL_GetError(). Below, we attempt to get the displays before we have initialized the video subsystem, which results in an error:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
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    std::cout << "Displays: " << DisplayCount;
16    SDL_free(Displays);
17  } else {
18    std::cout << "Could not get displays: "
19      << SDL_GetError();
20  }
21  
34
35  SDL_Quit();
36  return 0;
37}

1Could not get displays: Video subsystem has not been initialized

Getting a Display Name

When presenting options for our player to select a monitor, it can be helpful to identify the displays by name. We can do this by passing an SDL_DisplayID to the SDL_GetDisplayName() function.

This will return a const char* string containing the name of the display.

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
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    std::cout << "First Display Name: "
16      << SDL_GetDisplayName(Displays[0]);
17    SDL_free(Displays);
18  }
19  
32
33  SDL_Quit();
34  return 0;
35}

1First Display Name: DELL S2721DGF

Listing All Display Names

Knowing the names of all connected displays can be useful for games or applications that allow players to select a monitor. To achieve this, we can iterate over the array of SDL_DisplayIDs returned by SDL_GetDisplays() and pass each of their SDL_DisplayIDs to SDL_GetDisplayName():

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
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      const char* DisplayName{
17        SDL_GetDisplayName(Displays[i])
18      };
19      if (DisplayName) {
20        std::cout << "Display " << Displays[i]
21          << ": " << DisplayName << '\n';
22      } else {
23        std::cout << "Display " << Displays[i]
24          << ": Unknown (" << SDL_GetError() << ")\n";
25      }
26    }
27    SDL_free(Displays);
28  } else {
29    std::cout << "Error: " << SDL_GetError();
30    SDL_Quit();
31    return 1;
32  }
33  
46
47  SDL_Quit();
48  return 0;
49}

1Display 1: DELL S2721DGF
2Display 2: DELL S2721DGF
3Display 3: DELL U2515H
4Display 4: DELL U2515H

Handling `SDL_GetDisplayName()` Errors

The SDL_GetDisplayName() function will return a nullptr if it is unable to get the name of the display with the ID we provide. We can call SDL_GetError() for an explanation of this failure. Below, we provide an invalid display ID of 0:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8
9  const char* Name{SDL_GetDisplayName(0)};
10  if (Name) {
11    std::cout << "Display 0: " << Name;
12  } else {
13    std::cout << "Cannot get display name: "
14      << SDL_GetError();
15  }
16  
29
30  SDL_Quit();
31  return 0;
32}

1Cannot get display name: Invalid display

Creating Windows on Specific Monitors

As before, to set the position of our window, we use the more flexible properties system with SDL_CreateWindowWithProperties().

To create a window on a specific monitor, we can explicity chose x and y values that are within the bounds of that display. We cover how to do that in the next section.

A simpler alternative is to use two helper macros that SDL provides:

SDL_WINDOWPOS_CENTERED_DISPLAY(x) to center the window on a specific display , where x is the SDL_DisplayID.
SDL_WINDOWPOS_UNDEFINED_DISPLAY(x) to let the platform choose the exact position on that display , where x is the SDL_DisplayID of that display.

For example, the following program creates two windows, each centered on a different monitor. We'll get the list of displays, and then use the ID of the first two displays to create our windows:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
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 || DisplayCount < 2) {
15    std::cout << "Need at least two displays.\n";
16    SDL_Quit();
17    return 1;
18  }
19
20  // Properties for Window 1 on Displays[0]
21  SDL_PropertiesID Props1{SDL_CreateProperties()};
22  
23  // Positioning Window 1 on Displays[0]
24  SDL_SetNumberProperty(Props1,
25    SDL_PROP_WINDOW_CREATE_X_NUMBER,
26    SDL_WINDOWPOS_CENTERED_DISPLAY(Displays[0]));
27  SDL_SetNumberProperty(Props1,
28    SDL_PROP_WINDOW_CREATE_Y_NUMBER,
29    SDL_WINDOWPOS_CENTERED_DISPLAY(Displays[0])
30  );
31  
32  // Other Window 1 Properties
33  SDL_SetStringProperty(Props1,
34    SDL_PROP_WINDOW_CREATE_TITLE_STRING,
35    "First Monitor");
36  SDL_SetNumberProperty(Props1,
37    SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER, 400);
38  SDL_SetNumberProperty(Props1,
39    SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER, 400);
40    
41  // Create the window
42  SDL_Window* Window1{
43    SDL_CreateWindowWithProperties(Props1)};
44  SDL_DestroyProperties(Props1);
45
46  // Properties for Window 2 on Displays[1]
47  SDL_PropertiesID Props2{SDL_CreateProperties()};
48  
49  SDL_SetNumberProperty(Props2,
50    SDL_PROP_WINDOW_CREATE_X_NUMBER,
51    SDL_WINDOWPOS_CENTERED_DISPLAY(Displays[1]));
52  SDL_SetNumberProperty(Props2,
53    SDL_PROP_WINDOW_CREATE_Y_NUMBER,
54    SDL_WINDOWPOS_CENTERED_DISPLAY(Displays[1])
55  );
56  
57  // Other Window 2 Properties
58  SDL_SetStringProperty(Props2,
59    SDL_PROP_WINDOW_CREATE_TITLE_STRING,
60    "Second Monitor");
61  SDL_SetNumberProperty(Props2,
62    SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER, 400);
63  SDL_SetNumberProperty(Props2,
64    SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER, 400);
65    
66  // Create the Window
67  SDL_Window* Window2{
68    SDL_CreateWindowWithProperties(Props2)};
69  SDL_DestroyProperties(Props2);
70
71  SDL_free(Displays);
72
99    
100  SDL_Quit();
101  return 0;
102}

Getting Display Bounds

To understand the size and layout of our user's monitors, we can get their display bounds. This involves passing the SDL_DisplayID and a pointer to an SDL_Rect to the SDL_GetDisplayBounds() function:

1SDL_Rect Bounds;
2SDL_GetDisplayBounds(DisplayID, &Bounds);

As we've covered in the past, an SDL_Rect combines 4 integers to represent a rectangle. SDL_GetDisplayBounds() updates these members with values representing the position and size of a given display. These values are useful if we want some operations, such as moving a window, to target a specific monitor. We'll demonstrate this use case in the next section.

Below, we iterate through all of our displays, and log out their bounds:

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{SDL_GetDisplays(&DisplayCount)};
11
12  if (Displays) {
13    SDL_Rect Bounds;
14    for (int i = 0; i < DisplayCount; ++i) {
15      SDL_GetDisplayBounds(Displays[i], &Bounds);
16      std::cout << "[Display " << Displays[i]
17        << "] Left: " << Bounds.x
18        << ", Top: " << Bounds.y
19        << ", Width: " << Bounds.w
20        << ", Height: " << Bounds.h << '\n';
21    }
22    SDL_free(Displays);
23  }
24
37
38  SDL_Quit();
39  return 0;
40}

1[Display 1] Left: 0, Top: 0, Width: 2560, Height: 1440
2[Display 2] Left: 2560, Top: 0, Width: 2560, Height: 1440
3[Display 3] Left: 14, Top: -1440, Width: 2560, Height: 1440
4[Display 4] Left: 2574, Top: -1440, Width: 2560, Height: 1440

Moving Windows to Specific Monitors

Once we've used SDL_GetDisplayBounds() to understand the size and position of a monitor, we can move a window onto that monitor by setting its position to within those bounds.

Below, we move the window to the top left of display 1 if the user presses 1 on their keyboard, and to the top left of display 2 if the user presses 2:

src/main.cpp

1#include <iostream>
2#include <SDL3/SDL.h>
3#include <SDL3/SDL_main.h>
4#include "Window.h"
5
6void HandleKeydownEvent(
7  const SDL_KeyboardEvent& E,
8  SDL_DisplayID* Displays,
9  int DisplayCount
10) {
11  SDL_Window* Window{
12    SDL_GetWindowFromID(E.windowID)
13  };
14
15  SDL_Rect Bounds;
16  if (E.key == SDLK_1 && DisplayCount > 0) {
17    SDL_GetDisplayBounds(Displays[0], &Bounds);
18    SDL_SetWindowPosition(Window, Bounds.x, Bounds.y);
19  } else if (E.key == SDLK_2 && DisplayCount > 1) {
20    SDL_GetDisplayBounds(Displays[1], &Bounds);
21    SDL_SetWindowPosition(Window, Bounds.x, Bounds.y);
22  }
23}
24
25int main(int, char**) {
26  SDL_Init(SDL_INIT_VIDEO);
27  Window GameWindow;
28
29  int DisplayCount{0};
30  SDL_DisplayID* Displays{
31    SDL_GetDisplays(&DisplayCount)
32  };
33
34  SDL_Event E;
35  bool IsRunning = true;
36  while (IsRunning) {
37    while (SDL_PollEvent(&E)) {
38      if (E.type == SDL_EVENT_KEY_DOWN) {
39        HandleKeydownEvent(E.key, Displays, DisplayCount);
40      } else if (E.type == SDL_EVENT_QUIT) {
41        IsRunning = false;
42      }
43    }
44    GameWindow.Update();
45  }
46
47  if (Displays) {
48    SDL_free(Displays);
49  }
50  SDL_Quit();
51  return 0;
52}

Window Borders

In a previous chapter, we introduced the notion of window decorations, which SDL refers to as borders. These can include elements like the title bar.

When setting a window position, we are setting the position of the window's top-left corner, excluding decorations. The borders are added outside this area, so we typically want to ensure we leave enough room for them.

We can do this using the SDL_GetWindowBordersSize() function, which we covered in our lesson on .

Get Display of Window

If we have a window and need to find out which display it is on, we can use the SDL_GetDisplayForWindow() function. We pass it an SDL_Window pointer, and retrieve an SDL_DisplayID as the return value:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6int main(int, char**) {
7  SDL_Init(SDL_INIT_VIDEO);
8    Window GameWindow;
9
10  SDL_DisplayID Display{
11    SDL_GetDisplayForWindow(GameWindow.GetRaw())
12  };
13  std::cout << "Window is on display " << Display
14    << " (" << SDL_GetDisplayName(Display) << ")";
15
27
28  SDL_Quit();
29  return 0;
30}

1Window is on display 1 (DELL S2721DGF)

In this example, we log out the name of the display the window is currently on when the player presses their spacebar:

src/main.cpp

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5
6void HandleKeydownEvent(const SDL_KeyboardEvent& E) {
7  if (E.key != SDLK_SPACE) return;
8
9  SDL_Window* Window{
10    SDL_GetWindowFromID(E.windowID)
11  };
12  SDL_DisplayID Display{
13    SDL_GetDisplayForWindow(Window)
14  };
15  std::cout << "Window is on display " << Display
16    << " (" << SDL_GetDisplayName(Display) << ")\n";
17}
18
19int main(int, char**) {
20  SDL_Init(SDL_INIT_VIDEO);
21  Window GameWindow;
22
23  SDL_Event E;
24  bool IsRunning = true;
25  while (IsRunning) {
26    while (SDL_PollEvent(&E)) {
27      if (E.type == SDL_EVENT_KEY_DOWN) {
28        HandleKeydownEvent(E.key);
29      } else if (E.type == SDL_EVENT_QUIT) {
30        IsRunning = false;
31      }
32    }
33    GameWindow.Render();
34    GameWindow.Update();
35  }
36
37  SDL_Quit();
38  return 0;
39}

1Window is on display 1 (DELL S2721DGF)
2Window is on display 3 (DELL U2515H)

Summary

This lesson covers detecting displays, fetching their properties, and dynamically creating and positioning windows across multiple screens. Key takeaways:

Access the number of connected monitors and their IDs with SDL_GetDisplays().
Use SDL_GetDisplayName() to display monitor names for user-friendly interfaces.
Create windows on specific displays using SDL_CreateWindowWithProperties() and the SDL_PROP_WINDOW_CREATE_DISPLAY_ID_NUMBER property.
Understand display dimensions and layout with SDL_GetDisplayBounds().
Manage window decorations with SDL_GetWindowBordersSize() for better placement accuracy.

Video Displays

Starting Point

Files

Getting Display Information

Working with Multiple Displays

src/main.cpp

Handling `SDL_GetDisplays()` Errors

src/main.cpp

Getting a Display Name

Listing All Display Names

src/main.cpp

Handling `SDL_GetDisplayName()` Errors

src/main.cpp

Creating Windows on Specific Monitors

src/main.cpp

Getting Display Bounds

src/main.cpp

Moving Windows to Specific Monitors

src/main.cpp

Window Borders

Get Display of Window

src/main.cpp

src/main.cpp

Summary

Fullscreen Windows

Game Development with SDL3

Video Displays

Starting Point

Files

Getting Display Information

Working with Multiple Displays

src/main.cpp

Handling SDL_GetDisplays() Errors

src/main.cpp

Getting a Display Name

Listing All Display Names

src/main.cpp

Handling SDL_GetDisplayName() Errors

src/main.cpp

Creating Windows on Specific Monitors

src/main.cpp

Getting Display Bounds

src/main.cpp

Moving Windows to Specific Monitors

src/main.cpp

Window Borders

Get Display of Window

src/main.cpp

src/main.cpp

Summary

Fullscreen Windows

Handling `SDL_GetDisplays()` Errors

Handling `SDL_GetDisplayName()` Errors