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

Sync SDL3 wiki -> headers

main
Ryan C. Gordon 2024-04-09 00:49:23 -04:00
parent ad090d2444
commit e044318a8e
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
33 changed files with 1510 additions and 909 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
include/SDL3/SDL_assert.h
View File

@ -129,8 +129,8 @@ typedef enum
* Information about an assertion failure.
*
* This structure is filled in with information about a triggered assertion,
* used by the assertion handler, then added to the assertion report.
* This is returned as a linked list from SDL_GetAssertionReport().
* used by the assertion handler, then added to the assertion report. This is
* returned as a linked list from SDL_GetAssertionReport().
*
* \since This struct is available since SDL 3.0.0.
*/

22
include/SDL3/SDL_audio.h
View File

@ -149,9 +149,9 @@ typedef Uint32 SDL_AudioDeviceID;
/**
* Format specifier for audio data.
*
* \sa SDL_AudioFormat
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_AudioFormat
*/
typedef struct SDL_AudioSpec
{
@ -168,19 +168,19 @@ typedef struct SDL_AudioSpec
*
* SDL_AudioStream is an audio conversion interface.
*
* - It can handle resampling data in chunks without generating
* artifacts, when it doesn't have the complete buffer available.
* - It can handle resampling data in chunks without generating artifacts,
* when it doesn't have the complete buffer available.
* - It can handle incoming data in any variable size.
* - It can handle input/output format changes on the fly.
* - You push data as you have it, and pull it when you need it
* - It can also function as a basic audio data queue even if you
* just have sound that needs to pass from one place to another.
* - You can hook callbacks up to them when more data is added or
* requested, to manage data on-the-fly.
* - It can also function as a basic audio data queue even if you just have
* sound that needs to pass from one place to another.
* - You can hook callbacks up to them when more data is added or requested,
* to manage data on-the-fly.
*
* Audio streams are the core of the SDL3 audio interface. You create
* one or more of them, bind them to an opened audio device, and feed
* data to them (or for recording, consume data from them).
* Audio streams are the core of the SDL3 audio interface. You create one or
* more of them, bind them to an opened audio device, and feed data to them
* (or for recording, consume data from them).
*
* \since This struct is available since SDL 3.0.0.
*

18
include/SDL3/SDL_blendmode.h
View File

@ -37,11 +37,12 @@ extern "C" {
/**
* An enumeration of blend modes used in drawing operations.
*
* Note that additional values may be obtained from SDL_ComposeCustomBlendMode.
*
* \sa SDL_ComposeCustomBlendMode
* Note that additional values may be obtained from
* SDL_ComposeCustomBlendMode.
*
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_ComposeCustomBlendMode
*/
typedef enum SDL_BlendMode
{
@ -66,7 +67,8 @@ typedef enum SDL_BlendMode
} SDL_BlendMode;
/**
* The blend operation used when combining source and destination pixel components.
* The blend operation used when combining source and destination pixel
* components.
*
* \since This enum is available since SDL 3.0.0.
*/
@ -82,10 +84,10 @@ typedef enum SDL_BlendOperation
/**
* The normalized factor used to multiply pixel components.
*
* The blend factors are multiplied with the pixels from a drawing
* operation (src) and the pixels from the render target (dst) before
* the blend operation. The comma-separated factors listed above are always
* applied in the component order red, green, blue, and alpha.
* The blend factors are multiplied with the pixels from a drawing operation
* (src) and the pixels from the render target (dst) before the blend
* operation. The comma-separated factors listed above are always applied in
* the component order red, green, blue, and alpha.
*
* \since This enum is available since SDL 3.0.0.
*/

11
include/SDL3/SDL_camera.h
View File

@ -59,12 +59,13 @@ typedef struct SDL_Camera SDL_Camera;
/**
* The details of an output format for a camera device.
*
* Cameras often support multiple formats; each one will be encapsulated in this struct.
* Cameras often support multiple formats; each one will be encapsulated in
* this struct.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GetCameraDeviceSupportedFormats
* \sa SDL_GetCameraFormat
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_CameraSpec
{
@ -78,9 +79,9 @@ typedef struct SDL_CameraSpec
/**
* The position of camera in relation to system device.
*
* \sa SDL_GetCameraDevicePosition
*
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_GetCameraDevicePosition
*/
typedef enum SDL_CameraPosition
{

3
include/SDL3/SDL_dialog.h
View File

@ -34,7 +34,8 @@ extern "C" {
/**
* An entry for filters for file dialogs.
*
* `name` is a user-readable label for the filter (for example, "Office document").
* `name` is a user-readable label for the filter (for example, "Office
* document").
*
* `pattern` is a semicolon-separated list of file extensions (for example,
* "doc;docx"). File extensions may only contain alphanumeric characters,

31
include/SDL3/SDL_events.h
View File

@ -303,11 +303,12 @@ typedef struct SDL_KeyboardEvent
} SDL_KeyboardEvent;
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE 64
/**
* Keyboard text editing event structure (event.edit.*)
*
* The `text` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event.
* The `text` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextEditingEvent
{
@ -323,8 +324,8 @@ typedef struct SDL_TextEditingEvent
/**
* Keyboard text input event structure (event.text.*)
*
* The `text` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event.
* The `text` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextInputEvent
{
@ -416,7 +417,7 @@ typedef struct SDL_JoyAxisEvent
} SDL_JoyAxisEvent;
/**
* \brief Joystick trackball motion event structure (event.jball.*)
* Joystick trackball motion event structure (event.jball.*)
*/
typedef struct SDL_JoyBallEvent
{
@ -616,6 +617,7 @@ typedef struct SDL_TouchFingerEvent
#define SDL_DROPEVENT_DATA_SIZE 64
/**
* Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
*/
@ -635,7 +637,8 @@ typedef struct SDL_PenTipEvent
} SDL_PenTipEvent;
/**
* Pressure-sensitive pen motion / pressure / angle event structure (event.pmotion.*)
* Pressure-sensitive pen motion / pressure / angle event structure
* (event.pmotion.*)
*/
typedef struct SDL_PenMotionEvent
{
@ -671,10 +674,11 @@ typedef struct SDL_PenButtonEvent
} SDL_PenButtonEvent;
/**
* An event used to drop text or request a file open by the system (event.drop.*)
* An event used to drop text or request a file open by the system
* (event.drop.*)
*
* The `data` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event. Do not free it!
* The `data` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event. Do not free it!
*/
typedef struct SDL_DropEvent
{
@ -689,7 +693,8 @@ typedef struct SDL_DropEvent
} SDL_DropEvent;
/**
* An event triggered when the clipboard contents have changed (event.clipboard.*)
* An event triggered when the clipboard contents have changed
* (event.clipboard.*)
*/
typedef struct SDL_ClipboardEvent
{
@ -726,9 +731,9 @@ typedef struct SDL_QuitEvent
*
* This event is unique; it is never created by SDL, but only by the
* application. The event can be pushed onto the event queue using
* SDL_PushEvent(). The contents of the structure members are completely
* up to the programmer; the only requirement is that '''type''' is a value
* obtained from SDL_RegisterEvents().
* SDL_PushEvent(). The contents of the structure members are completely up to
* the programmer; the only requirement is that '''type''' is a value obtained
* from SDL_RegisterEvents().
*/
typedef struct SDL_UserEvent
{

6
include/SDL3/SDL_filesystem.h
View File

@ -142,9 +142,9 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
/**
* The type of the OS-provided default folder for a specific purpose.
*
* Note that the Trash folder isn't included here, because trashing files usually
* involves extra OS-specific functionality to remember the file's original
* location.
* Note that the Trash folder isn't included here, because trashing files
* usually involves extra OS-specific functionality to remember the file's
* original location.
*
* The folders supported per platform are:
*

44
include/SDL3/SDL_gamepad.h
View File

@ -78,22 +78,23 @@ typedef enum SDL_GamepadType
/**
* The list of buttons available on a gamepad
*
* For controllers that use a diamond pattern for the face buttons,
* the south/east/west/north buttons below correspond to the locations
* in the diamond pattern. For Xbox controllers, this would be A/B/X/Y,
* for Nintendo Switch controllers, this would be B/A/Y/X, for
* PlayStation controllers this would be Cross/Circle/Square/Triangle.
* For controllers that use a diamond pattern for the face buttons, the
* south/east/west/north buttons below correspond to the locations in the
* diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo
* Switch controllers, this would be B/A/Y/X, for PlayStation controllers this
* would be Cross/Circle/Square/Triangle.
*
* For controllers that don't use a diamond pattern for the face buttons,
* the south/east/west/north buttons indicate the buttons labeled A, B,
* C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are
* the primary, secondary, etc. buttons.
* For controllers that don't use a diamond pattern for the face buttons, the
* south/east/west/north buttons indicate the buttons labeled A, B, C, D, or
* 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary,
* secondary, etc. buttons.
*
* The activate action is often the south button and the cancel action
* is often the east button, but in some regions this is reversed, so
* your game should allow remapping actions based on user preferences.
* The activate action is often the south button and the cancel action is
* often the east button, but in some regions this is reversed, so your game
* should allow remapping actions based on user preferences.
*
* You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
* You can query the labels for the face buttons using
* SDL_GetGamepadButtonLabel()
*/
typedef enum SDL_GamepadButton
{
@ -130,9 +131,11 @@ typedef enum SDL_GamepadButton
/**
* The set of gamepad button labels
*
* This isn't a complete set, just the face buttons to make it easy to show button prompts.
* This isn't a complete set, just the face buttons to make it easy to show
* button prompts.
*
* For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
* For a complete set, you should look at the button and gamepad type and have
* a set of symbols that work well with your art style.
*/
typedef enum SDL_GamepadButtonLabel
{
@ -150,12 +153,13 @@ typedef enum SDL_GamepadButtonLabel
/**
* The list of axes available on a gamepad
*
* Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX,
* and are centered within ~8000 of zero, though advanced UI will allow users to set
* or autodetect the dead zone, which varies between gamepads.
* Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
* SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
* advanced UI will allow users to set or autodetect the dead zone, which
* varies between gamepads.
*
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX
* (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
* pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
* same range that will be reported by the lower-level SDL_GetJoystickAxis().
*/
typedef enum SDL_GamepadAxis

22
include/SDL3/SDL_guid.h
View File

@ -38,19 +38,19 @@ extern "C" {
#endif
/**
* An SDL_GUID is a 128-bit identifier for an input device that
* identifies that device across runs of SDL programs on the same
* platform. If the device is detached and then re-attached to a
* different port, or if the base system is rebooted, the device
* should still report the same GUID.
* An SDL_GUID is a 128-bit identifier for an input device that identifies
* that device across runs of SDL programs on the same platform.
*
* GUIDs are as precise as possible but are not guaranteed to
* distinguish physically distinct but equivalent devices. For
* example, two game controllers from the same vendor with the same
* product ID and revision may have the same GUID.
* If the device is detached and then re-attached to a different port, or if
* the base system is rebooted, the device should still report the same GUID.
*
* GUIDs may be platform-dependent (i.e., the same device may report
* different GUIDs on different operating systems).
* GUIDs are as precise as possible but are not guaranteed to distinguish
* physically distinct but equivalent devices. For example, two game
* controllers from the same vendor with the same product ID and revision may
* have the same GUID.
*
* GUIDs may be platform-dependent (i.e., the same device may report different
* GUIDs on different operating systems).
*/
typedef struct SDL_GUID {
Uint8 data[16];

82
include/SDL3/SDL_haptic.h
View File

@ -359,8 +359,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Use this value to play an effect on the steering wheel axis.
*
* This provides better compatibility across platforms and devices as SDL
* will guess the correct axis.
* This provides better compatibility across platforms and devices as SDL will
* guess the correct axis.
*
* \sa SDL_HapticDirection
*/
@ -385,8 +385,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Structure that represents a haptic direction.
*
* This is the direction where the force comes from,
* instead of the direction in which the force is exerted.
* This is the direction where the force comes from, instead of the direction
* in which the force is exerted.
*
* Directions can be specified by:
*
@ -394,8 +394,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
* - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
*
* Cardinal directions of the haptic device are relative to the positioning
* of the device. North is considered to be away from the user.
* Cardinal directions of the haptic device are relative to the positioning of
* the device. North is considered to be away from the user.
*
* The following diagram represents the cardinal directions:
*
@ -426,31 +426,31 @@ typedef struct SDL_Haptic SDL_Haptic;
* ---ooO-(_)-Ooo---
* ```
*
* If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
* degree starting north and turning clockwise. SDL_HAPTIC_POLAR only uses
* the first `dir` parameter. The cardinal directions would be:
* If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree
* starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first
* `dir` parameter. The cardinal directions would be:
*
* - North: 0 (0 degrees)
* - East: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - West: 27000 (270 degrees)
*
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
* (X axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses
* the first three `dir` parameters. The cardinal directions would be:
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X
* axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first
* three `dir` parameters. The cardinal directions would be:
*
* - North: 0,-1, 0
* - East: 1, 0, 0
* - South: 0, 1, 0
* - West: -1, 0, 0
*
* The Z axis represents the height of the effect if supported, otherwise
* it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you
* can use any multiple you want, only the direction matters.
* The Z axis represents the height of the effect if supported, otherwise it's
* unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can
* use any multiple you want, only the direction matters.
*
* If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
* The first two `dir` parameters are used. The `dir` parameters are as
* follows (all values are in hundredths of degrees):
* If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The
* first two `dir` parameters are used. The `dir` parameters are as follows
* (all values are in hundredths of degrees):
*
* - Degrees from (1, 0) rotated towards (0, 1).
* - Degrees towards (0, 0, 1) (device needs at least 3 axes).
@ -495,8 +495,8 @@ typedef struct SDL_HapticDirection
*
* This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
*
* A constant effect applies a constant force in the specified direction
* to the joystick.
* A constant effect applies a constant force in the specified direction to
* the joystick.
*
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
@ -536,12 +536,12 @@ typedef struct SDL_HapticConstant
* - SDL_HAPTIC_SAWTOOTHUP
* - SDL_HAPTIC_SAWTOOTHDOWN
*
* A periodic effect consists in a wave-shaped effect that repeats itself
* over time. The type determines the shape of the wave and the parameters
* A periodic effect consists in a wave-shaped effect that repeats itself over
* time. The type determines the shape of the wave and the parameters
* determine the dimensions of the wave.
*
* Phase is given by hundredth of a degree meaning that giving the phase a value
* of 9000 will displace it 25% of its period. Here are sample values:
* Phase is given by hundredth of a degree meaning that giving the phase a
* value of 9000 will displace it 25% of its period. Here are sample values:
*
* - 0: No phase displacement.
* - 9000: Displaced 25% of its period.
@ -626,11 +626,11 @@ typedef struct SDL_HapticPeriodic
*
* Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first
* refers to the X axis, the second refers to the Y axis and the third
* refers to the Z axis. The right terms refer to the positive side of the
* axis and the left terms refer to the negative side of the axis. Please
* refer to the SDL_HapticDirection diagram for which side is positive and
* which is negative.
* refers to the X axis, the second refers to the Y axis and the third refers
* to the Z axis. The right terms refer to the positive side of the axis and
* the left terms refer to the negative side of the axis. Please refer to the
* SDL_HapticDirection diagram for which side is positive and which is
* negative.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
@ -668,10 +668,10 @@ typedef struct SDL_HapticCondition
*
* This struct is exclusively for the SDL_HAPTIC_RAMP effect.
*
* The ramp effect starts at start strength and ends at end strength.
* It augments in linear fashion. If you use attack and fade with a ramp
* the effects get added to the ramp effect making the effect become
* quadratic instead of linear.
* The ramp effect starts at start strength and ends at end strength. It
* augments in linear fashion. If you use attack and fade with a ramp the
* effects get added to the ramp effect making the effect become quadratic
* instead of linear.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
@ -732,8 +732,8 @@ typedef struct SDL_HapticLeftRight
* This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
*
* A custom force feedback effect is much like a periodic effect, where the
* application can define its exact shape. You will have to allocate the
* data yourself. Data should consist of channels * samples Uint16 samples.
* application can define its exact shape. You will have to allocate the data
* yourself. Data should consist of channels * samples Uint16 samples.
*
* If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes.
@ -771,19 +771,19 @@ typedef struct SDL_HapticCustom
/**
* The generic template for any haptic effect.
*
* All values max at 32767 (0x7FFF). Signed values also can be negative.
* Time values unless specified otherwise are in milliseconds.
* All values max at 32767 (0x7FFF). Signed values also can be negative. Time
* values unless specified otherwise are in milliseconds.
*
* You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767
* value. Neither delay, interval, attack_length nor fade_length support
* You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
* Neither delay, interval, attack_length nor fade_length support
* SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
*
* Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
* SDL_HAPTIC_INFINITY.
*
* Button triggers may not be supported on all devices, it is advised to not
* use them if possible. Buttons start at index 1 instead of index 0 like
* the joystick.
* use them if possible. Buttons start at index 1 instead of index 0 like the
* joystick.
*
* If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used.

1
include/SDL3/SDL_hidapi.h
View File

@ -109,6 +109,7 @@ typedef enum SDL_hid_bus_type {
} SDL_hid_bus_type;
/** hidapi info structure */
/**
* Information about a connected HID device
*/

1397
include/SDL3/SDL_hints.h
View File

File diff suppressed because it is too large Load Diff

4
include/SDL3/SDL_init.h
View File

@ -42,8 +42,8 @@ extern "C" {
/**
* Initialization flags for SDL_Init and/or SDL_InitSubSystem
*
* These are the flags which may be passed to SDL_Init(). You should
* specify the subsystems which you will be using in your application.
* These are the flags which may be passed to SDL_Init(). You should specify
* the subsystems which you will be using in your application.
*
* \sa SDL_Init
* \sa SDL_Quit

21
include/SDL3/SDL_iostream.h
View File

@ -56,11 +56,10 @@ typedef enum SDL_IOStatus
/**
* The function pointers that drive an SDL_IOStream.
*
* Applications can provide this struct to SDL_OpenIO() to
* create their own implementation of SDL_IOStream. This is
* not necessarily required, as SDL already offers several
* common types of I/O streams, via functions like SDL_IOFromFile()
* and SDL_IOFromMem().
* Applications can provide this struct to SDL_OpenIO() to create their own
* implementation of SDL_IOStream. This is not necessarily required, as SDL
* already offers several common types of I/O streams, via functions like
* SDL_IOFromFile() and SDL_IOFromMem().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -120,10 +119,10 @@ typedef struct SDL_IOStreamInterface
/**
* The read/write operation structure.
*
* This operates as an opaque handle. There are several APIs to create
* various types of I/O streams, or an app can supply an
* SDL_IOStreamInterface to SDL_OpenIO() to provide their own stream
* implementation behind this struct's abstract interface.
* This operates as an opaque handle. There are several APIs to create various
* types of I/O streams, or an app can supply an SDL_IOStreamInterface to
* SDL_OpenIO() to provide their own stream implementation behind this
* struct's abstract interface.
*
* \since This struct is available since SDL 3.0.0.
*/
@ -323,8 +322,8 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
*
* You must free the returned pointer with SDL_CloseIO().
*
* This function makes a copy of `iface` and the caller does not need to
* keep this data around after this call.
* This function makes a copy of `iface` and the caller does not need to keep
* this data around after this call.
*
* \param iface The function pointers that implement this SDL_IOStream.
* \param userdata The app-controlled pointer that is passed to iface's

6
include/SDL3/SDL_joystick.h
View File

@ -356,8 +356,10 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickTyp
/**
* The structure that defines an extended virtual joystick description
*
* The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_AttachVirtualJoystickEx()
* All other elements of this structure are optional and can be left 0.
* The caller must zero the structure and then initialize the version with
* `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to
* SDL_AttachVirtualJoystickEx() All other elements of this structure are
* optional and can be left 0.
*
* \sa SDL_AttachVirtualJoystickEx
*/

3
include/SDL3/SDL_keyboard.h
View File

@ -44,7 +44,8 @@ typedef Uint32 SDL_KeyboardID;
/**
* The SDL keysym structure, used in key events.
*
* If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event.
* If you are looking for translated character input, see the
* ::SDL_EVENT_TEXT_INPUT event.
*/
typedef struct SDL_Keysym
{

8
include/SDL3/SDL_locale.h
View File

@ -42,10 +42,10 @@ extern "C" {
/**
* A struct to provide locale data.
*
* Locale data is split into a spoken language, like English, and an
* optional country, like Canada. The language will be in ISO-639 format
* (so English would be "en"), and the country, if not NULL, will be an
* ISO-3166 country code (so Canada would be "CA").
* Locale data is split into a spoken language, like English, and an optional
* country, like Canada. The language will be in ISO-639 format (so English
* would be "en"), and the country, if not NULL, will be an ISO-3166 country
* code (so Canada would be "CA").
*
* \since This function is available since SDL 3.0.0.
*

7
include/SDL3/SDL_log.h
View File

@ -56,10 +56,9 @@ extern "C" {
/**
* The predefined log categories
*
* By default the application category is enabled at the INFO level,
* the assert category is enabled at the WARN level, test is enabled
* at the VERBOSE level and all other categories are enabled at the
* ERROR level.
* By default the application category is enabled at the INFO level, the
* assert category is enabled at the WARN level, test is enabled at the
* VERBOSE level and all other categories are enabled at the ERROR level.
*/
typedef enum SDL_LogCategory
{

4
include/SDL3/SDL_messagebox.h
View File

@ -33,7 +33,9 @@ extern "C" {
#endif
/**
* SDL_MessageBox flags. If supported will display warning icon, etc.
* SDL_MessageBox flags.
*
* If supported will display warning icon, etc.
*/
typedef enum SDL_MessageBoxFlags
{

4
include/SDL3/SDL_mutex.h
View File

@ -116,8 +116,8 @@ extern "C" {
#endif
/**
* Synchronization functions which can time out return this value
* if they time out.
* Synchronization functions which can time out return this value if they time
* out.
*/
#define SDL_MUTEX_TIMEDOUT 1

30
include/SDL3/SDL_pen.h
View File

@ -66,11 +66,12 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio
/**
* Pen axis indices
*
* Below are the valid indices to the "axis" array from SDL_PenMotionEvent and SDL_PenButtonEvent.
* The axis indices form a contiguous range of ints from 0 to SDL_PEN_AXIS_LAST, inclusive.
* All "axis[]" entries are either normalised to 0..1 or report a (positive or negative)
* angle in degrees, with 0.0 representing the centre.
* Not all pens/backends support all axes: unsupported entries are always "0.0f".
* Below are the valid indices to the "axis" array from SDL_PenMotionEvent and
* SDL_PenButtonEvent. The axis indices form a contiguous range of ints from 0
* to SDL_PEN_AXIS_LAST, inclusive. All "axis[]" entries are either normalised
* to 0..1 or report a (positive or negative) angle in degrees, with 0.0
* representing the centre. Not all pens/backends support all axes:
* unsupported entries are always "0.0f".
*
* To convert angles for tilt and rotation into vector representation, use
* SDL_sinf on the XTILT, YTILT, or ROTATION component, for example:
@ -122,7 +123,8 @@ typedef enum SDL_PenAxis
/**
* Pen types
*
* Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
* Some pens identify as a particular type of drawing device (e.g., an
* airbrush or a pencil).
*
* \since This enum is available since SDL 3.0.0
*/
@ -221,10 +223,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
* \returns A string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use
* SDL_GetPenGUID() for (best-effort) unique identifiers. The
* pointer is managed by the SDL pen subsystem and must not be
* deallocated. The pointer remains valid until SDL is shut down.
* Returns NULL on error (cf. SDL_GetError())
* SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
* is managed by the SDL pen subsystem and must not be deallocated.
* The pointer remains valid until SDL is shut down. Returns NULL on
* error (cf. SDL_GetError())
*
* \since This function is available since SDL 3.0.0
*/
@ -258,10 +260,10 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL
* \param instance_id The pen to query.
* \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
* Note that the pen type does not dictate whether the pen tip is
* SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a
* pen is being used for drawing or in eraser mode, check either the
* pen tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK
* in the pen state.
* SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen
* is being used for drawing or in eraser mode, check either the pen
* tip on SDL_EVENT_PEN_DOWN, or the flag SDL_PEN_ERASER_MASK in the
* pen state.
*
* \since This function is available since SDL 3.0.0
*/

24
include/SDL3/SDL_pixels.h
View File

@ -457,7 +457,8 @@ typedef enum SDL_ColorType
} SDL_ColorType;
/**
* The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
* The color range, as described by
* https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
*/
typedef enum SDL_ColorRange
{
@ -467,7 +468,8 @@ typedef enum SDL_ColorRange
} SDL_ColorRange;
/**
* The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
* The color primaries, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en
*/
typedef enum SDL_ColorPrimaries
{
@ -488,7 +490,8 @@ typedef enum SDL_ColorPrimaries
} SDL_ColorPrimaries;
/**
* The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
* The transfer characteristics, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en
*/
typedef enum SDL_TransferCharacteristics
{
@ -514,7 +517,8 @@ typedef enum SDL_TransferCharacteristics
} SDL_TransferCharacteristics;
/**
* The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en
* The matrix coefficients, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en
*/
typedef enum SDL_MatrixCoefficients
{
@ -663,9 +667,10 @@ typedef enum SDL_Colorspace
/**
* A structure that represents a color as RGBA components.
*
* The bits of this structure can be directly reinterpreted as an integer-packed
* color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
* on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
* The bits of this structure can be directly reinterpreted as an
* integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format
* (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and
* SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
*
* \since This struct is available since SDL 3.0.0.
*/
@ -712,9 +717,8 @@ typedef struct SDL_Palette
/**
* Details about the format of a pixel.
*
* Generally this is used with SDL_Surface, and covers many
* possible configurations, including paletted data and various
* bit patterns.
* Generally this is used with SDL_Surface, and covers many possible
* configurations, including paletted data and various bit patterns.
*
* \since This struct is available since SDL 3.0.0.
*/

19
include/SDL3/SDL_rect.h
View File

@ -40,10 +40,10 @@ extern "C" {
/**
* The structure that defines a point (using integers).
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GetRectEnclosingPoints
* \sa SDL_PointInRect
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_Point
{
@ -54,10 +54,10 @@ typedef struct SDL_Point
/**
* The structure that defines a point (using floating point values).
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GetRectEnclosingPointsFloat
* \sa SDL_PointInRectFloat
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_FPoint
{
@ -69,6 +69,8 @@ typedef struct SDL_FPoint
/**
* A rectangle, with the origin at the upper left (using integers).
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_RectEmpty
* \sa SDL_RectsEqual
* \sa SDL_HasRectIntersection
@ -76,8 +78,6 @@ typedef struct SDL_FPoint
* \sa SDL_GetRectAndLineIntersection
* \sa SDL_GetRectUnion
* \sa SDL_GetRectEnclosingPoints
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_Rect
{
@ -87,7 +87,10 @@ typedef struct SDL_Rect
/**
* A rectangle, with the origin at the upper left (using floating point values).
* A rectangle, with the origin at the upper left (using floating point
* values).
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_RectEmptyFloat
* \sa SDL_RectsEqualFloat
@ -98,8 +101,6 @@ typedef struct SDL_Rect
* \sa SDL_GetRectUnionFloat
* \sa SDL_GetRectEnclosingPointsFloat
* \sa SDL_PointInRectFloat
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_FRect
{

16
include/SDL3/SDL_sensor.h
View File

@ -81,16 +81,16 @@ typedef enum
/**
* Accelerometer sensor.
*
* The accelerometer returns the current acceleration in SI meters per
* second squared. This measurement includes the force of gravity, so
* a device at rest will have an value of SDL_STANDARD_GRAVITY away
* from the center of the earth, which is a positive Y value.
* The accelerometer returns the current acceleration in SI meters per second
* squared. This measurement includes the force of gravity, so a device at
* rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
* earth, which is a positive Y value.
*
* values[0]: Acceleration on the x axis
* values[1]: Acceleration on the y axis
* values[0]: Acceleration on the x axis values[1]: Acceleration on the y axis
* values[2]: Acceleration on the z axis
*
* For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows:
* For phones and tablets held in natural orientation and game controllers
* held in front of you, the axes are defined as follows:
*
* - -X ... +X : left ... right
* - -Y ... +Y : bottom ... top
@ -98,7 +98,7 @@ typedef enum
*
* The axis data is not changed when the device is rotated.
*
* \sa SDL_GetCurrentDisplayOrientation()
* \sa SDL_GetCurrentDisplayOrientation
*/
#define SDL_STANDARD_GRAVITY 9.80665f

14
include/SDL3/SDL_stdinc.h
View File

@ -146,30 +146,35 @@ typedef int SDL_bool;
#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
typedef int8_t Sint8;
/**
* An unsigned 8-bit integer type.
*/
#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
typedef uint8_t Uint8;
/**
* A signed 16-bit integer type.
*/
#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
typedef int16_t Sint16;
/**
* An unsigned 16-bit integer type.
*/
#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
typedef uint16_t Uint16;
/**
* A signed 32-bit integer type.
*/
#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
typedef int32_t Sint32;
/**
* An unsigned 32-bit integer type.
*/
@ -183,6 +188,7 @@ typedef uint32_t Uint32;
#define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */
#define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
typedef int64_t Sint64;
/**
* An unsigned 64-bit integer type.
*/
@ -191,10 +197,12 @@ typedef int64_t Sint64;
typedef uint64_t Uint64;
/**
* SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970).
* SDL times are signed, 64-bit integers representing nanoseconds since the
* Unix epoch (Jan 1, 1970).
*
* They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() and SDL_SECONDS_TO_NS(),
* and between Windows FILETIME values with SDL_TimeToWindows() and SDL_TimeFromWindows().
* They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS()
* and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
* SDL_TimeToWindows() and SDL_TimeFromWindows().
*/
#define SDL_MAX_TIME SDL_MAX_SINT64
#define SDL_MIN_TIME SDL_MIN_SINT64

24
include/SDL3/SDL_surface.h
View File

@ -89,21 +89,17 @@ typedef enum SDL_FlipMode
/**
* A collection of pixels used in software blitting.
*
* Pixels are arranged in memory in rows, with the top row first.
* Each row occupies an amount of memory given by the pitch (sometimes
* known as the row stride in non-SDL APIs).
* Pixels are arranged in memory in rows, with the top row first. Each row
* occupies an amount of memory given by the pitch (sometimes known as the row
* stride in non-SDL APIs).
*
* Within each row, pixels are arranged from left to right until the
* width is reached.
* Each pixel occupies a number of bits appropriate for its format, with
* most formats representing each pixel as one or more whole bytes
* (in some indexed formats, instead multiple pixels are packed into
* each byte), and a byte order given by the format.
* After encoding all pixels, any remaining bytes to reach the pitch are
* used as padding to reach a desired alignment, and have undefined contents.
*
* \note This structure should be treated as read-only, except for \c pixels,
* which, if not NULL, contains the raw pixel data for the surface.
* Within each row, pixels are arranged from left to right until the width is
* reached. Each pixel occupies a number of bits appropriate for its format,
* with most formats representing each pixel as one or more whole bytes (in
* some indexed formats, instead multiple pixels are packed into each byte),
* and a byte order given by the format. After encoding all pixels, any
* remaining bytes to reach the pitch are used as padding to reach a desired
* alignment, and have undefined contents.
*/
typedef struct SDL_Surface
{

4
include/SDL3/SDL_system.h
View File

@ -337,8 +337,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
/**
See the official Android developer guide for more information:
http://developer.android.com/guide/topics/data/data-storage.html
* See the official Android developer guide for more information:
* http://developer.android.com/guide/topics/data/data-storage.html
*/
#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02

11
include/SDL3/SDL_thread.h
View File

@ -58,12 +58,11 @@ typedef Uint32 SDL_TLSID;
/**
* The SDL thread priority.
*
* SDL will make system changes as necessary in order to apply the thread priority.
* Code which attempts to control thread state related to priority should be aware
* that calling SDL_SetThreadPriority may alter such state.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior.
*
* \note On many systems you require special privileges to set high or time critical priority.
* SDL will make system changes as necessary in order to apply the thread
* priority. Code which attempts to control thread state related to priority
* should be aware that calling SDL_SetThreadPriority may alter such state.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this
* behavior.
*/
typedef enum SDL_ThreadPriority {
SDL_THREAD_PRIORITY_LOW,

3
include/SDL3/SDL_time.h
View File

@ -38,7 +38,8 @@ extern "C" {
#endif
/**
* A structure holding a calendar date and time broken down into its components.
* A structure holding a calendar date and time broken down into its
* components.
*/
typedef struct SDL_DateTime
{

19
include/SDL3/SDL_version.h
View File

@ -41,15 +41,14 @@ extern "C" {
* Information about the version of SDL in use.
*
* Represents the library's version as three levels: major revision
* (increments with massive changes, additions, and enhancements),
* minor revision (increments with backwards-compatible changes to the
* major revision), and patchlevel (increments with fixes to the minor
* revision).
* (increments with massive changes, additions, and enhancements), minor
* revision (increments with backwards-compatible changes to the major
* revision), and patchlevel (increments with fixes to the minor revision).
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_VERSION
* \sa SDL_GetVersion
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_Version
{
@ -70,15 +69,15 @@ typedef struct SDL_Version
* library you compiled against. This is determined by what header the
* compiler uses. Note that if you dynamically linked the library, you might
* have a slightly newer or older version at runtime. That version can be
* determined with SDL_GetVersion(), which, unlike SDL_VERSION(),
* is not a macro.
* determined with SDL_GetVersion(), which, unlike SDL_VERSION(), is not a
* macro.
*
* \param x A pointer to an SDL_Version struct to initialize.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_Version
* \sa SDL_GetVersion
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_VERSION(x) \
{ \

27
include/SDL3/SDL_video.h
View File

@ -76,13 +76,13 @@ typedef enum SDL_SystemTheme
/**
* The structure that defines a display mode.
*
* \sa SDL_GetFullscreenDisplayModes()
* \sa SDL_GetDesktopDisplayMode()
* \sa SDL_GetCurrentDisplayMode()
* \sa SDL_SetWindowFullscreenMode()
* \sa SDL_GetWindowFullscreenMode()
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GetFullscreenDisplayModes
* \sa SDL_GetDesktopDisplayMode
* \sa SDL_GetCurrentDisplayMode
* \sa SDL_SetWindowFullscreenMode
* \sa SDL_GetWindowFullscreenMode
*/
typedef struct SDL_DisplayMode
{
@ -207,9 +207,17 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);
/**
* An enumeration of OpenGL configuration attributes.
*
* While you can set most OpenGL attributes normally, the attributes listed above must be known before SDL creates the window that will be used with the OpenGL context. These attributes are set and read with SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
* While you can set most OpenGL attributes normally, the attributes listed
* above must be known before SDL creates the window that will be used with
* the OpenGL context. These attributes are set and read with
* SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
*
* In some cases, these attributes are minimum requests; the GL does not promise to give you exactly what you asked for. It's possible to ask for a 16-bit depth buffer and get a 24-bit one instead, for example, or to ask for no stencil buffer and still have one available. Context creation should fail if the GL can't provide your requested attributes at a minimum, but you should check to see exactly what you got.
* In some cases, these attributes are minimum requests; the GL does not
* promise to give you exactly what you asked for. It's possible to ask for a
* 16-bit depth buffer and get a 24-bit one instead, for example, or to ask
* for no stencil buffer and still have one available. Context creation should
* fail if the GL can't provide your requested attributes at a minimum, but
* you should check to see exactly what you got.
*
* \since This enum is available since SDL 3.0.0.
*/
@ -271,7 +279,8 @@ typedef enum SDL_GLcontextFlag
} SDL_GLcontextFlag;
/**
* Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR attribute.
* Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR
* attribute.
*
* \since This enum is available since SDL 3.0.0.
*/