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.

Author: Kontrabant

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);