From 8a67896d9af57086523198b7a7ee8f7ac6954b9a Mon Sep 17 00:00:00 2001
From: Frank Praznik <[EMAIL REDACTED]>
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 43e471799ef03..bcf6f4d16efad 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);