mirrors
/
SDL
mirror of https://github.com/libsdl-org/SDL
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync wiki -> headers.

This commit is contained in:
Ryan C. Gordon 2023-02-24 11:49:41 -05:00
parent d748a454a8
commit 0598ecc150
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
12 changed files with 60 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
include/SDL3/SDL_assert.h
View File

@ -137,7 +137,9 @@ typedef struct SDL_AssertData
#if (SDL_ASSERT_LEVEL > 0) #if (SDL_ASSERT_LEVEL > 0)
/** /**
* Never call this directly. Use the SDL_assert* macros. * Never call this directly.
*
* Use the SDL_assert* macros.
* *
* \param data assert data structure * \param data assert data structure
* \param func function name * \param func function name

6
include/SDL3/SDL_audio.h
View File

@ -811,7 +811,7 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
/** /**
* Clear any pending data in the stream without converting it * Clear any pending data in the stream without converting it
* *
* \param stream The audio stream to clear * \param stream The audio stream to clear
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@ -830,6 +830,7 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
* Free an audio stream * Free an audio stream
* *
* \param stream The audio stream to free * \param stream The audio stream to free
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_CreateAudioStream * \sa SDL_CreateAudioStream
@ -1149,7 +1150,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
* \param dst_channels The number of channels of the desired audio output * \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output * \param dst_rate The sampling rate of the desired audio output
* \param dst_data Will be filled with a pointer to converted audio data, * \param dst_data Will be filled with a pointer to converted audio data,
* which should be freed with SDL_free(). On error, it will be NULL. * which should be freed with SDL_free(). On error, it will be
* NULL.
* \param dst_len Will be filled with the len of dst_data * \param dst_len Will be filled with the len of dst_data
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.

1
include/SDL3/SDL_error.h
View File

@ -148,6 +148,7 @@ typedef enum
SDL_UNSUPPORTED, SDL_UNSUPPORTED,
SDL_LASTERROR SDL_LASTERROR
} SDL_errorcode; } SDL_errorcode;
/** /**
* SDL_Error() * SDL_Error()
* *

3
include/SDL3/SDL_joystick.h
View File

@ -918,7 +918,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U
* DualShock 4 controller. * DualShock 4 controller.
* *
* \param joystick The joystick to query * \param joystick The joystick to query
* \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE
* otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

2
include/SDL3/SDL_locale.h
View File

@ -84,7 +84,7 @@ typedef struct SDL_Locale
* preferred locales. * preferred locales.
* *
* \returns array of locales, terminated with a locale with a NULL language * \returns array of locales, terminated with a locale with a NULL language
* field. Will return NULL on error. * field. Will return NULL on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

2
include/SDL3/SDL_main.h
View File

@ -192,7 +192,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
* \param reserved should be NULL (reserved for future use, will probably be * \param reserved should be NULL (reserved for future use, will probably be
* platform-specific then) * platform-specific then)
* \returns the return value from mainFunction: 0 on success, -1 on failure; * \returns the return value from mainFunction: 0 on success, -1 on failure;
* SDL_GetError() might have more information on the failure * SDL_GetError() might have more information on the failure
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

34
include/SDL3/SDL_render.h
View File

@ -235,9 +235,9 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
* need a specific renderer, specify NULL and SDL will attempt to chooes the * need a specific renderer, specify NULL and SDL will attempt to chooes the
* best option for you, based on what is available on the user's system. * best option for you, based on what is available on the user's system.
* *
* By default the rendering size matches the window size in screen coordinates, * By default the rendering size matches the window size in screen
* but you can call SDL_SetRenderLogicalPresentation() to enable high DPI * coordinates, but you can call SDL_SetRenderLogicalPresentation() to enable
* rendering or change the content size and scaling options. * high DPI rendering or change the content size and scaling options.
* *
* \param window the window where rendering is displayed * \param window the window where rendering is displayed
* \param name the name of the rendering driver to initialize, or NULL to * \param name the name of the rendering driver to initialize, or NULL to
@ -337,8 +337,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderWindowSize(SDL_Renderer *renderer, int
/** /**
* Get the output size in pixels of a rendering context. * Get the output size in pixels of a rendering context.
* *
* This returns the true output size in pixels, ignoring any render targets * This returns the true output size in pixels, ignoring any render targets or
* or logical size and presentation. * logical size and presentation.
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param w a pointer filled in with the width in pixels * \param w a pointer filled in with the width in pixels
@ -355,9 +355,9 @@ extern DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int
/** /**
* Get the current output size in pixels of a rendering context. * Get the current output size in pixels of a rendering context.
* *
* If a rendering target is active, this will return the size of the * If a rendering target is active, this will return the size of the rendering
* rendering target in pixels, otherwise if a logical size is set, it will * target in pixels, otherwise if a logical size is set, it will return the
* return the logical size, otherwise it will return the value of * logical size, otherwise it will return the value of
* SDL_GetRenderOutputSize(). * SDL_GetRenderOutputSize().
* *
* \param renderer the rendering context * \param renderer the rendering context
@ -610,7 +610,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *u
* *
* \param texture the texture to query. * \param texture the texture to query.
* \returns the pointer associated with the texture, or NULL if the texture is * \returns the pointer associated with the texture, or NULL if the texture is
* not valid. * not valid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -836,9 +836,9 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer)
/** /**
* Set a device independent resolution and presentation mode for rendering. * Set a device independent resolution and presentation mode for rendering.
* *
* This function sets the width and height of the logical rendering output. * This function sets the width and height of the logical rendering output. A
* A render target is created at the specified size and used for rendering * render target is created at the specified size and used for rendering and
* and then copied to the output during presentation. * then copied to the output during presentation.
* *
* When a renderer is created, the logical size is set to match the window * When a renderer is created, the logical size is set to match the window
* size in screen coordinates. The actual output size may be higher pixel * size in screen coordinates. The actual output size may be higher pixel
@ -869,8 +869,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *rende
/** /**
* Get device independent resolution and presentation mode for rendering. * Get device independent resolution and presentation mode for rendering.
* *
* This function gets the width and height of the logical rendering output, * This function gets the width and height of the logical rendering output, or
* or the output size in pixels if a logical resolution is not enabled. * the output size in pixels if a logical resolution is not enabled.
* *
* \param renderer the rendering context * \param renderer the rendering context
* \param w an int to be filled with the width * \param w an int to be filled with the width
@ -910,8 +910,10 @@ extern DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *render
* \param renderer the rendering context * \param renderer the rendering context
* \param x the x coordinate in render coordinates * \param x the x coordinate in render coordinates
* \param y the y coordinate in render coordinates * \param y the y coordinate in render coordinates
* \param window_x a pointer filled with the x coordinate in window coordinates * \param window_x a pointer filled with the x coordinate in window
* \param window_y a pointer filled with the y coordinate in window coordinates * coordinates
* \param window_y a pointer filled with the y coordinate in window
* coordinates
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

16
include/SDL3/SDL_shape.h
View File

@ -72,8 +72,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,un
* Return whether the given window is a shaped window. * Return whether the given window is a shaped window.
* *
* \param window The window to query for being shaped. * \param window The window to query for being shaped.
* \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE
* the window is unshaped or NULL. * if the window is unshaped or NULL.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -117,8 +117,8 @@ typedef struct SDL_WindowShapeMode {
* \param shape A surface encoding the desired shape for the window. * \param shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window. * \param shape_mode The parameters to set for the shaped window.
* \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape * \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
* not reference a valid shaped window. * not reference a valid shaped window.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -134,10 +134,10 @@ extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *s
* \param shape_mode An empty shape-mode structure to fill, or NULL to check * \param shape_mode An empty shape-mode structure to fill, or NULL to check
* whether the window has a shape. * whether the window has a shape.
* \returns 0 if the window has a shape and, provided shape_mode was not NULL, * \returns 0 if the window has a shape and, provided shape_mode was not NULL,
* shape_mode has been filled with the mode data, * shape_mode has been filled with the mode data,
* SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
* window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
* shapeable window currently lacking a shape. * shapeable window currently lacking a shape.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

4
include/SDL3/SDL_surface.h
View File

@ -797,6 +797,8 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* Perform a fast, low quality, stretch blit between two surfaces of the same * Perform a fast, low quality, stretch blit between two surfaces of the same
* format. * format.
* *
* **WARNING**: Please use SDL_BlitScaled() instead.
*
* \param src the SDL_Surface structure to be copied from * \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be * \param srcrect the SDL_Rect structure representing the rectangle to be
* copied * copied
@ -806,8 +808,6 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* Please use SDL_BlitScaled() instead.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,

3
include/SDL3/SDL_system.h
View File

@ -385,7 +385,8 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
* *
* If external storage is currently unavailable, this will return 0. * If external storage is currently unavailable, this will return 0.
* *
* \param state filled with the current state of external storage. 0 if external storage is currently unavailable. * \param state filled with the current state of external storage. 0 if
* external storage is currently unavailable.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *

3
include/SDL3/SDL_touch.h
View File

@ -121,7 +121,8 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t
* *
* \param touchID the ID of a touch device * \param touchID the ID of a touch device
* \returns the number of active fingers for a given touch device on success * \returns the number of active fingers for a given touch device on success
* or a negative error code on failure; call SDL_GetError() for more information. * or a negative error code on failure; call SDL_GetError() for more
* information.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

26
include/SDL3/SDL_video.h
View File

@ -392,6 +392,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
* Get a list of fullscreen display modes available on a display. * Get a list of fullscreen display modes available on a display.
* *
* The display modes are sorted in this priority: * The display modes are sorted in this priority:
*
* - screen_w -> largest to smallest * - screen_w -> largest to smallest
* - screen_h -> largest to smallest * - screen_h -> largest to smallest
* - pixel_w -> largest to smallest * - pixel_w -> largest to smallest
@ -402,9 +403,9 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query
* \param count a pointer filled in with the number of displays returned * \param count a pointer filled in with the number of displays returned
* \returns a NULL terminated array of display mode pointers which should be freed * \returns a NULL terminated array of display mode pointers which should be
* with SDL_free(), or NULL on error; call SDL_GetError() for more * freed with SDL_free(), or NULL on error; call SDL_GetError() for
* details. * more details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -425,8 +426,11 @@ extern DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayModes(SD
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query
* \param w the width in pixels of the desired display mode * \param w the width in pixels of the desired display mode
* \param h the height in pixels of the desired display mode * \param h the height in pixels of the desired display mode
* \param refresh_rate the refresh rate of the desired display mode, or 0.0f for the desktop refresh rate * \param refresh_rate the refresh rate of the desired display mode, or 0.0f
* \returns a pointer to the closest display mode equal to or larger than the desired mode, or NULL on error; call SDL_GetError() for more information. * for the desktop refresh rate
* \returns a pointer to the closest display mode equal to or larger than the
* desired mode, or NULL on error; call SDL_GetError() for more
* information.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -525,7 +529,9 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window
* SDL_SetWindowSize(). * SDL_SetWindowSize().
* *
* \param window the window to affect * \param window the window to affect
* \param mode a pointer to the display mode to use, which can be NULL for desktop mode, or one of the fullscreen modes returned by SDL_GetFullscreenDisplayModes(). * \param mode a pointer to the display mode to use, which can be NULL for
* desktop mode, or one of the fullscreen modes returned by
* SDL_GetFullscreenDisplayModes().
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@ -822,8 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, in
* The window size in screen coordinates may differ from the size in pixels if * The window size in screen coordinates may differ from the size in pixels if
* the window is on a high density display (one with an OS scaling factor). * the window is on a high density display (one with an OS scaling factor).
* *
* This only affects the size of the window when not in fullscreen mode. To change * This only affects the size of the window when not in fullscreen mode. To
* the fullscreen mode of a window, use SDL_SetWindowFullscreenMode() * change the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
* *
* \param window the window to change * \param window the window to change
* \param w the width of the window, must be > 0 * \param w the width of the window, must be > 0
@ -1127,8 +1133,8 @@ extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
/** /**
* Set a window's fullscreen state. * Set a window's fullscreen state.
* *
* By default a window in fullscreen state uses fullscreen desktop mode, * By default a window in fullscreen state uses fullscreen desktop mode, but a
* but a specific display mode can be set using SDL_SetWindowFullscreenMode(). * specific display mode can be set using SDL_SetWindowFullscreenMode().
* *
* \param window the window to change * \param window the window to change
* \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode * \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode