Added properties to various SDL objects

The following objects now have properties that can be user modified:
* SDL_AudioStream
* SDL_Gamepad
* SDL_Joystick
* SDL_RWops
* SDL_Renderer
* SDL_Sensor
* SDL_Surface
* SDL_Texture
* SDL_Window

build-scripts/SDL_migration.cocci

@@ -2735,3 +2735,13 @@ typedef SDL_cond, SDL_Condition;
 - SDL_WriteBE64
 + SDL_WriteU64BE
   (...)
+@@
+expression e, n;
+@@
+- SDL_GetWindowData(e, n)
++ SDL_GetProperty(SDL_GetWindowProperties(e), n)
+@@
+expression e, n, v;
+@@
+- SDL_SetWindowData(e, n, v)
++ SDL_SetProperty(SDL_GetWindowProperties(e), n, v, NULL, NULL)

docs/README-migration.md

@@ -852,9 +852,11 @@ The following functions have been renamed:
 * SDL_RenderWindowToLogical() => SDL_RenderCoordinatesFromWindow()
 
 The following functions have been removed:
+* SDL_GetTextureUserData() - use SDL_GetTextureProperties() instead
 * SDL_RenderGetIntegerScale()
 * SDL_RenderSetIntegerScale() - this is now explicit with SDL_LOGICAL_PRESENTATION_INTEGER_SCALE
 * SDL_RenderTargetSupported() - render targets are always supported
+* SDL_SetTextureUserData() - use SDL_GetTextureProperties() instead
 
 The following symbols have been renamed:
 * SDL_ScaleModeBest => SDL_SCALEMODE_BEST
@@ -1066,6 +1068,8 @@ The following functions have been renamed:
 
 ## SDL_surface.h
 
+The userdata member of SDL_Surface has been replaced with a more general properties interface, which can be queried with SDL_GetSurfaceProperties()
+
 Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat.
 
 SDL_CreateRGBSurface() and SDL_CreateRGBSurfaceWithFormat() have been combined into a new function SDL_CreateSurface().
@@ -1272,6 +1276,8 @@ The following functions have been removed:
 * SDL_GetDisplayMode()
 * SDL_GetNumDisplayModes() - replaced with SDL_GetFullscreenDisplayModes()
 * SDL_GetNumVideoDisplays() - replaced with SDL_GetDisplays()
+* SDL_GetWindowData() - use SDL_GetWindowProperties() instead
+* SDL_SetWindowData() - use SDL_GetWindowProperties() instead
 
 SDL_Window id type is named SDL_WindowID
 

include/SDL3/SDL_audio.h

@@ -29,11 +29,12 @@
 #define SDL_audio_h_
 
 #include <SDL3/SDL_stdinc.h>
-#include <SDL3/SDL_error.h>
 #include <SDL3/SDL_endian.h>
+#include <SDL3/SDL_error.h>
 #include <SDL3/SDL_mutex.h>
-#include <SDL3/SDL_thread.h>
+#include <SDL3/SDL_properties.h>
 #include <SDL3/SDL_rwops.h>
+#include <SDL3/SDL_thread.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -675,6 +676,18 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStre
  */
 extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
 
+/**
+ * Get the properties associated with an audio stream.
+ *
+ * \param stream the SDL_AudioStream to query
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);
 
 /**
  * Query the current format of an audio stream.

include/SDL3/SDL_gamepad.h

@@ -30,9 +30,10 @@
 
 #include <SDL3/SDL_stdinc.h>
 #include <SDL3/SDL_error.h>
+#include <SDL3/SDL_joystick.h>
+#include <SDL3/SDL_properties.h>
 #include <SDL3/SDL_rwops.h>
 #include <SDL3/SDL_sensor.h>
-#include <SDL3/SDL_joystick.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -554,6 +555,22 @@ extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_JoystickID
  */
 extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int player_index);
 
+/**
+ * Get the properties associated with an opened gamepad.
+ *
+ * These properties are shared with the underlying joystick object.
+ *
+ * \param gamepad a gamepad identifier previously returned by
+ *                SDL_OpenGamepad()
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad);
+
 /**
  * Get the instance ID of an opened gamepad.
  *

include/SDL3/SDL_joystick.h

@@ -42,6 +42,7 @@
 #include <SDL3/SDL_error.h>
 #include <SDL3/SDL_guid.h>
 #include <SDL3/SDL_mutex.h>
+#include <SDL3/SDL_properties.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -456,6 +457,19 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick,
  */
 extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
 
+/**
+ * Get the properties associated with a joystick.
+ *
+ * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick);
+
 /**
  * Get the implementation dependent name of a joystick.
  *

include/SDL3/SDL_properties.h

@@ -111,6 +111,21 @@ extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *
  */
 extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name);
 
+/**
+ * Clear a property on a set of properties
+ *
+ * \param props the properties to modify
+ * \param name the name of the property to clear
+ *
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ */
+extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
+
 /**
  * Destroy a set of properties
  *

include/SDL3/SDL_render.h

@@ -50,6 +50,7 @@
 
 #include <SDL3/SDL_stdinc.h>
 #include <SDL3/SDL_events.h>
+#include <SDL3/SDL_properties.h>
 #include <SDL3/SDL_rect.h>
 #include <SDL3/SDL_video.h>
 
@@ -315,6 +316,19 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
  */
 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_RendererInfo *info);
 
+/**
+ * Get the properties associated with a renderer.
+ *
+ * \param renderer the rendering context
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer);
+
 /**
  * Get the output size in pixels of a rendering context.
  *
@@ -421,6 +435,19 @@ typedef struct IDXGIResource IDXGIResource;
  */
 extern DECLSPEC IDXGIResource* SDLCALL SDL_GetTextureDXGIResource(SDL_Texture *texture);
 
+/**
+ * Get the properties associated with a texture.
+ *
+ * \param texture the texture to query
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture);
+
 /**
  * Query the attributes of a texture.
  *
@@ -589,33 +616,6 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_Sc
  */
 extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode);
 
-/**
- * Associate a user-specified pointer with a texture.
- *
- * \param texture the texture to update.
- * \param userdata the pointer to associate with the texture.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_GetTextureUserData
- */
-extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *userdata);
-
-/**
- * Get the user-specified pointer associated with a texture
- *
- * \param texture the texture to query.
- * \returns the pointer associated with the texture, or NULL if the texture is
- *          not valid.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_SetTextureUserData
- */
-extern DECLSPEC void *SDLCALL SDL_GetTextureUserData(SDL_Texture *texture);
-
 /**
  * Update the given texture rectangle with new pixel data.
  *

include/SDL3/SDL_rwops.h

@@ -31,6 +31,7 @@
 
 #include <SDL3/SDL_stdinc.h>
 #include <SDL3/SDL_error.h>
+#include <SDL3/SDL_properties.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -99,6 +100,7 @@ typedef struct SDL_RWops
 
     Uint32 type;
     Uint32 status;
+    SDL_PropertiesID props;
     union
     {
 #ifdef __ANDROID__
@@ -331,6 +333,19 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(void);
  */
 extern DECLSPEC void SDLCALL SDL_DestroyRW(SDL_RWops *context);
 
+/**
+ * Get the properties associated with an SDL_RWops.
+ *
+ * \param context a pointer to an SDL_RWops structure
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRWProperties(SDL_RWops *context);
+
 #define SDL_RW_SEEK_SET 0       /**< Seek from the beginning of data */
 #define SDL_RW_SEEK_CUR 1       /**< Seek relative to current read point */
 #define SDL_RW_SEEK_END 2       /**< Seek relative to the end of data */

include/SDL3/SDL_sensor.h

@@ -30,6 +30,7 @@
 
 #include <SDL3/SDL_stdinc.h>
 #include <SDL3/SDL_error.h>
+#include <SDL3/SDL_properties.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -189,6 +190,19 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id);
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID instance_id);
 
+/**
+ * Get the properties associated with a sensor.
+ *
+ * \param sensor The SDL_Sensor object
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor);
+
 /**
  * Get the implementation dependent name of a sensor
  *

include/SDL3/SDL_surface.h

@@ -29,9 +29,10 @@
 #define SDL_surface_h_
 
 #include <SDL3/SDL_stdinc.h>
+#include <SDL3/SDL_blendmode.h>
 #include <SDL3/SDL_pixels.h>
+#include <SDL3/SDL_properties.h>
 #include <SDL3/SDL_rect.h>
-#include <SDL3/SDL_blendmode.h>
 #include <SDL3/SDL_rwops.h>
 
 #include <SDL3/SDL_begin_code.h>
@@ -92,7 +93,7 @@ typedef struct SDL_Surface
     void *pixels;               /**< Read-write */
 
     /** Application data associated with the surface */
-    void *userdata;             /**< Read-write */
+    SDL_PropertiesID props;     /**< Read-write */
 
     /** information needed for surfaces requiring locks */
     int locked;                 /**< Read-only */
@@ -189,6 +190,19 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom
  */
 extern DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface);
 
+/**
+ * Get the properties associated with a surface.
+ *
+ * \param surface the SDL_Surface structure to query
+ * \returns a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetProperty
+ * \sa SDL_SetProperty
+ */
+extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface);
+
 /**
  * Set the palette used by a surface.
  *