mirror of
https://github.com/libsdl-org/SDL.git
synced 2026-04-20 14:25:40 +00:00
Added property types: pointer, string, number, float
This commit is contained in:
Sam Lantinga
@@ -39,6 +39,18 @@ extern "C" {
|
||||
*/
|
||||
typedef Uint32 SDL_PropertiesID;
|
||||
|
||||
/**
|
||||
* SDL property type
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
SDL_PROPERTY_TYPE_INVALID,
|
||||
SDL_PROPERTY_TYPE_POINTER,
|
||||
SDL_PROPERTY_TYPE_STRING,
|
||||
SDL_PROPERTY_TYPE_NUMBER,
|
||||
SDL_PROPERTY_TYPE_FLOAT,
|
||||
} SDL_PropertyType;
|
||||
|
||||
/**
|
||||
* Get the global SDL properties
|
||||
*
|
||||
@@ -105,24 +117,6 @@ extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
|
||||
*/
|
||||
extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
|
||||
|
||||
/**
|
||||
* Set a property on a set of properties
|
||||
*
|
||||
* \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
|
||||
@@ -145,6 +139,88 @@ extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
|
||||
|
||||
/**
|
||||
* Set a property on a set of properties
|
||||
*
|
||||
* \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 string property on a set of properties
|
||||
*
|
||||
* \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_GetStringProperty
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
|
||||
|
||||
/**
|
||||
* Set an integer property on a set of properties
|
||||
*
|
||||
* \param props the properties to modify
|
||||
* \param name the name of the property to modify
|
||||
* \param value the new value of 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_GetNumberProperty
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
|
||||
|
||||
/**
|
||||
* Set a floating point property on a set of properties
|
||||
*
|
||||
* \param props the properties to modify
|
||||
* \param name the name of the property to modify
|
||||
* \param value the new value of 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_GetFloatProperty
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
|
||||
|
||||
/**
|
||||
* Get the type of a property on a set of properties
|
||||
*
|
||||
* \param props the properties to query
|
||||
* \param name the name of the property to query
|
||||
* \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is not set.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*/
|
||||
extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
|
||||
|
||||
/**
|
||||
* Get a property on a set of properties
|
||||
*
|
||||
@@ -155,7 +231,8 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c
|
||||
*
|
||||
* \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.
|
||||
* \param default_value the default value of the property
|
||||
* \returns the value of the property, or `default_value` if it is not set or not a pointer property.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread, although
|
||||
* the data returned is not protected and could potentially be
|
||||
@@ -165,9 +242,65 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetPropertyType
|
||||
* \sa SDL_SetProperty
|
||||
*/
|
||||
extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name);
|
||||
extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);
|
||||
|
||||
/**
|
||||
* Get a string property on a set of properties
|
||||
*
|
||||
* \param props the properties to query
|
||||
* \param name the name of the property to query
|
||||
* \param default_value the default value of the property
|
||||
* \returns the value of the property, or `default_value` if it is not set or not a string property.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetPropertyType
|
||||
* \sa SDL_SetStringProperty
|
||||
*/
|
||||
extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
|
||||
|
||||
/**
|
||||
* Get a number property on a set of properties
|
||||
*
|
||||
* You can use SDL_GetPropertyType() to query whether the property exists and is a number property.
|
||||
*
|
||||
* \param props the properties to query
|
||||
* \param name the name of the property to query
|
||||
* \param default_value the default value of the property
|
||||
* \returns the value of the property, or `default_value` if it is not set or not a number property.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetPropertyType
|
||||
* \sa SDL_SetNumberProperty
|
||||
*/
|
||||
extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
|
||||
|
||||
/**
|
||||
* Get a floating point property on a set of properties
|
||||
*
|
||||
* You can use SDL_GetPropertyType() to query whether the property exists and is a floating point property.
|
||||
*
|
||||
* \param props the properties to query
|
||||
* \param name the name of the property to query
|
||||
* \param default_value the default value of the property
|
||||
* \returns the value of the property, or `default_value` if it is not set or not a float property.
|
||||
*
|
||||
* \threadsafety It is safe to call this function from any thread.
|
||||
*
|
||||
* \since This function is available since SDL 3.0.0.
|
||||
*
|
||||
* \sa SDL_GetPropertyType
|
||||
* \sa SDL_SetFloatProperty
|
||||
*/
|
||||
extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
|
||||
|
||||
/**
|
||||
* Clear a property on a set of properties
|
||||
@@ -185,6 +318,24 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char
|
||||
*/
|
||||
extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
|
||||
|
||||
typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
|
||||
/**
|
||||
* Enumerate the properties on a set of properties
|
||||
*
|
||||
* The callback function is called for each property on the set of properties. The properties are locked during enumeration.
|
||||
*
|
||||
* \param props the properties to query
|
||||
* \param callback the function to call for each property
|
||||
* \param userdata a pointer that is passed to `callback`
|
||||
* \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_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
|
||||
|
||||
/**
|
||||
* Destroy a set of properties
|
||||
*
|
||||
|
||||
@@ -311,10 +311,10 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
|
||||
*
|
||||
* The following properties are provided by SDL:
|
||||
* ```
|
||||
* "SDL.renderer.d3d9.device" - the IDirect3DDevice9 associated with the renderer
|
||||
* "SDL.renderer.d3d11.device" - the ID3D11Device associated with the renderer
|
||||
* "SDL.renderer.d3d12.device" - the ID3D12Device associated with the renderer
|
||||
* "SDL.renderer.d3d12.command_queue" - the ID3D12CommandQueue associated with the renderer
|
||||
* "SDL.renderer.d3d9.device" (pointer) - the IDirect3DDevice9 associated with the renderer
|
||||
* "SDL.renderer.d3d11.device" (pointer) - the ID3D11Device associated with the renderer
|
||||
* "SDL.renderer.d3d12.device" (pointer) - the ID3D12Device associated with the renderer
|
||||
* "SDL.renderer.d3d12.command_queue" (pointer) - the ID3D12CommandQueue associated with the renderer
|
||||
* ```
|
||||
*
|
||||
* \param renderer the rendering context
|
||||
@@ -424,33 +424,33 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
|
||||
*
|
||||
* With the direct3d11 renderer:
|
||||
* ```
|
||||
* "SDL.texture.d3d11.texture" - the ID3D11Texture2D associated with the texture
|
||||
* "SDL.texture.d3d11.texture_u" - the ID3D11Texture2D associated with the U plane of a YUV texture
|
||||
* "SDL.texture.d3d11.texture_v" - the ID3D11Texture2D associated with the V plane of a YUV texture
|
||||
* "SDL.texture.d3d11.texture" (pointer) - the ID3D11Texture2D associated with the texture
|
||||
* "SDL.texture.d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U plane of a YUV texture
|
||||
* "SDL.texture.d3d11.texture_v" (pointer) - the ID3D11Texture2D associated with the V plane of a YUV texture
|
||||
* ```
|
||||
*
|
||||
* With the direct3d12 renderer:
|
||||
* ```
|
||||
* "SDL.texture.d3d12.texture" - the ID3D12Resource associated with the texture
|
||||
* "SDL.texture.d3d12.texture_u" - the ID3D12Resource associated with the U plane of a YUV texture
|
||||
* "SDL.texture.d3d12.texture_v" - the ID3D12Resource associated with the V plane of a YUV texture
|
||||
* "SDL.texture.d3d12.texture" (pointer) - the ID3D12Resource associated with the texture
|
||||
* "SDL.texture.d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U plane of a YUV texture
|
||||
* "SDL.texture.d3d12.texture_v" (pointer) - the ID3D12Resource associated with the V plane of a YUV texture
|
||||
* ```
|
||||
*
|
||||
* With the opengl renderer:
|
||||
* ```
|
||||
* "SDL.texture.opengl.texture" - the GLuint texture associated with the texture
|
||||
* "SDL.texture.opengl.texture_u" - the GLuint texture associated with the U plane of a YUV texture
|
||||
* "SDL.texture.opengl.texture_v" - the GLuint texture associated with the V plane of a YUV texture
|
||||
* "SDL.texture.opengl.tex_w" - the 16.16 fixed point texture coordinate width of the texture
|
||||
* "SDL.texture.opengl.tex_h" - the 16.16 fixed point texture coordinate height of the texture
|
||||
* "SDL.texture.opengl.texture" (number) - the GLuint texture associated with the texture
|
||||
* "SDL.texture.opengl.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture
|
||||
* "SDL.texture.opengl.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture
|
||||
* "SDL.texture.opengl.tex_w" (float) - the texture coordinate width of the texture (0.0 - 1.0)
|
||||
* "SDL.texture.opengl.tex_h" (float) - the texture coordinate height of the texture (0.0 - 1.0)
|
||||
* ```
|
||||
*
|
||||
* With the opengles2 renderer:
|
||||
* ```
|
||||
* "SDL.texture.opengles2.texture" - the GLuint texture associated with the texture
|
||||
* "SDL.texture.opengles2.texture_uv" - the GLuint texture associated with the UV plane of an NV12 texture
|
||||
* "SDL.texture.opengles2.texture_u" - the GLuint texture associated with the U plane of a YUV texture
|
||||
* "SDL.texture.opengles2.texture_v" - the GLuint texture associated with the V plane of a YUV texture
|
||||
* "SDL.texture.opengles2.texture" (number) - the GLuint texture associated with the texture
|
||||
* "SDL.texture.opengles2.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture
|
||||
* "SDL.texture.opengles2.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture
|
||||
* "SDL.texture.opengles2.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture
|
||||
* ```
|
||||
*
|
||||
* \param texture the texture to query
|
||||
|
||||
@@ -938,58 +938,58 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
|
||||
*
|
||||
* On Android:
|
||||
* ```
|
||||
* "SDL.window.android.window" - the ANativeWindow associated with the window
|
||||
* "SDL.window.android.surface" - the EGLSurface associated with the window
|
||||
* "SDL.window.android.window" (pointer) - the ANativeWindow associated with the window
|
||||
* "SDL.window.android.surface" (pointer) - the EGLSurface associated with the window
|
||||
* ```
|
||||
*
|
||||
* On iOS:
|
||||
* ```
|
||||
* "SDL.window.uikit.window" - the (__unsafe_unretained) UIWindow associated with the window
|
||||
* "SDL.window.uikit.metal_view_tag" - the NSInteger tag assocated with metal views on the window
|
||||
* "SDL.window.uikit.window" (pointer) - the (__unsafe_unretained) UIWindow associated with the window
|
||||
* "SDL.window.uikit.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window
|
||||
* ```
|
||||
*
|
||||
* On KMS/DRM:
|
||||
* ```
|
||||
* "SDL.window.kmsdrm.dev_index" - the device index associated with the window (e.g. the X in /dev/dri/cardX)
|
||||
* "SDL.window.kmsdrm.drm_fd" - the DRM FD associated with the window
|
||||
* "SDL.window.kmsdrm.gbm_dev" - the GBM device associated with the window
|
||||
* "SDL.window.kmsdrm.dev_index" (number) - the device index associated with the window (e.g. the X in /dev/dri/cardX)
|
||||
* "SDL.window.kmsdrm.drm_fd" (number) - the DRM FD associated with the window
|
||||
* "SDL.window.kmsdrm.gbm_dev" (pointer) - the GBM device associated with the window
|
||||
* ```
|
||||
*
|
||||
* On macOS:
|
||||
* ```
|
||||
* "SDL.window.cocoa.window" - the (__unsafe_unretained) NSWindow associated with the window
|
||||
* "SDL.window.cocoa.metal_view_tag" - the NSInteger tag assocated with metal views on the window
|
||||
* "SDL.window.cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window
|
||||
* "SDL.window.cocoa.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window
|
||||
* ```
|
||||
*
|
||||
* On Vivante:
|
||||
* ```
|
||||
* "SDL.window.vivante.display" - the EGLNativeDisplayType associated with the window
|
||||
* "SDL.window.vivante.window" - the EGLNativeWindowType associated with the window
|
||||
* "SDL.window.vivante.surface" - the EGLSurface associated with the window
|
||||
* "SDL.window.vivante.display" (pointer) - the EGLNativeDisplayType associated with the window
|
||||
* "SDL.window.vivante.window" (pointer) - the EGLNativeWindowType associated with the window
|
||||
* "SDL.window.vivante.surface" (pointer) - the EGLSurface associated with the window
|
||||
* ```
|
||||
*
|
||||
* On UWP:
|
||||
* ```
|
||||
* "SDL.window.winrt.window" - the IInspectable CoreWindow associated with the window
|
||||
* "SDL.window.winrt.window" (pointer) - the IInspectable CoreWindow associated with the window
|
||||
* ```
|
||||
*
|
||||
* On Windows:
|
||||
* ```
|
||||
* "SDL.window.win32.hwnd" - the HWND associated with the window
|
||||
* "SDL.window.win32.hdc" - the HDC associated with the window
|
||||
* "SDL.window.win32.instance" - the HINSTANCE associated with the window
|
||||
* "SDL.window.win32.hwnd" (pointer) - the HWND associated with the window
|
||||
* "SDL.window.win32.hdc" (pointer) - the HDC associated with the window
|
||||
* "SDL.window.win32.instance" (pointer) - the HINSTANCE associated with the window
|
||||
* ```
|
||||
*
|
||||
* On Wayland:
|
||||
* ```
|
||||
* "SDL.window.wayland.registry" - the wl_registry associated with the window
|
||||
* "SDL.window.wayland.display" - the wl_display associated with the window
|
||||
* "SDL.window.wayland.surface" - the wl_surface associated with the window
|
||||
* "SDL.window.wayland.egl_window" - the wl_egl_window associated with the window
|
||||
* "SDL.window.wayland.xdg_surface" - the xdg_surface associated with the window
|
||||
* "SDL.window.wayland.xdg_toplevel" - the xdg_toplevel role associated with the window
|
||||
* "SDL.window.wayland.xdg_popup" - the xdg_popup role associated with the window
|
||||
* "SDL.window.wayland.xdg_positioner" - the xdg_positioner associated with the window, in popup mode
|
||||
* "SDL.window.wayland.registry" (pointer) - the wl_registry associated with the window
|
||||
* "SDL.window.wayland.display" (pointer) - the wl_display associated with the window
|
||||
* "SDL.window.wayland.surface" (pointer) - the wl_surface associated with the window
|
||||
* "SDL.window.wayland.egl_window" (pointer) - the wl_egl_window associated with the window
|
||||
* "SDL.window.wayland.xdg_surface" (pointer) - the xdg_surface associated with the window
|
||||
* "SDL.window.wayland.xdg_toplevel" (pointer) - the xdg_toplevel role associated with the window
|
||||
* "SDL.window.wayland.xdg_popup" (pointer) - the xdg_popup role associated with the window
|
||||
* "SDL.window.wayland.xdg_positioner" (pointer) - the xdg_positioner associated with the window, in popup mode
|
||||
* ```
|
||||
*
|
||||
* Note: The xdg_* window objects do not internally persist across window show/hide calls.
|
||||
@@ -997,9 +997,9 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
|
||||
*
|
||||
* On X11:
|
||||
* ```
|
||||
* "SDL.window.x11.display" - the X11 Display associated with the window
|
||||
* "SDL.window.x11.screen" - the screen number associated with the window
|
||||
* "SDL.window.x11.window" - the X11 Window associated with the window
|
||||
* "SDL.window.x11.display" (pointer) - the X11 Display associated with the window
|
||||
* "SDL.window.x11.screen" (number) - the screen number associated with the window
|
||||
* "SDL.window.x11.window" (number) - the X11 Window associated with the window
|
||||
* ```
|
||||
*
|
||||
* \param window the window to query
|
||||
|
||||
Reference in New Issue
Block a user