gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Removed temporary memory from the API

Browse Source 
It was intended to make the API easier to use, but various automatic garbage collection all had flaws, and making the application periodically clean up temporary memory added cognitive load to using the API, and in many cases was it was difficult to restructure threaded code to handle this.

So, we're largely going back to the original system, where the API returns allocated results and you free them.

In addition, to solve the problems we originally wanted temporary memory for:
* Short strings with a finite count, like device names, get stored in a per-thread string pool.
* Events continue to use temporary memory internally, which is cleaned up on the next event processing cycle.
This commit is contained in:
Sam Lantinga
2024-07-26 18:57:18 -07:00
parent 21411c6418
commit 4f55271571
100 changed files with 737 additions and 853 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/README-migration.md
View File

@@ -158,9 +158,9 @@ Rather than iterating over audio devices using a device index, there are new fun
if (devices) {
for (i = 0; i < num_devices; ++i) {
SDL_AudioDeviceID instance_id = devices[i];
const char *name = SDL_GetAudioDeviceName(instance_id);
SDL_Log("AudioDevice %" SDL_PRIu32 ": %s\n", instance_id, name);
SDL_Log("AudioDevice %" SDL_PRIu32 ": %s\n", instance_id, SDL_GetAudioDeviceName(instance_id));
}
SDL_free(devices);
}
SDL_QuitSubSystem(SDL_INIT_AUDIO);
}
@@ -298,10 +298,6 @@ The following symbols have been renamed:
The following symbols have been removed:
* 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
The intrinsics headers (mmintrin.h, etc.) have been moved to `<SDL3/SDL_intrin.h>` and are no longer automatically included in SDL.h.
@@ -458,10 +454,6 @@ The following functions have been removed:
The following enums have been renamed:
* 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 has been renamed SDL_gamepad.h, and all APIs have been renamed to match.
@@ -710,15 +702,13 @@ Rather than iterating over haptic devices using device index, there is a new fun
{
if (SDL_InitSubSystem(SDL_INIT_HAPTIC) == 0) {
int i, num_haptics;
const SDL_HapticID *haptics = SDL_GetHaptics(&num_haptics);
SDL_HapticID *haptics = SDL_GetHaptics(&num_haptics);
if (haptics) {
for (i = 0; i < num_haptics; ++i) {
SDL_HapticID instance_id = haptics[i];
const char *name = SDL_GetHapticNameForID(instance_id);
SDL_Log("Haptic %" SDL_PRIu32 ": %s\n",
instance_id, name ? name : "Unknown");
SDL_Log("Haptic %" SDL_PRIu32 ": %s\n", instance_id, SDL_GetHapticNameForID(instance_id));
}
SDL_free(haptics);
}
SDL_QuitSubSystem(SDL_INIT_HAPTIC);
}
@@ -840,7 +830,7 @@ Rather than iterating over joysticks using device index, there is a new function
{
if (SDL_InitSubSystem(SDL_INIT_JOYSTICK) == 0) {
int i, num_joysticks;
const SDL_JoystickID *joysticks = SDL_GetJoysticks(&num_joysticks);
SDL_JoystickID *joysticks = SDL_GetJoysticks(&num_joysticks);
if (joysticks) {
for (i = 0; i < num_joysticks; ++i) {
SDL_JoystickID instance_id = joysticks[i];
@@ -850,6 +840,7 @@ Rather than iterating over joysticks using device index, there is a new function
SDL_Log("Joystick %" SDL_PRIu32 ": %s%s%s VID 0x%.4x, PID 0x%.4x\n",
instance_id, name ? name : "Unknown", path ? ", " : "", path ? path : "", SDL_GetJoystickVendorForID(instance_id), SDL_GetJoystickProductForID(instance_id));
}
SDL_free(joysticks);
}
SDL_QuitSubSystem(SDL_INIT_JOYSTICK);
}
@@ -1034,10 +1025,6 @@ 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_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
The following macros have been removed:
@@ -1588,7 +1575,7 @@ Rather than iterating over sensors using device index, there is a new function S
{
if (SDL_InitSubSystem(SDL_INIT_SENSOR) == 0) {
int i, num_sensors;
const SDL_SensorID *sensors = SDL_GetSensors(&num_sensors);
SDL_SensorID *sensors = SDL_GetSensors(&num_sensors);
if (sensors) {
for (i = 0; i < num_sensors; ++i) {
SDL_Log("Sensor %" SDL_PRIu32 ": %s, type %d, platform type %d\n",
@@ -1597,6 +1584,7 @@ Rather than iterating over sensors using device index, there is a new function S
SDL_GetSensorTypeForID(sensors[i]),
SDL_GetSensorNonPortableTypeForID(sensors[i]));
}
SDL_free(sensors);
}
SDL_QuitSubSystem(SDL_INIT_SENSOR);
}
@@ -1996,7 +1984,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;
const SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
SDL_DisplayID *displays = SDL_GetDisplays(&num_displays);
if (displays) {
for (i = 0; i < num_displays; ++i) {
SDL_DisplayID instance_id = displays[i];
@@ -2004,6 +1992,7 @@ 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);
}
@@ -2041,13 +2030,14 @@ Rather than iterating over display modes using an index, there is a new function
{
SDL_DisplayID display = SDL_GetPrimaryDisplay();
int num_modes = 0;
const SDL_DisplayMode * const *modes = SDL_GetFullscreenDisplayModes(display, &num_modes);
SDL_DisplayMode **modes = SDL_GetFullscreenDisplayModes(display, &num_modes);
if (modes) {
for (i = 0; i < num_modes; ++i) {
SDL_DisplayMode *mode = modes[i];
SDL_Log("Display %" SDL_PRIu32 " mode %d: %dx%d@%gx %gHz\n",
display, i, mode->w, mode->h, mode->pixel_density, mode->refresh_rate);
}
SDL_free(modes);
}
}
```
@@ -2080,8 +2070,6 @@ 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_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:
* SDL_GL_DeleteContext() => SDL_GL_DestroyContext()
* SDL_GetClosestDisplayMode() => SDL_GetClosestFullscreenDisplayMode()