SDL_GetDisplays() follows the SDL_GetStringRule

docs/README-migration.md

@@ -1970,7 +1970,7 @@ Rather than iterating over displays using display index, there is a new function
 {
     if (SDL_InitSubSystem(SDL_INIT_VIDEO) == 0) {
         int i, num_displays = 0;
-        SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
+        const SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
         if (displays) {
             for (i = 0; i < num_displays; ++i) {
                 SDL_DisplayID instance_id = displays[i];
@@ -1978,7 +1978,6 @@ Rather than iterating over displays using display index, there is a new function
 
                 SDL_Log("Display %" SDL_PRIu32 ": %s\n", instance_id, name ? name : "Unknown");
             }
-            SDL_free(displays);
         }
         SDL_QuitSubSystem(SDL_INIT_VIDEO);
     }

include/SDL3/SDL_video.h

@@ -391,15 +391,16 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
 /**
  * Get a list of currently connected displays.
  *
+ * The returned array follows the SDL_GetStringRule, and will be automatically freed later.
+ *
  * \param count a pointer filled in with the number of displays returned, may
  *              be NULL.
- * \returns a 0 terminated array of display instance IDs which should be freed
+ * \returns a 0 terminated array of display instance IDs or NULL on failure; call SDL_GetError() for more
- *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
  *          information.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
+extern SDL_DECLSPEC const SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
 
 /**
  * Return the primary display.

src/dynapi/SDL_dynapi_procs.h

@@ -265,7 +265,7 @@ SDL_DYNAPI_PROC(SDL_DisplayID,SDL_GetDisplayForWindow,(SDL_Window *a),(a),return
 SDL_DYNAPI_PROC(const char*,SDL_GetDisplayName,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetDisplayProperties,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetDisplayUsableBounds,(SDL_DisplayID a, SDL_Rect *b),(a,b),return)
-SDL_DYNAPI_PROC(SDL_DisplayID*,SDL_GetDisplays,(int *a),(a),return)
+SDL_DYNAPI_PROC(const SDL_DisplayID*,SDL_GetDisplays,(int *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetError,(void),(),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GetEventFilter,(SDL_EventFilter *a, void **b),(a,b),return)
 SDL_DYNAPI_PROC(float,SDL_GetFloatProperty,(SDL_PropertiesID a, const char *b, float c),(a,b,c),return)

src/test/SDL_test_common.c

@@ -1192,7 +1192,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state)
         }
 
         if (state->verbose & VERBOSE_MODES) {
-            SDL_DisplayID *displays;
+            const SDL_DisplayID *displays;
             SDL_Rect bounds, usablebounds;
             const SDL_DisplayMode **modes;
             const SDL_DisplayMode *mode;
@@ -1270,7 +1270,6 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state)
                 SDL_Log("DXGI Adapter Index: %d  Output Index: %d", adapterIndex, outputIndex);
 #endif
             }
-            SDL_free(displays);
         }
 
         if (state->verbose & VERBOSE_RENDER) {
@@ -1287,11 +1286,10 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state)
 
         state->displayID = SDL_GetPrimaryDisplay();
         if (state->display_index > 0) {
-            SDL_DisplayID *displays = SDL_GetDisplays(&n);
+            const SDL_DisplayID *displays = SDL_GetDisplays(&n);
             if (state->display_index < n) {
                 state->displayID = displays[state->display_index];
             }
-            SDL_free(displays);
 
             if (SDL_WINDOWPOS_ISUNDEFINED(state->window_x)) {
                 state->window_x = SDL_WINDOWPOS_UNDEFINED_DISPLAY(state->displayID);
@@ -2021,7 +2019,7 @@ static void SDLTest_PasteScreenShot(void)
 static void FullscreenTo(SDLTest_CommonState *state, int index, int windowId)
 {
     int num_displays;
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     SDL_Window *window;
     SDL_WindowFlags flags;
     const SDL_DisplayMode *mode;
@@ -2062,7 +2060,6 @@ static void FullscreenTo(SDLTest_CommonState *state, int index, int windowId)
             SDL_SetWindowFullscreen(window, SDL_TRUE);
         }
     }
-    SDL_free(displays);
 }
 
 int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event)
@@ -2158,7 +2155,7 @@ int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event
                 SDL_Window *window = SDL_GetWindowFromID(event->key.windowID);
                 if (window) {
                     int num_displays;
-                    SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
+                    const SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
                     if (displays) {
                         SDL_DisplayID displayID = SDL_GetDisplayForWindow(window);
                         int current_index = -1;
@@ -2181,7 +2178,6 @@ int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event
                                                   SDL_WINDOWPOS_CENTERED_DISPLAY(dest),
                                                   SDL_WINDOWPOS_CENTERED_DISPLAY(dest));
                         }
-                        SDL_free(displays);
                     }
                 }
             }

src/video/SDL_video.c

@@ -699,7 +699,7 @@ static void SDL_UpdateDesktopBounds(void)
     SDL_Rect rect;
     SDL_zero(rect);
 
-    SDL_DisplayID *displays = SDL_GetDisplays(NULL);
+    const SDL_DisplayID *displays = SDL_GetDisplays(NULL);
     if (displays) {
         for (int i = 0; displays[i]; ++i) {
             SDL_Rect bounds;
@@ -711,7 +711,6 @@ static void SDL_UpdateDesktopBounds(void)
                 }
             }
         }
-        SDL_free(displays);
     }
     SDL_copyp(&_this->desktop_bounds, &rect);
 }
@@ -850,7 +849,7 @@ void SDL_DelVideoDisplay(SDL_DisplayID displayID, SDL_bool send_event)
     SDL_UpdateDesktopBounds();
 }
 
-SDL_DisplayID *SDL_GetDisplays(int *count)
+const SDL_DisplayID *SDL_GetDisplays(int *count)
 {
     int i;
     SDL_DisplayID *displays;
@@ -879,7 +878,7 @@ SDL_DisplayID *SDL_GetDisplays(int *count)
             *count = 0;
         }
     }
-    return displays;
+    return SDL_FreeLater(displays);
 }
 
 SDL_VideoDisplay *SDL_GetVideoDisplay(SDL_DisplayID displayID)

src/video/kmsdrm/SDL_kmsdrmmouse.c

@@ -315,14 +315,13 @@ static int KMSDRM_ShowCursor(SDL_Cursor *cursor)
            This happens on video quit, where we get here after
            the mouse focus has been unset, yet SDL wants to
            restore the system default cursor (makes no sense here). */
-        SDL_DisplayID *displays = SDL_GetDisplays(NULL);
+        const SDL_DisplayID *displays = SDL_GetDisplays(NULL);
         if (displays) {
             /* Iterate on the displays, hiding the cursor. */
             for (i = 0; i < displays[i]; i++) {
                 display = SDL_GetVideoDisplay(displays[i]);
                 ret = KMSDRM_RemoveCursorFromBO(display);
             }
-            SDL_free(displays);
         }
     } else {
         display = SDL_GetVideoDisplayForWindow(window);

src/video/kmsdrm/SDL_kmsdrmvideo.c

@@ -535,7 +535,7 @@ static drmModeModeInfo *KMSDRM_GetClosestDisplayMode(SDL_VideoDisplay *display,
 /* Deinitializes the internal of the SDL Displays in the SDL display list. */
 static void KMSDRM_DeinitDisplays(SDL_VideoDevice *_this)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     SDL_DisplayData *dispdata;
     int i;
 
@@ -559,7 +559,6 @@ static void KMSDRM_DeinitDisplays(SDL_VideoDevice *_this)
                 dispdata->crtc = NULL;
             }
         }
-        SDL_free(displays);
     }
 }
 

src/video/uikit/SDL_uikitmodes.m

@@ -310,7 +310,7 @@ int UIKit_AddDisplay(SDL_bool send_event){
 
 void UIKit_DelDisplay(UIScreen *uiscreen, SDL_bool send_event)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     int i;
 
     displays = SDL_GetDisplays(NULL);
@@ -326,7 +326,6 @@ void UIKit_DelDisplay(UIScreen *uiscreen, SDL_bool send_event)
                 break;
             }
         }
-        SDL_free(displays);
     }
 }
 

src/video/wayland/SDL_waylandwindow.c

@@ -516,7 +516,7 @@ static void Wayland_move_window(SDL_Window *window)
 {
     SDL_WindowData *wind = window->internal;
     SDL_DisplayData *display;
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
 
     if (wind->outputs && wind->num_outputs) {
         display = wind->outputs[wind->num_outputs - 1];
@@ -559,7 +559,6 @@ static void Wayland_move_window(SDL_Window *window)
                 break;
             }
         }
-        SDL_free(displays);
     }
 }
 

src/video/x11/SDL_x11modes.c

@@ -639,7 +639,7 @@ static int X11_AddXRandRDisplay(SDL_VideoDevice *_this, Display *dpy, int screen
 
 static void X11_HandleXRandROutputChange(SDL_VideoDevice *_this, const XRROutputChangeNotifyEvent *ev)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     SDL_VideoDisplay *display = NULL;
     int i;
 
@@ -657,7 +657,6 @@ static void X11_HandleXRandROutputChange(SDL_VideoDevice *_this, const XRROutput
                 break;
             }
         }
-        SDL_free(displays);
     }
 
     if (ev->connection == RR_Disconnected) { /* output is going away */

src/video/x11/SDL_x11mouse.c

@@ -416,7 +416,7 @@ static int X11_CaptureMouse(SDL_Window *window)
 static SDL_MouseButtonFlags X11_GetGlobalMouseState(float *x, float *y)
 {
     SDL_VideoData *videodata = SDL_GetVideoDevice()->internal;
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     Display *display = GetDisplay();
     int i;
 
@@ -458,7 +458,6 @@ static SDL_MouseButtonFlags X11_GetGlobalMouseState(float *x, float *y)
                     }
                 }
             }
-            SDL_free(displays);
         }
     }
 

test/testautomation_video.c

@@ -305,7 +305,7 @@ static int video_getWindowFlags(void *arg)
  */
 static int video_getFullscreenDisplayModes(void *arg)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     const SDL_DisplayMode **modes;
     int count;
     int i;
@@ -323,7 +323,6 @@ static int video_getFullscreenDisplayModes(void *arg)
             SDLTest_AssertCheck(count >= 0, "Validate number of modes; expected: >= 0; got: %d", count);
             SDL_free((void *)modes);
         }
-        SDL_free(displays);
     }
 
     return TEST_COMPLETED;
@@ -334,7 +333,7 @@ static int video_getFullscreenDisplayModes(void *arg)
  */
 static int video_getClosestDisplayModeCurrentResolution(void *arg)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     const SDL_DisplayMode **modes;
     SDL_DisplayMode current;
     const SDL_DisplayMode *closest;
@@ -373,7 +372,6 @@ static int video_getClosestDisplayModeCurrentResolution(void *arg)
             }
             SDL_free((void *)modes);
         }
-        SDL_free(displays);
     }
 
     return TEST_COMPLETED;
@@ -384,7 +382,7 @@ static int video_getClosestDisplayModeCurrentResolution(void *arg)
  */
 static int video_getClosestDisplayModeRandomResolution(void *arg)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     SDL_DisplayMode target;
     int i;
     int variation;
@@ -411,7 +409,6 @@ static int video_getClosestDisplayModeRandomResolution(void *arg)
                 SDLTest_AssertPass("Call to SDL_GetClosestFullscreenDisplayMode(target=random/variation%d)", variation);
             }
         }
-        SDL_free(displays);
     }
 
     return TEST_COMPLETED;
@@ -1673,7 +1670,7 @@ cleanup:
  */
 static int video_setWindowCenteredOnDisplay(void *arg)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     SDL_Window *window;
     const char *title = "video_setWindowCenteredOnDisplay Test Window";
     int x, y, w, h;
@@ -1869,8 +1866,6 @@ static int video_setWindowCenteredOnDisplay(void *arg)
                 destroyVideoSuiteTestWindow(window);
             }
         }
-
-        SDL_free(displays);
     }
 
     return TEST_COMPLETED;

test/testbounds.c

@@ -16,7 +16,7 @@
 
 int main(int argc, char **argv)
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     int i;
     SDLTest_CommonState *state;
 
@@ -47,7 +47,6 @@ int main(int argc, char **argv)
                     bounds.x, bounds.y, bounds.w, bounds.h,
                     usable.x, usable.y, usable.w, usable.h);
         }
-        SDL_free(displays);
     }
 
     SDL_Quit();

test/testdisplayinfo.c

@@ -33,7 +33,7 @@ print_mode(const char *prefix, const SDL_DisplayMode *mode)
 
 int main(int argc, char *argv[])
 {
-    SDL_DisplayID *displays;
+    const SDL_DisplayID *displays;
     const SDL_DisplayMode **modes;
     const SDL_DisplayMode *mode;
     int num_displays, i;
@@ -98,7 +98,6 @@ int main(int argc, char *argv[])
 
         SDL_Log("\n");
     }
-    SDL_free(displays);
 
     SDL_Quit();
     SDLTest_CommonDestroyState(state);

test/testwm.c

@@ -62,7 +62,7 @@ draw_modes_menu(SDL_Window *window, SDL_Renderer *renderer, SDL_FRect viewport)
     float x, y;
     float table_top;
     SDL_FPoint mouse_pos = { -1.0f, -1.0f };
-    SDL_DisplayID *display_ids;
+    const SDL_DisplayID *displays;
 
     /* Get mouse position */
     if (SDL_GetMouseFocus() == window) {
@@ -98,18 +98,18 @@ draw_modes_menu(SDL_Window *window, SDL_Renderer *renderer, SDL_FRect viewport)
         highlighted_mode = NULL;
     }
 
-    display_ids = SDL_GetDisplays(NULL);
+    displays = SDL_GetDisplays(NULL);
 
-    if (display_ids) {
+    if (displays) {
-        for (i = 0; display_ids[i]; ++i) {
+        for (i = 0; displays[i]; ++i) {
-            const SDL_DisplayID display_id = display_ids[i];
+            SDL_DisplayID display = displays[i];
-            modes = SDL_GetFullscreenDisplayModes(display_id, NULL);
+            modes = SDL_GetFullscreenDisplayModes(display, NULL);
             for (j = 0; modes[j]; ++j) {
                 SDL_FRect cell_rect;
                 const SDL_DisplayMode *mode = modes[j];
 
                 (void)SDL_snprintf(text, sizeof(text), "%s mode %d: %dx%d@%gx %gHz",
-                                   SDL_GetDisplayName(display_id),
+                                   SDL_GetDisplayName(display),
                                    j, mode->w, mode->h, mode->pixel_density, mode->refresh_rate);
 
                 /* Update column width */
@@ -145,7 +145,6 @@ draw_modes_menu(SDL_Window *window, SDL_Renderer *renderer, SDL_FRect viewport)
             }
             SDL_free((void *)modes);
         }
-        SDL_free(display_ids);
     }
 }