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.
$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.
if (scalar(@params) > 0) {
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.
*
* 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;

4
include/SDL3/SDL_audio.h
View File

@ -72,6 +72,8 @@ extern "C" {
* ```
*
* There are macros to query these bits.
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef Uint16 SDL_AudioFormat;
@ -140,6 +142,8 @@ typedef Uint16 SDL_AudioFormat;
/**
* SDL Audio Device instance IDs.
*
* \since This datatype is available since SDL 3.0.0.
*/
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
* invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_GetCameraDevices
*/
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
* single asterisk ("*"), which serves as an "All files" filter.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_DialogFileCallback
* \sa SDL_ShowOpenFileDialog
* \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
* 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_ShowOpenFileDialog
* \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.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_EventType
{
@ -241,6 +243,8 @@ typedef enum SDL_EventType
/**
* Fields shared by every event
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_CommonEvent
{
@ -251,6 +255,8 @@ typedef struct SDL_CommonEvent
/**
* Display state change event data (event.display.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_DisplayEvent
{
@ -263,6 +269,8 @@ typedef struct SDL_DisplayEvent
/**
* Window state change event data (event.window.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_WindowEvent
{
@ -276,6 +284,8 @@ typedef struct SDL_WindowEvent
/**
* Keyboard device event structure (event.kdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_KeyboardDeviceEvent
{
@ -287,6 +297,8 @@ typedef struct SDL_KeyboardDeviceEvent
/**
* Keyboard button event structure (event.key.*)
*
* \since This struct is available since SDL 3.0.0.
*/
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
* hold onto it beyond the scope of handling this event.
*
* \since This struct is available since SDL 3.0.0.
*/
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
* hold onto it beyond the scope of handling this event.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_TextInputEvent
{
@ -338,6 +354,8 @@ typedef struct SDL_TextInputEvent
/**
* Mouse device event structure (event.mdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MouseDeviceEvent
{
@ -349,6 +367,8 @@ typedef struct SDL_MouseDeviceEvent
/**
* Mouse motion event structure (event.motion.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MouseMotionEvent
{
@ -366,6 +386,8 @@ typedef struct SDL_MouseMotionEvent
/**
* Mouse button event structure (event.button.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MouseButtonEvent
{
@ -384,6 +406,8 @@ typedef struct SDL_MouseButtonEvent
/**
* Mouse wheel event structure (event.wheel.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MouseWheelEvent
{
@ -401,6 +425,8 @@ typedef struct SDL_MouseWheelEvent
/**
* Joystick axis motion event structure (event.jaxis.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyAxisEvent
{
@ -418,6 +444,8 @@ typedef struct SDL_JoyAxisEvent
/**
* Joystick trackball motion event structure (event.jball.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyBallEvent
{
@ -435,6 +463,8 @@ typedef struct SDL_JoyBallEvent
/**
* Joystick hat position change event structure (event.jhat.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyHatEvent
{
@ -456,6 +486,8 @@ typedef struct SDL_JoyHatEvent
/**
* Joystick button event structure (event.jbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyButtonEvent
{
@ -471,6 +503,8 @@ typedef struct SDL_JoyButtonEvent
/**
* Joystick device event structure (event.jdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyDeviceEvent
{
@ -482,6 +516,8 @@ typedef struct SDL_JoyDeviceEvent
/**
* Joysick battery level change event structure (event.jbattery.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_JoyBatteryEvent
{
@ -495,6 +531,8 @@ typedef struct SDL_JoyBatteryEvent
/**
* Gamepad axis motion event structure (event.gaxis.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GamepadAxisEvent
{
@ -513,6 +551,8 @@ typedef struct SDL_GamepadAxisEvent
/**
* Gamepad button event structure (event.gbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GamepadButtonEvent
{
@ -529,6 +569,8 @@ typedef struct SDL_GamepadButtonEvent
/**
* Gamepad device event structure (event.gdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GamepadDeviceEvent
{
@ -540,6 +582,8 @@ typedef struct SDL_GamepadDeviceEvent
/**
* Gamepad touchpad event structure (event.gtouchpad.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GamepadTouchpadEvent
{
@ -556,6 +600,8 @@ typedef struct SDL_GamepadTouchpadEvent
/**
* Gamepad sensor event structure (event.gsensor.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GamepadSensorEvent
{
@ -570,6 +616,8 @@ typedef struct SDL_GamepadSensorEvent
/**
* Audio device event structure (event.adevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_AudioDeviceEvent
{
@ -585,6 +633,8 @@ typedef struct SDL_AudioDeviceEvent
/**
* Camera device event structure (event.cdevice.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_CameraDeviceEvent
{
@ -599,6 +649,8 @@ typedef struct SDL_CameraDeviceEvent
/**
* Touch finger event structure (event.tfinger.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_TouchFingerEvent
{
@ -620,6 +672,8 @@ typedef struct SDL_TouchFingerEvent
/**
* Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_PenTipEvent
{
@ -639,6 +693,8 @@ typedef struct SDL_PenTipEvent
/**
* Pressure-sensitive pen motion / pressure / angle event structure
* (event.pmotion.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_PenMotionEvent
{
@ -657,6 +713,8 @@ typedef struct SDL_PenMotionEvent
/**
* Pressure-sensitive pen button event structure (event.pbutton.*)
*
* \since This struct is available since SDL 3.0.0.
*/
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
* 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
{
@ -695,6 +755,8 @@ typedef struct SDL_DropEvent
/**
* An event triggered when the clipboard contents have changed
* (event.clipboard.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_ClipboardEvent
{
@ -705,6 +767,8 @@ typedef struct SDL_ClipboardEvent
/**
* Sensor event structure (event.sensor.*)
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_SensorEvent
{
@ -718,6 +782,8 @@ typedef struct SDL_SensorEvent
/**
* The "quit requested" event
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_QuitEvent
{
@ -734,6 +800,8 @@ typedef struct SDL_QuitEvent
* SDL_PushEvent(). The contents of the structure members are completely up to
* the programmer; the only requirement is that '''type''' is a value obtained
* from SDL_RegisterEvents().
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_UserEvent
{
@ -749,6 +817,8 @@ typedef struct SDL_UserEvent
/**
* The structure for all events in SDL.
*
* \since This struct is available since SDL 3.0.0.
*/
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".
*
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_GetUserFolder
*/
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
*
* \since This struct is available since SDL 3.0.0.
*/
struct 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
* SDL_GetGamepadButtonLabel()
*
* \since This enum is available since SDL 3.0.0.
*/
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
* 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
{
@ -161,6 +167,8 @@ typedef enum SDL_GamepadButtonLabel
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
* pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
* same range that will be reported by the lower-level SDL_GetJoystickAxis().
*
* \since This enum is available since SDL 3.0.0.
*/
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 on different operating systems).
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_GUID {
Uint8 data[16];

64
include/SDL3/SDL_haptic.h
View File

@ -167,6 +167,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Constant haptic effect.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_CONSTANT (1u<<0)
@ -176,6 +178,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates sine waves.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SINE (1u<<1)
@ -185,6 +189,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates square waves.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SQUARE (1<<2)
@ -194,6 +200,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates triangular waves.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic
*/
#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.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic
*/
#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.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
@ -221,6 +233,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Ramp haptic effect.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticRamp
*/
#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
* axes position.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition
*/
#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
* axes velocity.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition
*/
#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
* acceleration.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition
*/
#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
* axes movement.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticCondition
*/
#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.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticLeftRight
*/
#define SDL_HAPTIC_LEFTRIGHT (1u<<11)
/**
* Reserved for future use
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_HAPTIC_RESERVED1 (1u<<12)
#define SDL_HAPTIC_RESERVED2 (1u<<13)
@ -285,6 +311,8 @@ typedef struct SDL_Haptic SDL_Haptic;
* Custom effect is supported.
*
* User defined custom haptic effect.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_HAPTIC_CUSTOM (1u<<15)
@ -297,6 +325,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting the global gain.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_SetHapticGain
*/
#define SDL_HAPTIC_GAIN (1u<<16)
@ -306,6 +336,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting autocenter.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_SetHapticAutocenter
*/
#define SDL_HAPTIC_AUTOCENTER (1u<<17)
@ -315,6 +347,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports querying effect status.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_GetHapticEffectStatus
*/
#define SDL_HAPTIC_STATUS (1u<<18)
@ -324,6 +358,8 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Devices supports being paused.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_PauseHaptic
* \sa SDL_ResumeHaptic
*/
@ -338,6 +374,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses polar coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_POLAR 0
@ -345,6 +383,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses cartesian coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_CARTESIAN 1
@ -352,6 +392,8 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses spherical coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection
*/
#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
* guess the correct axis.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection
*/
#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.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_RunHapticEffect
*/
#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.
* ```
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
@ -498,6 +546,8 @@ typedef struct SDL_HapticDirection
* A constant effect applies a constant force in the specified direction to
* the joystick.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_CONSTANT
* \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_SQUARE
* \sa SDL_HAPTIC_TRIANGLE
@ -632,6 +684,8 @@ typedef struct SDL_HapticPeriodic
* SDL_HapticDirection diagram for which side is positive and which is
* negative.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
@ -673,6 +727,8 @@ typedef struct SDL_HapticCondition
* effects get added to the ramp effect making the effect become quadratic
* instead of linear.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
*/
@ -710,6 +766,8 @@ typedef struct SDL_HapticRamp
* motors, commonly found in modern game controllers. The small (right) motor
* 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_HapticEffect
*/
@ -738,6 +796,8 @@ typedef struct SDL_HapticLeftRight
* If channels is one, the effect is rotated using the defined direction.
* 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_HapticEffect
*/
@ -831,6 +891,8 @@ typedef struct SDL_HapticCustom
* Note either the attack_level or the fade_level may be above the actual
* effect level.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \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
* invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
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
*
* \since This struct is available since SDL 3.0.0.
*/
struct SDL_hid_device;
typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */
/**
* HID underlying bus types.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_hid_bus_type {
/** Unknown bus type */
@ -112,6 +116,8 @@ typedef enum SDL_hid_bus_type {
/**
* Information about a connected HID device
*
* \since This struct is available since SDL 3.0.0.
*/
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 oldValue the previous hint value
* \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);

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
* 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_Quit
* \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
* invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
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
* optional and can be left 0.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_AttachVirtualJoystickEx
*/
typedef struct SDL_VirtualJoystickDesc
@ -393,6 +397,8 @@ typedef struct SDL_VirtualJoystickDesc
/**
* 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

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
* ::SDL_EVENT_TEXT_INPUT event.
*
* \since This struct is available since SDL 3.0.0.
*/
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.
*
* 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
@ -59,6 +61,8 @@ extern "C" {
* 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.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_LogCategory
{
@ -97,6 +101,8 @@ typedef enum SDL_LogCategory
/**
* The predefined log priorities
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_LogPriority
{
@ -363,6 +369,8 @@ extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
* \param category the category of the message
* \param priority the priority of the message
* \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);

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
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef int (SDLCALL *SDL_main_func)(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.
*
* If supported will display warning icon, etc.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_MessageBoxFlags
{
@ -48,6 +50,8 @@ typedef enum SDL_MessageBoxFlags
/**
* Flags for SDL_MessageBoxButtonData.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_MessageBoxButtonFlags
{
@ -57,6 +61,8 @@ typedef enum SDL_MessageBoxButtonFlags
/**
* Individual button data.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MessageBoxButtonData
{
@ -67,6 +73,8 @@ typedef struct SDL_MessageBoxButtonData
/**
* RGB value used in a message box color scheme
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MessageBoxColor
{
@ -85,6 +93,8 @@ typedef enum SDL_MessageBoxColorType
/**
* A set of colors to use for message box dialogs
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_MessageBoxColorScheme
{
@ -93,6 +103,8 @@ typedef struct SDL_MessageBoxColorScheme
/**
* MessageBox structure containing title, text, window, etc.
*
* \since This struct is available since SDL 3.0.0.
*/
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).
*
* \since This datatype is available since SDL 3.0.0.
*/
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().
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_SystemCursor
{
@ -72,6 +74,8 @@ typedef enum SDL_SystemCursor
/**
* Scroll direction types for the Scroll event
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_MouseWheelDirection
{
@ -512,6 +516,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void);
* - Button 1: Left mouse button
* - Button 2: Middle 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_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
* out.
*
* \since This macro is available since SDL 3.0.0.
*/
#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()
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_PenCapabilityInfo
{

12
include/SDL3/SDL_pixels.h
View File

@ -448,6 +448,8 @@ typedef enum SDL_PixelFormatEnum
/**
* The color type
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_ColorType
{
@ -459,6 +461,8 @@ typedef enum SDL_ColorType
/**
* The color range, as described by
* 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
{
@ -470,6 +474,8 @@ typedef enum SDL_ColorRange
/**
* The color primaries, as described by
* 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
{
@ -492,6 +498,8 @@ typedef enum SDL_ColorPrimaries
/**
* The transfer characteristics, as described by
* 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
{
@ -519,6 +527,8 @@ typedef enum SDL_TransferCharacteristics
/**
* The matrix coefficients, as described by
* 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
{
@ -541,6 +551,8 @@ typedef enum SDL_MatrixCoefficients
/**
* The chroma sample location
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_ChromaLocation
{

4
include/SDL3/SDL_properties.h
View File

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

16
include/SDL3/SDL_render.h
View File

@ -63,11 +63,15 @@ extern "C" {
/**
* The name of the software renderer.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_SOFTWARE_RENDERER "software"
/**
* Flags used when creating a rendering context.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_RendererFlags
{
@ -76,6 +80,8 @@ typedef enum SDL_RendererFlags
/**
* Information on the capabilities of a render driver or context.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_RendererInfo
{
@ -89,6 +95,8 @@ typedef struct SDL_RendererInfo
/**
* Vertex structure.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_Vertex
{
@ -99,6 +107,8 @@ typedef struct SDL_Vertex
/**
* The access pattern allowed for a texture.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_TextureAccess
{
@ -109,6 +119,8 @@ typedef enum SDL_TextureAccess
/**
* How the logical size is mapped to the output.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_RendererLogicalPresentation
{
@ -121,12 +133,16 @@ typedef enum SDL_RendererLogicalPresentation
/**
* A structure representing rendering state
*
* \since This struct is available since SDL 3.0.0.
*/
struct SDL_Renderer;
typedef struct SDL_Renderer SDL_Renderer;
/**
* An efficient driver-specific representation of pixel data
*
* \since This struct is available since SDL 3.0.0.
*/
struct 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
* invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef Uint32 SDL_SensorID;
@ -99,6 +101,8 @@ typedef enum
*
* The axis data is not changed when the device is rotated.
*
* \since This macro is available since SDL 3.0.0.
*
* \sa SDL_GetCurrentDisplayOrientation
*/
#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.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_arraysize(array) (sizeof(array)/sizeof(array[0]))
#define SDL_TABLESIZE(table) SDL_arraysize(table)
@ -102,6 +104,8 @@ void *alloca(size_t);
* ```c
* #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
@ -165,6 +169,8 @@ typedef int SDL_bool;
/**
* 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_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
@ -172,6 +178,8 @@ typedef int8_t Sint8;
/**
* 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_MIN_UINT8 ((Uint8)0x00) /* 0 */
@ -179,6 +187,8 @@ typedef uint8_t Uint8;
/**
* 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_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
@ -186,6 +196,8 @@ typedef int16_t Sint16;
/**
* 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_MIN_UINT16 ((Uint16)0x0000) /* 0 */
@ -193,6 +205,8 @@ typedef uint16_t Uint16;
/**
* 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_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
@ -200,6 +214,8 @@ typedef int32_t Sint32;
/**
* 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_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
@ -207,6 +223,8 @@ typedef uint32_t Uint32;
/**
* 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_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
@ -214,6 +232,8 @@ typedef int64_t Sint64;
/**
* 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_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()
* and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with
* SDL_TimeToWindows() and SDL_TimeFromWindows().
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_MAX_TIME SDL_MAX_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.
*
* \since This macro is available since SDL 3.0.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
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_ScaleMode
{
@ -78,6 +82,8 @@ typedef enum SDL_ScaleMode
/**
* The flip mode
*
* \since This enum is available since SDL 3.0.0.
*/
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
* remaining bytes to reach the pitch are used as padding to reach a desired
* alignment, and have undefined contents.
*
* \since This struct is available since SDL 3.0.0.
*/
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:
* 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_WRITE 0x02
@ -480,6 +482,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
/**
* WinRT / Windows Phone path types
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_WinRT_Path
{
@ -504,6 +508,8 @@ typedef enum SDL_WinRT_Path
/**
* WinRT Device Family
*
* \since This enum is available since SDL 3.0.0.
*/
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.
* SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this
* behavior.
*
* \since This enum is available since SDL 3.0.0.
*/
typedef enum SDL_ThreadPriority {
SDL_THREAD_PRIORITY_LOW,
@ -76,6 +78,8 @@ typedef enum SDL_ThreadPriority {
*
* \param data what was passed as `data` to SDL_CreateThread()
* \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);

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
* components.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_DateTime
{
@ -57,6 +59,8 @@ typedef struct SDL_DateTime
/**
* 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
*/
typedef enum SDL_DateFormat
@ -69,6 +73,8 @@ typedef enum SDL_DateFormat
/**
* 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
*/
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.
*
* \since This datatype is available since SDL 3.0.0.
*/
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
* the user or system outside of the app's control.
*
* \since This datatype is available since SDL 3.0.0.
*
* \sa SDL_GetWindowFlags
*/
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.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
#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.
*
* \since This macro is available since SDL 3.0.0.
*/
#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
#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.
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef void *SDL_GLContext;
/**
* Opaque EGL types.
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef void *SDL_EGLDisplay;
typedef void *SDL_EGLConfig;
@ -200,6 +210,8 @@ typedef int SDL_EGLint;
/**
* EGL attribute initialization callback types.
*
* \since This datatype is available since SDL 3.0.0.
*/
typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(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.
*
* \since This enum is available since SDL 3.0.0.
*
* \sa SDL_HitTest
*/
typedef enum SDL_HitTestResult