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

include: Add `\since` to all documentation that was missing it.

main
Ryan C. Gordon 2024-04-11 13:34:29 -04:00
parent db39de7f63
commit 0df988389c
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
33 changed files with 330 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
build-scripts/wikiheaders.pl
View File

@ -1454,6 +1454,28 @@ if ($copy_direction == 1) { # --copy-to-headers
# Make sure this ends with a double-newline. # Make sure this ends with a double-newline.
$sections{'See Also'} .= "\n" if defined $sections{'See Also'}; $sections{'See Also'} .= "\n" if defined $sections{'See Also'};
if (0) { # !!! FIXME: this was a useful hack, but this needs to be generalized if we're going to do this always.
# Plug in a \since section if one wasn't listed.
if (not defined $sections{'Version'}) {
my $symtypename;
if ($symtype == 1) {
$symtypename = 'function';
} elsif ($symtype == 2) {
$symtypename = 'macro';
} elsif ($symtype == 3) {
$symtypename = 'struct';
} elsif ($symtype == 4) {
$symtypename = 'enum';
} elsif ($symtype == 5) {
$symtypename = 'datatype';
} else {
die("Unexpected symbol type $symtype!");
}
my $str = "This $symtypename is available since SDL 3.0.0.";
$sections{'Version'} = wordwrap(wikify($wikitype, $str)) . "\n";
}
}
# We can build the wiki table now that we have all the data. # We can build the wiki table now that we have all the data.
if (scalar(@params) > 0) { if (scalar(@params) > 0) {
my $str = ''; my $str = '';

2
include/SDL3/SDL_atomic.h
View File

@ -266,6 +266,8 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
* A type representing an atomic integer value. * A type representing an atomic integer value.
* *
* It is a struct so people don't accidentally use numeric operations on it. * It is a struct so people don't accidentally use numeric operations on it.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt; typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt;

4
include/SDL3/SDL_audio.h
View File

@ -72,6 +72,8 @@ extern "C" {
* ``` * ```
* *
* There are macros to query these bits. * There are macros to query these bits.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint16 SDL_AudioFormat; typedef Uint16 SDL_AudioFormat;
@ -140,6 +142,8 @@ typedef Uint16 SDL_AudioFormat;
/** /**
* SDL Audio Device instance IDs. * SDL Audio Device instance IDs.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_AudioDeviceID; typedef Uint32 SDL_AudioDeviceID;

2
include/SDL3/SDL_camera.h
View File

@ -46,6 +46,8 @@ extern "C" {
* The ID value starts at 1 and increments from there. The value 0 is an * The ID value starts at 1 and increments from there. The value 0 is an
* invalid ID. * invalid ID.
* *
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_GetCameraDevices * \sa SDL_GetCameraDevices
*/ */
typedef Uint32 SDL_CameraDeviceID; typedef Uint32 SDL_CameraDeviceID;

4
include/SDL3/SDL_dialog.h
View File

@ -42,6 +42,8 @@ extern "C" {
* hyphens, underscores and periods. Alternatively, the whole string can be a * hyphens, underscores and periods. Alternatively, the whole string can be a
* single asterisk ("*"), which serves as an "All files" filter. * single asterisk ("*"), which serves as an "All files" filter.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_DialogFileCallback * \sa SDL_DialogFileCallback
* \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFileDialog
* \sa SDL_ShowSaveFileDialog * \sa SDL_ShowSaveFileDialog
@ -72,6 +74,8 @@ typedef struct SDL_DialogFileFilter
* entry) if no filter was selected, or -1 if the platform or method doesn't * entry) if no filter was selected, or -1 if the platform or method doesn't
* support fetching the selected filter or if an error occured. * support fetching the selected filter or if an error occured.
* *
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_DialogFileFilter * \sa SDL_DialogFileFilter
* \sa SDL_ShowOpenFileDialog * \sa SDL_ShowOpenFileDialog
* \sa SDL_ShowSaveFileDialog * \sa SDL_ShowSaveFileDialog

70
include/SDL3/SDL_events.h
View File

@ -53,6 +53,8 @@ extern "C" {
/** /**
* The types of events that can be delivered. * The types of events that can be delivered.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_EventType typedef enum SDL_EventType
{ {
@ -241,6 +243,8 @@ typedef enum SDL_EventType
/** /**
* Fields shared by every event * Fields shared by every event
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_CommonEvent typedef struct SDL_CommonEvent
{ {
@ -251,6 +255,8 @@ typedef struct SDL_CommonEvent
/** /**
* Display state change event data (event.display.*) * Display state change event data (event.display.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_DisplayEvent typedef struct SDL_DisplayEvent
{ {
@ -263,6 +269,8 @@ typedef struct SDL_DisplayEvent
/** /**
* Window state change event data (event.window.*) * Window state change event data (event.window.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_WindowEvent typedef struct SDL_WindowEvent
{ {
@ -276,6 +284,8 @@ typedef struct SDL_WindowEvent
/** /**
* Keyboard device event structure (event.kdevice.*) * Keyboard device event structure (event.kdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_KeyboardDeviceEvent typedef struct SDL_KeyboardDeviceEvent
{ {
@ -287,6 +297,8 @@ typedef struct SDL_KeyboardDeviceEvent
/** /**
* Keyboard button event structure (event.key.*) * Keyboard button event structure (event.key.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_KeyboardEvent typedef struct SDL_KeyboardEvent
{ {
@ -309,6 +321,8 @@ typedef struct SDL_KeyboardEvent
* *
* The `text` is owned by SDL and should be copied if the application wants to * The `text` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event. * hold onto it beyond the scope of handling this event.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_TextEditingEvent typedef struct SDL_TextEditingEvent
{ {
@ -326,6 +340,8 @@ typedef struct SDL_TextEditingEvent
* *
* The `text` is owned by SDL and should be copied if the application wants to * The `text` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event. * hold onto it beyond the scope of handling this event.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_TextInputEvent typedef struct SDL_TextInputEvent
{ {
@ -338,6 +354,8 @@ typedef struct SDL_TextInputEvent
/** /**
* Mouse device event structure (event.mdevice.*) * Mouse device event structure (event.mdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MouseDeviceEvent typedef struct SDL_MouseDeviceEvent
{ {
@ -349,6 +367,8 @@ typedef struct SDL_MouseDeviceEvent
/** /**
* Mouse motion event structure (event.motion.*) * Mouse motion event structure (event.motion.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MouseMotionEvent typedef struct SDL_MouseMotionEvent
{ {
@ -366,6 +386,8 @@ typedef struct SDL_MouseMotionEvent
/** /**
* Mouse button event structure (event.button.*) * Mouse button event structure (event.button.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MouseButtonEvent typedef struct SDL_MouseButtonEvent
{ {
@ -384,6 +406,8 @@ typedef struct SDL_MouseButtonEvent
/** /**
* Mouse wheel event structure (event.wheel.*) * Mouse wheel event structure (event.wheel.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MouseWheelEvent typedef struct SDL_MouseWheelEvent
{ {
@ -401,6 +425,8 @@ typedef struct SDL_MouseWheelEvent
/** /**
* Joystick axis motion event structure (event.jaxis.*) * Joystick axis motion event structure (event.jaxis.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyAxisEvent typedef struct SDL_JoyAxisEvent
{ {
@ -418,6 +444,8 @@ typedef struct SDL_JoyAxisEvent
/** /**
* Joystick trackball motion event structure (event.jball.*) * Joystick trackball motion event structure (event.jball.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyBallEvent typedef struct SDL_JoyBallEvent
{ {
@ -435,6 +463,8 @@ typedef struct SDL_JoyBallEvent
/** /**
* Joystick hat position change event structure (event.jhat.*) * Joystick hat position change event structure (event.jhat.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyHatEvent typedef struct SDL_JoyHatEvent
{ {
@ -456,6 +486,8 @@ typedef struct SDL_JoyHatEvent
/** /**
* Joystick button event structure (event.jbutton.*) * Joystick button event structure (event.jbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyButtonEvent typedef struct SDL_JoyButtonEvent
{ {
@ -471,6 +503,8 @@ typedef struct SDL_JoyButtonEvent
/** /**
* Joystick device event structure (event.jdevice.*) * Joystick device event structure (event.jdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyDeviceEvent typedef struct SDL_JoyDeviceEvent
{ {
@ -482,6 +516,8 @@ typedef struct SDL_JoyDeviceEvent
/** /**
* Joysick battery level change event structure (event.jbattery.*) * Joysick battery level change event structure (event.jbattery.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_JoyBatteryEvent typedef struct SDL_JoyBatteryEvent
{ {
@ -495,6 +531,8 @@ typedef struct SDL_JoyBatteryEvent
/** /**
* Gamepad axis motion event structure (event.gaxis.*) * Gamepad axis motion event structure (event.gaxis.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GamepadAxisEvent typedef struct SDL_GamepadAxisEvent
{ {
@ -513,6 +551,8 @@ typedef struct SDL_GamepadAxisEvent
/** /**
* Gamepad button event structure (event.gbutton.*) * Gamepad button event structure (event.gbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GamepadButtonEvent typedef struct SDL_GamepadButtonEvent
{ {
@ -529,6 +569,8 @@ typedef struct SDL_GamepadButtonEvent
/** /**
* Gamepad device event structure (event.gdevice.*) * Gamepad device event structure (event.gdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GamepadDeviceEvent typedef struct SDL_GamepadDeviceEvent
{ {
@ -540,6 +582,8 @@ typedef struct SDL_GamepadDeviceEvent
/** /**
* Gamepad touchpad event structure (event.gtouchpad.*) * Gamepad touchpad event structure (event.gtouchpad.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GamepadTouchpadEvent typedef struct SDL_GamepadTouchpadEvent
{ {
@ -556,6 +600,8 @@ typedef struct SDL_GamepadTouchpadEvent
/** /**
* Gamepad sensor event structure (event.gsensor.*) * Gamepad sensor event structure (event.gsensor.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GamepadSensorEvent typedef struct SDL_GamepadSensorEvent
{ {
@ -570,6 +616,8 @@ typedef struct SDL_GamepadSensorEvent
/** /**
* Audio device event structure (event.adevice.*) * Audio device event structure (event.adevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_AudioDeviceEvent typedef struct SDL_AudioDeviceEvent
{ {
@ -585,6 +633,8 @@ typedef struct SDL_AudioDeviceEvent
/** /**
* Camera device event structure (event.cdevice.*) * Camera device event structure (event.cdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_CameraDeviceEvent typedef struct SDL_CameraDeviceEvent
{ {
@ -599,6 +649,8 @@ typedef struct SDL_CameraDeviceEvent
/** /**
* Touch finger event structure (event.tfinger.*) * Touch finger event structure (event.tfinger.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_TouchFingerEvent typedef struct SDL_TouchFingerEvent
{ {
@ -620,6 +672,8 @@ typedef struct SDL_TouchFingerEvent
/** /**
* Pressure-sensitive pen touched or stopped touching surface (event.ptip.*) * Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_PenTipEvent typedef struct SDL_PenTipEvent
{ {
@ -639,6 +693,8 @@ typedef struct SDL_PenTipEvent
/** /**
* Pressure-sensitive pen motion / pressure / angle event structure * Pressure-sensitive pen motion / pressure / angle event structure
* (event.pmotion.*) * (event.pmotion.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_PenMotionEvent typedef struct SDL_PenMotionEvent
{ {
@ -657,6 +713,8 @@ typedef struct SDL_PenMotionEvent
/** /**
* Pressure-sensitive pen button event structure (event.pbutton.*) * Pressure-sensitive pen button event structure (event.pbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_PenButtonEvent typedef struct SDL_PenButtonEvent
{ {
@ -679,6 +737,8 @@ typedef struct SDL_PenButtonEvent
* *
* The `data` is owned by SDL and should be copied if the application wants to * The `data` is owned by SDL and should be copied if the application wants to
* hold onto it beyond the scope of handling this event. Do not free it! * hold onto it beyond the scope of handling this event. Do not free it!
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_DropEvent typedef struct SDL_DropEvent
{ {
@ -695,6 +755,8 @@ typedef struct SDL_DropEvent
/** /**
* An event triggered when the clipboard contents have changed * An event triggered when the clipboard contents have changed
* (event.clipboard.*) * (event.clipboard.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_ClipboardEvent typedef struct SDL_ClipboardEvent
{ {
@ -705,6 +767,8 @@ typedef struct SDL_ClipboardEvent
/** /**
* Sensor event structure (event.sensor.*) * Sensor event structure (event.sensor.*)
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_SensorEvent typedef struct SDL_SensorEvent
{ {
@ -718,6 +782,8 @@ typedef struct SDL_SensorEvent
/** /**
* The "quit requested" event * The "quit requested" event
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_QuitEvent typedef struct SDL_QuitEvent
{ {
@ -734,6 +800,8 @@ typedef struct SDL_QuitEvent
* SDL_PushEvent(). The contents of the structure members are completely up to * SDL_PushEvent(). The contents of the structure members are completely up to
* the programmer; the only requirement is that '''type''' is a value obtained * the programmer; the only requirement is that '''type''' is a value obtained
* from SDL_RegisterEvents(). * from SDL_RegisterEvents().
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_UserEvent typedef struct SDL_UserEvent
{ {
@ -749,6 +817,8 @@ typedef struct SDL_UserEvent
/** /**
* The structure for all events in SDL. * The structure for all events in SDL.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef union SDL_Event typedef union SDL_Event
{ {

2
include/SDL3/SDL_filesystem.h
View File

@ -164,6 +164,8 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
* *
* Note that on macOS/iOS, the Videos folder is called "Movies". * Note that on macOS/iOS, the Videos folder is called "Movies".
* *
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_GetUserFolder * \sa SDL_GetUserFolder
*/ */
typedef enum SDL_Folder typedef enum SDL_Folder

8
include/SDL3/SDL_gamepad.h
View File

@ -55,6 +55,8 @@ extern "C" {
/** /**
* The structure used to identify an SDL gamepad * The structure used to identify an SDL gamepad
*
* \since This struct is available since SDL 3.0.0.
*/ */
struct SDL_Gamepad; struct SDL_Gamepad;
typedef struct SDL_Gamepad SDL_Gamepad; typedef struct SDL_Gamepad SDL_Gamepad;
@ -95,6 +97,8 @@ typedef enum SDL_GamepadType
* *
* You can query the labels for the face buttons using * You can query the labels for the face buttons using
* SDL_GetGamepadButtonLabel() * SDL_GetGamepadButtonLabel()
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_GamepadButton typedef enum SDL_GamepadButton
{ {
@ -136,6 +140,8 @@ typedef enum SDL_GamepadButton
* *
* For a complete set, you should look at the button and gamepad type and have * For a complete set, you should look at the button and gamepad type and have
* a set of symbols that work well with your art style. * a set of symbols that work well with your art style.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_GamepadButtonLabel typedef enum SDL_GamepadButtonLabel
{ {
@ -161,6 +167,8 @@ typedef enum SDL_GamepadButtonLabel
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
* pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
* same range that will be reported by the lower-level SDL_GetJoystickAxis(). * same range that will be reported by the lower-level SDL_GetJoystickAxis().
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_GamepadAxis typedef enum SDL_GamepadAxis
{ {

2
include/SDL3/SDL_guid.h
View File

@ -51,6 +51,8 @@ extern "C" {
* *
* GUIDs may be platform-dependent (i.e., the same device may report different * GUIDs may be platform-dependent (i.e., the same device may report different
* GUIDs on different operating systems). * GUIDs on different operating systems).
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_GUID { typedef struct SDL_GUID {
Uint8 data[16]; Uint8 data[16];

64
include/SDL3/SDL_haptic.h
View File

@ -167,6 +167,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Constant haptic effect. * Constant haptic effect.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
*/ */
#define SDL_HAPTIC_CONSTANT (1u<<0) #define SDL_HAPTIC_CONSTANT (1u<<0)
@ -176,6 +178,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Periodic haptic effect that simulates sine waves. * Periodic haptic effect that simulates sine waves.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
*/ */
#define SDL_HAPTIC_SINE (1u<<1) #define SDL_HAPTIC_SINE (1u<<1)
@ -185,6 +189,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Periodic haptic effect that simulates square waves. * Periodic haptic effect that simulates square waves.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
*/ */
#define SDL_HAPTIC_SQUARE (1<<2) #define SDL_HAPTIC_SQUARE (1<<2)
@ -194,6 +200,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Periodic haptic effect that simulates triangular waves. * Periodic haptic effect that simulates triangular waves.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
*/ */
#define SDL_HAPTIC_TRIANGLE (1u<<3) #define SDL_HAPTIC_TRIANGLE (1u<<3)
@ -203,6 +211,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Periodic haptic effect that simulates saw tooth up waves. * Periodic haptic effect that simulates saw tooth up waves.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
*/ */
#define SDL_HAPTIC_SAWTOOTHUP (1u<<4) #define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
@ -212,6 +222,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Periodic haptic effect that simulates saw tooth down waves. * Periodic haptic effect that simulates saw tooth down waves.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
*/ */
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5) #define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
@ -221,6 +233,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Ramp haptic effect. * Ramp haptic effect.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticRamp * \sa SDL_HapticRamp
*/ */
#define SDL_HAPTIC_RAMP (1u<<6) #define SDL_HAPTIC_RAMP (1u<<6)
@ -231,6 +245,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Condition haptic effect that simulates a spring. Effect is based on the * Condition haptic effect that simulates a spring. Effect is based on the
* axes position. * axes position.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
*/ */
#define SDL_HAPTIC_SPRING (1u<<7) #define SDL_HAPTIC_SPRING (1u<<7)
@ -241,6 +257,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Condition haptic effect that simulates dampening. Effect is based on the * Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity. * axes velocity.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
*/ */
#define SDL_HAPTIC_DAMPER (1u<<8) #define SDL_HAPTIC_DAMPER (1u<<8)
@ -251,6 +269,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Condition haptic effect that simulates inertia. Effect is based on the axes * Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration. * acceleration.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
*/ */
#define SDL_HAPTIC_INERTIA (1u<<9) #define SDL_HAPTIC_INERTIA (1u<<9)
@ -261,6 +281,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Condition haptic effect that simulates friction. Effect is based on the * Condition haptic effect that simulates friction. Effect is based on the
* axes movement. * axes movement.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
*/ */
#define SDL_HAPTIC_FRICTION (1u<<10) #define SDL_HAPTIC_FRICTION (1u<<10)
@ -270,12 +292,16 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Haptic effect for direct control over high/low frequency motors. * Haptic effect for direct control over high/low frequency motors.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticLeftRight * \sa SDL_HapticLeftRight
*/ */
#define SDL_HAPTIC_LEFTRIGHT (1u<<11) #define SDL_HAPTIC_LEFTRIGHT (1u<<11)
/** /**
* Reserved for future use * Reserved for future use
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_HAPTIC_RESERVED1 (1u<<12) #define SDL_HAPTIC_RESERVED1 (1u<<12)
#define SDL_HAPTIC_RESERVED2 (1u<<13) #define SDL_HAPTIC_RESERVED2 (1u<<13)
@ -285,6 +311,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Custom effect is supported. * Custom effect is supported.
* *
* User defined custom haptic effect. * User defined custom haptic effect.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_HAPTIC_CUSTOM (1u<<15) #define SDL_HAPTIC_CUSTOM (1u<<15)
@ -297,6 +325,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Device supports setting the global gain. * Device supports setting the global gain.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_SetHapticGain * \sa SDL_SetHapticGain
*/ */
#define SDL_HAPTIC_GAIN (1u<<16) #define SDL_HAPTIC_GAIN (1u<<16)
@ -306,6 +336,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Device supports setting autocenter. * Device supports setting autocenter.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_SetHapticAutocenter * \sa SDL_SetHapticAutocenter
*/ */
#define SDL_HAPTIC_AUTOCENTER (1u<<17) #define SDL_HAPTIC_AUTOCENTER (1u<<17)
@ -315,6 +347,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Device supports querying effect status. * Device supports querying effect status.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_GetHapticEffectStatus * \sa SDL_GetHapticEffectStatus
*/ */
#define SDL_HAPTIC_STATUS (1u<<18) #define SDL_HAPTIC_STATUS (1u<<18)
@ -324,6 +358,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* *
* Devices supports being paused. * Devices supports being paused.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_PauseHaptic * \sa SDL_PauseHaptic
* \sa SDL_ResumeHaptic * \sa SDL_ResumeHaptic
*/ */
@ -338,6 +374,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/** /**
* Uses polar coordinates for the direction. * Uses polar coordinates for the direction.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_POLAR 0 #define SDL_HAPTIC_POLAR 0
@ -345,6 +383,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/** /**
* Uses cartesian coordinates for the direction. * Uses cartesian coordinates for the direction.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_CARTESIAN 1 #define SDL_HAPTIC_CARTESIAN 1
@ -352,6 +392,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/** /**
* Uses spherical coordinates for the direction. * Uses spherical coordinates for the direction.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_SPHERICAL 2 #define SDL_HAPTIC_SPHERICAL 2
@ -362,6 +404,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* This provides better compatibility across platforms and devices as SDL will * This provides better compatibility across platforms and devices as SDL will
* guess the correct axis. * guess the correct axis.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
*/ */
#define SDL_HAPTIC_STEERING_AXIS 3 #define SDL_HAPTIC_STEERING_AXIS 3
@ -377,6 +421,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/** /**
* Used to play a device an infinite number of times. * Used to play a device an infinite number of times.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_RunHapticEffect * \sa SDL_RunHapticEffect
*/ */
#define SDL_HAPTIC_INFINITY 4294967295U #define SDL_HAPTIC_INFINITY 4294967295U
@ -476,6 +522,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
* ``` * ```
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN * \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL * \sa SDL_HAPTIC_SPHERICAL
@ -498,6 +546,8 @@ typedef struct SDL_HapticDirection
* A constant effect applies a constant force in the specified direction to * A constant effect applies a constant force in the specified direction to
* the joystick. * the joystick.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_CONSTANT * \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
*/ */
@ -578,6 +628,8 @@ typedef struct SDL_HapticConstant
* \| \| \| \| \| \| \| * \| \| \| \| \| \| \|
* ``` * ```
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_SQUARE * \sa SDL_HAPTIC_SQUARE
* \sa SDL_HAPTIC_TRIANGLE * \sa SDL_HAPTIC_TRIANGLE
@ -632,6 +684,8 @@ typedef struct SDL_HapticPeriodic
* SDL_HapticDirection diagram for which side is positive and which is * SDL_HapticDirection diagram for which side is positive and which is
* negative. * negative.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection * \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING * \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER * \sa SDL_HAPTIC_DAMPER
@ -673,6 +727,8 @@ typedef struct SDL_HapticCondition
* effects get added to the ramp effect making the effect become quadratic * effects get added to the ramp effect making the effect become quadratic
* instead of linear. * instead of linear.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_RAMP * \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
*/ */
@ -710,6 +766,8 @@ typedef struct SDL_HapticRamp
* motors, commonly found in modern game controllers. The small (right) motor * motors, commonly found in modern game controllers. The small (right) motor
* is high frequency, and the large (left) motor is low frequency. * is high frequency, and the large (left) motor is low frequency.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_LEFTRIGHT * \sa SDL_HAPTIC_LEFTRIGHT
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
*/ */
@ -738,6 +796,8 @@ typedef struct SDL_HapticLeftRight
* If channels is one, the effect is rotated using the defined direction. * If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes. * Otherwise it uses the samples in data for the different axes.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_CUSTOM * \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect * \sa SDL_HapticEffect
*/ */
@ -831,6 +891,8 @@ typedef struct SDL_HapticCustom
* Note either the attack_level or the fade_level may be above the actual * Note either the attack_level or the fade_level may be above the actual
* effect level. * effect level.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HapticConstant * \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic * \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition * \sa SDL_HapticCondition
@ -858,6 +920,8 @@ typedef union SDL_HapticEffect
* *
* The ID value starts at 1 and increments from there. The value 0 is an * The ID value starts at 1 and increments from there. The value 0 is an
* invalid ID. * invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_HapticID; typedef Uint32 SDL_HapticID;

6
include/SDL3/SDL_hidapi.h
View File

@ -73,12 +73,16 @@ extern "C" {
/** /**
* A handle representing an open HID device * A handle representing an open HID device
*
* \since This struct is available since SDL 3.0.0.
*/ */
struct SDL_hid_device; struct SDL_hid_device;
typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */ typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */
/** /**
* HID underlying bus types. * HID underlying bus types.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_hid_bus_type { typedef enum SDL_hid_bus_type {
/** Unknown bus type */ /** Unknown bus type */
@ -112,6 +116,8 @@ typedef enum SDL_hid_bus_type {
/** /**
* Information about a connected HID device * Information about a connected HID device
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_hid_device_info typedef struct SDL_hid_device_info
{ {

2
include/SDL3/SDL_hints.h
View File

@ -3806,6 +3806,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool d
* \param name what was passed as `name` to SDL_AddHintCallback() * \param name what was passed as `name` to SDL_AddHintCallback()
* \param oldValue the previous hint value * \param oldValue the previous hint value
* \param newValue the new value hint is to be set to * \param newValue the new value hint is to be set to
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);

2
include/SDL3/SDL_init.h
View File

@ -45,6 +45,8 @@ extern "C" {
* These are the flags which may be passed to SDL_Init(). You should specify * These are the flags which may be passed to SDL_Init(). You should specify
* the subsystems which you will be using in your application. * the subsystems which you will be using in your application.
* *
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_Init * \sa SDL_Init
* \sa SDL_Quit * \sa SDL_Quit
* \sa SDL_InitSubSystem * \sa SDL_InitSubSystem

6
include/SDL3/SDL_joystick.h
View File

@ -83,6 +83,8 @@ typedef SDL_GUID SDL_JoystickGUID;
* *
* The ID value starts at 1 and increments from there. The value 0 is an * The ID value starts at 1 and increments from there. The value 0 is an
* invalid ID. * invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_JoystickID; typedef Uint32 SDL_JoystickID;
@ -363,6 +365,8 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickTyp
* SDL_AttachVirtualJoystickEx() All other elements of this structure are * SDL_AttachVirtualJoystickEx() All other elements of this structure are
* optional and can be left 0. * optional and can be left 0.
* *
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_AttachVirtualJoystickEx * \sa SDL_AttachVirtualJoystickEx
*/ */
typedef struct SDL_VirtualJoystickDesc typedef struct SDL_VirtualJoystickDesc
@ -393,6 +397,8 @@ typedef struct SDL_VirtualJoystickDesc
/** /**
* The current version of the SDL_VirtualJoystickDesc structure. * The current version of the SDL_VirtualJoystickDesc structure.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1

2
include/SDL3/SDL_keyboard.h
View File

@ -46,6 +46,8 @@ typedef Uint32 SDL_KeyboardID;
* *
* If you are looking for translated character input, see the * If you are looking for translated character input, see the
* ::SDL_EVENT_TEXT_INPUT event. * ::SDL_EVENT_TEXT_INPUT event.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_Keysym typedef struct SDL_Keysym
{ {

8
include/SDL3/SDL_log.h
View File

@ -50,6 +50,8 @@ extern "C" {
* 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.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_LOG_MESSAGE 4096 #define SDL_MAX_LOG_MESSAGE 4096
@ -59,6 +61,8 @@ extern "C" {
* By default the application category is enabled at the INFO level, the * 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 * 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. * VERBOSE level and all other categories are enabled at the ERROR level.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_LogCategory typedef enum SDL_LogCategory
{ {
@ -97,6 +101,8 @@ typedef enum SDL_LogCategory
/** /**
* The predefined log priorities * The predefined log priorities
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_LogPriority typedef enum SDL_LogPriority
{ {
@ -363,6 +369,8 @@ extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
* \param category the category of the message * \param category the category of the message
* \param priority the priority of the message * \param priority the priority of the message
* \param message the message being output * \param message the message being output
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message);

2
include/SDL3/SDL_main.h
View File

@ -367,6 +367,8 @@ extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate);
/** /**
* The prototype for the application's main() function * The prototype for the application's main() function
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]); typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]);

12
include/SDL3/SDL_messagebox.h
View File

@ -36,6 +36,8 @@ extern "C" {
* SDL_MessageBox flags. * SDL_MessageBox flags.
* *
* If supported will display warning icon, etc. * If supported will display warning icon, etc.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_MessageBoxFlags typedef enum SDL_MessageBoxFlags
{ {
@ -48,6 +50,8 @@ typedef enum SDL_MessageBoxFlags
/** /**
* Flags for SDL_MessageBoxButtonData. * Flags for SDL_MessageBoxButtonData.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_MessageBoxButtonFlags typedef enum SDL_MessageBoxButtonFlags
{ {
@ -57,6 +61,8 @@ typedef enum SDL_MessageBoxButtonFlags
/** /**
* Individual button data. * Individual button data.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MessageBoxButtonData typedef struct SDL_MessageBoxButtonData
{ {
@ -67,6 +73,8 @@ typedef struct SDL_MessageBoxButtonData
/** /**
* RGB value used in a message box color scheme * RGB value used in a message box color scheme
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MessageBoxColor typedef struct SDL_MessageBoxColor
{ {
@ -85,6 +93,8 @@ typedef enum SDL_MessageBoxColorType
/** /**
* A set of colors to use for message box dialogs * A set of colors to use for message box dialogs
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MessageBoxColorScheme typedef struct SDL_MessageBoxColorScheme
{ {
@ -93,6 +103,8 @@ typedef struct SDL_MessageBoxColorScheme
/** /**
* MessageBox structure containing title, text, window, etc. * MessageBox structure containing title, text, window, etc.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_MessageBoxData typedef struct SDL_MessageBoxData
{ {

2
include/SDL3/SDL_metal.h
View File

@ -38,6 +38,8 @@ extern "C" {
/** /**
* A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef void *SDL_MetalView; typedef void *SDL_MetalView;

6
include/SDL3/SDL_mouse.h
View File

@ -44,6 +44,8 @@ typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
/** /**
* Cursor types for SDL_CreateSystemCursor(). * Cursor types for SDL_CreateSystemCursor().
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_SystemCursor typedef enum SDL_SystemCursor
{ {
@ -72,6 +74,8 @@ typedef enum SDL_SystemCursor
/** /**
* Scroll direction types for the Scroll event * Scroll direction types for the Scroll event
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_MouseWheelDirection typedef enum SDL_MouseWheelDirection
{ {
@ -512,6 +516,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void);
* - Button 1: Left mouse button * - Button 1: Left mouse button
* - Button 2: Middle mouse button * - Button 2: Middle mouse button
* - Button 3: Right mouse button * - Button 3: Right mouse button
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_BUTTON(X) (1 << ((X)-1)) #define SDL_BUTTON(X) (1 << ((X)-1))
#define SDL_BUTTON_LEFT 1 #define SDL_BUTTON_LEFT 1

2
include/SDL3/SDL_mutex.h
View File

@ -118,6 +118,8 @@ extern "C" {
/** /**
* Synchronization functions which can time out return this value if they time * Synchronization functions which can time out return this value if they time
* out. * out.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MUTEX_TIMEDOUT 1 #define SDL_MUTEX_TIMEDOUT 1

2
include/SDL3/SDL_pen.h
View File

@ -234,6 +234,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);
/** /**
* Pen capabilities, as reported by SDL_GetPenCapabilities() * Pen capabilities, as reported by SDL_GetPenCapabilities()
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_PenCapabilityInfo typedef struct SDL_PenCapabilityInfo
{ {

12
include/SDL3/SDL_pixels.h
View File

@ -448,6 +448,8 @@ typedef enum SDL_PixelFormatEnum
/** /**
* The color type * The color type
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ColorType typedef enum SDL_ColorType
{ {
@ -459,6 +461,8 @@ typedef enum SDL_ColorType
/** /**
* The color range, as described by * The color range, as described by
* https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ColorRange typedef enum SDL_ColorRange
{ {
@ -470,6 +474,8 @@ typedef enum SDL_ColorRange
/** /**
* The color primaries, as described by * The color primaries, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en * https://www.itu.int/rec/T-REC-H.273-201612-S/en
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ColorPrimaries typedef enum SDL_ColorPrimaries
{ {
@ -492,6 +498,8 @@ typedef enum SDL_ColorPrimaries
/** /**
* The transfer characteristics, as described by * The transfer characteristics, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en * https://www.itu.int/rec/T-REC-H.273-201612-S/en
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_TransferCharacteristics typedef enum SDL_TransferCharacteristics
{ {
@ -519,6 +527,8 @@ typedef enum SDL_TransferCharacteristics
/** /**
* The matrix coefficients, as described by * The matrix coefficients, as described by
* https://www.itu.int/rec/T-REC-H.273-201612-S/en * https://www.itu.int/rec/T-REC-H.273-201612-S/en
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_MatrixCoefficients typedef enum SDL_MatrixCoefficients
{ {
@ -541,6 +551,8 @@ typedef enum SDL_MatrixCoefficients
/** /**
* The chroma sample location * The chroma sample location
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ChromaLocation typedef enum SDL_ChromaLocation
{ {

4
include/SDL3/SDL_properties.h
View File

@ -39,11 +39,15 @@ extern "C" {
/** /**
* SDL properties ID * SDL properties ID
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_PropertiesID; typedef Uint32 SDL_PropertiesID;
/** /**
* SDL property type * SDL property type
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_PropertyType typedef enum SDL_PropertyType
{ {

16
include/SDL3/SDL_render.h
View File

@ -63,11 +63,15 @@ extern "C" {
/** /**
* The name of the software renderer. * The name of the software renderer.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_SOFTWARE_RENDERER "software" #define SDL_SOFTWARE_RENDERER "software"
/** /**
* Flags used when creating a rendering context. * Flags used when creating a rendering context.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_RendererFlags typedef enum SDL_RendererFlags
{ {
@ -76,6 +80,8 @@ typedef enum SDL_RendererFlags
/** /**
* Information on the capabilities of a render driver or context. * Information on the capabilities of a render driver or context.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_RendererInfo typedef struct SDL_RendererInfo
{ {
@ -89,6 +95,8 @@ typedef struct SDL_RendererInfo
/** /**
* Vertex structure. * Vertex structure.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_Vertex typedef struct SDL_Vertex
{ {
@ -99,6 +107,8 @@ typedef struct SDL_Vertex
/** /**
* The access pattern allowed for a texture. * The access pattern allowed for a texture.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_TextureAccess typedef enum SDL_TextureAccess
{ {
@ -109,6 +119,8 @@ typedef enum SDL_TextureAccess
/** /**
* How the logical size is mapped to the output. * How the logical size is mapped to the output.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_RendererLogicalPresentation typedef enum SDL_RendererLogicalPresentation
{ {
@ -121,12 +133,16 @@ typedef enum SDL_RendererLogicalPresentation
/** /**
* A structure representing rendering state * A structure representing rendering state
*
* \since This struct is available since SDL 3.0.0.
*/ */
struct SDL_Renderer; struct SDL_Renderer;
typedef struct SDL_Renderer SDL_Renderer; typedef struct SDL_Renderer SDL_Renderer;
/** /**
* An efficient driver-specific representation of pixel data * An efficient driver-specific representation of pixel data
*
* \since This struct is available since SDL 3.0.0.
*/ */
struct SDL_Texture; struct SDL_Texture;
typedef struct SDL_Texture SDL_Texture; typedef struct SDL_Texture SDL_Texture;

4
include/SDL3/SDL_sensor.h
View File

@ -57,6 +57,8 @@ typedef struct SDL_Sensor SDL_Sensor;
* *
* The ID value starts at 1 and increments from there. The value 0 is an * The ID value starts at 1 and increments from there. The value 0 is an
* invalid ID. * invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_SensorID; typedef Uint32 SDL_SensorID;
@ -99,6 +101,8 @@ typedef enum
* *
* The axis data is not changed when the device is rotated. * The axis data is not changed when the device is rotated.
* *
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_GetCurrentDisplayOrientation * \sa SDL_GetCurrentDisplayOrientation
*/ */
#define SDL_STANDARD_GRAVITY 9.80665f #define SDL_STANDARD_GRAVITY 9.80665f

22
include/SDL3/SDL_stdinc.h
View File

@ -90,6 +90,8 @@ void *alloca(size_t);
/** /**
* The number of elements in an array. * The number of elements in an array.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
#define SDL_TABLESIZE(table) SDL_arraysize(table) #define SDL_TABLESIZE(table) SDL_arraysize(table)
@ -102,6 +104,8 @@ void *alloca(size_t);
* ```c * ```c
* #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")`
* ``` * ```
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_STRINGIFY_ARG(arg) #arg #define SDL_STRINGIFY_ARG(arg) #arg
@ -165,6 +169,8 @@ typedef int SDL_bool;
/** /**
* A signed 8-bit integer type. * A signed 8-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
@ -172,6 +178,8 @@ typedef int8_t Sint8;
/** /**
* An unsigned 8-bit integer type. * An unsigned 8-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
@ -179,6 +187,8 @@ typedef uint8_t Uint8;
/** /**
* A signed 16-bit integer type. * A signed 16-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
@ -186,6 +196,8 @@ typedef int16_t Sint16;
/** /**
* An unsigned 16-bit integer type. * An unsigned 16-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
@ -193,6 +205,8 @@ typedef uint16_t Uint16;
/** /**
* A signed 32-bit integer type. * A signed 32-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
@ -200,6 +214,8 @@ typedef int32_t Sint32;
/** /**
* An unsigned 32-bit integer type. * An unsigned 32-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */ #define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */
#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */ #define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
@ -207,6 +223,8 @@ typedef uint32_t Uint32;
/** /**
* A signed 64-bit integer type. * A signed 64-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ #define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */
#define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ #define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
@ -214,6 +232,8 @@ typedef int64_t Sint64;
/** /**
* An unsigned 64-bit integer type. * An unsigned 64-bit integer type.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */ #define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */
#define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */ #define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */
@ -226,6 +246,8 @@ typedef uint64_t Uint64;
* They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS()
* and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
* SDL_TimeToWindows() and SDL_TimeFromWindows(). * SDL_TimeToWindows() and SDL_TimeFromWindows().
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MAX_TIME SDL_MAX_SINT64 #define SDL_MAX_TIME SDL_MAX_SINT64
#define SDL_MIN_TIME SDL_MIN_SINT64 #define SDL_MIN_TIME SDL_MIN_SINT64

8
include/SDL3/SDL_surface.h
View File

@ -61,6 +61,8 @@ extern "C" {
/** /**
* Evaluates to true if the surface needs to be locked before access. * Evaluates to true if the surface needs to be locked before access.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
@ -68,6 +70,8 @@ typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */
/** /**
* The scaling mode * The scaling mode
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ScaleMode typedef enum SDL_ScaleMode
{ {
@ -78,6 +82,8 @@ typedef enum SDL_ScaleMode
/** /**
* The flip mode * The flip mode
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_FlipMode typedef enum SDL_FlipMode
{ {
@ -100,6 +106,8 @@ typedef enum SDL_FlipMode
* and a byte order given by the format. After encoding all pixels, any * and a byte order given by the format. After encoding all pixels, any
* remaining bytes to reach the pitch are used as padding to reach a desired * remaining bytes to reach the pitch are used as padding to reach a desired
* alignment, and have undefined contents. * alignment, and have undefined contents.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_Surface typedef struct SDL_Surface
{ {

6
include/SDL3/SDL_system.h
View File

@ -339,6 +339,8 @@ extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
/** /**
* See the official Android developer guide for more information: * See the official Android developer guide for more information:
* http://developer.android.com/guide/topics/data/data-storage.html * http://developer.android.com/guide/topics/data/data-storage.html
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
@ -480,6 +482,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
/** /**
* WinRT / Windows Phone path types * WinRT / Windows Phone path types
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_WinRT_Path typedef enum SDL_WinRT_Path
{ {
@ -504,6 +508,8 @@ typedef enum SDL_WinRT_Path
/** /**
* WinRT Device Family * WinRT Device Family
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_WinRT_DeviceFamily typedef enum SDL_WinRT_DeviceFamily
{ {

4
include/SDL3/SDL_thread.h
View File

@ -63,6 +63,8 @@ typedef Uint32 SDL_TLSID;
* should be aware that calling SDL_SetThreadPriority may alter such state. * should be aware that calling SDL_SetThreadPriority may alter such state.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this
* behavior. * behavior.
*
* \since This enum is available since SDL 3.0.0.
*/ */
typedef enum SDL_ThreadPriority { typedef enum SDL_ThreadPriority {
SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_LOW,
@ -76,6 +78,8 @@ typedef enum SDL_ThreadPriority {
* *
* \param data what was passed as `data` to SDL_CreateThread() * \param data what was passed as `data` to SDL_CreateThread()
* \returns a value that can be reported through SDL_WaitThread(). * \returns a value that can be reported through SDL_WaitThread().
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef int (SDLCALL * SDL_ThreadFunction) (void *data); typedef int (SDLCALL * SDL_ThreadFunction) (void *data);

6
include/SDL3/SDL_time.h
View File

@ -40,6 +40,8 @@ extern "C" {
/** /**
* A structure holding a calendar date and time broken down into its * A structure holding a calendar date and time broken down into its
* components. * components.
*
* \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_DateTime typedef struct SDL_DateTime
{ {
@ -57,6 +59,8 @@ typedef struct SDL_DateTime
/** /**
* The preferred date format of the current system locale. * The preferred date format of the current system locale.
* *
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER * \sa SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER
*/ */
typedef enum SDL_DateFormat typedef enum SDL_DateFormat
@ -69,6 +73,8 @@ typedef enum SDL_DateFormat
/** /**
* The preferred time format of the current system locale. * The preferred time format of the current system locale.
* *
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER * \sa SDL_PROP_GLOBAL_SYSTEM_TIME_FORMAT_NUMBER
*/ */
typedef enum SDL_TimeFormat typedef enum SDL_TimeFormat

2
include/SDL3/SDL_timer.h
View File

@ -150,6 +150,8 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(Uint32 interval, void *param);
/** /**
* Definition of the timer ID type. * Definition of the timer ID type.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef Uint32 SDL_TimerID; typedef Uint32 SDL_TimerID;

14
include/SDL3/SDL_video.h
View File

@ -126,6 +126,8 @@ typedef struct SDL_Window SDL_Window;
* changed on existing windows by the app, and some of it might be altered by * changed on existing windows by the app, and some of it might be altered by
* the user or system outside of the app's control. * the user or system outside of the app's control.
* *
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_GetWindowFlags * \sa SDL_GetWindowFlags
*/ */
typedef Uint32 SDL_WindowFlags; typedef Uint32 SDL_WindowFlags;
@ -156,6 +158,8 @@ typedef Uint32 SDL_WindowFlags;
/** /**
* 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.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
@ -165,6 +169,8 @@ typedef Uint32 SDL_WindowFlags;
/** /**
* Used to indicate that the window position should be centered. * Used to indicate that the window position should be centered.
*
* \since This macro is available since SDL 3.0.0.
*/ */
#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
#define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X))
@ -186,11 +192,15 @@ typedef enum SDL_FlashOperation
/** /**
* An opaque handle to an OpenGL context. * An opaque handle to an OpenGL context.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef void *SDL_GLContext; typedef void *SDL_GLContext;
/** /**
* Opaque EGL types. * Opaque EGL types.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef void *SDL_EGLDisplay; typedef void *SDL_EGLDisplay;
typedef void *SDL_EGLConfig; typedef void *SDL_EGLConfig;
@ -200,6 +210,8 @@ typedef int SDL_EGLint;
/** /**
* EGL attribute initialization callback types. * EGL attribute initialization callback types.
*
* \since This datatype is available since SDL 3.0.0.
*/ */
typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void);
typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);
@ -2054,6 +2066,8 @@ extern DECLSPEC int SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x,
/** /**
* Possible return values from the SDL_HitTest callback. * Possible return values from the SDL_HitTest callback.
* *
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_HitTest * \sa SDL_HitTest
*/ */
typedef enum SDL_HitTestResult typedef enum SDL_HitTestResult