gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> headers

Browse Source
This commit is contained in:
Ryan C. Gordon
2024-04-09 00:49:23 -04:00
parent ad090d2444
commit e044318a8e
33 changed files with 1510 additions and 909 deletions
Download Patch File Download Diff File Expand all files Collapse all files

406
include/SDL3/SDL_haptic.h
View File

@@ -163,128 +163,128 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
* Constant effect supported.
* Constant effect supported.
*
* Constant haptic effect.
* Constant haptic effect.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_CONSTANT (1u<<0)
/**
* Sine wave effect supported.
* Sine wave effect supported.
*
* Periodic haptic effect that simulates sine waves.
* Periodic haptic effect that simulates sine waves.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SINE (1u<<1)
/**
* Square wave effect supported.
* Square wave effect supported.
*
* Periodic haptic effect that simulates square waves.
* Periodic haptic effect that simulates square waves.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SQUARE (1<<2)
/**
* Triangle wave effect supported.
* Triangle wave effect supported.
*
* Periodic haptic effect that simulates triangular waves.
* Periodic haptic effect that simulates triangular waves.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_TRIANGLE (1u<<3)
/**
* Sawtoothup wave effect supported.
* Sawtoothup wave effect supported.
*
* Periodic haptic effect that simulates saw tooth up waves.
* Periodic haptic effect that simulates saw tooth up waves.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
/**
* Sawtoothdown wave effect supported.
* Sawtoothdown wave effect supported.
*
* Periodic haptic effect that simulates saw tooth down waves.
* Periodic haptic effect that simulates saw tooth down waves.
*
* \sa SDL_HapticPeriodic
* \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/**
* Ramp effect supported.
* Ramp effect supported.
*
* Ramp haptic effect.
* Ramp haptic effect.
*
* \sa SDL_HapticRamp
* \sa SDL_HapticRamp
*/
#define SDL_HAPTIC_RAMP (1u<<6)
/**
* Spring effect supported - uses axes position.
* Spring effect supported - uses axes position.
*
* Condition haptic effect that simulates a spring. Effect is based on the
* axes position.
* Condition haptic effect that simulates a spring. Effect is based on the
* axes position.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_SPRING (1u<<7)
/**
* Damper effect supported - uses axes velocity.
* Damper effect supported - uses axes velocity.
*
* Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity.
* Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_DAMPER (1u<<8)
/**
* Inertia effect supported - uses axes acceleration.
* Inertia effect supported - uses axes acceleration.
*
* Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration.
* Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_INERTIA (1u<<9)
/**
* Friction effect supported - uses axes movement.
* Friction effect supported - uses axes movement.
*
* Condition haptic effect that simulates friction. Effect is based on the
* axes movement.
* Condition haptic effect that simulates friction. Effect is based on the
* axes movement.
*
* \sa SDL_HapticCondition
* \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_FRICTION (1u<<10)
/**
* Left/Right effect supported.
* Left/Right effect supported.
*
* Haptic effect for direct control over high/low frequency motors.
* Haptic effect for direct control over high/low frequency motors.
*
* \sa SDL_HapticLeftRight
* \sa SDL_HapticLeftRight
*/
#define SDL_HAPTIC_LEFTRIGHT (1u<<11)
/**
* Reserved for future use
* Reserved for future use
*/
#define SDL_HAPTIC_RESERVED1 (1u<<12)
#define SDL_HAPTIC_RESERVED2 (1u<<13)
#define SDL_HAPTIC_RESERVED3 (1u<<14)
/**
* Custom effect is supported.
* Custom effect is supported.
*
* User defined custom haptic effect.
* User defined custom haptic effect.
*/
#define SDL_HAPTIC_CUSTOM (1u<<15)
@@ -293,39 +293,39 @@ typedef struct SDL_Haptic SDL_Haptic;
/* These last few are features the device has, not effects */
/**
* Device can set global gain.
* Device can set global gain.
*
* Device supports setting the global gain.
* Device supports setting the global gain.
*
* \sa SDL_SetHapticGain
* \sa SDL_SetHapticGain
*/
#define SDL_HAPTIC_GAIN (1u<<16)
/**
* Device can set autocenter.
* Device can set autocenter.
*
* Device supports setting autocenter.
* Device supports setting autocenter.
*
* \sa SDL_SetHapticAutocenter
* \sa SDL_SetHapticAutocenter
*/
#define SDL_HAPTIC_AUTOCENTER (1u<<17)
/**
* Device can be queried for effect status.
* Device can be queried for effect status.
*
* Device supports querying effect status.
* Device supports querying effect status.
*
* \sa SDL_GetHapticEffectStatus
* \sa SDL_GetHapticEffectStatus
*/
#define SDL_HAPTIC_STATUS (1u<<18)
/**
* Device can be paused.
* Device can be paused.
*
* Devices supports being paused.
* Devices supports being paused.
*
* \sa SDL_PauseHaptic
* \sa SDL_ResumeHaptic
* \sa SDL_PauseHaptic
* \sa SDL_ResumeHaptic
*/
#define SDL_HAPTIC_PAUSE (1u<<19)
@@ -336,31 +336,31 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
* Uses polar coordinates for the direction.
* Uses polar coordinates for the direction.
*
* \sa SDL_HapticDirection
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_POLAR 0
/**
* Uses cartesian coordinates for the direction.
* Uses cartesian coordinates for the direction.
*
* \sa SDL_HapticDirection
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_CARTESIAN 1
/**
* Uses spherical coordinates for the direction.
* Uses spherical coordinates for the direction.
*
* \sa SDL_HapticDirection
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_SPHERICAL 2
/**
* Use this value to play an effect on the steering wheel axis.
*
* This provides better compatibility across platforms and devices as SDL
* will guess the correct axis.
* This provides better compatibility across platforms and devices as SDL will
* guess the correct axis.
*
* \sa SDL_HapticDirection
*/
@@ -383,23 +383,23 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* Structure that represents a haptic direction.
* Structure that represents a haptic direction.
*
* This is the direction where the force comes from,
* instead of the direction in which the force is exerted.
* This is the direction where the force comes from, instead of the direction
* in which the force is exerted.
*
* Directions can be specified by:
* Directions can be specified by:
*
* - SDL_HAPTIC_POLAR : Specified by polar coordinates.
* - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
* - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
* - SDL_HAPTIC_POLAR : Specified by polar coordinates.
* - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
* - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
*
* Cardinal directions of the haptic device are relative to the positioning
* of the device. North is considered to be away from the user.
* Cardinal directions of the haptic device are relative to the positioning of
* the device. North is considered to be away from the user.
*
* The following diagram represents the cardinal directions:
* The following diagram represents the cardinal directions:
*
* ```
* ```
* .--.
* |__| .-------.
* |=.| |.-----.|
@@ -424,41 +424,41 @@ typedef struct SDL_Haptic SDL_Haptic;
* \|||/
* (o o)
* ---ooO-(_)-Ooo---
* ```
* ```
*
* If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
* degree starting north and turning clockwise. SDL_HAPTIC_POLAR only uses
* the first `dir` parameter. The cardinal directions would be:
* If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree
* starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first
* `dir` parameter. The cardinal directions would be:
*
* - North: 0 (0 degrees)
* - East: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - West: 27000 (270 degrees)
* - North: 0 (0 degrees)
* - East: 9000 (90 degrees)
* - South: 18000 (180 degrees)
* - West: 27000 (270 degrees)
*
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
* (X axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses
* the first three `dir` parameters. The cardinal directions would be:
* If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X
* axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first
* three `dir` parameters. The cardinal directions would be:
*
* - North: 0,-1, 0
* - East: 1, 0, 0
* - South: 0, 1, 0
* - West: -1, 0, 0
* - North: 0,-1, 0
* - East: 1, 0, 0
* - South: 0, 1, 0
* - West: -1, 0, 0
*
* The Z axis represents the height of the effect if supported, otherwise
* it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you
* can use any multiple you want, only the direction matters.
* The Z axis represents the height of the effect if supported, otherwise it's
* unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can
* use any multiple you want, only the direction matters.
*
* If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
* The first two `dir` parameters are used. The `dir` parameters are as
* follows (all values are in hundredths of degrees):
* If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The
* first two `dir` parameters are used. The `dir` parameters are as follows
* (all values are in hundredths of degrees):
*
* - Degrees from (1, 0) rotated towards (0, 1).
* - Degrees towards (0, 0, 1) (device needs at least 3 axes).
* - Degrees from (1, 0) rotated towards (0, 1).
* - Degrees towards (0, 0, 1) (device needs at least 3 axes).
*
* Example of force coming from the south with all encodings (force coming
* from the south means the user will have to pull the stick to counteract):
* Example of force coming from the south with all encodings (force coming
* from the south means the user will have to pull the stick to counteract):
*
* ```c
* ```c
* SDL_HapticDirection direction;
*
* // Cartesian directions
@@ -474,14 +474,14 @@ typedef struct SDL_Haptic SDL_Haptic;
* // Spherical coordinates
* direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
* direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
* ```
* ```
*
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
* \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
* \sa SDL_GetNumHapticAxes
* \sa SDL_HAPTIC_POLAR
* \sa SDL_HAPTIC_CARTESIAN
* \sa SDL_HAPTIC_SPHERICAL
* \sa SDL_HAPTIC_STEERING_AXIS
* \sa SDL_HapticEffect
* \sa SDL_GetNumHapticAxes
*/
typedef struct SDL_HapticDirection
{
@@ -491,15 +491,15 @@ typedef struct SDL_HapticDirection
/**
* A structure containing a template for a Constant effect.
* A structure containing a template for a Constant effect.
*
* This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
* This struct is exclusively for the SDL_HAPTIC_CONSTANT effect.
*
* A constant effect applies a constant force in the specified direction
* to the joystick.
* A constant effect applies a constant force in the specified direction to
* the joystick.
*
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_CONSTANT
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticConstant
{
@@ -526,32 +526,32 @@ typedef struct SDL_HapticConstant
} SDL_HapticConstant;
/**
* A structure containing a template for a Periodic effect.
* A structure containing a template for a Periodic effect.
*
* The struct handles the following effects:
* The struct handles the following effects:
*
* - SDL_HAPTIC_SINE
* - SDL_HAPTIC_SQUARE
* - SDL_HAPTIC_TRIANGLE
* - SDL_HAPTIC_SAWTOOTHUP
* - SDL_HAPTIC_SAWTOOTHDOWN
* - SDL_HAPTIC_SINE
* - SDL_HAPTIC_SQUARE
* - SDL_HAPTIC_TRIANGLE
* - SDL_HAPTIC_SAWTOOTHUP
* - SDL_HAPTIC_SAWTOOTHDOWN
*
* A periodic effect consists in a wave-shaped effect that repeats itself
* over time. The type determines the shape of the wave and the parameters
* determine the dimensions of the wave.
* A periodic effect consists in a wave-shaped effect that repeats itself over
* time. The type determines the shape of the wave and the parameters
* determine the dimensions of the wave.
*
* Phase is given by hundredth of a degree meaning that giving the phase a value
* of 9000 will displace it 25% of its period. Here are sample values:
* Phase is given by hundredth of a degree meaning that giving the phase a
* value of 9000 will displace it 25% of its period. Here are sample values:
*
* - 0: No phase displacement.
* - 9000: Displaced 25% of its period.
* - 18000: Displaced 50% of its period.
* - 27000: Displaced 75% of its period.
* - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
* - 0: No phase displacement.
* - 9000: Displaced 25% of its period.
* - 18000: Displaced 50% of its period.
* - 27000: Displaced 75% of its period.
* - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
*
* Examples:
* Examples:
*
* ```
* ```
* SDL_HAPTIC_SINE
* __ __ __ __
* / \ / \ / \ /
@@ -576,14 +576,14 @@ typedef struct SDL_HapticConstant
* \ |\ |\ |\ |\ |\ |\ |
* \ | \ | \ | \ | \ | \ | \ |
* \| \| \| \| \| \| \|
* ```
* ```
*
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_SQUARE
* \sa SDL_HAPTIC_TRIANGLE
* \sa SDL_HAPTIC_SAWTOOTHUP
* \sa SDL_HAPTIC_SAWTOOTHDOWN
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_SINE
* \sa SDL_HAPTIC_SQUARE
* \sa SDL_HAPTIC_TRIANGLE
* \sa SDL_HAPTIC_SAWTOOTHUP
* \sa SDL_HAPTIC_SAWTOOTHDOWN
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticPeriodic
{
@@ -615,29 +615,29 @@ typedef struct SDL_HapticPeriodic
} SDL_HapticPeriodic;
/**
* A structure containing a template for a Condition effect.
* A structure containing a template for a Condition effect.
*
* The struct handles the following effects:
* The struct handles the following effects:
*
* - SDL_HAPTIC_SPRING: Effect based on axes position.
* - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - SDL_HAPTIC_FRICTION: Effect based on axes movement.
* - SDL_HAPTIC_SPRING: Effect based on axes position.
* - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
* - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
* - SDL_HAPTIC_FRICTION: Effect based on axes movement.
*
* Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first
* refers to the X axis, the second refers to the Y axis and the third
* refers to the Z axis. The right terms refer to the positive side of the
* axis and the left terms refer to the negative side of the axis. Please
* refer to the SDL_HapticDirection diagram for which side is positive and
* which is negative.
* Direction is handled by condition internals instead of a direction member.
* The condition effect specific members have three parameters. The first
* refers to the X axis, the second refers to the Y axis and the third refers
* to the Z axis. The right terms refer to the positive side of the axis and
* the left terms refer to the negative side of the axis. Please refer to the
* SDL_HapticDirection diagram for which side is positive and which is
* negative.
*
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
* \sa SDL_HAPTIC_INERTIA
* \sa SDL_HAPTIC_FRICTION
* \sa SDL_HapticEffect
* \sa SDL_HapticDirection
* \sa SDL_HAPTIC_SPRING
* \sa SDL_HAPTIC_DAMPER
* \sa SDL_HAPTIC_INERTIA
* \sa SDL_HAPTIC_FRICTION
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticCondition
{
@@ -664,17 +664,17 @@ typedef struct SDL_HapticCondition
} SDL_HapticCondition;
/**
* A structure containing a template for a Ramp effect.
* A structure containing a template for a Ramp effect.
*
* This struct is exclusively for the SDL_HAPTIC_RAMP effect.
* This struct is exclusively for the SDL_HAPTIC_RAMP effect.
*
* The ramp effect starts at start strength and ends at end strength.
* It augments in linear fashion. If you use attack and fade with a ramp
* the effects get added to the ramp effect making the effect become
* quadratic instead of linear.
* The ramp effect starts at start strength and ends at end strength. It
* augments in linear fashion. If you use attack and fade with a ramp the
* effects get added to the ramp effect making the effect become quadratic
* instead of linear.
*
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_RAMP
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticRamp
{
@@ -727,19 +727,19 @@ typedef struct SDL_HapticLeftRight
} SDL_HapticLeftRight;
/**
* A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
* A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
*
* This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
* This struct is exclusively for the SDL_HAPTIC_CUSTOM effect.
*
* A custom force feedback effect is much like a periodic effect, where the
* application can define its exact shape. You will have to allocate the
* data yourself. Data should consist of channels * samples Uint16 samples.
* A custom force feedback effect is much like a periodic effect, where the
* application can define its exact shape. You will have to allocate the data
* yourself. Data should consist of channels * samples Uint16 samples.
*
* If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes.
* If channels is one, the effect is rotated using the defined direction.
* Otherwise it uses the samples in data for the different axes.
*
* \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect
* \sa SDL_HAPTIC_CUSTOM
* \sa SDL_HapticEffect
*/
typedef struct SDL_HapticCustom
{
@@ -769,28 +769,28 @@ typedef struct SDL_HapticCustom
} SDL_HapticCustom;
/**
* The generic template for any haptic effect.
* The generic template for any haptic effect.
*
* All values max at 32767 (0x7FFF). Signed values also can be negative.
* Time values unless specified otherwise are in milliseconds.
* All values max at 32767 (0x7FFF). Signed values also can be negative. Time
* values unless specified otherwise are in milliseconds.
*
* You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767
* value. Neither delay, interval, attack_length nor fade_length support
* SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
* You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
* Neither delay, interval, attack_length nor fade_length support
* SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends.
*
* Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
* SDL_HAPTIC_INFINITY.
* Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
* SDL_HAPTIC_INFINITY.
*
* Button triggers may not be supported on all devices, it is advised to not
* use them if possible. Buttons start at index 1 instead of index 0 like
* the joystick.
* Button triggers may not be supported on all devices, it is advised to not
* use them if possible. Buttons start at index 1 instead of index 0 like the
* joystick.
*
* If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used.
* If both attack_length and fade_level are 0, the envelope is not used,
* otherwise both values are used.
*
* Common parts:
* Common parts:
*
* ```c
* ```c
* // Replay - All effects have this
* Uint32 length; // Duration of effect (ms).
* Uint16 delay; // Delay before starting effect.
@@ -804,11 +804,11 @@ typedef struct SDL_HapticCustom
* Uint16 attack_level; // Level at the start of the attack.
* Uint16 fade_length; // Duration of the fade out (ms).
* Uint16 fade_level; // Level at the end of the fade.
* ```
* ```
*
* Here we have an example of a constant effect evolution in time:
* Here we have an example of a constant effect evolution in time:
*
* ```
* ```
* Strength
* ^
* |
@@ -826,17 +826,17 @@ typedef struct SDL_HapticCustom
*
* [------------------][-----------------------]
* delay length
* ```
* ```
*
* Note either the attack_level or the fade_level may be above the actual
* effect level.
* Note either the attack_level or the fade_level may be above the actual
* effect level.
*
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition
* \sa SDL_HapticRamp
* \sa SDL_HapticLeftRight
* \sa SDL_HapticCustom
* \sa SDL_HapticConstant
* \sa SDL_HapticPeriodic
* \sa SDL_HapticCondition
* \sa SDL_HapticRamp
* \sa SDL_HapticLeftRight
* \sa SDL_HapticCustom
*/
typedef union SDL_HapticEffect
{