mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-11-21 09:36:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

fnsince: update \since policy for documentation.

Browse Source 
Everything in SDL3 up to the ABI lock is reported as available since 3.1.3.
Everything else will be reported as since 3.2.0 (what will be the first
official release).

Also ran a Perl script over the headers to change everything to 3.1.3 that
wasn't an API function, since fnsince.pl can't manage those. If there's a
macro or datatype that has snuck in that needs to be 3.2.0 instead, we'll
have to manually fix it up, but it shouldn't be a big deal in any case.

Reference PR #11304.
This commit is contained in:
Ryan C. Gordon
2024-10-23 12:19:38 -04:00
parent 21c91d5535
commit 1c1706a00b
59 changed files with 1828 additions and 1825 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
include/SDL3/SDL_haptic.h
View File

@@ -141,7 +141,7 @@ extern "C" {
/**
* The haptic structure used to identify an SDL haptic.
*
* \since This struct is available since SDL 3.0.0.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_OpenHaptic
* \sa SDL_OpenHapticFromJoystick
@@ -167,7 +167,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Constant haptic effect.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticCondition
*/
@@ -178,7 +178,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates sine waves.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticPeriodic
*/
@@ -189,7 +189,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates square waves.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticPeriodic
*/
@@ -200,7 +200,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Periodic haptic effect that simulates triangular waves.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticPeriodic
*/
@@ -211,7 +211,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticPeriodic
*/
@@ -222,7 +222,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticPeriodic
*/
@@ -233,7 +233,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Ramp haptic effect.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticRamp
*/
@@ -245,7 +245,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticCondition
*/
@@ -257,7 +257,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticCondition
*/
@@ -269,7 +269,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticCondition
*/
@@ -281,7 +281,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticCondition
*/
@@ -292,7 +292,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticLeftRight
*/
@@ -301,7 +301,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Reserved for future use
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_HAPTIC_RESERVED1 (1u<<12)
#define SDL_HAPTIC_RESERVED2 (1u<<13)
@@ -312,7 +312,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* User defined custom haptic effect.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_HAPTIC_CUSTOM (1u<<15)
@@ -325,7 +325,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting the global gain.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_SetHapticGain
*/
@@ -336,7 +336,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports setting autocenter.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_SetHapticAutocenter
*/
@@ -347,7 +347,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Device supports querying effect status.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_GetHapticEffectStatus
*/
@@ -358,7 +358,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*
* Devices supports being paused.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_PauseHaptic
* \sa SDL_ResumeHaptic
@@ -374,7 +374,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses polar coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticDirection
*/
@@ -383,7 +383,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses cartesian coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticDirection
*/
@@ -392,7 +392,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Uses spherical coordinates for the direction.
*
* \since This macro is available since SDL 3.0.0.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticDirection
*/
@@ -404,7 +404,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_HapticDirection
*/
@@ -421,7 +421,7 @@ 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.
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_RunHapticEffect
*/
@@ -522,7 +522,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
@@ -546,7 +546,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
@@ -628,7 +628,7 @@ typedef struct SDL_HapticConstant
* \| \| \| \| \| \| \|
* ```
*
* \since This struct is available since SDL 3.0.0.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_SQUARE
@@ -684,7 +684,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
@@ -727,7 +727,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
@@ -766,7 +766,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_LEFTRIGHT
* \sa SDL_HapticEffect
@@ -796,7 +796,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect
@@ -891,7 +891,7 @@ 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.
* \since This struct is available since SDL 3.1.3.
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
@@ -920,7 +920,7 @@ typedef union SDL_HapticEffect
*
* The value 0 is an invalid ID.
*
* \since This datatype is available since SDL 3.0.0.
* \since This datatype is available since SDL 3.1.3.
*/
typedef Uint32 SDL_HapticID;
@@ -936,7 +936,7 @@ typedef Uint32 SDL_HapticID;
* failure; call SDL_GetError() for more information. This should be
* freed with SDL_free() when it is no longer needed.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_OpenHaptic
*/
@@ -952,7 +952,7 @@ extern SDL_DECLSPEC SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
* this function returns NULL; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticName
* \sa SDL_OpenHaptic
@@ -973,7 +973,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID ins
* \returns the device identifier or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CloseHaptic
* \sa SDL_GetHaptics
@@ -992,7 +992,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHaptic(SDL_HapticID instance_id
* \returns an SDL_Haptic on success or NULL on failure or if it hasn't been
* opened yet; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instance_id);
@@ -1003,7 +1003,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_GetHapticFromID(SDL_HapticID instan
* \returns the instance ID of the specified haptic device on success or 0 on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
@@ -1015,7 +1015,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
* this function returns NULL; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticNameForID
*/
@@ -1026,7 +1026,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);
*
* \returns true if the mouse is haptic or false if it isn't.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_OpenHapticFromMouse
*/
@@ -1038,7 +1038,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsMouseHaptic(void);
* \returns the haptic device identifier or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CloseHaptic
* \sa SDL_IsMouseHaptic
@@ -1051,7 +1051,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromMouse(void);
* \param joystick the SDL_Joystick to test for haptic capabilities.
* \returns true if the joystick is haptic or false if it isn't.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_OpenHapticFromJoystick
*/
@@ -1072,7 +1072,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickHaptic(SDL_Joystick *joystick);
* \returns a valid haptic device identifier on success or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CloseHaptic
* \sa SDL_IsJoystickHaptic
@@ -1084,7 +1084,7 @@ extern SDL_DECLSPEC SDL_Haptic * SDLCALL SDL_OpenHapticFromJoystick(SDL_Joystick
*
* \param haptic the SDL_Haptic device to close.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_OpenHaptic
*/
@@ -1101,7 +1101,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseHaptic(SDL_Haptic *haptic);
* \returns the number of effects the haptic device can store or a negative
* error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetMaxHapticEffectsPlaying
* \sa SDL_GetHapticFeatures
@@ -1117,7 +1117,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffects(SDL_Haptic *haptic);
* \returns the number of effects the haptic device can play at the same time
* or -1 on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetMaxHapticEffects
* \sa SDL_GetHapticFeatures
@@ -1131,7 +1131,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *hapti
* \returns a list of supported haptic features in bitwise manner (OR'd), or 0
* on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HapticEffectSupported
* \sa SDL_GetMaxHapticEffects
@@ -1148,7 +1148,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic);
* \returns the number of axes on success or -1 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic);
@@ -1159,7 +1159,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumHapticAxes(SDL_Haptic *haptic);
* \param effect the desired effect to query.
* \returns true if the effect is supported or false if it isn't.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CreateHapticEffect
* \sa SDL_GetHapticFeatures
@@ -1175,7 +1175,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HapticEffectSupported(SDL_Haptic *haptic, c
* \returns the ID of the effect on success or -1 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_DestroyHapticEffect
* \sa SDL_RunHapticEffect
@@ -1198,7 +1198,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CreateHapticEffect(SDL_Haptic *haptic, const
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CreateHapticEffect
* \sa SDL_RunHapticEffect
@@ -1221,7 +1221,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_UpdateHapticEffect(SDL_Haptic *haptic, int
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticEffectStatus
* \sa SDL_StopHapticEffect
@@ -1237,7 +1237,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int eff
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_RunHapticEffect
* \sa SDL_StopHapticEffects
@@ -1253,7 +1253,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffect(SDL_Haptic *haptic, int ef
* \param haptic the SDL_Haptic device to destroy the effect on.
* \param effect the ID of the haptic effect to destroy.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_CreateHapticEffect
*/
@@ -1269,7 +1269,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyHapticEffect(SDL_Haptic *haptic, int
* \returns true if it is playing, false if it isn't playing or haptic status
* isn't supported.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticFeatures
*/
@@ -1291,7 +1291,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetHapticEffectStatus(SDL_Haptic *haptic, i
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticFeatures
*/
@@ -1310,7 +1310,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticGain(SDL_Haptic *haptic, int gain)
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetHapticFeatures
*/
@@ -1329,7 +1329,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetHapticAutocenter(SDL_Haptic *haptic, int
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_ResumeHaptic
*/
@@ -1344,7 +1344,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PauseHaptic(SDL_Haptic *haptic);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PauseHaptic
*/
@@ -1357,7 +1357,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ResumeHaptic(SDL_Haptic *haptic);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_RunHapticEffect
* \sa SDL_StopHapticEffects
@@ -1370,7 +1370,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_StopHapticEffects(SDL_Haptic *haptic);
* \param haptic haptic device to check for rumble support.
* \returns true if the effect is supported or false if it isn't.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_InitHapticRumble
*/
@@ -1383,7 +1383,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HapticRumbleSupported(SDL_Haptic *haptic);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PlayHapticRumble
* \sa SDL_StopHapticRumble
@@ -1400,7 +1400,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_InitHapticRumble(SDL_Haptic *haptic);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_InitHapticRumble
* \sa SDL_StopHapticRumble
@@ -1414,7 +1414,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PlayHapticRumble(SDL_Haptic *haptic, float
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PlayHapticRumble
*/