include/SDL_haptic.h
author Sam Lantinga
Mon, 04 May 2020 13:17:43 -0700
changeset 13789 a359f4f93439
parent 13645 f7fc52b64177
permissions -rw-r--r--
Improvement for bug 3446 - The haptic API does not allow to select the direction axes

meyraud705

I see how the documentation is confusing. I think that the choice of the axis is an implementation detail. The documentation should state the goal of this value, so I propose this wording:

"Use this value to play an effect on the steering wheel axis. This provides
better compatibility across platforms and devices as SDL will guess the
correct axis."

Value could even be renamed 'SDL_HAPTIC_STEERING_AXIS'.

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