/*
Simple DirectMedia Layer
- Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
+ Copyright (C) 1997-2019 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
/**
* \file SDL_haptic.h
*
- * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
+ * \brief The SDL haptic subsystem allows you to control haptic (force feedback)
* devices.
*
* The basic usage is as follows:
- * - Initialize the Subsystem (::SDL_INIT_HAPTIC).
- * - Open a Haptic Device.
+ * - Initialize the subsystem (::SDL_INIT_HAPTIC).
+ * - Open a haptic device.
* - SDL_HapticOpen() to open from index.
* - SDL_HapticOpenFromJoystick() to open from an existing joystick.
* - Create an effect (::SDL_HapticEffect).
* \endcode
*/
-#ifndef _SDL_haptic_h
-#define _SDL_haptic_h
+#ifndef SDL_haptic_h_
+#define SDL_haptic_h_
#include "SDL_stdinc.h"
#include "SDL_error.h"
extern "C" {
#endif /* __cplusplus */
+/* FIXME: For SDL 2.1, adjust all the magnitude variables to be Uint16 (0xFFFF).
+ *
+ * At the moment the magnitude variables are mixed between signed/unsigned, and
+ * it is also not made clear that ALL of those variables expect a max of 0x7FFF.
+ *
+ * Some platforms may have higher precision than that (Linux FF, Windows XInput)
+ * so we should fix the inconsistency in favor of higher possible precision,
+ * adjusting for platforms that use different scales.
+ * -flibit
+ */
+
/**
* \typedef SDL_Haptic
*
*
* \sa SDL_HapticCondition
*/
-#define SDL_HAPTIC_CONSTANT (1<<0)
+#define SDL_HAPTIC_CONSTANT (1u<<0)
/**
* \brief Sine wave effect supported.
*
* \sa SDL_HapticPeriodic
*/
-#define SDL_HAPTIC_SINE (1<<1)
+#define SDL_HAPTIC_SINE (1u<<1)
/**
* \brief Left/Right effect supported.
* \warning this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry,
* we ran out of bits, and this is important for XInput devices.
*/
-#define SDL_HAPTIC_LEFTRIGHT (1<<2)
+#define SDL_HAPTIC_LEFTRIGHT (1u<<2)
/* !!! FIXME: put this back when we have more bits in 2.1 */
/* #define SDL_HAPTIC_SQUARE (1<<2) */
*
* \sa SDL_HapticPeriodic
*/
-#define SDL_HAPTIC_TRIANGLE (1<<3)
+#define SDL_HAPTIC_TRIANGLE (1u<<3)
/**
* \brief Sawtoothup wave effect supported.
*
* \sa SDL_HapticPeriodic
*/
-#define SDL_HAPTIC_SAWTOOTHUP (1<<4)
+#define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
/**
* \brief Sawtoothdown wave effect supported.
*
* \sa SDL_HapticPeriodic
*/
-#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
+#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/**
* \brief Ramp effect supported.
*
* \sa SDL_HapticRamp
*/
-#define SDL_HAPTIC_RAMP (1<<6)
+#define SDL_HAPTIC_RAMP (1u<<6)
/**
* \brief Spring effect supported - uses axes position.
*
* \sa SDL_HapticCondition
*/
-#define SDL_HAPTIC_SPRING (1<<7)
+#define SDL_HAPTIC_SPRING (1u<<7)
/**
* \brief Damper effect supported - uses axes velocity.
*
* \sa SDL_HapticCondition
*/
-#define SDL_HAPTIC_DAMPER (1<<8)
+#define SDL_HAPTIC_DAMPER (1u<<8)
/**
* \brief Inertia effect supported - uses axes acceleration.
*
* \sa SDL_HapticCondition
*/
-#define SDL_HAPTIC_INERTIA (1<<9)
+#define SDL_HAPTIC_INERTIA (1u<<9)
/**
* \brief Friction effect supported - uses axes movement.
*
* \sa SDL_HapticCondition
*/
-#define SDL_HAPTIC_FRICTION (1<<10)
+#define SDL_HAPTIC_FRICTION (1u<<10)
/**
* \brief Custom effect is supported.
*
* User defined custom haptic effect.
*/
-#define SDL_HAPTIC_CUSTOM (1<<11)
+#define SDL_HAPTIC_CUSTOM (1u<<11)
/* @} *//* Haptic effects */
*
* \sa SDL_HapticSetGain
*/
-#define SDL_HAPTIC_GAIN (1<<12)
+#define SDL_HAPTIC_GAIN (1u<<12)
/**
* \brief Device can set autocenter.
*
* \sa SDL_HapticSetAutocenter
*/
-#define SDL_HAPTIC_AUTOCENTER (1<<13)
+#define SDL_HAPTIC_AUTOCENTER (1u<<13)
/**
* \brief Device can be queried for effect status.
*
- * Device can be queried for effect status.
+ * Device supports querying effect status.
*
* \sa SDL_HapticGetEffectStatus
*/
-#define SDL_HAPTIC_STATUS (1<<14)
+#define SDL_HAPTIC_STATUS (1u<<14)
/**
* \brief Device can be paused.
*
+ * Devices supports being paused.
+ *
* \sa SDL_HapticPause
* \sa SDL_HapticUnpause
*/
-#define SDL_HAPTIC_PAUSE (1<<15)
+#define SDL_HAPTIC_PAUSE (1u<<15)
/**
/**
* \brief A structure containing a template for a Constant effect.
*
- * The struct is exclusive to 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.
* This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
*
* The Left/Right effect is used to explicitly control the large and small
- * motors, commonly found in modern game controllers. One motor is high
- * frequency, the other is low frequency.
+ * motors, commonly found in modern game controllers. The small (right) motor
+ * is high frequency, and the large (left) motor is low frequency.
*
* \sa SDL_HAPTIC_LEFTRIGHT
* \sa SDL_HapticEffect
Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */
/* Replay */
- Uint32 length; /**< Duration of the effect. */
+ Uint32 length; /**< Duration of the effect in milliseconds. */
/* Rumble */
Uint16 large_magnitude; /**< Control of the large controller motor. */
/**
* \brief A structure containing a template 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.
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
/**
- * \brief Get the implementation dependent name of a Haptic device.
+ * \brief Get the implementation dependent name of a haptic device.
*
* This can be called before any joysticks are opened.
* If no name can be found, this function returns NULL.
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
/**
- * \brief Opens a Haptic device for usage.
+ * \brief Opens a haptic device for use.
*
- * The index passed as an argument refers to the N'th Haptic device on this
+ * The index passed as an argument refers to the N'th haptic device on this
* system.
*
* When opening a haptic device, its gain will be set to maximum and
* \brief Checks to see if a joystick has haptic features.
*
* \param joystick Joystick to test for haptic capabilities.
- * \return 1 if the joystick is haptic, 0 if it isn't
- * or -1 if an error ocurred.
+ * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
+ * or -1 if an error occurred.
*
* \sa SDL_HapticOpenFromJoystick
*/
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
/**
- * \brief Opens a Haptic device for usage from a Joystick device.
+ * \brief Opens a haptic device for use from a joystick device.
*
* You must still close the haptic device separately. It will not be closed
* with the joystick.
joystick);
/**
- * \brief Closes a Haptic device previously opened with SDL_HapticOpen().
+ * \brief Closes a haptic device previously opened with SDL_HapticOpen().
*
* \param haptic Haptic device to close.
*/
* Example:
* \code
* if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
- * printf("We have constant haptic effect!");
+ * printf("We have constant haptic effect!\n");
* }
* \endcode
*
*
* \param haptic Haptic device to create the effect on.
* \param effect Properties of the effect to create.
- * \return The id of the effect on success or -1 on error.
+ * \return The identifier of the effect on success or -1 on error.
*
* \sa SDL_HapticUpdateEffect
* \sa SDL_HapticRunEffect
/**
* \brief Updates the properties of an effect.
*
- * Can be used dynamically, although behaviour when dynamically changing
+ * Can be used dynamically, although behavior when dynamically changing
* direction may be strange. Specifically the effect may reupload itself
* and start playing from the start. You cannot change the type either when
* running SDL_HapticUpdateEffect().
*
* \param haptic Haptic device that has the effect.
- * \param effect Effect to update.
+ * \param effect Identifier of the effect to update.
* \param data New effect properties to use.
* \return 0 on success or -1 on error.
*
#endif
#include "close_code.h"
-#endif /* _SDL_haptic_h */
+#endif /* SDL_haptic_h_ */
/* vi: set ts=4 sw=4 expandtab: */
projects / xonotic / xonotic.git / blobdiff