/*

  Simple DirectMedia Layer

  Copyright (C) 1997-2014 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

  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,

  including commercial applications, and to alter it and redistribute it

  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not

     claim that you wrote the original software. If you use this software

     in a product, an acknowledgment in the product documentation would be

     appreciated but is not required.

  2. Altered source versions must be plainly marked as such, and must not be

     misrepresented as being the original software.

  3. This notice may not be removed or altered from any source distribution.

*/

/**

 *  \file SDL_haptic.h

 *

 *  \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.

 *    - SDL_HapticOpen() to open from index.

 *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.

 *   - Create an effect (::SDL_HapticEffect).

 *   - Upload the effect with SDL_HapticNewEffect().

 *   - Run the effect with SDL_HapticRunEffect().

 *   - (optional) Free the effect with SDL_HapticDestroyEffect().

 *   - Close the haptic device with SDL_HapticClose().

 *

 * \par Simple rumble example:

 * \code

 *    SDL_Haptic *haptic;

 *

 *    // Open the device

 *    haptic = SDL_HapticOpen( 0 );

 *    if (haptic == NULL)

 *       return -1;

 *

 *    // Initialize simple rumble

 *    if (SDL_HapticRumbleInit( haptic ) != 0)

 *       return -1;

 *

 *    // Play effect at 50% strength for 2 seconds

 *    if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)

 *       return -1;

 *    SDL_Delay( 2000 );

 *

 *    // Clean up

 *    SDL_HapticClose( haptic );

 * \endcode

 *

 * \par Complete example:

 * \code

 * int test_haptic( SDL_Joystick * joystick ) {

 *    SDL_Haptic *haptic;

 *    SDL_HapticEffect effect;

 *    int effect_id;

 *

 *    // Open the device

 *    haptic = SDL_HapticOpenFromJoystick( joystick );

 *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic

 *

 *    // See if it can do sine waves

 *    if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {

 *       SDL_HapticClose(haptic); // No sine effect

 *       return -1;

 *    }

 *

 *    // Create the effect

 *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default

 *    effect.type = SDL_HAPTIC_SINE;

 *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates

 *    effect.periodic.direction.dir[0] = 18000; // Force comes from south

 *    effect.periodic.period = 1000; // 1000 ms

 *    effect.periodic.magnitude = 20000; // 20000/32767 strength

 *    effect.periodic.length = 5000; // 5 seconds long

 *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength

 *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away

 *

 *    // Upload the effect

 *    effect_id = SDL_HapticNewEffect( haptic, &effect );

 *

 *    // Test the effect

 *    SDL_HapticRunEffect( haptic, effect_id, 1 );

 *    SDL_Delay( 5000); // Wait for the effect to finish

 *

 *    // We destroy the effect, although closing the device also does this

 *    SDL_HapticDestroyEffect( haptic, effect_id );

 *

 *    // Close the device

 *    SDL_HapticClose(haptic);

 *

 *    return 0; // Success

 * }

 * \endcode

 *

 * You can also find out more information on my blog:

 * http://bobbens.dyndns.org/journal/2010/sdl_haptic/

 *

 * \author Edgar Simo Serra

 */

#ifndef _SDL_haptic_h

#define _SDL_haptic_h

#include "SDL_stdinc.h"

#include "SDL_error.h"

#include "SDL_joystick.h"

#include "begin_code.h"

/* Set up for C function definitions, even when using C++ */

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

/**

 *  \typedef SDL_Haptic

 *

 *  \brief The haptic structure used to identify an SDL haptic.

 *

 *  \sa SDL_HapticOpen

 *  \sa SDL_HapticOpenFromJoystick

 *  \sa SDL_HapticClose

 */

struct _SDL_Haptic;

typedef struct _SDL_Haptic SDL_Haptic;

/**

 *  \name Haptic features

 *

 *  Different haptic features a device can have.

 */

/* @{ */

/**

 *  \name Haptic effects

 */

/* @{ */

/**

 *  \brief Constant effect supported.

 *

 *  Constant haptic effect.

 *

 *  \sa SDL_HapticCondition

 */

#define SDL_HAPTIC_CONSTANT   (1<<0)

/**

 *  \brief Sine wave effect supported.

 *

 *  Periodic haptic effect that simulates sine waves.

 *

 *  \sa SDL_HapticPeriodic

 */

#define SDL_HAPTIC_SINE       (1<<1)

/**

 *  \brief Left/Right effect supported.

 *

 *  Haptic effect for direct control over high/low frequency motors.

 *

 *  \sa SDL_HapticLeftRight

 * \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)

/* !!! FIXME: put this back when we have more bits in 2.1 */

/* #define SDL_HAPTIC_SQUARE     (1<<2) */

/**

 *  \brief Triangle wave effect supported.

 *

 *  Periodic haptic effect that simulates triangular waves.

 *

 *  \sa SDL_HapticPeriodic

 */

#define SDL_HAPTIC_TRIANGLE   (1<<3)

/**

 *  \brief Sawtoothup wave effect supported.

 *

 *  Periodic haptic effect that simulates saw tooth up waves.

 *

 *  \sa SDL_HapticPeriodic

 */

#define SDL_HAPTIC_SAWTOOTHUP (1<<4)

/**

 *  \brief Sawtoothdown wave effect supported.

 *

 *  Periodic haptic effect that simulates saw tooth down waves.

 *

 *  \sa SDL_HapticPeriodic

 */

#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)

/**

 *  \brief Ramp effect supported.

 *

 *  Ramp haptic effect.

 *

 *  \sa SDL_HapticRamp

 */

#define SDL_HAPTIC_RAMP       (1<<6)

/**

 *  \brief Spring effect supported - uses axes position.

 *

 *  Condition haptic effect that simulates a spring.  Effect is based on the

 *  axes position.

 *

 *  \sa SDL_HapticCondition

 */

#define SDL_HAPTIC_SPRING     (1<<7)

/**

 *  \brief Damper effect supported - uses axes velocity.

 *

 *  Condition haptic effect that simulates dampening.  Effect is based on the

 *  axes velocity.

 *

 *  \sa SDL_HapticCondition

 */

#define SDL_HAPTIC_DAMPER     (1<<8)

/**

 *  \brief Inertia effect supported - uses axes acceleration.

 *

 *  Condition haptic effect that simulates inertia.  Effect is based on the axes

 *  acceleration.

 *

 *  \sa SDL_HapticCondition

 */

#define SDL_HAPTIC_INERTIA    (1<<9)

/**

 *  \brief Friction effect supported - uses axes movement.

 *

 *  Condition haptic effect that simulates friction.  Effect is based on the

 *  axes movement.

 *

 *  \sa SDL_HapticCondition

 */

#define SDL_HAPTIC_FRICTION   (1<<10)

/**

 *  \brief Custom effect is supported.

 *

 *  User defined custom haptic effect.

 */

#define SDL_HAPTIC_CUSTOM     (1<<11)

/* @} *//* Haptic effects */

/* These last few are features the device has, not effects */

/**

 *  \brief Device can set global gain.

 *

 *  Device supports setting the global gain.

 *

 *  \sa SDL_HapticSetGain

 */

#define SDL_HAPTIC_GAIN       (1<<12)

/**

 *  \brief Device can set autocenter.

 *

 *  Device supports setting autocenter.

 *

 *  \sa SDL_HapticSetAutocenter

 */

#define SDL_HAPTIC_AUTOCENTER (1<<13)

/**

 *  \brief Device can be queried for effect status.

 *

 *  Device can be queried for effect status.

 *

 *  \sa SDL_HapticGetEffectStatus

 */

#define SDL_HAPTIC_STATUS     (1<<14)

/**

 *  \brief Device can be paused.

 *

 *  \sa SDL_HapticPause

 *  \sa SDL_HapticUnpause

 */

#define SDL_HAPTIC_PAUSE      (1<<15)

/**

 * \name Direction encodings

 */

/* @{ */

/**

 *  \brief Uses polar coordinates for the direction.

 *

 *  \sa SDL_HapticDirection

 */

#define SDL_HAPTIC_POLAR      0

/**

 *  \brief Uses cartesian coordinates for the direction.

 *

 *  \sa SDL_HapticDirection

 */

#define SDL_HAPTIC_CARTESIAN  1

/**

 *  \brief Uses spherical coordinates for the direction.

 *

 *  \sa SDL_HapticDirection

 */

#define SDL_HAPTIC_SPHERICAL  2

/* @} *//* Direction encodings */

/* @} *//* Haptic features */

/*

 * Misc defines.

 */

/**

 * \brief Used to play a device an infinite number of times.

 *

 * \sa SDL_HapticRunEffect

 */

#define SDL_HAPTIC_INFINITY   4294967295U

/**

 *  \brief Structure that represents a haptic direction.

 *

 *  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.

 *

 *  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:

 *  \verbatim

                 .--.

                 |__| .-------.

                 |=.| |.-----.|

                 |--| ||     ||

                 |  | |'-----'|

                 |__|~')_____('

                   [ COMPUTER ]

                     North (0,-1)

                         ^

                         |

                         |

   (-1,0)  West <----[ HAPTIC ]----> East (1,0)

                         |

                         |

                         v

                      South (0,1)

                      [ USER ]

                        \|||/

                        (o o)

                  ---ooO-(_)-Ooo---

    \endverbatim

 *

 *  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 \c dir parameter.  The cardinal directions would be:

 *   - 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 \c dir parameters.  The cardinal directions would be:

 *   - 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.

 *

 *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.

 *  The first two \c dir parameters are used.  The \c 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).

 *

 *

 *  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):

 *  \code

 *  SDL_HapticDirection direction;

 *

 *  // Cartesian directions

 *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.

 *  direction.dir[0] = 0; // X position

 *  direction.dir[1] = 1; // Y position

 *  // Assuming the device has 2 axes, we don't need to specify third parameter.

 *

 *  // Polar directions

 *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.

 *  direction.dir[0] = 18000; // Polar only uses first parameter

 *

 *  // 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.

 *  \endcode

 *

 *  \sa SDL_HAPTIC_POLAR

 *  \sa SDL_HAPTIC_CARTESIAN

 *  \sa SDL_HAPTIC_SPHERICAL

 *  \sa SDL_HapticEffect

 *  \sa SDL_HapticNumAxes

 */

typedef struct SDL_HapticDirection

{

    Uint8 type;         /**< The type of encoding. */

    Sint32 dir[3];      /**< The encoded direction. */

} SDL_HapticDirection;

/**

 *  \brief A structure containing a template for a Constant effect.

 *

 *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.

 *

 *  A constant effect applies a constant force in the specified direction

 *  to the joystick.

 *

 *  \sa SDL_HAPTIC_CONSTANT

 *  \sa SDL_HapticEffect

 */

typedef struct SDL_HapticConstant

{

    /* Header */

    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */

    SDL_HapticDirection direction;  /**< Direction of the effect. */

    /* Replay */

    Uint32 length;          /**< Duration of the effect. */

    Uint16 delay;           /**< Delay before starting the effect. */

    /* Trigger */

    Uint16 button;          /**< Button that triggers the effect. */

    Uint16 interval;        /**< How soon it can be triggered again after button. */

    /* Constant */

    Sint16 level;           /**< Strength of the constant effect. */

    /* Envelope */

    Uint16 attack_length;   /**< Duration of the attack. */

    Uint16 attack_level;    /**< Level at the start of the attack. */

    Uint16 fade_length;     /**< Duration of the fade. */

    Uint16 fade_level;      /**< Level at the end of the fade. */

} SDL_HapticConstant;

/**

 *  \brief A structure containing a template for a Periodic effect.

 *

 *  The struct handles the following effects:

 *   - ::SDL_HAPTIC_SINE

 *   - ::SDL_HAPTIC_LEFTRIGHT

 *   - ::SDL_HAPTIC_TRIANGLE

 *   - ::SDL_HAPTIC_SAWTOOTHUP