include/SDL_haptic.h
changeset 2713 0906692aa6a4
child 3407 d3baf5ac4e37
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/include/SDL_haptic.h	Mon Aug 25 09:55:03 2008 +0000
     1.3 @@ -0,0 +1,1154 @@
     1.4 +/*
     1.5 +    SDL - Simple DirectMedia Layer
     1.6 +    Copyright (C) 2008 Edgar Simo
     1.7 +
     1.8 +    This library is free software; you can redistribute it and/or
     1.9 +    modify it under the terms of the GNU Lesser General Public
    1.10 +    License as published by the Free Software Foundation; either
    1.11 +    version 2.1 of the License, or (at your option) any later version.
    1.12 +
    1.13 +    This library is distributed in the hope that it will be useful,
    1.14 +    but WITHOUT ANY WARRANTY; without even the implied warranty of
    1.15 +    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    1.16 +    Lesser General Public License for more details.
    1.17 +
    1.18 +    You should have received a copy of the GNU Lesser General Public
    1.19 +    License along with this library; if not, write to the Free Software
    1.20 +    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    1.21 +
    1.22 +    Sam Lantinga
    1.23 +    slouken@libsdl.org
    1.24 +*/
    1.25 +
    1.26 +/**
    1.27 + * \file SDL_haptic.h
    1.28 + *
    1.29 + * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
    1.30 + *  devices.
    1.31 + *
    1.32 + * The basic usage is as follows:
    1.33 + *   - Initialize the Subsystem (SDL_INIT_HAPTIC).
    1.34 + *   - Open a Haptic Device.
    1.35 + *     - SDL_HapticOpen(...) to open from index.
    1.36 + *     - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
    1.37 + *   - Create an effect (SDL_HapticEffect).
    1.38 + *   - Upload the effect with SDL_HapticNewEffect(...).
    1.39 + *   - Run the effect with SDL_HapticRunEffect(...).
    1.40 + *   - (optional) Free the effect with SDL_HapticDestroyEffect(...).
    1.41 + *   - Close the haptic device with SDL_HapticClose(...).
    1.42 + *
    1.43 + * Example:
    1.44 + *
    1.45 + * \code
    1.46 + * int test_haptic( SDL_Joystick * joystick ) {
    1.47 + *    SDL_Haptic *haptic;
    1.48 + *    SDL_HapticEffect effect;
    1.49 + *    int effect_id;
    1.50 + *
    1.51 + *    // Open the device
    1.52 + *    haptic = SDL_HapticOpenFromJoystick( joystick );
    1.53 + *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
    1.54 + *
    1.55 + *    // See if it can do sine waves
    1.56 + *    if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
    1.57 + *       SDL_HapticClose(haptic); // No sine effect
    1.58 + *       return -1;
    1.59 + *    }
    1.60 + *
    1.61 + *    // Create the effect
    1.62 + *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
    1.63 + *    effect.type = SDL_HAPTIC_SINE;
    1.64 + *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
    1.65 + *    effect.periodic.direction.dir[0] = 18000; // Force comes from south
    1.66 + *    effect.periodic.period = 1000; // 1000 ms
    1.67 + *    effect.periodic.magnitude = 20000; // 20000/32767 strength
    1.68 + *    effect.periodic.length = 5000; // 5 seconds long
    1.69 + *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
    1.70 + *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
    1.71 + *
    1.72 + *    // Upload the effect
    1.73 + *    effect_id = SDL_HapticNewEffect( haptic, &effect );
    1.74 + *
    1.75 + *    // Test the effect
    1.76 + *    SDL_HapticRunEffect( haptic, effect_id, 1 );
    1.77 + *    SDL_Delay( 5000); // Wait for the effect to finish
    1.78 + *
    1.79 + *    // We destroy the effect, although closing the device also does this
    1.80 + *    SDL_HapticDestroyEffect( haptic, effect_id );
    1.81 + *
    1.82 + *    // Close the device
    1.83 + *    SDL_HapticClose(haptic);
    1.84 + *
    1.85 + *    return 0; // Success
    1.86 + * }
    1.87 + * \endcode
    1.88 + *
    1.89 + * \author Edgar Simo Serra
    1.90 + */
    1.91 +
    1.92 +#ifndef _SDL_haptic_h
    1.93 +#define _SDL_haptic_h
    1.94 +
    1.95 +#include "SDL_stdinc.h"
    1.96 +#include "SDL_error.h"
    1.97 +#include "SDL_joystick.h"
    1.98 +
    1.99 +#include "begin_code.h"
   1.100 +/* Set up for C function definitions, even when using C++ */
   1.101 +#ifdef __cplusplus
   1.102 +/* *INDENT-OFF* */
   1.103 +extern "C" {
   1.104 +   /* *INDENT-ON* */                                                         
   1.105 +#endif /* __cplusplus */
   1.106 +
   1.107 +/**
   1.108 + * \typedef SDL_Haptic
   1.109 + *
   1.110 + * \brief The haptic structure used to identify an SDL haptic.
   1.111 + *
   1.112 + * \sa SDL_HapticOpen
   1.113 + * \sa SDL_HapticOpenFromJoystick
   1.114 + * \sa SDL_HapticClose
   1.115 + */
   1.116 +struct _SDL_Haptic;
   1.117 +typedef struct _SDL_Haptic SDL_Haptic;
   1.118 +
   1.119 +
   1.120 +/*
   1.121 + * Different haptic features a device can have.
   1.122 + */
   1.123 +/**
   1.124 + * \def SDL_HAPTIC_CONSTANT
   1.125 + *
   1.126 + * \brief Constant haptic effect.
   1.127 + *
   1.128 + * \sa SDL_HapticCondition
   1.129 + */
   1.130 +#define SDL_HAPTIC_CONSTANT   (1<<0)    /* Constant effect supported */
   1.131 +/**
   1.132 + * \def SDL_HAPTIC_SINE
   1.133 + *
   1.134 + * \brief Periodic haptic effect that simulates sine waves.
   1.135 + *
   1.136 + * \sa SDL_HapticPeriodic
   1.137 + */
   1.138 +#define SDL_HAPTIC_SINE       (1<<1)    /* Sine wave effect supported */
   1.139 +/**
   1.140 + * \def SDL_HAPTIC_SQUARE
   1.141 + *
   1.142 + * \brief Periodic haptic effect that simulates square waves.
   1.143 + * 
   1.144 + * \sa SDL_HapticPeriodic
   1.145 + */
   1.146 +#define SDL_HAPTIC_SQUARE     (1<<2)    /* Square wave effect supported */
   1.147 +/**
   1.148 + * \def SDL_HAPTIC_TRIANGLE
   1.149 + *
   1.150 + * \brief Periodic haptic effect that simulates triangular waves.
   1.151 + *
   1.152 + * \sa SDL_HapticPeriodic
   1.153 + */
   1.154 +#define SDL_HAPTIC_TRIANGLE   (1<<3)    /* Triangle wave effect supported */
   1.155 +/**
   1.156 + * \def SDL_HAPTIC_SAWTOOTHUP
   1.157 + *
   1.158 + * \brief Periodic haptic effect that simulates saw tooth up waves.
   1.159 + *
   1.160 + * \sa SDL_HapticPeriodic
   1.161 + */
   1.162 +#define SDL_HAPTIC_SAWTOOTHUP (1<<4)    /* Sawtoothup wave effect supported */
   1.163 +/**
   1.164 + * \def SDL_HAPTIC_SAWTOOTHDOWN
   1.165 + *
   1.166 + * \brief Periodic haptic effect that simulates saw tooth down waves.
   1.167 + *
   1.168 + * \sa SDL_HapticPeriodic
   1.169 + */
   1.170 +#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)  /* Sawtoothdown wave effect supported */
   1.171 +/**
   1.172 + * \def SDL_HAPTIC_RAMP
   1.173 + *
   1.174 + * \brief Ramp haptic effect.
   1.175 + *
   1.176 + * \sa SDL_HapticRamp
   1.177 + */
   1.178 +#define SDL_HAPTIC_RAMP       (1<<6)    /* Ramp effect supported */
   1.179 +/**
   1.180 + * \def SDL_HAPTIC_SPRING
   1.181 + *
   1.182 + * \brief Condition haptic effect that simulates a spring.  Effect is based on the
   1.183 + * axes position.
   1.184 + *
   1.185 + * \sa SDL_HapticCondition
   1.186 + */
   1.187 +#define SDL_HAPTIC_SPRING     (1<<7)    /* Spring effect supported - uses axes position */
   1.188 +/**
   1.189 + * \def SDL_HAPTIC_DAMPER
   1.190 + *
   1.191 + * \brief Condition haptic effect that simulates dampening.  Effect is based on the
   1.192 + * axes velocity.
   1.193 + *
   1.194 + * \sa SDL_HapticCondition
   1.195 + */
   1.196 +#define SDL_HAPTIC_DAMPER     (1<<8)    /* Damper effect supported - uses axes velocity */
   1.197 +/**
   1.198 + * \def SDL_HAPTIC_INERTIA
   1.199 + *
   1.200 + * \brief Condition haptic effect that simulates inertia.  Effect is based on the axes
   1.201 + * acceleration.
   1.202 + *
   1.203 + * \sa SDL_HapticCondition
   1.204 + */
   1.205 +#define SDL_HAPTIC_INERTIA    (1<<9)    /* Inertia effect supported - uses axes acceleration */
   1.206 +/**
   1.207 + * \def SDL_HAPTIC_FRICTION
   1.208 + *
   1.209 + * \brief Condition haptic effect that simulates friction.  Effect is based on the axes
   1.210 + * movement.
   1.211 + *
   1.212 + * \sa SDL_HapticCondition
   1.213 + */
   1.214 +#define SDL_HAPTIC_FRICTION   (1<<10)   /* Friction effect supported - uses axes movement */
   1.215 +/**
   1.216 + * \def SDL_HAPTIC_CUSTOM
   1.217 + *
   1.218 + * \brief User defined custom haptic effect.
   1.219 + */
   1.220 +#define SDL_HAPTIC_CUSTOM     (1<<11)   /* Custom effect is supported */
   1.221 +/* These last two are features the device has, not effects */
   1.222 +/**
   1.223 + * \def SDL_HAPTIC_GAIN
   1.224 + *
   1.225 + * \brief Device supports setting the global gain.
   1.226 + *
   1.227 + * \sa SDL_HapticSetGain
   1.228 + */
   1.229 +#define SDL_HAPTIC_GAIN       (1<<12)   /* Device can set global gain */
   1.230 +/**
   1.231 + * \def SDL_HAPTIC_AUTOCENTER
   1.232 + *
   1.233 + * \brief Device supports setting autocenter.
   1.234 + *
   1.235 + * \sa SDL_HapticSetAutocenter
   1.236 + */
   1.237 +#define SDL_HAPTIC_AUTOCENTER (1<<13)   /* Device can set autocenter */
   1.238 +/**
   1.239 + * \def SDL_HAPTIC_STATUS
   1.240 + *
   1.241 + * \brief Device can be queried for effect status.
   1.242 + *
   1.243 + * \sa SDL_HapticGetEffectStatus
   1.244 + */
   1.245 +#define SDL_HAPTIC_STATUS     (1<<14)   /* Device can be queried for effect status */
   1.246 +/**
   1.247 + * \def SDL_HAPTIC_PAUSE
   1.248 + *
   1.249 + * \brief Device can be paused.
   1.250 + *
   1.251 + * \sa SDL_HapticPause
   1.252 + * \sa SDL_HapticUnpause
   1.253 + */
   1.254 +#define SDL_HAPTIC_PAUSE      (1<<15)   /* Device can be paused. */
   1.255 +
   1.256 +
   1.257 +/*
   1.258 + * Direction encodings
   1.259 + */
   1.260 +/**
   1.261 + * \def SDL_HAPTIC_POLAR
   1.262 + *
   1.263 + * \brief Uses polar coordinates for the direction.
   1.264 + *
   1.265 + * \sa SDL_HapticDirection
   1.266 + */
   1.267 +#define SDL_HAPTIC_POLAR      0
   1.268 +/**
   1.269 + * \def SDL_HAPTIC_CARTESIAN
   1.270 + *
   1.271 + * \brief Uses cartesian coordinates for the direction.
   1.272 + *
   1.273 + * \sa SDL_HapticDirection
   1.274 + */
   1.275 +#define SDL_HAPTIC_CARTESIAN  1
   1.276 +/**
   1.277 + * \def SDL_HAPTIC_SPHERICAL
   1.278 + *
   1.279 + * \brief Uses spherical coordinates for the direction.
   1.280 + *
   1.281 + * \sa SDL_HapticDirection
   1.282 + */
   1.283 +#define SDL_HAPTIC_SPHERICAL  2
   1.284 +
   1.285 +
   1.286 +/*
   1.287 + * Misc defines.
   1.288 + */
   1.289 +/**
   1.290 + * \def SDL_HAPTIC_INFINITY
   1.291 + *
   1.292 + * \brief Used to play a device an infinite number of times.
   1.293 + *
   1.294 + * \sa SDL_HapticRunEffect
   1.295 + */
   1.296 +#define SDL_HAPTIC_INFINITY   4294967295U
   1.297 +
   1.298 +
   1.299 +/**
   1.300 + * \struct SDL_HapticDirection
   1.301 + *
   1.302 + * \brief Structure that represents a haptic direction.
   1.303 + *
   1.304 + * Directions can be specified by:
   1.305 + *   - SDL_HAPTIC_POLAR : Specified by polar coordinates.
   1.306 + *   - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
   1.307 + *   - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
   1.308 + *
   1.309 + * Cardinal directions of the haptic device are relative to the positioning
   1.310 + *  of the device.  North is considered to be away from the user.
   1.311 + *
   1.312 + * The following diagram represents the cardinal directions:
   1.313 + * \code
   1.314 + *              .--.
   1.315 + *              |__| .-------.
   1.316 + *              |=.| |.-----.|
   1.317 + *              |--| ||     ||
   1.318 + *              |  | |'-----'|
   1.319 + *              |__|~')_____('
   1.320 + *                [ COMPUTER ]
   1.321 + *
   1.322 + *
   1.323 + *                  North (0,-1)
   1.324 + *                      ^
   1.325 + *                      |
   1.326 + *                      |
   1.327 + * (1,0)  West <----[ HAPTIC ]----> East (-1,0)
   1.328 + *                      |
   1.329 + *                      |
   1.330 + *                      v
   1.331 + *                   South (0,1)
   1.332 + *
   1.333 + *
   1.334 + *                   [ USER ]
   1.335 + *                     \|||/
   1.336 + *                     (o o)
   1.337 + *               ---ooO-(_)-Ooo---
   1.338 + * \endcode
   1.339 + *
   1.340 + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
   1.341 + *  degree starting north and turning clockwise.  SDL_HAPTIC_POLAR only uses
   1.342 + *  the first dir parameter.  The cardinal directions would be:
   1.343 + *   - North: 0 (0 degrees)
   1.344 + *   - East: 9000 (90 degrees)
   1.345 + *   - South: 18000 (180 degrees)
   1.346 + *   - West: 27000 (270 degrees)
   1.347 + *
   1.348 + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
   1.349 + *  (X axis, Y axis and Z axis (with 3 axes)).  SDL_HAPTIC_CARTESIAN uses
   1.350 + *  the first three dir parameters.  The cardinal directions would be:
   1.351 + *   - North:  0,-1, 0
   1.352 + *   - East:  -1, 0, 0
   1.353 + *   - South:  0, 1, 0
   1.354 + *   - West:   1, 0, 0
   1.355 + *  The Z axis represents the height of the effect if supported, otherwise
   1.356 + *  it's unused.  In cartesian encoding (1,2) would be the same as (2,4), you
   1.357 + *  can use any multiple you want, only the direction matters.
   1.358 + *
   1.359 + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
   1.360 + *  The first two  dir parameters are used.  The dir parameters are as follows
   1.361 + *  (all values are in hundredths of degrees):
   1.362 + *    1) Degrees from (1, 0) rotated towards (0, 1).
   1.363 + *    2) Degrees towards (0, 0, 1) (device needs at least 3 axes).
   1.364 + *
   1.365 + *
   1.366 + * Example of force coming from the south with all encodings (force coming
   1.367 + *  from the south means the user will have to pull the stick to counteract):
   1.368 + * \code
   1.369 + * SDL_HapticDirection direction;
   1.370 + *
   1.371 + * // Cartesian directions
   1.372 + * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
   1.373 + * direction.dir[0] = 0; // X position
   1.374 + * direction.dir[1] = 1; // Y position
   1.375 + * // Assuming the device has 2 axes, we don't need to specify third parameter.
   1.376 + *
   1.377 + * // Polar directions
   1.378 + * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
   1.379 + * direction.dir[0] = 18000; // Polar only uses first parameter
   1.380 + *
   1.381 + * // Spherical coordinates
   1.382 + * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
   1.383 + * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
   1.384 + * \endcode
   1.385 + *
   1.386 + * \sa SDL_HAPTIC_POLAR
   1.387 + * \sa SDL_HAPTIC_CARTESIAN
   1.388 + * \sa SDL_HAPTIC_SPHERICAL
   1.389 + * \sa SDL_HapticEffect
   1.390 + * \sa SDL_HapticNumAxes
   1.391 + */
   1.392 +typedef struct SDL_HapticDirection
   1.393 +{
   1.394 +    Uint8 type;         /**< The type of encoding. */
   1.395 +    Uint16 dir[3];      /**< The encoded direction. */
   1.396 +} SDL_HapticDirection;
   1.397 +
   1.398 +
   1.399 +/**
   1.400 + * \struct SDL_HapticConstant
   1.401 + *
   1.402 + * \brief A structure containing a template for a Constant effect.
   1.403 + *
   1.404 + * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
   1.405 + *
   1.406 + * A constant effect applies a constant force in the specified direction
   1.407 + *  to the joystick.
   1.408 + *
   1.409 + * \sa SDL_HAPTIC_CONSTANT
   1.410 + * \sa SDL_HapticEffect
   1.411 + */
   1.412 +typedef struct SDL_HapticConstant
   1.413 +{
   1.414 +    /* Header */
   1.415 +    Uint16 type;            /**< SDL_HAPTIC_CONSTANT */
   1.416 +    SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.417 +
   1.418 +    /* Replay */
   1.419 +    Uint32 length;          /**< Duration of the effect. */
   1.420 +    Uint16 delay;           /**< Delay before starting the effect. */
   1.421 +
   1.422 +    /* Trigger */
   1.423 +    Uint16 button;          /**< Button that triggers the effect. */
   1.424 +    Uint16 interval;        /**< How soon it can be triggered again after button. */
   1.425 +
   1.426 +    /* Constant */
   1.427 +    Sint16 level;           /**< Strength of the constant effect. */
   1.428 +
   1.429 +    /* Envelope */
   1.430 +    Uint16 attack_length;   /**< Duration of the attack. */
   1.431 +    Uint16 attack_level;    /**< Level at the start of the attack. */
   1.432 +    Uint16 fade_length;     /**< Duration of the fade. */
   1.433 +    Uint16 fade_level;      /**< Level at the end of the fade. */
   1.434 +} SDL_HapticConstant;
   1.435 +/**
   1.436 + * \struct SDL_HapticPeriodic
   1.437 + *
   1.438 + * \brief A structure containing a template for a Periodic effect.
   1.439 + *
   1.440 + * The struct handles the following effects:
   1.441 + *   - SDL_HAPTIC_SINE
   1.442 + *   - SDL_HAPTIC_SQUARE
   1.443 + *   - SDL_HAPTIC_TRIANGLE
   1.444 + *   - SDL_HAPTIC_SAWTOOTHUP
   1.445 + *   - SDL_HAPTIC_SAWTOOTHDOWN
   1.446 + *
   1.447 + * A periodic effect consists in a wave-shaped effect that repeats itself
   1.448 + *  over time.  The type determines the shape of the wave and the parameters
   1.449 + *  determine the dimensions of the wave.
   1.450 + *
   1.451 + * Phase is given by hundredth of a cyle meaning that giving the phase a value
   1.452 + *  of 9000 will displace it 25% of it's period.  Here are sample values:
   1.453 + *    -     0: No phase displacement.
   1.454 + *    -  9000: Displaced 25% of it's period.
   1.455 + *    - 18000: Displaced 50% of it's period.
   1.456 + *    - 27000: Displaced 75% of it's period.
   1.457 + *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
   1.458 + *
   1.459 + * Examples:
   1.460 + * \code
   1.461 + * SDL_HAPTIC_SINE
   1.462 + *   __      __      __      __
   1.463 + *  /  \    /  \    /  \    /
   1.464 + * /    \__/    \__/    \__/
   1.465 + *
   1.466 + * SDL_HAPTIC_SQUARE
   1.467 + *  __    __    __    __    __
   1.468 + * |  |  |  |  |  |  |  |  |  |
   1.469 + * |  |__|  |__|  |__|  |__|  |
   1.470 + *
   1.471 + * SDL_HAPTIC_TRIANGLE
   1.472 + *   /\    /\    /\    /\    /\
   1.473 + *  /  \  /  \  /  \  /  \  /
   1.474 + * /    \/    \/    \/    \/
   1.475 + *
   1.476 + * SDL_HAPTIC_SAWTOOTHUP
   1.477 + *   /|  /|  /|  /|  /|  /|  /|
   1.478 + *  / | / | / | / | / | / | / |
   1.479 + * /  |/  |/  |/  |/  |/  |/  |
   1.480 + *
   1.481 + * SDL_HAPTIC_SAWTOOTHDOWN
   1.482 + * \  |\  |\  |\  |\  |\  |\  |
   1.483 + *  \ | \ | \ | \ | \ | \ | \ |
   1.484 + *   \|  \|  \|  \|  \|  \|  \|
   1.485 + * \endcode
   1.486 + *
   1.487 + * \sa SDL_HAPTIC_SINE
   1.488 + * \sa SDL_HAPTIC_SQUARE
   1.489 + * \sa SDL_HAPTIC_TRIANGLE
   1.490 + * \sa SDL_HAPTIC_SAWTOOTHUP
   1.491 + * \sa SDL_HAPTIC_SAWTOOTHDOWN
   1.492 + * \sa SDL_HapticEffect
   1.493 + */
   1.494 +typedef struct SDL_HapticPeriodic
   1.495 +{
   1.496 +    /* Header */
   1.497 +    Uint16 type;        /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE,
   1.498 +                             SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or
   1.499 +                             SDL_HAPTIC_SAWTOOTHDOWN */
   1.500 +    SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.501 +
   1.502 +    /* Replay */
   1.503 +    Uint32 length;      /**< Duration of the effect. */
   1.504 +    Uint16 delay;       /**< Delay before starting the effect. */
   1.505 +
   1.506 +    /* Trigger */
   1.507 +    Uint16 button;      /**< Button that triggers the effect. */
   1.508 +    Uint16 interval;    /**< How soon it can be triggered again after button. */
   1.509 +
   1.510 +    /* Periodic */
   1.511 +    Uint16 period;      /**< Period of the wave. */
   1.512 +    Sint16 magnitude;   /**< Peak value. */
   1.513 +    Sint16 offset;      /**< Mean value of the wave. */
   1.514 +    Uint16 phase;       /**< Horizontal shift given by hundredth of a cycle. */
   1.515 +
   1.516 +    /* Envelope */
   1.517 +    Uint16 attack_length;   /**< Duration of the attack. */
   1.518 +    Uint16 attack_level;    /**< Level at the start of the attack. */
   1.519 +    Uint16 fade_length; /**< Duration of the fade. */
   1.520 +    Uint16 fade_level;  /**< Level at the end of the fade. */
   1.521 +} SDL_HapticPeriodic;
   1.522 +/**
   1.523 + * \struct SDL_HapticCondition
   1.524 + *
   1.525 + * \brief A structure containing a template for a Condition effect.
   1.526 + *
   1.527 + * The struct handles the following effects:
   1.528 + *   - SDL_HAPTIC_SPRING: Effect based on axes position.
   1.529 + *   - SDL_HAPTIC_DAMPER: Effect based on axes velocity.
   1.530 + *   - SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
   1.531 + *   - SDL_HAPTIC_FRICTION: Effect based on axes movement.
   1.532 + *
   1.533 + * Direction is handled by condition internals instead of a direction member.
   1.534 + *  The condition effect specific members have three parameters.  The first
   1.535 + *  refers to the X axis, the second refers to the Y axis and the third
   1.536 + *  refers to the Z axis.  The right terms refer to the positive side of the
   1.537 + *  axis and the left terms refer to the negative side of the axis.  Please 
   1.538 + *  refer to the SDL_HapticDirection  diagram for which side is positive and
   1.539 + *  which is negative.
   1.540 + *
   1.541 + * \sa SDL_HapticDirection
   1.542 + * \sa SDL_HAPTIC_SPRING
   1.543 + * \sa SDL_HAPTIC_DAMPER
   1.544 + * \sa SDL_HAPTIC_INERTIA
   1.545 + * \sa SDL_HAPTIC_FRICTION
   1.546 + * \sa SDL_HapticEffect
   1.547 + */
   1.548 +typedef struct SDL_HapticCondition
   1.549 +{
   1.550 +    /* Header */
   1.551 +    Uint16 type;            /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER,
   1.552 +                                 SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */
   1.553 +    SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
   1.554 +
   1.555 +    /* Replay */
   1.556 +    Uint32 length;          /**< Duration of the effect. */
   1.557 +    Uint16 delay;           /**< Delay before starting the effect. */
   1.558 +
   1.559 +    /* Trigger */
   1.560 +    Uint16 button;          /**< Button that triggers the effect. */
   1.561 +    Uint16 interval;        /**< How soon it can be triggered again after button. */
   1.562 +
   1.563 +    /* Condition */
   1.564 +    Uint16 right_sat[3];    /**< Level when joystick is to the positive side. */
   1.565 +    Uint16 left_sat[3];     /**< Level when joystick is to the negative side. */
   1.566 +    Sint16 right_coeff[3];  /**< How fast to increase the force towards the positive side. */
   1.567 +    Sint16 left_coeff[3];   /**< How fast to increase the force towards the negative side. */
   1.568 +    Uint16 deadband[3];     /**< Size of the dead zone. */
   1.569 +    Sint16 center[3];       /**< Position of the dead zone. */
   1.570 +} SDL_HapticCondition;
   1.571 +/**
   1.572 + * \struct SDL_HapticRamp
   1.573 + *
   1.574 + * \brief A structure containing a template for a Ramp effect.
   1.575 + *
   1.576 + * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
   1.577 + *
   1.578 + * The ramp effect starts at start strength and ends at end strength.
   1.579 + *  It augments in linear fashion.  If you use attack and fade with a ramp
   1.580 + *  they effects get added to the ramp effect making the effect become
   1.581 + *  quadratic instead of linear.
   1.582 + *
   1.583 + * \sa SDL_HAPTIC_RAMP
   1.584 + * \sa SDL_HapticEffect
   1.585 + */
   1.586 +typedef struct SDL_HapticRamp
   1.587 +{
   1.588 +    /* Header */
   1.589 +    Uint16 type;            /**< SDL_HAPTIC_RAMP */
   1.590 +    SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.591 +
   1.592 +    /* Replay */
   1.593 +    Uint32 length;          /**< Duration of the effect. */
   1.594 +    Uint16 delay;           /**< Delay before starting the effect. */
   1.595 +
   1.596 +    /* Trigger */
   1.597 +    Uint16 button;          /**< Button that triggers the effect. */
   1.598 +    Uint16 interval;        /**< How soon it can be triggered again after button. */
   1.599 +
   1.600 +    /* Ramp */
   1.601 +    Sint16 start;           /**< Beginning strength level. */
   1.602 +    Sint16 end;             /**< Ending strength level. */
   1.603 +
   1.604 +    /* Envelope */
   1.605 +    Uint16 attack_length;   /**< Duration of the attack. */
   1.606 +    Uint16 attack_level;    /**< Level at the start of the attack. */
   1.607 +    Uint16 fade_length;     /**< Duration of the fade. */
   1.608 +    Uint16 fade_level;      /**< Level at the end of the fade. */
   1.609 +} SDL_HapticRamp;
   1.610 +/**
   1.611 + * \struct SDL_HapticCustom
   1.612 + *
   1.613 + * \brief A structure containing a template for the SDL_HAPTIC_CUSTOM effect.
   1.614 + *
   1.615 + * A custom force feedback effect is much like a periodic effect, where the
   1.616 + *  application can define it's exact shape.  You will have to allocate the
   1.617 + *  data yourself.  Data should consist of channels * samples Uint16 samples.
   1.618 + *
   1.619 + * If channels is one, the effect is rotated using the defined direction.
   1.620 + *  Otherwise it uses the samples in data for the different axes.
   1.621 + *
   1.622 + * \sa SDL_HAPTIC_CUSTOM
   1.623 + * \sa SDL_HapticEffect
   1.624 + */
   1.625 +typedef struct SDL_HapticCustom
   1.626 +{
   1.627 +    /* Header */
   1.628 +    Uint16 type;            /**< SDL_HAPTIC_CUSTOM */
   1.629 +    SDL_HapticDirection direction;  /**< Direction of the effect. */
   1.630 +
   1.631 +    /* Replay */
   1.632 +    Uint32 length;          /**< Duration of the effect. */
   1.633 +    Uint16 delay;           /**< Delay before starting the effect. */
   1.634 +
   1.635 +    /* Trigger */
   1.636 +    Uint16 button;          /**< Button that triggers the effect. */
   1.637 +    Uint16 interval;        /**< How soon it can be triggered again after button. */
   1.638 +
   1.639 +    /* Custom */
   1.640 +    Uint8 channels;         /**< Axes to use, minimum of one. */
   1.641 +    Uint16 period;          /**< Sample periods. */
   1.642 +    Uint16 samples;         /**< Amount of samples. */
   1.643 +    Uint16 *data;           /**< Should contain channels*samples items. */
   1.644 +
   1.645 +    /* Envelope */
   1.646 +    Uint16 attack_length;   /**< Duration of the attack. */
   1.647 +    Uint16 attack_level;    /**< Level at the start of the attack. */
   1.648 +    Uint16 fade_length;     /**< Duration of the fade. */
   1.649 +    Uint16 fade_level;      /**< Level at the end of the fade. */
   1.650 +} SDL_HapticCustom;
   1.651 +/**
   1.652 + * \union SDL_HapticEffect
   1.653 + *
   1.654 + * \brief The generic template for any haptic effect.
   1.655 + *
   1.656 + * All values max at 32767 (0x7FFF).  Signed values also can be negative.
   1.657 + *  Time values unless specified otherwise are in milliseconds.
   1.658 + *
   1.659 + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
   1.660 + *  Neither delay, interval, attack_length nor fade_length support 
   1.661 + *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
   1.662 + *
   1.663 + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of
   1.664 + *  SDL_HAPTIC_INFINITY.
   1.665 + *
   1.666 + * Button triggers may not be supported on all devices, it is advised to not
   1.667 + *  use them if possible.  Buttons start at index 1 instead of index 0 like
   1.668 + *  they joystick.
   1.669 + *
   1.670 + * If both attack_length and fade_level are 0, the envelope is not used,
   1.671 + *  otherwise both values are used.
   1.672 + *
   1.673 + * Common parts:
   1.674 + * \code
   1.675 + * // Replay - All effects have this
   1.676 + * Uint32 length;        // Duration of effect (ms).
   1.677 + * Uint16 delay;         // Delay before starting effect.
   1.678 + *
   1.679 + * // Trigger - All effects have this
   1.680 + * Uint16 button;        // Button that triggers effect.
   1.681 + * Uint16 interval;      // How soon before effect can be triggered again.
   1.682 + *
   1.683 + * // Envelope - All effects except condition effects have this
   1.684 + * Uint16 attack_length; // Duration of the attack (ms).
   1.685 + * Uint16 attack_level;  // Level at the start of the attack.
   1.686 + * Uint16 fade_length;   // Duration of the fade out (ms).
   1.687 + * Uint16 fade_level;    // Level at the end of the fade.
   1.688 + * \endcode
   1.689 + *
   1.690 + *
   1.691 + * Here we have an example of a constant effect evolution in time:
   1.692 + *
   1.693 + * \code
   1.694 + * Strength
   1.695 + * ^
   1.696 + * |
   1.697 + * |    effect level -->  _________________
   1.698 + * |                     /                 \
   1.699 + * |                    /                   \
   1.700 + * |                   /                     \
   1.701 + * |                  /                       \ 
   1.702 + * | attack_level --> |                        \
   1.703 + * |                  |                        |  <---  fade_level
   1.704 + * |
   1.705 + * +--------------------------------------------------> Time
   1.706 + *                    [--]                 [---]
   1.707 + *                    attack_length        fade_length
   1.708 + * 
   1.709 + * [------------------][-----------------------]
   1.710 + * delay               length
   1.711 + * \endcode
   1.712 + *
   1.713 + * Note either the attack_level or the fade_level may be above the actual
   1.714 + *  effect level.
   1.715 + *
   1.716 + * \sa SDL_HapticConstant
   1.717 + * \sa SDL_HapticPeriodic
   1.718 + * \sa SDL_HapticCondition
   1.719 + * \sa SDL_HapticRamp
   1.720 + * \sa SDL_HapticCustom
   1.721 + */
   1.722 +typedef union SDL_HapticEffect
   1.723 +{
   1.724 +    /* Common for all force feedback effects */
   1.725 +    Uint16 type;                    /**< Effect type. */
   1.726 +    SDL_HapticConstant constant;    /**< Constant effect. */
   1.727 +    SDL_HapticPeriodic periodic;    /**< Periodic effect. */
   1.728 +    SDL_HapticCondition condition;  /**< Condition effect. */
   1.729 +    SDL_HapticRamp ramp;            /**< Ramp effect. */
   1.730 +    SDL_HapticCustom custom;        /**< Custom effect. */
   1.731 +} SDL_HapticEffect;
   1.732 +
   1.733 +
   1.734 +/* Function prototypes */
   1.735 +/**
   1.736 + * \fn int SDL_NumHaptics(void)
   1.737 + *
   1.738 + * \brief Count the number of joysticks attached to the system.
   1.739 + *
   1.740 + *    \return Number of haptic devices detected on the system.
   1.741 + */
   1.742 +extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   1.743 +
   1.744 +/**
   1.745 + * \fn const char * SDL_HapticName(int device_index)
   1.746 + *
   1.747 + * \brief Get the implementation dependent name of a Haptic device.
   1.748 + * This can be called before any joysticks are opened.
   1.749 + * If no name can be found, this function returns NULL.
   1.750 + *
   1.751 + *    \param device_index Index of the device to get it's name.
   1.752 + *    \return Name of the device or NULL on error.
   1.753 + *
   1.754 + * \sa SDL_NumHaptics
   1.755 + */
   1.756 +extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   1.757 +
   1.758 +/**
   1.759 + * \fn SDL_Haptic * SDL_HapticOpen(int device_index)
   1.760 + *
   1.761 + * \brief Opens a Haptic device for usage - the index passed as an
   1.762 + * argument refers to the N'th Haptic device on this system.
   1.763 + *
   1.764 + * When opening a haptic device, it's gain will be set to maximum and
   1.765 + *  autocenter will be disabled.  To modify these values use
   1.766 + *  SDL_HapticSetGain and SDL_HapticSetAutocenter
   1.767 + *
   1.768 + *    \param device_index Index of the device to open.
   1.769 + *    \return Device identifier or NULL on error.
   1.770 + *
   1.771 + * \sa SDL_HapticIndex
   1.772 + * \sa SDL_HapticOpenFromMouse
   1.773 + * \sa SDL_HapticOpenFromJoystick
   1.774 + * \sa SDL_HapticClose
   1.775 + * \sa SDL_HapticSetGain
   1.776 + * \sa SDL_HapticSetAutocenter
   1.777 + * \sa SDL_HapticPause
   1.778 + * \sa SDL_HapticStopAll
   1.779 + */
   1.780 +extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
   1.781 +
   1.782 +/**
   1.783 + * \fn int SDL_HapticOpened(int device_index)
   1.784 + *
   1.785 + * \brief Checks if the haptic device at index has been opened.
   1.786 + *
   1.787 + *    \param device_index Index to check to see if it has been opened.
   1.788 + *    \return 1 if it has been opened or 0 if it hasn't.
   1.789 + * 
   1.790 + * \sa SDL_HapticOpen
   1.791 + * \sa SDL_HapticIndex
   1.792 + */
   1.793 +extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
   1.794 +
   1.795 +/**
   1.796 + * \fn int SDL_HapticIndex(SDL_Haptic * haptic)
   1.797 + *
   1.798 + * \brief Gets the index of a haptic device.
   1.799 + *
   1.800 + *    \param haptic Haptic device to get the index of.
   1.801 + *    \return The index of the haptic device or -1 on error.
   1.802 + *
   1.803 + * \sa SDL_HapticOpen
   1.804 + * \sa SDL_HapticOpened
   1.805 + */
   1.806 +extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
   1.807 +
   1.808 +/**
   1.809 + * \fn int SDL_MouseIsHaptic(void)
   1.810 + *
   1.811 + * \brief Gets whether or not the current mouse has haptic capabilities.
   1.812 + *
   1.813 + *    \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
   1.814 + *
   1.815 + * \sa SDL_HapticOpenFromMouse
   1.816 + */
   1.817 +extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
   1.818 +
   1.819 +/**
   1.820 + * \fn SDL_Haptic * SDL_HapticOpenFromMouse(void)
   1.821 + *
   1.822 + * \brief Tries to open a haptic device from the current mouse.
   1.823 + *
   1.824 + *    \return The haptic device identifier or NULL on error.
   1.825 + *
   1.826 + * \sa SDL_MouseIsHaptic
   1.827 + * \sa SDL_HapticOpen
   1.828 + */
   1.829 +extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
   1.830 +
   1.831 +/**
   1.832 + * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
   1.833 + *
   1.834 + * \brief Checks to see if a joystick has haptic features.
   1.835 + *
   1.836 + *    \param joystick Joystick to test for haptic capabilities.
   1.837 + *    \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   1.838 + *            or -1 if an error ocurred.
   1.839 + *
   1.840 + * \sa SDL_HapticOpenFromJoystick
   1.841 + */
   1.842 +extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   1.843 +
   1.844 +/**
   1.845 + * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
   1.846 + *
   1.847 + * \brief Opens a Haptic device for usage from a Joystick device.  Still has
   1.848 + * to be closed seperately to the joystick.
   1.849 + *
   1.850 + * When opening from a joystick you should first close the haptic device before
   1.851 + *  closing the joystick device.  If not, on some implementations the haptic
   1.852 + *  device will also get unallocated and you'll be unable to use force feedback
   1.853 + *  on that device.
   1.854 + *
   1.855 + *    \param joystick Joystick to create a haptic device from.
   1.856 + *    \return A valid haptic device identifier on success or NULL on error.
   1.857 + *
   1.858 + * \sa SDL_HapticOpen
   1.859 + * \sa SDL_HapticClose
   1.860 + */
   1.861 +extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
   1.862 +                                                               joystick);
   1.863 +
   1.864 +/**
   1.865 + * \fn void SDL_HapticClose(SDL_Haptic * haptic)
   1.866 + *
   1.867 + * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
   1.868 + *
   1.869 + *    \param haptic Haptic device to close.
   1.870 + */
   1.871 +extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
   1.872 +
   1.873 +/**
   1.874 + * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
   1.875 + *
   1.876 + * \brief Returns the number of effects a haptic device can store.
   1.877 + *
   1.878 + * On some platforms this isn't fully supported, and therefore is an
   1.879 + *  aproximation.  Always check to see if your created effect was actually
   1.880 + *  created and do not rely solely on HapticNumEffects.
   1.881 + *
   1.882 + *    \param haptic The haptic device to query effect max.
   1.883 + *    \return The number of effects the haptic device can store or
   1.884 + *            -1 on error.
   1.885 + *
   1.886 + * \sa SDL_HapticNumEffectsPlaying
   1.887 + * \sa SDL_HapticQuery
   1.888 + */
   1.889 +extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
   1.890 +
   1.891 +/**
   1.892 + * \fn int SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic)
   1.893 + *
   1.894 + * \brief Returns the number of effects a haptic device can play at the same time.
   1.895 + *
   1.896 + * This is not supported on all platforms, but will always return a value.  Added
   1.897 + *  here for the sake of completness.
   1.898 + *
   1.899 + *    \param haptic The haptic device to query maximum playing effect.s
   1.900 + *    \return The number of effects the haptic device can play at the same time
   1.901 + *            or -1 on error.
   1.902 + *
   1.903 + * \sa SDL_HapticNumEffects
   1.904 + * \sa SDL_HapticQuery
   1.905 + */
   1.906 +extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
   1.907 +
   1.908 +/**
   1.909 + * \fn unsigned int SDL_HapticQuery(SDL_Haptic * haptic)
   1.910 + *
   1.911 + * \brief Gets the haptic devices supported features in bitwise matter.
   1.912 + *
   1.913 + * Example: 
   1.914 + * \code
   1.915 + * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
   1.916 + *    printf("We have constant haptic effect!");
   1.917 + * }
   1.918 + * \endcode
   1.919 + *    
   1.920 + *
   1.921 + *    \param haptic The haptic device to query.
   1.922 + *    \return Haptic features in bitwise manner (OR'd).
   1.923 + *
   1.924 + * \sa SDL_HapticNumEffects
   1.925 + * \sa SDL_HapticEffectSupported
   1.926 + */
   1.927 +extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
   1.928 +
   1.929 +
   1.930 +/**
   1.931 + * \fn int SDL_HapticNumAxes(SDL_Haptic * haptic)
   1.932 + *
   1.933 + * \brief Gets the number of haptic axes the device has.
   1.934 + *
   1.935 + * \sa SDL_HapticDirection
   1.936 + */
   1.937 +extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
   1.938 +
   1.939 +/**
   1.940 + * \fn int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   1.941 + *
   1.942 + * \brief Checks to see if effect is supported by haptic.
   1.943 + *
   1.944 + *    \param haptic Haptic device to check on.
   1.945 + *    \param effect Effect to check to see if it is supported.
   1.946 + *    \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or 
   1.947 + *            -1 on error.
   1.948 + * 
   1.949 + * \sa SDL_HapticQuery
   1.950 + * \sa SDL_HapticNewEffect
   1.951 + */
   1.952 +extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
   1.953 +                                                      SDL_HapticEffect *
   1.954 +                                                      effect);
   1.955 +
   1.956 +/**
   1.957 + * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
   1.958 + *
   1.959 + * \brief Creates a new haptic effect on the device.
   1.960 + *
   1.961 + *    \param haptic Haptic device to create the effect on.
   1.962 + *    \param effect Properties of the effect to create.
   1.963 + *    \return The id of the effect on success or -1 on error.
   1.964 + *
   1.965 + * \sa SDL_HapticUpdateEffect
   1.966 + * \sa SDL_HapticRunEffect
   1.967 + * \sa SDL_HapticDestroyEffect
   1.968 + */
   1.969 +extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
   1.970 +                                                SDL_HapticEffect * effect);
   1.971 +
   1.972 +/**
   1.973 + * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
   1.974 + *
   1.975 + * \brief Updates the properties of an effect.
   1.976 + *
   1.977 + * Can be used dynamically, although behaviour when dynamically changing
   1.978 + * direction may be strange.  Specifically the effect may reupload itself
   1.979 + * and start playing from the start.  You cannot change the type either when
   1.980 + * running UpdateEffect.
   1.981 + *
   1.982 + *    \param haptic Haptic device that has the effect.
   1.983 + *    \param effect Effect to update.
   1.984 + *    \param data New effect properties to use.
   1.985 + *    \return The id of the effect on success or -1 on error.
   1.986 + *
   1.987 + * \sa SDL_HapticNewEffect
   1.988 + * \sa SDL_HapticRunEffect
   1.989 + * \sa SDL_HapticDestroyEffect
   1.990 + */
   1.991 +extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
   1.992 +                                                   int effect,
   1.993 +                                                   SDL_HapticEffect * data);
   1.994 +
   1.995 +/**
   1.996 + * \fn int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect, Uint32 iterations)
   1.997 + *
   1.998 + * \brief Runs the haptic effect on it's assosciated haptic device.
   1.999 + *
  1.1000 + * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
  1.1001 + *  repeating the envelope (attack and fade) every time.  If you only want the
  1.1002 + *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
  1.1003 + *  parameter.
  1.1004 + *
  1.1005 + *    \param haptic Haptic device to run the effect on.
  1.1006 + *    \param effect Identifier of the haptic effect to run.
  1.1007 + *    \param iterations Number of iterations to run the effect. Use
  1.1008 + *           SDL_HAPTIC_INFINITY for infinity.
  1.1009 + *    \return 0 on success or -1 on error.
  1.1010 + *
  1.1011 + * \sa SDL_HapticStopEffect
  1.1012 + * \sa SDL_HapticDestroyEffect
  1.1013 + * \sa SDL_HapticGetEffectStatus
  1.1014 + */
  1.1015 +extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
  1.1016 +                                                int effect,
  1.1017 +                                                Uint32 iterations);
  1.1018 +
  1.1019 +/**
  1.1020 + * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
  1.1021 + *
  1.1022 + * \brief Stops the haptic effect on it's assosciated haptic device.
  1.1023 + *
  1.1024 + *    \param haptic Haptic device to stop the effect on.
  1.1025 + *    \param effect Identifier of the effect to stop.
  1.1026 + *    \return 0 on success or -1 on error.
  1.1027 + *
  1.1028 + * \sa SDL_HapticRunEffect
  1.1029 + * \sa SDL_HapticDestroyEffect
  1.1030 + */
  1.1031 +extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
  1.1032 +                                                 int effect);
  1.1033 +
  1.1034 +/**
  1.1035 + * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
  1.1036 + *
  1.1037 + * \brief Destroys a haptic effect on the device.  This will stop the effect
  1.1038 + * if it's running.  Effects are automatically destroyed when the device is
  1.1039 + * closed.
  1.1040 + *
  1.1041 + *    \param haptic Device to destroy the effect on.
  1.1042 + *    \param effect Identifier of the effect to destroy.
  1.1043 + * 
  1.1044 + * \sa SDL_HapticNewEffect
  1.1045 + */
  1.1046 +extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
  1.1047 +                                                     int effect);
  1.1048 +
  1.1049 +/**
  1.1050 + * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
  1.1051 + *
  1.1052 + * \brief Gets the status of the current effect on the haptic device.
  1.1053 + *
  1.1054 + * Device must support the SDL_HAPTIC_STATUS feature.
  1.1055 + *
  1.1056 + *    \param haptic Haptic device to query the effect status on.
  1.1057 + *    \param effect Identifier of the effect to query it's status.
  1.1058 + *    \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
  1.1059 + *            or -1 on error.
  1.1060 + *
  1.1061 + * \sa SDL_HapticRunEffect
  1.1062 + * \sa SDL_HapticStopEffect
  1.1063 + */
  1.1064 +extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
  1.1065 +                                                      int effect);
  1.1066 +
  1.1067 +/**
  1.1068 + * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
  1.1069 + *
  1.1070 + * \brief Sets the global gain of the device.  Gain should be between 0 and 100.
  1.1071 + *
  1.1072 + * Device must support the SDL_HAPTIC_GAIN feature.
  1.1073 + *
  1.1074 + * The user may specify the maxmimum gain by setting the environment variable
  1.1075 + *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
  1.1076 + *  SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the
  1.1077 + *  maximum.
  1.1078 + *
  1.1079 + *    \param haptic Haptic device to set the gain on.
  1.1080 + *    \param gain Value to set the gain to, should be between 0 and 100.
  1.1081 + *    \return 0 on success or -1 on error.
  1.1082 + *
  1.1083 + * \sa SDL_HapticQuery
  1.1084 + */
  1.1085 +extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
  1.1086 +
  1.1087 +/**
  1.1088 + * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
  1.1089 + *
  1.1090 + * \brief Sets the global autocenter of the device.  Autocenter should be between
  1.1091 + * 0 and 100.  Setting it to 0 will disable autocentering.
  1.1092 + *
  1.1093 + * Device must support the SDL_HAPTIC_AUTOCENTER feature.
  1.1094 + *
  1.1095 + *    \param haptic Haptic device to set autocentering on.
  1.1096 + *    \param autocenter Value to set autocenter to, 0 disables autocentering.
  1.1097 + *    \return 0 on success or -1 on error.
  1.1098 + *
  1.1099 + * \sa SDL_HapticQuery
  1.1100 + */
  1.1101 +extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
  1.1102 +                                                    int autocenter);
  1.1103 +
  1.1104 +/**
  1.1105 + * \fn extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic)
  1.1106 + *
  1.1107 + * \brief Pauses a haptic device.
  1.1108 + *
  1.1109 + * Device must support the SDL_HAPTIC_PAUSE feature.  Call SDL_HapticUnpause
  1.1110 + *  to resume playback.
  1.1111 + *
  1.1112 + * Do not modify the effects nor add new ones while the device is paused.
  1.1113 + *  That can cause all sorts of weird errors.
  1.1114 + *
  1.1115 + *    \param haptic Haptic device to pause.
  1.1116 + *    \return 0 on success or -1 on error.
  1.1117 + *
  1.1118 + * \sa SDL_HapticUnpause
  1.1119 + */
  1.1120 +extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
  1.1121 +
  1.1122 +/**
  1.1123 + * \fn extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic)
  1.1124 + *
  1.1125 + * \brief Unpauses a haptic device.
  1.1126 + *
  1.1127 + * Call to unpause after SDL_HapticPause.
  1.1128 + *
  1.1129 + *    \param haptic Haptic device to pause.
  1.1130 + *    \return 0 on success or -1 on error.
  1.1131 + *
  1.1132 + * \sa SDL_HapticPause
  1.1133 + */
  1.1134 +extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
  1.1135 +
  1.1136 +/**
  1.1137 + * \fn extern DECSLPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic)
  1.1138 + *
  1.1139 + * \brief Stops all the currently playing effects on a haptic device.
  1.1140 + *
  1.1141 + *    \param haptic Haptic device to stop.
  1.1142 + *    \return 0 on success or -1 on error.
  1.1143 + */
  1.1144 +extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
  1.1145 +
  1.1146 +
  1.1147 +/* Ends C function definitions when using C++ */
  1.1148 +#ifdef __cplusplus
  1.1149 +/* *INDENT-OFF* */
  1.1150 +}
  1.1151 +/* *INDENT-ON* */
  1.1152 +#endif
  1.1153 +#include "close_code.h"
  1.1154 +
  1.1155 +#endif /* _SDL_haptic_h */
  1.1156 +
  1.1157 +/* vi: set ts=4 sw=4 expandtab: */