Pixel Density and High-DPI Displays

To take advantage of higher quality screens, we first need to understand what pixel density we're working with. SDL3 provides new tools to make this straightforward.

Getting the Display Scale

The most direct way to handle DPI is to get the display's scaling factor. The SDL_GetWindowDisplayScale() function returns this as a float.

• A value of 1.0f means no scaling (e.g., a standard 96 DPI display on Windows).
• A value of 2.0f means the display has double the pixel density (a "Retina" display).
• Other values like 1.25f or 1.5f represent intermediate scaling levels.

1#include <SDL3/SDL.h>
2#include <iostream>
3#include "Window.h"
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8
9  float RenderScale{SDL_GetWindowDisplayScale(
10    GameWindow.GetRaw()
11  )};
12  std::cout << "Render Scale: " << RenderScale;
13  
14  SDL_Event E;
15  bool isRunning{true};
16  while (isRunning) {
17    while (SDL_PollEvent(&E)) {
18      if (E.type == SDL_EVENT_QUIT) {
19        isRunning = false;
20      }
21    }
22    GameWindow.Render();
23    GameWindow.Update();
24  }
25  
26  SDL_Quit();
27  return 0;
28}

1Render Scale: 1.25

You can use this scale factor to convert between logical screen coordinates and physical pixels:

Retrieving Pixel Size Directly

If you need the exact pixel dimensions of the window's drawable area (the surface), you can use SDL_GetWindowSizeInPixels(). This is useful when you need to work directly with pixel buffers or configure graphics APIs like OpenGL or Vulkan.

Depending on the platform and your settings, the value returned from SDL_GetWindowSizeInPixels() may be different from that returned by SDL_GetWindowSize().

This is just based on what units that platform uses to represent window sizes. On Windows, for example, these values will be the same, but they will likely be different on macOS:

1#include <SDL3/SDL.h>
2#include <iostream>
3#include "Window.h"
4
5int main(int, char**) {
6  SDL_Init(SDL_INIT_VIDEO);
7  Window GameWindow;
8
9  int w1, h1;
10  SDL_GetWindowSize(
11    GameWindow.GetRaw(), &w1, &h1
12  );
13
14  int w2, h2;
15  SDL_GetWindowSizeInPixels(
16    GameWindow.GetRaw(), &w2, &h2
17  );
18
19  std::cout << "Screen Size: " << w1 << "x" << h1
20    << ", Pixel Size: " << w2 << "x" << h2;
21
22  SDL_Event E;
23  bool isRunning{true};
24  while (isRunning) {
25    while (SDL_PollEvent(&E)) {
26      if (E.type == SDL_EVENT_QUIT) {
27        isRunning = false;
28      }
29    }
30    GameWindow.Render();
31    GameWindow.Update();
32  }
33  
34  SDL_Quit();
35  return 0;
36}

1Screen Size: 700x200, Pixel Size: 700x200

We've introduced SDL_GetWindowDisplayScale() as the primary way of working with varying pixel-densities, but you might notice another, similar-sounding function: SDL_GetDisplayContentScale(). You should almost always use SDL_GetWindowDisplayScale(), but this section briefly explains the differences.

The existence of two similar functions is a result of SDL3 abstracting away major differences in how operating systems handle high-DPI scaling.

Windows, Android, and X11 (Linux)

On these platforms, window coordinates are typically treated as physical pixels. A call to SDL_CreateWindow() for an 800x600 window creates an 800x600 pixel window.

The SDL_GetDisplayContentScale() will be greater than 1.0 (e.g., 1.5 for 150% scaling). On these systems, SDL_GetWindowDisplayScale() will usually return the same value as SDL_GetDisplayContentScale().

macOS, iOS, and Wayland (Linux)

On these platforms, window coordinates are logical "points". An 800x600 window is 800x600 points. If the window has the SDL_WINDOW_HIGH_PIXEL_DENSITY flag on a high-DPI (Retina) display, the operating system gives it a backing framebuffer with more pixels (e.g., 1600x1200).

On these systems, SDL_GetDisplayContentScale() is usually 1.0, and the scaling is communicated through the window's pixel density - SDL_GetWindowPixelDensity().

Comparing Functions

The recommended SDL_GetWindowDisplayScale() function provides the correct, unified scaling factor regardless of the underlying platform's model. It correctly combines the pixel density and the content scale to give you the single number you care most about: "By what factor do I multiply my logical sizes to get the correct pixel sizes for rendering?"

The official SDL documentation provides more information on these functions, as well as a numeric example for a 4K (3840x2160) monitor with 200% scaling. The table below illustrates how SDL3 unifies the different platform approaches:

Notice how, despite the underlying differences, SDL_GetWindowDisplayScale() returns the correct 2.0f multiplier on both platforms.

This makes it the most reliable choice for cross-platform code, although we should of course test our program on all platforms we're releasing on.

Once we know what scaling factor is being applied, any component that can benefit from high-DPI displays can react to that value. A component that loads images, for example, might select to use higher-resolution images if the application is running on a high-DPI display.

To set this up, we simply make the scaling factor available to any component in our application that might want it. The following Render() function receives not just the SDL_Surface to render on, but also the DPI scaling factor that is currently in effect:

The DPI scaling factor is not constant. It can change during your application's lifetime, most commonly when the user drags the window from one display to another with a different pixel density.

If we don't react to these changes then, depending on the platform, our graphics may no longer be rendering in the way we intended:

To create a seamless experience, our application needs to detect and respond to these changes. SDL3 provides two main events for this:

• SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED: This event is sent when the scale factor of the display the window is on changes. That is, after this event, we'd expect SDL_GetWindowDisplayScale() to return a different value.
• SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED: This fires whenever the backing pixel buffer of the window changes size. This happens as a result of regular window resizing, but it can also happen as a result of DPI changes - ie, where SDL_GetWindowPixelDensity() would return a new value. After a window pixel size change event, we'd expect SDL_GetWindowSizeInPixels() to calculate different values, but not necessarily SDL_GetWindowSize().

We can listen for one or both of these events in our main loop and have our components react as appropriate based on the type of content they're rendering.

Below, we recalculate our RenderScale whenever either changes, which influences how our Rectangle is scaled:

1#include <SDL3/SDL.h>
2#include <SDL3/SDL_main.h>
3#include <iostream>
4#include "Window.h"
5#include "Rectangle.h"
6
7int main(int, char**) {
8  SDL_Init(SDL_INIT_VIDEO);
9  Window GameWindow;
10  Rectangle Rect;
11
12  float RenderScale{SDL_GetWindowDisplayScale(
13    GameWindow.GetRaw()
14  )};
15  
16  SDL_Event E;
17  bool isRunning{true};
18  while (isRunning) {
19    while (SDL_PollEvent(&E)) {
20      if (E.type == SDL_EVENT_QUIT) {
21        isRunning = false;
22      }
23
24      if (E.type == SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED ||
25          E.type == SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED) {
26        RenderScale = SDL_GetWindowDisplayScale(
27          GameWindow.GetRaw()
28        );
29        std::cout << "DPI Scale changed to: "
30          << RenderScale << '\n';
31      }
32    }
33    GameWindow.Render();
34    Rect.Render(GameWindow.GetSurface(), RenderScale);
35    GameWindow.Update();
36  }
37  
38  SDL_Quit();
39  return 0;
40}

In this lesson, we've explored how to create SDL3 applications that work across different display resolutions and pixel densities. We've learned about DPI awareness, scaling techniques, and how to handle resolution changes dynamically. Key takeaways:

• DPI awareness is enabled by default in SDL3, but using the SDL_WINDOW_HIGH_PIXEL_DENSITY flag is good practice for cross-platform consistency.
• Use SDL_GetWindowDisplayScale() to get the current display's scaling factor.
• SDL_GetWindowSizeInPixels() provides the exact pixel dimensions of the window's drawable surface.
• Scale graphics at render time based on the current DPI scaling factor to maintain physical size.
• Monitor window events like SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED and SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED to handle DPI changes dynamically, such as when a window is moved between monitors.