/*
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
*
/**
* \brief Device can be queried for effect status.
*
- * Device can be queried for effect status.
+ * Device supports querying effect status.
*
* \sa SDL_HapticGetEffectStatus
*/
/**
* \brief Device can be paused.
*
+ * Devices supports being paused.
+ *
* \sa SDL_HapticPause
* \sa SDL_HapticUnpause
*/
/**
* \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: */