SDL: Displays are now referenced by instance ID instead of index

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