eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-30 16:37:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

properties: add formal SDL_CleanupPropertyCallback type, improve docs.

Browse source
This commit is contained in:
Ryan C. Gordon 2024-05-26 12:17:34 -04:00
parent 4ee28b6bb4
commit 2626304e70
No known key found for this signature in database
GPG key ID: FA148B892AB48044
3 changed files with 50 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

48
include/SDL3/SDL_properties.h
View file

@ -145,6 +145,30 @@ extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
*/
extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
/**
* A callback used to free resources when a property is deleted.
*
* This should release any resources associated with `value` that are
* no longer needed.
*
* This callback is set per-property. Different properties in the same
* set can have different cleanup callbacks.
*
* This callback will be called _during_ SDL_SetPropertyWithCleanup if the
* function fails for any reason.
*
* \param userdata an app-defined pointer passed to the callback.
* \param value the pointer assigned to the property to clean up.
*
* \threadsafety This callback may fire without any locks held; if this is
* a concern, the app should provide its own locking.
*
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_SetPropertyWithCleanup
*/
typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value);
/**
* Set a property on a set of properties with a cleanup function that is
* called when the property is deleted.
@ -152,6 +176,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
* The cleanup function is also called if setting the property fails for any
* reason.
*
* For simply setting basic data types, like numbers, bools, or strings,
* use SDL_SetNumberProperty, SDL_SetBooleanProperty, or SDL_SetStringProperty
* instead, as those functions will handle cleanup on your behalf. This
* function is only for more complex, custom data.
*
* \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
@ -167,8 +196,9 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
* \sa SDL_CleanupPropertyCallback
*/
extern SDL_DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
extern SDL_DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata);
/**
* Set a property on a set of properties.
@ -426,6 +456,22 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID pro
*/
extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
/**
* A callback used to enumerate all properties set in an SDL_PropertiesID.
*
* This callback is called from SDL_EnumerateProperties(), and is called once
* per property in the set.
*
* \param userdata an app-defined pointer passed to the callback.
* \param props the SDL_PropertiesID that is being enumerated.
* \param name the next property name in the enumeration.
*
* \threadsafety SDL_EnumerateProperties holds a lock on `props` during this callback.
*
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_EnumerateProperties
*/
typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
/**

4
src/SDL_properties.c
View file

@ -38,7 +38,7 @@ typedef struct
char *string_storage;
void (SDLCALL *cleanup)(void *userdata, void *value);
SDL_CleanupPropertyCallback cleanup;
void *userdata;
} SDL_Property;
@ -338,7 +338,7 @@ static int SDL_PrivateSetProperty(SDL_PropertiesID props, const char *name, SDL_
return result;
}
int SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata)
int SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata)
{
SDL_Property *property;

2
src/dynapi/SDL_dynapi_procs.h
View file

@ -748,7 +748,7 @@ SDL_DYNAPI_PROC(int,SDL_SetPaletteColors,(SDL_Palette *a, const SDL_Color *b, in
SDL_DYNAPI_PROC(int,SDL_SetPixelFormatPalette,(SDL_PixelFormat *a, SDL_Palette *b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetPrimarySelectionText,(const char *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_SetProperty,(SDL_PropertiesID a, const char *b, void *c),(a,b,c),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)
SDL_DYNAPI_PROC(int,SDL_SetPropertyWithCleanup,(SDL_PropertiesID a, const char *b, void *c, SDL_CleanupPropertyCallback d, void *e),(a,b,c,d,e),return)
SDL_DYNAPI_PROC(int,SDL_SetRelativeMouseMode,(SDL_bool a),(a),return)
SDL_DYNAPI_PROC(int,SDL_SetRenderClipRect,(SDL_Renderer *a, const SDL_Rect *b),(a,b),return)
SDL_DYNAPI_PROC(int,SDL_SetRenderColorScale,(SDL_Renderer *a, float b),(a,b),return)