Understanding SDL Display Indices

SDL assigns a numerical index to each connected display. These indices start from 0 and increment for every additional monitor. Display indices are used throughout SDL’s API to refer to specific monitors when querying their properties or creating windows.

Mapping to Physical Monitors

The display index corresponds to the monitor order reported by the operating system. For example, if you have three monitors connected, SDL_GetDisplayName(0) will return the name of the first monitor as recognized by the OS.

You can retrieve the total number of displays using SDL_GetNumVideoDisplays():

1int numDisplays = SDL_GetNumVideoDisplays();
2std::cout << "Number of displays: "
3  << numDisplays << '\n';

Example Use Case

If you want to create a window on the second monitor, use display-specific macros like this:

1SDL_CreateWindow("My Window",
2                 SDL_WINDOWPOS_CENTERED_DISPLAY(1), 
3                 SDL_WINDOWPOS_CENTERED_DISPLAY(1), 
4                 800, 600, SDL_WINDOW_SHOWN);

How Indices Can Vary

• If monitors are reconnected or the OS display order changes, the indices might not correspond to their previous mappings.
• On multi-GPU setups, displays might appear in different orders depending on which GPU is active.

Display Index Pitfalls

Always verify the number of displays using SDL_GetNumVideoDisplays() to avoid referencing an out-of-bounds index. For example:

1if (displayIndex >= SDL_GetNumVideoDisplays()) {
2  std::cerr << "Invalid display index: "
3    << displayIndex << '\n';
4}

By understanding display indices, you can ensure your application works smoothly in multi-monitor environments.