From 4696c9556be690667e1783eb385bfa9267dda035 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Wed, 25 Jan 2023 01:23:17 -0800
Subject: [PATCH] =?UTF-8?q?SDL=203.0=20is=20going=20to=20be=20high=20DPI?=
=?UTF-8?q?=20aware=20and=20officially=20separates=20screen=E2=80=A6=20(#7?=
=?UTF-8?q?145)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* SDL 3.0 is going to be high DPI aware and officially separates screen coordinates from client pixel area
The public APIs to disable high DPI support have been removed
Work in progress on https://github.com/libsdl-org/SDL/issues/7134
---
include/SDL3/SDL_hints.h | 104 +++-------
include/SDL3/SDL_video.h | 286 +++++++++++----------------
src/test/SDL_test_common.c | 8 -
src/video/SDL_sysvideo.h | 3 +
src/video/SDL_video.c | 15 +-
src/video/windows/SDL_windowsvideo.c | 24 ++-
test/testautomation_hints.c | 2 -
test/testautomation_video.c | 2 +-
test/testdrawchessboard.c | 5 +-
9 files changed, 159 insertions(+), 290 deletions(-)
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 36cd2082d6c2..1a5237be54bf 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -92,7 +92,7 @@ extern "C" {
* By default this hint is not set and the APK expansion files are not searched.
*/
#define SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION "SDL_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION"
-
+
/**
* \brief Android APK expansion patch file version. Should be a string number like "1", "2" etc.
*
@@ -132,13 +132,13 @@ extern "C" {
* \brief A variable to control whether we trap the Android back button to handle it manually.
* This is necessary for the right mouse button to work on some Android devices, or
* to be able to trap the back button for use in your code reliably. If set to true,
- * the back button will show up as an SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of
+ * the back button will show up as an SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of
* SDL_SCANCODE_AC_BACK.
*
* The variable can be set to the following values:
* "0" - Back button will be handled as usual for system. (default)
* "1" - Back button will be trapped, allowing you to handle the key press
- * manually. (This will also let right mouse click work on systems
+ * manually. (This will also let right mouse click work on systems
* where the right mouse button functions as back.)
*
* The value of this hint is used at runtime, so it can be changed at any time.
@@ -147,7 +147,7 @@ extern "C" {
/**
* \brief Specify an application name.
- *
+ *
* This hint lets you specify the application name sent to the OS when
* required. For example, this will often appear in volume control applets for
* audio streams, and in lists of applications which are inhibiting the
@@ -516,7 +516,7 @@ extern "C" {
/**
* \brief If set, game controller face buttons report their values according to their labels instead of their positional layout.
- *
+ *
* For example, on Nintendo Switch controllers, normally you'd get:
*
* (Y)
@@ -561,9 +561,9 @@ extern "C" {
*
* The variable can be set to the following values:
* "0" - SDL_EVENT_TEXT_EDITING events are sent, and it is the application's
- * responsibility to render the text from these events and
+ * responsibility to render the text from these events and
* differentiate it somehow from committed text. (default)
- * "1" - If supported by the IME then SDL_EVENT_TEXT_EDITING events are not sent,
+ * "1" - If supported by the IME then SDL_EVENT_TEXT_EDITING events are not sent,
* and text that is being composed will be rendered in its own UI.
*/
#define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING"
@@ -1147,10 +1147,10 @@ extern "C" {
* \brief A variable controlling whether relative mouse motion is affected by renderer scaling
*
* This variable can be set to the following values:
- * "0" - Relative motion is unaffected by DPI or renderer's logical size
- * "1" - Relative motion is scaled according to DPI scaling and logical size
+ * "0" - Relative motion is unaffected by display scale or renderer's logical size
+ * "1" - Relative motion is scaled according to display scale scaling and logical size
*
- * By default relative mouse deltas are affected by DPI and renderer scaling
+ * By default relative mouse deltas are affected by display scale and renderer scaling
*/
#define SDL_HINT_MOUSE_RELATIVE_SCALING "SDL_MOUSE_RELATIVE_SCALING"
@@ -1487,7 +1487,7 @@ extern "C" {
* disabled. You should use a string that describes what your program is doing
* (and, therefore, why the screensaver is disabled). For example, "Playing a
* game" or "Watching a video".
- *
+ *
* Setting this to "" or leaving it unset will have SDL use a reasonable
* default: "Playing a game" or something similar.
*
@@ -1501,13 +1501,13 @@ extern "C" {
* On some platforms, like Linux, a realtime priority thread may be subject to restrictions
* that require special handling by the application. This hint exists to let SDL know that
* the app is prepared to handle said restrictions.
- *
+ *
* On Linux, SDL will apply the following configuration to any thread that becomes realtime:
* * The SCHED_RESET_ON_FORK bit will be set on the scheduling policy,
* * An RLIMIT_RTTIME budget will be configured to the rtkit specified limit.
* * Exceeding this limit will result in the kernel sending SIGKILL to the app,
* * Refer to the man pages for more information.
- *
+ *
* This variable can be set to the following values:
* "0" - default platform specific behaviour
* "1" - Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy
@@ -1595,7 +1595,7 @@ extern "C" {
#define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK"
/**
- * \brief A variable controlling whether the screensaver is enabled.
+ * \brief A variable controlling whether the screensaver is enabled.
*
* This variable can be set to the following values:
* "0" - Disable screensaver
@@ -1608,7 +1608,7 @@ extern "C" {
/**
* \brief Tell the video driver that we only want a double buffer.
*
- * By default, most lowlevel 2D APIs will use a triple buffer scheme that
+ * By default, most lowlevel 2D APIs will use a triple buffer scheme that
* wastes no CPU time on waiting for vsync after issuing a flip, but
* introduces a frame of latency. On the other hand, using a double buffer
* scheme instead is recommended for cases where low latency is an important
@@ -1662,11 +1662,6 @@ extern "C" {
*/
#define SDL_HINT_VIDEO_EXTERNAL_CONTEXT "SDL_VIDEO_EXTERNAL_CONTEXT"
-/**
- * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac and iOS)
- */
-#define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
-
/**
* \brief A variable that dictates policy for fullscreen Spaces on macOS.
*
@@ -1751,9 +1746,9 @@ extern "C" {
/**
* \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
-*
+*
* If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
-* SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly
+* SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly
* created SDL_Window:
*
* 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is
@@ -1820,13 +1815,13 @@ extern "C" {
/**
* \brief A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
- *
+ *
* This variable can be set to the following values:
* "0" - Disable _NET_WM_BYPASS_COMPOSITOR
* "1" - Enable _NET_WM_BYPASS_COMPOSITOR
- *
+ *
* By default SDL will use _NET_WM_BYPASS_COMPOSITOR
- *
+ *
*/
#define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR"
@@ -1964,7 +1959,7 @@ extern "C" {
#define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS"
/**
- * \brief A variable controlling whether the windows message loop is processed by SDL
+ * \brief A variable controlling whether the windows message loop is processed by SDL
*
* This variable can be set to the following values:
* "0" - The window message loop is not run
@@ -2005,7 +2000,7 @@ extern "C" {
#define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL"
/**
- * \brief A variable to specify custom icon resource id from RC file on Windows platform
+ * \brief A variable to specify custom icon resource id from RC file on Windows platform
*/
#define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON"
#define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL"
@@ -2040,58 +2035,7 @@ extern "C" {
#define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX"
/**
- * \brief Controls whether SDL will declare the process to be DPI aware.
- *
- * This hint must be set before initializing the video subsystem.
- *
- * The main purpose of declaring DPI awareness is to disable OS bitmap scaling of SDL windows on monitors with
- * a DPI scale factor.
- *
- * This hint is equivalent to requesting DPI awareness via external means (e.g. calling SetProcessDpiAwarenessContext)
- * and does not cause SDL to use a virtualized coordinate system, so it will generally give you 1 SDL coordinate = 1 pixel
- * even on high-DPI displays.
- *
- * For more information, see:
- * https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows
- *
- * This variable can be set to the following values:
- * "" - Do not change the DPI awareness (default).
- * "unaware" - Declare the process as DPI unaware. (Windows 8.1 and later).
- * "system" - Request system DPI awareness. (Vista and later).
- * "permonitor" - Request per-monitor DPI awareness. (Windows 8.1 and later).
- * "permonitorv2" - Request per-monitor V2 DPI awareness. (Windows 10, version 1607 and later).
- * The most visible difference from "permonitor" is that window title bar will be scaled
- * to the visually correct size when dragging between monitors with different scale factors.
- * This is the preferred DPI awareness level.
- *
- * If the requested DPI awareness is not available on the currently running OS, SDL will try to request the best
- * available match.
- */
-#define SDL_HINT_WINDOWS_DPI_AWARENESS "SDL_WINDOWS_DPI_AWARENESS"
-
-/**
- * \brief Uses DPI-scaled points as the SDL coordinate system on Windows.
- *
- * This changes the SDL coordinate system units to be DPI-scaled points, rather than pixels everywhere.
- * This means windows will be appropriately sized, even when created on high-DPI displays with scaling.
- *
- * e.g. requesting a 640x480 window from SDL, on a display with 125% scaling in Windows display settings,
- * will create a window with an 800x600 client area (in pixels).
- *
- * Setting this to "1" implicitly requests process DPI awareness (setting SDL_WINDOWS_DPI_AWARENESS is unnecessary),
- * and forces SDL_WINDOW_ALLOW_HIGHDPI on all windows.
- *
- * This variable can be set to the following values:
- * "0" - SDL coordinates equal Windows coordinates. No automatic window resizing when dragging
- * between monitors with different scale factors (unless this is performed by
- * Windows itself, which is the case when the process is DPI unaware).
- * "1" - SDL coordinates are in DPI-scaled points. Automatically resize windows as needed on
- * displays with non-100% scale factors.
- */
-#define SDL_HINT_WINDOWS_DPI_SCALING "SDL_WINDOWS_DPI_SCALING"
-
-/**
- * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
+ * \brief A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
*
* This variable can be set to the following values:
* "0" - The window frame is not interactive when the cursor is hidden (no move, resize, etc)
@@ -2102,7 +2046,7 @@ extern "C" {
#define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN"
/**
-* \brief A variable controlling whether the window is activated when the SDL_ShowWindow function is called
+* \brief A variable controlling whether the window is activated when the SDL_ShowWindow function is called
*
* This variable can be set to the following values:
* "0" - The window is activated when the SDL_ShowWindow function is called
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 23a9f246f525..a2318246d492 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -106,7 +106,7 @@ typedef enum
{
SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window */
SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */
- /* 0x4 was SDL_WINDOW_SHOWN in SDL2, please reserve this bit for sdl2-compat. */
+ /* 0x00000004 was SDL_WINDOW_SHOWN in SDL2, please reserve this bit for sdl2-compat. */
SDL_WINDOW_HIDDEN = 0x00000008, /**< window is not visible */
SDL_WINDOW_BORDERLESS = 0x00000010, /**< no window decoration */
SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */
@@ -117,9 +117,7 @@ typedef enum
SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */
SDL_WINDOW_FULLSCREEN_DESKTOP = ( SDL_WINDOW_FULLSCREEN | 0x00001000 ),
SDL_WINDOW_FOREIGN = 0x00000800, /**< window not created by SDL */
- SDL_WINDOW_ALLOW_HIGHDPI = 0x00002000, /**< window should be created in high-DPI mode if supported.
- On macOS NSHighResolutionCapable must be set true in the
- application's Info.plist for this to have any effect. */
+ /* 0x00002000 was SDL_WINDOW_ALLOW_HIGHDPI in SDL2, please reserve this bit for sdl2-compat. */
SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
SDL_WINDOW_SKIP_TASKBAR = 0x00010000, /**< window should not be added to the taskbar */
@@ -321,7 +319,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
*
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
+extern DECLSPEC const char *SDLCALL SDL_GetDisplayName(int displayIndex);
/**
* Get the desktop area represented by a display.
@@ -337,7 +335,7 @@ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex);
*
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * rect);
+extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rect);
/**
* Get the usable desktop area represented by a display.
@@ -368,7 +366,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * re
* \sa SDL_GetDisplayBounds
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect * rect);
+extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect *rect);
/**
* Get the dots/pixels-per-inch for a display.
@@ -403,7 +401,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
*
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayPhysicalDPI(int displayIndex, float * ddpi, float * hdpi, float * vdpi);
+extern DECLSPEC int SDLCALL SDL_GetDisplayPhysicalDPI(int displayIndex, float *ddpi, float *hdpi, float *vdpi);
/**
* Get the orientation of a display.
@@ -457,8 +455,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
*
* \sa SDL_GetNumDisplayModes
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
- SDL_DisplayMode * mode);
+extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, SDL_DisplayMode *mode);
/**
* Get information about the desktop's display mode.
@@ -480,7 +477,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
* \sa SDL_GetDisplayMode
* \sa SDL_SetWindowDisplayMode
*/
-extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode * mode);
+extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_DisplayMode *mode);
/**
* Get information about the current display mode.
@@ -503,7 +500,7 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp
* \sa SDL_GetNumVideoDisplays
* \sa SDL_SetWindowDisplayMode
*/
-extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode * mode);
+extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode *mode);
/**
@@ -529,7 +526,7 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
* \sa SDL_GetDisplayMode
* \sa SDL_GetNumDisplayModes
*/
-extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode * mode, SDL_DisplayMode * closest);
+extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(int displayIndex, const SDL_DisplayMode *mode, SDL_DisplayMode *closest);
/**
* Get the index of the display containing a point
@@ -543,7 +540,7 @@ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayI
* \sa SDL_GetDisplayBounds
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForPoint(const SDL_Point * point);
+extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForPoint(const SDL_Point *point);
/**
* Get the index of the display primarily containing a rect
@@ -558,7 +555,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForPoint(const SDL_Point * point)
* \sa SDL_GetDisplayBounds
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForRect(const SDL_Rect * rect);
+extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForRect(const SDL_Rect *rect);
/**
* Get the index of the display associated with a window.
@@ -573,7 +570,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForRect(const SDL_Rect * rect);
* \sa SDL_GetDisplayBounds
* \sa SDL_GetNumVideoDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
+extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window *window);
/**
* Set the display mode to use when a window is visible at fullscreen.
@@ -594,8 +591,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window);
* \sa SDL_GetWindowDisplayMode
* \sa SDL_SetWindowFullscreen
*/
-extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
- const SDL_DisplayMode * mode);
+extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window *window, const SDL_DisplayMode *mode);
/**
* Query the display mode to use when a window is visible at fullscreen.
@@ -611,8 +607,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(SDL_Window * window,
* \sa SDL_SetWindowDisplayMode
* \sa SDL_SetWindowFullscreen
*/
-extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
- SDL_DisplayMode * mode);
+extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window *window, SDL_DisplayMode *mode);
/**
* Get the raw ICC profile data for the screen the window is currently on.
@@ -626,7 +621,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window,
*
* \since This function is available since SDL 3.0.0.
*/
-extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_t* size);
+extern DECLSPEC void *SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size);
/**
* Get the pixel format associated with the window.
@@ -638,7 +633,7 @@ extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_
*
* \since This function is available since SDL 3.0.0.
*/
-extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
+extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
/**
* Create a window with the specified position, dimensions, and flags.
@@ -656,22 +651,19 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* - `SDL_WINDOW_MINIMIZED`: window is minimized
* - `SDL_WINDOW_MAXIMIZED`: window is maximized
* - `SDL_WINDOW_INPUT_GRABBED`: window has grabbed input focus
- * - `SDL_WINDOW_ALLOW_HIGHDPI`: window should be created in high-DPI mode if
- * supported (>= SDL 2.0.1)
*
* The SDL_Window is implicitly shown if SDL_WINDOW_HIDDEN is not set.
*
* On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
* property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
*
- * If the window is created with the `SDL_WINDOW_ALLOW_HIGHDPI` flag, its size
- * in pixels may differ from its size in screen coordinates on platforms with
- * high-DPI support (e.g. iOS and macOS). Use SDL_GetWindowSize() to query the
- * client area's size in screen coordinates, and SDL_GetWindowSizeInPixels() or
- * SDL_GetRendererOutputSize() to query the drawable size in pixels. Note that
- * when this flag is set, the drawable size can vary after the window is
- * created and should be queried after major window events such as when the
- * window is resized or moved between displays.
+ * The window size in pixels may differ from its size in screen coordinates if
+ * the window is on a high density display (one with an OS scaling factor).
+ * Use SDL_GetWindowSize() to query the client area's size in screen coordinates,
+ * and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize() to query the
+ * drawable size in pixels. Note that the drawable size can vary after the window
+ * is created and should be queried again when the window is resized or moved
+ * between displays.
*
* If the window is set fullscreen, the width and height parameters `w` and
* `h` will not be used. However, invalid size parameters (e.g. too large) may
@@ -709,9 +701,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window * window);
* \sa SDL_CreateWindowFrom
* \sa SDL_DestroyWindow
*/
-extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
- int x, int y, int w,
- int h, Uint32 flags);
+extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags);
/**
* Create an SDL window from an existing native window.
@@ -730,7 +720,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title,
* \sa SDL_CreateWindow
* \sa SDL_DestroyWindow
*/
-extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
+extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowFrom(const void *data);
/**
* Get the numeric ID of a window.
@@ -746,7 +736,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data);
*
* \sa SDL_GetWindowFromID
*/
-extern DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window * window);
+extern DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window);
/**
* Get a window from a stored ID.
@@ -762,7 +752,7 @@ extern DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window * window);
*
* \sa SDL_GetWindowID
*/
-extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
+extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
/**
* Get the window flags.
@@ -780,7 +770,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
* \sa SDL_SetWindowGrab
* \sa SDL_ShowWindow
*/
-extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
+extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window *window);
/**
* Set the title of a window.
@@ -794,8 +784,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window);
*
* \sa SDL_GetWindowTitle
*/
-extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
- const char *title);
+extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title);
/**
* Get the title of a window.
@@ -808,7 +797,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window,
*
* \sa SDL_SetWindowTitle
*/
-extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
+extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window *window);
/**
* Set the icon for a window.
@@ -818,8 +807,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window * window);
*
* \since This function is available since SDL 3.0.0.
*/
-extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
- SDL_Surface * icon);
+extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon);
/**
* Associate an arbitrary named pointer with a window.
@@ -835,9 +823,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window,
*
* \sa SDL_GetWindowData
*/
-extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
- const char *name,
- void *userdata);
+extern DECLSPEC void *SDLCALL SDL_SetWindowData(SDL_Window *window, const char *name, void *userdata);
/**
* Retrieve the data pointer associated with a window.
@@ -850,101 +836,86 @@ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window,
*
* \sa SDL_SetWindowData
*/
-extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window,
- const char *name);
+extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *name);
/**
- * Set the position of a window.
- *
- * The window coordinate origin is the upper left of the display.
+ * Set the position of a window, in screen coordinates.
*
* \param window the window to reposition
- * \param x the x coordinate of the window in screen coordinates, or
- * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
- * \param y the y coordinate of the window in screen coordinates, or
- * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
+ * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
+ * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetWindowPosition
*/
-extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window,
- int x, int y);
+extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y);
/**
- * Get the position of a window.
+ * Get the position of a window, in screen coordinates.
*
* If you do not need the value for one of the positions a NULL may be passed
* in the `x` or `y` parameter.
*
* \param window the window to query
- * \param x a pointer filled in with the x position of the window, in screen
- * coordinates, may be NULL
- * \param y a pointer filled in with the y position of the window, in screen
- * coordinates, may be NULL
+ * \param x a pointer filled in with the x position of the window, may be NULL
+ * \param y a pointer filled in with the y position of the window, may be NULL
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowPosition
*/
-extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window,
- int *x, int *y);
+extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y);
/**
- * Set the size of a window's client area.
+ * Set the size of a window's client area, in screen coordinates.
*
- * The window size in screen coordinates may differ from the size in pixels,
- * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
- * with high-dpi support (e.g. iOS or macOS). Use SDL_GL_GetDrawableSize() or
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
+ * The window size in screen coordinates may differ from the size in pixels if
+ * the window is on a high density display (one with an OS scaling factor).
*
* Fullscreen windows automatically match the size of the display mode, and
* you should use SDL_SetWindowDisplayMode() to change their size.
*
* \param window the window to change
- * \param w the width of the window in pixels, in screen coordinates, must be
- * > 0
- * \param h the height of the window in pixels, in screen coordinates, must be
- * > 0
+ * \param w the width of the window, must be > 0
+ * \param h the height of the window, must be > 0
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetWindowSize
* \sa SDL_SetWindowDisplayMode
*/
-extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w,
- int h);
+extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h);
/**
- * Get the size of a window's client area.
+ * Get the size of a window's client area, in screen coordinates.
*
* NULL can safely be passed as the `w` or `h` parameter if the width or
* height value is not desired.
*
- * The window size in screen coordinates may differ from the size in pixels,
- * if the window was created with `SDL_WINDOW_ALLOW_HIGHDPI` on a platform
- * with high-dpi support (e.g. iOS or macOS). Use SDL_GetWindowSizeInPixels(),
- * SDL_GL_GetDrawableSize(), SDL_Vulkan_GetDrawableSize(), or
- * SDL_GetRendererOutputSize() to get the real client area size in pixels.
+ * The window size in screen coordinates may differ from the size in pixels if
+ * the window is on a high density display (one with an OS scaling factor).
+ * Use SDL_GetWindowSizeInPixels(), SDL_GL_GetDrawableSize(),
+ * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() 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, in screen
- * coordinates, may be NULL
- * \param h a pointer filled in with the height of the window, in screen
- * coordinates, may be NULL
+ * \param w a pointer filled i
(Patch may be truncated, please check the link at the top of this post.)