Sync wiki -> headers.

This commit is contained in:
Ryan C. Gordon 2023-01-25 12:58:29 -05:00
parent 01cba48d18
commit 197340ea1c
No known key found for this signature in database
GPG key ID: FA148B892AB48044
18 changed files with 291 additions and 273 deletions

View file

@ -407,8 +407,8 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
* Open a specific audio device. * Open a specific audio device.
* *
* Passing in a `device` name of NULL requests the most reasonable default. * Passing in a `device` name of NULL requests the most reasonable default.
* The `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but * The `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(),
* some drivers allow arbitrary and driver-specific strings, such as a * but some drivers allow arbitrary and driver-specific strings, such as a
* hostname/IP address for a remote audio server, or a filename in the * hostname/IP address for a remote audio server, or a filename in the
* diskaudio driver. * diskaudio driver.
* *
@ -545,13 +545,13 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice
/** /**
* Use this function to play audio on a specified device. * Use this function to play audio on a specified device.
* *
* Newly-opened audio devices start in the paused state, so you must * Newly-opened audio devices start in the paused state, so you must call this
* call this function after opening the specified audio * function after opening the specified audio device to start playing sound.
* device to start playing sound. This allows you to safely initialize data * This allows you to safely initialize data for your callback function after
* for your callback function after opening the audio device. Silence will be * opening the audio device. Silence will be written to the audio device while
* written to the audio device while paused, and the audio callback is * paused, and the audio callback is guaranteed to not be called. Pausing one
* guaranteed to not be called. Pausing one device does not prevent other * device does not prevent other unpaused devices from running their
* unpaused devices from running their callbacks. * callbacks.
* *
* \param dev a device opened by SDL_OpenAudioDevice() * \param dev a device opened by SDL_OpenAudioDevice()
* *
@ -567,11 +567,10 @@ extern DECLSPEC void SDLCALL SDL_PlayAudioDevice(SDL_AudioDeviceID dev);
/** /**
* Use this function to pause audio playback on a specified device. * Use this function to pause audio playback on a specified device.
* *
* This function pauses the audio callback processing for a given * This function pauses the audio callback processing for a given device.
* device. Silence will be written to the audio device while paused, and * Silence will be written to the audio device while paused, and the audio
* the audio callback is guaranteed to not be called. * callback is guaranteed to not be called. Pausing one device does not
* Pausing one device does not prevent other unpaused devices from running * prevent other unpaused devices from running their callbacks.
* their callbacks.
* *
* If you just need to protect a few variables from race conditions vs your * If you just need to protect a few variables from race conditions vs your
* callback, you shouldn't pause the audio device, as it will lead to dropouts * callback, you shouldn't pause the audio device, as it will lead to dropouts
@ -1125,9 +1124,10 @@ 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_len Will be filled with the len of dst_data * \param dst_len Will be filled with the len of dst_data
* \param dst_data Will be filled with a pointer to converted audio data, which should be freed with SDL_free(). * \param dst_data Will be filled with a pointer to converted audio data,
* * which should be freed with SDL_free().
* \returns 0 on success or a negative error code on failure. On error, *dst_data will be NULL and so not allocated. * \returns 0 on success or a negative error code on failure. On error,
* *dst_data will be NULL and so not allocated.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

View file

@ -879,8 +879,8 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
* As this function may implicitly call SDL_PumpEvents(), you can only call * As this function may implicitly call SDL_PumpEvents(), you can only call
* this function in the thread that initialized the video subsystem. * this function in the thread that initialized the video subsystem.
* *
* The timeout is not guaranteed, the actual wait time could be longer * The timeout is not guaranteed, the actual wait time could be longer due to
* due to system scheduling. * system scheduling.
* *
* \param event the SDL_Event structure to be filled in with the next event * \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL * from the queue, or NULL

View file

@ -160,11 +160,11 @@ typedef struct SDL_GamepadBinding
* *
* The mapping string has the format "GUID,name,mapping", where GUID is the * The mapping string has the format "GUID,name,mapping", where GUID is the
* string value from SDL_GetJoystickGUIDString(), name is the human readable * string value from SDL_GetJoystickGUIDString(), name is the human readable
* string for the device and mappings are gamepad mappings to joystick * string for the device and mappings are gamepad mappings to joystick ones.
* ones. Under Windows there is a reserved GUID of "xinput" that covers all * Under Windows there is a reserved GUID of "xinput" that covers all XInput
* XInput devices. The mapping format for joystick is: {| |bX |a joystick * devices. The mapping format for joystick is: {| |bX |a joystick button,
* button, index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick * index X |- |hX.Y |hat X with value Y |- |aX |axis X of the joystick |}
* |} Buttons can be used as a gamepad axes and vice versa. * Buttons can be used as a gamepad axes and vice versa.
* *
* This string shows an example of a valid mapping for a gamepad: * This string shows an example of a valid mapping for a gamepad:
* *
@ -262,10 +262,9 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_JoystickGUID gui
* *
* Details about mappings are discussed with SDL_AddGamepadMapping(). * Details about mappings are discussed with SDL_AddGamepadMapping().
* *
* \param gamepad the gamepad you want to get the current * \param gamepad the gamepad you want to get the current mapping for
* mapping for * \returns a string that has the gamepad's mapping or NULL if no mapping is
* \returns a string that has the gamepad's mapping or NULL if no mapping * available; call SDL_GetError() for more information.
* is available; 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.
* *
@ -278,7 +277,9 @@ extern DECLSPEC char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
* Get a list of currently connected gamepads. * Get a list of currently connected gamepads.
* *
* \param count a pointer filled in with the number of gamepads returned * \param count a pointer filled in with the number of gamepads returned
* \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details. * \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -370,8 +371,8 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joystick
* available this function returns 0. * available this function returns 0.
* *
* \param instance_id the joystick instance ID * \param instance_id the joystick instance ID
* \returns the USB vendor ID of the selected gamepad. If called on an * \returns the USB vendor ID of the selected gamepad. If called on an invalid
* invalid index, this function returns zero * index, this function returns zero
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -446,10 +447,12 @@ extern DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID insta
extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id); extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id);
/** /**
* Get the SDL_Gamepad associated with a joystick instance ID, if it has been opened. * Get the SDL_Gamepad associated with a joystick instance ID, if it has been
* opened.
* *
* \param instance_id the joystick instance ID of the gamepad * \param instance_id the joystick instance ID of the gamepad
* \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information. * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been
* opened yet; 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.
*/ */
@ -471,13 +474,13 @@ extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int player_in
/** /**
* Get the implementation-dependent name for an opened gamepad. * Get the implementation-dependent name for an opened gamepad.
* *
* This is the same name as returned by SDL_GetGamepadNameForIndex(), but * This is the same name as returned by SDL_GetGamepadNameForIndex(), but it
* it takes a gamepad identifier instead of the (unstable) device index. * takes a gamepad identifier instead of the (unstable) device index.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad()
* \returns the implementation dependent name for the gamepad, or NULL * \returns the implementation dependent name for the gamepad, or NULL if
* if there is no name or the identifier passed is invalid. * there is no name or the identifier passed is invalid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -489,13 +492,13 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
/** /**
* Get the implementation-dependent path for an opened gamepad. * Get the implementation-dependent path for an opened gamepad.
* *
* This is the same path as returned by SDL_GetGamepadNameForIndex(), but * This is the same path as returned by SDL_GetGamepadNameForIndex(), but it
* it takes a gamepad identifier instead of the (unstable) device index. * takes a gamepad identifier instead of the (unstable) device index.
* *
* \param gamepad a gamepad identifier previously returned by * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad() * SDL_OpenGamepad()
* \returns the implementation dependent path for the gamepad, or NULL * \returns the implementation dependent path for the gamepad, or NULL if
* if there is no path or the identifier passed is invalid. * there is no path or the identifier passed is invalid.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -506,8 +509,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
/** /**
* Get the type of this currently opened gamepad * Get the type of this currently opened gamepad
* *
* This is the same name as returned by SDL_GetGamepadInstanceType(), but * This is the same name as returned by SDL_GetGamepadInstanceType(), but it
* it takes a gamepad identifier instead of the (unstable) device index. * takes a gamepad identifier instead of the (unstable) device index.
* *
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \returns the gamepad type. * \returns the gamepad type.
@ -532,8 +535,8 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
* Set the player index of an opened gamepad. * Set the player index of an opened gamepad.
* *
* \param gamepad the gamepad object to adjust. * \param gamepad the gamepad object to adjust.
* \param player_index Player index to assign to this gamepad, or -1 to * \param player_index Player index to assign to this gamepad, or -1 to clear
* clear the player index and turn off player LEDs. * the player index and turn off player LEDs.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -590,8 +593,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepa
/** /**
* Get the serial number of an opened gamepad, if available. * Get the serial number of an opened gamepad, if available.
* *
* Returns the serial number of the gamepad, or NULL if it is not * Returns the serial number of the gamepad, or NULL if it is not available.
* available.
* *
* \param gamepad the gamepad object to query. * \param gamepad the gamepad object to query.
* \return the serial number, or NULL if unavailable. * \return the serial number, or NULL if unavailable.
@ -619,17 +621,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* Get the underlying joystick from a gamepad * Get the underlying joystick from a gamepad
* *
* This function will give you a SDL_Joystick object, which allows you to use * This function will give you a SDL_Joystick object, which allows you to use
* the SDL_Joystick functions with a SDL_Gamepad object. This would be * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful
* useful for getting a joystick's position at any given time, even if it * for getting a joystick's position at any given time, even if it hasn't
* hasn't moved (moving it would produce an event, which would have the axis' * moved (moving it would produce an event, which would have the axis' value).
* value).
* *
* The pointer returned is owned by the SDL_Gamepad. You should not * The pointer returned is owned by the SDL_Gamepad. You should not call
* call SDL_CloseJoystick() on it, for example, since doing so will likely * SDL_CloseJoystick() on it, for example, since doing so will likely cause
* cause SDL to crash. * SDL to crash.
* *
* \param gamepad the gamepad object that you want to get a * \param gamepad the gamepad object that you want to get a joystick from
* joystick from
* \returns an SDL_Joystick object; call SDL_GetError() for more information. * \returns an SDL_Joystick object; 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.
@ -639,9 +639,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetGamepadJoystick(SDL_Gamepad *gamepa
/** /**
* Set the state of gamepad event processing. * Set the state of gamepad event processing.
* *
* If gamepad events are disabled, you must call SDL_UpdateGamepads() * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
* yourself and check the state of the gamepad when you want gamepad * and check the state of the gamepad when you want gamepad information.
* information.
* *
* \param enabled whether to process gamepad events or not * \param enabled whether to process gamepad events or not
* *
@ -654,11 +653,11 @@ extern DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled);
/** /**
* Query the state of gamepad event processing. * Query the state of gamepad event processing.
* *
* If gamepad events are disabled, you must call SDL_UpdateGamepads() * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
* yourself and check the state of the gamepad when you want gamepad * and check the state of the gamepad when you want gamepad information.
* information.
* *
* \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE otherwise. * \returns SDL_TRUE if gamepad events are being processed, SDL_FALSE
* otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -681,18 +680,18 @@ extern DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
/** /**
* Convert a string into SDL_GamepadAxis enum. * Convert a string into SDL_GamepadAxis enum.
* *
* This function is called internally to translate SDL_Gamepad mapping * This function is called internally to translate SDL_Gamepad mapping strings
* strings for the underlying joystick device into the consistent * for the underlying joystick device into the consistent SDL_Gamepad mapping.
* SDL_Gamepad mapping. You do not normally need to call this function * You do not normally need to call this function unless you are parsing
* unless you are parsing SDL_Gamepad mappings in your own code. * SDL_Gamepad mappings in your own code.
* *
* Note specially that "righttrigger" and "lefttrigger" map to * Note specially that "righttrigger" and "lefttrigger" map to
* `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`, * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
* respectively. * respectively.
* *
* \param str string representing a SDL_Gamepad axis * \param str string representing a SDL_Gamepad axis
* \returns the SDL_GamepadAxis enum corresponding to the input string, * \returns the SDL_GamepadAxis enum corresponding to the input string, or
* or `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -721,8 +720,8 @@ extern DECLSPEC const char* SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis
* *
* \param gamepad a gamepad * \param gamepad a gamepad
* \param axis an axis enum value (one of the SDL_GamepadAxis values) * \param axis an axis enum value (one of the SDL_GamepadAxis values)
* \returns a SDL_GamepadBinding describing the bind. On failure * \returns a SDL_GamepadBinding describing the bind. On failure (like the
* (like the given Controller axis doesn't exist on the device), its * given Controller axis doesn't exist on the device), its
* `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`. * `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -767,14 +766,14 @@ extern DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_Game
/** /**
* Convert a string into an SDL_GamepadButton enum. * Convert a string into an SDL_GamepadButton enum.
* *
* This function is called internally to translate SDL_Gamepad mapping * This function is called internally to translate SDL_Gamepad mapping strings
* strings for the underlying joystick device into the consistent * for the underlying joystick device into the consistent SDL_Gamepad mapping.
* SDL_Gamepad mapping. You do not normally need to call this function * You do not normally need to call this function unless you are parsing
* unless you are parsing SDL_Gamepad mappings in your own code. * SDL_Gamepad mappings in your own code.
* *
* \param str string representing a SDL_Gamepad axis * \param str string representing a SDL_Gamepad axis
* \returns the SDL_GamepadButton enum corresponding to the input * \returns the SDL_GamepadButton enum corresponding to the input string, or
* string, or `SDL_GAMEPAD_AXIS_INVALID` if no match was found. * `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -801,9 +800,9 @@ extern DECLSPEC const char* SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadBut
* *
* \param gamepad a gamepad * \param gamepad a gamepad
* \param button an button enum value (an SDL_GamepadButton value) * \param button an button enum value (an SDL_GamepadButton value)
* \returns a SDL_GamepadBinding describing the bind. On failure * \returns a SDL_GamepadBinding describing the bind. On failure (like the
* (like the given Controller button doesn't exist on the device), * given Controller button doesn't exist on the device), its
* its `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`. * `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -814,8 +813,8 @@ extern DECLSPEC SDL_GamepadBinding SDLCALL SDL_GetGamepadBindForButton(SDL_Gamep
/** /**
* Query whether a gamepad has a given button. * Query whether a gamepad has a given button.
* *
* This merely reports whether the gamepad's mapping defined this button, * This merely reports whether the gamepad's mapping defined this button, as
* as that is all the information SDL has about the physical device. * that is all the information SDL has about the physical device.
* *
* \param gamepad a gamepad * \param gamepad a gamepad
* \param button a button enum value (an SDL_GamepadButton value) * \param button a button enum value (an SDL_GamepadButton value)
@ -896,8 +895,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadSensorEnabled(SDL_Gamepad *gamepad, SD
extern DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type); extern DECLSPEC SDL_bool SDLCALL SDL_GamepadSensorEnabled(SDL_Gamepad *gamepad, SDL_SensorType type);
/** /**
* Get the data rate (number of events per second) of a gamepad * Get the data rate (number of events per second) of a gamepad sensor.
* sensor.
* *
* \param gamepad The gamepad to query * \param gamepad The gamepad to query
* \param type The type of sensor to query * \param type The type of sensor to query
@ -949,10 +947,9 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
* Each call to this function cancels any previous trigger rumble effect, and * Each call to this function cancels any previous trigger rumble effect, and
* calling it with 0 intensity stops any rumbling. * calling it with 0 intensity stops any rumbling.
* *
* Note that this is rumbling of the _triggers_ and not the gamepad as * Note that this is rumbling of the _triggers_ and not the gamepad as a
* a whole. This is currently only supported on Xbox One gamepads. If you * whole. This is currently only supported on Xbox One gamepads. If you want
* want the (more common) whole-gamepad rumble, use * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.
* SDL_RumbleGamepad() instead.
* *
* \param gamepad The gamepad to vibrate * \param gamepad The gamepad to vibrate
* \param left_rumble The intensity of the left trigger rumble motor, from 0 * \param left_rumble The intensity of the left trigger rumble motor, from 0
@ -972,8 +969,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint
* Query whether a gamepad has an LED. * Query whether a gamepad has an LED.
* *
* \param gamepad The gamepad to query * \param gamepad The gamepad to query
* \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a * \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a modifiable
* modifiable LED * LED
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -1024,8 +1021,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, U
* \param gamepad The gamepad to affect * \param gamepad The gamepad to affect
* \param data The data to send to the gamepad * \param data The data to send to the gamepad
* \param size The size of the data to send to the gamepad * \param size The size of the data to send to the gamepad
* \returns 0, or -1 if this gamepad or driver doesn't support effect * \returns 0, or -1 if this gamepad or driver doesn't support effect packets
* packets
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -1034,7 +1030,8 @@ extern DECLSPEC int SDLCALL SDL_SendGamepadEffect(SDL_Gamepad *gamepad, const vo
/** /**
* Close a gamepad previously opened with SDL_OpenGamepad(). * Close a gamepad previously opened with SDL_OpenGamepad().
* *
* \param gamepad a gamepad identifier previously returned by SDL_OpenGamepad() * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -1057,8 +1054,7 @@ extern DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
extern DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button); extern DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
/** /**
* Return the sfSymbolsName for a given axis on a gamepad on Apple * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
* platforms.
* *
* \param gamepad the gamepad to query * \param gamepad the gamepad to query
* \param axis an axis on the gamepad * \param axis an axis on the gamepad

View file

@ -91,8 +91,8 @@ typedef enum
* - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
* events subsystem * events subsystem
* - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
* - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically initializes the
* initializes the joystick subsystem * joystick subsystem
* - `SDL_INIT_EVENTS`: events subsystem * - `SDL_INIT_EVENTS`: events subsystem
* - `SDL_INIT_EVERYTHING`: all of the above subsystems * - `SDL_INIT_EVERYTHING`: all of the above subsystems
* *

View file

@ -121,9 +121,9 @@ typedef enum
/** /**
* Locking for atomic access to the joystick API * Locking for atomic access to the joystick API
* *
* The SDL joystick functions are thread-safe, however you can lock the joysticks * The SDL joystick functions are thread-safe, however you can lock the
* while processing to guarantee that the joystick list won't change and joystick * joysticks while processing to guarantee that the joystick list won't change
* and gamepad events will not be delivered. * and joystick and gamepad events will not be delivered.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -140,7 +140,9 @@ extern DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_
* Get a list of currently connected joysticks. * Get a list of currently connected joysticks.
* *
* \param count a pointer filled in with the number of joysticks returned * \param count a pointer filled in with the number of joysticks returned
* \returns a 0 terminated array of joystick instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details. * \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -286,7 +288,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_i
* Get the SDL_Joystick associated with an instance ID, if it has been opened. * Get the SDL_Joystick associated with an instance ID, if it has been opened.
* *
* \param instance_id the instance ID to get the SDL_Joystick for * \param instance_id the instance ID to get the SDL_Joystick for
* \returns an SDL_Joystick on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information. * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been
* opened yet; 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.
*/ */
@ -306,7 +309,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
/** /**
* Attach a new virtual joystick. * Attach a new virtual joystick.
* *
* \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information. * \returns the joystick instance ID, or 0 if an error occurred; 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.
*/ */
@ -357,7 +361,8 @@ typedef struct SDL_VirtualJoystickDesc
/** /**
* Attach a new virtual joystick with extended properties. * Attach a new virtual joystick with extended properties.
* *
* \returns the joystick instance ID, or 0 if an error occurred; call SDL_GetError() for more information. * \returns the joystick instance ID, or 0 if an error occurred; 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.
*/ */
@ -366,7 +371,8 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
/** /**
* Detach a virtual joystick. * Detach a virtual joystick.
* *
* \param instance_id the joystick instance ID, previously returned from SDL_AttachVirtualJoystick() * \param instance_id the joystick instance ID, previously returned from
* SDL_AttachVirtualJoystick()
* \returns 0 on success, or -1 if an error occurred. * \returns 0 on success, or -1 if an error occurred.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -729,7 +735,8 @@ extern DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(SDL_bool enabled);
* yourself and check the state of the joystick when you want joystick * yourself and check the state of the joystick when you want joystick
* information. * information.
* *
* \returns SDL_TRUE if joystick events are being processed, SDL_FALSE otherwise. * \returns SDL_TRUE if joystick events are being processed, SDL_FALSE
* otherwise.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *

View file

@ -247,9 +247,9 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
* Start accepting Unicode text input events. * Start accepting Unicode text input events.
* *
* This function will start accepting Unicode text input events in the focused * This function will start accepting Unicode text input events in the focused
* SDL window, and start emitting SDL_TextInputEvent (SDL_EVENT_TEXT_INPUT) and * SDL window, and start emitting SDL_TextInputEvent (SDL_EVENT_TEXT_INPUT)
* SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this function in * and SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this
* pair with SDL_StopTextInput(). * function in pair with SDL_StopTextInput().
* *
* On some platforms using this function activates the screen keyboard. * On some platforms using this function activates the screen keyboard.
* *

View file

@ -79,8 +79,8 @@ typedef struct SDL_Locale
* This might be a "slow" call that has to query the operating system. It's * This might be a "slow" call that has to query the operating system. It's
* best to ask for this once and save the results. However, this list can * best to ask for this once and save the results. However, this list can
* change, usually because the user has changed a system preference outside of * change, usually because the user has changed a system preference outside of
* your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if * your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case,
* possible, and you can call this function again to get an updated copy of * if possible, and you can call this function again to get an updated copy of
* preferred locales. * preferred locales.
* *
* \return array of locales, terminated with a locale with a NULL language * \return array of locales, terminated with a locale with a NULL language

View file

@ -173,22 +173,24 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
/** /**
* Initializes and launches an SDL application, by doing platform-specific * Initializes and launches an SDL application, by doing platform-specific
* initialization before calling your mainFunction and cleanups after it returns, * initialization before calling your mainFunction and cleanups after it
* if that is needed for a specific platform, otherwise it just calls mainFunction. * returns, if that is needed for a specific platform, otherwise it just calls
* You can use this if you want to use your own main() implementation * mainFunction.
* without using SDL_main (like when using SDL_MAIN_HANDLED).
* When using this, you do *not* need SDL_SetMainReady().
* *
* \param argc The argc parameter from the application's main() function, * You can use this if you want to use your own main() implementation without
* or 0 if the platform's main-equivalent has no argc * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do
* \param argv The argv parameter from the application's main() function, * *not* need SDL_SetMainReady().
* or NULL if the platform's main-equivalent has no argv *
* \param mainFunction Your SDL app's C-style main(), an SDL_main_func. * \param argc The argc parameter from the application's main() function, or 0
* NOT the function you're calling this from! * if the platform's main-equivalent has no argc
* Its name doesn't matter, but its signature must be * \param argv The argv parameter from the application's main() function, or
* like int my_main(int argc, char* argv[]) * NULL if the platform's main-equivalent has no argv
* \param reserved should be NULL (reserved for future use, will probably * \param mainFunction Your SDL app's C-style main(), an SDL_main_func. NOT
* be platform-specific then) * the function you're calling this from! Its name doesn't
* matter, but its signature must be like int my_main(int
* argc, char* argv[])
* \param reserved should be NULL (reserved for future use, will probably be
* platform-specific then)
* \return the return value from mainFunction: 0 on success, -1 on failure; * \return 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
* *

View file

@ -389,8 +389,8 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
/** /**
* Get the default cursor. * Get the default cursor.
* *
* You do not have to call SDL_DestroyCursor() on the return value, * You do not have to call SDL_DestroyCursor() on the return value, but it is
* but it is safe to do so. * safe to do so.
* *
* \returns the default cursor on success or NULL on failure. * \returns the default cursor on success or NULL on failure.
* *

View file

@ -481,9 +481,9 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
* `cond`. Once the condition variable is signaled, the mutex is re-locked and * `cond`. Once the condition variable is signaled, the mutex is re-locked and
* the function returns. * the function returns.
* *
* The mutex must be locked before calling this function. Locking the * The mutex must be locked before calling this function. Locking the mutex
* mutex recursively (more than once) is not supported and leads to * recursively (more than once) is not supported and leads to undefined
* undefined behavior. * behavior.
* *
* This function is the equivalent of calling SDL_CondWaitTimeout() with a * This function is the equivalent of calling SDL_CondWaitTimeout() with a
* time length of `SDL_MUTEX_MAXWAIT`. * time length of `SDL_MUTEX_MAXWAIT`.
@ -512,14 +512,14 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex);
* signaled or the time elapsed, the mutex is re-locked and the function * signaled or the time elapsed, the mutex is re-locked and the function
* returns. * returns.
* *
* The mutex must be locked before calling this function. Locking the * The mutex must be locked before calling this function. Locking the mutex
* mutex recursively (more than once) is not supported and leads to * recursively (more than once) is not supported and leads to undefined
* undefined behavior. * behavior.
* *
* \param cond the condition variable to wait on * \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access * \param mutex the mutex used to coordinate thread access
* \param timeoutMS the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT` * \param timeoutMS the maximum time to wait, in milliseconds, or
* to wait indefinitely * `SDL_MUTEX_MAXWAIT` to wait indefinitely
* \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
* the condition is not signaled in the allotted time, or a negative * the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information. * error code on failure; call SDL_GetError() for more information.

View file

@ -64,12 +64,12 @@ typedef enum
* It's possible a platform can only report battery percentage or time left * It's possible a platform can only report battery percentage or time left
* but not both. * but not both.
* *
* \param seconds seconds of battery life left, you can pass a NULL here if you * \param seconds seconds of battery life left, you can pass a NULL here if
* don't care, will return -1 if we can't determine a value, or * you don't care, will return -1 if we can't determine a
* we're not running on a battery * value, or we're not running on a battery
* \param percent percentage of battery life left, between 0 and 100, you can pass * \param percent percentage of battery life left, between 0 and 100, you can
* a NULL here if you don't care, will return -1 if we can't * pass a NULL here if you don't care, will return -1 if we
* determine a value, or we're not running on a battery * can't determine a value, or we're not running on a battery
* \returns an SDL_PowerState enum representing the current battery state. * \returns an SDL_PowerState enum representing the current battery state.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

View file

@ -217,12 +217,11 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
/** /**
* Create a 2D rendering context for a window. * Create a 2D rendering context for a window.
* *
* If you want a specific renderer, you can specify its name here. A list * If you want a specific renderer, you can specify its name here. A list of
* of available renderers can be obtained by calling SDL_GetRenderDriver * available renderers can be obtained by calling SDL_GetRenderDriver multiple
* multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't
* you don't need a specific renderer, specify NULL and SDL will attempt * need a specific renderer, specify NULL and SDL will attempt to chooes the
* to chooes the best option for you, based on what is available on the * best option for you, based on what is available on the user's system.
* user's system.
* *
* \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
@ -1377,9 +1376,9 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer,
* Update the screen with any rendering performed since the previous call. * Update the screen with any rendering performed since the previous call.
* *
* SDL's rendering functions operate on a backbuffer; that is, calling a * SDL's rendering functions operate on a backbuffer; that is, calling a
* rendering function such as SDL_RenderLine() does not directly put a * rendering function such as SDL_RenderLine() does not directly put a line on
* line on the screen, but rather updates the backbuffer. As such, you compose * the screen, but rather updates the backbuffer. As such, you compose your
* your entire scene and *present* the composed backbuffer to the screen as a * entire scene and *present* the composed backbuffer to the screen as a
* complete picture. * complete picture.
* *
* Therefore, when using SDL's rendering API, one does all drawing intended * Therefore, when using SDL's rendering API, one does all drawing intended
@ -1394,12 +1393,12 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer,
* *
* \param renderer the rendering context * \param renderer the rendering context
* *
* \since This function is available since SDL 3.0.0. * \threadsafety You may only call this function on the main thread. If this
* happens to work on a background thread on any given platform
* or backend, it's purely by luck and you should not rely on it
* to work next time.
* *
* \threadsafety You may only call this function on the main thread. If * \since This function is available since SDL 3.0.0.
* this happens to work on a background thread on any given
* platform or backend, it's purely by luck and you should
* not rely on it to work next time.
* *
* \sa SDL_RenderClear * \sa SDL_RenderClear
* \sa SDL_RenderLine * \sa SDL_RenderLine
@ -1580,7 +1579,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync
* Get VSync of the given renderer. * Get VSync of the given renderer.
* *
* \param renderer The renderer to toggle * \param renderer The renderer to toggle
* \param vsync an int filled with 1 for on, 0 for off. All other values are reserved * \param vsync an int filled with 1 for on, 0 for off. All other values are
* reserved
* \returns a 0 int on success, or non-zero on failure * \returns a 0 int on success, or non-zero on failure
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

View file

@ -319,10 +319,11 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(void);
* call the **close** method on those SDL_RWops pointers when you are done * call the **close** method on those SDL_RWops pointers when you are done
* with them. * with them.
* *
* Only use SDL_DestroyRW() on pointers returned by SDL_CreateRW(). The pointer is * Only use SDL_DestroyRW() on pointers returned by SDL_CreateRW(). The
* invalid as soon as this function returns. Any extra memory allocated during * pointer is invalid as soon as this function returns. Any extra memory
* creation of the SDL_RWops is not freed by SDL_DestroyRW(); the programmer must * allocated during creation of the SDL_RWops is not freed by SDL_DestroyRW();
* be responsible for managing that memory in their **close** method. * the programmer must be responsible for managing that memory in their
* **close** method.
* *
* \param area the SDL_RWops structure to be freed * \param area the SDL_RWops structure to be freed
* *
@ -371,7 +372,8 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
* \param context a pointer to an SDL_RWops structure * \param context a pointer to an SDL_RWops structure
* \param offset an offset in bytes, relative to **whence** location; can be * \param offset an offset in bytes, relative to **whence** location; can be
* negative * negative
* \param whence any of `SDL_RW_SEEK_SET`, `SDL_RW_SEEK_CUR`, `SDL_RW_SEEK_END` * \param whence any of `SDL_RW_SEEK_SET`, `SDL_RW_SEEK_CUR`,
* `SDL_RW_SEEK_END`
* \returns the final offset in the data stream after the seek or -1 on error. * \returns the final offset in the data stream after the seek or -1 on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -417,24 +419,25 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
* Read from a data source. * Read from a data source.
* *
* This function reads up `size` bytes from the data source to the area * This function reads up `size` bytes from the data source to the area
* pointed at by `ptr`. This function may read less bytes than requested. * pointed at by `ptr`. This function may read less bytes than requested. It
* It will return zero when the data stream is completely read, or * will return zero when the data stream is completely read, or -1 on error.
* -1 on error. For streams that support non-blocking * For streams that support non-blocking operation, if nothing was read
* operation, if nothing was read because it would require blocking, * because it would require blocking, this function returns -2 to distinguish
* this function returns -2 to distinguish that this is not an error or * that this is not an error or end-of-file, and the caller can try again
* end-of-file, and the caller can try again later. * later.
* *
* SDL_RWread() is actually a function wrapper that calls the SDL_RWops's * SDL_RWread() is actually a function wrapper that calls the SDL_RWops's
* `read` method appropriately, to simplify application development. * `read` method appropriately, to simplify application development.
* *
* It is an error to specify a negative `size`, but this parameter is * It is an error to specify a negative `size`, but this parameter is signed
* signed so you definitely cannot overflow the return value on a * so you definitely cannot overflow the return value on a successful run with
* successful run with enormous amounts of data. * enormous amounts of data.
* *
* \param context a pointer to an SDL_RWops structure * \param context a pointer to an SDL_RWops structure
* \param ptr a pointer to a buffer to read data into * \param ptr a pointer to a buffer to read data into
* \param size the number of bytes to read from the data source. * \param size the number of bytes to read from the data source.
* \returns the number of bytes read, 0 at end of file, -1 on error, and -2 for data not ready with a non-blocking context. * \returns the number of bytes read, 0 at end of file, -1 on error, and -2
* for data not ready with a non-blocking context.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -450,25 +453,23 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWread(SDL_RWops *context, void *ptr, Sint64
/** /**
* Write to an SDL_RWops data stream. * Write to an SDL_RWops data stream.
* *
* This function writes exactly `size` bytes from the area pointed at by * This function writes exactly `size` bytes from the area pointed at by `ptr`
* `ptr` to the stream. If this fails for any reason, it'll return less * to the stream. If this fails for any reason, it'll return less than `size`
* than `size` to demonstrate how far the write progressed. On success, * to demonstrate how far the write progressed. On success, it returns `num`.
* it returns `num`.
* *
* On error, this function still attempts to write as much as possible, * On error, this function still attempts to write as much as possible, so it
* so it might return a positive value less than the requested write * might return a positive value less than the requested write size. If the
* size. If the function failed to write anything and there was an * function failed to write anything and there was an actual error, it will
* actual error, it will return -1. For streams that support non-blocking * return -1. For streams that support non-blocking operation, if nothing was
* operation, if nothing was written because it would require blocking, * written because it would require blocking, this function returns -2 to
* this function returns -2 to distinguish that this is not an error and * distinguish that this is not an error and the caller can try again later.
* the caller can try again later.
* *
* SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's * SDL_RWwrite is actually a function wrapper that calls the SDL_RWops's
* `write` method appropriately, to simplify application development. * `write` method appropriately, to simplify application development.
* *
* It is an error to specify a negative `size`, but this parameter is * It is an error to specify a negative `size`, but this parameter is signed
* signed so you definitely cannot overflow the return value on a * so you definitely cannot overflow the return value on a successful run with
* successful run with enormous amounts of data. * enormous amounts of data.
* *
* \param context a pointer to an SDL_RWops structure * \param context a pointer to an SDL_RWops structure
* \param ptr a pointer to a buffer containing data to write * \param ptr a pointer to a buffer containing data to write

View file

@ -132,7 +132,9 @@ typedef enum
* Get a list of currently connected sensors. * Get a list of currently connected sensors.
* *
* \param count a pointer filled in with the number of sensors returned * \param count a pointer filled in with the number of sensors returned
* \returns a 0 terminated array of sensor instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details. * \returns a 0 terminated array of sensor instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -152,7 +154,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID insta
* Get the type of a sensor. * Get the type of a sensor.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID
* \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is not valid * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `instance_id` is
* not valid
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
@ -162,7 +165,8 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorID in
* Get the platform dependent type of a sensor. * Get the platform dependent type of a sensor.
* *
* \param instance_id the sensor instance ID * \param instance_id the sensor instance ID
* \returns the sensor platform dependent type, or -1 if `instance_id` is not valid * \returns the sensor platform dependent type, or -1 if `instance_id` is not
* valid
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */

View file

@ -424,9 +424,11 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
/** /**
* Allocate memory aligned to a specific value * Allocate memory aligned to a specific value
* *
* If `alignment` is less than the size of `void *`, then it will be increased to match that. * If `alignment` is less than the size of `void *`, then it will be increased
* to match that.
* *
* The returned memory address will be a multiple of the alignment value, and the amount of memory allocated will be a multiple of the alignment value. * The returned memory address will be a multiple of the alignment value, and
* the amount of memory allocated will be a multiple of the alignment value.
* *
* The memory returned by this function must be freed with SDL_aligned_free() * The memory returned by this function must be freed with SDL_aligned_free()
* *

View file

@ -224,8 +224,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
/** /**
* Load a BMP image from a seekable SDL data stream. * Load a BMP image from a seekable SDL data stream.
* *
* The new surface should be freed with SDL_DestroySurface(). Not doing so will * The new surface should be freed with SDL_DestroySurface(). Not doing so
* result in a memory leak. * will result in a memory leak.
* *
* src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile. * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile.
* Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap
@ -652,8 +652,8 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height,
* information, no blending takes place. * information, no blending takes place.
* *
* If there is a clip rectangle set on the destination (set via * If there is a clip rectangle set on the destination (set via
* SDL_SetSurfaceClipRect()), then this function will fill based on the intersection * SDL_SetSurfaceClipRect()), then this function will fill based on the
* of the clip rectangle and `rect`. * intersection of the clip rectangle and `rect`.
* *
* \param dst the SDL_Surface structure that is the drawing target * \param dst the SDL_Surface structure that is the drawing target
* \param rect the SDL_Rect structure representing the rectangle to fill, or * \param rect the SDL_Rect structure representing the rectangle to fill, or
@ -678,8 +678,8 @@ extern DECLSPEC int SDLCALL SDL_FillSurfaceRect
* information, no blending takes place. * information, no blending takes place.
* *
* If there is a clip rectangle set on the destination (set via * If there is a clip rectangle set on the destination (set via
* SDL_SetSurfaceClipRect()), then this function will fill based on the intersection * SDL_SetSurfaceClipRect()), then this function will fill based on the
* of the clip rectangle and `rect`. * intersection of the clip rectangle and `rect`.
* *
* \param dst the SDL_Surface structure that is the drawing target * \param dst the SDL_Surface structure that is the drawing target
* \param rects an array of SDL_Rects representing the rectangles to fill. * \param rects an array of SDL_Rects representing the rectangles to fill.
@ -698,54 +698,55 @@ extern DECLSPEC int SDLCALL SDL_FillSurfaceRects
/** /**
* Performs a fast blit from the source surface to the destination surface. * Performs a fast blit from the source surface to the destination surface.
* *
* This assumes that the source and destination rectangles are * This assumes that the source and destination rectangles are the same size.
* the same size. If either \c srcrect or \c dstrect are NULL, the entire * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
* surface (\c src or \c dst) is copied. The final blit rectangles are saved * `dst`) is copied. The final blit rectangles are saved in `srcrect` and
* in \c srcrect and \c dstrect after all clipping is performed. * `dstrect` after all clipping is performed.
* *
* The blit function should not be called on a locked surface. * The blit function should not be called on a locked surface.
* *
* The blit semantics for surfaces with and without blending and colorkey * The blit semantics for surfaces with and without blending and colorkey are
* are defined as follows: * defined as follows:
* \verbatim *
RGBA->RGB: * ```c
Source surface blend mode set to SDL_BLENDMODE_BLEND: * RGBA->RGB:
alpha-blend (using the source alpha-channel and per-surface alpha) * Source surface blend mode set to SDL_BLENDMODE_BLEND:
SDL_SRCCOLORKEY ignored. * alpha-blend (using the source alpha-channel and per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE: * SDL_SRCCOLORKEY ignored.
copy RGB. * Source surface blend mode set to SDL_BLENDMODE_NONE:
if SDL_SRCCOLORKEY set, only copy the pixels matching the * copy RGB.
RGB values of the source color key, ignoring alpha in the * if SDL_SRCCOLORKEY set, only copy the pixels matching the
comparison. * RGB values of the source color key, ignoring alpha in the
* comparison.
RGB->RGBA: *
Source surface blend mode set to SDL_BLENDMODE_BLEND: * RGB->RGBA:
alpha-blend (using the source per-surface alpha) * Source surface blend mode set to SDL_BLENDMODE_BLEND:
Source surface blend mode set to SDL_BLENDMODE_NONE: * alpha-blend (using the source per-surface alpha)
copy RGB, set destination alpha to source per-surface alpha value. * Source surface blend mode set to SDL_BLENDMODE_NONE:
both: * copy RGB, set destination alpha to source per-surface alpha value.
if SDL_SRCCOLORKEY set, only copy the pixels matching the * both:
source color key. * if SDL_SRCCOLORKEY set, only copy the pixels matching the
* source color key.
RGBA->RGBA: *
Source surface blend mode set to SDL_BLENDMODE_BLEND: * RGBA->RGBA:
alpha-blend (using the source alpha-channel and per-surface alpha) * Source surface blend mode set to SDL_BLENDMODE_BLEND:
SDL_SRCCOLORKEY ignored. * alpha-blend (using the source alpha-channel and per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE: * SDL_SRCCOLORKEY ignored.
copy all of RGBA to the destination. * Source surface blend mode set to SDL_BLENDMODE_NONE:
if SDL_SRCCOLORKEY set, only copy the pixels matching the * copy all of RGBA to the destination.
RGB values of the source color key, ignoring alpha in the * if SDL_SRCCOLORKEY set, only copy the pixels matching the
comparison. * RGB values of the source color key, ignoring alpha in the
* comparison.
RGB->RGB: *
Source surface blend mode set to SDL_BLENDMODE_BLEND: * RGB->RGB:
alpha-blend (using the source per-surface alpha) * Source surface blend mode set to SDL_BLENDMODE_BLEND:
Source surface blend mode set to SDL_BLENDMODE_NONE: * alpha-blend (using the source per-surface alpha)
copy RGB. * Source surface blend mode set to SDL_BLENDMODE_NONE:
both: * copy RGB.
if SDL_SRCCOLORKEY set, only copy the pixels matching the * both:
source color key. * if SDL_SRCCOLORKEY set, only copy the pixels matching the
\endverbatim * source color key.
* ```
* *
* \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

View file

@ -339,7 +339,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetDisplayName(int displayIndex);
extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rect); extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect *rect);
/** /**
* Get the usable desktop area represented by a display, in screen coordinates. * Get the usable desktop area represented by a display, in screen
* coordinates.
* *
* The primary display (`displayIndex` zero) is always located at 0,0. * The primary display (`displayIndex` zero) is always located at 0,0.
* *
@ -385,7 +386,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
* SDL_Vulkan_GetDrawableSize(), SDL_Metal_GetDrawableSize(), or * SDL_Vulkan_GetDrawableSize(), SDL_Metal_GetDrawableSize(), or
* SDL_GetRendererOutputSize(), and compare the two values to get an actual * SDL_GetRendererOutputSize(), and compare the two values to get an actual
* scaling value between the two. We will be rethinking how high-dpi details * scaling value between the two. We will be rethinking how high-dpi details
* should be managed in SDL3 to make things more consistent, reliable, and clear. * should be managed in SDL3 to make things more consistent, reliable, and
* clear.
* *
* \param displayIndex the index of the display from which DPI information * \param displayIndex the index of the display from which DPI information
* should be queried * should be queried
@ -659,13 +661,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
* On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
* property to YES, otherwise you will not receive a High-DPI OpenGL canvas. * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
* *
* The window size in pixels may differ from its size in screen coordinates if * The window size in pixels may differ from its size in screen coordinates
* the window is on a high density display (one with an OS scaling factor). * if the window is on a high density display (one with an OS scaling factor).
* Use SDL_GetWindowSize() to query the client area's size in screen coordinates, * Use SDL_GetWindowSize() to query the client area's size in screen
* and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize() to query the * coordinates, and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize()
* drawable size in pixels. Note that the drawable size can vary after the window * to query the drawable size in pixels. Note that the drawable size can vary
* is created and should be queried again when the window is resized or moved * after the window is created and should be queried again when the window is
* between displays. * resized or moved between displays.
* *
* If the window is set fullscreen, the width and height parameters `w` and * If the window is set fullscreen, the width and height parameters `w` and
* `h` will not be used. However, invalid size parameters (e.g. too large) may * `h` will not be used. However, invalid size parameters (e.g. too large) may
@ -844,8 +846,10 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *
* Set the position of a window, in screen coordinates. * Set the position of a window, in screen coordinates.
* *
* \param window the window to reposition * \param window the window to reposition
* \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
* \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` * `SDL_WINDOWPOS_UNDEFINED`
* \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
* `SDL_WINDOWPOS_UNDEFINED`
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -916,8 +920,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h)
extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h); extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h);
/** /**
* Get the size of a window's borders (decorations) around the client area, * Get the size of a window's borders (decorations) around the client area, in
* in screen coordinates. * screen coordinates.
* *
* Note: If this function fails (returns -1), the size values will be * Note: If this function fails (returns -1), the size values will be
* initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
@ -1938,12 +1942,12 @@ extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
* If the system can't determine the swap interval, or there isn't a valid * If the system can't determine the swap interval, or there isn't a valid
* current context, this function will set *interval to 0 as a safe default. * current context, this function will set *interval to 0 as a safe default.
* *
* \param interval Output interval value. 0 if there is no vertical retrace synchronization, 1 if the buffer * \param interval Output interval value. 0 if there is no vertical retrace
* swap is synchronized with the vertical retrace, and -1 if late * synchronization, 1 if the buffer swap is synchronized with
* swaps happen immediately instead of waiting for the next retrace * the vertical retrace, and -1 if late swaps happen
* * immediately instead of waiting for the next retrace
* \returns 0 on success or -1 error. * \returns 0 on success or -1 error. call SDL_GetError() for more
* call SDL_GetError() for more information. * information.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -1962,7 +1966,6 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval);
* extra. * extra.
* *
* \param window the window to change * \param window the window to change
*
* \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.
* *

View file

@ -111,11 +111,13 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
* This should be called after either calling SDL_Vulkan_LoadLibrary() or * This should be called after either calling SDL_Vulkan_LoadLibrary() or
* creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
* *
* The actual type of the returned function pointer is PFN_vkGetInstanceProcAddr, * The actual type of the returned function pointer is
* but that isn't available because the Vulkan headers are not included here. You * PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan
* should cast the return value of this function to that type, e.g. * headers are not included here. You should cast the return value of this
* function to that type, e.g.
* *
* `vkGetInstanceProcAddr = (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();` * `vkGetInstanceProcAddr =
* (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
* *
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error. * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
* *