Browse Source

Updated migration documentation for functions that now return temporary memory

Sam Lantinga 1 year ago
parent
commit
64cb431ead
1 changed files with 18 additions and 0 deletions
  1. 18 0
      docs/README-migration.md

+ 18 - 0
docs/README-migration.md

@@ -298,6 +298,10 @@ The following symbols have been renamed:
 The following symbols have been removed:
 The following symbols have been removed:
 * SDL_MIX_MAXVOLUME - mixer volume is now a float between 0.0 and 1.0
 * SDL_MIX_MAXVOLUME - mixer volume is now a float between 0.0 and 1.0
 
 
+## SDL_clipboard.h
+
+SDL_GetClipboardText() and SDL_GetPrimarySelectionText() return a const pointer to temporary memory, which does not need to be freed. You can use SDL_ClaimTemporaryMemory() to convert it to a non-const pointer that should be freed when you're done with it.
+
 ## SDL_cpuinfo.h
 ## SDL_cpuinfo.h
 
 
 The intrinsics headers (mmintrin.h, etc.) have been moved to `<SDL3/SDL_intrin.h>` and are no longer automatically included in SDL.h.
 The intrinsics headers (mmintrin.h, etc.) have been moved to `<SDL3/SDL_intrin.h>` and are no longer automatically included in SDL.h.
@@ -454,6 +458,10 @@ The following functions have been removed:
 The following enums have been renamed:
 The following enums have been renamed:
 * SDL_eventaction => SDL_EventAction
 * SDL_eventaction => SDL_EventAction
 
 
+## SDL_filesystem.h
+
+SDL_GetBasePath() and SDL_GetPrefPath() return a const pointer to temporary memory, which does not need to be freed. You can use SDL_ClaimTemporaryMemory() to convert it to a non-const pointer that should be freed when you're done with it.
+
 ## SDL_gamecontroller.h
 ## SDL_gamecontroller.h
 
 
 SDL_gamecontroller.h has been renamed SDL_gamepad.h, and all APIs have been renamed to match.
 SDL_gamecontroller.h has been renamed SDL_gamepad.h, and all APIs have been renamed to match.
@@ -686,6 +694,10 @@ be dropped into an SDL3 or SDL2 program, to continue to provide this
 functionality to your app and aid migration. That is located in the
 functionality to your app and aid migration. That is located in the
 [SDL_gesture GitHub repository](https://github.com/libsdl-org/SDL_gesture).
 [SDL_gesture GitHub repository](https://github.com/libsdl-org/SDL_gesture).
 
 
+## SDL_guid.h
+
+SDL_GUIDToString() returns a const pointer to the string representation of a GUID.
+
 ## SDL_haptic.h
 ## SDL_haptic.h
 
 
 Gamepads with simple rumble capability no longer show up in the SDL haptics interface, instead you should use SDL_RumbleGamepad().
 Gamepads with simple rumble capability no longer show up in the SDL haptics interface, instead you should use SDL_RumbleGamepad().
@@ -1017,6 +1029,10 @@ The following symbols have been renamed:
 
 
 SDL_LoadFunction() now returns `SDL_FunctionPointer` instead of `void *`, and should be cast to the appropriate function type. You can define SDL_FUNCTION_POINTER_IS_VOID_POINTER in your project to restore the previous behavior.
 SDL_LoadFunction() now returns `SDL_FunctionPointer` instead of `void *`, and should be cast to the appropriate function type. You can define SDL_FUNCTION_POINTER_IS_VOID_POINTER in your project to restore the previous behavior.
 
 
+## SDL_locale.h
+
+SDL_GetPreferredLocales() returns a const array of locale pointers, which does not need to be freed. You can use SDL_ClaimTemporaryMemory() to convert it to a non-const pointer that should be freed when you're done with it.
+
 ## SDL_log.h
 ## SDL_log.h
 
 
 The following macros have been removed:
 The following macros have been removed:
@@ -2054,6 +2070,8 @@ SDL_WindowFlags is used instead of Uint32 for API functions that refer to window
 
 
 SDL_GetWindowOpacity() directly returns the opacity instead of using an out parameter.
 SDL_GetWindowOpacity() directly returns the opacity instead of using an out parameter.
 
 
+SDL_GetWindowICCProfile() returns a const pointer to temporary memory, which does not need to be freed. You can use SDL_ClaimTemporaryMemory() to convert it to a non-const pointer that should be freed when you're done with it.
+
 The following functions have been renamed:
 The following functions have been renamed:
 * SDL_GL_DeleteContext() => SDL_GL_DestroyContext()
 * SDL_GL_DeleteContext() => SDL_GL_DestroyContext()
 * SDL_GetClosestDisplayMode() => SDL_GetClosestFullscreenDisplayMode()
 * SDL_GetClosestDisplayMode() => SDL_GetClosestFullscreenDisplayMode()