SDL_GetAudioPlaybackDevices() and SDL_GetAudioRecordingDevices() follow the SDL_GetStringRule

docs/README-migration.md

@@ -161,7 +161,6 @@ Rather than iterating over audio devices using a device index, there are new fun
                 const char *name = SDL_GetAudioDeviceName(instance_id);
                 SDL_Log("AudioDevice %" SDL_PRIu32 ": %s\n", instance_id, name);
             }
-            SDL_free(devices);
         }
         SDL_QuitSubSystem(SDL_INIT_AUDIO);
     }

include/SDL3/SDL_audio.h

@@ -448,11 +448,11 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
  * If this function returns NULL, to signify an error, `*count` will be set to
  * zero.
  *
- * \param count a pointer filled in with the number of devices returned. NULL
+ * The returned array follows the SDL_GetStringRule, and will be automatically freed later.
- *              is allowed.
+ *
- * \returns a 0 terminated array of device instance IDs which should be freed
+ * \param count a pointer filled in with the number of devices returned, may be NULL.
- *          with SDL_free(), or NULL on error; call SDL_GetError() for more
+ * \returns a 0 terminated array of device instance IDs or NULL on error; call SDL_GetError() for more
- *          details.
+ *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -461,7 +461,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
  * \sa SDL_OpenAudioDevice
  * \sa SDL_GetAudioRecordingDevices
  */
-extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *count);
+extern SDL_DECLSPEC const SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *count);
 
 /**
  * Get a list of currently-connected audio recording devices.
@@ -477,10 +477,10 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *
  * If this function returns NULL, to signify an error, `*count` will be set to
  * zero.
  *
- * \param count a pointer filled in with the number of devices returned. NULL
+ * The returned array follows the SDL_GetStringRule, and will be automatically freed later.
- *              is allowed.
+ *
- * \returns a 0 terminated array of device instance IDs which should be freed
+ * \param count a pointer filled in with the number of devices returned, may be NULL.
- *          with SDL_free(), or NULL on failure; call SDL_GetError() for more
+ * \returns a 0 terminated array of device instance IDs, or NULL on failure; call SDL_GetError() for more
  *          information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -490,7 +490,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *
  * \sa SDL_OpenAudioDevice
  * \sa SDL_GetAudioPlaybackDevices
  */
-extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioRecordingDevices(int *count);
+extern SDL_DECLSPEC const SDL_AudioDeviceID *SDLCALL SDL_GetAudioRecordingDevices(int *count);
 
 /**
  * Get the human-readable name of a specific audio device.

src/audio/SDL_audio.c

@@ -1330,7 +1330,7 @@ static int SDLCALL RecordingAudioThread(void *devicep)  // thread entry point
 }
 
 
-static SDL_AudioDeviceID *GetAudioDevices(int *count, SDL_bool recording)
+static const SDL_AudioDeviceID *GetAudioDevices(int *count, SDL_bool recording)
 {
     SDL_AudioDeviceID *retval = NULL;
     int num_devices = 0;
@@ -1373,15 +1373,15 @@ static SDL_AudioDeviceID *GetAudioDevices(int *count, SDL_bool recording)
             *count = 0;
         }
     }
-    return retval;
+    return SDL_FreeLater(retval);
 }
 
-SDL_AudioDeviceID *SDL_GetAudioPlaybackDevices(int *count)
+const SDL_AudioDeviceID *SDL_GetAudioPlaybackDevices(int *count)
 {
     return GetAudioDevices(count, SDL_FALSE);
 }
 
-SDL_AudioDeviceID *SDL_GetAudioRecordingDevices(int *count)
+const SDL_AudioDeviceID *SDL_GetAudioRecordingDevices(int *count)
 {
     return GetAudioDevices(count, SDL_TRUE);
 }

src/dynapi/SDL_dynapi_procs.h

@@ -209,8 +209,8 @@ SDL_DYNAPI_PROC(int,SDL_GetAudioDeviceFormat,(SDL_AudioDeviceID a, SDL_AudioSpec
 SDL_DYNAPI_PROC(float,SDL_GetAudioDeviceGain,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetAudioDeviceName,(SDL_AudioDeviceID a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetAudioDriver,(int a),(a),return)
-SDL_DYNAPI_PROC(SDL_AudioDeviceID*,SDL_GetAudioPlaybackDevices,(int *a),(a),return)
+SDL_DYNAPI_PROC(const SDL_AudioDeviceID*,SDL_GetAudioPlaybackDevices,(int *a),(a),return)
-SDL_DYNAPI_PROC(SDL_AudioDeviceID*,SDL_GetAudioRecordingDevices,(int *a),(a),return)
+SDL_DYNAPI_PROC(const SDL_AudioDeviceID*,SDL_GetAudioRecordingDevices,(int *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetAudioStreamAvailable,(SDL_AudioStream *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetAudioStreamData,(SDL_AudioStream *a, void *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_AudioDeviceID,SDL_GetAudioStreamDevice,(SDL_AudioStream *a),(a),return)

test/testaudioinfo.c

@@ -20,7 +20,7 @@ print_devices(SDL_bool recording)
     const char *typestr = (recording ? "recording" : "playback");
     int n = 0;
     int frames;
-    SDL_AudioDeviceID *devices = recording ? SDL_GetAudioRecordingDevices(&n) : SDL_GetAudioPlaybackDevices(&n);
+    const SDL_AudioDeviceID *devices = recording ? SDL_GetAudioRecordingDevices(&n) : SDL_GetAudioPlaybackDevices(&n);
 
     if (!devices) {
         SDL_Log("  Driver failed to report %s devices: %s\n\n", typestr, SDL_GetError());
@@ -46,7 +46,6 @@ print_devices(SDL_bool recording)
         }
         SDL_Log("\n");
     }
-    SDL_free(devices);
 }
 
 int main(int argc, char **argv)

test/testaudiorecording.c

@@ -23,7 +23,7 @@ static SDLTest_CommonState *state = NULL;
 
 int SDL_AppInit(void **appstate, int argc, char **argv)
 {
-    SDL_AudioDeviceID *devices;
+    const SDL_AudioDeviceID *devices;
     SDL_AudioSpec outspec;
     SDL_AudioSpec inspec;
     SDL_AudioDeviceID device;

test/testautomation_audio.c

@@ -366,7 +366,7 @@ static int audio_enumerateAndNameAudioDevices(void *arg)
     int t;
     int i, n;
     const char *name;
-    SDL_AudioDeviceID *devices = NULL;
+    const SDL_AudioDeviceID *devices = NULL;
 
     /* Iterate over types: t=0 playback device, t=1 recording device */
     for (t = 0; t < 2; t++) {
@@ -388,8 +388,6 @@ static int audio_enumerateAndNameAudioDevices(void *arg)
                 }
             }
         }
-
-        SDL_free(devices);
     }
 
     return TEST_COMPLETED;

test/testmultiaudio.c

@@ -43,7 +43,7 @@ static void loop(void)
 #endif
 
 static void
-test_multi_audio(SDL_AudioDeviceID *devices, int devcount)
+test_multi_audio(const SDL_AudioDeviceID *devices, int devcount)
 {
     int keep_going = 1;
     SDL_AudioStream **streams = NULL;
@@ -135,7 +135,7 @@ test_multi_audio(SDL_AudioDeviceID *devices, int devcount)
 
 int main(int argc, char **argv)
 {
-    SDL_AudioDeviceID *devices = NULL;
+    const SDL_AudioDeviceID *devices = NULL;
     int devcount = 0;
     int i;
     char *filename = NULL;
@@ -194,7 +194,6 @@ int main(int argc, char **argv)
         }
     }
 
-    SDL_free(devices);
     SDL_free(filename);
 
     SDL_Quit();

test/testsurround.c

@@ -146,7 +146,7 @@ static void SDLCALL fill_buffer(void *userdata, SDL_AudioStream *stream, int len
 
 int main(int argc, char *argv[])
 {
-    SDL_AudioDeviceID *devices = NULL;
+    const SDL_AudioDeviceID *devices = NULL;
     SDLTest_CommonState *state;
     int devcount = 0;
     int i;
@@ -234,8 +234,6 @@ int main(int argc, char *argv[])
         SDL_DestroyAudioStream(stream);
     }
 
-    SDL_free(devices);
-
     SDL_Quit();
     return 0;
 }