mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-10-17 15:21:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL2 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot
2024-06-14 06:11:54 +00:00
parent 169f77ed5e
commit 143d5d779c
41 changed files with 1150 additions and 1138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
include/SDL_gamecontroller.h
View File

@@ -154,8 +154,8 @@ typedef struct SDL_GameControllerButtonBind
* processing it, so take this into consideration if you are in a memory
* constrained environment.
*
* \param rw the data stream for the mappings to be added
* \param freerw non-zero to close the stream after being read
* \param rw the data stream for the mappings to be added.
* \param freerw non-zero to close the stream after being read.
* \returns the number of mappings added or -1 on error; call SDL_GetError()
* for more information.
*
@@ -193,7 +193,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
* "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
* ```
*
* \param mappingString the mapping string
* \param mappingString the mapping string.
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information.
*
@@ -228,7 +228,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind
*
* The returned string must be freed with SDL_free().
*
* \param guid a structure containing the GUID for which a mapping is desired
* \param guid a structure containing the GUID for which a mapping is desired.
* \returns a mapping string or NULL on error; call SDL_GetError() for more
* information.
*
@@ -247,7 +247,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID
* Details about mappings are discussed with SDL_GameControllerAddMapping().
*
* \param gamecontroller the game controller you want to get the current
* mapping for
* mapping for.
* \returns a string that has the controller's mapping or NULL if no mapping
* is available; call SDL_GetError() for more information.
*
@@ -265,7 +265,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam
* SDL_JoystickOpen().
*
* \param joystick_index the device_index of a device, up to
* SDL_NumJoysticks()
* SDL_NumJoysticks().
* \returns SDL_TRUE if the given joystick is supported by the game controller
* interface, SDL_FALSE if it isn't or it's an invalid index.
*
@@ -285,7 +285,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index);
* SDL_JoystickOpen().
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* SDL_NumJoysticks()-1.
* \returns the implementation-dependent name for the game controller, or NULL
* if there is no name or the index is invalid.
*
@@ -306,7 +306,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_
* SDL_JoystickOpen().
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* SDL_NumJoysticks()-1.
* \returns the implementation-dependent path for the game controller, or NULL
* if there is no path or the index is invalid.
*
@@ -322,7 +322,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_
* This can be called before any controllers are opened.
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* SDL_NumJoysticks()-1.
* \returns the controller type.
*
* \since This function is available since SDL 2.0.12.
@@ -335,7 +335,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in
* This can be called before any controllers are opened.
*
* \param joystick_index the device_index of a device, from zero to
* SDL_NumJoysticks()-1
* SDL_NumJoysticks()-1.
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* no mapping is available.
*
@@ -355,7 +355,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti
* be used there instead.
*
* \param joystick_index the device_index of a device, up to
* SDL_NumJoysticks()
* SDL_NumJoysticks().
* \returns a gamecontroller identifier or NULL if an error occurred; call
* SDL_GetError() for more information.
*
@@ -370,7 +370,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_
/**
* Get the SDL_GameController associated with an instance id.
*
* \param joyid the instance id to get the SDL_GameController for
* \param joyid the instance id to get the SDL_GameController for.
* \returns an SDL_GameController on success or NULL on failure; call
* SDL_GetError() for more information.
*
@@ -402,7 +402,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in
* it takes a controller identifier instead of the (unstable) device index.
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* SDL_GameControllerOpen().
* \returns the implementation dependent name for the game controller, or NULL
* if there is no name or the identifier passed is invalid.
*
@@ -420,7 +420,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g
* it takes a controller identifier instead of the (unstable) device index.
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* SDL_GameControllerOpen().
* \returns the implementation dependent path for the game controller, or NULL
* if there is no path or the identifier passed is invalid.
*
@@ -545,7 +545,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameControll
* Check if a controller has been opened and is currently connected.
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* SDL_GameControllerOpen().
* \returns SDL_TRUE if the controller has been opened and is currently
* connected, or SDL_FALSE if not.
*
@@ -570,7 +570,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle
* cause SDL to crash.
*
* \param gamecontroller the game controller object that you want to get a
* joystick from
* joystick from.
* \returns a SDL_Joystick object; call SDL_GetError() for more information.
*
* \since This function is available since SDL 2.0.0.
@@ -587,7 +587,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont
* Any number can be passed to SDL_GameControllerEventState(), but only -1, 0,
* and 1 will have any effect. Other numbers will just be returned.
*
* \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`
* \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`.
* \returns the same value passed to the function, with exception to -1
* (SDL_QUERY), which will return the current state.
*
@@ -646,7 +646,7 @@ typedef enum SDL_GameControllerAxis
* `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`,
* respectively.
*
* \param str string representing a SDL_GameController axis
* \param str string representing a SDL_GameController axis.
* \returns the SDL_GameControllerAxis enum corresponding to the input string,
* or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
@@ -661,7 +661,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri
*
* The caller should not SDL_free() the returned string.
*
* \param axis an enum value for a given SDL_GameControllerAxis
* \param axis an enum value for a given SDL_GameControllerAxis.
* \returns a string for the given axis, or NULL if an invalid axis is
* specified. The string returned is of the format used by
* SDL_GameController mapping strings.
@@ -675,8 +675,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC
/**
* Get the SDL joystick layer binding for a controller axis mapping.
*
* \param gamecontroller a game controller
* \param axis an axis enum value (one of the SDL_GameControllerAxis values)
* \param gamecontroller a game controller.
* \param axis an axis enum value (one of the SDL_GameControllerAxis values).
* \returns a SDL_GameControllerButtonBind describing the bind. On failure
* (like the given Controller axis doesn't exist on the device), its
* `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -695,8 +695,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller,
* This merely reports whether the controller's mapping defined this axis, as
* that is all the information SDL has about the physical device.
*
* \param gamecontroller a game controller
* \param axis an axis enum value (an SDL_GameControllerAxis value)
* \param gamecontroller a game controller.
* \param axis an axis enum value (an SDL_GameControllerAxis value).
* \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.14.
@@ -716,8 +716,8 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController
* return a negative value. Note that this differs from the value reported by
* the lower-level SDL_GetJoystickAxis(), which normally uses the full range.
*
* \param gamecontroller a game controller
* \param axis an axis index (one of the SDL_GameControllerAxis values)
* \param gamecontroller a game controller.
* \param axis an axis index (one of the SDL_GameControllerAxis values).
* \returns axis state (including 0) on success or 0 (also) on failure; call
* SDL_GetError() for more information.
*
@@ -766,7 +766,7 @@ typedef enum SDL_GameControllerButton
* SDL_GameController mapping. You do not normally need to call this function
* unless you are parsing SDL_GameController mappings in your own code.
*
* \param str string representing a SDL_GameController axis
* \param str string representing a SDL_GameController axis.
* \returns the SDL_GameControllerButton enum corresponding to the input
* string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found.
*
@@ -779,7 +779,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom
*
* The caller should not SDL_free() the returned string.
*
* \param button an enum value for a given SDL_GameControllerButton
* \param button an enum value for a given SDL_GameControllerButton.
* \returns a string for the given button, or NULL if an invalid button is
* specified. The string returned is of the format used by
* SDL_GameController mapping strings.
@@ -793,8 +793,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam
/**
* Get the SDL joystick layer binding for a controller button mapping.
*
* \param gamecontroller a game controller
* \param button an button enum value (an SDL_GameControllerButton value)
* \param gamecontroller a game controller.
* \param button an button enum value (an SDL_GameControllerButton value).
* \returns a SDL_GameControllerButtonBind describing the bind. On failure
* (like the given Controller button doesn't exist on the device),
* its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`.
@@ -813,8 +813,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller,
* This merely reports whether the controller's mapping defined this button,
* as that is all the information SDL has about the physical device.
*
* \param gamecontroller a game controller
* \param button a button enum value (an SDL_GameControllerButton value)
* \param gamecontroller a game controller.
* \param button a button enum value (an SDL_GameControllerButton value).
* \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.14.
@@ -825,8 +825,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController
/**
* Get the current state of a button on a game controller.
*
* \param gamecontroller a game controller
* \param button a button index (one of the SDL_GameControllerButton values)
* \param gamecontroller a game controller.
* \param button a button index (one of the SDL_GameControllerButton values).
* \returns 1 for pressed state or 0 for not pressed state or error; call
* SDL_GetError() for more information.
*
@@ -862,8 +862,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll
/**
* Return whether a game controller has a particular sensor.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
* \param gamecontroller The controller to query.
* \param type The type of sensor to query.
* \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.14.
@@ -873,9 +873,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController
/**
* Set whether data reporting for a game controller sensor is enabled.
*
* \param gamecontroller The controller to update
* \param type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled
* \param gamecontroller The controller to update.
* \param type The type of sensor to enable/disable.
* \param enabled Whether data reporting should be enabled.
* \returns 0 or -1 if an error occurred.
*
* \since This function is available since SDL 2.0.14.
@@ -885,8 +885,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle
/**
* Query whether sensor data reporting is enabled for a game controller.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
* \param gamecontroller The controller to query.
* \param type The type of sensor to query.
* \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise.
*
* \since This function is available since SDL 2.0.14.
@@ -897,8 +897,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr
* Get the data rate (number of events per second) of a game controller
* sensor.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
* \param gamecontroller The controller to query.
* \param type The type of sensor to query.
* \return the data rate, or 0.0f if the data rate is not available.
*
* \since This function is available since SDL 2.0.16.
@@ -911,10 +911,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro
* The number of values and interpretation of the data is sensor dependent.
* See SDL_sensor.h for the details for each type of sensor.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
* \param gamecontroller The controller to query.
* \param type The type of sensor to query.
* \param data A pointer filled with the current sensor state.
* \param num_values The number of values to write to data.
* \return 0 or -1 if an error occurred.
*
* \since This function is available since SDL 2.0.14.
@@ -928,12 +928,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController *
* The number of values and interpretation of the data is sensor dependent.
* See SDL_sensor.h for the details for each type of sensor.
*
* \param gamecontroller The controller to query
* \param type The type of sensor to query
* \param gamecontroller The controller to query.
* \param type The type of sensor to query.
* \param timestamp A pointer filled with the timestamp in microseconds of the
* current sensor reading if available, or 0 if not
* \param data A pointer filled with the current sensor state
* \param num_values The number of values to write to data
* current sensor reading if available, or 0 if not.
* \param data A pointer filled with the current sensor state.
* \param num_values The number of values to write to data.
* \return 0 or -1 if an error occurred.
*
* \since This function is available since SDL 2.26.0.
@@ -946,13 +946,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam
* Each call to this function cancels any previous rumble effect, and calling
* it with 0 intensity stops any rumbling.
*
* \param gamecontroller The controller to vibrate
* \param gamecontroller The controller to vibrate.
* \param low_frequency_rumble The intensity of the low frequency (left)
* rumble motor, from 0 to 0xFFFF
* rumble motor, from 0 to 0xFFFF.
* \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
* \returns 0, or -1 if rumble isn't supported on this controller
* rumble motor, from 0 to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds.
* \returns 0, or -1 if rumble isn't supported on this controller.
*
* \since This function is available since SDL 2.0.9.
*
@@ -971,13 +971,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon
* want the (more common) whole-controller rumble, use
* SDL_GameControllerRumble() instead.
*
* \param gamecontroller The controller to vibrate
* \param gamecontroller The controller to vibrate.
* \param left_rumble The intensity of the left trigger rumble motor, from 0
* to 0xFFFF
* to 0xFFFF.
* \param right_rumble The intensity of the right trigger rumble motor, from 0
* to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
* \returns 0, or -1 if trigger rumble isn't supported on this controller
* to 0xFFFF.
* \param duration_ms The duration of the rumble effect, in milliseconds.
* \returns 0, or -1 if trigger rumble isn't supported on this controller.
*
* \since This function is available since SDL 2.0.14.
*
@@ -988,9 +988,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController
/**
* Query whether a game controller has an LED.
*
* \param gamecontroller The controller to query
* \param gamecontroller The controller to query.
* \returns SDL_TRUE, or SDL_FALSE if this controller does not have a
* modifiable LED
* modifiable LED.
*
* \since This function is available since SDL 2.0.14.
*/
@@ -999,9 +999,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga
/**
* Query whether a game controller has rumble support.
*
* \param gamecontroller The controller to query
* \param gamecontroller The controller to query.
* \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble
* support
* support.
*
* \since This function is available since SDL 2.0.18.
*
@@ -1012,9 +1012,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController
/**
* Query whether a game controller has rumble support on triggers.
*
* \param gamecontroller The controller to query
* \param gamecontroller The controller to query.
* \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger
* rumble support
* rumble support.
*
* \since This function is available since SDL 2.0.18.
*
@@ -1025,11 +1025,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon
/**
* Update a game controller's LED color.
*
* \param gamecontroller The controller to update
* \param red The intensity of the red LED
* \param green The intensity of the green LED
* \param blue The intensity of the blue LED
* \returns 0, or -1 if this controller does not have a modifiable LED
* \param gamecontroller The controller to update.
* \param red The intensity of the red LED.
* \param green The intensity of the green LED.
* \param blue The intensity of the blue LED.
* \returns 0, or -1 if this controller does not have a modifiable LED.
*
* \since This function is available since SDL 2.0.14.
*/
@@ -1038,11 +1038,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon
/**
* Send a controller specific effect packet
*
* \param gamecontroller The controller to affect
* \param data The data to send to the controller
* \param size The size of the data to send to the controller
* \param gamecontroller The controller to affect.
* \param data The data to send to the controller.
* \param size The size of the data to send to the controller.
* \returns 0, or -1 if this controller or driver doesn't support effect
* packets
* packets.
*
* \since This function is available since SDL 2.0.16.
*/
@@ -1052,7 +1052,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam
* Close a game controller previously opened with SDL_GameControllerOpen().
*
* \param gamecontroller a game controller identifier previously returned by
* SDL_GameControllerOpen()
* SDL_GameControllerOpen().
*
* \since This function is available since SDL 2.0.0.
*
@@ -1064,9 +1064,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon
* Return the sfSymbolsName for a given button on a game controller on Apple
* platforms.
*
* \param gamecontroller the controller to query
* \param button a button on the game controller
* \returns the sfSymbolsName or NULL if the name can't be found
* \param gamecontroller the controller to query.
* \param button a button on the game controller.
* \returns the sfSymbolsName or NULL if the name can't be found.
*
* \since This function is available since SDL 2.0.18.
*
@@ -1078,9 +1078,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu
* Return the sfSymbolsName for a given axis on a game controller on Apple
* platforms.
*
* \param gamecontroller the controller to query
* \param axis an axis on the game controller
* \returns the sfSymbolsName or NULL if the name can't be found
* \param gamecontroller the controller to query.
* \param axis an axis on the game controller.
* \returns the sfSymbolsName or NULL if the name can't be found.
*
* \since This function is available since SDL 2.0.18.
*