From 22c69bccdf18d6c5c0990de9bc89e5e76d3a7c50 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Sun, 29 Jan 2023 13:30:55 -0800
Subject: [PATCH] Displays are now referenced by instance ID instead of index
---
build-scripts/SDL_migration.cocci | 9 +-
docs/README-migration.md | 32 +-
docs/README-winrt.md | 2 +-
include/SDL3/SDL_events.h | 2 +-
include/SDL3/SDL_oldnames.h | 10 +-
include/SDL3/SDL_system.h | 22 +-
include/SDL3/SDL_video.h | 139 +++---
src/core/android/SDL_android.c | 8 +-
src/core/windows/SDL_windows.c | 9 +-
src/core/winrt/SDL_winrtapp_direct3d.cpp | 4 +-
src/dynapi/SDL_dynapi.sym | 9 +-
src/dynapi/SDL_dynapi_overrides.h | 9 +-
src/dynapi/SDL_dynapi_procs.h | 33 +-
src/events/SDL_displayevents.c | 2 +-
src/events/SDL_events.c | 2 +-
src/events/SDL_windowevents.c | 4 +-
src/render/SDL_render.c | 8 +-
src/render/direct3d/SDL_render_d3d.c | 6 +-
src/test/SDL_test_common.c | 123 +++--
src/video/SDL_egl_c.h | 19 +-
src/video/SDL_shape.c | 30 +-
src/video/SDL_sysvideo.h | 61 ++-
src/video/SDL_video.c | 446 ++++++++++--------
src/video/android/SDL_androidevents.c | 8 +-
src/video/android/SDL_androidgl.c | 6 +-
src/video/android/SDL_androidkeyboard.c | 4 +-
src/video/android/SDL_androidvideo.c | 12 +-
src/video/android/SDL_androidvideo.h | 4 +-
src/video/android/SDL_androidvulkan.c | 2 +-
src/video/android/SDL_androidwindow.c | 6 +-
src/video/android/SDL_androidwindow.h | 4 +-
src/video/cocoa/SDL_cocoaclipboard.m | 2 +-
src/video/cocoa/SDL_cocoaevents.m | 6 +-
src/video/cocoa/SDL_cocoakeyboard.m | 12 +-
src/video/cocoa/SDL_cocoamessagebox.m | 2 +-
src/video/cocoa/SDL_cocoametalview.m | 2 +-
src/video/cocoa/SDL_cocoamodes.h | 8 +-
src/video/cocoa/SDL_cocoamodes.m | 10 +-
src/video/cocoa/SDL_cocoamouse.m | 8 +-
src/video/cocoa/SDL_cocoaopengl.m | 10 +-
src/video/cocoa/SDL_cocoaopengles.m | 10 +-
src/video/cocoa/SDL_cocoashape.m | 4 +-
src/video/cocoa/SDL_cocoavideo.m | 10 +-
src/video/cocoa/SDL_cocoavulkan.m | 2 +-
src/video/cocoa/SDL_cocoawindow.h | 2 +-
src/video/cocoa/SDL_cocoawindow.m | 91 ++--
src/video/emscripten/SDL_emscriptenevents.c | 2 +-
src/video/emscripten/SDL_emscriptenevents.h | 11 +-
.../emscripten/SDL_emscriptenframebuffer.c | 6 +-
src/video/emscripten/SDL_emscriptenmouse.c | 2 +-
src/video/emscripten/SDL_emscriptenopengles.c | 8 +-
src/video/emscripten/SDL_emscriptenvideo.c | 8 +-
src/video/emscripten/SDL_emscriptenvideo.h | 4 +-
src/video/haiku/SDL_bvideo.cc | 5 +-
src/video/kmsdrm/SDL_kmsdrmmouse.c | 45 +-
src/video/kmsdrm/SDL_kmsdrmopengles.c | 8 +-
src/video/kmsdrm/SDL_kmsdrmvideo.c | 98 ++--
src/video/kmsdrm/SDL_kmsdrmvideo.h | 16 +-
src/video/kmsdrm/SDL_kmsdrmvulkan.c | 2 +-
src/video/n3ds/SDL_n3dsframebuffer.c | 2 +-
src/video/n3ds/SDL_n3dsvideo.c | 12 +-
src/video/n3ds/SDL_n3dsvideo.h | 5 +-
src/video/ngage/SDL_ngageevents.cpp | 4 +-
src/video/ngage/SDL_ngageframebuffer.cpp | 10 +-
src/video/ngage/SDL_ngagevideo.cpp | 2 +-
src/video/ngage/SDL_ngagevideo.h | 4 +-
src/video/ngage/SDL_ngagewindow.cpp | 4 +-
src/video/offscreen/SDL_offscreenopengles.c | 6 +-
src/video/offscreen/SDL_offscreenwindow.c | 4 +-
src/video/offscreen/SDL_offscreenwindow.h | 9 +-
src/video/psp/SDL_pspgl.c | 4 +-
src/video/psp/SDL_pspvideo.c | 7 +-
src/video/psp/SDL_pspvideo.h | 13 +-
src/video/raspberry/SDL_rpimouse.c | 8 +-
src/video/raspberry/SDL_rpiopengles.c | 2 +-
src/video/raspberry/SDL_rpivideo.c | 11 +-
src/video/raspberry/SDL_rpivideo.h | 13 +-
src/video/riscos/SDL_riscosevents.c | 8 +-
src/video/riscos/SDL_riscosframebuffer.c | 8 +-
src/video/riscos/SDL_riscosvideo.h | 4 +-
src/video/riscos/SDL_riscoswindow.c | 2 +-
src/video/riscos/SDL_riscoswindow.h | 4 +-
src/video/uikit/SDL_uikitappdelegate.m | 2 +-
src/video/uikit/SDL_uikitclipboard.m | 4 +-
src/video/uikit/SDL_uikitmessagebox.m | 2 +-
src/video/uikit/SDL_uikitmetalview.m | 2 +-
src/video/uikit/SDL_uikitmodes.m | 38 +-
src/video/uikit/SDL_uikitopengles.m | 2 +-
src/video/uikit/SDL_uikitvideo.m | 8 +-
src/video/uikit/SDL_uikitview.m | 4 +-
src/video/uikit/SDL_uikitviewcontroller.m | 4 +-
src/video/uikit/SDL_uikitwindow.m | 39 +-
src/video/vita/SDL_vitaframebuffer.c | 4 +-
src/video/vita/SDL_vitagl_pvr.c | 2 +-
src/video/vita/SDL_vitagles.c | 4 +-
src/video/vita/SDL_vitagles_pvr.c | 12 +-
src/video/vita/SDL_vitavideo.c | 14 +-
src/video/vita/SDL_vitavideo.h | 13 +-
src/video/vivante/SDL_vivanteopengles.c | 4 +-
src/video/vivante/SDL_vivantevideo.c | 16 +-
src/video/vivante/SDL_vivantevideo.h | 12 +-
src/video/wayland/SDL_waylandmouse.c | 6 +-
src/video/wayland/SDL_waylandopengles.c | 20 +-
src/video/wayland/SDL_waylandtouch.c | 2 +-
src/video/wayland/SDL_waylandvideo.c | 126 +++--
src/video/wayland/SDL_waylandvideo.h | 14 +-
src/video/wayland/SDL_waylandvulkan.c | 2 +-
src/video/wayland/SDL_waylandwindow.c | 125 ++---
src/video/wayland/SDL_waylandwindow.h | 6 +-
src/video/windows/SDL_windowsclipboard.c | 4 +-
src/video/windows/SDL_windowsevents.c | 14 +-
src/video/windows/SDL_windowsframebuffer.c | 6 +-
src/video/windows/SDL_windowskeyboard.c | 18 +-
src/video/windows/SDL_windowsmessagebox.c | 4 +-
src/video/windows/SDL_windowsmodes.c | 68 +--
src/video/windows/SDL_windowsmodes.h | 8 +-
src/video/windows/SDL_windowsmouse.c | 6 +-
src/video/windows/SDL_windowsopengl.c | 12 +-
src/video/windows/SDL_windowsopengles.c | 6 +-
src/video/windows/SDL_windowsshape.c | 2 +-
src/video/windows/SDL_windowsvideo.c | 29 +-
src/video/windows/SDL_windowsvideo.h | 4 +-
src/video/windows/SDL_windowsvulkan.c | 2 +-
src/video/windows/SDL_windowswindow.c | 69 ++-
src/video/windows/SDL_windowswindow.h | 4 +-
src/video/winrt/SDL_winrtgamebar.cpp | 4 +-
src/video/winrt/SDL_winrtopengles.cpp | 4 +-
src/video/winrt/SDL_winrtpointerinput.cpp | 2 +-
src/video/winrt/SDL_winrtvideo.cpp | 22 +-
src/video/winrt/SDL_winrtvideo_cpp.h | 4 +-
src/video/x11/SDL_x11clipboard.c | 10 +-
src/video/x11/SDL_x11events.c | 28 +-
src/video/x11/SDL_x11framebuffer.c | 6 +-
src/video/x11/SDL_x11keyboard.c | 18 +-
src/video/x11/SDL_x11messagebox.c | 7 +-
src/video/x11/SDL_x11modes.c | 46 +-
src/video/x11/SDL_x11modes.h | 8 +-
src/video/x11/SDL_x11mouse.c | 68 +--
src/video/x11/SDL_x11opengl.c | 29 +-
src/video/x11/SDL_x11opengles.c | 6 +-
src/video/x11/SDL_x11shape.c | 2 +-
src/video/x11/SDL_x11video.c | 8 +-
src/video/x11/SDL_x11video.h | 4 +-
src/video/x11/SDL_x11vulkan.c | 10 +-
src/video/x11/SDL_x11window.c | 105 ++---
src/video/x11/SDL_x11window.h | 4 +-
src/video/x11/SDL_x11xfixes.c | 14 +-
src/video/x11/SDL_x11xinput2.c | 12 +-
test/testautomation_video.c | 415 ++++++++--------
test/testbounds.c | 24 +-
test/testdisplayinfo.c | 11 +-
test/testgl.c | 2 +-
test/testgles.c | 2 +-
test/testgles2.c | 2 +-
test/testgles2_sdf.c | 2 +-
test/testvulkan.c | 2 +-
test/testwm.c | 12 +-
157 files changed, 1621 insertions(+), 1590 deletions(-)
diff --git a/build-scripts/SDL_migration.cocci b/build-scripts/SDL_migration.cocci
index 9d22580de925..feaf0c9b0816 100644
--- a/build-scripts/SDL_migration.cocci
+++ b/build-scripts/SDL_migration.cocci
@@ -1993,12 +1993,12 @@ typedef SDL_GameControllerButtonBind, SDL_GamepadBinding;
@@
@@
- SDL_GetPointDisplayIndex
-+ SDL_GetDisplayIndexForPoint
++ SDL_GetDisplayForPoint
(...)
@@
@@
- SDL_GetRectDisplayIndex
-+ SDL_GetDisplayIndexForRect
++ SDL_GetDisplayForRect
(...)
@ depends on rule_init_noparachute @
expression e;
@@ -2354,3 +2354,8 @@ SDL_DisplayMode e;
- e.h
+ e.screen_h
)
+@@
+@@
+- SDL_GetWindowDisplayIndex
++ SDL_GetDisplayForWindow
+ (...)
diff --git a/docs/README-migration.md b/docs/README-migration.md
index 4b0ee7e2f41d..66bf8e51332b 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -444,7 +444,7 @@ The following functions have been removed:
* SDL_JoystickGetDeviceVendor() - replaced with SDL_GetJoystickInstanceVendor()
* SDL_JoystickNameForIndex() - replaced with SDL_GetJoystickInstanceName()
* SDL_JoystickPathForIndex() - replaced with SDL_GetJoystickInstancePath()
-* SDL_NumJoysticks - replaced with SDL_GetJoysticks()
+* SDL_NumJoysticks() - replaced with SDL_GetJoysticks()
## SDL_keyboard.h
@@ -958,6 +958,28 @@ SDL_GetRevisionNumber() has been removed from the API, it always returned 0 in S
SDL_VideoInit() and SDL_VideoQuit() have been removed. Instead you can call SDL_InitSubSytem() and SDL_QuitSubSytem() with SDL_INIT_VIDEO, which will properly refcount the subsystems. You can choose a specific audio driver using SDL_VIDEO_DRIVER hint.
+Rather than iterating over displays using display index, there is a new function SDL_GetDisplays() to get the current list of displays, and functions which used to take a display index now take SDL_DisplayID, with an invalid ID being 0.
+```c
+{
+ if (SDL_InitSubSystem(SDL_INIT_VIDEO) == 0) {
+ int i, num_displays;
+ SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
+ if (displays) {
+ for (i = 0; i < num_displays; ++i) {
+ SDL_DisplayID instance_id = displays[i];
+ const char *name = SDL_GetDisplayName(instance_id);
+
+ SDL_Log("Display %" SDL_PRIu32 ": %s\n", instance_id, name ? name : "Unknown");
+ }
+ SDL_free(displays);
+ }
+ SDL_QuitSubSystem(SDL_INIT_VIDEO);
+ }
+}
+```
+
+The SDL_WINDOWPOS_UNDEFINED_DISPLAY() and SDL_WINDOWPOS_CENTERED_DISPLAY() macros take a display ID instead of display index. The display ID 0 has a special meaning in this case, and is used to indicate the primary display.
+
The SDL_WINDOW_SHOWN flag has been removed. Windows are shown by default and can be created hidden by using the SDL_WINDOW_HIDDEN flag.
The SDL_WINDOW_ALLOW_HIGHDPI flag has been removed. Windows are automatically high DPI aware and their coordinates are in screen space, which may differ from physical pixels on displays using display scaling.
@@ -982,8 +1004,12 @@ SDL_GL_GetDrawableSize() has been removed. SDL_GetWindowSizeInPixels() can be us
The following functions have been renamed:
* SDL_GetDisplayDPI() => SDL_GetDisplayPhysicalDPI()
-* SDL_GetPointDisplayIndex() => SDL_GetDisplayIndexForPoint()
-* SDL_GetRectDisplayIndex() => SDL_GetDisplayIndexForRect()
+* SDL_GetPointDisplayIndex() => SDL_GetDisplayForPoint()
+* SDL_GetRectDisplayIndex() => SDL_GetDisplayForRect()
+* SDL_GetWindowDisplayIndex() => SDL_GetDisplayForWindow()
+
+The following functions have been removed:
+* SDL_GetNumVideoDisplays() - replaced with SDL_GetDisplays()
SDL_Window id type is named SDL_WindowID
diff --git a/docs/README-winrt.md b/docs/README-winrt.md
index 8f7bbbe3fb45..7d26fbf5d71e 100644
--- a/docs/README-winrt.md
+++ b/docs/README-winrt.md
@@ -341,7 +341,7 @@ int main(int argc, char **argv)
if (SDL_Init(SDL_INIT_VIDEO) != 0) {
return 1;
- } else if (SDL_GetCurrentDisplayMode(0, &mode) != 0) {
+ } else if (SDL_GetCurrentDisplayMode(SDL_GetPrimaryDisplay(), &mode) != 0) {
return 1;
} else if (SDL_CreateWindowAndRenderer(mode.w, mode.h, SDL_WINDOW_FULLSCREEN_EXCLUSIVE, &window, &renderer) != 0) {
return 1;
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 89bfaceda38a..e5b0ceaeb344 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -215,7 +215,7 @@ typedef struct SDL_DisplayEvent
{
Uint32 type; /**< ::SDL_DISPLAYEVENT_* */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
- Uint32 display; /**< The associated display index */
+ SDL_DisplayID displayID;/**< The associated display */
Sint32 data1; /**< event dependent data */
} SDL_DisplayEvent;
diff --git a/include/SDL3/SDL_oldnames.h b/include/SDL3/SDL_oldnames.h
index 23fb15632cb9..f84b8e0df3e3 100644
--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -413,8 +413,9 @@
/* ##SDL_video.h */
#define SDL_GetDisplayDPI SDL_GetDisplayPhysicalDPI
-#define SDL_GetPointDisplayIndex SDL_GetDisplayIndexForPoint
-#define SDL_GetRectDisplayIndex SDL_GetDisplayIndexForRect
+#define SDL_GetPointDisplayIndex SDL_GetDisplayForPoint
+#define SDL_GetRectDisplayIndex SDL_GetDisplayForRect
+#define SDL_GetWindowDisplayIndex SDL_GetDisplayForWindow
#define SDL_WINDOW_FULLSCREEN SDL_WINDOW_FULLSCREEN_EXCLUSIVE
#define SDL_WINDOW_INPUT_GRABBED SDL_WINDOW_MOUSE_GRABBED
@@ -795,8 +796,9 @@
/* ##SDL_video.h */
#define SDL_GetDisplayDPI SDL_GetDisplayDPI_renamed_SDL_GetDisplayPhysicalDPI
-#define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayIndexForPoint
-#define SDL_GetRectDisplayIndex SDL_GetRectDisplayIndex_renamed_SDL_GetDisplayIndexForRect
+#define SDL_GetPointDisplayIndex SDL_GetPointDisplayIndex_renamed_SDL_GetDisplayForPoint
+#define SDL_GetRectDisplayIndex SDL_GetRectDisplayIndex_renamed_SDL_GetDisplayForRect
+#define SDL_GetWindowDisplayIndex SDL_GetWindowDisplayIndex_renamed_SDL_GetDisplayForWindow
#define SDL_WINDOW_FULLSCREEN SDL_WINDOW_FULLSCREEN_renamed_SDL_WINDOW_FULLSCREEN_EXCLUSIVE
#define SDL_WINDOW_INPUT_GRABBED SDL_WINDOW_INPUT_GRABBED_renamed_SDL_WINDOW_MOUSE_GRABBED
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index ab482396f25f..7c13f5af827e 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -42,7 +42,7 @@ extern "C" {
/* Platform specific functions for Windows */
#if defined(__WIN32__) || defined(__GDK__)
-
+
typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
/**
@@ -60,19 +60,18 @@ extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook ca
#if defined(__WIN32__) || defined(__WINGDK__)
/**
- * Get the D3D9 adapter index that matches the specified display index.
+ * Get the D3D9 adapter index that matches the specified display.
*
* The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
* controls on which monitor a full screen application will appear.
*
- * \param displayIndex the display index for which to get the D3D9 adapter
- * index
+ * \param displayID the instance of the display to query
* \returns the D3D9 adapter index on success or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
-extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex( int displayIndex );
+extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex(SDL_DisplayID displayID);
typedef struct IDirect3DDevice9 IDirect3DDevice9;
@@ -131,16 +130,13 @@ extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* ren
#if defined(__WIN32__) || defined(__WINGDK__)
/**
- * Get the DXGI Adapter and Output indices for the specified display index.
+ * Get the DXGI Adapter and Output indices for the specified display.
*
* The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
* `EnumOutputs` respectively to get the objects required to create a DX10 or
* DX11 device and swap chain.
*
- * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it
- * returns an SDL_bool.
- *
- * \param displayIndex the display index for which to get both indices
+ * \param displayID the instance of the display to query
* \param adapterIndex a pointer to be filled in with the adapter index
* \param outputIndex a pointer to be filled in with the output index
* \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
@@ -148,7 +144,7 @@ extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* ren
*
* \since This function is available since SDL 3.0.0.
*/
-extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo( int displayIndex, int *adapterIndex, int *outputIndex );
+extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex);
#endif /* defined(__WIN32__) || defined(__WINGDK__) */
@@ -182,9 +178,9 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
-
+
#endif /* __LINUX__ */
-
+
/* Platform specific functions for iOS */
#ifdef __IOS__
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 1d8255abb679..f33c89f15683 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -40,6 +40,7 @@ extern "C" {
#endif
+typedef Uint32 SDL_DisplayID;
typedef Uint32 SDL_WindowID;
/**
@@ -300,53 +301,61 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
/**
- * Get the number of available video displays.
+ * Get a list of currently connected displays.
*
- * \returns a number >= 1 or a negative error code on failure; call
- * SDL_GetError() for more information.
+ * \param count a pointer filled in with the number of displays returned
+ * \returns a 0 terminated array of display instance IDs which should be
+ * freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ * more details.
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC SDL_DisplayID *SDLCALL SDL_GetDisplays(int *count);
+
+/**
+ * Return the primary display.
+ *
+ * \returns the instance ID of the primary display on success or 0 on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_GetDisplayBounds
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void);
+extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
/**
* Get the name of a display in UTF-8 encoding.
*
- * \param displayIndex the index of display from which the name should be
- * queried
- * \returns the name of a display or NULL for an invalid display index or
- * failure; call SDL_GetError() for more information.
+ * \param displayID the instance ID of the display to query
+ * \returns the name of a display or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC const char *SDLCALL SDL_GetDisplayName(int displayIndex);
+extern DECLSPEC const char *SDLCALL SDL_GetDisplayName(SDL_DisplayID displayID);
/**
* Get the desktop area represented by a display, in screen coordinates.
*
- * The primary display (`displayIndex` zero) is always located at 0,0.
+ * The primary display is always located at (0,0).
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \param rect the SDL_Rect structure filled in with the display bounds
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplayUsableBounds
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rect);
+extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect);
/**
* Get the usable desktop area represented by a display, in screen
* coordinates.
*
- * The primary display (`displayIndex` zero) is always located at 0,0.
- *
* This is the same area as SDL_GetDisplayBounds() reports, but with portions
* reserved by the system removed. For example, on Apple's macOS, this
* subtracts the area occupied by the menu bar and dock.
@@ -355,13 +364,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rec
* so these are good guidelines for the maximum space available to a
* non-fullscreen window.
*
- * The parameter `rect` is ignored if it is NULL.
- *
- * This function also returns -1 if the parameter `displayIndex` is out of
- * range.
- *
- * \param displayIndex the index of the display to query the usable bounds
- * from
+ * \param displayID the instance ID of the display to query
* \param rect the SDL_Rect structure filled in with the display bounds
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
@@ -369,9 +372,9 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rec
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetDisplayBounds
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rect *rect);
+extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect);
/**
* Get the dots/pixels-per-inch for a display.
@@ -379,9 +382,6 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
* Diagonal, horizontal and vertical DPI can all be optionally returned if the
* appropriate parameter is non-NULL.
*
- * A failure of this function usually means that either no DPI information is
- * available or the `displayIndex` is out of range.
- *
* **WARNING**: This reports the DPI that the hardware reports, and it is not
* always reliable! It is almost always better to use SDL_GetWindowSize() to
* find the window size, which might be in logical points instead of pixels,
@@ -390,8 +390,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
* will be rethinking how high-dpi details should be managed in SDL3 to make
* things more consistent, reliable, and clear.
*
- * \param displayIndex the index of the display from which DPI information
- * should be queried
+ * \param displayID the instance ID of the display to query
* \param ddpi a pointer filled in with the diagonal DPI of the display; may
* be NULL
* \param hdpi a pointer filled in with the horizontal DPI of the display; may
@@ -403,53 +402,51 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayPhysicalDPI(int displayIndex, float *ddpi, float *hdpi, float *vdpi);
+extern DECLSPEC int SDLCALL SDL_GetDisplayPhysicalDPI(SDL_DisplayID displayID, float *ddpi, float *hdpi, float *vdpi);
/**
* Get the orientation of a display.
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \returns The SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available.
*
* \since This function is available since SDL 3.0.0.
*
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int displayIndex);
+extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_DisplayID displayID);
/**
* Get the number of available display modes.
*
- * The `displayIndex` needs to be in the range from 0 to
- * SDL_GetNumVideoDisplays() - 1.
- *
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \returns a number >= 1 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetDisplayMode
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex);
+extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(SDL_DisplayID displayID);
/**
* Get information about a specific display mode.
*
* The display modes are sorted in this priority:
*
- * - width -> largest to smallest
- * - height -> largest to smallest
- * - display_scale -> smallest to largest
+ * - screen_w -> largest to smallest
+ * - screen_h -> largest to smallest
+ * - pixel_w -> largest to smallest
+ * - pixel_h -> largest to smallest
* - bits per pixel -> more colors to fewer colors
* - packed pixel layout -> largest to smallest
* - refresh rate -> highest to lowest
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \param modeIndex the index of the display mode to query
* \param mode an SDL_DisplayMode structure filled in with the mode at
* `modeIndex`
@@ -460,7 +457,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(SDL_DisplayID displayID, int modeIndex, SDL_DisplayMode *mode);
/**
* Get information about the desktop's display mode.
@@ -470,7 +467,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex,
* function will return the previous native display mode, and not the current
* display mode.
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \param mode an SDL_DisplayMode structure filled in with the current display
* mode
* \returns 0 on success or a negative error code on failure; call
@@ -482,7 +479,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(SDL_DisplayID displayID, SDL_DisplayMode *mode);
/**
* Get information about the current display mode.
@@ -492,7 +489,7 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp
* function will return the current display mode, and not the previous native
* display mode.
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \param mode an SDL_DisplayMode structure filled in with the current display
* mode
* \returns 0 on success or a negative error code on failure; call
@@ -502,11 +499,10 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp
*
* \sa SDL_GetDesktopDisplayMode
* \sa SDL_GetDisplayMode
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
* \sa SDL_SetWindowDisplayMode
*/
-extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_DisplayMode *mode);
-
+extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayID displayID, SDL_DisplayMode *mode);
/**
* Get the closest match to the requested display mode.
@@ -518,9 +514,9 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp
* and finally checking the refresh rate. If all the available modes are too
* small, then NULL is returned.
*
- * \param displayIndex the index of the display to query
+ * \param displayID the instance ID of the display to query
* \param mode an SDL_DisplayMode structure containing the desired display
- * mode
+ * mode, should be zero initialized
* \param closest an SDL_DisplayMode structure filled in with the closest
* match of the available display modes
* \returns the passed in value `closest` or NULL if no matching video mode
@@ -531,51 +527,48 @@ 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(SDL_DisplayID displayID, const SDL_DisplayMode *mode, SDL_DisplayMode *closest);
/**
- * Get the index of the display containing a point
+ * Get the display containing a point
*
* \param point the point to query
- * \returns the index of the display containing the point or a negative error
- * code on failure; call SDL_GetError() for more information.
+ * \returns the instance ID of the display containing the point or 0 on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetDisplayBounds
- * \sa SDL_GetNumVideoDisplays
+ * \sa SDL_GetDisplays
*/
-extern DECLSPEC int SDLCALL SDL_GetDisplayIndexForPoint(const SDL_Point *point);
+extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point *point);
/**
- * Get the index of the display primarily containing a rect
+ * Get the display primarily containing a rect
*
* \param rect the rect to query
- * \returns the index of the display entirely containing the rect or closest
- * to the center of the rect on success or a negative error code on
- * failure; call SDL_GetError() for more information.
+ * \returns the instance ID of the display ent
(Patch may be truncated, please check the link at the top of this post.)