Video Displays

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.

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:

Getting Display Count

We can retrieve the total number of displays available to our program using the SDL_GetNumVideoDisplays() function. Below, we invoke this function on a computer with 4 monitors:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  int DisplayCount{SDL_GetNumVideoDisplays()};
8  std::cout << "Displays: " << DisplayCount;
9
10  return 0;
11}

1Displays: 4

Error Handling

The SDL_GetNumVideoDisplays() function can return 0, or a negative error code. This typically indicates an error, which can be further investigated using SDL_GetError():

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO); 
6  int DisplayCount{SDL_GetNumVideoDisplays()};
7
8  if (DisplayCount > 0) {
9    std::cout << "Displays: " << DisplayCount;
10  } else {
11    std::cout << "Could not get displays: "
12      << SDL_GetError();
13  }
14
15  return 0;
16}

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 a display index to the SDL_GetDisplayName() function.

This will return a char* string containing the name of the display. The first display on our system will have a display index of 0:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  std::cout << "First Display Name: "
7    << SDL_GetDisplayName(0);
8
9  return 0;
10}

1First Display Name: DELL S2721DGF

Listing All Display Names

Beyond the first monitor, whose display index is 0, additional monitors will have incrementing display indices. For example, if our system has four displays, their display indices will be 0, 1, 2, and 3.

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 combine the SDL_GetNumVideoDisplays() and SDL_GetDisplayName() functions.

We can use SDL_GetNumVideoDisplays() to get the number of displays, and then use a for loop to iterate over all of the display indices in that range:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  int displayCount = SDL_GetNumVideoDisplays();
8  if (displayCount < 1) {
9    std::cout << "Error: " << SDL_GetError() << '\n';
10    return 1;
11  }
12
13  for (int i = 0; i < displayCount; ++i) {
14    const char* displayName = SDL_GetDisplayName(i);
15    if (displayName) {
16      std::cout << "Display " << i << ": "
17        << displayName << '\n';
18    } else {
19      std::cout << "Display " << i
20        << ": Unknown (" << SDL_GetError() << ")\n";
21    }
22  }
23
24  return 0;
25}

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

Error Handling

The SDL_GetDisplayName() function will return a nullptr if it is unable to get the name of the display with the index we provide. We can call SDL_GetError() for an explanation of this failure. Below, we provide a display index of 100, when our system only has 4 displays:

1#include <SDL.h>
2#include <iostream>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6
7  const char* Name{SDL_GetDisplayName(100)};
8  if (Name) {
9    std::cout << "Display 100: " << Name;
10  } else {
11    std::cout << "Cannot get display name:\n"
12      << SDL_GetError();
13  }
14
15  return 0;
16}

1Cannot get display name:
2displayIndex must be in the range 0 - 3

Creating Windows on Specific Monitors

As we’ve seen, we can set the horizontal and vertical positions of a window when creating it. We specify these coordinates using the second and third arguments to SDL_CreateWindow(), representing the horizontal and vertical position of the window:

1SDL_CreateWindow(
2  "First Monitor Window",
3  100, // Horizontal position
4  200, // Vertical position
5  400,400, 0)};

We’ll cover how to precisely control position on a targeted display later in this lesson. For now, let’s introduce some SDL helpers that cover most use cases.

SDL_WINDOWPOS_UNDEFINED_DISPLAY(n)

Previously, we saw how we could use the SDL_WINDOWPOS_UNDEFINED macro to let the platform decide where to position our window:

1SDL_CreateWindow(
2  "First Monitor Window",
3  SDL_WINDOWPOS_UNDEFINED, // Horizontal position
4  SDL_WINDOWPOS_UNDEFINED, // Vertical position
5  400,400, 0)};

We have a similar SDL_WINDOWPOS_UNDEFINED_DISPLAY() macro that lets us specify which display our window should be on, but let the platform decide the position within that display.

We provide the display index as an argument to SDL_WINDOWPOS_UNDEFINED_DISPLAY() to specify the monitor for our window. Below, we create a window on the display with index 0, and a second window on display with index 1:

1#include <SDL.h>
2
3int main(int argc, char** argv) {
4  SDL_Init(SDL_INIT_VIDEO);
5  SDL_Window* Window1{
6    SDL_CreateWindow(
7      "First Monitor Window",
8      SDL_WINDOWPOS_UNDEFINED_DISPLAY(0),
9      SDL_WINDOWPOS_UNDEFINED_DISPLAY(0),
10      400,400, 0)};
11
12  SDL_Window* Window2{
13    SDL_CreateWindow(
14      "Second Monitor Window",
15      SDL_WINDOWPOS_UNDEFINED_DISPLAY(1),
16      SDL_WINDOWPOS_UNDEFINED_DISPLAY(1),
17      400, 400, 0)};
18
19  SDL_Event E;
Application Loop|Show
20  while (true) {/*...*/}
29}

SDL_WINDOWPOS_CENTERED_DISPLAY(n)

A display-targetting variation of the SDL_WINDOWPOS_CENTERED macro is also available, in the form of SDL_WINDOWPOS_CENTERED_DISPLAY()

Below, we create a window centered on the display with index 0, and a second window centered on the display with index 1:

1#include <SDL.h>
2
3int main(int argc, char** argv) {
4  SDL_Init(SDL_INIT_VIDEO);
5  SDL_Window* Window1{
6    SDL_CreateWindow(
7      "First Monitor Centered",
8      SDL_WINDOWPOS_CENTERED_DISPLAY(0),
9      SDL_WINDOWPOS_CENTERED_DISPLAY(0),
10      400,400, 0)};
11
12  SDL_Window* Window2{
13    SDL_CreateWindow(
14      "Second Monitor Centered",
15      SDL_WINDOWPOS_CENTERED_DISPLAY(1),
16      SDL_WINDOWPOS_CENTERED_DISPLAY(1),
17      400, 400, 0)};
18
19  SDL_Event E;
Application Loop|Show
20  while (true) {/*...*/}
29}

Getting Display Bounds

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

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

As we’ve covered in the past, an SDL_Rect combines 4 integers to represent a rectangle. The member variables are:

• x - The left edge of the rectangle
• y - The top edge of the rectangle
• w - The width of the rectangle
• h - The height of the rectangle

SDL_GetDisplayBounds() updates these members of our SDL_Rect 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:

1#include <iostream>
2#include <SDL.h>
3
4int main(int argc, char** argv) {
5  SDL_Init(SDL_INIT_VIDEO);
6  
7  int DisplayCount{SDL_GetNumVideoDisplays()};
8  SDL_Rect Bounds;
9  for (int i{0}; i < DisplayCount; ++i) {
10    SDL_GetDisplayBounds(i, &Bounds);
11    std::cout << "[Display " << i
12      << "] Left: " << Bounds.x
13      << ", Top: " << Bounds.y
14      << ", Width: " << Bounds.w
15      << ", Height: " << Bounds.h << '\n';
16  }
17
18  SDL_Event E;
Application Loop|Show
19  while (true) {/*...*/}
28}

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

Whilst the SDL_Rect only includes where the top left corner of a display is within the overall monitor layout, we can calculate the right and bottom edges using some basic arithmetic.

The right edge of a display can be calculated by adding its left edge to it’s width. In this example, the right edge of display 2 is $14 + 2560 = 2574$

The bottom edge can be calculated by adding its top edge to its height. The bottom edge of display 2 is $-1440 + 1440 = 0$

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 0 if the user presses 0 on their keyboard, and to the top left of display 1 if the user presses 1:

1#include <iostream>
2#include <SDL.h>
3#include "Window.h"
4
5void HandleKeydownEvent(SDL_KeyboardEvent& E) {
6  SDL_Window* Window{
7    SDL_GetWindowFromID(E.windowID)};
8    
9  SDL_Rect Bounds;
10  if (E.keysym.sym == SDLK_0) {
11    SDL_GetDisplayBounds(0, &Bounds);
12    SDL_SetWindowPosition(
13      Window, Bounds.x, Bounds.y);
14  } else if (E.keysym.sym == SDLK_1) {
15    SDL_GetDisplayBounds(1, &Bounds);
16    SDL_SetWindowPosition(
17      Window, Bounds.x, Bounds.y);
18  }
19}
20
21int main(int argc, char** argv) {
22  SDL_Init(SDL_INIT_VIDEO);
23  Window GameWindow;
24
25  SDL_Event E;
26  while (true) {
27    while (SDL_PollEvent(&E)) {
28      if (E.type == SDL_KEYDOWN) {
29        HandleKeydownEvent(E.key);
30      } else if (E.type == SDL_QUIT) {
31        SDL_Quit();
32        return 0;
33      }
34    }
35    GameWindow.Update();
36    GameWindow.Render();
37  }
38}

Window Borders

In the previous chapter, we introduced the notion of window decorations, which SDL refers to as borders. These can include elements like the title bar. Below, we show a decorated window, and the equivalent undecorated window:

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

In the previous chapter, we covered how to do this using the SDL_GetWindowBorderSize() function.

Window Decorations and Borders

An introduction to managing SDL2 window decorations, borders, and client areas.

Below, we update our previous example where we move our window to the top left of a targetted monitor. But this time, we use SDL_GetWindowBorderSize() and some arithmetic to ensure the position we choose leaves enough room for the decorations:

1void HandleKeydownEvent(SDL_KeyboardEvent& E) {
2  SDL_Window* Window{
3    SDL_GetWindowFromID(E.windowID)};
4  SDL_Rect Bounds;
5
6  int Top, Left;
7  SDL_GetWindowBordersSize(
8    Window, &Top, &Left, nullptr, nullptr);
9
10  if (E.keysym.sym == SDLK_0) {
11    SDL_GetDisplayBounds(0, &Bounds);
12    SDL_SetWindowPosition(
13      Window, Bounds.x + Left, Bounds.y + Top);
14  } else if (E.keysym.sym == SDLK_1) {
15    SDL_GetDisplayBounds(1, &Bounds);
16    SDL_SetWindowPosition(
17      Window, Bounds.x + Left, Bounds.y + Top);
18  }
19}

Get Display of Window

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

1SDL_Window* Window(SDL_CreateWindow(
2  "Example Window",
3  SDL_WINDOWPOS_UNDEFINED,
4  SDL_WINDOWPOS_UNDEFINED,
5  300, 300, 0));
6
7std::cout << "Display Index: "
8  << SDL_GetWindowDisplayIndex(Window);

1Display Index: 0

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

1#include <SDL.h>
2#include <iostream>
3#include "Window.h"
4
5void HandleKeydownEvent(SDL_KeyboardEvent& E) {
6  if (E.keysym.sym != SDLK_SPACE) return;
7
8  SDL_Window* Window{
9    SDL_GetWindowFromID(E.windowID)};
10  int DisplayIndex{
11    SDL_GetWindowDisplayIndex(Window)};
12  std::cout << "\nWindow is on "
13    << SDL_GetDisplayName(DisplayIndex);
14}
15
16int main(int argc, char** argv) {
17  SDL_Init(SDL_INIT_VIDEO);
18  Window GameWindow;
19
20  SDL_Event E;
21  while (true) {
22    while (SDL_PollEvent(&E)) {
23      if (E.type == SDL_KEYDOWN) {
24        HandleKeydownEvent(E.key);
25      } else if (E.type == SDL_QUIT) {
26        SDL_Quit();
27        return 0;
28      }
29    }
30    GameWindow.Update();
31    GameWindow.Render();
32  }
33}

1Window is on DELL S2721DGF
2Window is on 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 with SDL_GetNumVideoDisplays().
• Use SDL_GetDisplayName() to display monitor names for user-friendly interfaces.
• Create windows on specific displays using SDL_WINDOWPOS_UNDEFINED_DISPLAY() and SDL_WINDOWPOS_CENTERED_DISPLAY() .
• Understand display dimensions and layout with SDL_GetDisplayBounds().
• Manage window decorations with SDL_GetWindowBordersSize() for better placement accuracy.

Next Lesson

Handling Mouse Scrolling

Learn how to detect and handle mouse scroll wheel events in SDL2, including vertical and horizontal scrolling, as well as scroll wheel button events.

ContinueView Course