From 5836e057dea946aefc8a629998f87d6a0f8f9a00 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Wed, 17 May 2023 19:59:14 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
---
docs/README-highdpi.md | 36 ++++++++++++++--------------
include/SDL3/SDL_render.h | 7 +++---
include/SDL3/SDL_video.h | 50 +++++++++++++++++++++++++--------------
3 files changed, 54 insertions(+), 39 deletions(-)
diff --git a/docs/README-highdpi.md b/docs/README-highdpi.md
index a63cbbcb6752..c6fe908e85e0 100644
--- a/docs/README-highdpi.md
+++ b/docs/README-highdpi.md
@@ -1,18 +1,18 @@
-
-SDL 3.0 has new support for high DPI displays
-
-Displays now have a content display scale.
-
-The display scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability.
-
-The window size is now distinct from the window pixel size.
-
-The window also has a display scale, which is the content display scale relative to the window pixel size.
-
-For example, a 3840x2160 window displayed at 200% on Windows, and a 1920x1080 window on a 2x display on macOS will both have a pixel size of 3840x2160 and a display scale of 2.0.
-
-You can query the window size using SDL_GetWindowSize(), and when this changes you get an SDL_EVENT_WINDOW_RESIZED event.
-
-You can query the window pixel size using SDL_GetWindowSizeInPixels(), and when this changes you get an SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. You are guaranteed to get a SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event when a window is created and resized, and you can use this event to create and resize your graphics context for the window.
-
-You can query the window display scale using SDL_GetWindowDisplayScale(), and when this changes you get an SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED event.
+
+SDL 3.0 has new support for high DPI displays
+
+Displays now have a content display scale.
+
+The display scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability.
+
+The window size is now distinct from the window pixel size.
+
+The window also has a display scale, which is the content display scale relative to the window pixel size.
+
+For example, a 3840x2160 window displayed at 200% on Windows, and a 1920x1080 window on a 2x display on macOS will both have a pixel size of 3840x2160 and a display scale of 2.0.
+
+You can query the window size using SDL_GetWindowSize(), and when this changes you get an SDL_EVENT_WINDOW_RESIZED event.
+
+You can query the window pixel size using SDL_GetWindowSizeInPixels(), and when this changes you get an SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event. You are guaranteed to get a SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event when a window is created and resized, and you can use this event to create and resize your graphics context for the window.
+
+You can query the window display scale using SDL_GetWindowDisplayScale(), and when this changes you get an SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED event.
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 7ea1a312448f..b6909aafcfad 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -235,7 +235,8 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
* best option for you, based on what is available on the user's system.
*
* By default the rendering size matches the window size in pixels, but you
- * can call SDL_SetRenderLogicalPresentation() to change the content size and scaling options.
+ * can call SDL_SetRenderLogicalPresentation() to change the content size and
+ * scaling options.
*
* \param window the window where rendering is displayed
* \param name the name of the rendering driver to initialize, or NULL to
@@ -821,8 +822,8 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer)
* then copied to the output during presentation.
*
* You can disable logical coordinates by setting the mode to
- * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full
- * pixel resolution of the output window.
+ * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel
+ * resolution of the output window.
*
* You can convert coordinates in an event into rendering coordinates using
* SDL_ConvertEventToRenderCoordinates().
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index fe41eb27165a..cf81ebb6e3ee 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -410,10 +410,14 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
/**
* Get the content scale of a display.
*
- * The content scale is the expected scale for content based on the DPI settings of the display. For example, a 4K display might have a 2.0 (200%) display scale, which means that the user expects UI elements to be twice as big on this display, to aid in readability.
+ * The content scale is the expected scale for content based on the DPI
+ * settings of the display. For example, a 4K display might have a 2.0 (200%)
+ * display scale, which means that the user expects UI elements to be twice as
+ * big on this display, to aid in readability.
*
* \param displayID the instance ID of the display to query
- * \returns The content scale of the display, or 0.0f on error; call SDL_GetError() for more details.
+ * \returns The content scale of the display, or 0.0f on error; call
+ * SDL_GetError() for more details.
*
* \since This function is available since SDL 3.0.0.
*
@@ -556,12 +560,20 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window
/**
* Get the content display scale relative to a window's pixel size.
*
- * This is a combination of the window pixel density and the display content scale, and is the expected scale for displaying content in this window. For example, if a 3840x2160 window had a display scale of 2.0, the user expects the content to take twice as many pixels and be the same physical size as if it were being displayed in a 1920x1080 window with a display scale of 1.0.
+ * This is a combination of the window pixel density and the display content
+ * scale, and is the expected scale for displaying content in this window. For
+ * example, if a 3840x2160 window had a display scale of 2.0, the user expects
+ * the content to take twice as many pixels and be the same physical size as
+ * if it were being displayed in a 1920x1080 window with a display scale of
+ * 1.0.
*
- * Conceptually this value corresponds to the scale display setting, and is updated when that setting is changed, or the window moves to a display with a different scale setting.
+ * Conceptually this value corresponds to the scale display setting, and is
+ * updated when that setting is changed, or the window moves to a display with
+ * a different scale setting.
*
* \param window the window to query
- * \returns the display scale, or 0.0f on failure; call SDL_GetError() for more information.
+ * \returns the display scale, or 0.0f on failure; call SDL_GetError() for
+ * more information.
*
* \since This function is available since SDL 3.0.0.
*/
@@ -648,11 +660,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
* On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
* property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
*
- * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display.
- * Use SDL_GetWindowSize() to query the client area's size in window
- * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize()
- * to query the drawable size in pixels. Note that the drawable size can vary
- * after the window is created and should be queried again if you get an
+ * The window pixel size may differ from its window coordinate size if the
+ * window is on a high pixel density display. Use SDL_GetWindowSize() to query
+ * the client area's size in window coordinates, and
+ * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the
+ * drawable size in pixels. Note that the drawable size can vary after the
+ * window is created and should be queried again if you get an
* SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event.
*
* If the window is set fullscreen, the width and height parameters `w` and
@@ -712,11 +725,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, i
* On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
* property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
*
- * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display.
- * Use SDL_GetWindowSize() to query the client area's size in window
- * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize()
- * to query the drawable size in pixels. Note that the drawable size can vary
- * after the window is created and should be queried again if you get an
+ * The window pixel size may differ from its window coordinate size if the
+ * window is on a high pixel density display. Use SDL_GetWindowSize() to query
+ * the client area's size in window coordinates, and
+ * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the
+ * drawable size in pixels. Note that the drawable size can vary after the
+ * window is created and should be queried again if you get an
* SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event.
*
* If the window is set fullscreen, the width and height parameters `w` and
@@ -1020,9 +1034,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h);
* NULL can safely be passed as the `w` or `h` parameter if the width or
* height value is not desired.
*
- * The window pixel size may differ from its window coordinate size if the window is on a high pixel density display.
- * Use SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to get the
- * real client area size in pixels.
+ * The window pixel size may differ from its window coordinate size if the
+ * window is on a high pixel density display. Use SDL_GetWindowSizeInPixels()
+ * or SDL_GetRenderOutputSize() to get the real client area size in pixels.
*
* \param window the window to query the width and height from
* \param w a pointer filled in with the width of the window, may be NULL