sdl (master post 3.1 preview) Merge commit 'e4f454091a943345938608570b104400f62fd625'

external/sdl/SDL/include/SDL3/SDL_properties.h

@@ -28,6 +28,8 @@
 #ifndef SDL_properties_h_
 #define SDL_properties_h_
 
+#include <SDL3/SDL_stdinc.h>
+
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
 #ifdef __cplusplus
@@ -81,6 +83,25 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
  */
 extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
 
+/**
+ * Copy a set of properties
+ *
+ * Copy all the properties from one set of properties to another, with the
+ * exception of properties requiring cleanup (set using
+ * SDL_SetPropertyWithCleanup()), which will not be copied. Any property that
+ * already exists on `dst` will be overwritten.
+ *
+ * \param src the properties to copy
+ * \param dst the destination properties
+ * \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.
+ */
+extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);
+
 /**
  * Lock a set of properties
  *
@@ -122,6 +143,9 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
  * Set a property on a set of properties with a cleanup function that is
  * called when the property is deleted
  *
+ * The cleanup function is also called if setting the property fails for any
+ * reason.
+ *
  * \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
@@ -154,13 +178,21 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetProperty
+ * \sa SDL_HasProperty
+ * \sa SDL_SetBooleanProperty
+ * \sa SDL_SetFloatProperty
+ * \sa SDL_SetNumberProperty
  * \sa SDL_SetPropertyWithCleanup
+ * \sa SDL_SetStringProperty
  */
 extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
 
 /**
  * Set a string property on a set of properties
  *
+ * This function makes a copy of the string; the caller does not have to
+ * preserve the data after this call completes.
+ *
  * \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
@@ -226,6 +258,21 @@ extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const c
  */
 extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
 
+/**
+ * Return whether a property exists in a set of properties.
+ *
+ * \param props the properties to query
+ * \param name the name of the property to query
+ * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetPropertyType
+ */
+extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);
+
 /**
  * Get the type of a property on a set of properties
  *
@@ -237,6 +284,8 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const
  * \threadsafety It is safe to call this function from any thread.
  *
  * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_HasProperty
  */
 extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
 
@@ -262,7 +311,12 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr
  *
  * \since This function is available since SDL 3.0.0.
  *
+ * \sa SDL_GetBooleanProperty
+ * \sa SDL_GetFloatProperty
+ * \sa SDL_GetNumberProperty
  * \sa SDL_GetPropertyType
+ * \sa SDL_GetStringProperty
+ * \sa SDL_HasProperty
  * \sa SDL_SetProperty
  */
 extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);
@@ -281,6 +335,7 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetPropertyType
+ * \sa SDL_HasProperty
  * \sa SDL_SetStringProperty
  */
 extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
@@ -302,6 +357,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetPropertyType
+ * \sa SDL_HasProperty
  * \sa SDL_SetNumberProperty
  */
 extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
@@ -323,6 +379,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetPropertyType
+ * \sa SDL_HasProperty
  * \sa SDL_SetFloatProperty
  */
 extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
@@ -344,6 +401,7 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetPropertyType
+ * \sa SDL_HasProperty
  * \sa SDL_SetBooleanProperty
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
@@ -359,8 +417,6 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props,
  * \threadsafety It is safe to call this function from any thread.
  *
  * \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);