From 8a67896d9af57086523198b7a7ee8f7ac6954b9a Mon Sep 17 00:00:00 2001 From: Frank Praznik Date: Tue, 21 Jan 2025 11:05:05 -0500 Subject: [PATCH] docs: Note the preferred function for getting the content scale of a window SDL_GetWindowDisplayScale() should be preferred over SDL_GetDisplayForWindow() + SDL_GetDisplayContentScale() for querying the per-window content scale, as the former provides a more accurate and current value for individual windows, as the per-window value can differ from the base display scale value, particularly on high-DPI and multi-monitor desktops. --- include/SDL3/SDL_video.h | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 43e471799e..bcf6f4d16e 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -729,6 +729,12 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the display + * for a window and calling this function, as the per-window content scale factor + * may differ from the base value of the display it is on, particularly on + * high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. @@ -737,6 +743,7 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat * * \since This function is available since SDL 3.1.3. * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays */ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID);