gallant/SDL2
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Sync wiki -> headers.

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

38
include/SDL3/SDL_audio.h
View file

@ -407,8 +407,8 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name,
* Open a specific audio device.
*
* 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
* some drivers allow arbitrary and driver-specific strings, such as a
* The `device` name is a UTF-8 string reported by SDL_GetAudioDeviceName(),
* 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
* 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.
*
* Newly-opened audio devices start in the paused state, so you must
* call this function after opening the specified audio
* device to start playing sound. This allows you to safely initialize data
* for your callback function after opening the audio device. Silence will be
* written to the audio device while paused, and the audio callback is
* guaranteed to not be called. Pausing one device does not prevent other
* unpaused devices from running their callbacks.
* Newly-opened audio devices start in the paused state, so you must call this
* function after opening the specified audio device to start playing sound.
* This allows you to safely initialize data for your callback function after
* opening the audio device. Silence will be written to the audio device while
* paused, and the audio callback is guaranteed to not be called. Pausing one
* device does not prevent other unpaused devices from running their
* callbacks.
*
* \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.
*
* This function pauses the audio callback processing for a given
* device. Silence will be written to the audio device while paused, and
* the audio callback is guaranteed to not be called.
* Pausing one device does not prevent other unpaused devices from running
* their callbacks.
* This function pauses the audio callback processing for a given device.
* Silence will be written to the audio device while paused, and the audio
* callback is guaranteed to not be called. Pausing one device does not
* prevent other unpaused devices from running their callbacks.
*
* 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
@ -1119,15 +1118,16 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
* \param src_format The format of the source audio
* \param src_channels The number of channels of the source audio
* \param src_rate The sampling rate of the source audio
* \param src_len The len of src_data
* \param src_len The len of src_data
* \param src_data The audio data to be converted
* \param dst_format The format 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_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().
*
* \returns 0 on success or a negative error code on failure. On error, *dst_data will be NULL and so not allocated.
* \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().
* \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.
*

4
include/SDL3/SDL_events.h
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
* this function in the thread that initialized the video subsystem.
*
* The timeout is not guaranteed, the actual wait time could be longer
* due to system scheduling.
* The timeout is not guaranteed, the actual wait time could be longer due to
* system scheduling.
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL

154
include/SDL3/SDL_gamepad.h
View file

@ -160,11 +160,11 @@ typedef struct SDL_GamepadBinding
*
* The mapping string has the format "GUID,name,mapping", where GUID is the
* string value from SDL_GetJoystickGUIDString(), name is the human readable
* string for the device and mappings are gamepad mappings to joystick
* ones. Under Windows there is a reserved GUID of "xinput" that covers all
* XInput devices. The mapping format for joystick is: {| |bX |a joystick
* button, 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.
* string for the device and mappings are gamepad mappings to joystick ones.
* Under Windows there is a reserved GUID of "xinput" that covers all XInput
* devices. The mapping format for joystick is: {| |bX |a joystick button,
* 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.
*
* 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().
*
* \param gamepad the gamepad you want to get the current
* mapping for
* \returns a string that has the gamepad's mapping or NULL if no mapping
* is available; call SDL_GetError() for more information.
* \param gamepad the gamepad you want to get the current mapping for
* \returns a string that has the gamepad's mapping or NULL if no mapping is
* available; call SDL_GetError() for more information.
*
* \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.
*
* \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.
*
@ -370,8 +371,8 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetGamepadInstanceGUID(SDL_Joystick
* available this function returns 0.
*
* \param instance_id the joystick instance ID
* \returns the USB vendor ID of the selected gamepad. If called on an
* invalid index, this function returns zero
* \returns the USB vendor ID of the selected gamepad. If called on an invalid
* index, this function returns zero
*
* \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);
/**
* 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
* \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.
*/
@ -471,13 +474,13 @@ extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int player_in
/**
* Get the implementation-dependent name for an opened gamepad.
*
* This is the same name as returned by SDL_GetGamepadNameForIndex(), but
* it takes a gamepad identifier instead of the (unstable) device index.
* This is the same name as returned by SDL_GetGamepadNameForIndex(), but it
* takes a gamepad identifier instead of the (unstable) device index.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* \returns the implementation dependent name for the gamepad, or NULL
* if there is no name or the identifier passed is invalid.
* SDL_OpenGamepad()
* \returns the implementation dependent name for the gamepad, or NULL if
* there is no name or the identifier passed is invalid.
*
* \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.
*
* This is the same path as returned by SDL_GetGamepadNameForIndex(), but
* it takes a gamepad identifier instead of the (unstable) device index.
* This is the same path as returned by SDL_GetGamepadNameForIndex(), but it
* takes a gamepad identifier instead of the (unstable) device index.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* \returns the implementation dependent path for the gamepad, or NULL
* if there is no path or the identifier passed is invalid.
* SDL_OpenGamepad()
* \returns the implementation dependent path for the gamepad, or NULL if
* there is no path or the identifier passed is invalid.
*
* \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
*
* This is the same name as returned by SDL_GetGamepadInstanceType(), but
* it takes a gamepad identifier instead of the (unstable) device index.
* This is the same name as returned by SDL_GetGamepadInstanceType(), but it
* takes a gamepad identifier instead of the (unstable) device index.
*
* \param gamepad the gamepad object to query.
* \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.
*
* \param gamepad the gamepad object to adjust.
* \param player_index Player index to assign to this gamepad, or -1 to
* clear the player index and turn off player LEDs.
* \param player_index Player index to assign to this gamepad, or -1 to clear
* the player index and turn off player LEDs.
*
* \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.
*
* Returns the serial number of the gamepad, or NULL if it is not
* available.
* Returns the serial number of the gamepad, or NULL if it is not available.
*
* \param gamepad the gamepad object to query.
* \return the serial number, or NULL if unavailable.
@ -604,7 +606,7 @@ extern DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
* Check if a gamepad has been opened and is currently connected.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* SDL_OpenGamepad()
* \returns SDL_TRUE if the gamepad has been opened and is currently
* connected, or SDL_FALSE if not.
*
@ -619,17 +621,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* Get the underlying joystick from a gamepad
*
* 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
* useful for getting a joystick's position at any given time, even if it
* hasn't moved (moving it would produce an event, which would have the axis'
* value).
* the SDL_Joystick functions with a SDL_Gamepad object. This would be useful
* for getting a joystick's position at any given time, even if it hasn't
* moved (moving it would produce an event, which would have the axis' value).
*
* The pointer returned is owned by the SDL_Gamepad. You should not
* call SDL_CloseJoystick() on it, for example, since doing so will likely
* cause SDL to crash.
* The pointer returned is owned by the SDL_Gamepad. You should not call
* SDL_CloseJoystick() on it, for example, since doing so will likely cause
* SDL to crash.
*
* \param gamepad the gamepad object that you want to get a
* joystick from
* \param gamepad the gamepad object that you want to get a joystick from
* \returns an SDL_Joystick object; call SDL_GetError() for more information.
*
* \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.
*
* If gamepad events are disabled, you must call SDL_UpdateGamepads()
* yourself and check the state of the gamepad when you want gamepad
* information.
* If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
* and check the state of the gamepad when you want gamepad information.
*
* \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.
*
* If gamepad events are disabled, you must call SDL_UpdateGamepads()
* yourself and check the state of the gamepad when you want gamepad
* information.
* If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself
* and check the state of the gamepad when you want gamepad 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.
*
@ -681,18 +680,18 @@ extern DECLSPEC void SDLCALL SDL_UpdateGamepads(void);
/**
* Convert a string into SDL_GamepadAxis enum.
*
* This function is called internally to translate SDL_Gamepad mapping
* strings for the underlying joystick device into the consistent
* SDL_Gamepad mapping. You do not normally need to call this function
* unless you are parsing SDL_Gamepad mappings in your own code.
* This function is called internally to translate SDL_Gamepad mapping strings
* for the underlying joystick device into the consistent SDL_Gamepad mapping.
* You do not normally need to call this function unless you are parsing
* SDL_Gamepad mappings in your own code.
*
* Note specially that "righttrigger" and "lefttrigger" map to
* `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`,
* respectively.
*
* \param str string representing a SDL_Gamepad axis
* \returns the SDL_GamepadAxis enum corresponding to the input string,
* or `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* \returns the SDL_GamepadAxis enum corresponding to the input string, or
* `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
*
* \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 axis an axis enum value (one of the SDL_GamepadAxis values)
* \returns a SDL_GamepadBinding describing the bind. On failure
* (like the given Controller axis doesn't exist on the device), its
* \returns a SDL_GamepadBinding describing the bind. On failure (like the
* given Controller axis doesn't exist on the device), its
* `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
*
* \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.
*
* This function is called internally to translate SDL_Gamepad mapping
* strings for the underlying joystick device into the consistent
* SDL_Gamepad mapping. You do not normally need to call this function
* unless you are parsing SDL_Gamepad mappings in your own code.
* This function is called internally to translate SDL_Gamepad mapping strings
* for the underlying joystick device into the consistent SDL_Gamepad mapping.
* You do not normally need to call this function unless you are parsing
* SDL_Gamepad mappings in your own code.
*
* \param str string representing a SDL_Gamepad axis
* \returns the SDL_GamepadButton enum corresponding to the input
* string, or `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* \returns the SDL_GamepadButton enum corresponding to the input string, or
* `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
*
* \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 button an button enum value (an SDL_GamepadButton value)
* \returns a SDL_GamepadBinding describing the bind. On failure
* (like the given Controller button doesn't exist on the device),
* its `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
* \returns a SDL_GamepadBinding describing the bind. On failure (like the
* given Controller button doesn't exist on the device), its
* `.bindType` will be `SDL_GAMEPAD_BINDTYPE_NONE`.
*
* \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.
*
* This merely reports whether the gamepad's mapping defined this button,
* as that is all the information SDL has about the physical device.
* This merely reports whether the gamepad's mapping defined this button, as
* that is all the information SDL has about the physical device.
*
* \param gamepad a gamepad
* \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);
/**
* Get the data rate (number of events per second) of a gamepad
* sensor.
* Get the data rate (number of events per second) of a gamepad sensor.
*
* \param gamepad The gamepad 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
* calling it with 0 intensity stops any rumbling.
*
* Note that this is rumbling of the _triggers_ and not the gamepad as
* a whole. This is currently only supported on Xbox One gamepads. If you
* want the (more common) whole-gamepad rumble, use
* SDL_RumbleGamepad() instead.
* Note that this is rumbling of the _triggers_ and not the gamepad as a
* whole. This is currently only supported on Xbox One gamepads. If you want
* the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.
*
* \param gamepad The gamepad to vibrate
* \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.
*
* \param gamepad The gamepad to query
* \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a
* modifiable LED
* \returns SDL_TRUE, or SDL_FALSE if this gamepad does not have a modifiable
* LED
*
* \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 data 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
* packets
* \returns 0, or -1 if this gamepad or driver doesn't support effect packets
*
* \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().
*
* \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.
*
@ -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);
/**
* Return the sfSymbolsName for a given axis on a gamepad on Apple
* platforms.
* Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
*
* \param gamepad the gamepad to query
* \param axis an axis on the gamepad

4
include/SDL3/SDL_init.h
View file

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

25
include/SDL3/SDL_joystick.h
View file

@ -121,9 +121,9 @@ typedef enum
/**
* Locking for atomic access to the joystick API
*
* The SDL joystick functions are thread-safe, however you can lock the joysticks
* while processing to guarantee that the joystick list won't change and joystick
* and gamepad events will not be delivered.
* The SDL joystick functions are thread-safe, however you can lock the
* joysticks while processing to guarantee that the joystick list won't change
* and joystick and gamepad events will not be delivered.
*
* \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.
*
* \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.
*
@ -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.
*
* \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.
*/
@ -306,7 +309,8 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
/**
* 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.
*/
@ -357,7 +361,8 @@ typedef struct SDL_VirtualJoystickDesc
/**
* 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.
*/
@ -366,7 +371,8 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
/**
* 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.
*
* \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
* 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.
*

6
include/SDL3/SDL_keyboard.h
View file

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

4
include/SDL3/SDL_locale.h
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
* 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
* your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, if
* possible, and you can call this function again to get an updated copy of
* your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case,
* if possible, and you can call this function again to get an updated copy of
* preferred locales.
*
* \return array of locales, terminated with a locale with a NULL language

32
include/SDL3/SDL_main.h
View file

@ -173,22 +173,24 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
/**
* Initializes and launches an SDL application, by doing platform-specific
* initialization before calling your mainFunction and cleanups after it returns,
* if that is needed for a specific platform, otherwise it just calls mainFunction.
* You can use this if you want to use your own main() implementation
* without using SDL_main (like when using SDL_MAIN_HANDLED).
* When using this, you do *not* need SDL_SetMainReady().
* initialization before calling your mainFunction and cleanups after it
* returns, if that is needed for a specific platform, otherwise it just calls
* mainFunction.
*
* \param argc The argc parameter from the application's main() function,
* or 0 if the platform's main-equivalent has no argc
* \param argv The argv parameter from the application's main() function,
* or NULL if the platform's main-equivalent has no argv
* \param mainFunction Your SDL app's C-style main(), an SDL_main_func.
* NOT 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)
* You can use this if you want to use your own main() implementation 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, or 0
* if the platform's main-equivalent has no argc
* \param argv The argv parameter from the application's main() function, or
* NULL if the platform's main-equivalent has no argv
* \param mainFunction Your SDL app's C-style main(), an SDL_main_func. NOT
* 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;
* SDL_GetError() might have more information on the failure
*

4
include/SDL3/SDL_mouse.h
View file

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

16
include/SDL3/SDL_mutex.h
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
* the function returns.
*
* The mutex must be locked before calling this function. Locking the
* mutex recursively (more than once) is not supported and leads to
* undefined behavior.
* The mutex must be locked before calling this function. Locking the mutex
* recursively (more than once) is not supported and leads to undefined
* behavior.
*
* This function is the equivalent of calling SDL_CondWaitTimeout() with a
* 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
* returns.
*
* The mutex must be locked before calling this function. Locking the
* mutex recursively (more than once) is not supported and leads to
* undefined behavior.
* The mutex must be locked before calling this function. Locking the mutex
* recursively (more than once) is not supported and leads to undefined
* behavior.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \param timeoutMS the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT`
* to wait indefinitely
* \param timeoutMS the maximum time to wait, in milliseconds, or
* `SDL_MUTEX_MAXWAIT` to wait indefinitely
* \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
* the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information.

12
include/SDL3/SDL_power.h
View file

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

30
include/SDL3/SDL_render.h
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.
*
* If you want a specific renderer, you can specify its name here. A list
* of available renderers can be obtained by calling SDL_GetRenderDriver
* multiple times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If
* you don't 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.
* If you want a specific renderer, you can specify its name here. A list of
* available renderers can be obtained by calling SDL_GetRenderDriver multiple
* times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't
* 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.
*
* \param window the window where rendering is displayed
* \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.
*
* SDL's rendering functions operate on a backbuffer; that is, calling a
* rendering function such as SDL_RenderLine() does not directly put a
* line on the screen, but rather updates the backbuffer. As such, you compose
* your entire scene and *present* the composed backbuffer to the screen as a
* rendering function such as SDL_RenderLine() does not directly put a line on
* the screen, but rather updates the backbuffer. As such, you compose your
* entire scene and *present* the composed backbuffer to the screen as a
* complete picture.
*
* 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
*
* \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
* 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.
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_RenderClear
* \sa SDL_RenderLine
@ -1580,7 +1579,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync
* Get VSync of the given renderer.
*
* \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
*
* \since This function is available since SDL 3.0.0.

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

10
include/SDL3/SDL_sensor.h
View file

@ -132,7 +132,9 @@ typedef enum
* Get a list of currently connected sensors.
*
* \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.
*/
@ -152,7 +154,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetSensorInstanceName(SDL_SensorID insta
* Get the type of a sensor.
*
* \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.
*/
@ -162,7 +165,8 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorID in
* Get the platform dependent type of a sensor.
*
* \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.
*/

6
include/SDL3/SDL_stdinc.h
View file

@ -424,9 +424,11 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func,
/**
* 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()
*

107
include/SDL3/SDL_surface.h
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.
*
* The new surface should be freed with SDL_DestroySurface(). Not doing so will
* result in a memory leak.
* The new surface should be freed with SDL_DestroySurface(). Not doing so
* will result in a memory leak.
*
* 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
@ -652,8 +652,8 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height,
* information, no blending takes place.
*
* If there is a clip rectangle set on the destination (set via
* SDL_SetSurfaceClipRect()), then this function will fill based on the intersection
* of the clip rectangle and `rect`.
* SDL_SetSurfaceClipRect()), then this function will fill based on the
* intersection of the clip rectangle and `rect`.
*
* \param dst the SDL_Surface structure that is the drawing target
* \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.
*
* If there is a clip rectangle set on the destination (set via
* SDL_SetSurfaceClipRect()), then this function will fill based on the intersection
* of the clip rectangle and `rect`.
* SDL_SetSurfaceClipRect()), then this function will fill based on the
* intersection of the clip rectangle and `rect`.
*
* \param dst the SDL_Surface structure that is the drawing target
* \param rects an array of SDL_Rects representing the rectangles to fill.
@ -696,56 +696,57 @@ extern DECLSPEC int SDLCALL SDL_FillSurfaceRects
(SDL_Surface *dst, const SDL_Rect *rects, int count, Uint32 color);
/**
* 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
* the same size. If either \c srcrect or \c dstrect are NULL, the entire
* surface (\c src or \c dst) is copied. The final blit rectangles are saved
* in \c srcrect and \c dstrect after all clipping is performed.
* This assumes that the source and destination rectangles are the same size.
* If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
* `dst`) is copied. The final blit rectangles are saved in `srcrect` and
* `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
* are defined as follows:
* \verbatim
RGBA->RGB:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source alpha-channel and per-surface alpha)
SDL_SRCCOLORKEY ignored.
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB.
if SDL_SRCCOLORKEY set, only copy the pixels matching the
RGB values of the source color key, ignoring alpha in the
comparison.
RGB->RGBA:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB, set destination alpha to source per-surface alpha value.
both:
if SDL_SRCCOLORKEY set, only copy the pixels matching the
source color key.
RGBA->RGBA:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source alpha-channel and per-surface alpha)
SDL_SRCCOLORKEY ignored.
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy all of RGBA to the destination.
if SDL_SRCCOLORKEY set, only copy the pixels matching the
RGB values of the source color key, ignoring alpha in the
comparison.
RGB->RGB:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB.
both:
if SDL_SRCCOLORKEY set, only copy the pixels matching the
source color key.
\endverbatim
* The blit semantics for surfaces with and without blending and colorkey are
* defined as follows:
*
* ```c
* RGBA->RGB:
* Source surface blend mode set to SDL_BLENDMODE_BLEND:
* alpha-blend (using the source alpha-channel and per-surface alpha)
* SDL_SRCCOLORKEY ignored.
* Source surface blend mode set to SDL_BLENDMODE_NONE:
* copy RGB.
* if SDL_SRCCOLORKEY set, only copy the pixels matching the
* RGB values of the source color key, ignoring alpha in the
* comparison.
*
* RGB->RGBA:
* Source surface blend mode set to SDL_BLENDMODE_BLEND:
* alpha-blend (using the source per-surface alpha)
* Source surface blend mode set to SDL_BLENDMODE_NONE:
* copy RGB, set destination alpha to source per-surface alpha value.
* both:
* if SDL_SRCCOLORKEY set, only copy the pixels matching the
* source color key.
*
* RGBA->RGBA:
* Source surface blend mode set to SDL_BLENDMODE_BLEND:
* alpha-blend (using the source alpha-channel and per-surface alpha)
* SDL_SRCCOLORKEY ignored.
* Source surface blend mode set to SDL_BLENDMODE_NONE:
* copy all of RGBA to the destination.
* if SDL_SRCCOLORKEY set, only copy the pixels matching the
* RGB values of the source color key, ignoring alpha in the
* comparison.
*
* RGB->RGB:
* Source surface blend mode set to SDL_BLENDMODE_BLEND:
* alpha-blend (using the source per-surface alpha)
* Source surface blend mode set to SDL_BLENDMODE_NONE:
* copy RGB.
* both:
* if SDL_SRCCOLORKEY set, only copy the pixels matching the
* source color key.
* ```
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be

43
include/SDL3/SDL_video.h
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);
/**
* 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.
*
@ -385,7 +386,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec
* SDL_Vulkan_GetDrawableSize(), SDL_Metal_GetDrawableSize(), or
* SDL_GetRendererOutputSize(), and compare the two values to get an actual
* 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
* 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
* 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 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,
* and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize() to query the
* drawable size in pixels. Note that the drawable size can vary after the window
* is created and should be queried again when the window is resized or moved
* between displays.
* The window size in pixels may differ from its size in screen coordinates
* 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, and SDL_GetWindowSizeInPixels() or SDL_GetRendererOutputSize()
* to query the drawable size in pixels. Note that the drawable size can vary
* after the window is created and should be queried again when the window is
* resized or moved between displays.
*
* 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
@ -844,8 +846,10 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *
* Set the position of a window, in screen coordinates.
*
* \param window the window to reposition
* \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`
* \param y the y 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
* `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.
*
@ -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);
/**
* Get the size of a window's borders (decorations) around the client area,
* in screen coordinates.
* Get the size of a window's borders (decorations) around the client area, in
* screen coordinates.
*
* 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
@ -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
* 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
* swap is synchronized with the vertical retrace, and -1 if late
* swaps happen immediately instead of waiting for the next retrace
*
* \returns 0 on success or -1 error.
* call SDL_GetError() for more information.
* \param interval Output interval value. 0 if there is no vertical retrace
* synchronization, 1 if the buffer swap is synchronized with
* the vertical retrace, and -1 if late swaps happen
* immediately instead of waiting for the next retrace
* \returns 0 on success or -1 error. call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1962,7 +1966,6 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(int *interval);
* extra.
*
* \param window the window to change
*
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*

10
include/SDL3/SDL_vulkan.h
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
* creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
*
* The actual type of the returned function pointer is PFN_vkGetInstanceProcAddr,
* but that isn't available because the Vulkan headers are not included here. You
* should cast the return value of this function to that type, e.g.
* The actual type of the returned function pointer is
* PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan
* 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.
*