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