mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-06 03:18:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: heavy editing to make this happy with latest wikibridge.

Browse Source 
The public headers saw lots of cleanups, backporting from SDL3 docs, and
merging with the wiki.

The markdown files in docs/README-*.md were converted to Unix endlines.
This commit is contained in:
Ryan C. Gordon
2024-04-23 14:19:47 -04:00
parent a96196c958
commit e03ad30a57
80 changed files with 6963 additions and 6115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

637
build-scripts/wikiheaders.pl
View File

File diff suppressed because it is too large Load Diff

5
include/SDL_atomic.h
View File

@@ -257,8 +257,9 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
/** /**
* \brief A type representing an atomic integer value. It is a struct * A type representing an atomic integer value.
* so people don't accidentally use numeric operations on it. *
* It is a struct so people don't accidentally use numeric operations on it.
*/ */
typedef struct SDL_atomic_t { typedef struct SDL_atomic_t {
int value; int value;

20
include/SDL_audio.h
View File

@@ -169,6 +169,8 @@ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
* The calculated values in this structure are calculated by SDL_OpenAudio(). * The calculated values in this structure are calculated by SDL_OpenAudio().
* *
* For multi-channel audio, the default SDL channel mapping is: * For multi-channel audio, the default SDL channel mapping is:
*
* ```
* 2: FL FR (stereo) * 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround) * 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad) * 4: FL FR BL BR (quad)
@@ -176,6 +178,7 @@ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
* 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR) * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
* 7: FL FR FC LFE BC SL SR (6.1 surround) * 7: FL FR FC LFE BC SL SR (6.1 surround)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround) * 8: FL FR FC LFE BL BR SL SR (7.1 surround)
* ```
*/ */
typedef struct SDL_AudioSpec typedef struct SDL_AudioSpec
{ {
@@ -196,11 +199,11 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
SDL_AudioFormat format); SDL_AudioFormat format);
/** /**
* \brief Upper limit of filters in SDL_AudioCVT * Upper limit of filters in SDL_AudioCVT
* *
* The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is * The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
* currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, * currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one
* one of which is the terminating NULL pointer. * of which is the terminating NULL pointer.
*/ */
#define SDL_AUDIOCVT_MAX_FILTERS 9 #define SDL_AUDIOCVT_MAX_FILTERS 9
@@ -410,11 +413,11 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
/** /**
* SDL Audio Device IDs. * SDL Audio Device IDs.
* *
* A successful call to SDL_OpenAudio() is always device id 1, and legacy * A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL
* SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls * audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
* always returns devices >= 2 on success. The legacy calls are good both * always returns devices >= 2 on success. The legacy calls are good both for
* for backwards compatibility and when you don't care about multiple, * backwards compatibility and when you don't care about multiple, specific,
* specific, or capture devices. * or capture devices.
*/ */
typedef Uint32 SDL_AudioDeviceID; typedef Uint32 SDL_AudioDeviceID;
@@ -875,6 +878,7 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
/** /**
* Loads a WAV from a file. * Loads a WAV from a file.
*
* Compatibility convenience function. * Compatibility convenience function.
*/ */
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \ #define SDL_LoadWAV(file, spec, audio_buf, audio_len) \

6
include/SDL_bits.h
View File

@@ -56,6 +56,12 @@ extern __inline int _SDL_bsr_watcom(Uint32);
modify exact [eax] nomemory; modify exact [eax] nomemory;
#endif #endif
/**
* Use this function to get the index of the most significant (set) bit in a
*
* \param x the number to find the MSB of
* \returns the index of the most significant bit of x, or -1 if x is 0.
*/
SDL_FORCE_INLINE int SDL_FORCE_INLINE int
SDL_MostSignificantBitIndex32(Uint32 x) SDL_MostSignificantBitIndex32(Uint32 x)
{ {

7
include/SDL_blendmode.h
View File

@@ -35,7 +35,7 @@ extern "C" {
#endif #endif
/** /**
* \brief The blend mode used in SDL_RenderCopy() and drawing operations. * The blend mode used in SDL_RenderCopy() and drawing operations.
*/ */
typedef enum SDL_BlendMode typedef enum SDL_BlendMode
{ {
@@ -60,7 +60,8 @@ typedef enum SDL_BlendMode
} SDL_BlendMode; } SDL_BlendMode;
/** /**
* \brief The blend operation used when combining source and destination pixel components * The blend operation used when combining source and destination pixel
* components
*/ */
typedef enum SDL_BlendOperation typedef enum SDL_BlendOperation
{ {
@@ -72,7 +73,7 @@ typedef enum SDL_BlendOperation
} SDL_BlendOperation; } SDL_BlendOperation;
/** /**
* \brief The normalized factor used to multiply pixel components * The normalized factor used to multiply pixel components
*/ */
typedef enum SDL_BlendFactor typedef enum SDL_BlendFactor
{ {

39
include/SDL_endian.h
View File

@@ -180,6 +180,16 @@ extern __inline Uint16 SDL_Swap16(Uint16);
parm [ax] \ parm [ax] \
modify [ax]; modify [ax];
#else #else
/**
* Use this function to swap the byte order of a 16-bit value.
*
* \param x the value to be swapped
* \returns the swapped value.
*
* \sa SDL_SwapBE16
* \sa SDL_SwapLE16
*/
SDL_FORCE_INLINE Uint16 SDL_FORCE_INLINE Uint16
SDL_Swap16(Uint16 x) SDL_Swap16(Uint16 x)
{ {
@@ -231,6 +241,16 @@ extern __inline Uint32 SDL_Swap32(Uint32);
parm [eax] \ parm [eax] \
modify [eax]; modify [eax];
#else #else
/**
* Use this function to swap the byte order of a 32-bit value.
*
* \param x the value to be swapped
* \returns the swapped value.
*
* \sa SDL_SwapBE32
* \sa SDL_SwapLE32
*/
SDL_FORCE_INLINE Uint32 SDL_FORCE_INLINE Uint32
SDL_Swap32(Uint32 x) SDL_Swap32(Uint32 x)
{ {
@@ -276,6 +296,16 @@ extern __inline Uint64 SDL_Swap64(Uint64);
parm [eax edx] \ parm [eax edx] \
modify [eax edx]; modify [eax edx];
#else #else
/**
* Use this function to swap the byte order of a 64-bit value.
*
* \param x the value to be swapped
* \returns the swapped value.
*
* \sa SDL_SwapBE64
* \sa SDL_SwapLE64
*/
SDL_FORCE_INLINE Uint64 SDL_FORCE_INLINE Uint64
SDL_Swap64(Uint64 x) SDL_Swap64(Uint64 x)
{ {
@@ -293,6 +323,15 @@ SDL_Swap64(Uint64 x)
#endif #endif
/**
* Use this function to swap the byte order of a floating point value.
*
* \param x the value to be swapped
* \returns the swapped value.
*
* \sa SDL_SwapFloatBE
* \sa SDL_SwapFloatLE
*/
SDL_FORCE_INLINE float SDL_FORCE_INLINE float
SDL_SwapFloat(float x) SDL_SwapFloat(float x)
{ {

163
include/SDL_events.h
View File

@@ -167,7 +167,7 @@ typedef enum SDL_EventType
/* Internal events */ /* Internal events */
SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */ SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
/** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use, /** Events SDL_USEREVENT through SDL_LASTEVENT are for your use,
* and should be allocated with SDL_RegisterEvents() * and should be allocated with SDL_RegisterEvents()
*/ */
SDL_USEREVENT = 0x8000, SDL_USEREVENT = 0x8000,
@@ -179,7 +179,7 @@ typedef enum SDL_EventType
} SDL_EventType; } SDL_EventType;
/** /**
* \brief Fields shared by every event * Fields shared by every event
*/ */
typedef struct SDL_CommonEvent typedef struct SDL_CommonEvent
{ {
@@ -188,14 +188,14 @@ typedef struct SDL_CommonEvent
} SDL_CommonEvent; } SDL_CommonEvent;
/** /**
* \brief Display state change event data (event.display.*) * Display state change event data (event.display.*)
*/ */
typedef struct SDL_DisplayEvent typedef struct SDL_DisplayEvent
{ {
Uint32 type; /**< ::SDL_DISPLAYEVENT */ Uint32 type; /**< SDL_DISPLAYEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 display; /**< The associated display index */ Uint32 display; /**< The associated display index */
Uint8 event; /**< ::SDL_DisplayEventID */ Uint8 event; /**< SDL_DisplayEventID */
Uint8 padding1; Uint8 padding1;
Uint8 padding2; Uint8 padding2;
Uint8 padding3; Uint8 padding3;
@@ -203,14 +203,14 @@ typedef struct SDL_DisplayEvent
} SDL_DisplayEvent; } SDL_DisplayEvent;
/** /**
* \brief Window state change event data (event.window.*) * Window state change event data (event.window.*)
*/ */
typedef struct SDL_WindowEvent typedef struct SDL_WindowEvent
{ {
Uint32 type; /**< ::SDL_WINDOWEVENT */ Uint32 type; /**< SDL_WINDOWEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The associated window */ Uint32 windowID; /**< The associated window */
Uint8 event; /**< ::SDL_WindowEventID */ Uint8 event; /**< SDL_WindowEventID */
Uint8 padding1; Uint8 padding1;
Uint8 padding2; Uint8 padding2;
Uint8 padding3; Uint8 padding3;
@@ -219,14 +219,14 @@ typedef struct SDL_WindowEvent
} SDL_WindowEvent; } SDL_WindowEvent;
/** /**
* \brief Keyboard button event structure (event.key.*) * Keyboard button event structure (event.key.*)
*/ */
typedef struct SDL_KeyboardEvent typedef struct SDL_KeyboardEvent
{ {
Uint32 type; /**< ::SDL_KEYDOWN or ::SDL_KEYUP */ Uint32 type; /**< SDL_KEYDOWN or SDL_KEYUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */ Uint32 windowID; /**< The window with keyboard focus, if any */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 repeat; /**< Non-zero if this is a key repeat */ Uint8 repeat; /**< Non-zero if this is a key repeat */
Uint8 padding2; Uint8 padding2;
Uint8 padding3; Uint8 padding3;
@@ -234,12 +234,13 @@ typedef struct SDL_KeyboardEvent
} SDL_KeyboardEvent; } SDL_KeyboardEvent;
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32) #define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
/** /**
* \brief Keyboard text editing event structure (event.edit.*) * Keyboard text editing event structure (event.edit.*)
*/ */
typedef struct SDL_TextEditingEvent typedef struct SDL_TextEditingEvent
{ {
Uint32 type; /**< ::SDL_TEXTEDITING */ Uint32 type; /**< SDL_TEXTEDITING */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */ Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */ char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
@@ -248,12 +249,12 @@ typedef struct SDL_TextEditingEvent
} SDL_TextEditingEvent; } SDL_TextEditingEvent;
/** /**
* \brief Extended keyboard text editing event structure (event.editExt.*) when text would be * Extended keyboard text editing event structure (event.editExt.*) when text
* truncated if stored in the text buffer SDL_TextEditingEvent * would be truncated if stored in the text buffer SDL_TextEditingEvent
*/ */
typedef struct SDL_TextEditingExtEvent typedef struct SDL_TextEditingExtEvent
{ {
Uint32 type; /**< ::SDL_TEXTEDITING_EXT */ Uint32 type; /**< SDL_TEXTEDITING_EXT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */ Uint32 windowID; /**< The window with keyboard focus, if any */
char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */ char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
@@ -262,23 +263,24 @@ typedef struct SDL_TextEditingExtEvent
} SDL_TextEditingExtEvent; } SDL_TextEditingExtEvent;
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32) #define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
/** /**
* \brief Keyboard text input event structure (event.text.*) * Keyboard text input event structure (event.text.*)
*/ */
typedef struct SDL_TextInputEvent typedef struct SDL_TextInputEvent
{ {
Uint32 type; /**< ::SDL_TEXTINPUT */ Uint32 type; /**< SDL_TEXTINPUT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */ Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */ char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
} SDL_TextInputEvent; } SDL_TextInputEvent;
/** /**
* \brief Mouse motion event structure (event.motion.*) * Mouse motion event structure (event.motion.*)
*/ */
typedef struct SDL_MouseMotionEvent typedef struct SDL_MouseMotionEvent
{ {
Uint32 type; /**< ::SDL_MOUSEMOTION */ Uint32 type; /**< SDL_MOUSEMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@@ -290,16 +292,16 @@ typedef struct SDL_MouseMotionEvent
} SDL_MouseMotionEvent; } SDL_MouseMotionEvent;
/** /**
* \brief Mouse button event structure (event.button.*) * Mouse button event structure (event.button.*)
*/ */
typedef struct SDL_MouseButtonEvent typedef struct SDL_MouseButtonEvent
{ {
Uint32 type; /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */ Uint32 type; /**< SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
Uint8 button; /**< The mouse button index */ Uint8 button; /**< The mouse button index */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */ Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
Uint8 padding1; Uint8 padding1;
Sint32 x; /**< X coordinate, relative to window */ Sint32 x; /**< X coordinate, relative to window */
@@ -307,11 +309,11 @@ typedef struct SDL_MouseButtonEvent
} SDL_MouseButtonEvent; } SDL_MouseButtonEvent;
/** /**
* \brief Mouse wheel event structure (event.wheel.*) * Mouse wheel event structure (event.wheel.*)
*/ */
typedef struct SDL_MouseWheelEvent typedef struct SDL_MouseWheelEvent
{ {
Uint32 type; /**< ::SDL_MOUSEWHEEL */ Uint32 type; /**< SDL_MOUSEWHEEL */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */ Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */ Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@@ -325,11 +327,11 @@ typedef struct SDL_MouseWheelEvent
} SDL_MouseWheelEvent; } SDL_MouseWheelEvent;
/** /**
* \brief Joystick axis motion event structure (event.jaxis.*) * Joystick axis motion event structure (event.jaxis.*)
*/ */
typedef struct SDL_JoyAxisEvent typedef struct SDL_JoyAxisEvent
{ {
Uint32 type; /**< ::SDL_JOYAXISMOTION */ Uint32 type; /**< SDL_JOYAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 axis; /**< The joystick axis index */ Uint8 axis; /**< The joystick axis index */
@@ -341,11 +343,11 @@ typedef struct SDL_JoyAxisEvent
} SDL_JoyAxisEvent; } SDL_JoyAxisEvent;
/** /**
* \brief Joystick trackball motion event structure (event.jball.*) * Joystick trackball motion event structure (event.jball.*)
*/ */
typedef struct SDL_JoyBallEvent typedef struct SDL_JoyBallEvent
{ {
Uint32 type; /**< ::SDL_JOYBALLMOTION */ Uint32 type; /**< SDL_JOYBALLMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 ball; /**< The joystick trackball index */ Uint8 ball; /**< The joystick trackball index */
@@ -357,18 +359,18 @@ typedef struct SDL_JoyBallEvent
} SDL_JoyBallEvent; } SDL_JoyBallEvent;
/** /**
* \brief Joystick hat position change event structure (event.jhat.*) * Joystick hat position change event structure (event.jhat.*)
*/ */
typedef struct SDL_JoyHatEvent typedef struct SDL_JoyHatEvent
{ {
Uint32 type; /**< ::SDL_JOYHATMOTION */ Uint32 type; /**< SDL_JOYHATMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 hat; /**< The joystick hat index */ Uint8 hat; /**< The joystick hat index */
Uint8 value; /**< The hat position value. Uint8 value; /**< The hat position value.
* \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP * \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP
* \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT * \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT
* \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN * \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN
* *
* Note that zero means the POV is centered. * Note that zero means the POV is centered.
*/ */
@@ -377,46 +379,46 @@ typedef struct SDL_JoyHatEvent
} SDL_JoyHatEvent; } SDL_JoyHatEvent;
/** /**
* \brief Joystick button event structure (event.jbutton.*) * Joystick button event structure (event.jbutton.*)
*/ */
typedef struct SDL_JoyButtonEvent typedef struct SDL_JoyButtonEvent
{ {
Uint32 type; /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */ Uint32 type; /**< SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The joystick button index */ Uint8 button; /**< The joystick button index */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1; Uint8 padding1;
Uint8 padding2; Uint8 padding2;
} SDL_JoyButtonEvent; } SDL_JoyButtonEvent;
/** /**
* \brief Joystick device event structure (event.jdevice.*) * Joystick device event structure (event.jdevice.*)
*/ */
typedef struct SDL_JoyDeviceEvent typedef struct SDL_JoyDeviceEvent
{ {
Uint32 type; /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */ Uint32 type; /**< SDL_JOYDEVICEADDED or SDL_JOYDEVICEREMOVED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
} SDL_JoyDeviceEvent; } SDL_JoyDeviceEvent;
/** /**
* \brief Joysick battery level change event structure (event.jbattery.*) * Joysick battery level change event structure (event.jbattery.*)
*/ */
typedef struct SDL_JoyBatteryEvent typedef struct SDL_JoyBatteryEvent
{ {
Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */ Uint32 type; /**< SDL_JOYBATTERYUPDATED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
SDL_JoystickPowerLevel level; /**< The joystick battery level */ SDL_JoystickPowerLevel level; /**< The joystick battery level */
} SDL_JoyBatteryEvent; } SDL_JoyBatteryEvent;
/** /**
* \brief Game controller axis motion event structure (event.caxis.*) * Game controller axis motion event structure (event.caxis.*)
*/ */
typedef struct SDL_ControllerAxisEvent typedef struct SDL_ControllerAxisEvent
{ {
Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */ Uint32 type; /**< SDL_CONTROLLERAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */ Uint8 axis; /**< The controller axis (SDL_GameControllerAxis) */
@@ -429,36 +431,36 @@ typedef struct SDL_ControllerAxisEvent
/** /**
* \brief Game controller button event structure (event.cbutton.*) * Game controller button event structure (event.cbutton.*)
*/ */
typedef struct SDL_ControllerButtonEvent typedef struct SDL_ControllerButtonEvent
{ {
Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */ Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The controller button (SDL_GameControllerButton) */ Uint8 button; /**< The controller button (SDL_GameControllerButton) */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */ Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1; Uint8 padding1;
Uint8 padding2; Uint8 padding2;
} SDL_ControllerButtonEvent; } SDL_ControllerButtonEvent;
/** /**
* \brief Controller device event structure (event.cdevice.*) * Controller device event structure (event.cdevice.*)
*/ */
typedef struct SDL_ControllerDeviceEvent typedef struct SDL_ControllerDeviceEvent
{ {
Uint32 type; /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, ::SDL_CONTROLLERDEVICEREMAPPED, or ::SDL_CONTROLLERSTEAMHANDLEUPDATED */ Uint32 type; /**< SDL_CONTROLLERDEVICEADDED, SDL_CONTROLLERDEVICEREMOVED, SDL_CONTROLLERDEVICEREMAPPED, or SDL_CONTROLLERSTEAMHANDLEUPDATED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */ Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
} SDL_ControllerDeviceEvent; } SDL_ControllerDeviceEvent;
/** /**
* \brief Game controller touchpad event structure (event.ctouchpad.*) * Game controller touchpad event structure (event.ctouchpad.*)
*/ */
typedef struct SDL_ControllerTouchpadEvent typedef struct SDL_ControllerTouchpadEvent
{ {
Uint32 type; /**< ::SDL_CONTROLLERTOUCHPADDOWN or ::SDL_CONTROLLERTOUCHPADMOTION or ::SDL_CONTROLLERTOUCHPADUP */ Uint32 type; /**< SDL_CONTROLLERTOUCHPADDOWN or SDL_CONTROLLERTOUCHPADMOTION or SDL_CONTROLLERTOUCHPADUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Sint32 touchpad; /**< The index of the touchpad */ Sint32 touchpad; /**< The index of the touchpad */
@@ -469,24 +471,24 @@ typedef struct SDL_ControllerTouchpadEvent
} SDL_ControllerTouchpadEvent; } SDL_ControllerTouchpadEvent;
/** /**
* \brief Game controller sensor event structure (event.csensor.*) * Game controller sensor event structure (event.csensor.*)
*/ */
typedef struct SDL_ControllerSensorEvent typedef struct SDL_ControllerSensorEvent
{ {
Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */ Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */ SDL_JoystickID which; /**< The joystick instance id */
Sint32 sensor; /**< The type of the sensor, one of the values of ::SDL_SensorType */ Sint32 sensor; /**< The type of the sensor, one of the values of SDL_SensorType */
float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */ float data[3]; /**< Up to 3 values from the sensor, as defined in SDL_sensor.h */
Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */ Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
} SDL_ControllerSensorEvent; } SDL_ControllerSensorEvent;
/** /**
* \brief Audio device event structure (event.adevice.*) * Audio device event structure (event.adevice.*)
*/ */
typedef struct SDL_AudioDeviceEvent typedef struct SDL_AudioDeviceEvent
{ {
Uint32 type; /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */ Uint32 type; /**< SDL_AUDIODEVICEADDED, or SDL_AUDIODEVICEREMOVED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */ Uint32 which; /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */ Uint8 iscapture; /**< zero if an output device, non-zero if a capture device. */
@@ -497,11 +499,11 @@ typedef struct SDL_AudioDeviceEvent
/** /**
* \brief Touch finger event structure (event.tfinger.*) * Touch finger event structure (event.tfinger.*)
*/ */
typedef struct SDL_TouchFingerEvent typedef struct SDL_TouchFingerEvent
{ {
Uint32 type; /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */ Uint32 type; /**< SDL_FINGERMOTION or SDL_FINGERDOWN or SDL_FINGERUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */ SDL_TouchID touchId; /**< The touch device id */
SDL_FingerID fingerId; SDL_FingerID fingerId;
@@ -515,11 +517,11 @@ typedef struct SDL_TouchFingerEvent
/** /**
* \brief Multiple Finger Gesture Event (event.mgesture.*) * Multiple Finger Gesture Event (event.mgesture.*)
*/ */
typedef struct SDL_MultiGestureEvent typedef struct SDL_MultiGestureEvent
{ {
Uint32 type; /**< ::SDL_MULTIGESTURE */ Uint32 type; /**< SDL_MULTIGESTURE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */ SDL_TouchID touchId; /**< The touch device id */
float dTheta; float dTheta;
@@ -532,11 +534,11 @@ typedef struct SDL_MultiGestureEvent
/** /**
* \brief Dollar Gesture Event (event.dgesture.*) * Dollar Gesture Event (event.dgesture.*)
*/ */
typedef struct SDL_DollarGestureEvent typedef struct SDL_DollarGestureEvent
{ {
Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */ Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */ SDL_TouchID touchId; /**< The touch device id */
SDL_GestureID gestureId; SDL_GestureID gestureId;
@@ -548,13 +550,15 @@ typedef struct SDL_DollarGestureEvent
/** /**
* \brief An event used to request a file open by the system (event.drop.*) * An event used to request a file open by the system (event.drop.*)
*
* This event is enabled by default, you can disable it with SDL_EventState(). * This event is enabled by default, you can disable it with SDL_EventState().
* \note If this event is enabled, you must free the filename in the event. *
* If this event is enabled, you must free the filename in the event.
*/ */
typedef struct SDL_DropEvent typedef struct SDL_DropEvent
{ {
Uint32 type; /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */ Uint32 type; /**< SDL_DROPBEGIN or SDL_DROPFILE or SDL_DROPTEXT or SDL_DROPCOMPLETE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */ char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
Uint32 windowID; /**< The window that was dropped on, if any */ Uint32 windowID; /**< The window that was dropped on, if any */
@@ -562,11 +566,11 @@ typedef struct SDL_DropEvent
/** /**
* \brief Sensor event structure (event.sensor.*) * Sensor event structure (event.sensor.*)
*/ */
typedef struct SDL_SensorEvent typedef struct SDL_SensorEvent
{ {
Uint32 type; /**< ::SDL_SENSORUPDATE */ Uint32 type; /**< SDL_SENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Sint32 which; /**< The instance ID of the sensor */ Sint32 which; /**< The instance ID of the sensor */
float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */ float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_SensorGetData() */
@@ -574,20 +578,20 @@ typedef struct SDL_SensorEvent
} SDL_SensorEvent; } SDL_SensorEvent;
/** /**
* \brief The "quit requested" event * The "quit requested" event
*/ */
typedef struct SDL_QuitEvent typedef struct SDL_QuitEvent
{ {
Uint32 type; /**< ::SDL_QUIT */ Uint32 type; /**< SDL_QUIT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
} SDL_QuitEvent; } SDL_QuitEvent;
/** /**
* \brief A user-defined event type (event.user.*) * A user-defined event type (event.user.*)
*/ */
typedef struct SDL_UserEvent typedef struct SDL_UserEvent
{ {
Uint32 type; /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */ Uint32 type; /**< SDL_USEREVENT through SDL_LASTEVENT-1 */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The associated window if any */ Uint32 windowID; /**< The associated window if any */
Sint32 code; /**< User defined event code */ Sint32 code; /**< User defined event code */
@@ -600,20 +604,21 @@ struct SDL_SysWMmsg;
typedef struct SDL_SysWMmsg SDL_SysWMmsg; typedef struct SDL_SysWMmsg SDL_SysWMmsg;
/** /**
* \brief A video driver dependent system event (event.syswm.*) * A video driver dependent system event (event.syswm.*)
*
* This event is disabled by default, you can enable it with SDL_EventState() * This event is disabled by default, you can enable it with SDL_EventState()
* *
* \note If you want to use this event, you should include SDL_syswm.h. * If you want to use this event, you should include SDL_syswm.h.
*/ */
typedef struct SDL_SysWMEvent typedef struct SDL_SysWMEvent
{ {
Uint32 type; /**< ::SDL_SYSWMEVENT */ Uint32 type; /**< SDL_SYSWMEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */ Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */ SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
} SDL_SysWMEvent; } SDL_SysWMEvent;
/** /**
* \brief General event structure * General event structure
*/ */
typedef union SDL_Event typedef union SDL_Event
{ {
@@ -961,11 +966,11 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
/** /**
* A function pointer used for callbacks that watch the event queue. * A function pointer used for callbacks that watch the event queue.
* *
* \param userdata what was passed as `userdata` to SDL_SetEventFilter() * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
* or SDL_AddEventWatch, etc * SDL_AddEventWatch, etc
* \param event the event that triggered the callback * \param event the event that triggered the callback
* \returns 1 to permit event to be added to the queue, and 0 to disallow * \returns 1 to permit event to be added to the queue, and 0 to disallow it.
* it. When used with SDL_AddEventWatch, the return value is ignored. * When used with SDL_AddEventWatch, the return value is ignored.
* *
* \sa SDL_SetEventFilter * \sa SDL_SetEventFilter
* \sa SDL_AddEventWatch * \sa SDL_AddEventWatch
@@ -988,7 +993,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
* interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
* application at the next event poll. * application at the next event poll.
* *
* There is one caveat when dealing with the ::SDL_QuitEvent event type. The * There is one caveat when dealing with the SDL_QuitEvent event type. The
* event filter is only called when the window manager desires to close the * event filter is only called when the window manager desires to close the
* application window. If the event filter returns 1, then the window will be * application window. If the event filter returns 1, then the window will be
* closed, otherwise the window will remain open if possible. * closed, otherwise the window will remain open if possible.

19
include/SDL_gamecontroller.h
View File

@@ -44,7 +44,7 @@ extern "C" {
* \file SDL_gamecontroller.h * \file SDL_gamecontroller.h
* *
* In order to use these functions, SDL_Init() must have been called * In order to use these functions, SDL_Init() must have been called
* with the ::SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system * with the SDL_INIT_GAMECONTROLLER flag. This causes SDL to scan the system
* for game controllers, and load appropriate drivers. * for game controllers, and load appropriate drivers.
* *
* If you would like to receive controller updates while the application * If you would like to receive controller updates while the application
@@ -166,7 +166,8 @@ typedef struct SDL_GameControllerButtonBind
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw); extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
/** /**
* Load a set of mappings from a file, filtered by the current SDL_GetPlatform() * Load a set of mappings from a file, filtered by the current
* SDL_GetPlatform()
* *
* Convenience macro. * Convenience macro.
*/ */
@@ -609,13 +610,15 @@ extern DECLSPEC void SDLCALL SDL_GameControllerUpdate(void);
/** /**
* The list of axes available from a controller * The list of axes available from a controller
* *
* Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX, * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
* and are centered within ~8000 of zero, though advanced UI will allow users to set * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
* or autodetect the dead zone, which varies between controllers. * advanced UI will allow users to set or autodetect the dead zone, which
* varies between controllers.
* *
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
* (fully pressed) when reported by SDL_GameControllerGetAxis(). Note that this is not the * pressed) when reported by SDL_GameControllerGetAxis(). Note that this is
* same range that will be reported by the lower-level SDL_GetJoystickAxis(). * not the same range that will be reported by the lower-level
* SDL_GetJoystickAxis().
*/ */
typedef enum SDL_GameControllerAxis typedef enum SDL_GameControllerAxis
{ {

32
include/SDL_guid.h
View File

@@ -22,7 +22,7 @@
/** /**
* \file SDL_guid.h * \file SDL_guid.h
* *
* Include file for handling ::SDL_GUID values. * Include file for handling SDL_GUID values.
*/ */
#ifndef SDL_guid_h_ #ifndef SDL_guid_h_
@@ -38,19 +38,19 @@ extern "C" {
#endif #endif
/** /**
* An SDL_GUID is a 128-bit identifier for an input device that * An SDL_GUID is a 128-bit identifier for an input device that identifies
* identifies that device across runs of SDL programs on the same * that device across runs of SDL programs on the same platform.
* 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.
* *
* GUIDs are as precise as possible but are not guaranteed to * If the device is detached and then re-attached to a different port, or if
* distinguish physically distinct but equivalent devices. For * the base system is rebooted, the device should still report the same GUID.
* 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 * GUIDs are as precise as possible but are not guaranteed to distinguish
* different GUIDs on different operating systems). * 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 { typedef struct SDL_GUID {
Uint8 data[16]; Uint8 data[16];
@@ -59,11 +59,11 @@ typedef struct SDL_GUID {
/* Function prototypes */ /* Function prototypes */
/** /**
* Get an ASCII string representation for a given ::SDL_GUID. * Get an ASCII string representation for a given SDL_GUID.
* *
* You should supply at least 33 bytes for pszGUID. * You should supply at least 33 bytes for pszGUID.
* *
* \param guid the ::SDL_GUID you wish to convert to string * \param guid the SDL_GUID you wish to convert to string
* \param pszGUID buffer in which to write the ASCII string * \param pszGUID buffer in which to write the ASCII string
* \param cbGUID the size of pszGUID * \param cbGUID the size of pszGUID
* *
@@ -74,14 +74,14 @@ typedef struct SDL_GUID {
extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID); extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID);
/** /**
* Convert a GUID string into a ::SDL_GUID structure. * Convert a GUID string into a SDL_GUID structure.
* *
* Performs no error checking. If this function is given a string containing * Performs no error checking. If this function is given a string containing
* an invalid GUID, the function will silently succeed, but the GUID generated * an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful. * will not be useful.
* *
* \param pchGUID string containing an ASCII representation of a GUID * \param pchGUID string containing an ASCII representation of a GUID
* \returns a ::SDL_GUID structure. * \returns a SDL_GUID structure.
* *
* \since This function is available since SDL 2.24.0. * \since This function is available since SDL 2.24.0.
* *

380
include/SDL_haptic.h
View File

@@ -26,18 +26,19 @@
* devices. * devices.
* *
* The basic usage is as follows: * The basic usage is as follows:
* - Initialize the subsystem (::SDL_INIT_HAPTIC). * - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device. * - Open a haptic device.
* - SDL_HapticOpen() to open from index. * - SDL_HapticOpen() to open from index.
* - SDL_HapticOpenFromJoystick() to open from an existing joystick. * - SDL_HapticOpenFromJoystick() to open from an existing joystick.
* - Create an effect (::SDL_HapticEffect). * - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_HapticNewEffect(). * - Upload the effect with SDL_HapticNewEffect().
* - Run the effect with SDL_HapticRunEffect(). * - Run the effect with SDL_HapticRunEffect().
* - (optional) Free the effect with SDL_HapticDestroyEffect(). * - (optional) Free the effect with SDL_HapticDestroyEffect().
* - Close the haptic device with SDL_HapticClose(). * - Close the haptic device with SDL_HapticClose().
* *
* \par Simple rumble example: * \par Simple rumble example:
* \code *
* ```c
* SDL_Haptic *haptic; * SDL_Haptic *haptic;
* *
* // Open the device * // Open the device
@@ -56,10 +57,11 @@
* *
* // Clean up * // Clean up
* SDL_HapticClose( haptic ); * SDL_HapticClose( haptic );
* \endcode * ```
* *
* \par Complete example: * Complete example:
* \code *
* ```c
* int test_haptic( SDL_Joystick * joystick ) { * int test_haptic( SDL_Joystick * joystick ) {
* SDL_Haptic *haptic; * SDL_Haptic *haptic;
* SDL_HapticEffect effect; * SDL_HapticEffect effect;
@@ -101,7 +103,7 @@
* *
* return 0; // Success * return 0; // Success
* } * }
* \endcode * ```
*/ */
#ifndef SDL_haptic_h_ #ifndef SDL_haptic_h_
@@ -154,7 +156,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* @{ */ /* @{ */
/** /**
* \brief Constant effect supported. * Constant effect supported.
* *
* Constant haptic effect. * Constant haptic effect.
* *
@@ -163,7 +165,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_CONSTANT (1u<<0) #define SDL_HAPTIC_CONSTANT (1u<<0)
/** /**
* \brief Sine wave effect supported. * Sine wave effect supported.
* *
* Periodic haptic effect that simulates sine waves. * Periodic haptic effect that simulates sine waves.
* *
@@ -172,13 +174,11 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SINE (1u<<1) #define SDL_HAPTIC_SINE (1u<<1)
/** /**
* \brief Left/Right effect supported. * Left/Right effect supported.
* *
* Haptic effect for direct control over high/low frequency motors. * Haptic effect for direct control over high/low frequency motors.
* *
* \sa SDL_HapticLeftRight * \sa SDL_HapticLeftRight
* \warning this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry,
* we ran out of bits, and this is important for XInput devices.
*/ */
#define SDL_HAPTIC_LEFTRIGHT (1u<<2) #define SDL_HAPTIC_LEFTRIGHT (1u<<2)
@@ -186,7 +186,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* #define SDL_HAPTIC_SQUARE (1<<2) */ /* #define SDL_HAPTIC_SQUARE (1<<2) */
/** /**
* \brief Triangle wave effect supported. * Triangle wave effect supported.
* *
* Periodic haptic effect that simulates triangular waves. * Periodic haptic effect that simulates triangular waves.
* *
@@ -195,7 +195,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_TRIANGLE (1u<<3) #define SDL_HAPTIC_TRIANGLE (1u<<3)
/** /**
* \brief Sawtoothup wave effect supported. * Sawtoothup wave effect supported.
* *
* Periodic haptic effect that simulates saw tooth up waves. * Periodic haptic effect that simulates saw tooth up waves.
* *
@@ -204,7 +204,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SAWTOOTHUP (1u<<4) #define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
/** /**
* \brief Sawtoothdown wave effect supported. * Sawtoothdown wave effect supported.
* *
* Periodic haptic effect that simulates saw tooth down waves. * Periodic haptic effect that simulates saw tooth down waves.
* *
@@ -213,7 +213,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5) #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/** /**
* \brief Ramp effect supported. * Ramp effect supported.
* *
* Ramp haptic effect. * Ramp haptic effect.
* *
@@ -222,7 +222,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_RAMP (1u<<6) #define SDL_HAPTIC_RAMP (1u<<6)
/** /**
* \brief Spring effect supported - uses axes position. * Spring effect supported - uses axes position.
* *
* Condition haptic effect that simulates a spring. Effect is based on the * Condition haptic effect that simulates a spring. Effect is based on the
* axes position. * axes position.
@@ -232,7 +232,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SPRING (1u<<7) #define SDL_HAPTIC_SPRING (1u<<7)
/** /**
* \brief Damper effect supported - uses axes velocity. * Damper effect supported - uses axes velocity.
* *
* Condition haptic effect that simulates dampening. Effect is based on the * Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity. * axes velocity.
@@ -242,7 +242,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_DAMPER (1u<<8) #define SDL_HAPTIC_DAMPER (1u<<8)
/** /**
* \brief Inertia effect supported - uses axes acceleration. * Inertia effect supported - uses axes acceleration.
* *
* Condition haptic effect that simulates inertia. Effect is based on the axes * Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration. * acceleration.
@@ -252,7 +252,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_INERTIA (1u<<9) #define SDL_HAPTIC_INERTIA (1u<<9)
/** /**
* \brief Friction effect supported - uses axes movement. * Friction effect supported - uses axes movement.
* *
* Condition haptic effect that simulates friction. Effect is based on the * Condition haptic effect that simulates friction. Effect is based on the
* axes movement. * axes movement.
@@ -262,7 +262,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_FRICTION (1u<<10) #define SDL_HAPTIC_FRICTION (1u<<10)
/** /**
* \brief Custom effect is supported. * Custom effect is supported.
* *
* User defined custom haptic effect. * User defined custom haptic effect.
*/ */
@@ -273,7 +273,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* These last few are features the device has, not effects */ /* These last few are features the device has, not effects */
/** /**
* \brief Device can set global gain. * Device can set global gain.
* *
* Device supports setting the global gain. * Device supports setting the global gain.
* *
@@ -282,7 +282,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_GAIN (1u<<12) #define SDL_HAPTIC_GAIN (1u<<12)
/** /**
* \brief Device can set autocenter. * Device can set autocenter.
* *
* Device supports setting autocenter. * Device supports setting autocenter.
* *
@@ -291,7 +291,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_AUTOCENTER (1u<<13) #define SDL_HAPTIC_AUTOCENTER (1u<<13)
/** /**
* \brief Device can be queried for effect status. * Device can be queried for effect status.
* *
* Device supports querying effect status. * Device supports querying effect status.
* *
@@ -300,7 +300,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_STATUS (1u<<14) #define SDL_HAPTIC_STATUS (1u<<14)
/** /**
* \brief Device can be paused. * Device can be paused.
* *
* Devices supports being paused. * Devices supports being paused.
* *
@@ -316,30 +316,32 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* @{ */ /* @{ */
/** /**
* \brief Uses polar coordinates for the direction. * Uses polar coordinates for the direction.
* *
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_POLAR 0 #define SDL_HAPTIC_POLAR 0
/** /**
* \brief Uses cartesian coordinates for the direction. * Uses cartesian coordinates for the direction.
* *
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_CARTESIAN 1 #define SDL_HAPTIC_CARTESIAN 1
/** /**
* \brief Uses spherical coordinates for the direction. * Uses spherical coordinates for the direction.
* *
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_SPHERICAL 2 #define SDL_HAPTIC_SPHERICAL 2
/** /**
* \brief Use this value to play an effect on the steering wheel axis. This * Use this value to play an effect on the steering wheel axis.
* 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 * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_STEERING_AXIS 3 #define SDL_HAPTIC_STEERING_AXIS 3
@@ -353,7 +355,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
*/ */
/** /**
* \brief Used to play a device an infinite number of times. * Used to play a device an infinite number of times.
* *
* \sa SDL_HapticRunEffect * \sa SDL_HapticRunEffect
*/ */
@@ -361,77 +363,82 @@ typedef struct _SDL_Haptic SDL_Haptic;
/** /**
* \brief Structure that represents a haptic direction. * Structure that represents a haptic direction.
* *
* This is the direction where the force comes from, * This is the direction where the force comes from, instead of the direction
* instead of the direction in which the force is exerted. * in which the force is exerted.
* *
* Directions can be specified by: * Directions can be specified by:
* - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
* - ::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 * - SDL_HAPTIC_POLAR : Specified by polar coordinates.
* of the device. North is considered to be away from the user. * - 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.
* *
* The following diagram represents the cardinal directions: * The following diagram represents the cardinal directions:
* \verbatim
.--.
|__| .-------.
|=.| |.-----.|
|--| || ||
| | |'-----'|
|__|~')_____('
[ COMPUTER ]
North (0,-1)
^
|
|
(-1,0) West <----[ HAPTIC ]----> East (1,0)
|
|
v
South (0,1)
[ USER ]
\|||/
(o o)
---ooO-(_)-Ooo---
\endverbatim
* *
* 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 \c dir parameter. The cardinal directions would be: * |__| .-------.
* |=.| |.-----.|
* |--| || ||
* | | |'-----'|
* |__|~')_____('
* [ COMPUTER ]
*
*
* North (0,-1)
* ^
* |
* |
* (-1,0) West <----[ HAPTIC ]----> East (1,0)
* |
* |
* v
* South (0,1)
*
*
* [ USER ]
* \|||/
* (o o)
* ---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:
*
* - North: 0 (0 degrees) * - North: 0 (0 degrees)
* - East: 9000 (90 degrees) * - East: 9000 (90 degrees)
* - South: 18000 (180 degrees) * - South: 18000 (180 degrees)
* - West: 27000 (270 degrees) * - West: 27000 (270 degrees)
* *
* If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X
* (X axis, Y axis and Z axis (with 3 axes)). ::SDL_HAPTIC_CARTESIAN uses * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first
* the first three \c dir parameters. The cardinal directions would be: * three `dir` parameters. The cardinal directions would be:
*
* - North: 0,-1, 0 * - North: 0,-1, 0
* - East: 1, 0, 0 * - East: 1, 0, 0
* - South: 0, 1, 0 * - South: 0, 1, 0
* - West: -1, 0, 0 * - West: -1, 0, 0
* *
* The Z axis represents the height of the effect if supported, otherwise * The Z axis represents the height of the effect if supported, otherwise it's
* it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can
* can use any multiple you want, only the direction matters. * 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 \c dir parameters are used. The \c dir parameters are as
* follows (all values are in hundredths of degrees):
* - Degrees from (1, 0) rotated towards (0, 1). * - Degrees from (1, 0) rotated towards (0, 1).
* - Degrees towards (0, 0, 1) (device needs at least 3 axes). * - Degrees towards (0, 0, 1) (device needs at least 3 axes).
* *
*
* Example of force coming from the south with all encodings (force coming * Example of force coming from the south with all encodings (force coming
* from the south means the user will have to pull the stick to counteract): * from the south means the user will have to pull the stick to counteract):
* \code *
* ```c
* SDL_HapticDirection direction; * SDL_HapticDirection direction;
* *
* // Cartesian directions * // Cartesian directions
@@ -447,7 +454,7 @@ typedef struct _SDL_Haptic SDL_Haptic;
* // Spherical coordinates * // Spherical coordinates
* direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
* direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
* \endcode * ```
* *
* \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN * \sa SDL_HAPTIC_CARTESIAN
@@ -464,12 +471,12 @@ typedef struct SDL_HapticDirection
/** /**
* \brief A structure containing a template for a Constant effect. * A structure containing a template for a Constant effect.
* *
* This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect. * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
* *
* A constant effect applies a constant force in the specified direction * A constant effect applies a constant force in the specified direction to
* to the joystick. * the joystick.
* *
* \sa SDL_HAPTIC_CONSTANT * \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
@@ -477,7 +484,7 @@ typedef struct SDL_HapticDirection
typedef struct SDL_HapticConstant typedef struct SDL_HapticConstant
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_CONSTANT */ Uint16 type; /**< SDL_HAPTIC_CONSTANT */
SDL_HapticDirection direction; /**< Direction of the effect. */ SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */ /* Replay */
@@ -499,21 +506,23 @@ typedef struct SDL_HapticConstant
} SDL_HapticConstant; } SDL_HapticConstant;
/** /**
* \brief A structure containing a template for a Periodic effect. * A structure containing a template for a Periodic effect.
* *
* The struct handles the following effects: * The struct handles the following effects:
* - ::SDL_HAPTIC_SINE
* - ::SDL_HAPTIC_LEFTRIGHT
* - ::SDL_HAPTIC_TRIANGLE
* - ::SDL_HAPTIC_SAWTOOTHUP
* - ::SDL_HAPTIC_SAWTOOTHDOWN
* *
* A periodic effect consists in a wave-shaped effect that repeats itself * - SDL_HAPTIC_SINE
* over time. The type determines the shape of the wave and the parameters * - SDL_HAPTIC_SQUARE
* - SDL_HAPTIC_TRIANGLE
* - 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
* determine the dimensions of the wave. * determine the dimensions of the wave.
* *
* Phase is given by hundredth of a degree meaning that giving the phase a value * Phase is given by hundredth of a degree meaning that giving the phase a
* of 9000 will displace it 25% of its period. Here are sample values: * value of 9000 will displace it 25% of its period. Here are sample values:
*
* - 0: No phase displacement. * - 0: No phase displacement.
* - 9000: Displaced 25% of its period. * - 9000: Displaced 25% of its period.
* - 18000: Displaced 50% of its period. * - 18000: Displaced 50% of its period.
@@ -521,32 +530,33 @@ typedef struct SDL_HapticConstant
* - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
* *
* Examples: * Examples:
* \verbatim *
SDL_HAPTIC_SINE * ```
__ __ __ __ * SDL_HAPTIC_SINE
/ \ / \ / \ / * __ __ __ __
/ \__/ \__/ \__/ * / \ / \ / \ /
* / \__/ \__/ \__/
SDL_HAPTIC_SQUARE *
__ __ __ __ __ * SDL_HAPTIC_SQUARE
| | | | | | | | | | * __ __ __ __ __
| |__| |__| |__| |__| | * | | | | | | | | | |
* | |__| |__| |__| |__| |
SDL_HAPTIC_TRIANGLE *
/\ /\ /\ /\ /\ * SDL_HAPTIC_TRIANGLE
/ \ / \ / \ / \ / * /\ /\ /\ /\ /\
/ \/ \/ \/ \/ * / \ / \ / \ / \ /
* / \/ \/ \/ \/
SDL_HAPTIC_SAWTOOTHUP *
/| /| /| /| /| /| /| * SDL_HAPTIC_SAWTOOTHUP
/ | / | / | / | / | / | / | * /| /| /| /| /| /| /|
/ |/ |/ |/ |/ |/ |/ | * / | / | / | / | / | / | / |
* / |/ |/ |/ |/ |/ |/ |
SDL_HAPTIC_SAWTOOTHDOWN *
\ |\ |\ |\ |\ |\ |\ | * SDL_HAPTIC_SAWTOOTHDOWN
\ | \ | \ | \ | \ | \ | \ | * \ |\ |\ |\ |\ |\ |\ |
\| \| \| \| \| \| \| * \ | \ | \ | \ | \ | \ | \ |
\endverbatim * \| \| \| \| \| \| \|
* ```
* *
* \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HAPTIC_LEFTRIGHT
@@ -558,9 +568,9 @@ typedef struct SDL_HapticConstant
typedef struct SDL_HapticPeriodic typedef struct SDL_HapticPeriodic
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_LEFTRIGHT, Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT,
::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
::SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HAPTIC_SAWTOOTHDOWN */
SDL_HapticDirection direction; /**< Direction of the effect. */ SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */ /* Replay */
@@ -585,21 +595,22 @@ typedef struct SDL_HapticPeriodic
} SDL_HapticPeriodic; } SDL_HapticPeriodic;
/** /**
* \brief A structure containing a template for a Condition effect. * A structure containing a template for a Condition effect.
* *
* The struct handles the following effects: * The struct handles the following effects:
* - ::SDL_HAPTIC_SPRING: Effect based on axes position. *
* - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity. * - SDL_HAPTIC_SPRING: Effect based on axes position.
* - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration. * - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - ::SDL_HAPTIC_FRICTION: Effect based on axes movement. * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - SDL_HAPTIC_FRICTION: Effect based on axes movement.
* *
* Direction is handled by condition internals instead of a direction member. * Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first * 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 X axis, the second refers to the Y axis and the third refers
* refers to the Z axis. The right terms refer to the positive side of the * to the Z axis. The right terms refer to the positive side of the axis and
* axis and the left terms refer to the negative side of the axis. Please * the left terms refer to the negative side of the axis. Please refer to the
* refer to the ::SDL_HapticDirection diagram for which side is positive and * SDL_HapticDirection diagram for which side is positive and which is
* which is negative. * negative.
* *
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING * \sa SDL_HAPTIC_SPRING
@@ -611,8 +622,8 @@ typedef struct SDL_HapticPeriodic
typedef struct SDL_HapticCondition typedef struct SDL_HapticCondition
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER, Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */ SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */
/* Replay */ /* Replay */
@@ -633,14 +644,14 @@ typedef struct SDL_HapticCondition
} SDL_HapticCondition; } SDL_HapticCondition;
/** /**
* \brief A structure containing a template for a Ramp effect. * A structure containing a template for a Ramp effect.
* *
* This struct is exclusively for the ::SDL_HAPTIC_RAMP effect. * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
* *
* The ramp effect starts at start strength and ends at end strength. * The ramp effect starts at start strength and ends at end strength. It
* It augments in linear fashion. If you use attack and fade with a ramp * augments in linear fashion. If you use attack and fade with a ramp the
* the effects get added to the ramp effect making the effect become * effects get added to the ramp effect making the effect become quadratic
* quadratic instead of linear. * instead of linear.
* *
* \sa SDL_HAPTIC_RAMP * \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
@@ -648,7 +659,7 @@ typedef struct SDL_HapticCondition
typedef struct SDL_HapticRamp typedef struct SDL_HapticRamp
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_RAMP */ Uint16 type; /**< SDL_HAPTIC_RAMP */
SDL_HapticDirection direction; /**< Direction of the effect. */ SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */ /* Replay */
@@ -671,9 +682,9 @@ typedef struct SDL_HapticRamp
} SDL_HapticRamp; } SDL_HapticRamp;
/** /**
* \brief A structure containing a template for a Left/Right effect. * A structure containing a template for a Left/Right effect.
* *
* This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect. * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect.
* *
* The Left/Right effect is used to explicitly control the large and small * The Left/Right effect is used to explicitly control the large and small
* motors, commonly found in modern game controllers. The small (right) motor * motors, commonly found in modern game controllers. The small (right) motor
@@ -685,7 +696,7 @@ typedef struct SDL_HapticRamp
typedef struct SDL_HapticLeftRight typedef struct SDL_HapticLeftRight
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */ Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */
/* Replay */ /* Replay */
Uint32 length; /**< Duration of the effect in milliseconds. */ Uint32 length; /**< Duration of the effect in milliseconds. */
@@ -696,13 +707,13 @@ typedef struct SDL_HapticLeftRight
} SDL_HapticLeftRight; } SDL_HapticLeftRight;
/** /**
* \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect. * A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
* *
* This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect. * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
* *
* A custom force feedback effect is much like a periodic effect, where the * 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 * application can define its exact shape. You will have to allocate the data
* data yourself. Data should consist of channels * samples Uint16 samples. * yourself. Data should consist of channels * samples Uint16 samples.
* *
* If channels is one, the effect is rotated using the defined direction. * If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes. * Otherwise it uses the samples in data for the different axes.
@@ -713,7 +724,7 @@ typedef struct SDL_HapticLeftRight
typedef struct SDL_HapticCustom typedef struct SDL_HapticCustom
{ {
/* Header */ /* Header */
Uint16 type; /**< ::SDL_HAPTIC_CUSTOM */ Uint16 type; /**< SDL_HAPTIC_CUSTOM */
SDL_HapticDirection direction; /**< Direction of the effect. */ SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */ /* Replay */
@@ -738,27 +749,28 @@ typedef struct SDL_HapticCustom
} SDL_HapticCustom; } SDL_HapticCustom;
/** /**
* \brief The generic template for any haptic effect. * The generic template for any haptic effect.
* *
* All values max at 32767 (0x7FFF). Signed values also can be negative. * All values max at 32767 (0x7FFF). Signed values also can be negative. Time
* Time values unless specified otherwise are in milliseconds. * values unless specified otherwise are in milliseconds.
* *
* You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
* value. Neither delay, interval, attack_length nor fade_length support * Neither delay, interval, attack_length nor fade_length support
* ::SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. * 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 * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
* ::SDL_HAPTIC_INFINITY. * SDL_HAPTIC_INFINITY.
* *
* Button triggers may not be supported on all devices, it is advised to not * 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 * use them if possible. Buttons start at index 1 instead of index 0 like the
* the joystick. * joystick.
* *
* If both attack_length and fade_level are 0, the envelope is not used, * If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used. * otherwise both values are used.
* *
* Common parts: * Common parts:
* \code *
* ```c
* // Replay - All effects have this * // Replay - All effects have this
* Uint32 length; // Duration of effect (ms). * Uint32 length; // Duration of effect (ms).
* Uint16 delay; // Delay before starting effect. * Uint16 delay; // Delay before starting effect.
@@ -772,29 +784,29 @@ typedef struct SDL_HapticCustom
* Uint16 attack_level; // Level at the start of the attack. * Uint16 attack_level; // Level at the start of the attack.
* Uint16 fade_length; // Duration of the fade out (ms). * Uint16 fade_length; // Duration of the fade out (ms).
* Uint16 fade_level; // Level at the end of the fade. * Uint16 fade_level; // Level at the end of the fade.
* \endcode * ```
*
* *
* Here we have an example of a constant effect evolution in time: * Here we have an example of a constant effect evolution in time:
* \verbatim *
Strength * ```
^ * Strength
| * ^
| effect level --> _________________ * |
| / \ * | effect level --> _________________
| / \ * | / \
| / \ * | / \
| / \ * | / \
| attack_level --> | \ * | / \
| | | <--- fade_level * | attack_level --> | \
| * | | | <--- fade_level
+--------------------------------------------------> Time * |
[--] [---] * +--------------------------------------------------> Time
attack_length fade_length * [--] [---]
* attack_length fade_length
[------------------][-----------------------] *
delay length * [------------------][-----------------------]
\endverbatim * delay length
* ```
* *
* Note either the attack_level or the fade_level may be above the actual * Note either the attack_level or the fade_level may be above the actual
* effect level. * effect level.

5
include/SDL_hidapi.h
View File

@@ -71,14 +71,15 @@ extern "C" {
#endif #endif
/** /**
* \brief A handle representing an open HID device * A handle representing an open HID device
*/ */
struct SDL_hid_device_; struct SDL_hid_device_;
typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
/** hidapi info structure */ /** hidapi info structure */
/** /**
* \brief Information about a connected HID device * Information about a connected HID device
*/ */
typedef struct SDL_hid_device_info typedef struct SDL_hid_device_info
{ {

2244
include/SDL_hints.h
View File

File diff suppressed because it is too large Load Diff

20
include/SDL_joystick.h
View File

@@ -56,7 +56,7 @@ extern "C" {
* \file SDL_joystick.h * \file SDL_joystick.h
* *
* In order to use these functions, SDL_Init() must have been called * In order to use these functions, SDL_Init() must have been called
* with the ::SDL_INIT_JOYSTICK flag. This causes SDL to scan the system * with the SDL_INIT_JOYSTICK flag. This causes SDL to scan the system
* for joysticks, and load appropriate drivers. * for joysticks, and load appropriate drivers.
* *
* If you would like to receive joystick updates while the application * If you would like to receive joystick updates while the application
@@ -77,11 +77,13 @@ typedef struct _SDL_Joystick SDL_Joystick;
typedef SDL_GUID SDL_JoystickGUID; typedef SDL_GUID SDL_JoystickGUID;
/** /**
* This is a unique ID for a joystick for the time it is connected to the system, * This is a unique ID for a joystick for the time it is connected to the
* and is never reused for the lifetime of the application. If the joystick is * system, and is never reused for the lifetime of the application.
* disconnected and reconnected, it will get a new ID.
* *
* The ID value starts at 0 and increments from there. The value -1 is an invalid ID. * If the joystick is disconnected and reconnected, it will get a new ID.
*
* The ID value starts at 0 and increments from there. The value -1 is an
* invalid ID.
*/ */
typedef Sint32 SDL_JoystickID; typedef Sint32 SDL_JoystickID;
@@ -358,8 +360,10 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
/** /**
* The structure that defines an extended virtual joystick description * 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_JoystickAttachVirtualEx() * The caller must zero the structure and then initialize the version with
* All other elements of this structure are optional and can be left 0. * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to
* SDL_JoystickAttachVirtualEx() All other elements of this structure are
* optional and can be left 0.
* *
* \sa SDL_JoystickAttachVirtualEx * \sa SDL_JoystickAttachVirtualEx
*/ */
@@ -390,7 +394,7 @@ typedef struct SDL_VirtualJoystickDesc
} SDL_VirtualJoystickDesc; } SDL_VirtualJoystickDesc;
/** /**
* \brief The current version of the SDL_VirtualJoystickDesc structure * The current version of the SDL_VirtualJoystickDesc structure
*/ */
#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1

9
include/SDL_keyboard.h
View File

@@ -40,14 +40,15 @@ extern "C" {
#endif #endif
/** /**
* \brief The SDL keysym structure, used in key events. * The SDL keysym structure, used in key events.
* *
* \note If you are looking for translated character input, see the ::SDL_TEXTINPUT event. * If you are looking for translated character input, see the SDL_TEXTINPUT
* event.
*/ */
typedef struct SDL_Keysym typedef struct SDL_Keysym
{ {
SDL_Scancode scancode; /**< SDL physical key code - see ::SDL_Scancode for details */ SDL_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */
SDL_Keycode sym; /**< SDL virtual key code - see ::SDL_Keycode for details */ SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */
Uint16 mod; /**< current key modifiers */ Uint16 mod; /**< current key modifiers */
Uint32 unused; Uint32 unused;
} SDL_Keysym; } SDL_Keysym;

12
include/SDL_keycode.h
View File

@@ -32,15 +32,15 @@
#include "SDL_scancode.h" #include "SDL_scancode.h"
/** /**
* \brief The SDL virtual key representation. * The SDL virtual key representation.
* *
* Values of this type are used to represent keyboard keys using the current * Values of this type are used to represent keyboard keys using the current
* layout of the keyboard. These values include Unicode values representing * layout of the keyboard. These values include Unicode values representing
* the unmodified character that would be generated by pressing the key, or * the unmodified character that would be generated by pressing the key, or an
* an SDLK_* constant for those keys that do not generate characters. * SDLK_* constant for those keys that do not generate characters.
* *
* A special exception is the number keys at the top of the keyboard which * A special exception is the number keys at the top of the keyboard which map
* map to SDLK_0...SDLK_9 on AZERTY layouts. * to SDLK_0...SDLK_9 on AZERTY layouts.
*/ */
typedef Sint32 SDL_Keycode; typedef Sint32 SDL_Keycode;
@@ -327,7 +327,7 @@ typedef enum SDL_KeyCode
} SDL_KeyCode; } SDL_KeyCode;
/** /**
* \brief Enumeration of valid key mods (possibly OR'd together). * Enumeration of valid key mods (possibly OR'd together).
*/ */
typedef enum SDL_Keymod typedef enum SDL_Keymod
{ {

13
include/SDL_log.h
View File

@@ -47,19 +47,18 @@ extern "C" {
/** /**
* \brief The maximum size of a log message prior to SDL 2.0.24 * The maximum size of a log message prior to SDL 2.0.24
* *
* As of 2.0.24 there is no limit to the length of SDL log messages. * As of 2.0.24 there is no limit to the length of SDL log messages.
*/ */
#define SDL_MAX_LOG_MESSAGE 4096 #define SDL_MAX_LOG_MESSAGE 4096
/** /**
* \brief The predefined log categories * The predefined log categories
* *
* By default the application category is enabled at the INFO level, * By default the application category is enabled at the INFO level, the
* the assert category is enabled at the WARN level, test is enabled * assert category is enabled at the WARN level, test is enabled at the
* at the VERBOSE level and all other categories are enabled at the * VERBOSE level and all other categories are enabled at the ERROR level.
* ERROR level.
*/ */
typedef enum SDL_LogCategory typedef enum SDL_LogCategory
{ {
@@ -97,7 +96,7 @@ typedef enum SDL_LogCategory
} SDL_LogCategory; } SDL_LogCategory;
/** /**
* \brief The predefined log priorities * The predefined log priorities
*/ */
typedef enum SDL_LogPriority typedef enum SDL_LogPriority
{ {

4
include/SDL_main.h
View File

@@ -129,14 +129,14 @@
* *
* The application's main() function must be called with C linkage, * The application's main() function must be called with C linkage,
* and should be declared like this: * and should be declared like this:
* \code * ```c
* #ifdef __cplusplus * #ifdef __cplusplus
* extern "C" * extern "C"
* #endif * #endif
* int main(int argc, char *argv[]) * int main(int argc, char *argv[])
* { * {
* } * }
* \endcode * ```
*/ */
#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE)

10
include/SDL_messagebox.h
View File

@@ -32,7 +32,9 @@ extern "C" {
#endif #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 typedef enum SDL_MessageBoxFlags
{ {
@@ -57,7 +59,7 @@ typedef enum SDL_MessageBoxButtonFlags
*/ */
typedef struct SDL_MessageBoxButtonData typedef struct SDL_MessageBoxButtonData
{ {
Uint32 flags; /**< ::SDL_MessageBoxButtonFlags */ Uint32 flags; /**< SDL_MessageBoxButtonFlags */
int buttonid; /**< User defined button id (value returned via SDL_ShowMessageBox) */ int buttonid; /**< User defined button id (value returned via SDL_ShowMessageBox) */
const char * text; /**< The UTF-8 button text */ const char * text; /**< The UTF-8 button text */
} SDL_MessageBoxButtonData; } SDL_MessageBoxButtonData;
@@ -93,7 +95,7 @@ typedef struct SDL_MessageBoxColorScheme
*/ */
typedef struct SDL_MessageBoxData typedef struct SDL_MessageBoxData
{ {
Uint32 flags; /**< ::SDL_MessageBoxFlags */ Uint32 flags; /**< SDL_MessageBoxFlags */
SDL_Window *window; /**< Parent window, can be NULL */ SDL_Window *window; /**< Parent window, can be NULL */
const char *title; /**< UTF-8 title */ const char *title; /**< UTF-8 title */
const char *message; /**< UTF-8 message text */ const char *message; /**< UTF-8 message text */
@@ -101,7 +103,7 @@ typedef struct SDL_MessageBoxData
int numbuttons; int numbuttons;
const SDL_MessageBoxButtonData *buttons; const SDL_MessageBoxButtonData *buttons;
const SDL_MessageBoxColorScheme *colorScheme; /**< ::SDL_MessageBoxColorScheme, can be NULL to use system settings */ const SDL_MessageBoxColorScheme *colorScheme; /**< SDL_MessageBoxColorScheme, can be NULL to use system settings */
} SDL_MessageBoxData; } SDL_MessageBoxData;
/** /**

4
include/SDL_metal.h
View File

@@ -37,9 +37,9 @@ extern "C" {
#endif #endif
/** /**
* \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
* *
* \note This can be cast directly to an NSView or UIView. * This can be cast directly to an NSView or UIView.
*/ */
typedef void *SDL_MetalView; typedef void *SDL_MetalView;

4
include/SDL_mouse.h
View File

@@ -41,7 +41,7 @@ extern "C" {
typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
/** /**
* \brief Cursor types for SDL_CreateSystemCursor(). * Cursor types for SDL_CreateSystemCursor().
*/ */
typedef enum SDL_SystemCursor typedef enum SDL_SystemCursor
{ {
@@ -61,7 +61,7 @@ typedef enum SDL_SystemCursor
} SDL_SystemCursor; } SDL_SystemCursor;
/** /**
* \brief Scroll direction types for the Scroll event * Scroll direction types for the Scroll event
*/ */
typedef enum SDL_MouseWheelDirection typedef enum SDL_MouseWheelDirection
{ {

4
include/SDL_mutex.h
View File

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

32
include/SDL_pixels.h
View File

@@ -320,9 +320,10 @@ typedef enum
} SDL_PixelFormatEnum; } SDL_PixelFormatEnum;
/** /**
* The bits of this structure can be directly reinterpreted as an integer-packed * The bits of this structure can be directly reinterpreted as an
* color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format
* on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and
* SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
*/ */
typedef struct SDL_Color typedef struct SDL_Color
{ {
@@ -342,7 +343,30 @@ typedef struct SDL_Palette
} SDL_Palette; } SDL_Palette;
/** /**
* \note Everything in the pixel format structure is read-only. * A structure that contains pixel format information.
*
* Everything in the pixel format structure is read-only.
*
* A pixel format has either a palette or masks. If a palette is used `Rmask`,
* `Gmask`, `Bmask`, and `Amask` will be 0.
*
* An SDL_PixelFormat describes the format of the pixel data stored at the
* `pixels` field of an SDL_Surface. Every surface stores an SDL_PixelFormat
* in the `format` field.
*
* If you wish to do pixel level modifications on a surface, then
* understanding how SDL stores its color information is essential.
*
* For information on modern pixel color spaces, see the following Wikipedia
* article: http://en.wikipedia.org/wiki/RGBA_color_space
*
* \sa SDL_ConvertSurface
* \sa SDL_GetRGB
* \sa SDL_GetRGBA
* \sa SDL_MapRGB
* \sa SDL_MapRGBA
* \sa SDL_AllocFormat
* \sa SDL_FreeFormat
*/ */
typedef struct SDL_PixelFormat typedef struct SDL_PixelFormat
{ {

6
include/SDL_quit.h
View File

@@ -34,7 +34,7 @@
/** /**
* \file SDL_quit.h * \file SDL_quit.h
* *
* An ::SDL_QUIT event is generated when the user tries to close the application * An SDL_QUIT event is generated when the user tries to close the application
* window. If it is ignored or filtered out, the window will remain open. * window. If it is ignored or filtered out, the window will remain open.
* If it is not ignored or filtered, it is queued normally and the window * If it is not ignored or filtered, it is queued normally and the window
* is allowed to close. When the window is closed, screen updates will * is allowed to close. When the window is closed, screen updates will
@@ -42,8 +42,8 @@
* *
* SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) * SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
* and SIGTERM (system termination request), if handlers do not already * and SIGTERM (system termination request), if handlers do not already
* exist, that generate ::SDL_QUIT events as well. There is no way * exist, that generate SDL_QUIT events as well. There is no way
* to determine the cause of an ::SDL_QUIT event, but setting a signal * to determine the cause of an SDL_QUIT event, but setting a signal
* handler in your application will override the default generation of * handler in your application will override the default generation of
* quit events for that signal. * quit events for that signal.
* *

2
include/SDL_render.h
View File

@@ -78,7 +78,7 @@ typedef enum SDL_RendererFlags
typedef struct SDL_RendererInfo typedef struct SDL_RendererInfo
{ {
const char *name; /**< The name of the renderer */ const char *name; /**< The name of the renderer */
Uint32 flags; /**< Supported ::SDL_RendererFlags */ Uint32 flags; /**< Supported SDL_RendererFlags */
Uint32 num_texture_formats; /**< The number of available texture formats */ Uint32 num_texture_formats; /**< The number of available texture formats */
Uint32 texture_formats[16]; /**< The available texture formats */ Uint32 texture_formats[16]; /**< The available texture formats */
int max_texture_width; /**< The maximum texture width */ int max_texture_width; /**< The maximum texture width */

10
include/SDL_rwops.h
View File

@@ -57,7 +57,7 @@ typedef struct SDL_RWops
Sint64 (SDLCALL * size) (struct SDL_RWops * context); Sint64 (SDLCALL * size) (struct SDL_RWops * context);
/** /**
* Seek to \c offset relative to \c whence, one of stdio's whence values: * Seek to `offset` relative to `whence`, one of stdio's whence values:
* RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END * RW_SEEK_SET, RW_SEEK_CUR, RW_SEEK_END
* *
* \return the final offset in the data stream, or -1 on error. * \return the final offset in the data stream, or -1 on error.
@@ -66,8 +66,8 @@ typedef struct SDL_RWops
int whence); int whence);
/** /**
* Read up to \c maxnum objects each of size \c size from the data * Read up to `maxnum` objects each of size `size` from the data
* stream to the area pointed at by \c ptr. * stream to the area pointed at by `ptr`.
* *
* \return the number of objects read, or 0 at error or end of file. * \return the number of objects read, or 0 at error or end of file.
*/ */
@@ -75,8 +75,8 @@ typedef struct SDL_RWops
size_t size, size_t maxnum); size_t size, size_t maxnum);
/** /**
* Write exactly \c num objects each of size \c size from the area * Write exactly `num` objects each of size `size` from the area
* pointed at by \c ptr to data stream. * pointed at by `ptr` to data stream.
* *
* \return the number of objects written, or 0 at error or end of file. * \return the number of objects written, or 0 at error or end of file.
*/ */

6
include/SDL_scancode.h
View File

@@ -31,11 +31,11 @@
#include "SDL_stdinc.h" #include "SDL_stdinc.h"
/** /**
* \brief The SDL keyboard scancode representation. * The SDL keyboard scancode representation.
* *
* Values of this type are used to represent keyboard keys, among other places * Values of this type are used to represent keyboard keys, among other places
* in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the * in the SDL_Keysym::scancode key.keysym.scancode field of the SDL_Event
* SDL_Event structure. * structure.
* *
* The values in this enumeration are based on the USB usage page standard: * The values in this enumeration are based on the USB usage page standard:
* https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf

108
include/SDL_sensor.h
View File

@@ -44,7 +44,7 @@ extern "C" {
* \brief SDL_sensor.h * \brief SDL_sensor.h
* *
* In order to use these functions, SDL_Init() must have been called * In order to use these functions, SDL_Init() must have been called
* with the ::SDL_INIT_SENSOR flag. This causes SDL to scan the system * with the SDL_INIT_SENSOR flag. This causes SDL to scan the system
* for sensors, and load appropriate drivers. * for sensors, and load appropriate drivers.
*/ */
@@ -52,21 +52,67 @@ struct _SDL_Sensor;
typedef struct _SDL_Sensor SDL_Sensor; typedef struct _SDL_Sensor SDL_Sensor;
/** /**
* This is a unique ID for a sensor for the time it is connected to the system, * This is a unique ID for a sensor for the time it is connected to the
* and is never reused for the lifetime of the application. * system, and is never reused for the lifetime of the application.
* *
* The ID value starts at 0 and increments from there. The value -1 is an invalid ID. * The ID value starts at 0 and increments from there. The value -1 is an
* invalid ID.
*/ */
typedef Sint32 SDL_SensorID; typedef Sint32 SDL_SensorID;
/* The different sensors defined by SDL /**
* The different sensors defined by SDL.
* *
* Additional sensors may be available, using platform dependent semantics. * Additional sensors may be available, using platform dependent semantics.
* *
* Hare are the additional Android sensors: * Here are the additional Android sensors:
*
* https://developer.android.com/reference/android/hardware/SensorEvent.html#values * https://developer.android.com/reference/android/hardware/SensorEvent.html#values
*
* Accelerometer sensor notes:
*
* 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[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:
*
* - -X ... +X : left ... right
* - -Y ... +Y : bottom ... top
* - -Z ... +Z : farther ... closer
*
* The accelerometer axis data is not changed when the device is rotated.
*
* Gyroscope sensor notes:
*
* The gyroscope returns the current rate of rotation in radians per second.
* The rotation is positive in the counter-clockwise direction. That is, an
* observer looking from a positive location on one of the axes would see
* positive rotation on that axis when it appeared to be rotating
* counter-clockwise.
*
* - `values[0]`: Angular speed around the x axis (pitch)
* - `values[1]`: Angular speed around the y axis (yaw)
* - `values[2]`: Angular speed around the z axis (roll)
*
* 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
* - -Z ... +Z : farther ... closer
*
* The gyroscope axis data is not changed when the device is rotated.
*
* \sa SDL_GetDisplayOrientation
*/ */
typedef enum typedef enum SDL_SensorType
{ {
SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */ SDL_SENSOR_INVALID = -1, /**< Returned for an invalid sensor */
SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */ SDL_SENSOR_UNKNOWN, /**< Unknown sensor type */
@@ -79,53 +125,15 @@ typedef enum
} SDL_SensorType; } SDL_SensorType;
/** /**
* Accelerometer sensor * A constant to represent standard gravity for accelerometer sensors.
* *
* The accelerometer returns the current acceleration in SI meters per * The accelerometer returns the current acceleration in SI meters per second
* second squared. This measurement includes the force of gravity, so * squared. This measurement includes the force of gravity, so a device at
* a device at rest will have an value of SDL_STANDARD_GRAVITY away * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
* from the center of the earth, which is a positive Y value. * earth, which is a positive Y value.
*
* values[0]: Acceleration on the x axis
* values[1]: Acceleration on the y axis
* values[2]: Acceleration on the z axis
*
* For phones held in portrait mode and game controllers held in front of you,
* the axes are defined as follows:
* -X ... +X : left ... right
* -Y ... +Y : bottom ... top
* -Z ... +Z : farther ... closer
*
* The axis data is not changed when the phone is rotated.
*
* \sa SDL_GetDisplayOrientation()
*/ */
#define SDL_STANDARD_GRAVITY 9.80665f #define SDL_STANDARD_GRAVITY 9.80665f
/**
* Gyroscope sensor
*
* The gyroscope returns the current rate of rotation in radians per second.
* The rotation is positive in the counter-clockwise direction. That is,
* an observer looking from a positive location on one of the axes would
* see positive rotation on that axis when it appeared to be rotating
* counter-clockwise.
*
* values[0]: Angular speed around the x axis (pitch)
* values[1]: Angular speed around the y axis (yaw)
* values[2]: Angular speed around the z axis (roll)
*
* For phones held in portrait mode and game controllers held in front of you,
* the axes are defined as follows:
* -X ... +X : left ... right
* -Y ... +Y : bottom ... top
* -Z ... +Z : farther ... closer
*
* The axis data is not changed when the phone or controller is rotated.
*
* \sa SDL_GetDisplayOrientation()
*/
/* Function prototypes */ /* Function prototypes */
/** /**

18
include/SDL_shape.h
View File

@@ -48,18 +48,18 @@ extern "C" {
* and flags. * and flags.
* *
* \param title The title of the window, in UTF-8 encoding. * \param title The title of the window, in UTF-8 encoding.
* \param x The x position of the window, ::SDL_WINDOWPOS_CENTERED, or * \param x The x position of the window, SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED. * SDL_WINDOWPOS_UNDEFINED.
* \param y The y position of the window, ::SDL_WINDOWPOS_CENTERED, or * \param y The y position of the window, SDL_WINDOWPOS_CENTERED, or
* ::SDL_WINDOWPOS_UNDEFINED. * SDL_WINDOWPOS_UNDEFINED.
* \param w The width of the window. * \param w The width of the window.
* \param h The height of the window. * \param h The height of the window.
* \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with * \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
* any of the following: ::SDL_WINDOW_OPENGL, * any of the following: SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_INPUT_GRABBED, ::SDL_WINDOW_HIDDEN, * SDL_WINDOW_INPUT_GRABBED, SDL_WINDOW_HIDDEN,
* ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED, * SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED,
* ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set, * SDL_WINDOW_MINIMIZED, SDL_WINDOW_BORDERLESS is always set, and
* and ::SDL_WINDOW_FULLSCREEN is always unset. * SDL_WINDOW_FULLSCREEN is always unset.
* \return the window created, or NULL if window creation failed. * \return the window created, or NULL if window creation failed.
* *
* \since This function is available since SDL 2.0.0. * \since This function is available since SDL 2.0.0.

38
include/SDL_stdinc.h
View File

@@ -137,7 +137,11 @@ void *alloca(size_t);
/** /**
* Macro useful for building other macros with strings in them * Macro useful for building other macros with strings in them
* *
* e.g. #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") * e.g:
*
* ```c
* #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")
* ```
*/ */
#define SDL_STRINGIFY_ARG(arg) #arg #define SDL_STRINGIFY_ARG(arg) #arg
@@ -185,50 +189,56 @@ typedef enum
#endif #endif
/** /**
* \brief A signed 8-bit integer type. * A signed 8-bit integer type.
*/ */
#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
typedef int8_t Sint8; typedef int8_t Sint8;
/** /**
* \brief An unsigned 8-bit integer type. * An unsigned 8-bit integer type.
*/ */
#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
typedef uint8_t Uint8; typedef uint8_t Uint8;
/** /**
* \brief A signed 16-bit integer type. * A signed 16-bit integer type.
*/ */
#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
typedef int16_t Sint16; typedef int16_t Sint16;
/** /**
* \brief An unsigned 16-bit integer type. * An unsigned 16-bit integer type.
*/ */
#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
typedef uint16_t Uint16; typedef uint16_t Uint16;
/** /**
* \brief A signed 32-bit integer type. * A signed 32-bit integer type.
*/ */
#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
typedef int32_t Sint32; typedef int32_t Sint32;
/** /**
* \brief An unsigned 32-bit integer type. * An unsigned 32-bit integer type.
*/ */
#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */
#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
typedef uint32_t Uint32; typedef uint32_t Uint32;
/** /**
* \brief A signed 64-bit integer type. * A signed 64-bit integer type.
*/ */
#define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ #define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */
#define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ #define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
typedef int64_t Sint64; typedef int64_t Sint64;
/** /**
* \brief An unsigned 64-bit integer type. * An unsigned 64-bit integer type.
*/ */
#define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */ #define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */
#define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */ #define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */
@@ -775,8 +785,9 @@ SDL_FORCE_INLINE void *SDL_memcpy4(SDL_OUT_BYTECAP(dwords*4) void *dst, SDL_IN_B
} }
/** /**
* If a * b would overflow, return -1. Otherwise store a * b via ret * If a * b would overflow, return -1.
* and return 0. *
* Otherwise store a * b via ret and return 0.
* *
* \since This function is available since SDL 2.24.0. * \since This function is available since SDL 2.24.0.
*/ */
@@ -805,8 +816,9 @@ SDL_FORCE_INLINE int _SDL_size_mul_overflow_builtin (size_t a,
#endif #endif
/** /**
* If a + b would overflow, return -1. Otherwise store a + b via ret * If a + b would overflow, return -1.
* and return 0. *
* Otherwise store a + b via ret and return 0.
* *
* \since This function is available since SDL 2.24.0. * \since This function is available since SDL 2.24.0.
*/ */

112
include/SDL_surface.h
View File

@@ -22,7 +22,7 @@
/** /**
* \file SDL_surface.h * \file SDL_surface.h
* *
* Header file for ::SDL_Surface definition and management functions. * Header file for SDL_Surface definition and management functions.
*/ */
#ifndef SDL_surface_h_ #ifndef SDL_surface_h_
@@ -43,7 +43,7 @@ extern "C" {
/** /**
* \name Surface flags * \name Surface flags
* *
* These are the currently supported flags for the ::SDL_Surface. * These are the currently supported flags for the SDL_Surface.
* *
* \internal * \internal
* Used internally (read-only). * Used internally (read-only).
@@ -64,10 +64,10 @@ extern "C" {
typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */
/** /**
* \brief A collection of pixels used in software blitting. * A collection of pixels used in software blitting.
* *
* \note This structure should be treated as read-only, except for \c pixels, * This structure should be treated as read-only, except for `pixels`, which,
* which, if not NULL, contains the raw pixel data for the surface. * if not NULL, contains the raw pixel data for the surface.
*/ */
typedef struct SDL_Surface typedef struct SDL_Surface
{ {
@@ -103,7 +103,7 @@ typedef int (SDLCALL *SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
struct SDL_Surface * dst, SDL_Rect * dstrect); struct SDL_Surface * dst, SDL_Rect * dstrect);
/** /**
* \brief The formula used for converting between YUV and RGB * The formula used for converting between YUV and RGB
*/ */
typedef enum SDL_YUV_CONVERSION_MODE typedef enum SDL_YUV_CONVERSION_MODE
{ {
@@ -801,62 +801,64 @@ extern DECLSPEC int SDLCALL SDL_FillRects
(SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color); (SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
/* !!! FIXME: merge this documentation with the wiki */ /* !!! FIXME: merge this documentation with the wiki */
/** /**
* Performs a fast blit from the source surface to the destination surface. * Performs a fast blit from the source surface to the destination surface.
* *
* This assumes that the source and destination rectangles are * This assumes that the source and destination rectangles are the same size.
* the same size. If either \c srcrect or \c dstrect are NULL, the entire * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
* surface (\c src or \c dst) is copied. The final blit rectangles are saved * `dst`) is copied. The final blit rectangles are saved in `srcrect` and
* in \c srcrect and \c dstrect after all clipping is performed. * `dstrect` after all clipping is performed.
*
* \returns 0 if the blit is successful, otherwise it returns -1.
* *
* The blit function should not be called on a locked surface. * The blit function should not be called on a locked surface.
* *
* The blit semantics for surfaces with and without blending and colorkey * The blit semantics for surfaces with and without blending and colorkey are
* are defined as follows: * defined as follows:
* \verbatim
RGBA->RGB:
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
* *
* You should call SDL_BlitSurface() unless you know exactly how SDL * ```
* blitting works internally and how to use the other blit functions. * 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.
* ```
*
* You should call SDL_BlitSurface() unless you know exactly how SDL blitting
* works internally and how to use the other blit functions.
*
* \returns 0 if the blit is successful, otherwise it returns -1.
*/ */
#define SDL_BlitSurface SDL_UpperBlit #define SDL_BlitSurface SDL_UpperBlit

8
include/SDL_system.h
View File

@@ -356,8 +356,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
/** /**
See the official Android developer guide for more information: * See the official Android developer guide for more information:
http://developer.android.com/guide/topics/data/data-storage.html * http://developer.android.com/guide/topics/data/data-storage.html
*/ */
#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
@@ -470,7 +470,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
#ifdef __WINRT__ #ifdef __WINRT__
/** /**
* \brief WinRT / Windows Phone path types * WinRT / Windows Phone path types
*/ */
typedef enum SDL_WinRT_Path typedef enum SDL_WinRT_Path
{ {
@@ -494,7 +494,7 @@ typedef enum SDL_WinRT_Path
/** /**
* \brief WinRT Device Family * WinRT Device Family
*/ */
typedef enum SDL_WinRT_DeviceFamily typedef enum SDL_WinRT_DeviceFamily
{ {

7
include/SDL_syswm.h
View File

@@ -36,7 +36,7 @@
/* /*
* \file SDL_syswm.h * \file SDL_syswm.h
* *
* Your application has access to a special type of event ::SDL_SYSWMEVENT, * Your application has access to a special type of event SDL_SYSWMEVENT,
* which contains window-manager specific information and arrives whenever * which contains window-manager specific information and arrives whenever
* an unhandled window event occurs. This event is ignored by default, but * an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_EventState(). * you can enable it with SDL_EventState().
@@ -130,6 +130,7 @@ extern "C" {
#endif #endif
#if !defined(SDL_PROTOTYPES_ONLY) #if !defined(SDL_PROTOTYPES_ONLY)
/** /**
* These are the various supported windowing subsystems * These are the various supported windowing subsystems
*/ */
@@ -221,8 +222,8 @@ struct SDL_SysWMmsg
/** /**
* The custom window manager information structure. * The custom window manager information structure.
* *
* When this structure is returned, it holds information about which * When this structure is returned, it holds information about which low level
* low level system it is using, and will be one of SDL_SYSWM_TYPE. * system it is using, and will be one of SDL_SYSWM_TYPE.
*/ */
struct SDL_SysWMinfo struct SDL_SysWMinfo
{ {

2
include/SDL_test.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test.h * \file SDL_test.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.

18
include/SDL_test_assert.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_assert.h * \file SDL_test_assert.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -42,17 +42,17 @@
extern "C" { extern "C" {
#endif #endif
/** /*
* \brief Fails the assert. * \brief Fails the assert.
*/ */
#define ASSERT_FAIL 0 #define ASSERT_FAIL 0
/** /*
* \brief Passes the assert. * \brief Passes the assert.
*/ */
#define ASSERT_PASS 1 #define ASSERT_PASS 1
/** /*
* \brief Assert that logs and break execution flow on failures. * \brief Assert that logs and break execution flow on failures.
* *
* \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
@@ -60,7 +60,7 @@ extern "C" {
*/ */
void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
/** /*
* \brief Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. * \brief Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters.
* *
* \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
@@ -70,25 +70,25 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
*/ */
int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
/** /*
* \brief Explicitly pass without checking an assertion condition. Updates assertion counter. * \brief Explicitly pass without checking an assertion condition. Updates assertion counter.
* *
* \param assertDescription Message to log with the assert describing it. * \param assertDescription Message to log with the assert describing it.
*/ */
void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1);
/** /*
* \brief Resets the assert summary counters to zero. * \brief Resets the assert summary counters to zero.
*/ */
void SDLTest_ResetAssertSummary(void); void SDLTest_ResetAssertSummary(void);
/** /*
* \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. * \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR.
*/ */
void SDLTest_LogAssertSummary(void); void SDLTest_LogAssertSummary(void);
/** /*
* \brief Converts the current assert summary state to a test result. * \brief Converts the current assert summary state to a test result.
* *
* \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT

20
include/SDL_test_common.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_common.h * \file SDL_test_common.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -129,7 +129,7 @@ extern "C" {
/* Function prototypes */ /* Function prototypes */
/** /*
* \brief Parse command line parameters and create common state. * \brief Parse command line parameters and create common state.
* *
* \param argv Array of command line parameters * \param argv Array of command line parameters
@@ -139,7 +139,7 @@ extern "C" {
*/ */
SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags); SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
/** /*
* \brief Process one common argument. * \brief Process one common argument.
* *
* \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
@@ -150,7 +150,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
int SDLTest_CommonArg(SDLTest_CommonState * state, int index); int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
/** /*
* \brief Logs command line usage info. * \brief Logs command line usage info.
* *
* This logs the appropriate command line options for the subsystems in use * This logs the appropriate command line options for the subsystems in use
@@ -164,7 +164,7 @@ int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
*/ */
void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, const char **options); void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, const char **options);
/** /*
* \brief Returns common usage information * \brief Returns common usage information
* *
* You should (probably) be using SDLTest_CommonLogUsage() instead, but this * You should (probably) be using SDLTest_CommonLogUsage() instead, but this
@@ -177,7 +177,7 @@ void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, cons
*/ */
const char *SDLTest_CommonUsage(SDLTest_CommonState * state); const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
/** /*
* \brief Open test window. * \brief Open test window.
* *
* \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
@@ -186,7 +186,7 @@ const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
*/ */
SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state); SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
/** /*
* \brief Easy argument handling when test app doesn't need any custom args. * \brief Easy argument handling when test app doesn't need any custom args.
* *
* \param state The common state describing the test window to create. * \param state The common state describing the test window to create.
@@ -197,7 +197,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
*/ */
SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv); SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv);
/** /*
* \brief Common event handler for test windows. * \brief Common event handler for test windows.
* *
* \param state The common state used to create test window. * \param state The common state used to create test window.
@@ -207,7 +207,7 @@ SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc,
*/ */
void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done); void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *done);
/** /*
* \brief Close test window. * \brief Close test window.
* *
* \param state The common state used to create test window. * \param state The common state used to create test window.
@@ -215,7 +215,7 @@ void SDLTest_CommonEvent(SDLTest_CommonState * state, SDL_Event * event, int *do
*/ */
void SDLTest_CommonQuit(SDLTest_CommonState * state); void SDLTest_CommonQuit(SDLTest_CommonState * state);
/** /*
* \brief Draws various window information (position, size, etc.) to the renderer. * \brief Draws various window information (position, size, etc.) to the renderer.
* *
* \param renderer The renderer to draw to. * \param renderer The renderer to draw to.

4
include/SDL_test_compare.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_compare.h * \file SDL_test_compare.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -46,7 +46,7 @@
extern "C" { extern "C" {
#endif #endif
/** /*
* \brief Compares a surface and with reference image data for equality * \brief Compares a surface and with reference image data for equality
* *
* \param surface Surface used in comparison * \param surface Surface used in comparison

22
include/SDL_test_font.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_font.h * \file SDL_test_font.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -41,7 +41,7 @@ extern "C" {
#define FONT_CHARACTER_SIZE 8 #define FONT_CHARACTER_SIZE 8
#define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2) #define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2)
/** /*
* \brief Draw a string in the currently set font. * \brief Draw a string in the currently set font.
* *
* \param renderer The renderer to draw on. * \param renderer The renderer to draw on.
@@ -53,7 +53,7 @@ extern "C" {
*/ */
int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c); int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c);
/** /*
* \brief Draw a UTF-8 string in the currently set font. * \brief Draw a UTF-8 string in the currently set font.
* *
* The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets. * The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets.
@@ -67,7 +67,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, Uint32 c);
*/ */
int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s); int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s);
/** /*
* \brief Data used for multi-line text output * \brief Data used for multi-line text output
*/ */
typedef struct SDLTest_TextWindow typedef struct SDLTest_TextWindow
@@ -78,7 +78,7 @@ typedef struct SDLTest_TextWindow
char **lines; char **lines;
} SDLTest_TextWindow; } SDLTest_TextWindow;
/** /*
* \brief Create a multi-line text output window * \brief Create a multi-line text output window
* *
* \param x The X coordinate of the upper left corner of the window. * \param x The X coordinate of the upper left corner of the window.
@@ -92,7 +92,7 @@ typedef struct SDLTest_TextWindow
*/ */
SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h); SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h);
/** /*
* \brief Display a multi-line text output window * \brief Display a multi-line text output window
* *
* This function should be called every frame to display the text * This function should be called every frame to display the text
@@ -104,7 +104,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(int x, int y, int w, int h);
*/ */
void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer);
/** /*
* \brief Add text to a multi-line text output window * \brief Add text to a multi-line text output window
* *
* Adds UTF-8 text to the end of the current text. The newline character starts a * Adds UTF-8 text to the end of the current text. The newline character starts a
@@ -119,7 +119,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render
*/ */
void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/** /*
* \brief Add text to a multi-line text output window * \brief Add text to a multi-line text output window
* *
* Adds UTF-8 text to the end of the current text. The newline character starts a * Adds UTF-8 text to the end of the current text. The newline character starts a
@@ -134,7 +134,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST
*/ */
void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len);
/** /*
* \brief Clear the text in a multi-line text output window * \brief Clear the text in a multi-line text output window
* *
* \param textwin The text output window * \param textwin The text output window
@@ -143,7 +143,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char
*/ */
void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
/** /*
* \brief Free the storage associated with a multi-line text output window * \brief Free the storage associated with a multi-line text output window
* *
* \param textwin The text output window * \param textwin The text output window
@@ -152,7 +152,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
*/ */
void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin);
/** /*
* \brief Cleanup textures used by font drawing functions. * \brief Cleanup textures used by font drawing functions.
*/ */
void SDLTest_CleanupTextDrawing(void); void SDLTest_CleanupTextDrawing(void);

57
include/SDL_test_fuzzer.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_fuzzer.h * \file SDL_test_fuzzer.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -48,13 +48,13 @@ extern "C" {
*/ */
/** /*
* \file * \file
* Note: The fuzzer implementation uses a static instance of random context * Note: The fuzzer implementation uses a static instance of random context
* internally which makes it thread-UNsafe. * internally which makes it thread-UNsafe.
*/ */
/** /*
* Initializes the fuzzer for a test * Initializes the fuzzer for a test
* *
* \param execKey Execution "Key" that initializes the random number generator uniquely for the test. * \param execKey Execution "Key" that initializes the random number generator uniquely for the test.
@@ -63,14 +63,14 @@ extern "C" {
void SDLTest_FuzzerInit(Uint64 execKey); void SDLTest_FuzzerInit(Uint64 execKey);
/** /*
* Returns a random Uint8 * Returns a random Uint8
* *
* \returns a generated integer * \returns a generated integer
*/ */
Uint8 SDLTest_RandomUint8(void); Uint8 SDLTest_RandomUint8(void);
/** /*
* Returns a random Sint8 * Returns a random Sint8
* *
* \returns a generated signed integer * \returns a generated signed integer
@@ -78,14 +78,14 @@ Uint8 SDLTest_RandomUint8(void);
Sint8 SDLTest_RandomSint8(void); Sint8 SDLTest_RandomSint8(void);
/** /*
* Returns a random Uint16 * Returns a random Uint16
* *
* \returns a generated integer * \returns a generated integer
*/ */
Uint16 SDLTest_RandomUint16(void); Uint16 SDLTest_RandomUint16(void);
/** /*
* Returns a random Sint16 * Returns a random Sint16
* *
* \returns a generated signed integer * \returns a generated signed integer
@@ -93,7 +93,7 @@ Uint16 SDLTest_RandomUint16(void);
Sint16 SDLTest_RandomSint16(void); Sint16 SDLTest_RandomSint16(void);
/** /*
* Returns a random integer * Returns a random integer
* *
* \returns a generated integer * \returns a generated integer
@@ -101,14 +101,14 @@ Sint16 SDLTest_RandomSint16(void);
Sint32 SDLTest_RandomSint32(void); Sint32 SDLTest_RandomSint32(void);
/** /*
* Returns a random positive integer * Returns a random positive integer
* *
* \returns a generated integer * \returns a generated integer
*/ */
Uint32 SDLTest_RandomUint32(void); Uint32 SDLTest_RandomUint32(void);
/** /*
* Returns random Uint64. * Returns random Uint64.
* *
* \returns a generated integer * \returns a generated integer
@@ -116,36 +116,36 @@ Uint32 SDLTest_RandomUint32(void);
Uint64 SDLTest_RandomUint64(void); Uint64 SDLTest_RandomUint64(void);
/** /*
* Returns random Sint64. * Returns random Sint64.
* *
* \returns a generated signed integer * \returns a generated signed integer
*/ */
Sint64 SDLTest_RandomSint64(void); Sint64 SDLTest_RandomSint64(void);
/** /*
* \returns a random float in range [0.0 - 1.0] * \returns a random float in range [0.0 - 1.0]
*/ */
float SDLTest_RandomUnitFloat(void); float SDLTest_RandomUnitFloat(void);
/** /*
* \returns a random double in range [0.0 - 1.0] * \returns a random double in range [0.0 - 1.0]
*/ */
double SDLTest_RandomUnitDouble(void); double SDLTest_RandomUnitDouble(void);
/** /*
* \returns a random float. * \returns a random float.
* *
*/ */
float SDLTest_RandomFloat(void); float SDLTest_RandomFloat(void);
/** /*
* \returns a random double. * \returns a random double.
* *
*/ */
double SDLTest_RandomDouble(void); double SDLTest_RandomDouble(void);
/** /*
* Returns a random boundary value for Uint8 within the given boundaries. * Returns a random boundary value for Uint8 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -166,7 +166,7 @@ double SDLTest_RandomDouble(void);
*/ */
Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain); Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Uint16 within the given boundaries. * Returns a random boundary value for Uint16 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -187,7 +187,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo
*/ */
Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain); Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Uint32 within the given boundaries. * Returns a random boundary value for Uint32 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -208,7 +208,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL
*/ */
Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain); Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Uint64 within the given boundaries. * Returns a random boundary value for Uint64 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -229,7 +229,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL
*/ */
Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain); Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Sint8 within the given boundaries. * Returns a random boundary value for Sint8 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -251,7 +251,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL
Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain); Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Sint16 within the given boundaries. * Returns a random boundary value for Sint16 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -272,7 +272,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo
*/ */
Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain); Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Sint32 within the given boundaries. * Returns a random boundary value for Sint32 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -293,7 +293,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL
*/ */
Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain); Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
/** /*
* Returns a random boundary value for Sint64 within the given boundaries. * Returns a random boundary value for Sint64 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain * Boundaries are inclusive, see the usage examples below. If validDomain
* is true, the function will only return valid boundaries, otherwise non-valid * is true, the function will only return valid boundaries, otherwise non-valid
@@ -315,7 +315,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL
Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain); Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
/** /*
* Returns integer in range [min, max] (inclusive). * Returns integer in range [min, max] (inclusive).
* Min and max values can be negative values. * Min and max values can be negative values.
* If Max in smaller than min, then the values are swapped. * If Max in smaller than min, then the values are swapped.
@@ -329,7 +329,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL
Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max); Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
/** /*
* Generates random null-terminated string. The minimum length for * Generates random null-terminated string. The minimum length for
* the string is 1 character, maximum length for the string is 255 * the string is 1 character, maximum length for the string is 255
* characters and it can contain ASCII characters from 32 to 126. * characters and it can contain ASCII characters from 32 to 126.
@@ -341,7 +341,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
char * SDLTest_RandomAsciiString(void); char * SDLTest_RandomAsciiString(void);
/** /*
* Generates random null-terminated string. The maximum length for * Generates random null-terminated string. The maximum length for
* the string is defined by the maxLength parameter. * the string is defined by the maxLength parameter.
* String can contain ASCII characters from 32 to 126. * String can contain ASCII characters from 32 to 126.
@@ -355,7 +355,7 @@ char * SDLTest_RandomAsciiString(void);
char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength); char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
/** /*
* Generates random null-terminated string. The length for * Generates random null-terminated string. The length for
* the string is defined by the size parameter. * the string is defined by the size parameter.
* String can contain ASCII characters from 32 to 126. * String can contain ASCII characters from 32 to 126.
@@ -368,7 +368,8 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
*/ */
char * SDLTest_RandomAsciiStringOfSize(int size); char * SDLTest_RandomAsciiStringOfSize(int size);
/**
/*
* Get the invocation count for the fuzzer since last ...FuzzerInit. * Get the invocation count for the fuzzer since last ...FuzzerInit.
* *
* \returns the invocation count. * \returns the invocation count.

10
include/SDL_test_harness.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_harness.h * \file SDL_test_harness.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -69,7 +69,7 @@ typedef int (*SDLTest_TestCaseFp)(void *arg);
/* !< Function pointer to a test case teardown function (run after every test) */ /* !< Function pointer to a test case teardown function (run after every test) */
typedef void (*SDLTest_TestCaseTearDownFp)(void *arg); typedef void (*SDLTest_TestCaseTearDownFp)(void *arg);
/** /*
* Holds information about a single test case. * Holds information about a single test case.
*/ */
typedef struct SDLTest_TestCaseReference { typedef struct SDLTest_TestCaseReference {
@@ -83,7 +83,7 @@ typedef struct SDLTest_TestCaseReference {
int enabled; int enabled;
} SDLTest_TestCaseReference; } SDLTest_TestCaseReference;
/** /*
* Holds information about a test suite (multiple test cases). * Holds information about a test suite (multiple test cases).
*/ */
typedef struct SDLTest_TestSuiteReference { typedef struct SDLTest_TestSuiteReference {
@@ -98,7 +98,7 @@ typedef struct SDLTest_TestSuiteReference {
} SDLTest_TestSuiteReference; } SDLTest_TestSuiteReference;
/** /*
* \brief Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z). * \brief Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z).
* *
* Note: The returned string needs to be deallocated by the caller. * Note: The returned string needs to be deallocated by the caller.
@@ -109,7 +109,7 @@ typedef struct SDLTest_TestSuiteReference {
*/ */
char *SDLTest_GenerateRunSeed(const int length); char *SDLTest_GenerateRunSeed(const int length);
/** /*
* \brief Execute a test suite using the given run seed and execution key. * \brief Execute a test suite using the given run seed and execution key.
* *
* \param testSuites Suites containing the test case. * \param testSuites Suites containing the test case.

4
include/SDL_test_images.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_images.h * \file SDL_test_images.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -44,7 +44,7 @@
extern "C" { extern "C" {
#endif #endif
/** /*
*Type for test images. *Type for test images.
*/ */
typedef struct SDLTest_SurfaceImage_s { typedef struct SDLTest_SurfaceImage_s {

6
include/SDL_test_log.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_log.h * \file SDL_test_log.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -42,14 +42,14 @@
extern "C" { extern "C" {
#endif #endif
/** /*
* \brief Prints given message with a timestamp in the TEST category and INFO priority. * \brief Prints given message with a timestamp in the TEST category and INFO priority.
* *
* \param fmt Message to be logged * \param fmt Message to be logged
*/ */
void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1); void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/** /*
* \brief Prints given message with a timestamp in the TEST category and the ERROR priority. * \brief Prints given message with a timestamp in the TEST category and the ERROR priority.
* *
* \param fmt Message to be logged * \param fmt Message to be logged

8
include/SDL_test_md5.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_md5.h * \file SDL_test_md5.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -77,7 +77,7 @@ extern "C" {
/* ---------- Function Prototypes ------------- */ /* ---------- Function Prototypes ------------- */
/** /*
* \brief initialize the context * \brief initialize the context
* *
* \param mdContext pointer to context variable * \param mdContext pointer to context variable
@@ -89,7 +89,7 @@ extern "C" {
void SDLTest_Md5Init(SDLTest_Md5Context * mdContext); void SDLTest_Md5Init(SDLTest_Md5Context * mdContext);
/** /*
* \brief update digest from variable length data * \brief update digest from variable length data
* *
* \param mdContext pointer to context variable * \param mdContext pointer to context variable
@@ -105,7 +105,7 @@ extern "C" {
unsigned int inLen); unsigned int inLen);
/** /*
* \brief complete digest computation * \brief complete digest computation
* *
* \param mdContext pointer to context variable * \param mdContext pointer to context variable

6
include/SDL_test_memory.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_memory.h * \file SDL_test_memory.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -37,14 +37,14 @@ extern "C" {
#endif #endif
/** /*
* \brief Start tracking SDL memory allocations * \brief Start tracking SDL memory allocations
* *
* \note This should be called before any other SDL functions for complete tracking coverage * \note This should be called before any other SDL functions for complete tracking coverage
*/ */
int SDLTest_TrackAllocations(void); int SDLTest_TrackAllocations(void);
/** /*
* \brief Print a log of any outstanding allocations * \brief Print a log of any outstanding allocations
* *
* \note This can be called after SDL_Quit() * \note This can be called after SDL_Quit()

8
include/SDL_test_random.h
View File

@@ -19,7 +19,7 @@
3. This notice may not be removed or altered from any source distribution. 3. This notice may not be removed or altered from any source distribution.
*/ */
/** /*
* \file SDL_test_random.h * \file SDL_test_random.h
* *
* Include file for SDL test framework. * Include file for SDL test framework.
@@ -67,7 +67,7 @@ extern "C" {
/* --- Function prototypes */ /* --- Function prototypes */
/** /*
* \brief Initialize random number generator with two integers. * \brief Initialize random number generator with two integers.
* *
* Note: The random sequence of numbers returned by ...Random() is the * Note: The random sequence of numbers returned by ...Random() is the
@@ -81,7 +81,7 @@ extern "C" {
void SDLTest_RandomInit(SDLTest_RandomContext * rndContext, unsigned int xi, void SDLTest_RandomInit(SDLTest_RandomContext * rndContext, unsigned int xi,
unsigned int ci); unsigned int ci);
/** /*
* \brief Initialize random number generator based on current system time. * \brief Initialize random number generator based on current system time.
* *
* \param rndContext pointer to context structure * \param rndContext pointer to context structure
@@ -90,7 +90,7 @@ extern "C" {
void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext); void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext);
/** /*
* \brief Initialize random number generator based on current system time. * \brief Initialize random number generator based on current system time.
* *
* Note: ...RandomInit() or ...RandomInitTime() must have been called * Note: ...RandomInit() or ...RandomInitTime() must have been called

12
include/SDL_thread.h
View File

@@ -65,12 +65,14 @@ typedef unsigned int SDL_TLSID;
/** /**
* The SDL thread priority. * The SDL thread priority.
* *
* SDL will make system changes as necessary in order to apply the thread priority. * SDL will make system changes as necessary in order to apply the thread
* Code which attempts to control thread state related to priority should be aware * priority. Code which attempts to control thread state related to priority
* that calling SDL_SetThreadPriority may alter such state. * 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. * 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. * On many systems you require special privileges to set high or time critical
* priority.
*/ */
typedef enum SDL_ThreadPriority { typedef enum SDL_ThreadPriority {
SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_LOW,

18
include/SDL_timer.h
View File

@@ -89,8 +89,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void);
* days, but should _not_ be used with SDL_GetTicks64(), which does not have * days, but should _not_ be used with SDL_GetTicks64(), which does not have
* that problem. * that problem.
* *
* For example, with SDL_GetTicks(), if you want to wait 100 ms, you could * For example, with SDL_GetTicks(), if you want to wait 100 ms, you could do
* do this: * this:
* *
* ```c * ```c
* const Uint32 timeout = SDL_GetTicks() + 100; * const Uint32 timeout = SDL_GetTicks() + 100;
@@ -99,9 +99,9 @@ extern DECLSPEC Uint64 SDLCALL SDL_GetTicks64(void);
* } * }
* ``` * ```
* *
* Note that this does not handle tick differences greater * Note that this does not handle tick differences greater than 2^31 so take
* than 2^31 so take care when using the above kind of code * care when using the above kind of code with large timeout delays (tens of
* with large timeout delays (tens of days). * days).
*/ */
#define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0) #define SDL_TICKS_PASSED(A, B) ((Sint32)((B) - (A)) <= 0)
@@ -149,10 +149,10 @@ extern DECLSPEC void SDLCALL SDL_Delay(Uint32 ms);
/** /**
* Function prototype for the timer callback function. * Function prototype for the timer callback function.
* *
* The callback function is passed the current timer interval and returns * The callback function is passed the current timer interval and returns the
* the next timer interval. If the returned value is the same as the one * next timer interval. If the returned value is the same as the one passed
* passed in, the periodic alarm continues, otherwise a new alarm is * in, the periodic alarm continues, otherwise a new alarm is scheduled. If
* scheduled. If the callback returns 0, the periodic alarm is cancelled. * the callback returns 0, the periodic alarm is cancelled.
*/ */
typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param); typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);

39
include/SDL_version.h
View File

@@ -40,10 +40,9 @@ extern "C" {
* Information about the version of SDL in use. * Information about the version of SDL in use.
* *
* Represents the library's version as three levels: major revision * Represents the library's version as three levels: major revision
* (increments with massive changes, additions, and enhancements), * (increments with massive changes, additions, and enhancements), minor
* minor revision (increments with backwards-compatible changes to the * revision (increments with backwards-compatible changes to the major
* major revision), and patchlevel (increments with fixes to the minor * revision), and patchlevel (increments with fixes to the minor revision).
* revision).
* *
* \sa SDL_VERSION * \sa SDL_VERSION
* \sa SDL_GetVersion * \sa SDL_GetVersion
@@ -64,12 +63,11 @@ typedef struct SDL_version
/** /**
* Macro to determine SDL version program was compiled against. * Macro to determine SDL version program was compiled against.
* *
* This macro fills in a SDL_version structure with the version of the * This macro fills in a SDL_version structure with the version of the library
* library you compiled against. This is determined by what header the * you compiled against. This is determined by what header the compiler uses.
* compiler uses. Note that if you dynamically linked the library, you might * Note that if you dynamically linked the library, you might have a slightly
* have a slightly newer or older version at runtime. That version can be * newer or older version at runtime. That version can be determined with
* determined with SDL_GetVersion(), which, unlike SDL_VERSION(), * SDL_GetVersion(), which, unlike SDL_VERSION(), is not a macro.
* is not a macro.
* *
* \param x A pointer to a SDL_version struct to initialize. * \param x A pointer to a SDL_version struct to initialize.
* *
@@ -85,17 +83,20 @@ typedef struct SDL_version
/* TODO: Remove this whole block in SDL 3 */ /* TODO: Remove this whole block in SDL 3 */
#if SDL_MAJOR_VERSION < 3 #if SDL_MAJOR_VERSION < 3
/** /**
* This macro turns the version numbers into a numeric value: * This macro turns the version numbers into a numeric value:
* \verbatim *
(1,2,3) -> (1203) * ```
\endverbatim * (1,2,3) -> (1203)
* ```
* *
* This assumes that there will never be more than 100 patchlevels. * This assumes that there will never be more than 100 patchlevels.
* *
* In versions higher than 2.9.0, the minor version overflows into * In versions higher than 2.9.0, the minor version overflows into the
* the thousands digit: for example, 2.23.0 is encoded as 4300, * thousands digit: for example, 2.23.0 is encoded as 4300, and 2.255.99 would
* and 2.255.99 would be encoded as 25799. * be encoded as 25799.
*
* This macro will not be available in SDL 3.x. * This macro will not be available in SDL 3.x.
*/ */
#define SDL_VERSIONNUM(X, Y, Z) \ #define SDL_VERSIONNUM(X, Y, Z) \
@@ -104,9 +105,9 @@ typedef struct SDL_version
/** /**
* This is the version number macro for the current SDL version. * This is the version number macro for the current SDL version.
* *
* In versions higher than 2.9.0, the minor version overflows into * In versions higher than 2.9.0, the minor version overflows into the
* the thousands digit: for example, 2.23.0 is encoded as 4300. * thousands digit: for example, 2.23.0 is encoded as 4300. This macro will
* This macro will not be available in SDL 3.x. * not be available in SDL 3.x.
* *
* Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead. * Deprecated, use SDL_VERSION_ATLEAST or SDL_VERSION instead.
*/ */

96
include/SDL_video.h
View File

@@ -40,15 +40,15 @@ extern "C" {
#endif #endif
/** /**
* \brief The structure that defines a display mode * The structure that defines a display mode
* *
* \sa SDL_GetNumDisplayModes() * \sa SDL_GetNumDisplayModes
* \sa SDL_GetDisplayMode() * \sa SDL_GetDisplayMode
* \sa SDL_GetDesktopDisplayMode() * \sa SDL_GetDesktopDisplayMode
* \sa SDL_GetCurrentDisplayMode() * \sa SDL_GetCurrentDisplayMode
* \sa SDL_GetClosestDisplayMode() * \sa SDL_GetClosestDisplayMode
* \sa SDL_SetWindowDisplayMode() * \sa SDL_SetWindowDisplayMode
* \sa SDL_GetWindowDisplayMode() * \sa SDL_GetWindowDisplayMode
*/ */
typedef struct SDL_DisplayMode typedef struct SDL_DisplayMode
{ {
@@ -60,44 +60,44 @@ typedef struct SDL_DisplayMode
} SDL_DisplayMode; } SDL_DisplayMode;
/** /**
* \brief The type used to identify a window * The type used to identify a window
* *
* \sa SDL_CreateWindow() * \sa SDL_CreateWindow
* \sa SDL_CreateWindowFrom() * \sa SDL_CreateWindowFrom
* \sa SDL_DestroyWindow() * \sa SDL_DestroyWindow
* \sa SDL_FlashWindow() * \sa SDL_FlashWindow
* \sa SDL_GetWindowData() * \sa SDL_GetWindowData
* \sa SDL_GetWindowFlags() * \sa SDL_GetWindowFlags
* \sa SDL_GetWindowGrab() * \sa SDL_GetWindowGrab
* \sa SDL_GetWindowKeyboardGrab() * \sa SDL_GetWindowKeyboardGrab
* \sa SDL_GetWindowMouseGrab() * \sa SDL_GetWindowMouseGrab
* \sa SDL_GetWindowPosition() * \sa SDL_GetWindowPosition
* \sa SDL_GetWindowSize() * \sa SDL_GetWindowSize
* \sa SDL_GetWindowTitle() * \sa SDL_GetWindowTitle
* \sa SDL_HideWindow() * \sa SDL_HideWindow
* \sa SDL_MaximizeWindow() * \sa SDL_MaximizeWindow
* \sa SDL_MinimizeWindow() * \sa SDL_MinimizeWindow
* \sa SDL_RaiseWindow() * \sa SDL_RaiseWindow
* \sa SDL_RestoreWindow() * \sa SDL_RestoreWindow
* \sa SDL_SetWindowData() * \sa SDL_SetWindowData
* \sa SDL_SetWindowFullscreen() * \sa SDL_SetWindowFullscreen
* \sa SDL_SetWindowGrab() * \sa SDL_SetWindowGrab
* \sa SDL_SetWindowKeyboardGrab() * \sa SDL_SetWindowKeyboardGrab
* \sa SDL_SetWindowMouseGrab() * \sa SDL_SetWindowMouseGrab
* \sa SDL_SetWindowIcon() * \sa SDL_SetWindowIcon
* \sa SDL_SetWindowPosition() * \sa SDL_SetWindowPosition
* \sa SDL_SetWindowSize() * \sa SDL_SetWindowSize
* \sa SDL_SetWindowBordered() * \sa SDL_SetWindowBordered
* \sa SDL_SetWindowResizable() * \sa SDL_SetWindowResizable
* \sa SDL_SetWindowTitle() * \sa SDL_SetWindowTitle
* \sa SDL_ShowWindow() * \sa SDL_ShowWindow
*/ */
typedef struct SDL_Window SDL_Window; typedef struct SDL_Window SDL_Window;
/** /**
* \brief The flags on a window * The flags on a window
* *
* \sa SDL_GetWindowFlags() * \sa SDL_GetWindowFlags
*/ */
typedef enum SDL_WindowFlags typedef enum SDL_WindowFlags
{ {
@@ -131,7 +131,7 @@ typedef enum SDL_WindowFlags
} SDL_WindowFlags; } SDL_WindowFlags;
/** /**
* \brief Used to indicate that you don't care what the window position is. * Used to indicate that you don't care what the window position is.
*/ */
#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
@@ -140,7 +140,7 @@ typedef enum SDL_WindowFlags
(((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
/** /**
* \brief Used to indicate that the window position should be centered. * Used to indicate that the window position should be centered.
*/ */
#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
#define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X))
@@ -149,7 +149,7 @@ typedef enum SDL_WindowFlags
(((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
/** /**
* \brief Event subtype for window events * Event subtype for window events
*/ */
typedef enum SDL_WindowEventID typedef enum SDL_WindowEventID
{ {
@@ -180,7 +180,7 @@ typedef enum SDL_WindowEventID
} SDL_WindowEventID; } SDL_WindowEventID;
/** /**
* \brief Event subtype for display events * Event subtype for display events
*/ */
typedef enum SDL_DisplayEventID typedef enum SDL_DisplayEventID
{ {
@@ -192,7 +192,7 @@ typedef enum SDL_DisplayEventID
} SDL_DisplayEventID; } SDL_DisplayEventID;
/** /**
* \brief Display orientation * Display orientation
*/ */
typedef enum SDL_DisplayOrientation typedef enum SDL_DisplayOrientation
{ {
@@ -204,7 +204,7 @@ typedef enum SDL_DisplayOrientation
} SDL_DisplayOrientation; } SDL_DisplayOrientation;
/** /**
* \brief Window flash operation * Window flash operation
*/ */
typedef enum SDL_FlashOperation typedef enum SDL_FlashOperation
{ {
@@ -214,12 +214,12 @@ typedef enum SDL_FlashOperation
} SDL_FlashOperation; } SDL_FlashOperation;
/** /**
* \brief An opaque handle to an OpenGL context. * An opaque handle to an OpenGL context.
*/ */
typedef void *SDL_GLContext; typedef void *SDL_GLContext;
/** /**
* \brief OpenGL configuration attributes * OpenGL configuration attributes
*/ */
typedef enum SDL_GLattr typedef enum SDL_GLattr
{ {