geemili
/
SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sync wiki -> headers.

main
Ryan C. Gordon 2023-11-13 13:03:42 -05:00
parent e5ffd6d8eb
commit 8766aa39d6
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
4 changed files with 78 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
include/SDL3/SDL_pen.h
View File

@ -147,15 +147,13 @@ typedef enum
/**
* Retrieves all pens that are connected to the system.
*
* Yields an array of ::SDL_PenID values. These identify and track pens throughout a session.
* To track pens across sessions (program restart), use ::SDL_GUID .
* Yields an array of ::SDL_PenID values. These identify and track pens
* throughout a session. To track pens across sessions (program restart), use
* ::SDL_GUID .
*
* \param[out] count The number of pens in the array (number of array elements minus 1, i.e., not
* counting the terminator 0).
*
* \returns A 0 terminated array of ::SDL_PenID values, or NULL on error.
* The array must be freed with ::SDL_free().
* On a NULL return, ::SDL_GetError() is set.
* \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
* array must be freed with ::SDL_free(). On a NULL return,
* ::SDL_GetError() is set.
*
* \since This function is available since SDL 3.TBD
*/
@ -168,15 +166,11 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
* default values.
*
* \param instance_id The pen to query.
* \param[out] x Out-mode parameter for pen x coordinate. May be NULL.
* \param[out] y Out-mode parameter for pen y coordinate. May be NULL.
* \param[out] axes Out-mode parameter for axis information. May be null. The axes are in the same order as for
* ::SDL_PenAxis .
* \param num_axes Maximum number of axes to write to "axes".
*
* \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK etc.),
* possibly ::SDL_PEN_DOWN_MASK, and exactly one of
* ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see ::SDL_GetError()).
* \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
* etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
* ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
* ::SDL_GetError()).
*
* \since This function is available since SDL 3.TBD
*/
@ -186,12 +180,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x,
* Retrieves an ::SDL_PenID for the given ::SDL_GUID.
*
* \param guid A pen GUID.
*
* \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching SDL_PenID.
* \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
* SDL_PenID.
*
* \since This function is available since SDL 3.TBD
*
* \sa SDL_GUID()
* \sa SDL_GUID
*/
extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
@ -199,25 +193,24 @@ extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
* Retrieves the ::SDL_GUID for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
*
* \returns The corresponding pen GUID; persistent across multiple sessions.
* If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
* If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
*
* \since This function is available since SDL 3.TBD
*
* \sa SDL_PenForID()
* \sa SDL_PenForID
*/
extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
/**
* Checks whether a pen is still attached.
*
* If a pen is detached, it will not show up for ::SDL_GetPens().
* Other operations will still be available but may return default values.
* If a pen is detached, it will not show up for ::SDL_GetPens(). Other
* operations will still be available but may return default values.
*
* \param instance_id A pen ID.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is attached, or
* SDL_FALSE otherwise.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
* attached, or SDL_FALSE otherwise.
*
* \since This function is available since SDL 3.TBD
*/
@ -227,14 +220,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
* Retrieves a human-readable description for a ::SDL_PenID.
*
* \param instance_id The pen to query.
*
* \returns A string that contains the name of the pen, intended for human consumption.
* The string might or might not be localised, depending on platform settings.
* It is not guaranteed to be unique; use ::SDL_GetPenGUID() for (best-effort)
* unique identifiers.
* The pointer is managed by the SDL pen subsystem and must not be deallocated.
* The pointer remains valid until SDL is shut down.
* Returns NULL on error (cf. ::SDL_GetError())
* \returns A string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use
* ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
* pointer is managed by the SDL pen subsystem and must not be
* deallocated. The pointer remains valid until SDL is shut down.
* Returns NULL on error (cf. ::SDL_GetError())
*
* \since This function is available since SDL 3.TBD
*/
@ -254,10 +246,7 @@ typedef struct SDL_PenCapabilityInfo
* Retrieves capability flags for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \param[out] capabilities Detail information about pen capabilities, such as the number of buttons
*
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES. Returns 0 on error
* (cf. ::SDL_GetError())
* \returns a set of capability flags, cf. \link SDL_PEN_CAPABILITIES
*
* \since This function is available since SDL 3.TBD
*/
@ -267,10 +256,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL
* Retrieves the pen type for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error. Note that the pen type does not
* dictate whether the pen tip is ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a pen
* is being used for drawing or in eraser mode, check either the pen tip on ::SDL_EVENT_PEN_DOWN, or the
* flag ::SDL_PEN_ERASER_MASK in the pen state.
* \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
* Note that the pen type does not dictate whether the pen tip is
* ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
* pen is being used for drawing or in eraser mode, check either the
* pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
* in the pen state.
*
* \since This function is available since SDL 3.TBD
*/
extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);

31
include/SDL3/SDL_properties.h
View File

@ -231,7 +231,8 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const
*
* \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.
* \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.
*
@ -250,7 +251,8 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr
* \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 pointer 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
@ -271,7 +273,8 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char
* \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.
* \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.
*
@ -285,12 +288,14 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props
/**
* 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.
* 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.
* \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.
*
@ -304,12 +309,14 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con
/**
* 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.
* 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.
* \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.
*
@ -323,12 +330,14 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const
/**
* Get a boolean property on a set of properties
*
* You can use SDL_GetPropertyType() to query whether the property exists and is a boolean property.
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a boolean 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.
* \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.
*
@ -356,10 +365,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props,
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.
* 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

5
include/SDL3/SDL_render.h
View File

@ -310,6 +310,7 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
* Get the properties associated with a renderer.
*
* The following properties are provided by SDL:
*
* ```
* "SDL.renderer.d3d9.device" (pointer) - the IDirect3DDevice9 associated with the renderer
* "SDL.renderer.d3d11.device" (pointer) - the ID3D11Device associated with the renderer
@ -423,6 +424,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
* The following properties are provided by SDL:
*
* With the direct3d11 renderer:
*
* ```
* "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
@ -430,6 +432,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
* ```
*
* With the direct3d12 renderer:
*
* ```
* "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
@ -437,6 +440,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
* ```
*
* With the opengl renderer:
*
* ```
* "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
@ -446,6 +450,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
* ```
*
* With the opengles2 renderer:
*
* ```
* "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

21
include/SDL3/SDL_video.h
View File

@ -868,28 +868,33 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *tit
extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, Uint32 flags);
/**
* Create an SDL window from properties representing an existing native window.
* Create an SDL window from properties representing an existing native
* window.
*
* These are the supported properties:
*
* On macOS:
*
* ```
* "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window
* "cocoa.view" (pointer) - optional, the (__unsafe_unretained) NSView associated with the window, defaults to [window contentView]
* ```
*
* On Windows:
*
* ```
* "win32.hwnd" (pointer) - the HWND associated with the window
* "win32.pixel_format_hwnd" (pointer) - optional, another window to share pixel format with, useful for OpenGL windows
* ```
*
* On X11:
*
* ```
* "x11.window" (number) - the X11 Window associated with the window
* ```
*
* On all platforms:
*
* ```
* "opengl" (boolean) - optional, true if the window will be used with OpenGL rendering
* "vulkan" (boolean) - optional, true if the window will be used with Vulkan rendering
@ -957,18 +962,21 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
* The following properties are provided by SDL:
*
* On Android:
*
* ```
* "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" (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" (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
@ -976,12 +984,14 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
* ```
*
* On macOS:
*
* ```
* "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" (pointer) - the EGLNativeDisplayType associated with the window
* "SDL.window.vivante.window" (pointer) - the EGLNativeWindowType associated with the window
@ -989,11 +999,13 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
* ```
*
* On UWP:
*
* ```
* "SDL.window.winrt.window" (pointer) - the IInspectable CoreWindow associated with the window
* ```
*
* On Windows:
*
* ```
* "SDL.window.win32.hwnd" (pointer) - the HWND associated with the window
* "SDL.window.win32.hdc" (pointer) - the HDC associated with the window
@ -1001,6 +1013,7 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
* ```
*
* On Wayland:
*
* ```
* "SDL.window.wayland.registry" (pointer) - the wl_registry associated with the window
* "SDL.window.wayland.display" (pointer) - the wl_display associated with the window
@ -1012,10 +1025,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *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.
* They will be null if the window is hidden and must be queried each time it is shown.
* Note: The xdg_* window objects do not internally persist across window
* show/hide calls. They will be null if the window is hidden and must be
* queried each time it is shown.
*
* On X11:
*
* ```
* "SDL.window.x11.display" (pointer) - the X11 Display associated with the window
* "SDL.window.x11.screen" (number) - the screen number associated with the window