include/SDL_haptic.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 20 Feb 2011 10:54:44 -0800
changeset 5360 220d3af9121f
parent 5126 ad4141d88412
child 5535 96594ac5fd1a
permissions -rw-r--r--
Simple rumble API for haptic

Edgar Simo 2011-02-20 10:27:52 PST

Adding patch that adds a simplified API for the haptic subsystem built ontop of
the "real one" for those who want simple rumble without jumping through hoops.

Adds 4 functions:

- extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
- extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
- extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float
strength, Uint32 length );
- extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);

Also provided is test/testrumble.c which does test this.

This has all been tested on linux and has worked, but due to being built ontop
of the other haptic API it should work on all OS the same.
slouken@2713
     1
/*
slouken@2713
     2
    SDL - Simple DirectMedia Layer
slouken@2713
     3
    Copyright (C) 2008 Edgar Simo
slouken@2713
     4
slouken@2713
     5
    This library is free software; you can redistribute it and/or
slouken@2713
     6
    modify it under the terms of the GNU Lesser General Public
slouken@2713
     7
    License as published by the Free Software Foundation; either
slouken@2713
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@2713
     9
slouken@2713
    10
    This library is distributed in the hope that it will be useful,
slouken@2713
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@2713
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@2713
    13
    Lesser General Public License for more details.
slouken@2713
    14
slouken@2713
    15
    You should have received a copy of the GNU Lesser General Public
slouken@2713
    16
    License along with this library; if not, write to the Free Software
slouken@2713
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@2713
    18
slouken@2713
    19
    Sam Lantinga
slouken@2713
    20
    slouken@libsdl.org
slouken@2713
    21
*/
slouken@2713
    22
slouken@2713
    23
/**
slouken@3407
    24
 *  \file SDL_haptic.h
slouken@3407
    25
 *  
slouken@3407
    26
 *  \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
slouken@3407
    27
 *         devices.
slouken@5360
    28
 * 
slouken@3407
    29
 *  The basic usage is as follows:
slouken@3407
    30
 *   - Initialize the Subsystem (::SDL_INIT_HAPTIC).
slouken@3407
    31
 *   - Open a Haptic Device.
slouken@3407
    32
 *    - SDL_HapticOpen() to open from index.
slouken@3407
    33
 *    - SDL_HapticOpenFromJoystick() to open from an existing joystick.
slouken@3407
    34
 *   - Create an effect (::SDL_HapticEffect).
slouken@3407
    35
 *   - Upload the effect with SDL_HapticNewEffect().
slouken@3407
    36
 *   - Run the effect with SDL_HapticRunEffect().
slouken@3407
    37
 *   - (optional) Free the effect with SDL_HapticDestroyEffect().
slouken@3407
    38
 *   - Close the haptic device with SDL_HapticClose().
slouken@2713
    39
 *
slouken@5360
    40
 * \par Simple rumble example:
slouken@5360
    41
 * \code
slouken@5360
    42
 *    SDL_Haptic *haptic;
slouken@5360
    43
 *
slouken@5360
    44
 *    // Open the device
slouken@5360
    45
 *    haptic = SDL_HapticOpen( 0 );
slouken@5360
    46
 *    if (haptic == NULL)
slouken@5360
    47
 *       return -1;
slouken@5360
    48
 *
slouken@5360
    49
 *    // Initialize simple rumble
slouken@5360
    50
 *    if (SDL_HapticRumbleInit( haptic ) != 0)
slouken@5360
    51
 *       return -1;
slouken@5360
    52
 *
slouken@5360
    53
 *    // Play effect at 50% strength for 2 seconds
slouken@5360
    54
 *    if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
slouken@5360
    55
 *       return -1;
slouken@5360
    56
 *    SDL_Delay( 2000 );
slouken@5360
    57
 *
slouken@5360
    58
 *    // Clean up
slouken@5360
    59
 *    SDL_HapticClose( haptic );
slouken@5360
    60
 * \endcode
slouken@5360
    61
 *
slouken@5360
    62
 * \par Complete example:
slouken@2713
    63
 * \code
slouken@2713
    64
 * int test_haptic( SDL_Joystick * joystick ) {
slouken@2713
    65
 *    SDL_Haptic *haptic;
slouken@2713
    66
 *    SDL_HapticEffect effect;
slouken@2713
    67
 *    int effect_id;
slouken@2713
    68
 *
slouken@2713
    69
 *    // Open the device
slouken@2713
    70
 *    haptic = SDL_HapticOpenFromJoystick( joystick );
slouken@2713
    71
 *    if (haptic == NULL) return -1; // Most likely joystick isn't haptic
slouken@2713
    72
 *
slouken@2713
    73
 *    // See if it can do sine waves
slouken@2713
    74
 *    if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
slouken@2713
    75
 *       SDL_HapticClose(haptic); // No sine effect
slouken@2713
    76
 *       return -1;
slouken@2713
    77
 *    }
slouken@2713
    78
 *
slouken@2713
    79
 *    // Create the effect
slouken@2713
    80
 *    memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
slouken@2713
    81
 *    effect.type = SDL_HAPTIC_SINE;
slouken@2713
    82
 *    effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
slouken@2713
    83
 *    effect.periodic.direction.dir[0] = 18000; // Force comes from south
slouken@2713
    84
 *    effect.periodic.period = 1000; // 1000 ms
slouken@2713
    85
 *    effect.periodic.magnitude = 20000; // 20000/32767 strength
slouken@2713
    86
 *    effect.periodic.length = 5000; // 5 seconds long
slouken@2713
    87
 *    effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
slouken@2713
    88
 *    effect.periodic.fade_length = 1000; // Takes 1 second to fade away
slouken@2713
    89
 *
slouken@2713
    90
 *    // Upload the effect
slouken@2713
    91
 *    effect_id = SDL_HapticNewEffect( haptic, &effect );
slouken@2713
    92
 *
slouken@2713
    93
 *    // Test the effect
slouken@2713
    94
 *    SDL_HapticRunEffect( haptic, effect_id, 1 );
slouken@2713
    95
 *    SDL_Delay( 5000); // Wait for the effect to finish
slouken@2713
    96
 *
slouken@2713
    97
 *    // We destroy the effect, although closing the device also does this
slouken@2713
    98
 *    SDL_HapticDestroyEffect( haptic, effect_id );
slouken@2713
    99
 *
slouken@2713
   100
 *    // Close the device
slouken@2713
   101
 *    SDL_HapticClose(haptic);
slouken@2713
   102
 *
slouken@2713
   103
 *    return 0; // Success
slouken@2713
   104
 * }
slouken@2713
   105
 * \endcode
slouken@5126
   106
 *
slouken@5126
   107
 * You can also find out more information on my blog:
slouken@5126
   108
 * http://bobbens.dyndns.org/journal/2010/sdl_haptic/
slouken@5126
   109
 *
slouken@2713
   110
 * \author Edgar Simo Serra
slouken@2713
   111
 */
slouken@2713
   112
slouken@2713
   113
#ifndef _SDL_haptic_h
slouken@2713
   114
#define _SDL_haptic_h
slouken@2713
   115
slouken@2713
   116
#include "SDL_stdinc.h"
slouken@2713
   117
#include "SDL_error.h"
slouken@2713
   118
#include "SDL_joystick.h"
slouken@2713
   119
slouken@2713
   120
#include "begin_code.h"
slouken@2713
   121
/* Set up for C function definitions, even when using C++ */
slouken@2713
   122
#ifdef __cplusplus
slouken@2713
   123
/* *INDENT-OFF* */
slouken@2713
   124
extern "C" {
slouken@2713
   125
   /* *INDENT-ON* */                                                         
slouken@2713
   126
#endif /* __cplusplus */
slouken@2713
   127
slouken@2713
   128
/**
slouken@3407
   129
 *  \typedef SDL_Haptic
slouken@3407
   130
 *  
slouken@3407
   131
 *  \brief The haptic structure used to identify an SDL haptic.
slouken@3407
   132
 *  
slouken@3407
   133
 *  \sa SDL_HapticOpen
slouken@3407
   134
 *  \sa SDL_HapticOpenFromJoystick
slouken@3407
   135
 *  \sa SDL_HapticClose
slouken@2713
   136
 */
slouken@2713
   137
struct _SDL_Haptic;
slouken@2713
   138
typedef struct _SDL_Haptic SDL_Haptic;
slouken@2713
   139
slouken@2713
   140
slouken@3407
   141
/**
slouken@3407
   142
 *  \name Haptic features
slouken@3407
   143
 *  
slouken@3407
   144
 *  Different haptic features a device can have.
slouken@2713
   145
 */
slouken@3407
   146
/*@{*/
slouken@3407
   147
slouken@2713
   148
/**
slouken@3407
   149
 *  \name Haptic effects
slouken@3407
   150
 */
slouken@3407
   151
/*@{*/
slouken@3407
   152
slouken@3407
   153
/**
slouken@3407
   154
 *  \brief Constant effect supported.
slouken@2713
   155
 *
slouken@3407
   156
 *  Constant haptic effect.
slouken@3407
   157
 *  
slouken@3407
   158
 *  \sa SDL_HapticCondition
slouken@3407
   159
 */
slouken@3407
   160
#define SDL_HAPTIC_CONSTANT   (1<<0)
slouken@3407
   161
slouken@3407
   162
/**
slouken@3407
   163
 *  \brief Sine wave effect supported.
slouken@3407
   164
 *  
slouken@3407
   165
 *  Periodic haptic effect that simulates sine waves.
slouken@3407
   166
 *  
slouken@3407
   167
 *  \sa SDL_HapticPeriodic
slouken@3407
   168
 */
slouken@3407
   169
#define SDL_HAPTIC_SINE       (1<<1)
slouken@3407
   170
slouken@3407
   171
/**
slouken@3407
   172
 *  \brief Square wave effect supported.
slouken@3407
   173
 *  
slouken@3407
   174
 *  Periodic haptic effect that simulates square waves.
slouken@3407
   175
 * 
slouken@3407
   176
 *  \sa SDL_HapticPeriodic
slouken@3407
   177
 */
slouken@3407
   178
#define SDL_HAPTIC_SQUARE     (1<<2)
slouken@3407
   179
slouken@3407
   180
/**
slouken@3407
   181
 *  \brief Triangle wave effect supported.
slouken@3407
   182
 *  
slouken@3407
   183
 *  Periodic haptic effect that simulates triangular waves.
slouken@3407
   184
 *  
slouken@3407
   185
 *  \sa SDL_HapticPeriodic
slouken@3407
   186
 */
slouken@3407
   187
#define SDL_HAPTIC_TRIANGLE   (1<<3)
slouken@3407
   188
slouken@3407
   189
/**
slouken@3407
   190
 *  \brief Sawtoothup wave effect supported.
slouken@3407
   191
 *  
slouken@3407
   192
 *  Periodic haptic effect that simulates saw tooth up waves.
slouken@3407
   193
 *  
slouken@3407
   194
 *  \sa SDL_HapticPeriodic
slouken@3407
   195
 */
slouken@3407
   196
#define SDL_HAPTIC_SAWTOOTHUP (1<<4)
slouken@3407
   197
slouken@3407
   198
/**
slouken@3407
   199
 *  \brief Sawtoothdown wave effect supported.
slouken@3407
   200
 *  
slouken@3407
   201
 *  Periodic haptic effect that simulates saw tooth down waves.
slouken@3407
   202
 *  
slouken@3407
   203
 *  \sa SDL_HapticPeriodic
slouken@3407
   204
 */
slouken@3407
   205
#define SDL_HAPTIC_SAWTOOTHDOWN (1<<5)
slouken@3407
   206
slouken@3407
   207
/**
slouken@3407
   208
 *  \brief Ramp effect supported.
slouken@3407
   209
 *  
slouken@3407
   210
 *  Ramp haptic effect.
slouken@3407
   211
 *  
slouken@3407
   212
 *  \sa SDL_HapticRamp
slouken@3407
   213
 */
slouken@3407
   214
#define SDL_HAPTIC_RAMP       (1<<6)
slouken@3407
   215
slouken@3407
   216
/**
slouken@3407
   217
 *  \brief Spring effect supported - uses axes position.
slouken@3407
   218
 *  
slouken@3407
   219
 *  Condition haptic effect that simulates a spring.  Effect is based on the
slouken@3407
   220
 *  axes position.
slouken@2713
   221
 *
slouken@3407
   222
 *  \sa SDL_HapticCondition
slouken@2713
   223
 */
slouken@3407
   224
#define SDL_HAPTIC_SPRING     (1<<7)
slouken@3407
   225
slouken@2713
   226
/**
slouken@3407
   227
 *  \brief Damper effect supported - uses axes velocity.
slouken@3407
   228
 *  
slouken@3407
   229
 *  Condition haptic effect that simulates dampening.  Effect is based on the
slouken@3407
   230
 *  axes velocity.
slouken@3407
   231
 *  
slouken@3407
   232
 *  \sa SDL_HapticCondition
slouken@3407
   233
 */
slouken@3407
   234
#define SDL_HAPTIC_DAMPER     (1<<8)
slouken@3407
   235
slouken@3407
   236
/**
slouken@3407
   237
 *  \brief Inertia effect supported - uses axes acceleration.
slouken@3407
   238
 *  
slouken@3407
   239
 *  Condition haptic effect that simulates inertia.  Effect is based on the axes
slouken@3407
   240
 *  acceleration.
slouken@2713
   241
 *
slouken@3407
   242
 *  \sa SDL_HapticCondition
slouken@2713
   243
 */
slouken@3407
   244
#define SDL_HAPTIC_INERTIA    (1<<9)
slouken@3407
   245
slouken@2713
   246
/**
slouken@3407
   247
 *  \brief Friction effect supported - uses axes movement.
slouken@3407
   248
 *  
slouken@3407
   249
 *  Condition haptic effect that simulates friction.  Effect is based on the 
slouken@3407
   250
 *  axes movement.
slouken@3407
   251
 *  
slouken@3407
   252
 *  \sa SDL_HapticCondition
slouken@2713
   253
 */
slouken@3407
   254
#define SDL_HAPTIC_FRICTION   (1<<10)
slouken@3407
   255
slouken@2713
   256
/**
slouken@3407
   257
 *  \brief Custom effect is supported.
slouken@3407
   258
 *  
slouken@3407
   259
 *  User defined custom haptic effect.
slouken@2713
   260
 */
slouken@3407
   261
#define SDL_HAPTIC_CUSTOM     (1<<11)
slouken@3407
   262
slouken@3407
   263
/*@}*//*Haptic effects*/
slouken@3407
   264
slouken@3407
   265
/* These last few are features the device has, not effects */
slouken@3407
   266
slouken@2713
   267
/**
slouken@3407
   268
 *  \brief Device can set global gain.
slouken@3407
   269
 *  
slouken@3407
   270
 *  Device supports setting the global gain.
slouken@3407
   271
 *  
slouken@3407
   272
 *  \sa SDL_HapticSetGain
slouken@2713
   273
 */
slouken@3407
   274
#define SDL_HAPTIC_GAIN       (1<<12)
slouken@3407
   275
slouken@2713
   276
/**
slouken@3407
   277
 *  \brief Device can set autocenter.
slouken@3407
   278
 *  
slouken@3407
   279
 *  Device supports setting autocenter.
slouken@3407
   280
 *  
slouken@3407
   281
 *  \sa SDL_HapticSetAutocenter
slouken@2713
   282
 */
slouken@3407
   283
#define SDL_HAPTIC_AUTOCENTER (1<<13)
slouken@3407
   284
slouken@2713
   285
/**
slouken@3407
   286
 *  \brief Device can be queried for effect status.
slouken@3407
   287
 *  
slouken@3407
   288
 *  Device can be queried for effect status.
slouken@3407
   289
 *  
slouken@3407
   290
 *  \sa SDL_HapticGetEffectStatus
slouken@2713
   291
 */
slouken@3407
   292
#define SDL_HAPTIC_STATUS     (1<<14)
slouken@3407
   293
slouken@2713
   294
/**
slouken@3407
   295
 *  \brief Device can be paused.
slouken@3407
   296
 *  
slouken@3407
   297
 *  \sa SDL_HapticPause
slouken@3407
   298
 *  \sa SDL_HapticUnpause
slouken@2713
   299
 */
slouken@3407
   300
#define SDL_HAPTIC_PAUSE      (1<<15)
slouken@3407
   301
slouken@3407
   302
slouken@2713
   303
/**
slouken@3407
   304
 * \name Direction encodings
slouken@2713
   305
 */
slouken@3407
   306
/*@{*/
slouken@3407
   307
slouken@2713
   308
/**
slouken@3407
   309
 *  \brief Uses polar coordinates for the direction.
slouken@3407
   310
 *  
slouken@3407
   311
 *  \sa SDL_HapticDirection
slouken@2713
   312
 */
slouken@2713
   313
#define SDL_HAPTIC_POLAR      0
slouken@3407
   314
slouken@2713
   315
/**
slouken@3407
   316
 *  \brief Uses cartesian coordinates for the direction.
slouken@3407
   317
 *  
slouken@3407
   318
 *  \sa SDL_HapticDirection
slouken@2713
   319
 */
slouken@2713
   320
#define SDL_HAPTIC_CARTESIAN  1
slouken@3407
   321
slouken@2713
   322
/**
slouken@3407
   323
 *  \brief Uses spherical coordinates for the direction.
slouken@3407
   324
 *  
slouken@3407
   325
 *  \sa SDL_HapticDirection
slouken@2713
   326
 */
slouken@2713
   327
#define SDL_HAPTIC_SPHERICAL  2
slouken@2713
   328
slouken@3407
   329
/*@}*//*Direction encodings*/
slouken@3407
   330
slouken@3407
   331
/*@}*//*Haptic features*/
slouken@2713
   332
slouken@2713
   333
/*
slouken@2713
   334
 * Misc defines.
slouken@2713
   335
 */
slouken@3407
   336
slouken@2713
   337
/**
slouken@2713
   338
 * \brief Used to play a device an infinite number of times.
slouken@2713
   339
 *
slouken@2713
   340
 * \sa SDL_HapticRunEffect
slouken@2713
   341
 */
slouken@2713
   342
#define SDL_HAPTIC_INFINITY   4294967295U
slouken@2713
   343
slouken@2713
   344
slouken@2713
   345
/**
slouken@3407
   346
 *  \brief Structure that represents a haptic direction.
slouken@3407
   347
 *  
slouken@3407
   348
 *  Directions can be specified by:
slouken@3407
   349
 *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
slouken@3407
   350
 *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
slouken@3407
   351
 *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
slouken@2713
   352
 *
slouken@3407
   353
 *  Cardinal directions of the haptic device are relative to the positioning
slouken@2713
   354
 *  of the device.  North is considered to be away from the user.
slouken@2713
   355
 *
slouken@3407
   356
 *  The following diagram represents the cardinal directions:
slouken@3407
   357
 *  \verbatim
slouken@3407
   358
                 .--.
slouken@3407
   359
                 |__| .-------.
slouken@3407
   360
                 |=.| |.-----.|
slouken@3407
   361
                 |--| ||     ||
slouken@3407
   362
                 |  | |'-----'|
slouken@3407
   363
                 |__|~')_____('
slouken@3407
   364
                   [ COMPUTER ]
slouken@3407
   365
    
slouken@3407
   366
    
slouken@3407
   367
                     North (0,-1)
slouken@3407
   368
                         ^
slouken@3407
   369
                         |
slouken@3407
   370
                         |
slouken@3407
   371
    (1,0)  West <----[ HAPTIC ]----> East (-1,0)
slouken@3407
   372
                         |
slouken@3407
   373
                         |
slouken@3407
   374
                         v
slouken@3407
   375
                      South (0,1)
slouken@3407
   376
    
slouken@3407
   377
    
slouken@3407
   378
                      [ USER ]
slouken@3407
   379
                        \|||/
slouken@3407
   380
                        (o o)
slouken@3407
   381
                  ---ooO-(_)-Ooo---
slouken@3407
   382
    \endverbatim
slouken@3407
   383
 *  
slouken@3407
   384
 *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a 
slouken@3407
   385
 *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
slouken@3407
   386
 *  the first \c dir parameter.  The cardinal directions would be:
slouken@2713
   387
 *   - North: 0 (0 degrees)
slouken@2713
   388
 *   - East: 9000 (90 degrees)
slouken@2713
   389
 *   - South: 18000 (180 degrees)
slouken@2713
   390
 *   - West: 27000 (270 degrees)
slouken@3407
   391
 *  
slouken@3407
   392
 *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
slouken@3407
   393
 *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
slouken@3407
   394
 *  the first three \c dir parameters.  The cardinal directions would be:
slouken@2713
   395
 *   - North:  0,-1, 0
slouken@2713
   396
 *   - East:  -1, 0, 0
slouken@2713
   397
 *   - South:  0, 1, 0
slouken@2713
   398
 *   - West:   1, 0, 0
slouken@3407
   399
 *  
slouken@2713
   400
 *  The Z axis represents the height of the effect if supported, otherwise
slouken@3407
   401
 *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
slouken@2713
   402
 *  can use any multiple you want, only the direction matters.
slouken@3407
   403
 *  
slouken@3407
   404
 *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
slouken@3407
   405
 *  The first two \c dir parameters are used.  The \c dir parameters are as 
slouken@3407
   406
 *  follows (all values are in hundredths of degrees):
slouken@3407
   407
 *   - Degrees from (1, 0) rotated towards (0, 1).
slouken@3407
   408
 *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
slouken@2713
   409
 *
slouken@2713
   410
 *
slouken@3407
   411
 *  Example of force coming from the south with all encodings (force coming
slouken@3407
   412
 *  from the south means the user will have to pull the stick to counteract):
slouken@3407
   413
 *  \code
slouken@3407
   414
 *  SDL_HapticDirection direction;
slouken@3407
   415
 *  
slouken@3407
   416
 *  // Cartesian directions
slouken@3407
   417
 *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
slouken@3407
   418
 *  direction.dir[0] = 0; // X position
slouken@3407
   419
 *  direction.dir[1] = 1; // Y position
slouken@3407
   420
 *  // Assuming the device has 2 axes, we don't need to specify third parameter.
slouken@3407
   421
 *  
slouken@3407
   422
 *  // Polar directions
slouken@3407
   423
 *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
slouken@3407
   424
 *  direction.dir[0] = 18000; // Polar only uses first parameter
slouken@3407
   425
 *  
slouken@3407
   426
 *  // Spherical coordinates
slouken@3407
   427
 *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
slouken@3407
   428
 *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
slouken@3407
   429
 *  \endcode
slouken@2713
   430
 *
slouken@3407
   431
 *  \sa SDL_HAPTIC_POLAR
slouken@3407
   432
 *  \sa SDL_HAPTIC_CARTESIAN
slouken@3407
   433
 *  \sa SDL_HAPTIC_SPHERICAL
slouken@3407
   434
 *  \sa SDL_HapticEffect
slouken@3407
   435
 *  \sa SDL_HapticNumAxes
slouken@2713
   436
 */
slouken@2713
   437
typedef struct SDL_HapticDirection
slouken@2713
   438
{
slouken@2713
   439
    Uint8 type;         /**< The type of encoding. */
slouken@3496
   440
    Sint32 dir[3];      /**< The encoded direction. */
slouken@2713
   441
} SDL_HapticDirection;
slouken@2713
   442
slouken@2713
   443
slouken@2713
   444
/**
slouken@3407
   445
 *  \brief A structure containing a template for a Constant effect.
slouken@3407
   446
 *  
slouken@3407
   447
 *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
slouken@3407
   448
 *  
slouken@3407
   449
 *  A constant effect applies a constant force in the specified direction
slouken@2713
   450
 *  to the joystick.
slouken@3407
   451
 *  
slouken@3407
   452
 *  \sa SDL_HAPTIC_CONSTANT
slouken@3407
   453
 *  \sa SDL_HapticEffect
slouken@2713
   454
 */
slouken@2713
   455
typedef struct SDL_HapticConstant
slouken@2713
   456
{
slouken@2713
   457
    /* Header */
slouken@3407
   458
    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
slouken@2713
   459
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   460
slouken@2713
   461
    /* Replay */
slouken@2713
   462
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   463
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   464
slouken@2713
   465
    /* Trigger */
slouken@2713
   466
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   467
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   468
slouken@2713
   469
    /* Constant */
slouken@2713
   470
    Sint16 level;           /**< Strength of the constant effect. */
slouken@2713
   471
slouken@2713
   472
    /* Envelope */
slouken@2713
   473
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   474
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   475
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   476
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   477
} SDL_HapticConstant;
slouken@3407
   478
slouken@2713
   479
/**
slouken@3407
   480
 *  \brief A structure containing a template for a Periodic effect.
slouken@3407
   481
 *  
slouken@3407
   482
 *  The struct handles the following effects:
slouken@3407
   483
 *   - ::SDL_HAPTIC_SINE
slouken@3407
   484
 *   - ::SDL_HAPTIC_SQUARE
slouken@3407
   485
 *   - ::SDL_HAPTIC_TRIANGLE
slouken@3407
   486
 *   - ::SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   487
 *   - ::SDL_HAPTIC_SAWTOOTHDOWN
slouken@3407
   488
 *  
slouken@3407
   489
 *  A periodic effect consists in a wave-shaped effect that repeats itself
slouken@2713
   490
 *  over time.  The type determines the shape of the wave and the parameters
slouken@2713
   491
 *  determine the dimensions of the wave.
slouken@3407
   492
 *  
slouken@3407
   493
 *  Phase is given by hundredth of a cyle meaning that giving the phase a value
slouken@3407
   494
 *  of 9000 will displace it 25% of it's period.  Here are sample values:
slouken@3407
   495
 *   -     0: No phase displacement.
slouken@3407
   496
 *   -  9000: Displaced 25% of it's period.
slouken@3407
   497
 *   - 18000: Displaced 50% of it's period.
slouken@3407
   498
 *   - 27000: Displaced 75% of it's period.
slouken@3407
   499
 *   - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
slouken@2713
   500
 *
slouken@3407
   501
 *  Examples:
slouken@3407
   502
 *  \verbatim
slouken@3407
   503
    SDL_HAPTIC_SINE
slouken@3407
   504
      __      __      __      __
slouken@3407
   505
     /  \    /  \    /  \    /
slouken@3407
   506
    /    \__/    \__/    \__/
slouken@3407
   507
    
slouken@3407
   508
    SDL_HAPTIC_SQUARE
slouken@3407
   509
     __    __    __    __    __
slouken@3407
   510
    |  |  |  |  |  |  |  |  |  |
slouken@3407
   511
    |  |__|  |__|  |__|  |__|  |
slouken@3407
   512
    
slouken@3407
   513
    SDL_HAPTIC_TRIANGLE
slouken@3407
   514
      /\    /\    /\    /\    /\
slouken@3407
   515
     /  \  /  \  /  \  /  \  /
slouken@3407
   516
    /    \/    \/    \/    \/
slouken@3407
   517
    
slouken@3407
   518
    SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   519
      /|  /|  /|  /|  /|  /|  /|
slouken@3407
   520
     / | / | / | / | / | / | / |
slouken@3407
   521
    /  |/  |/  |/  |/  |/  |/  |
slouken@3407
   522
    
slouken@3407
   523
    SDL_HAPTIC_SAWTOOTHDOWN
slouken@3407
   524
    \  |\  |\  |\  |\  |\  |\  |
slouken@3407
   525
     \ | \ | \ | \ | \ | \ | \ |
slouken@3407
   526
      \|  \|  \|  \|  \|  \|  \|
slouken@3407
   527
    \endverbatim
slouken@3407
   528
 *  
slouken@3407
   529
 *  \sa SDL_HAPTIC_SINE
slouken@3407
   530
 *  \sa SDL_HAPTIC_SQUARE
slouken@3407
   531
 *  \sa SDL_HAPTIC_TRIANGLE
slouken@3407
   532
 *  \sa SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   533
 *  \sa SDL_HAPTIC_SAWTOOTHDOWN
slouken@3407
   534
 *  \sa SDL_HapticEffect
slouken@2713
   535
 */
slouken@2713
   536
typedef struct SDL_HapticPeriodic
slouken@2713
   537
{
slouken@2713
   538
    /* Header */
slouken@3407
   539
    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE,
slouken@3407
   540
                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
slouken@3407
   541
                             ::SDL_HAPTIC_SAWTOOTHDOWN */
slouken@2713
   542
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   543
slouken@2713
   544
    /* Replay */
slouken@2713
   545
    Uint32 length;      /**< Duration of the effect. */
slouken@2713
   546
    Uint16 delay;       /**< Delay before starting the effect. */
slouken@2713
   547
slouken@2713
   548
    /* Trigger */
slouken@2713
   549
    Uint16 button;      /**< Button that triggers the effect. */
slouken@2713
   550
    Uint16 interval;    /**< How soon it can be triggered again after button. */
slouken@2713
   551
slouken@2713
   552
    /* Periodic */
slouken@2713
   553
    Uint16 period;      /**< Period of the wave. */
slouken@2713
   554
    Sint16 magnitude;   /**< Peak value. */
slouken@2713
   555
    Sint16 offset;      /**< Mean value of the wave. */
slouken@2713
   556
    Uint16 phase;       /**< Horizontal shift given by hundredth of a cycle. */
slouken@2713
   557
slouken@2713
   558
    /* Envelope */
slouken@2713
   559
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   560
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   561
    Uint16 fade_length; /**< Duration of the fade. */
slouken@2713
   562
    Uint16 fade_level;  /**< Level at the end of the fade. */
slouken@2713
   563
} SDL_HapticPeriodic;
slouken@3407
   564
slouken@2713
   565
/**
slouken@3407
   566
 *  \brief A structure containing a template for a Condition effect.
slouken@3407
   567
 *  
slouken@3407
   568
 *  The struct handles the following effects:
slouken@3407
   569
 *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
slouken@3407
   570
 *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
slouken@3407
   571
 *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
slouken@3407
   572
 *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
slouken@3407
   573
 *  
slouken@3407
   574
 *  Direction is handled by condition internals instead of a direction member.
slouken@2713
   575
 *  The condition effect specific members have three parameters.  The first
slouken@2713
   576
 *  refers to the X axis, the second refers to the Y axis and the third
slouken@2713
   577
 *  refers to the Z axis.  The right terms refer to the positive side of the
slouken@2713
   578
 *  axis and the left terms refer to the negative side of the axis.  Please 
slouken@3407
   579
 *  refer to the ::SDL_HapticDirection diagram for which side is positive and
slouken@2713
   580
 *  which is negative.
slouken@3407
   581
 *  
slouken@3407
   582
 *  \sa SDL_HapticDirection
slouken@3407
   583
 *  \sa SDL_HAPTIC_SPRING
slouken@3407
   584
 *  \sa SDL_HAPTIC_DAMPER
slouken@3407
   585
 *  \sa SDL_HAPTIC_INERTIA
slouken@3407
   586
 *  \sa SDL_HAPTIC_FRICTION
slouken@3407
   587
 *  \sa SDL_HapticEffect
slouken@2713
   588
 */
slouken@2713
   589
typedef struct SDL_HapticCondition
slouken@2713
   590
{
slouken@2713
   591
    /* Header */
slouken@3407
   592
    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
slouken@3407
   593
                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
slouken@2713
   594
    SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
slouken@2713
   595
slouken@2713
   596
    /* Replay */
slouken@2713
   597
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   598
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   599
slouken@2713
   600
    /* Trigger */
slouken@2713
   601
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   602
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   603
slouken@2713
   604
    /* Condition */
slouken@2713
   605
    Uint16 right_sat[3];    /**< Level when joystick is to the positive side. */
slouken@2713
   606
    Uint16 left_sat[3];     /**< Level when joystick is to the negative side. */
slouken@2713
   607
    Sint16 right_coeff[3];  /**< How fast to increase the force towards the positive side. */
slouken@2713
   608
    Sint16 left_coeff[3];   /**< How fast to increase the force towards the negative side. */
slouken@2713
   609
    Uint16 deadband[3];     /**< Size of the dead zone. */
slouken@2713
   610
    Sint16 center[3];       /**< Position of the dead zone. */
slouken@2713
   611
} SDL_HapticCondition;
slouken@3407
   612
slouken@2713
   613
/**
slouken@3407
   614
 *  \brief A structure containing a template for a Ramp effect.
slouken@3407
   615
 *  
slouken@3407
   616
 *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
slouken@3407
   617
 *  
slouken@3407
   618
 *  The ramp effect starts at start strength and ends at end strength.
slouken@2713
   619
 *  It augments in linear fashion.  If you use attack and fade with a ramp
slouken@2713
   620
 *  they effects get added to the ramp effect making the effect become
slouken@2713
   621
 *  quadratic instead of linear.
slouken@3407
   622
 *  
slouken@3407
   623
 *  \sa SDL_HAPTIC_RAMP
slouken@3407
   624
 *  \sa SDL_HapticEffect
slouken@2713
   625
 */
slouken@2713
   626
typedef struct SDL_HapticRamp
slouken@2713
   627
{
slouken@2713
   628
    /* Header */
slouken@3407
   629
    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
slouken@2713
   630
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   631
slouken@2713
   632
    /* Replay */
slouken@2713
   633
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   634
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   635
slouken@2713
   636
    /* Trigger */
slouken@2713
   637
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   638
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   639
slouken@2713
   640
    /* Ramp */
slouken@2713
   641
    Sint16 start;           /**< Beginning strength level. */
slouken@2713
   642
    Sint16 end;             /**< Ending strength level. */
slouken@2713
   643
slouken@2713
   644
    /* Envelope */
slouken@2713
   645
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   646
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   647
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   648
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   649
} SDL_HapticRamp;
slouken@3407
   650
slouken@2713
   651
/**
slouken@3407
   652
 *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
slouken@3407
   653
 *  
slouken@3407
   654
 *  A custom force feedback effect is much like a periodic effect, where the
slouken@2713
   655
 *  application can define it's exact shape.  You will have to allocate the
slouken@2713
   656
 *  data yourself.  Data should consist of channels * samples Uint16 samples.
slouken@3407
   657
 *  
slouken@3407
   658
 *  If channels is one, the effect is rotated using the defined direction.
slouken@2713
   659
 *  Otherwise it uses the samples in data for the different axes.
slouken@3407
   660
 *  
slouken@3407
   661
 *  \sa SDL_HAPTIC_CUSTOM
slouken@3407
   662
 *  \sa SDL_HapticEffect
slouken@2713
   663
 */
slouken@2713
   664
typedef struct SDL_HapticCustom
slouken@2713
   665
{
slouken@2713
   666
    /* Header */
slouken@3407
   667
    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
slouken@2713
   668
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   669
slouken@2713
   670
    /* Replay */
slouken@2713
   671
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   672
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   673
slouken@2713
   674
    /* Trigger */
slouken@2713
   675
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   676
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   677
slouken@2713
   678
    /* Custom */
slouken@2713
   679
    Uint8 channels;         /**< Axes to use, minimum of one. */
slouken@2713
   680
    Uint16 period;          /**< Sample periods. */
slouken@2713
   681
    Uint16 samples;         /**< Amount of samples. */
slouken@2713
   682
    Uint16 *data;           /**< Should contain channels*samples items. */
slouken@2713
   683
slouken@2713
   684
    /* Envelope */
slouken@2713
   685
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   686
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   687
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   688
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   689
} SDL_HapticCustom;
slouken@3407
   690
slouken@2713
   691
/**
slouken@3407
   692
 *  \brief The generic template for any haptic effect.
slouken@3407
   693
 *  
slouken@3407
   694
 *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
slouken@2713
   695
 *  Time values unless specified otherwise are in milliseconds.
slouken@3407
   696
 *  
slouken@3407
   697
 *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767 
slouken@3407
   698
 *  value.  Neither delay, interval, attack_length nor fade_length support 
slouken@3407
   699
 *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
slouken@3407
   700
 *  
slouken@3407
   701
 *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
slouken@3407
   702
 *  ::SDL_HAPTIC_INFINITY.
slouken@3407
   703
 *  
slouken@3407
   704
 *  Button triggers may not be supported on all devices, it is advised to not
slouken@2713
   705
 *  use them if possible.  Buttons start at index 1 instead of index 0 like
slouken@2713
   706
 *  they joystick.
slouken@3407
   707
 *  
slouken@3407
   708
 *  If both attack_length and fade_level are 0, the envelope is not used,
slouken@3407
   709
 *  otherwise both values are used.
slouken@3407
   710
 *  
slouken@3407
   711
 *  Common parts:
slouken@3407
   712
 *  \code
slouken@3407
   713
 *  // Replay - All effects have this
slouken@3407
   714
 *  Uint32 length;        // Duration of effect (ms).
slouken@3407
   715
 *  Uint16 delay;         // Delay before starting effect.
slouken@3407
   716
 *  
slouken@3407
   717
 *  // Trigger - All effects have this
slouken@3407
   718
 *  Uint16 button;        // Button that triggers effect.
slouken@3407
   719
 *  Uint16 interval;      // How soon before effect can be triggered again.
slouken@3407
   720
 *  
slouken@3407
   721
 *  // Envelope - All effects except condition effects have this
slouken@3407
   722
 *  Uint16 attack_length; // Duration of the attack (ms).
slouken@3407
   723
 *  Uint16 attack_level;  // Level at the start of the attack.
slouken@3407
   724
 *  Uint16 fade_length;   // Duration of the fade out (ms).
slouken@3407
   725
 *  Uint16 fade_level;    // Level at the end of the fade.
slouken@3407
   726
 *  \endcode
slouken@2713
   727
 *
slouken@2713
   728
 *
slouken@3407
   729
 *  Here we have an example of a constant effect evolution in time:
slouken@3407
   730
 *  \verbatim
slouken@3407
   731
    Strength
slouken@3407
   732
    ^
slouken@3407
   733
    |
slouken@3407
   734
    |    effect level -->  _________________
slouken@3407
   735
    |                     /                 \
slouken@3407
   736
    |                    /                   \
slouken@3407
   737
    |                   /                     \
slouken@3407
   738
    |                  /                       \ 
slouken@3407
   739
    | attack_level --> |                        \
slouken@3407
   740
    |                  |                        |  <---  fade_level
slouken@3407
   741
    |
slouken@3407
   742
    +--------------------------------------------------> Time
slouken@3407
   743
                       [--]                 [---]
slouken@3407
   744
                       attack_length        fade_length
slouken@3407
   745
    
slouken@3407
   746
    [------------------][-----------------------]
slouken@3407
   747
    delay               length
slouken@3407
   748
    \endverbatim
slouken@3407
   749
 *  
slouken@3407
   750
 *  Note either the attack_level or the fade_level may be above the actual
slouken@2713
   751
 *  effect level.
slouken@2713
   752
 *
slouken@3407
   753
 *  \sa SDL_HapticConstant
slouken@3407
   754
 *  \sa SDL_HapticPeriodic
slouken@3407
   755
 *  \sa SDL_HapticCondition
slouken@3407
   756
 *  \sa SDL_HapticRamp
slouken@3407
   757
 *  \sa SDL_HapticCustom
slouken@2713
   758
 */
slouken@2713
   759
typedef union SDL_HapticEffect
slouken@2713
   760
{
slouken@2713
   761
    /* Common for all force feedback effects */
slouken@2713
   762
    Uint16 type;                    /**< Effect type. */
slouken@2713
   763
    SDL_HapticConstant constant;    /**< Constant effect. */
slouken@2713
   764
    SDL_HapticPeriodic periodic;    /**< Periodic effect. */
slouken@2713
   765
    SDL_HapticCondition condition;  /**< Condition effect. */
slouken@2713
   766
    SDL_HapticRamp ramp;            /**< Ramp effect. */
slouken@2713
   767
    SDL_HapticCustom custom;        /**< Custom effect. */
slouken@2713
   768
} SDL_HapticEffect;
slouken@2713
   769
slouken@2713
   770
slouken@2713
   771
/* Function prototypes */
slouken@2713
   772
/**
slouken@3407
   773
 *  \brief Count the number of joysticks attached to the system.
slouken@3407
   774
 *  
slouken@3407
   775
 *  \return Number of haptic devices detected on the system.
slouken@2713
   776
 */
slouken@2713
   777
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
slouken@2713
   778
slouken@2713
   779
/**
slouken@3407
   780
 *  \brief Get the implementation dependent name of a Haptic device.
slouken@3407
   781
 *  
slouken@3407
   782
 *  This can be called before any joysticks are opened.
slouken@3407
   783
 *  If no name can be found, this function returns NULL.
slouken@3407
   784
 *  
slouken@3407
   785
 *  \param device_index Index of the device to get it's name.
slouken@3407
   786
 *  \return Name of the device or NULL on error.
slouken@2713
   787
 *
slouken@3407
   788
 *  \sa SDL_NumHaptics
slouken@2713
   789
 */
slouken@2713
   790
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
slouken@2713
   791
slouken@2713
   792
/**
slouken@3407
   793
 *  \brief Opens a Haptic device for usage.
slouken@3407
   794
 *  
slouken@3407
   795
 *  The index passed as an argument refers to the N'th Haptic device on this 
slouken@3407
   796
 *  system.
slouken@2713
   797
 *
slouken@3407
   798
 *  When opening a haptic device, it's gain will be set to maximum and
slouken@3407
   799
 *  autocenter will be disabled.  To modify these values use
slouken@3407
   800
 *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
slouken@2713
   801
 *
slouken@3407
   802
 *  \param device_index Index of the device to open.
slouken@3407
   803
 *  \return Device identifier or NULL on error.
slouken@2713
   804
 *
slouken@3407
   805
 *  \sa SDL_HapticIndex
slouken@3407
   806
 *  \sa SDL_HapticOpenFromMouse
slouken@3407
   807
 *  \sa SDL_HapticOpenFromJoystick
slouken@3407
   808
 *  \sa SDL_HapticClose
slouken@3407
   809
 *  \sa SDL_HapticSetGain
slouken@3407
   810
 *  \sa SDL_HapticSetAutocenter
slouken@3407
   811
 *  \sa SDL_HapticPause
slouken@3407
   812
 *  \sa SDL_HapticStopAll
slouken@2713
   813
 */
slouken@2713
   814
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
slouken@2713
   815
slouken@2713
   816
/**
slouken@3407
   817
 *  \brief Checks if the haptic device at index has been opened.
slouken@3407
   818
 *  
slouken@3407
   819
 *  \param device_index Index to check to see if it has been opened.
slouken@3407
   820
 *  \return 1 if it has been opened or 0 if it hasn't.
slouken@3407
   821
 *  
slouken@3407
   822
 *  \sa SDL_HapticOpen
slouken@3407
   823
 *  \sa SDL_HapticIndex
slouken@2713
   824
 */
slouken@2713
   825
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
slouken@2713
   826
slouken@2713
   827
/**
slouken@3407
   828
 *  \brief Gets the index of a haptic device.
slouken@3407
   829
 *  
slouken@3407
   830
 *  \param haptic Haptic device to get the index of.
slouken@3407
   831
 *  \return The index of the haptic device or -1 on error.
slouken@3407
   832
 *  
slouken@3407
   833
 *  \sa SDL_HapticOpen
slouken@3407
   834
 *  \sa SDL_HapticOpened
slouken@2713
   835
 */
slouken@2713
   836
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
slouken@2713
   837
slouken@2713
   838
/**
slouken@3407
   839
 *  \brief Gets whether or not the current mouse has haptic capabilities.
slouken@3407
   840
 *  
slouken@3407
   841
 *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
slouken@3407
   842
 *  
slouken@3407
   843
 *  \sa SDL_HapticOpenFromMouse
slouken@2713
   844
 */
slouken@2713
   845
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
slouken@2713
   846
slouken@2713
   847
/**
slouken@3407
   848
 *  \brief Tries to open a haptic device from the current mouse.
slouken@3407
   849
 *  
slouken@3407
   850
 *  \return The haptic device identifier or NULL on error.
slouken@3407
   851
 *  
slouken@3407
   852
 *  \sa SDL_MouseIsHaptic
slouken@3407
   853
 *  \sa SDL_HapticOpen
slouken@2713
   854
 */
slouken@2713
   855
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
slouken@2713
   856
slouken@2713
   857
/**
slouken@3407
   858
 *  \brief Checks to see if a joystick has haptic features.
slouken@3407
   859
 *  
slouken@3407
   860
 *  \param joystick Joystick to test for haptic capabilities.
slouken@3407
   861
 *  \return 1 if the joystick is haptic, 0 if it isn't
slouken@3407
   862
 *          or -1 if an error ocurred.
slouken@3407
   863
 *  
slouken@3407
   864
 *  \sa SDL_HapticOpenFromJoystick
slouken@2713
   865
 */
slouken@2713
   866
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
slouken@2713
   867
slouken@2713
   868
/**
slouken@3407
   869
 *  \brief Opens a Haptic device for usage from a Joystick device.
slouken@3407
   870
 *  
slouken@3407
   871
 *  You must still close the haptic device seperately.  It will not be closed 
slouken@3407
   872
 *  with the joystick.
slouken@3407
   873
 *  
slouken@3407
   874
 *  When opening from a joystick you should first close the haptic device before
slouken@2713
   875
 *  closing the joystick device.  If not, on some implementations the haptic
slouken@2713
   876
 *  device will also get unallocated and you'll be unable to use force feedback
slouken@2713
   877
 *  on that device.
slouken@3407
   878
 *  
slouken@3407
   879
 *  \param joystick Joystick to create a haptic device from.
slouken@3407
   880
 *  \return A valid haptic device identifier on success or NULL on error.
slouken@3407
   881
 *  
slouken@3407
   882
 *  \sa SDL_HapticOpen
slouken@3407
   883
 *  \sa SDL_HapticClose
slouken@2713
   884
 */
slouken@2713
   885
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
slouken@2713
   886
                                                               joystick);
slouken@2713
   887
slouken@2713
   888
/**
slouken@3407
   889
 *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
slouken@3407
   890
 *  
slouken@3407
   891
 *  \param haptic Haptic device to close.
slouken@2713
   892
 */
slouken@2713
   893
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
slouken@2713
   894
slouken@2713
   895
/**
slouken@3407
   896
 *  \brief Returns the number of effects a haptic device can store.
slouken@3407
   897
 *  
slouken@3407
   898
 *  On some platforms this isn't fully supported, and therefore is an
slouken@2713
   899
 *  aproximation.  Always check to see if your created effect was actually
slouken@3407
   900
 *  created and do not rely solely on SDL_HapticNumEffects().
slouken@3407
   901
 *  
slouken@3407
   902
 *  \param haptic The haptic device to query effect max.
slouken@3407
   903
 *  \return The number of effects the haptic device can store or
slouken@3407
   904
 *          -1 on error.
slouken@3407
   905
 *  
slouken@3407
   906
 *  \sa SDL_HapticNumEffectsPlaying
slouken@3407
   907
 *  \sa SDL_HapticQuery
slouken@2713
   908
 */
slouken@2713
   909
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
slouken@2713
   910
slouken@2713
   911
/**
slouken@3407
   912
 *  \brief Returns the number of effects a haptic device can play at the same 
slouken@3407
   913
 *         time.
slouken@3407
   914
 *  
slouken@3407
   915
 *  This is not supported on all platforms, but will always return a value.  
slouken@3407
   916
 *  Added here for the sake of completness.
slouken@3407
   917
 *  
slouken@3407
   918
 *  \param haptic The haptic device to query maximum playing effects.
slouken@3407
   919
 *  \return The number of effects the haptic device can play at the same time
slouken@3407
   920
 *          or -1 on error.
slouken@2713
   921
 *
slouken@3407
   922
 *  \sa SDL_HapticNumEffects
slouken@3407
   923
 *  \sa SDL_HapticQuery
slouken@2713
   924
 */
slouken@2713
   925
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
slouken@2713
   926
slouken@2713
   927
/**
slouken@3407
   928
 *  \brief Gets the haptic devices supported features in bitwise matter.
slouken@3407
   929
 *  
slouken@3407
   930
 *  Example: 
slouken@3407
   931
 *  \code
slouken@3407
   932
 *  if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
slouken@3407
   933
 *      printf("We have constant haptic effect!");
slouken@3407
   934
 *  }
slouken@3407
   935
 *  \endcode
slouken@3407
   936
 *  
slouken@3407
   937
 *  \param haptic The haptic device to query.
slouken@3407
   938
 *  \return Haptic features in bitwise manner (OR'd).
slouken@3407
   939
 *  
slouken@3407
   940
 *  \sa SDL_HapticNumEffects
slouken@3407
   941
 *  \sa SDL_HapticEffectSupported
slouken@2713
   942
 */
slouken@2713
   943
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
slouken@2713
   944
slouken@2713
   945
slouken@2713
   946
/**
slouken@3407
   947
 *  \brief Gets the number of haptic axes the device has.
slouken@3407
   948
 *  
slouken@3407
   949
 *  \sa SDL_HapticDirection
slouken@2713
   950
 */
slouken@2713
   951
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
slouken@2713
   952
slouken@2713
   953
/**
slouken@3407
   954
 *  \brief Checks to see if effect is supported by haptic.
slouken@3407
   955
 *  
slouken@3407
   956
 *  \param haptic Haptic device to check on.
slouken@3407
   957
 *  \param effect Effect to check to see if it is supported.
slouken@5360
   958
 *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
slouken@3407
   959
 *  
slouken@3407
   960
 *  \sa SDL_HapticQuery
slouken@3407
   961
 *  \sa SDL_HapticNewEffect
slouken@2713
   962
 */
slouken@2713
   963
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
slouken@2713
   964
                                                      SDL_HapticEffect *
slouken@2713
   965
                                                      effect);
slouken@2713
   966
slouken@2713
   967
/**
slouken@3407
   968
 *  \brief Creates a new haptic effect on the device.
slouken@3407
   969
 *  
slouken@3407
   970
 *  \param haptic Haptic device to create the effect on.
slouken@3407
   971
 *  \param effect Properties of the effect to create.
slouken@3407
   972
 *  \return The id of the effect on success or -1 on error.
slouken@3407
   973
 *  
slouken@3407
   974
 *  \sa SDL_HapticUpdateEffect
slouken@3407
   975
 *  \sa SDL_HapticRunEffect
slouken@3407
   976
 *  \sa SDL_HapticDestroyEffect
slouken@2713
   977
 */
slouken@2713
   978
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
slouken@2713
   979
                                                SDL_HapticEffect * effect);
slouken@2713
   980
slouken@2713
   981
/**
slouken@3407
   982
 *  \brief Updates the properties of an effect.
slouken@3407
   983
 *  
slouken@3407
   984
 *  Can be used dynamically, although behaviour when dynamically changing
slouken@3407
   985
 *  direction may be strange.  Specifically the effect may reupload itself
slouken@3407
   986
 *  and start playing from the start.  You cannot change the type either when
slouken@3407
   987
 *  running SDL_HapticUpdateEffect().
slouken@3407
   988
 *  
slouken@3407
   989
 *  \param haptic Haptic device that has the effect.
slouken@3407
   990
 *  \param effect Effect to update.
slouken@3407
   991
 *  \param data New effect properties to use.
slouken@3407
   992
 *  \return The id of the effect on success or -1 on error.
slouken@3407
   993
 *  
slouken@3407
   994
 *  \sa SDL_HapticNewEffect
slouken@3407
   995
 *  \sa SDL_HapticRunEffect
slouken@3407
   996
 *  \sa SDL_HapticDestroyEffect
slouken@2713
   997
 */
slouken@2713
   998
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
slouken@2713
   999
                                                   int effect,
slouken@2713
  1000
                                                   SDL_HapticEffect * data);
slouken@2713
  1001
slouken@2713
  1002
/**
slouken@3407
  1003
 *  \brief Runs the haptic effect on it's assosciated haptic device.
slouken@3407
  1004
 *  
slouken@3407
  1005
 *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
slouken@2713
  1006
 *  repeating the envelope (attack and fade) every time.  If you only want the
slouken@3407
  1007
 *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
slouken@2713
  1008
 *  parameter.
slouken@3407
  1009
 *  
slouken@3407
  1010
 *  \param haptic Haptic device to run the effect on.
slouken@3407
  1011
 *  \param effect Identifier of the haptic effect to run.
slouken@3407
  1012
 *  \param iterations Number of iterations to run the effect. Use
slouken@3407
  1013
 *         ::SDL_HAPTIC_INFINITY for infinity.
slouken@3407
  1014
 *  \return 0 on success or -1 on error.
slouken@3407
  1015
 *  
slouken@3407
  1016
 *  \sa SDL_HapticStopEffect
slouken@3407
  1017
 *  \sa SDL_HapticDestroyEffect
slouken@3407
  1018
 *  \sa SDL_HapticGetEffectStatus
slouken@2713
  1019
 */
slouken@2713
  1020
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
slouken@2713
  1021
                                                int effect,
slouken@2713
  1022
                                                Uint32 iterations);
slouken@2713
  1023
slouken@2713
  1024
/**
slouken@3407
  1025
 *  \brief Stops the haptic effect on it's assosciated haptic device.
slouken@3407
  1026
 *  
slouken@3407
  1027
 *  \param haptic Haptic device to stop the effect on.
slouken@3407
  1028
 *  \param effect Identifier of the effect to stop.
slouken@3407
  1029
 *  \return 0 on success or -1 on error.
slouken@3407
  1030
 *  
slouken@3407
  1031
 *  \sa SDL_HapticRunEffect
slouken@3407
  1032
 *  \sa SDL_HapticDestroyEffect
slouken@2713
  1033
 */
slouken@2713
  1034
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
slouken@2713
  1035
                                                 int effect);
slouken@2713
  1036
slouken@2713
  1037
/**
slouken@3407
  1038
 *  \brief Destroys a haptic effect on the device.
slouken@3407
  1039
 *  
slouken@3407
  1040
 *  This will stop the effect if it's running.  Effects are automatically 
slouken@3407
  1041
 *  destroyed when the device is closed.
slouken@3407
  1042
 *  
slouken@3407
  1043
 *  \param haptic Device to destroy the effect on.
slouken@3407
  1044
 *  \param effect Identifier of the effect to destroy.
slouken@3407
  1045
 *  
slouken@3407
  1046
 *  \sa SDL_HapticNewEffect
slouken@2713
  1047
 */
slouken@2713
  1048
extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
slouken@2713
  1049
                                                     int effect);
slouken@2713
  1050
slouken@2713
  1051
/**
slouken@3407
  1052
 *  \brief Gets the status of the current effect on the haptic device.
slouken@3407
  1053
 *  
slouken@3407
  1054
 *  Device must support the ::SDL_HAPTIC_STATUS feature.
slouken@3407
  1055
 *  
slouken@3407
  1056
 *  \param haptic Haptic device to query the effect status on.
slouken@3407
  1057
 *  \param effect Identifier of the effect to query it's status.
slouken@3407
  1058
 *  \return 0 if it isn't playing, ::SDL_HAPTIC_PLAYING if it is playing
slouken@3407
  1059
 *          or -1 on error.
slouken@3407
  1060
 *  
slouken@3407
  1061
 *  \sa SDL_HapticRunEffect
slouken@3407
  1062
 *  \sa SDL_HapticStopEffect
slouken@2713
  1063
 */
slouken@2713
  1064
extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
slouken@2713
  1065
                                                      int effect);
slouken@2713
  1066
slouken@2713
  1067
/**
slouken@3407
  1068
 *  \brief Sets the global gain of the device.
slouken@3407
  1069
 *  
slouken@3407
  1070
 *  Device must support the ::SDL_HAPTIC_GAIN feature.
slouken@3407
  1071
 *  
slouken@3407
  1072
 *  The user may specify the maxmimum gain by setting the environment variable
slouken@3407
  1073
 *  ::SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
slouken@3407
  1074
 *  SDL_HapticSetGain() will scale linearly using ::SDL_HAPTIC_GAIN_MAX as the
slouken@2713
  1075
 *  maximum.
slouken@3407
  1076
 *  
slouken@3407
  1077
 *  \param haptic Haptic device to set the gain on.
slouken@3407
  1078
 *  \param gain Value to set the gain to, should be between 0 and 100.
slouken@3407
  1079
 *  \return 0 on success or -1 on error.
slouken@3407
  1080
 *  
slouken@3407
  1081
 *  \sa SDL_HapticQuery
slouken@2713
  1082
 */
slouken@2713
  1083
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
slouken@2713
  1084
slouken@2713
  1085
/**
slouken@3407
  1086
 *  \brief Sets the global autocenter of the device.
slouken@3407
  1087
 *  
slouken@3407
  1088
 *  Autocenter should be between 0 and 100.  Setting it to 0 will disable 
slouken@3407
  1089
 *  autocentering.
slouken@2713
  1090
 *
slouken@3407
  1091
 *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
slouken@2713
  1092
 *
slouken@3407
  1093
 *  \param haptic Haptic device to set autocentering on.
slouken@3407
  1094
 *  \param autocenter Value to set autocenter to, 0 disables autocentering.
slouken@3407
  1095
 *  \return 0 on success or -1 on error.
slouken@3407
  1096
 *  
slouken@3407
  1097
 *  \sa SDL_HapticQuery
slouken@2713
  1098
 */
slouken@2713
  1099
extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
slouken@2713
  1100
                                                    int autocenter);
slouken@2713
  1101
slouken@2713
  1102
/**
slouken@3407
  1103
 *  \brief Pauses a haptic device.
slouken@3407
  1104
 *  
slouken@3407
  1105
 *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call 
slouken@3407
  1106
 *  SDL_HapticUnpause() to resume playback.
slouken@3407
  1107
 *  
slouken@3407
  1108
 *  Do not modify the effects nor add new ones while the device is paused.
slouken@2713
  1109
 *  That can cause all sorts of weird errors.
slouken@3407
  1110
 *  
slouken@3407
  1111
 *  \param haptic Haptic device to pause.
slouken@3407
  1112
 *  \return 0 on success or -1 on error.
slouken@3407
  1113
 *  
slouken@3407
  1114
 *  \sa SDL_HapticUnpause
slouken@2713
  1115
 */
slouken@2713
  1116
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
slouken@2713
  1117
slouken@2713
  1118
/**
slouken@3407
  1119
 *  \brief Unpauses a haptic device.
slouken@3407
  1120
 *  
slouken@3407
  1121
 *  Call to unpause after SDL_HapticPause().
slouken@3407
  1122
 *  
slouken@3407
  1123
 *  \param haptic Haptic device to pause.
slouken@3407
  1124
 *  \return 0 on success or -1 on error.
slouken@3407
  1125
 *  
slouken@3407
  1126
 *  \sa SDL_HapticPause
slouken@2713
  1127
 */
slouken@2713
  1128
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
slouken@2713
  1129
slouken@2713
  1130
/**
slouken@3407
  1131
 *  \brief Stops all the currently playing effects on a haptic device.
slouken@3407
  1132
 *  
slouken@3407
  1133
 *  \param haptic Haptic device to stop.
slouken@3407
  1134
 *  \return 0 on success or -1 on error.
slouken@2713
  1135
 */
slouken@2713
  1136
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
slouken@2713
  1137
slouken@5360
  1138
/**
slouken@5360
  1139
 *  \brief Checks to see if rumble is supported on a haptic device..
slouken@5360
  1140
 *
slouken@5360
  1141
 *  \param haptic Haptic device to check to see if it supports rumble.
slouken@5360
  1142
 *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
slouken@5360
  1143
 *
slouken@5360
  1144
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1145
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1146
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1147
 */
slouken@5360
  1148
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
slouken@5360
  1149
slouken@5360
  1150
/**
slouken@5360
  1151
 *  \brief Initializes the haptic device for simple rumble playback.
slouken@5360
  1152
 *
slouken@5360
  1153
 *  \param haptic Haptic device to initialize for simple rumble playback.
slouken@5360
  1154
 *  \return 0 on success or -1 on error.
slouken@5360
  1155
 *
slouken@5360
  1156
 *  \sa SDL_HapticOpen
slouken@5360
  1157
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1158
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1159
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1160
 */
slouken@5360
  1161
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
slouken@5360
  1162
slouken@5360
  1163
/**
slouken@5360
  1164
 *  \brief Runs simple rumble on a haptic device
slouken@5360
  1165
 *
slouken@5360
  1166
 *  \param haptic Haptic device to play rumble effect on.
slouken@5360
  1167
 *  \param strength Strength of the rumble to play as a 0-1 float value.
slouken@5360
  1168
 *  \param length Length of the rumble to play in miliseconds.
slouken@5360
  1169
 *  \return 0 on success or -1 on error.
slouken@5360
  1170
 *
slouken@5360
  1171
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1172
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1173
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1174
 */
slouken@5360
  1175
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
slouken@5360
  1176
slouken@5360
  1177
/**
slouken@5360
  1178
 *  \brief Stops the simple rumble on a haptic device.
slouken@5360
  1179
 *
slouken@5360
  1180
 *  \param haptic Haptic to stop the rumble on.
slouken@5360
  1181
 *  \return 0 on success or -1 on error.
slouken@5360
  1182
 *
slouken@5360
  1183
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1184
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1185
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1186
 */
slouken@5360
  1187
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
slouken@5360
  1188
slouken@5360
  1189
slouken@2713
  1190
slouken@2713
  1191
/* Ends C function definitions when using C++ */
slouken@2713
  1192
#ifdef __cplusplus
slouken@2713
  1193
/* *INDENT-OFF* */
slouken@2713
  1194
}
slouken@2713
  1195
/* *INDENT-ON* */
slouken@2713
  1196
#endif
slouken@2713
  1197
#include "close_code.h"
slouken@2713
  1198
slouken@2713
  1199
#endif /* _SDL_haptic_h */
slouken@2713
  1200
slouken@2713
  1201
/* vi: set ts=4 sw=4 expandtab: */