Document DPI awareness quirks on Windows

[flibitijibibo]

I keep forgetting to write this down and it came up again today so I'm doing it before I forget one more time...

Other platforms like macOS/iOS/tvOS/Wayland all support high-DPI surfaces by using the ALLOW_HIGHDPI flag, and this can be done on a per-window basis. Windows on the other hand took a slightly several very different approaches that all require some kind of weird process on startup. The ways that I'm aware of:

• A manifest file next to the exe
• Calling SetProcessDPIAware
• Calling a really verbose series of DPI awareness functions that makes the awareness per-monitor (the only code I know of that actually does this is proprietary so I can't cite it even though it's the only way to rationally explain it)

As far as I know, we can't do this in SDL for the developer, but I always forget why we can't do it, both in SDL and SDLmain. It would be nice to have this written down in docs/ somewhere so it's easy to link to, we could possibly include a code snippet for those who don't want to put up with manifest files.

[slime73]

I'd consider #2119 related to this – @ericwa is probably the expert in the room for SDL+highdpi on Windows (and has some related branches for it at https://github.com/ericwa/SDL/branches).

As for why SDL doesn't just use the Windows DPI awareness stuff by default, I suppose one reason is since everything else related to highdpi-on-Windows isn't hooked up in SDL, things inside the window would look tiny on high pixel density screens and SDL wouldn't provide ways to let developers use their intended size (without Eric's work, anyway).

[ericwa]

Sorry it's taking so long!

As for why SDL doesn't just use the Windows DPI awareness stuff by default, I suppose one reason is since everything else related to highdpi-on-Windows isn't hooked up in SDL, things inside the window would look tiny on high pixel density screens and SDL wouldn't provide ways to let developers use their intended size (without Eric's work, anyway).

Found an interesting quirk related to this today..

What I'm seeing is, the first time I enter exclusive fullscreen mode for a given .exe, Windows will flag the .exe as DPI aware (in a way that persists across future launches) - so from that point onwards the .exe will look tiny on high DPI displays anyway. Specifically, this checkbox is getting checked, and I'm not doing it manually:

(If anyone wants to try reproducing this:

• I'm on Windows 10, 21H1, 19043.1348. Main monitor is 150%, secondary monitor is 100%.
• building testwm2 off a SDL commit from yesterday 343fa61 , no High-DPI related patches
• launching testwm2 I get the window scaled by 150% by the OS, as expected
• can close and reopen, or do Alt+Enter (desktop fullscreen) and I still get the blurry 150% OS provided scaling, as expected
• doing Ctrl+Enter to go exclusive fullscreen, then Ctrl+Enter again, I now get a unscaled 1pt = 1px window
• The highdpi awareness checkbox in the .exe properties in the above screenshot is now checked, and future launches are now unscaled, 1pt = 1px

I'm not too surprised Windows is doing this (assuming it's real and not a mistake in my testing) - I guess the logic is "only games would change the display mode, and games don't want blurry OS scaling, so if we (the OS) see a non-DPI-aware app change the display mode, flag it as DPI aware." I also recall MS's highdpi documentation saying something to the effect of "games should always declare themselves DPI aware".

It does make me wonder, when we're ready to merge my Windows highdpi patches, should we have SDL, at startup, call the Windows functions to declare highdpi awareness unconditionally (since Windows appears to be forcing it on apps under some conditions, anyway - namely the first time they change display modes)? Also, glfw and SFML both do the same from what I can see.

[slouken]

Yes, that seems like a good idea.

[slouken]

We automatically mark applications as DPI aware in SDL 3.0. :)