eden-emu/SDL
15
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
No known key found for this signature in database
GPG key ID: FA148B892AB48044
80 changed files with 6963 additions and 6115 deletions
Download patch file Download diff file Expand all files Collapse all files

709
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
* so people don't accidentally use numeric operations on it.
* A type representing an atomic integer value.
*
* It is a struct so people don't accidentally use numeric operations on it.
*/
typedef struct SDL_atomic_t {
int value;

46
include/SDL_audio.h
View file

@ -166,16 +166,19 @@ typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
int len);
/**
* 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:
* 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad)
* 5: FL FR LFE BL BR (4.1 surround)
* 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)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround)
* For multi-channel audio, the default SDL channel mapping is:
*
* ```
* 2: FL FR (stereo)
* 3: FL FR LFE (2.1 surround)
* 4: FL FR BL BR (quad)
* 5: FL FR LFE BL BR (4.1 surround)
* 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)
* 8: FL FR FC LFE BL BR SL SR (7.1 surround)
* ```
*/
typedef struct SDL_AudioSpec
{
@ -196,11 +199,11 @@ typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
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
* currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers,
* one of which is the terminating NULL pointer.
* The maximum number of SDL_AudioFilter functions in SDL_AudioCVT is
* currently limited to 9. The SDL_AudioCVT.filters array has 10 pointers, one
* of which is the terminating NULL pointer.
*/
#define SDL_AUDIOCVT_MAX_FILTERS 9
@ -408,13 +411,13 @@ extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
SDL_AudioSpec * obtained);
/**
* SDL Audio Device IDs.
* SDL Audio Device IDs.
*
* A successful call to SDL_OpenAudio() is always device id 1, and legacy
* SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
* always returns devices >= 2 on success. The legacy calls are good both
* for backwards compatibility and when you don't care about multiple,
* specific, or capture devices.
* A successful call to SDL_OpenAudio() is always device id 1, and legacy SDL
* audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
* always returns devices >= 2 on success. The legacy calls are good both for
* backwards compatibility and when you don't care about multiple, specific,
* or capture devices.
*/
typedef Uint32 SDL_AudioDeviceID;
@ -874,8 +877,9 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
Uint32 * audio_len);
/**
* Loads a WAV from a file.
* Compatibility convenience function.
* Loads a WAV from a file.
*
* Compatibility convenience function.
*/
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, 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;
#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_MostSignificantBitIndex32(Uint32 x)
{

7
include/SDL_blendmode.h
View file

@ -35,7 +35,7 @@ extern "C" {
#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
{
@ -60,7 +60,8 @@ typedef enum 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
{
@ -72,7 +73,7 @@ typedef enum 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
{

39
include/SDL_endian.h
View file

@ -180,6 +180,16 @@ extern __inline Uint16 SDL_Swap16(Uint16);
parm [ax] \
modify [ax];
#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_Swap16(Uint16 x)
{
@ -231,6 +241,16 @@ extern __inline Uint32 SDL_Swap32(Uint32);
parm [eax] \
modify [eax];
#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_Swap32(Uint32 x)
{
@ -276,6 +296,16 @@ extern __inline Uint64 SDL_Swap64(Uint64);
parm [eax edx] \
modify [eax edx];
#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_Swap64(Uint64 x)
{
@ -293,6 +323,15 @@ SDL_Swap64(Uint64 x)
#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_SwapFloat(float x)
{

167
include/SDL_events.h
View file

@ -167,7 +167,7 @@ typedef enum SDL_EventType
/* Internal events */
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()
*/
SDL_USEREVENT = 0x8000,
@ -179,7 +179,7 @@ typedef enum SDL_EventType
} SDL_EventType;
/**
* \brief Fields shared by every event
* Fields shared by every event
*/
typedef struct SDL_CommonEvent
{
@ -188,14 +188,14 @@ typedef struct SDL_CommonEvent
} SDL_CommonEvent;
/**
* \brief Display state change event data (event.display.*)
* Display state change event data (event.display.*)
*/
typedef struct SDL_DisplayEvent
{
Uint32 type; /**< ::SDL_DISPLAYEVENT */
Uint32 type; /**< SDL_DISPLAYEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 display; /**< The associated display index */
Uint8 event; /**< ::SDL_DisplayEventID */
Uint8 event; /**< SDL_DisplayEventID */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
@ -203,14 +203,14 @@ typedef struct SDL_DisplayEvent
} SDL_DisplayEvent;
/**
* \brief Window state change event data (event.window.*)
* Window state change event data (event.window.*)
*/
typedef struct SDL_WindowEvent
{
Uint32 type; /**< ::SDL_WINDOWEVENT */
Uint32 type; /**< SDL_WINDOWEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The associated window */
Uint8 event; /**< ::SDL_WindowEventID */
Uint8 event; /**< SDL_WindowEventID */
Uint8 padding1;
Uint8 padding2;
Uint8 padding3;
@ -219,14 +219,14 @@ typedef struct SDL_WindowEvent
} SDL_WindowEvent;
/**
* \brief Keyboard button event structure (event.key.*)
* Keyboard button event structure (event.key.*)
*/
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 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 padding2;
Uint8 padding3;
@ -234,12 +234,13 @@ typedef struct SDL_KeyboardEvent
} SDL_KeyboardEvent;
#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
{
Uint32 type; /**< ::SDL_TEXTEDITING */
Uint32 type; /**< SDL_TEXTEDITING */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
@ -248,12 +249,12 @@ typedef struct SDL_TextEditingEvent
} SDL_TextEditingEvent;
/**
* \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
* truncated if stored in the text buffer SDL_TextEditingEvent
* Extended keyboard text editing event structure (event.editExt.*) when text
* would be truncated if stored in the text buffer SDL_TextEditingEvent
*/
typedef struct SDL_TextEditingExtEvent
{
Uint32 type; /**< ::SDL_TEXTEDITING_EXT */
Uint32 type; /**< SDL_TEXTEDITING_EXT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
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 */
@ -262,23 +263,24 @@ typedef struct SDL_TextEditingExtEvent
} SDL_TextEditingExtEvent;
#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
{
Uint32 type; /**< ::SDL_TEXTINPUT */
Uint32 type; /**< SDL_TEXTINPUT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
} SDL_TextInputEvent;
/**
* \brief Mouse motion event structure (event.motion.*)
* Mouse motion event structure (event.motion.*)
*/
typedef struct SDL_MouseMotionEvent
{
Uint32 type; /**< ::SDL_MOUSEMOTION */
Uint32 type; /**< SDL_MOUSEMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@ -290,16 +292,16 @@ typedef struct SDL_MouseMotionEvent
} SDL_MouseMotionEvent;
/**
* \brief Mouse button event structure (event.button.*)
* Mouse button event structure (event.button.*)
*/
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 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
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 padding1;
Sint32 x; /**< X coordinate, relative to window */
@ -307,11 +309,11 @@ typedef struct SDL_MouseButtonEvent
} SDL_MouseButtonEvent;
/**
* \brief Mouse wheel event structure (event.wheel.*)
* Mouse wheel event structure (event.wheel.*)
*/
typedef struct SDL_MouseWheelEvent
{
Uint32 type; /**< ::SDL_MOUSEWHEEL */
Uint32 type; /**< SDL_MOUSEWHEEL */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
Uint32 windowID; /**< The window with mouse focus, if any */
Uint32 which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
@ -325,11 +327,11 @@ typedef struct SDL_MouseWheelEvent
} SDL_MouseWheelEvent;
/**
* \brief Joystick axis motion event structure (event.jaxis.*)
* Joystick axis motion event structure (event.jaxis.*)
*/
typedef struct SDL_JoyAxisEvent
{
Uint32 type; /**< ::SDL_JOYAXISMOTION */
Uint32 type; /**< SDL_JOYAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 axis; /**< The joystick axis index */
@ -341,11 +343,11 @@ typedef struct SDL_JoyAxisEvent
} SDL_JoyAxisEvent;
/**
* \brief Joystick trackball motion event structure (event.jball.*)
* Joystick trackball motion event structure (event.jball.*)
*/
typedef struct SDL_JoyBallEvent
{
Uint32 type; /**< ::SDL_JOYBALLMOTION */
Uint32 type; /**< SDL_JOYBALLMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 ball; /**< The joystick trackball index */
@ -357,18 +359,18 @@ typedef struct 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
{
Uint32 type; /**< ::SDL_JOYHATMOTION */
Uint32 type; /**< SDL_JOYHATMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 hat; /**< The joystick hat index */
Uint8 value; /**< The hat position value.
* \sa ::SDL_HAT_LEFTUP ::SDL_HAT_UP ::SDL_HAT_RIGHTUP
* \sa ::SDL_HAT_LEFT ::SDL_HAT_CENTERED ::SDL_HAT_RIGHT
* \sa ::SDL_HAT_LEFTDOWN ::SDL_HAT_DOWN ::SDL_HAT_RIGHTDOWN
* \sa SDL_HAT_LEFTUP SDL_HAT_UP SDL_HAT_RIGHTUP
* \sa SDL_HAT_LEFT SDL_HAT_CENTERED SDL_HAT_RIGHT
* \sa SDL_HAT_LEFTDOWN SDL_HAT_DOWN SDL_HAT_RIGHTDOWN
*
* Note that zero means the POV is centered.
*/
@ -377,46 +379,46 @@ typedef struct SDL_JoyHatEvent
} SDL_JoyHatEvent;
/**
* \brief Joystick button event structure (event.jbutton.*)
* Joystick button event structure (event.jbutton.*)
*/
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() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The joystick button index */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1;
Uint8 padding2;
} SDL_JoyButtonEvent;
/**
* \brief Joystick device event structure (event.jdevice.*)
* Joystick device event structure (event.jdevice.*)
*/
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() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
} SDL_JoyDeviceEvent;
/**
* \brief Joysick battery level change event structure (event.jbattery.*)
* Joysick battery level change event structure (event.jbattery.*)
*/
typedef struct SDL_JoyBatteryEvent
{
Uint32 type; /**< ::SDL_JOYBATTERYUPDATED */
Uint32 type; /**< SDL_JOYBATTERYUPDATED */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
SDL_JoystickPowerLevel level; /**< The joystick battery level */
} SDL_JoyBatteryEvent;
/**
* \brief Game controller axis motion event structure (event.caxis.*)
* Game controller axis motion event structure (event.caxis.*)
*/
typedef struct SDL_ControllerAxisEvent
{
Uint32 type; /**< ::SDL_CONTROLLERAXISMOTION */
Uint32 type; /**< SDL_CONTROLLERAXISMOTION */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
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
{
Uint32 type; /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
Uint32 type; /**< SDL_CONTROLLERBUTTONDOWN or SDL_CONTROLLERBUTTONUP */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_JoystickID which; /**< The joystick instance id */
Uint8 button; /**< The controller button (SDL_GameControllerButton) */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint8 state; /**< SDL_PRESSED or SDL_RELEASED */
Uint8 padding1;
Uint8 padding2;
} SDL_ControllerButtonEvent;
/**
* \brief Controller device event structure (event.cdevice.*)
* Controller device event structure (event.cdevice.*)
*/
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() */
Sint32 which; /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
} SDL_ControllerDeviceEvent;
/**
* \brief Game controller touchpad event structure (event.ctouchpad.*)
* Game controller touchpad event structure (event.ctouchpad.*)
*/
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() */
SDL_JoystickID which; /**< The joystick instance id */
Sint32 touchpad; /**< The index of the touchpad */
@ -469,24 +471,24 @@ typedef struct SDL_ControllerTouchpadEvent
} SDL_ControllerTouchpadEvent;
/**
* \brief Game controller sensor event structure (event.csensor.*)
* Game controller sensor event structure (event.csensor.*)
*/
typedef struct SDL_ControllerSensorEvent
{
Uint32 type; /**< ::SDL_CONTROLLERSENSORUPDATE */
Uint32 type; /**< SDL_CONTROLLERSENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
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 */
Uint64 timestamp_us; /**< The timestamp of the sensor reading in microseconds, if the hardware provides this information. */
} SDL_ControllerSensorEvent;
/**
* \brief Audio device event structure (event.adevice.*)
* Audio device event structure (event.adevice.*)
*/
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 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. */
@ -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
{
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() */
SDL_TouchID touchId; /**< The touch device id */
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
{
Uint32 type; /**< ::SDL_MULTIGESTURE */
Uint32 type; /**< SDL_MULTIGESTURE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */
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
{
Uint32 type; /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */
Uint32 type; /**< SDL_DOLLARGESTURE or SDL_DOLLARRECORD */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_TouchID touchId; /**< The touch device id */
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.*)
* 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.
* 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().
*
* If this event is enabled, you must free the filename in the event.
*/
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() */
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 */
@ -562,11 +566,11 @@ typedef struct SDL_DropEvent
/**
* \brief Sensor event structure (event.sensor.*)
* Sensor event structure (event.sensor.*)
*/
typedef struct SDL_SensorEvent
{
Uint32 type; /**< ::SDL_SENSORUPDATE */
Uint32 type; /**< SDL_SENSORUPDATE */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
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() */
@ -574,20 +578,20 @@ typedef struct SDL_SensorEvent
} SDL_SensorEvent;
/**
* \brief The "quit requested" event
* The "quit requested" event
*/
typedef struct SDL_QuitEvent
{
Uint32 type; /**< ::SDL_QUIT */
Uint32 type; /**< SDL_QUIT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
} SDL_QuitEvent;
/**
* \brief A user-defined event type (event.user.*)
* A user-defined event type (event.user.*)
*/
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 windowID; /**< The associated window if any */
Sint32 code; /**< User defined event code */
@ -600,20 +604,21 @@ struct SDL_SysWMmsg;
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
/**
* \brief A video driver dependent system event (event.syswm.*)
* This event is disabled by default, you can enable it with SDL_EventState()
* A video driver dependent system event (event.syswm.*)
*
* \note If you want to use this event, you should include SDL_syswm.h.
* This event is disabled by default, you can enable it with SDL_EventState()
*
* If you want to use this event, you should include SDL_syswm.h.
*/
typedef struct SDL_SysWMEvent
{
Uint32 type; /**< ::SDL_SYSWMEVENT */
Uint32 type; /**< SDL_SYSWMEVENT */
Uint32 timestamp; /**< In milliseconds, populated using SDL_GetTicks() */
SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
} SDL_SysWMEvent;
/**
* \brief General event structure
* General event structure
*/
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.
*
* \param userdata what was passed as `userdata` to SDL_SetEventFilter()
* or SDL_AddEventWatch, etc
* \param userdata what was passed as `userdata` to SDL_SetEventFilter() or
* SDL_AddEventWatch, etc
* \param event the event that triggered the callback
* \returns 1 to permit event to be added to the queue, and 0 to disallow
* it. When used with SDL_AddEventWatch, the return value is ignored.
* \returns 1 to permit event to be added to the queue, and 0 to disallow it.
* When used with SDL_AddEventWatch, the return value is ignored.
*
* \sa SDL_SetEventFilter
* \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
* 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
* application window. If the event filter returns 1, then the window will be
* closed, otherwise the window will remain open if possible.

27
include/SDL_gamecontroller.h
View file

@ -44,7 +44,7 @@ extern "C" {
* \file SDL_gamecontroller.h
*
* 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.
*
* If you would like to receive controller updates while the application
@ -86,7 +86,7 @@ typedef enum SDL_GameControllerBindType
} SDL_GameControllerBindType;
/**
* Get the SDL joystick layer binding for this controller button/axis mapping
* Get the SDL joystick layer binding for this controller button/axis mapping
*/
typedef struct SDL_GameControllerButtonBind
{
@ -166,9 +166,10 @@ typedef struct SDL_GameControllerButtonBind
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.
*/
#define SDL_GameControllerAddMappingsFromFile(file) SDL_GameControllerAddMappingsFromRW(SDL_RWFromFile(file, "rb"), 1)
@ -607,15 +608,17 @@ 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,
* and are centered within ~8000 of zero, though advanced UI will allow users to set
* or autodetect the dead zone, which varies between controllers.
* Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
* SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
* advanced UI will allow users to set or autodetect the dead zone, which
* varies between controllers.
*
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX
* (fully pressed) when reported by SDL_GameControllerGetAxis(). Note that this is not the
* same range that will be reported by the lower-level SDL_GetJoystickAxis().
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
* pressed) when reported by SDL_GameControllerGetAxis(). Note that this is
* not the same range that will be reported by the lower-level
* SDL_GetJoystickAxis().
*/
typedef enum SDL_GameControllerAxis
{
@ -724,7 +727,7 @@ extern DECLSPEC Sint16 SDLCALL
SDL_GameControllerGetAxis(SDL_GameController *gamecontroller, SDL_GameControllerAxis axis);
/**
* The list of buttons available from a controller
* The list of buttons available from a controller
*/
typedef enum SDL_GameControllerButton
{

32
include/SDL_guid.h
View file

@ -22,7 +22,7 @@
/**
* \file SDL_guid.h
*
* Include file for handling ::SDL_GUID values.
* Include file for handling SDL_GUID values.
*/
#ifndef SDL_guid_h_
@ -38,19 +38,19 @@ extern "C" {
#endif
/**
* An SDL_GUID is a 128-bit identifier for an input device that
* identifies that device across runs of SDL programs on the same
* platform. If the device is detached and then re-attached to a
* different port, or if the base system is rebooted, the device
* should still report the same GUID.
* An SDL_GUID is a 128-bit identifier for an input device that identifies
* that device across runs of SDL programs on the same platform.
*
* GUIDs are as precise as possible but are not guaranteed to
* distinguish physically distinct but equivalent devices. For
* example, two game controllers from the same vendor with the same
* product ID and revision may have the same GUID.
* If the device is detached and then re-attached to a different port, or if
* the base system is rebooted, the device should still report the same GUID.
*
* GUIDs may be platform-dependent (i.e., the same device may report
* different GUIDs on different operating systems).
* GUIDs are as precise as possible but are not guaranteed to distinguish
* physically distinct but equivalent devices. For example, two game
* controllers from the same vendor with the same product ID and revision may
* have the same GUID.
*
* GUIDs may be platform-dependent (i.e., the same device may report different
* GUIDs on different operating systems).
*/
typedef struct SDL_GUID {
Uint8 data[16];
@ -59,11 +59,11 @@ typedef struct SDL_GUID {
/* 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.
*
* \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 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);
/**
* 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
* an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful.
*
* \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.
*

590
include/SDL_haptic.h
View file

@ -26,18 +26,19 @@
* devices.
*
* The basic usage is as follows:
* - Initialize the subsystem (::SDL_INIT_HAPTIC).
* - Initialize the subsystem (SDL_INIT_HAPTIC).
* - Open a haptic device.
* - SDL_HapticOpen() to open from index.
* - SDL_HapticOpenFromJoystick() to open from an existing joystick.
* - Create an effect (::SDL_HapticEffect).
* - Create an effect (SDL_HapticEffect).
* - Upload the effect with SDL_HapticNewEffect().
* - Run the effect with SDL_HapticRunEffect().
* - (optional) Free the effect with SDL_HapticDestroyEffect().
* - Close the haptic device with SDL_HapticClose().
*
* \par Simple rumble example:
* \code
*
* ```c
* SDL_Haptic *haptic;
*
* // Open the device
@ -56,10 +57,11 @@
*
* // Clean up
* SDL_HapticClose( haptic );
* \endcode
* ```
*
* \par Complete example:
* \code
* Complete example:
*
* ```c
* int test_haptic( SDL_Joystick * joystick ) {
* SDL_Haptic *haptic;
* SDL_HapticEffect effect;
@ -101,7 +103,7 @@
*
* return 0; // Success
* }
* \endcode
* ```
*/
#ifndef SDL_haptic_h_
@ -154,31 +156,29 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* @{ */
/**
* \brief Constant effect supported.
* Constant effect supported.
*
* Constant haptic effect.
* Constant haptic effect.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#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.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#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
* \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.
* \sa SDL_HapticLeftRight
*/
#define SDL_HAPTIC_LEFTRIGHT (1u<<2)
@ -186,85 +186,85 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* #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.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#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.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#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.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/**
* \brief Ramp effect supported.
* Ramp effect supported.
*
* Ramp haptic effect.
* Ramp haptic effect.
*
* \sa SDL_HapticRamp
* \sa SDL_HapticRamp
*/
#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
* axes position.
* Condition haptic effect that simulates a spring. Effect is based on the
* axes position.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#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
* axes velocity.
* Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#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
* acceleration.
* Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#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
* axes movement.
* Condition haptic effect that simulates friction. Effect is based on the
* axes movement.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#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.
*/
#define SDL_HAPTIC_CUSTOM (1u<<11)
@ -273,39 +273,39 @@ typedef struct _SDL_Haptic SDL_Haptic;
/* 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.
*
* \sa SDL_HapticSetGain
* \sa SDL_HapticSetGain
*/
#define SDL_HAPTIC_GAIN (1u<<12)
/**
* \brief Device can set autocenter.
* Device can set autocenter.
*
* Device supports setting autocenter.
* Device supports setting autocenter.
*
* \sa SDL_HapticSetAutocenter
* \sa SDL_HapticSetAutocenter
*/
#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.
*
* \sa SDL_HapticGetEffectStatus
* \sa SDL_HapticGetEffectStatus
*/
#define SDL_HAPTIC_STATUS (1u<<14)
/**
* \brief Device can be paused.
* Device can be paused.
*
* Devices supports being paused.
* Devices supports being paused.
*
* \sa SDL_HapticPause
* \sa SDL_HapticUnpause
* \sa SDL_HapticPause
* \sa SDL_HapticUnpause
*/
#define SDL_HAPTIC_PAUSE (1u<<15)
@ -316,31 +316,33 @@ 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
/**
* \brief Uses cartesian coordinates for the direction.
* Uses cartesian coordinates for the direction.
*
* \sa SDL_HapticDirection
* \sa SDL_HapticDirection
*/
#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
/**
* \brief Use this value to play an effect on the steering wheel axis. This
* provides better compatibility across platforms and devices as SDL will guess
* the correct axis.
* \sa SDL_HapticDirection
* Use this value to play an effect on the steering wheel axis.
*
* This provides better compatibility across platforms and devices as SDL will
* guess the correct axis.
*
* \sa SDL_HapticDirection
*/
#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
*/
@ -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,
* instead of the direction in which the force is exerted.
* This is the direction where the force comes from, instead of the direction
* in which the force is exerted.
*
* Directions can be specified by:
* - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
* - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
* - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
* Directions can be specified by:
*
* Cardinal directions of the haptic device are relative to the positioning
* of the device. North is considered to be away from the user.
* - SDL_HAPTIC_POLAR : Specified by polar coordinates.
* - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
* - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
*
* 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
* Cardinal directions of the haptic device are relative to the positioning of
* the device. North is considered to be away from the user.
*
* 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:
* - North: 0 (0 degrees)
* - East: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - West: 27000 (270 degrees)
* The following diagram represents the cardinal directions:
*
* If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
* (X axis, Y axis and Z axis (with 3 axes)). ::SDL_HAPTIC_CARTESIAN uses
* the first three \c dir parameters. The cardinal directions would be:
* - North: 0,-1, 0
* - East: 1, 0, 0
* - South: 0, 1, 0
* - West: -1, 0, 0
*
* The Z axis represents the height of the effect if supported, otherwise
* it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you
* can use any multiple you want, only the direction matters.
*
* 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 towards (0, 0, 1) (device needs at least 3 axes).
* ```
* .--.
* |__| .-------.
* |=.| |.-----.|
* |--| || ||
* | | |'-----'|
* |__|~')_____('
* [ COMPUTER ]
*
*
* 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):
* \code
* 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)
* - East: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - West: 27000 (270 degrees)
*
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X
* axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first
* three `dir` parameters. The cardinal directions would be:
*
* - North: 0,-1, 0
* - East: 1, 0, 0
* - South: 0, 1, 0
* - West: -1, 0, 0
*
* The Z axis represents the height of the effect if supported, otherwise it's
* unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can
* use any multiple you want, only the direction matters.
*
* If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The
* first two `dir` parameters are used. The `dir` parameters are as follows
* (all values are in hundredths of degrees):
*
* - Degrees from (1, 0) rotated towards (0, 1).
* - Degrees towards (0, 0, 1) (device needs at least 3 axes).
*
* 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):
*
* ```c
* SDL_HapticDirection direction;
*
* // Cartesian directions
@ -447,14 +454,14 @@ typedef struct _SDL_Haptic SDL_Haptic;
* // Spherical coordinates
* direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
* direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
* \endcode
* ```
*
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
* \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
* \sa SDL_HapticNumAxes
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
* \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
* \sa SDL_HapticNumAxes
*/
typedef struct SDL_HapticDirection
{
@ -464,20 +471,20 @@ 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
* to the joystick.
* A constant effect applies a constant force in the specified direction to
* the joystick.
*
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticConstant
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_CONSTANT */
Uint16 type; /**< SDL_HAPTIC_CONSTANT */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@ -499,68 +506,71 @@ typedef struct 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:
* - ::SDL_HAPTIC_SINE
* - ::SDL_HAPTIC_LEFTRIGHT
* - ::SDL_HAPTIC_TRIANGLE
* - ::SDL_HAPTIC_SAWTOOTHUP
* - ::SDL_HAPTIC_SAWTOOTHDOWN
* The struct handles the following effects:
*
* 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.
* - SDL_HAPTIC_SINE
* - SDL_HAPTIC_SQUARE
* - SDL_HAPTIC_TRIANGLE
* - SDL_HAPTIC_SAWTOOTHUP
* - SDL_HAPTIC_SAWTOOTHDOWN
*
* Phase is given by hundredth of a degree meaning that giving the phase a value
* of 9000 will displace it 25% of its period. Here are sample values:
* - 0: No phase displacement.
* - 9000: Displaced 25% of its period.
* - 18000: Displaced 50% of its period.
* - 27000: Displaced 75% of its period.
* - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
* 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.
*
* Examples:
* \verbatim
SDL_HAPTIC_SINE
__ __ __ __
/ \ / \ / \ /
/ \__/ \__/ \__/
SDL_HAPTIC_SQUARE
__ __ __ __ __
| | | | | | | | | |
| |__| |__| |__| |__| |
SDL_HAPTIC_TRIANGLE
/\ /\ /\ /\ /\
/ \ / \ / \ / \ /
/ \/ \/ \/ \/
SDL_HAPTIC_SAWTOOTHUP
/| /| /| /| /| /| /|
/ | / | / | / | / | / | / |
/ |/ |/ |/ |/ |/ |/ |
SDL_HAPTIC_SAWTOOTHDOWN
\ |\ |\ |\ |\ |\ |\ |
\ | \ | \ | \ | \ | \ | \ |
\| \| \| \| \| \| \|
\endverbatim
* Phase is given by hundredth of a degree meaning that giving the phase a
* value of 9000 will displace it 25% of its period. Here are sample values:
*
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_LEFTRIGHT
* \sa SDL_HAPTIC_TRIANGLE
* \sa SDL_HAPTIC_SAWTOOTHUP
* \sa SDL_HAPTIC_SAWTOOTHDOWN
* \sa SDL_HapticEffect
* - 0: No phase displacement.
* - 9000: Displaced 25% of its period.
* - 18000: Displaced 50% of its period.
* - 27000: Displaced 75% of its period.
* - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
*
* Examples:
*
* ```
* SDL_HAPTIC_SINE
* __ __ __ __
* / \ / \ / \ /
* / \__/ \__/ \__/
*
* SDL_HAPTIC_SQUARE
* __ __ __ __ __
* | | | | | | | | | |
* | |__| |__| |__| |__| |
*
* SDL_HAPTIC_TRIANGLE
* /\ /\ /\ /\ /\
* / \ / \ / \ / \ /
* / \/ \/ \/ \/
*
* SDL_HAPTIC_SAWTOOTHUP
* /| /| /| /| /| /| /|
* / | / | / | / | / | / | / |
* / |/ |/ |/ |/ |/ |/ |
*
* SDL_HAPTIC_SAWTOOTHDOWN
* \ |\ |\ |\ |\ |\ |\ |
* \ | \ | \ | \ | \ | \ | \ |
* \| \| \| \| \| \| \|
* ```
*
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_LEFTRIGHT
* \sa SDL_HAPTIC_TRIANGLE
* \sa SDL_HAPTIC_SAWTOOTHUP
* \sa SDL_HAPTIC_SAWTOOTHDOWN
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticPeriodic
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_LEFTRIGHT,
::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
::SDL_HAPTIC_SAWTOOTHDOWN */
Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_LEFTRIGHT,
SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
SDL_HAPTIC_SAWTOOTHDOWN */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@ -585,34 +595,35 @@ typedef struct 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:
* - ::SDL_HAPTIC_SPRING: Effect based on axes position.
* - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
* The struct handles the following effects:
*
* Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first
* refers to the X axis, the second refers to the Y axis and the third
* refers to the Z axis. The right terms refer to the positive side of the
* axis and the left terms refer to the negative side of the axis. Please
* refer to the ::SDL_HapticDirection diagram for which side is positive and
* which is negative.
* - SDL_HAPTIC_SPRING: Effect based on axes position.
* - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - SDL_HAPTIC_FRICTION: Effect based on axes movement.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
* \sa SDL_HAPTIC_INERTIA
* \sa SDL_HAPTIC_FRICTION
* \sa SDL_HapticEffect
* Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first
* refers to the X axis, the second refers to the Y axis and the third refers
* to the Z axis. The right terms refer to the positive side of the axis and
* the left terms refer to the negative side of the axis. Please refer to the
* SDL_HapticDirection diagram for which side is positive and which is
* negative.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
* \sa SDL_HAPTIC_INERTIA
* \sa SDL_HAPTIC_FRICTION
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticCondition
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */
/* Replay */
@ -633,22 +644,22 @@ typedef struct 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.
* It augments in linear fashion. If you use attack and fade with a ramp
* the effects get added to the ramp effect making the effect become
* quadratic instead of linear.
* The ramp effect starts at start strength and ends at end strength. It
* augments in linear fashion. If you use attack and fade with a ramp the
* effects get added to the ramp effect making the effect become quadratic
* instead of linear.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticRamp
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_RAMP */
Uint16 type; /**< SDL_HAPTIC_RAMP */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@ -671,9 +682,9 @@ typedef struct 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
* motors, commonly found in modern game controllers. The small (right) motor
@ -685,7 +696,7 @@ typedef struct SDL_HapticRamp
typedef struct SDL_HapticLeftRight
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */
Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */
/* Replay */
Uint32 length; /**< Duration of the effect in milliseconds. */
@ -696,24 +707,24 @@ typedef struct 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
* application can define its exact shape. You will have to allocate the
* data yourself. Data should consist of channels * samples Uint16 samples.
* A custom force feedback effect is much like a periodic effect, where the
* application can define its exact shape. You will have to allocate the data
* yourself. Data should consist of channels * samples Uint16 samples.
*
* If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes.
* If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes.
*
* \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticCustom
{
/* Header */
Uint16 type; /**< ::SDL_HAPTIC_CUSTOM */
Uint16 type; /**< SDL_HAPTIC_CUSTOM */
SDL_HapticDirection direction; /**< Direction of the effect. */
/* Replay */
@ -738,27 +749,28 @@ typedef struct 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.
* Time values unless specified otherwise are in milliseconds.
* All values max at 32767 (0x7FFF). Signed values also can be negative. Time
* values unless specified otherwise are in milliseconds.
*
* You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767
* value. Neither delay, interval, attack_length nor fade_length support
* ::SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
* You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
* Neither delay, interval, attack_length nor fade_length support
* SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
*
* Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
* ::SDL_HAPTIC_INFINITY.
* Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
* SDL_HAPTIC_INFINITY.
*
* Button triggers may not be supported on all devices, it is advised to not
* use them if possible. Buttons start at index 1 instead of index 0 like
* the joystick.
* Button triggers may not be supported on all devices, it is advised to not
* use them if possible. Buttons start at index 1 instead of index 0 like the
* joystick.
*
* If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used.
* If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used.
*
* Common parts:
* \code
* Common parts:
*
* ```c
* // Replay - All effects have this
* Uint32 length; // Duration of effect (ms).
* Uint16 delay; // Delay before starting effect.
@ -772,39 +784,39 @@ typedef struct SDL_HapticCustom
* Uint16 attack_level; // Level at the start of the attack.
* Uint16 fade_length; // Duration of the fade out (ms).
* 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
^
|
| effect level --> _________________
| / \
| / \
| / \
| / \
| attack_level --> | \
| | | <--- fade_level
|
+--------------------------------------------------> Time
[--] [---]
attack_length fade_length
[------------------][-----------------------]
delay length
\endverbatim
* ```
* Strength
* ^
* |
* | effect level --> _________________
* | / \
* | / \
* | / \
* | / \
* | attack_level --> | \
* | | | <--- fade_level
* |
* +--------------------------------------------------> Time
* [--] [---]
* attack_length fade_length
*
* Note either the attack_level or the fade_level may be above the actual
* effect level.
* [------------------][-----------------------]
* delay length
* ```
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition
* \sa SDL_HapticRamp
* \sa SDL_HapticLeftRight
* \sa SDL_HapticCustom
* Note either the attack_level or the fade_level may be above the actual
* effect level.
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition
* \sa SDL_HapticRamp
* \sa SDL_HapticLeftRight
* \sa SDL_HapticCustom
*/
typedef union SDL_HapticEffect
{

5
include/SDL_hidapi.h
View file

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

3000
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
*
* 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.
*
* 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;
/**
* This is a unique ID for a joystick for the time it is connected to the system,
* and is never reused for the lifetime of the application. If the joystick is
* disconnected and reconnected, it will get a new ID.
* This is a unique ID for a joystick for the time it is connected to the
* 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.
* 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;
@ -358,8 +360,10 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtual(SDL_JoystickType type,
/**
* 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()
* All other elements of this structure are optional and can be left 0.
* The caller must zero the structure and then initialize the version with
* `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to
* SDL_JoystickAttachVirtualEx() All other elements of this structure are
* optional and can be left 0.
*
* \sa SDL_JoystickAttachVirtualEx
*/
@ -390,7 +394,7 @@ typedef struct 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

9
include/SDL_keyboard.h
View file

@ -40,14 +40,15 @@ extern "C" {
#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
{
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_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */
SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */
Uint16 mod; /**< current key modifiers */
Uint32 unused;
} SDL_Keysym;

16
include/SDL_keycode.h
View file

@ -32,15 +32,15 @@
#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
* layout of the keyboard. These values include Unicode values representing
* the unmodified character that would be generated by pressing the key, or
* an SDLK_* constant for those keys that do not generate characters.
* Values of this type are used to represent keyboard keys using the current
* layout of the keyboard. These values include Unicode values representing
* the unmodified character that would be generated by pressing the key, or an
* SDLK_* constant for those keys that do not generate characters.
*
* A special exception is the number keys at the top of the keyboard which
* map to SDLK_0...SDLK_9 on AZERTY layouts.
* A special exception is the number keys at the top of the keyboard which map
* to SDLK_0...SDLK_9 on AZERTY layouts.
*/
typedef Sint32 SDL_Keycode;
@ -327,7 +327,7 @@ typedef enum 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
{

15
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
/**
* \brief The predefined log categories
* The predefined log categories
*
* By default the application category is enabled at the INFO level,
* the assert category is enabled at the WARN level, test is enabled
* at the VERBOSE level and all other categories are enabled at the
* ERROR level.
* By default the application category is enabled at the INFO level, the
* assert category is enabled at the WARN level, test is enabled at the
* VERBOSE level and all other categories are enabled at the ERROR level.
*/
typedef enum SDL_LogCategory
{
@ -97,7 +96,7 @@ typedef enum SDL_LogCategory
} SDL_LogCategory;
/**
* \brief The predefined log priorities
* The predefined log priorities
*/
typedef enum SDL_LogPriority
{

6
include/SDL_main.h
View file

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

10
include/SDL_messagebox.h
View file

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

4
include/SDL_metal.h
View file

@ -37,9 +37,9 @@ extern "C" {
#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;

10
include/SDL_mouse.h
View file

@ -41,7 +41,7 @@ extern "C" {
typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
/**
* \brief Cursor types for SDL_CreateSystemCursor().
* Cursor types for SDL_CreateSystemCursor().
*/
typedef enum SDL_SystemCursor
{
@ -61,7 +61,7 @@ typedef enum SDL_SystemCursor
} SDL_SystemCursor;
/**
* \brief Scroll direction types for the Scroll event
* Scroll direction types for the Scroll event
*/
typedef enum SDL_MouseWheelDirection
{
@ -437,9 +437,9 @@ extern DECLSPEC int SDLCALL SDL_ShowCursor(int toggle);
/**
* Used as a mask when testing buttons in buttonstate.
*
* - Button 1: Left mouse button
* - Button 2: Middle mouse button
* - Button 3: Right mouse button
* - Button 1: Left mouse button
* - Button 2: Middle mouse button
* - Button 3: Right mouse button
*/
#define SDL_BUTTON(X) (1 << ((X)-1))
#define SDL_BUTTON_LEFT 1

6
include/SDL_mutex.h
View file

@ -112,13 +112,13 @@ extern "C" {
#endif
/**
* Synchronization functions which can time out return this value
* if they time out.
* Synchronization functions which can time out return this value if they time
* out.
*/
#define SDL_MUTEX_TIMEDOUT 1
/**
* This is the timeout value which corresponds to never time out.
* This is the timeout value which corresponds to never time out.
*/
#define SDL_MUTEX_MAXWAIT (~(Uint32)0)

32
include/SDL_pixels.h
View file

@ -320,9 +320,10 @@ typedef enum
} SDL_PixelFormatEnum;
/**
* The bits of this structure can be directly reinterpreted as an integer-packed
* color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
* on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
* The bits of this structure can be directly reinterpreted as an
* integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format
* (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and
* SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
*/
typedef struct SDL_Color
{
@ -342,7 +343,30 @@ typedef struct 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
{

2
include/SDL_power.h
View file

@ -37,7 +37,7 @@ extern "C" {
#endif
/**
* The basic state for the system's power supply.
* The basic state for the system's power supply.
*/
typedef enum SDL_PowerState
{

6
include/SDL_quit.h
View file

@ -34,7 +34,7 @@
/**
* \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.
* 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
@ -42,8 +42,8 @@
*
* SDL_Init() installs signal handlers for SIGINT (keyboard interrupt)
* and SIGTERM (system termination request), if handlers do not already
* 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
* 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
* handler in your application will override the default generation of
* quit events for that signal.
*

4
include/SDL_render.h
View file

@ -78,7 +78,7 @@ typedef enum SDL_RendererFlags
typedef struct SDL_RendererInfo
{
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 texture_formats[16]; /**< The available texture formats */
int max_texture_width; /**< The maximum texture width */
@ -86,7 +86,7 @@ typedef struct SDL_RendererInfo
} SDL_RendererInfo;
/**
* Vertex structure
* Vertex structure
*/
typedef struct SDL_Vertex
{

10
include/SDL_rwops.h
View file

@ -57,7 +57,7 @@ typedef struct SDL_RWops
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
*
* \return the final offset in the data stream, or -1 on error.
@ -66,8 +66,8 @@ typedef struct SDL_RWops
int whence);
/**
* Read up to \c maxnum objects each of size \c size from the data
* stream to the area pointed at by \c ptr.
* Read up to `maxnum` objects each of size `size` from the data
* stream to the area pointed at by `ptr`.
*
* \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);
/**
* Write exactly \c num objects each of size \c size from the area
* pointed at by \c ptr to data stream.
* Write exactly `num` objects each of size `size` from the area
* pointed at by `ptr` to data stream.
*
* \return the number of objects written, or 0 at error or end of file.
*/

12
include/SDL_scancode.h
View file

@ -31,14 +31,14 @@
#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
* in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the
* SDL_Event structure.
* Values of this type are used to represent keyboard keys, among other places
* in the SDL_Keysym::scancode key.keysym.scancode field of the SDL_Event
* structure.
*
* The values in this enumeration are based on the USB usage page standard:
* https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
* The values in this enumeration are based on the USB usage page standard:
* https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
*/
typedef enum SDL_Scancode
{

108
include/SDL_sensor.h
View file

@ -44,7 +44,7 @@ extern "C" {
* \brief SDL_sensor.h
*
* 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.
*/
@ -52,21 +52,67 @@ struct _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,
* and is never reused for the lifetime of the application.
* This is a unique ID for a sensor for the time it is connected to the
* 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;
/* The different sensors defined by SDL
/**
* The different sensors defined by SDL.
*
* 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
*
* 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_UNKNOWN, /**< Unknown sensor type */
@ -79,53 +125,15 @@ typedef enum
} SDL_SensorType;
/**
* Accelerometer sensor
* A constant to represent standard gravity for accelerometer sensors.
*
* 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 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()
* 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.
*/
#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 */
/**

18
include/SDL_shape.h
View file

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

42
include/SDL_stdinc.h
View file

@ -129,15 +129,19 @@ void *alloca(size_t);
#endif
/**
* The number of elements in an array.
* The number of elements in an array.
*/
#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
#define SDL_TABLESIZE(table) SDL_arraysize(table)
/**
* 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
@ -185,50 +189,56 @@ typedef enum
#endif
/**
* \brief A signed 8-bit integer type.
* A signed 8-bit integer type.
*/
#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
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_MIN_UINT8 ((Uint8)0x00) /* 0 */
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_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
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_MIN_UINT16 ((Uint16)0x0000) /* 0 */
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_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
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_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
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_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
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_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
* and return 0.
* If a * b would overflow, return -1.
*
* Otherwise store a * b via ret and return 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
/**
* If a + b would overflow, return -1. Otherwise store a + b via ret
* and return 0.
* If a + b would overflow, return -1.
*
* Otherwise store a + b via ret and return 0.
*
* \since This function is available since SDL 2.24.0.
*/

120
include/SDL_surface.h
View file

@ -22,7 +22,7 @@
/**
* \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_
@ -43,7 +43,7 @@ extern "C" {
/**
* \name Surface flags
*
* These are the currently supported flags for the ::SDL_Surface.
* These are the currently supported flags for the SDL_Surface.
*
* \internal
* Used internally (read-only).
@ -57,17 +57,17 @@ extern "C" {
/* @} *//* Surface flags */
/**
* Evaluates to true if the surface needs to be locked before access.
* Evaluates to true if the surface needs to be locked before access.
*/
#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
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,
* which, if not NULL, contains the raw pixel data for the surface.
* This structure should be treated as read-only, except for `pixels`, which,
* if not NULL, contains the raw pixel data for the 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);
/**
* \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
{
@ -378,9 +378,9 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
(SDL_Surface * surface, SDL_RWops * dst, int freedst);
/**
* Save a surface to a file.
* Save a surface to a file.
*
* Convenience macro.
* Convenience macro.
*/
#define SDL_SaveBMP(surface, file) \
SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
@ -801,62 +801,64 @@ extern DECLSPEC int SDLCALL SDL_FillRects
(SDL_Surface * dst, const SDL_Rect * rects, int count, Uint32 color);
/* !!! 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
* the same size. If either \c srcrect or \c dstrect are NULL, the entire
* surface (\c src or \c dst) is copied. The final blit rectangles are saved
* in \c srcrect and \c dstrect after all clipping is performed.
* This assumes that the source and destination rectangles are the same size.
* If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
* `dst`) is copied. The final blit rectangles are saved in `srcrect` and
* `dstrect` after all clipping is performed.
*
* \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 are
* defined as follows:
*
* The blit semantics for surfaces with and without blending and colorkey
* are defined as follows:
* \verbatim
RGBA->RGB:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source alpha-channel and per-surface alpha)
SDL_SRCCOLORKEY ignored.
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB.
if SDL_SRCCOLORKEY set, only copy the pixels matching the
RGB values of the source color key, ignoring alpha in the
comparison.
RGB->RGBA:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB, set destination alpha to source per-surface alpha value.
both:
if SDL_SRCCOLORKEY set, only copy the pixels matching the
source color key.
RGBA->RGBA:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source alpha-channel and per-surface alpha)
SDL_SRCCOLORKEY ignored.
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy all of RGBA to the destination.
if SDL_SRCCOLORKEY set, only copy the pixels matching the
RGB values of the source color key, ignoring alpha in the
comparison.
RGB->RGB:
Source surface blend mode set to SDL_BLENDMODE_BLEND:
alpha-blend (using the source per-surface alpha)
Source surface blend mode set to SDL_BLENDMODE_NONE:
copy RGB.
both:
if SDL_SRCCOLORKEY set, only copy the pixels matching the
source color key.
\endverbatim
* ```
* 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.
*
* You should call SDL_BlitSurface() unless you know exactly how SDL
* blitting works internally and how to use the other blit functions.
* 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

10
include/SDL_system.h
View file

@ -356,9 +356,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
/**
See the official Android developer guide for more information:
http://developer.android.com/guide/topics/data/data-storage.html
*/
* See the official Android developer guide for more information:
* http://developer.android.com/guide/topics/data/data-storage.html
*/
#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
@ -470,7 +470,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
#ifdef __WINRT__
/**
* \brief WinRT / Windows Phone path types
* WinRT / Windows Phone path types
*/
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
{

13
include/SDL_syswm.h
View file

@ -36,7 +36,7 @@
/*
* \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
* an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_EventState().
@ -130,8 +130,9 @@ extern "C" {
#endif
#if !defined(SDL_PROTOTYPES_ONLY)
/**
* These are the various supported windowing subsystems
* These are the various supported windowing subsystems
*/
typedef enum SDL_SYSWM_TYPE
{
@ -153,7 +154,7 @@ typedef enum SDL_SYSWM_TYPE
} SDL_SYSWM_TYPE;
/**
* The custom event structure.
* The custom event structure.
*/
struct SDL_SysWMmsg
{
@ -219,10 +220,10 @@ 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
* low level system it is using, and will be one of SDL_SYSWM_TYPE.
* When this structure is returned, it holds information about which low level
* system it is using, and will be one of SDL_SYSWM_TYPE.
*/
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.
*/
/**
/*
* \file SDL_test.h
*
* 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.
*/
/**
/*
* \file SDL_test_assert.h
*
* Include file for SDL test framework.
@ -42,17 +42,17 @@
extern "C" {
#endif
/**
/*
* \brief Fails the assert.
*/
#define ASSERT_FAIL 0
/**
/*
* \brief Passes the assert.
*/
#define ASSERT_PASS 1
/**
/*
* \brief Assert that logs and break execution flow on failures.
*
* \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);
/**
/*
* \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).
@ -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);
/**
/*
* \brief Explicitly pass without checking an assertion condition. Updates assertion counter.
*
* \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);
/**
/*
* \brief Resets the assert summary counters to zero.
*/
void SDLTest_ResetAssertSummary(void);
/**
/*
* \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR.
*/
void SDLTest_LogAssertSummary(void);
/**
/*
* \brief Converts the current assert summary state to a test result.
*
* \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.
*/
/**
/*
* \file SDL_test_common.h
*
* Include file for SDL test framework.
@ -129,7 +129,7 @@ extern "C" {
/* Function prototypes */
/**
/*
* \brief Parse command line parameters and create common state.
*
* \param argv Array of command line parameters
@ -139,7 +139,7 @@ extern "C" {
*/
SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
/**
/*
* \brief Process one common argument.
*
* \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);
/**
/*
* \brief Logs command line usage info.
*
* 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);
/**
/*
* \brief Returns common usage information
*
* 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);
/**
/*
* \brief Open test window.
*
* \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);
/**
/*
* \brief Easy argument handling when test app doesn't need any custom args.
*
* \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);
/**
/*
* \brief Common event handler for test windows.
*
* \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);
/**
/*
* \brief Close 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);
/**
/*
* \brief Draws various window information (position, size, etc.) to the renderer.
*
* \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.
*/
/**
/*
* \file SDL_test_compare.h
*
* Include file for SDL test framework.
@ -46,7 +46,7 @@
extern "C" {
#endif
/**
/*
* \brief Compares a surface and with reference image data for equality
*
* \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.
*/
/**
/*
* \file SDL_test_font.h
*
* Include file for SDL test framework.
@ -41,7 +41,7 @@ extern "C" {
#define FONT_CHARACTER_SIZE 8
#define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2)
/**
/*
* \brief Draw a string in the currently set font.
*
* \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);
/**
/*
* \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.
@ -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);
/**
/*
* \brief Data used for multi-line text output
*/
typedef struct SDLTest_TextWindow
@ -78,7 +78,7 @@ typedef struct SDLTest_TextWindow
char **lines;
} SDLTest_TextWindow;
/**
/*
* \brief Create a multi-line text output 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);
/**
/*
* \brief Display a multi-line text output window
*
* 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);
/**
/*
* \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
@ -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);
/**
/*
* \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
@ -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);
/**
/*
* \brief Clear the text in a multi-line 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);
/**
/*
* \brief Free the storage associated with a multi-line 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);
/**
/*
* \brief Cleanup textures used by font drawing functions.
*/
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.
*/
/**
/*
* \file SDL_test_fuzzer.h
*
* Include file for SDL test framework.
@ -48,13 +48,13 @@ extern "C" {
*/
/**
/*
* \file
* Note: The fuzzer implementation uses a static instance of random context
* internally which makes it thread-UNsafe.
*/
/**
/*
* Initializes the fuzzer for a 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);
/**
/*
* Returns a random Uint8
*
* \returns a generated integer
*/
Uint8 SDLTest_RandomUint8(void);
/**
/*
* Returns a random Sint8
*
* \returns a generated signed integer
@ -78,14 +78,14 @@ Uint8 SDLTest_RandomUint8(void);
Sint8 SDLTest_RandomSint8(void);
/**
/*
* Returns a random Uint16
*
* \returns a generated integer
*/
Uint16 SDLTest_RandomUint16(void);
/**
/*
* Returns a random Sint16
*
* \returns a generated signed integer
@ -93,7 +93,7 @@ Uint16 SDLTest_RandomUint16(void);
Sint16 SDLTest_RandomSint16(void);
/**
/*
* Returns a random integer
*
* \returns a generated integer
@ -101,14 +101,14 @@ Sint16 SDLTest_RandomSint16(void);
Sint32 SDLTest_RandomSint32(void);
/**
/*
* Returns a random positive integer
*
* \returns a generated integer
*/
Uint32 SDLTest_RandomUint32(void);
/**
/*
* Returns random Uint64.
*
* \returns a generated integer
@ -116,36 +116,36 @@ Uint32 SDLTest_RandomUint32(void);
Uint64 SDLTest_RandomUint64(void);
/**
/*
* Returns random Sint64.
*
* \returns a generated signed integer
*/
Sint64 SDLTest_RandomSint64(void);
/**
/*
* \returns a random float in range [0.0 - 1.0]
*/
float SDLTest_RandomUnitFloat(void);
/**
/*
* \returns a random double in range [0.0 - 1.0]
*/
double SDLTest_RandomUnitDouble(void);
/**
/*
* \returns a random float.
*
*/
float SDLTest_RandomFloat(void);
/**
/*
* \returns a random double.
*
*/
double SDLTest_RandomDouble(void);
/**
/*
* Returns a random boundary value for Uint8 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Uint16 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Uint32 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Uint64 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Sint8 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Sint16 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Sint32 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns a random boundary value for Sint64 within the given boundaries.
* Boundaries are inclusive, see the usage examples below. If validDomain
* 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);
/**
/*
* Returns integer in range [min, max] (inclusive).
* Min and max values can be negative values.
* 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);
/**
/*
* Generates random null-terminated string. The minimum length for
* the string is 1 character, maximum length for the string is 255
* 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);
/**
/*
* Generates random null-terminated string. The maximum length for
* the string is defined by the maxLength parameter.
* String can contain ASCII characters from 32 to 126.
@ -355,7 +355,7 @@ char * SDLTest_RandomAsciiString(void);
char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
/**
/*
* Generates random null-terminated string. The length for
* the string is defined by the size parameter.
* String can contain ASCII characters from 32 to 126.
@ -368,7 +368,8 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
*/
char * SDLTest_RandomAsciiStringOfSize(int size);
/**
/*
* Get the invocation count for the fuzzer since last ...FuzzerInit.
*
* \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.
*/
/**
/*
* \file SDL_test_harness.h
*
* 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) */
typedef void (*SDLTest_TestCaseTearDownFp)(void *arg);
/**
/*
* Holds information about a single test case.
*/
typedef struct SDLTest_TestCaseReference {
@ -83,7 +83,7 @@ typedef struct SDLTest_TestCaseReference {
int enabled;
} SDLTest_TestCaseReference;
/**
/*
* Holds information about a test suite (multiple test cases).
*/
typedef struct SDLTest_TestSuiteReference {
@ -98,7 +98,7 @@ typedef struct SDLTest_TestSuiteReference {
} SDLTest_TestSuiteReference;
/**
/*
* \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.
@ -109,7 +109,7 @@ typedef struct SDLTest_TestSuiteReference {
*/
char *SDLTest_GenerateRunSeed(const int length);
/**
/*
* \brief Execute a test suite using the given run seed and execution key.
*
* \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.
*/
/**
/*
* \file SDL_test_images.h
*
* Include file for SDL test framework.
@ -44,7 +44,7 @@
extern "C" {
#endif
/**
/*
*Type for test images.
*/
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.
*/
/**
/*
* \file SDL_test_log.h
*
* Include file for SDL test framework.
@ -42,14 +42,14 @@
extern "C" {
#endif
/**
/*
* \brief Prints given message with a timestamp in the TEST category and INFO priority.
*
* \param fmt Message to be logged
*/
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.
*
* \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.
*/
/**
/*
* \file SDL_test_md5.h
*
* Include file for SDL test framework.
@ -77,7 +77,7 @@ extern "C" {
/* ---------- Function Prototypes ------------- */
/**
/*
* \brief initialize the context
*
* \param mdContext pointer to context variable
@ -89,7 +89,7 @@ extern "C" {
void SDLTest_Md5Init(SDLTest_Md5Context * mdContext);
/**
/*
* \brief update digest from variable length data
*
* \param mdContext pointer to context variable
@ -105,7 +105,7 @@ extern "C" {
unsigned int inLen);
/**
/*
* \brief complete digest computation
*
* \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.
*/
/**
/*
* \file SDL_test_memory.h
*
* Include file for SDL test framework.
@ -37,14 +37,14 @@ extern "C" {
#endif
/**
/*
* \brief Start tracking SDL memory allocations
*
* \note This should be called before any other SDL functions for complete tracking coverage
*/
int SDLTest_TrackAllocations(void);
/**
/*
* \brief Print a log of any outstanding allocations
*
* \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.
*/
/**
/*
* \file SDL_test_random.h
*
* Include file for SDL test framework.
@ -67,7 +67,7 @@ extern "C" {
/* --- Function prototypes */
/**
/*
* \brief Initialize random number generator with two integers.
*
* 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,
unsigned int ci);
/**
/*
* \brief Initialize random number generator based on current system time.
*
* \param rndContext pointer to context structure
@ -90,7 +90,7 @@ extern "C" {
void SDLTest_RandomInitTime(SDLTest_RandomContext *rndContext);
/**
/*
* \brief Initialize random number generator based on current system time.
*
* Note: ...RandomInit() or ...RandomInitTime() must have been called

14
include/SDL_thread.h
View file

@ -63,14 +63,16 @@ typedef unsigned long SDL_threadID;
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.
* Code which attempts to control thread state related to priority should be aware
* that calling SDL_SetThreadPriority may alter such state.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior.
* SDL will make system changes as necessary in order to apply the thread
* priority. Code which attempts to control thread state related to priority
* should be aware that calling SDL_SetThreadPriority may alter such state.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this
* behavior.
*
* \note On many systems you require special privileges to set high or time critical priority.
* On many systems you require special privileges to set high or time critical
* priority.
*/
typedef enum SDL_ThreadPriority {
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
* that problem.
*
* For example, with SDL_GetTicks(), if you want to wait 100 ms, you could
* do this:
* For example, with SDL_GetTicks(), if you want to wait 100 ms, you could do
* this:
*
* ```c
* 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
* than 2^31 so take care when using the above kind of code
* with large timeout delays (tens of days).
* Note that this does not handle tick differences greater than 2^31 so take
* care when using the above kind of code with large timeout delays (tens of
* days).
*/
#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.
*
* The callback function is passed the current timer interval and returns
* the next timer interval. If the returned value is the same as the one
* passed in, the periodic alarm continues, otherwise a new alarm is
* scheduled. If the callback returns 0, the periodic alarm is cancelled.
* The callback function is passed the current timer interval and returns the
* next timer interval. If the returned value is the same as the one passed
* in, the periodic alarm continues, otherwise a new alarm is scheduled. If
* the callback returns 0, the periodic alarm is cancelled.
*/
typedef Uint32 (SDLCALL * SDL_TimerCallback) (Uint32 interval, void *param);

51
include/SDL_version.h
View file

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

96
include/SDL_video.h
View file

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