Simplified SDL_SetProperty() and added SDL_SetPropertyWithCleanup()

Most of the time people won't need to set a cleanup callback, so we can simplify the more commonly used API.

include/SDL3/SDL_properties.h

@@ -95,7 +95,23 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
 /**
  * Set a property on a set of properties
  *
- * By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.
+ * \param props the properties to modify
+ * \param name the name of the property to modify
+ * \param value the new value of the property, or NULL to delete the property
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetPropertyWithCleanup
+ */
+extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
+
+/**
+ * Set a property on a set of properties with a cleanup function that is called when the property is deleted
  *
  * \param props the properties to modify
  * \param name the name of the property to modify
@@ -111,12 +127,15 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
  */
-extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
+extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
 
 /**
  * Get a property on a set of properties
  *
+ * By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.
+ *
  * \param props the properties to query
  * \param name the name of the property to query
  * \returns the value of the property, or NULL if it is not set.

src/SDL_properties.c

@@ -183,7 +183,12 @@ void SDL_UnlockProperties(SDL_PropertiesID props)
     SDL_UnlockMutex(properties->lock);
 }
 
-int SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata)
+int SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value)
+{
+    return SDL_SetPropertyWithCleanup(props, name, value, NULL, NULL);
+}
+
+int SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata)
 {
     SDL_Properties *properties = NULL;
     SDL_Property *property = NULL;
@@ -274,7 +279,7 @@ void *SDL_GetProperty(SDL_PropertiesID props, const char *name)
 
 int SDL_ClearProperty(SDL_PropertiesID props, const char *name)
 {
-    return SDL_SetProperty(props, name, NULL, NULL, NULL);
+    return SDL_SetProperty(props, name, NULL);
 }
 
 void SDL_DestroyProperties(SDL_PropertiesID props)

src/dynapi/SDL_dynapi.sym

@@ -921,6 +921,7 @@ SDL3_0.0.0 {
     SDL_RWvprintf;
     SDL_AllocateEventMemory;
     SDL_GetDisplayProperties;
+    SDL_SetPropertyWithCleanup;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -946,3 +946,4 @@
 #define SDL_RWvprintf SDL_RWvprintf_REAL
 #define SDL_AllocateEventMemory SDL_AllocateEventMemory_REAL
 #define SDL_GetDisplayProperties SDL_GetDisplayProperties_REAL
+#define SDL_SetPropertyWithCleanup SDL_SetPropertyWithCleanup_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -962,7 +962,7 @@ SDL_DYNAPI_PROC(IDXGIResource*,SDL_GetTextureDXGIResource,(SDL_Texture *a),(a),r
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_CreateProperties,(void),(),return)
 SDL_DYNAPI_PROC(int,SDL_LockProperties,(SDL_PropertiesID a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_UnlockProperties,(SDL_PropertiesID a),(a),)
-SDL_DYNAPI_PROC(int,SDL_SetProperty,(SDL_PropertiesID a, const char *b, void *c, void (SDLCALL *d)(void *userdata, void *value), void *e),(a,b,c,d,e),return)
+SDL_DYNAPI_PROC(int,SDL_SetProperty,(SDL_PropertiesID a, const char *b, void *c),(a,b,c),return)
 SDL_DYNAPI_PROC(void*,SDL_GetProperty,(SDL_PropertiesID a, const char *b),(a,b),return)
 SDL_DYNAPI_PROC(void,SDL_DestroyProperties,(SDL_PropertiesID a),(a),)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetAudioStreamProperties,(SDL_AudioStream *a),(a),return)
@@ -979,3 +979,4 @@ SDL_DYNAPI_PROC(int,SDL_EnterAppMainCallbacks,(int a, char *b[], SDL_AppInit_fun
 SDL_DYNAPI_PROC(size_t,SDL_RWvprintf,(SDL_RWops *a, const char *b, va_list c),(a,b,c),return)
 SDL_DYNAPI_PROC(void*,SDL_AllocateEventMemory,(size_t a),(a),return)
 SDL_DYNAPI_PROC(SDL_PropertiesID,SDL_GetDisplayProperties,(SDL_DisplayID a),(a),return)
+SDL_DYNAPI_PROC(int,SDL_SetPropertyWithCleanup,(SDL_PropertiesID a, const char *b, void *c, void (SDLCALL *d)(void *userdata, void *value), void *e),(a,b,c,d,e),return)

src/render/SDL_render.c

@@ -929,7 +929,7 @@ SDL_Renderer *SDL_CreateRenderer(SDL_Window *window, const char *name, Uint32 fl
         renderer->hidden = SDL_FALSE;
     }
 
-    SDL_SetProperty(SDL_GetWindowProperties(window), SDL_WINDOWRENDERDATA, renderer, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), SDL_WINDOWRENDERDATA, renderer);
 
     SDL_SetRenderViewport(renderer, NULL);
 

src/render/direct3d/SDL_render_d3d.c

@@ -1714,7 +1714,7 @@ SDL_Renderer *D3D_CreateRenderer(SDL_Window *window, Uint32 flags)
     data->drawstate.cliprect_enabled_dirty = SDL_TRUE;
     data->drawstate.blend = SDL_BLENDMODE_INVALID;
 
-    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d9.device", data->device, NULL, NULL);
+    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d9.device", data->device);
 
     return renderer;
 }

src/render/direct3d11/SDL_render_d3d11.c

@@ -668,7 +668,7 @@ static HRESULT D3D11_CreateDeviceResources(SDL_Renderer *renderer)
     ID3D11DeviceContext_VSSetShader(data->d3dContext, data->vertexShader, NULL, 0);
     ID3D11DeviceContext_VSSetConstantBuffers(data->d3dContext, 0, 1, &data->vertexShaderConstants);
 
-    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d11.device", data->d3dDevice, NULL, NULL);
+    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d11.device", data->d3dDevice);
 
 done:
     SAFE_RELEASE(d3dDevice);

src/render/direct3d12/SDL_render_d3d12.c

@@ -1070,7 +1070,7 @@ static HRESULT D3D12_CreateDeviceResources(SDL_Renderer *renderer)
     }
     data->srvPoolHead = &data->srvPoolNodes[0];
 
-    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d12.device", data->d3dDevice, NULL, NULL);
+    SDL_SetProperty(SDL_GetRendererProperties(renderer), "SDL.renderer.d3d12.device", data->d3dDevice);
 
 done:
     SAFE_RELEASE(d3dDevice);

src/video/SDL_video.c

@@ -280,7 +280,7 @@ static int SDL_CreateWindowTexture(SDL_VideoDevice *_this, SDL_Window *window, U
             SDL_DestroyRenderer(renderer);
             return SDL_OutOfMemory();
         }
-        SDL_SetProperty(props, SDL_WINDOWTEXTUREDATA, data, SDL_CleanupWindowTextureData, NULL);
+        SDL_SetPropertyWithCleanup(props, SDL_WINDOWTEXTUREDATA, data, SDL_CleanupWindowTextureData, NULL);
 
         data->renderer = renderer;
     } else {

src/video/dummy/SDL_nullframebuffer.c

@@ -48,7 +48,7 @@ int SDL_DUMMY_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window
     }
 
     /* Save the info and return! */
-    SDL_SetProperty(SDL_GetWindowProperties(window), DUMMY_SURFACE, surface, CleanupSurface, NULL);
+    SDL_SetPropertyWithCleanup(SDL_GetWindowProperties(window), DUMMY_SURFACE, surface, CleanupSurface, NULL);
     *format = surface_format;
     *pixels = surface->pixels;
     *pitch = surface->pitch;

src/video/n3ds/SDL_n3dsframebuffer.c

@@ -57,7 +57,7 @@ int SDL_N3DS_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *window,
         return SDL_OutOfMemory();
     }
 
-    SDL_SetProperty(SDL_GetWindowProperties(window), N3DS_SURFACE, framebuffer, CleanupSurface, NULL);
+    SDL_SetPropertyWithCleanup(SDL_GetWindowProperties(window), N3DS_SURFACE, framebuffer, CleanupSurface, NULL);
     *format = FRAMEBUFFER_FORMAT;
     *pixels = framebuffer->pixels;
     *pitch = framebuffer->pitch;

src/video/offscreen/SDL_offscreenframebuffer.c

@@ -48,7 +48,7 @@ int SDL_OFFSCREEN_CreateWindowFramebuffer(SDL_VideoDevice *_this, SDL_Window *wi
     }
 
     /* Save the info and return! */
-    SDL_SetProperty(SDL_GetWindowProperties(window), OFFSCREEN_SURFACE, surface, CleanupSurface, NULL);
+    SDL_SetPropertyWithCleanup(SDL_GetWindowProperties(window), OFFSCREEN_SURFACE, surface, CleanupSurface, NULL);
     *format = surface_format;
     *pixels = surface->pixels;
     *pitch = surface->pitch;

test/testautomation_properties.c

@@ -26,7 +26,7 @@ static int properties_testBasic(void *arg)
     for (i = 0; i < 10; ++i) {
         SDL_snprintf(key, SDL_arraysize(key), "%c", 'a' + i);
         SDL_snprintf(expected_value, SDL_arraysize(expected_value), "%c", 'a' + i);
-        result = SDL_SetProperty(props, key, expected_value, NULL, NULL);
+        result = SDL_SetProperty(props, key, expected_value);
         SDLTest_AssertPass("Call to SDL_SetProperty()");
         SDLTest_AssertCheck(result == 0,
             "Verify property value was set, got: %d", result);
@@ -38,7 +38,7 @@ static int properties_testBasic(void *arg)
 
     for (i = 0; i < 10; ++i) {
         SDL_snprintf(key, SDL_arraysize(key), "%c", 'a' + i);
-        result = SDL_SetProperty(props, key, NULL, NULL, NULL);
+        result = SDL_SetProperty(props, key, NULL);
         SDLTest_AssertPass("Call to SDL_SetProperty(NULL)");
         SDLTest_AssertCheck(result == 0,
             "Verify property value was set, got: %d", result);
@@ -71,8 +71,8 @@ static int properties_testCleanup(void *arg)
 
     SDLTest_AssertPass("Call to SDL_SetProperty(cleanup)");
     count = 0;
-    SDL_SetProperty(props, "a", "0", cleanup, &count);
-    SDL_SetProperty(props, "a", NULL, cleanup, &count);
+    SDL_SetPropertyWithCleanup(props, "a", "0", cleanup, &count);
+    SDL_SetPropertyWithCleanup(props, "a", NULL, cleanup, &count);
     SDLTest_AssertCheck(count == 1,
         "Verify cleanup for deleting property, got %d, expected 1", count);
 
@@ -81,7 +81,7 @@ static int properties_testCleanup(void *arg)
     for (i = 0; i < 10; ++i) {
         SDL_snprintf(key, SDL_arraysize(key), "%c", 'a' + i);
         SDL_snprintf(expected_value, SDL_arraysize(expected_value), "%c", 'a' + i);
-        SDL_SetProperty(props, key, expected_value, cleanup, &count);
+        SDL_SetPropertyWithCleanup(props, key, expected_value, cleanup, &count);
     }
     SDL_DestroyProperties(props);
     SDLTest_AssertCheck(count == 10,
@@ -104,11 +104,11 @@ static int properties_thread(void *arg)
 
     while (!data->done) {
         SDL_LockProperties(data->props);
-        SDL_SetProperty(data->props, "a", "thread_loop", NULL, NULL);
+        SDL_SetProperty(data->props, "a", "thread_loop");
         SDL_UnlockProperties(data->props);
     }
     SDL_LockProperties(data->props);
-    SDL_SetProperty(data->props, "a", "thread_done", NULL, NULL);
+    SDL_SetProperty(data->props, "a", "thread_done");
     SDL_UnlockProperties(data->props);
     return 0;
 }
@@ -122,7 +122,7 @@ static int properties_testLocking(void *arg)
     data.done = SDL_FALSE;
     data.props = SDL_CreateProperties();
     SDLTest_AssertPass("Setting property to 'init'");
-    SDL_SetProperty(data.props, "a", "init", NULL, NULL);
+    SDL_SetProperty(data.props, "a", "init");
     thread = SDL_CreateThread(properties_thread, "properties_thread", &data);
     if (thread) {
         SDLTest_AssertPass("Waiting for property to change to 'thread_loop'");
@@ -142,7 +142,7 @@ static int properties_testLocking(void *arg)
 
         SDLTest_AssertPass("Setting property to 'main'");
         SDL_LockProperties(data.props);
-        SDL_SetProperty(data.props, "a", "main", NULL, NULL);
+        SDL_SetProperty(data.props, "a", "main");
         SDL_Delay(100);
         value = SDL_GetProperty(data.props, "a");
         SDLTest_AssertCheck(value && SDL_strcmp((const char *)value, "main") == 0,

test/testautomation_video.c

@@ -1498,7 +1498,7 @@ static int video_getSetWindowData(void *arg)
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
 
     /* Set data */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,%s)", name, userdata);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
@@ -1514,7 +1514,7 @@ static int video_getSetWindowData(void *arg)
 
     /* Set data again twice */
     for (iteration = 1; iteration <= 2; iteration++) {
-        SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata, NULL, NULL);
+        SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata);
         SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,%s) [iteration %d]", name, userdata, iteration);
         SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
         SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
@@ -1527,14 +1527,14 @@ static int video_getSetWindowData(void *arg)
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
 
     /* Set data with new data */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata2, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata2);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,%s) [new userdata]", name, userdata2);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata2, userdata2) == 0, "Validate that userdata2 was not changed, expected: %s, got: %s", referenceUserdata2, userdata2);
 
     /* Set data with new data again */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata2, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata2);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,%s) [new userdata again]", name, userdata2);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
@@ -1547,14 +1547,14 @@ static int video_getSetWindowData(void *arg)
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
 
     /* Set data with NULL to clear */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, NULL, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, NULL);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,NULL)", name);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata2, userdata2) == 0, "Validate that userdata2 was not changed, expected: %s, got: %s", referenceUserdata2, userdata2);
 
     /* Set data with NULL to clear again */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, NULL, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, NULL);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,NULL) [again]", name);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
@@ -1573,7 +1573,7 @@ static int video_getSetWindowData(void *arg)
     SDLTest_AssertCheck(SDL_strcmp(referenceName2, name2) == 0, "Validate that name2 was not changed, expected: %s, got: %s", referenceName2, name2);
 
     /* Set data (again) */
-    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), name, userdata);
     SDLTest_AssertPass("Call to SDL_SetWindowData(...%s,%s) [again, after clear]", name, userdata);
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
     SDLTest_AssertCheck(SDL_strcmp(referenceUserdata, userdata) == 0, "Validate that userdata was not changed, expected: %s, got: %s", referenceUserdata, userdata);
@@ -1585,22 +1585,22 @@ static int video_getSetWindowData(void *arg)
     SDLTest_AssertCheck(SDL_strcmp(referenceName, name) == 0, "Validate that name was not changed, expected: %s, got: %s", referenceName, name);
 
     /* Set data with NULL name, valid userdata */
-    SDL_SetProperty(SDL_GetWindowProperties(window), NULL, userdata, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), NULL, userdata);
     SDLTest_AssertPass("Call to SDL_SetWindowData(name=NULL)");
     checkInvalidParameterError();
 
     /* Set data with empty name, valid userdata */
-    SDL_SetProperty(SDL_GetWindowProperties(window), "", userdata, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), "", userdata);
     SDLTest_AssertPass("Call to SDL_SetWindowData(name='')");
     checkInvalidParameterError();
 
     /* Set data with NULL name, NULL userdata */
-    SDL_SetProperty(SDL_GetWindowProperties(window), NULL, NULL, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), NULL, NULL);
     SDLTest_AssertPass("Call to SDL_SetWindowData(name=NULL,userdata=NULL)");
     checkInvalidParameterError();
 
     /* Set data with empty name, NULL userdata */
-    SDL_SetProperty(SDL_GetWindowProperties(window), "", NULL, NULL, NULL);
+    SDL_SetProperty(SDL_GetWindowProperties(window), "", NULL);
     SDLTest_AssertPass("Call to SDL_SetWindowData(name='',userdata=NULL)");
     checkInvalidParameterError();
 

test/testffmpeg.c

@@ -464,7 +464,7 @@ static SDL_bool GetTextureForMemoryFrame(AVFrame *frame, SDL_Texture **texture)
                 SDL_OutOfMemory();
                 return SDL_FALSE;
             }
-            SDL_SetProperty(props, SWS_CONTEXT_CONTAINER_PROPERTY, sws_container, FreeSwsContextContainer, NULL);
+            SDL_SetPropertyWithCleanup(props, SWS_CONTEXT_CONTAINER_PROPERTY, sws_container, FreeSwsContextContainer, NULL);
         }
         sws_container->context = sws_getCachedContext(sws_container->context, frame->width, frame->height, frame->format, frame->width, frame->height, AV_PIX_FMT_BGRA, SWS_POINT, NULL, NULL, NULL);
         if (sws_container->context) {