Sync SDL3 wiki -> header

include/SDL3/SDL_render.h

@@ -256,6 +256,31 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, co
  * \sa SDL_DestroyRenderer
  * \sa SDL_GetRendererInfo
  */
+
+/**
+ * Create a 2D rendering context for a window, with the specified properties.
+ *
+ * These are the supported properties:
+ *
+ * - "window" (pointer) - the window where rendering is displayed
+ * - "surface" (pointer) - the surface where rendering is displayed, if you
+ *   want a software renderer without a window
+ * - "name" (string) - the name of the rendering driver to use, if a specific
+ *   one is desired
+ * - "present_vsync" (boolean) - true if you want present synchronized with
+ *   the refresh rate
+ *
+ * \param props the properties to use
+ * \returns a valid rendering context or NULL if there was an error; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateRenderer
+ * \sa SDL_CreateSoftwareRenderer
+ * \sa SDL_DestroyRenderer
+ * \sa SDL_GetRendererInfo
+ */
 extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_PropertiesID props);
 
 /**
@@ -337,6 +362,28 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
  * \sa SDL_GetProperty
  * \sa SDL_SetProperty
  */
+
+/**
+ * Get the properties associated with a renderer.
+ *
+ * The following read-only 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
+ * "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
+ * \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);
 
 /**
@@ -481,6 +528,73 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  * \sa SDL_QueryTexture
  * \sa SDL_UpdateTexture
  */
+
+/**
+ * Create a texture for a rendering context with the specified properties.
+ *
+ * These are the supported properties:
+ *
+ * - "format" (number) - one of the enumerated values in SDL_PixelFormatEnum,
+ *   defaults to the best RGBA format for the renderer
+ * - "access" (number) - one of the enumerated values in SDL_TextureAccess,
+ *   defaults to SDL_TEXTUREACCESS_STATIC
+ * - "width" (number) - the width of the texture in pixels, required
+ * - "height" (number) - the height of the texture in pixels, required
+ *
+ * With the direct3d11 renderer:
+ *
+ * - "d3d11.texture" (pointer) - the ID3D11Texture2D associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d11.texture_v" (pointer) - the ID3D11Texture2D associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ *
+ * With the direct3d12 renderer:
+ *
+ * - "d3d12.texture" (pointer) - the ID3D12Resource associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d12.texture_v" (pointer) - the ID3D12Resource associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ *
+ * With the opengl renderer:
+ *
+ * - "opengl.texture" (number) - the GLuint texture associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "opengl.texture_uv" (number) - the GLuint texture associated with the UV
+ *   plane of an NV12 texture, if you want to wrap an existing texture.
+ * - "opengl.texture_u" (number) - the GLuint texture associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengl.texture_v" (number) - the GLuint texture associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ *
+ * With the opengles2 renderer:
+ *
+ * - "opengles2.texture" (number) - the GLuint texture associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_uv" (number) - the GLuint texture associated with the
+ *   UV plane of an NV12 texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_u" (number) - the GLuint texture associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_v" (number) - the GLuint texture associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ *
+ * \param renderer the rendering context
+ * \param props the properties to use
+ * \returns a pointer to the created texture or NULL if no rendering context
+ *          was active, the format was unsupported, or the width or height
+ *          were out of range; call SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateTextureFromSurface
+ * \sa SDL_CreateTexture
+ * \sa SDL_DestroyTexture
+ * \sa SDL_QueryTexture
+ * \sa SDL_UpdateTexture
+ */
 extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props);
 
 /**
@@ -527,6 +641,65 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Rendere
  * \sa SDL_GetProperty
  * \sa SDL_SetProperty
  */
+
+/**
+ * Get the properties associated with a texture.
+ *
+ * The following read-only 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
+ * - "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" (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" (number) - the GLuint texture associated
+ *   with the texture
+ * - "SDL.texture.opengl.texture_uv" (number) - the GLuint texture associated
+ *   with the UV plane of an NV12 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" (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
+ * \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);
 
 /**

include/SDL3/SDL_video.h

@@ -861,6 +861,81 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, in
  * \sa SDL_CreateWindow
  * \sa SDL_DestroyWindow
  */
+
+/**
+ * Create a window with the specified properties.
+ *
+ * These are the supported properties:
+ *
+ * - "always-on-top" (boolean) - true if the window should be always on top
+ * - "borderless" (boolean) - true if the window has no window decoration
+ * - "focusable" (boolean) - true if the window should accept keyboard input
+ *   (defaults true)
+ * - "fullscreen" (boolean) - true if the window should start in fullscreen
+ *   mode at desktop resolution
+ * - "height" (number) - the height of the window
+ * - "hidden" (boolean) - true if the window should start hidden
+ * - "high-pixel-density" (boolean) - true if the window uses a high pixel
+ *   density buffer if possible
+ * - "maximized" (boolean) - true if the window should start maximized
+ * - "menu" (boolean) - true if the window is a popup menu
+ * - "metal" (string) - true if the window will be used with Metal rendering
+ * - "minimized" (boolean) - true if the window should start minimized
+ * - "mouse-grabbed" (boolean) - true if the window starts with grabbed mouse
+ *   focus
+ * - "opengl" (boolean) - true if the window will be used with OpenGL
+ *   rendering
+ * - "parent" (pointer) - an SDL_Window that will be the parent of this
+ *   window, required for windows with the "toolip" and "menu" properties
+ * - "resizable" (boolean) - true if the window should be resizable
+ * - "title" (string) - the title of the window, in UTF-8 encoding
+ * - "transparent" (string) - true if the window show transparent in the areas
+ *   with alpha of 0
+ * - "tooltip" (boolean) - true if the window is a tooltip
+ * - "utility" (boolean) - true if the window is a utility window, not showing
+ *   in the task bar and window list
+ * - "vulkan" (string) - true if the window will be used with Vulkan rendering
+ * - "width" (number) - the width of the window
+ * - "x" (number) - the x position of the window, or `SDL_WINDOWPOS_CENTERED`,
+ *   defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for
+ *   windows with the "parent" property set.
+ * - "y" (number) - the y position of the window, or `SDL_WINDOWPOS_CENTERED`,
+ *   defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for
+ *   windows with the "parent" property set.
+ *
+ * On macOS:
+ *
+ * - "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated
+ *   with the window, if you want to wrap an existing window.
+ * - "cocoa.view" (pointer) - the (__unsafe_unretained) NSView associated with
+ *   the window, defaults to [window contentView]
+ *
+ * On Windows:
+ *
+ * - "win32.hwnd" (pointer) - the HWND associated with the window, if you want
+ *   to wrap an existing 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, if you
+ *   want to wrap an existing window.
+ *
+ * The SDL_Window is implicitly shown if the "hidden" property is not set.
+ *
+ * Windows with the "tooltip" and "menu" properties are popup windows and have
+ * the behaviors and guidelines outlined in `SDL_CreatePopupWindow()`.
+ *
+ * \param props the properties to use
+ * \returns the window that was created or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreateWindow
+ * \sa SDL_DestroyWindow
+ */
 extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithProperties(SDL_PropertiesID props);
 
 /**
@@ -981,6 +1056,97 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
  * \sa SDL_GetProperty
  * \sa SDL_SetProperty
  */
+
+/**
+ * Get the properties associated with a window.
+ *
+ * The following read-only 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
+ * "SDL.window.kmsdrm.gbm_dev" (pointer) - the GBM device associated with the 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
+ * "SDL.window.vivante.surface" (pointer) - the EGLSurface associated with the 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
+ * "SDL.window.win32.instance" (pointer) - the HINSTANCE associated with the 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
+ * "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. 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
+ * "SDL.window.x11.window" (number) - the X11 Window associated with the window
+ * ```
+ *
+ * \param window the window 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_GetWindowProperties(SDL_Window *window);
 
 /**