include/SDL_haptic.h
author Ryan C. Gordon <icculus@icculus.org>
Wed, 17 Sep 2014 14:49:36 -0400
changeset 9147 6bf589c8d549
parent 9146 dbef1f283c3f
child 9249 35a4fab04296
permissions -rw-r--r--
Haptic: Deal with negative periodic magnitudes (thanks, Elias!).

A negative periodic magnitude doesn't exist in Windows' and MacOS' FF APIs

The periodic magnitude parameter of the SDL Haptic API is based on the Linux
FF API, so it means they are not directly compatible:
'dwMagnitude' is a 'DWORD', which is unsigned.

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