include/SDL_haptic.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 29 Nov 2014 11:48:43 -0800
changeset 9249 35a4fab04296
parent 9147 6bf589c8d549
child 9250 50fb32b7f2bd
permissions -rw-r--r--
Fixed bug 2766 - Haptic coding bugs and fixes for Linux FF: periodic.phase handled as time instead of angle; + direction clarification

Elias Vanderstuyft

It's not obvious from the general "haptic direction" description what the SDL direction actually means in terms of force magnitude sign,
currently its meaning is only reflected by the example.
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@9249
   350
 *  This is the direction where the force comes from,
slouken@9249
   351
 *  instead of the direction in which the force is exerted.
slouken@9249
   352
 *
slouken@3407
   353
 *  Directions can be specified by:
slouken@3407
   354
 *   - ::SDL_HAPTIC_POLAR : Specified by polar coordinates.
slouken@3407
   355
 *   - ::SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
slouken@3407
   356
 *   - ::SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
slouken@2713
   357
 *
slouken@3407
   358
 *  Cardinal directions of the haptic device are relative to the positioning
slouken@2713
   359
 *  of the device.  North is considered to be away from the user.
slouken@2713
   360
 *
slouken@3407
   361
 *  The following diagram represents the cardinal directions:
slouken@3407
   362
 *  \verbatim
slouken@3407
   363
                 .--.
slouken@3407
   364
                 |__| .-------.
slouken@3407
   365
                 |=.| |.-----.|
slouken@3407
   366
                 |--| ||     ||
slouken@3407
   367
                 |  | |'-----'|
slouken@3407
   368
                 |__|~')_____('
slouken@3407
   369
                   [ COMPUTER ]
slouken@7191
   370
slouken@7191
   371
slouken@3407
   372
                     North (0,-1)
slouken@3407
   373
                         ^
slouken@3407
   374
                         |
slouken@3407
   375
                         |
icculus@9068
   376
   (-1,0)  West <----[ HAPTIC ]----> East (1,0)
slouken@3407
   377
                         |
slouken@3407
   378
                         |
slouken@3407
   379
                         v
slouken@3407
   380
                      South (0,1)
slouken@7191
   381
slouken@7191
   382
slouken@3407
   383
                      [ USER ]
slouken@3407
   384
                        \|||/
slouken@3407
   385
                        (o o)
slouken@3407
   386
                  ---ooO-(_)-Ooo---
slouken@3407
   387
    \endverbatim
slouken@7191
   388
 *
slouken@7191
   389
 *  If type is ::SDL_HAPTIC_POLAR, direction is encoded by hundredths of a
slouken@3407
   390
 *  degree starting north and turning clockwise.  ::SDL_HAPTIC_POLAR only uses
slouken@3407
   391
 *  the first \c dir parameter.  The cardinal directions would be:
slouken@2713
   392
 *   - North: 0 (0 degrees)
slouken@2713
   393
 *   - East: 9000 (90 degrees)
slouken@2713
   394
 *   - South: 18000 (180 degrees)
slouken@2713
   395
 *   - West: 27000 (270 degrees)
slouken@7191
   396
 *
slouken@3407
   397
 *  If type is ::SDL_HAPTIC_CARTESIAN, direction is encoded by three positions
slouken@3407
   398
 *  (X axis, Y axis and Z axis (with 3 axes)).  ::SDL_HAPTIC_CARTESIAN uses
slouken@3407
   399
 *  the first three \c dir parameters.  The cardinal directions would be:
slouken@2713
   400
 *   - North:  0,-1, 0
icculus@9068
   401
 *   - East:   1, 0, 0
slouken@2713
   402
 *   - South:  0, 1, 0
icculus@9068
   403
 *   - West:  -1, 0, 0
slouken@7191
   404
 *
slouken@2713
   405
 *  The Z axis represents the height of the effect if supported, otherwise
slouken@3407
   406
 *  it's unused.  In cartesian encoding (1, 2) would be the same as (2, 4), you
slouken@2713
   407
 *  can use any multiple you want, only the direction matters.
slouken@7191
   408
 *
slouken@3407
   409
 *  If type is ::SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations.
slouken@7191
   410
 *  The first two \c dir parameters are used.  The \c dir parameters are as
slouken@3407
   411
 *  follows (all values are in hundredths of degrees):
slouken@3407
   412
 *   - Degrees from (1, 0) rotated towards (0, 1).
slouken@3407
   413
 *   - Degrees towards (0, 0, 1) (device needs at least 3 axes).
slouken@2713
   414
 *
slouken@2713
   415
 *
slouken@3407
   416
 *  Example of force coming from the south with all encodings (force coming
slouken@3407
   417
 *  from the south means the user will have to pull the stick to counteract):
slouken@3407
   418
 *  \code
slouken@3407
   419
 *  SDL_HapticDirection direction;
slouken@7191
   420
 *
slouken@3407
   421
 *  // Cartesian directions
slouken@3407
   422
 *  direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding.
slouken@3407
   423
 *  direction.dir[0] = 0; // X position
slouken@3407
   424
 *  direction.dir[1] = 1; // Y position
slouken@3407
   425
 *  // Assuming the device has 2 axes, we don't need to specify third parameter.
slouken@7191
   426
 *
slouken@3407
   427
 *  // Polar directions
slouken@3407
   428
 *  direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding.
slouken@3407
   429
 *  direction.dir[0] = 18000; // Polar only uses first parameter
slouken@7191
   430
 *
slouken@3407
   431
 *  // Spherical coordinates
slouken@3407
   432
 *  direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding
slouken@3407
   433
 *  direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters.
slouken@3407
   434
 *  \endcode
slouken@2713
   435
 *
slouken@3407
   436
 *  \sa SDL_HAPTIC_POLAR
slouken@3407
   437
 *  \sa SDL_HAPTIC_CARTESIAN
slouken@3407
   438
 *  \sa SDL_HAPTIC_SPHERICAL
slouken@3407
   439
 *  \sa SDL_HapticEffect
slouken@3407
   440
 *  \sa SDL_HapticNumAxes
slouken@2713
   441
 */
slouken@2713
   442
typedef struct SDL_HapticDirection
slouken@2713
   443
{
slouken@2713
   444
    Uint8 type;         /**< The type of encoding. */
slouken@3496
   445
    Sint32 dir[3];      /**< The encoded direction. */
slouken@2713
   446
} SDL_HapticDirection;
slouken@2713
   447
slouken@2713
   448
slouken@2713
   449
/**
slouken@3407
   450
 *  \brief A structure containing a template for a Constant effect.
slouken@7191
   451
 *
slouken@3407
   452
 *  The struct is exclusive to the ::SDL_HAPTIC_CONSTANT effect.
slouken@7191
   453
 *
slouken@3407
   454
 *  A constant effect applies a constant force in the specified direction
slouken@2713
   455
 *  to the joystick.
slouken@7191
   456
 *
slouken@3407
   457
 *  \sa SDL_HAPTIC_CONSTANT
slouken@3407
   458
 *  \sa SDL_HapticEffect
slouken@2713
   459
 */
slouken@2713
   460
typedef struct SDL_HapticConstant
slouken@2713
   461
{
slouken@2713
   462
    /* Header */
slouken@3407
   463
    Uint16 type;            /**< ::SDL_HAPTIC_CONSTANT */
slouken@2713
   464
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   465
slouken@2713
   466
    /* Replay */
slouken@2713
   467
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   468
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   469
slouken@2713
   470
    /* Trigger */
slouken@2713
   471
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   472
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   473
slouken@2713
   474
    /* Constant */
slouken@2713
   475
    Sint16 level;           /**< Strength of the constant effect. */
slouken@2713
   476
slouken@2713
   477
    /* Envelope */
slouken@2713
   478
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   479
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   480
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   481
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   482
} SDL_HapticConstant;
slouken@3407
   483
slouken@2713
   484
/**
slouken@3407
   485
 *  \brief A structure containing a template for a Periodic effect.
slouken@7191
   486
 *
slouken@3407
   487
 *  The struct handles the following effects:
slouken@3407
   488
 *   - ::SDL_HAPTIC_SINE
philipp@7630
   489
 *   - ::SDL_HAPTIC_LEFTRIGHT
slouken@3407
   490
 *   - ::SDL_HAPTIC_TRIANGLE
slouken@3407
   491
 *   - ::SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   492
 *   - ::SDL_HAPTIC_SAWTOOTHDOWN
slouken@7191
   493
 *
slouken@3407
   494
 *  A periodic effect consists in a wave-shaped effect that repeats itself
slouken@2713
   495
 *  over time.  The type determines the shape of the wave and the parameters
slouken@2713
   496
 *  determine the dimensions of the wave.
slouken@7191
   497
 *
icculus@9146
   498
 *  Phase is given by hundredth of a degree meaning that giving the phase a value
philipp@7125
   499
 *  of 9000 will displace it 25% of its period.  Here are sample values:
slouken@3407
   500
 *   -     0: No phase displacement.
philipp@7125
   501
 *   -  9000: Displaced 25% of its period.
philipp@7125
   502
 *   - 18000: Displaced 50% of its period.
philipp@7125
   503
 *   - 27000: Displaced 75% of its period.
philipp@7125
   504
 *   - 36000: Displaced 100% of its period, same as 0, but 0 is preferred.
slouken@2713
   505
 *
slouken@3407
   506
 *  Examples:
slouken@3407
   507
 *  \verbatim
slouken@3407
   508
    SDL_HAPTIC_SINE
slouken@3407
   509
      __      __      __      __
slouken@3407
   510
     /  \    /  \    /  \    /
slouken@3407
   511
    /    \__/    \__/    \__/
slouken@7191
   512
slouken@3407
   513
    SDL_HAPTIC_SQUARE
slouken@3407
   514
     __    __    __    __    __
slouken@3407
   515
    |  |  |  |  |  |  |  |  |  |
slouken@3407
   516
    |  |__|  |__|  |__|  |__|  |
slouken@7191
   517
slouken@3407
   518
    SDL_HAPTIC_TRIANGLE
slouken@3407
   519
      /\    /\    /\    /\    /\
slouken@3407
   520
     /  \  /  \  /  \  /  \  /
slouken@3407
   521
    /    \/    \/    \/    \/
slouken@7191
   522
slouken@3407
   523
    SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   524
      /|  /|  /|  /|  /|  /|  /|
slouken@3407
   525
     / | / | / | / | / | / | / |
slouken@3407
   526
    /  |/  |/  |/  |/  |/  |/  |
slouken@7191
   527
slouken@3407
   528
    SDL_HAPTIC_SAWTOOTHDOWN
slouken@3407
   529
    \  |\  |\  |\  |\  |\  |\  |
slouken@3407
   530
     \ | \ | \ | \ | \ | \ | \ |
slouken@3407
   531
      \|  \|  \|  \|  \|  \|  \|
slouken@3407
   532
    \endverbatim
slouken@7191
   533
 *
slouken@3407
   534
 *  \sa SDL_HAPTIC_SINE
philipp@7630
   535
 *  \sa SDL_HAPTIC_LEFTRIGHT
slouken@3407
   536
 *  \sa SDL_HAPTIC_TRIANGLE
slouken@3407
   537
 *  \sa SDL_HAPTIC_SAWTOOTHUP
slouken@3407
   538
 *  \sa SDL_HAPTIC_SAWTOOTHDOWN
slouken@3407
   539
 *  \sa SDL_HapticEffect
slouken@2713
   540
 */
slouken@2713
   541
typedef struct SDL_HapticPeriodic
slouken@2713
   542
{
slouken@2713
   543
    /* Header */
philipp@7630
   544
    Uint16 type;        /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_LEFTRIGHT,
slouken@3407
   545
                             ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or
slouken@3407
   546
                             ::SDL_HAPTIC_SAWTOOTHDOWN */
slouken@2713
   547
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   548
slouken@2713
   549
    /* Replay */
slouken@2713
   550
    Uint32 length;      /**< Duration of the effect. */
slouken@2713
   551
    Uint16 delay;       /**< Delay before starting the effect. */
slouken@2713
   552
slouken@2713
   553
    /* Trigger */
slouken@2713
   554
    Uint16 button;      /**< Button that triggers the effect. */
slouken@2713
   555
    Uint16 interval;    /**< How soon it can be triggered again after button. */
slouken@2713
   556
slouken@2713
   557
    /* Periodic */
slouken@2713
   558
    Uint16 period;      /**< Period of the wave. */
icculus@9147
   559
    Sint16 magnitude;   /**< Peak value; if negative, equivalent to 180 degrees extra phase shift. */
slouken@2713
   560
    Sint16 offset;      /**< Mean value of the wave. */
icculus@9146
   561
    Uint16 phase;       /**< Horizontal shift given by hundredth of a degree. */
slouken@2713
   562
slouken@2713
   563
    /* Envelope */
slouken@2713
   564
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   565
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   566
    Uint16 fade_length; /**< Duration of the fade. */
slouken@2713
   567
    Uint16 fade_level;  /**< Level at the end of the fade. */
slouken@2713
   568
} SDL_HapticPeriodic;
slouken@3407
   569
slouken@2713
   570
/**
slouken@3407
   571
 *  \brief A structure containing a template for a Condition effect.
slouken@7191
   572
 *
slouken@3407
   573
 *  The struct handles the following effects:
slouken@3407
   574
 *   - ::SDL_HAPTIC_SPRING: Effect based on axes position.
slouken@3407
   575
 *   - ::SDL_HAPTIC_DAMPER: Effect based on axes velocity.
slouken@3407
   576
 *   - ::SDL_HAPTIC_INERTIA: Effect based on axes acceleration.
slouken@3407
   577
 *   - ::SDL_HAPTIC_FRICTION: Effect based on axes movement.
slouken@7191
   578
 *
slouken@3407
   579
 *  Direction is handled by condition internals instead of a direction member.
slouken@2713
   580
 *  The condition effect specific members have three parameters.  The first
slouken@2713
   581
 *  refers to the X axis, the second refers to the Y axis and the third
slouken@2713
   582
 *  refers to the Z axis.  The right terms refer to the positive side of the
slouken@7191
   583
 *  axis and the left terms refer to the negative side of the axis.  Please
slouken@3407
   584
 *  refer to the ::SDL_HapticDirection diagram for which side is positive and
slouken@2713
   585
 *  which is negative.
slouken@7191
   586
 *
slouken@3407
   587
 *  \sa SDL_HapticDirection
slouken@3407
   588
 *  \sa SDL_HAPTIC_SPRING
slouken@3407
   589
 *  \sa SDL_HAPTIC_DAMPER
slouken@3407
   590
 *  \sa SDL_HAPTIC_INERTIA
slouken@3407
   591
 *  \sa SDL_HAPTIC_FRICTION
slouken@3407
   592
 *  \sa SDL_HapticEffect
slouken@2713
   593
 */
slouken@2713
   594
typedef struct SDL_HapticCondition
slouken@2713
   595
{
slouken@2713
   596
    /* Header */
slouken@3407
   597
    Uint16 type;            /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER,
slouken@3407
   598
                                 ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */
slouken@2713
   599
    SDL_HapticDirection direction;  /**< Direction of the effect - Not used ATM. */
slouken@2713
   600
slouken@2713
   601
    /* Replay */
slouken@2713
   602
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   603
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   604
slouken@2713
   605
    /* Trigger */
slouken@2713
   606
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   607
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   608
slouken@2713
   609
    /* Condition */
icculus@9070
   610
    Uint16 right_sat[3];    /**< Level when joystick is to the positive side; max 0xFFFF. */
icculus@9070
   611
    Uint16 left_sat[3];     /**< Level when joystick is to the negative side; max 0xFFFF. */
slouken@2713
   612
    Sint16 right_coeff[3];  /**< How fast to increase the force towards the positive side. */
slouken@2713
   613
    Sint16 left_coeff[3];   /**< How fast to increase the force towards the negative side. */
icculus@9070
   614
    Uint16 deadband[3];     /**< Size of the dead zone; max 0xFFFF: whole axis-range when 0-centered. */
slouken@2713
   615
    Sint16 center[3];       /**< Position of the dead zone. */
slouken@2713
   616
} SDL_HapticCondition;
slouken@3407
   617
slouken@2713
   618
/**
slouken@3407
   619
 *  \brief A structure containing a template for a Ramp effect.
slouken@7191
   620
 *
slouken@3407
   621
 *  This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
slouken@7191
   622
 *
slouken@3407
   623
 *  The ramp effect starts at start strength and ends at end strength.
slouken@2713
   624
 *  It augments in linear fashion.  If you use attack and fade with a ramp
philipp@7221
   625
 *  the effects get added to the ramp effect making the effect become
slouken@2713
   626
 *  quadratic instead of linear.
slouken@7191
   627
 *
slouken@3407
   628
 *  \sa SDL_HAPTIC_RAMP
slouken@3407
   629
 *  \sa SDL_HapticEffect
slouken@2713
   630
 */
slouken@2713
   631
typedef struct SDL_HapticRamp
slouken@2713
   632
{
slouken@2713
   633
    /* Header */
slouken@3407
   634
    Uint16 type;            /**< ::SDL_HAPTIC_RAMP */
slouken@2713
   635
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   636
slouken@2713
   637
    /* Replay */
slouken@2713
   638
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   639
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   640
slouken@2713
   641
    /* Trigger */
slouken@2713
   642
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   643
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   644
slouken@2713
   645
    /* Ramp */
slouken@2713
   646
    Sint16 start;           /**< Beginning strength level. */
slouken@2713
   647
    Sint16 end;             /**< Ending strength level. */
slouken@2713
   648
slouken@2713
   649
    /* Envelope */
slouken@2713
   650
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   651
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   652
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   653
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   654
} SDL_HapticRamp;
slouken@3407
   655
slouken@2713
   656
/**
icculus@7621
   657
 * \brief A structure containing a template for a Left/Right effect.
icculus@7621
   658
 *
icculus@7621
   659
 * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
icculus@7621
   660
 *
icculus@7621
   661
 * The Left/Right effect is used to explicitly control the large and small
icculus@7621
   662
 * motors, commonly found in modern game controllers. One motor is high
icculus@7621
   663
 * frequency, the other is low frequency.
icculus@7621
   664
 *
icculus@7621
   665
 * \sa SDL_HAPTIC_LEFTRIGHT
icculus@7621
   666
 * \sa SDL_HapticEffect
icculus@7621
   667
 */
icculus@7621
   668
typedef struct SDL_HapticLeftRight
icculus@7621
   669
{
icculus@7621
   670
    /* Header */
icculus@7621
   671
    Uint16 type;            /**< ::SDL_HAPTIC_LEFTRIGHT */
icculus@7621
   672
icculus@7621
   673
    /* Replay */
icculus@7621
   674
    Uint32 length;          /**< Duration of the effect. */
icculus@7621
   675
icculus@7621
   676
    /* Rumble */
icculus@7621
   677
    Uint16 large_magnitude; /**< Control of the large controller motor. */
icculus@7621
   678
    Uint16 small_magnitude; /**< Control of the small controller motor. */
icculus@7621
   679
} SDL_HapticLeftRight;
icculus@7621
   680
icculus@7621
   681
/**
slouken@3407
   682
 *  \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
slouken@7191
   683
 *
slouken@3407
   684
 *  A custom force feedback effect is much like a periodic effect, where the
philipp@7125
   685
 *  application can define its exact shape.  You will have to allocate the
slouken@2713
   686
 *  data yourself.  Data should consist of channels * samples Uint16 samples.
slouken@7191
   687
 *
slouken@3407
   688
 *  If channels is one, the effect is rotated using the defined direction.
slouken@2713
   689
 *  Otherwise it uses the samples in data for the different axes.
slouken@7191
   690
 *
slouken@3407
   691
 *  \sa SDL_HAPTIC_CUSTOM
slouken@3407
   692
 *  \sa SDL_HapticEffect
slouken@2713
   693
 */
slouken@2713
   694
typedef struct SDL_HapticCustom
slouken@2713
   695
{
slouken@2713
   696
    /* Header */
slouken@3407
   697
    Uint16 type;            /**< ::SDL_HAPTIC_CUSTOM */
slouken@2713
   698
    SDL_HapticDirection direction;  /**< Direction of the effect. */
slouken@2713
   699
slouken@2713
   700
    /* Replay */
slouken@2713
   701
    Uint32 length;          /**< Duration of the effect. */
slouken@2713
   702
    Uint16 delay;           /**< Delay before starting the effect. */
slouken@2713
   703
slouken@2713
   704
    /* Trigger */
slouken@2713
   705
    Uint16 button;          /**< Button that triggers the effect. */
slouken@2713
   706
    Uint16 interval;        /**< How soon it can be triggered again after button. */
slouken@2713
   707
slouken@2713
   708
    /* Custom */
slouken@2713
   709
    Uint8 channels;         /**< Axes to use, minimum of one. */
slouken@2713
   710
    Uint16 period;          /**< Sample periods. */
slouken@2713
   711
    Uint16 samples;         /**< Amount of samples. */
slouken@2713
   712
    Uint16 *data;           /**< Should contain channels*samples items. */
slouken@2713
   713
slouken@2713
   714
    /* Envelope */
slouken@2713
   715
    Uint16 attack_length;   /**< Duration of the attack. */
slouken@2713
   716
    Uint16 attack_level;    /**< Level at the start of the attack. */
slouken@2713
   717
    Uint16 fade_length;     /**< Duration of the fade. */
slouken@2713
   718
    Uint16 fade_level;      /**< Level at the end of the fade. */
slouken@2713
   719
} SDL_HapticCustom;
slouken@3407
   720
slouken@2713
   721
/**
slouken@3407
   722
 *  \brief The generic template for any haptic effect.
slouken@7191
   723
 *
slouken@3407
   724
 *  All values max at 32767 (0x7FFF).  Signed values also can be negative.
slouken@2713
   725
 *  Time values unless specified otherwise are in milliseconds.
slouken@7191
   726
 *
slouken@7191
   727
 *  You can also pass ::SDL_HAPTIC_INFINITY to length instead of a 0-32767
slouken@7191
   728
 *  value.  Neither delay, interval, attack_length nor fade_length support
slouken@3407
   729
 *  ::SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
slouken@7191
   730
 *
slouken@3407
   731
 *  Additionally, the ::SDL_HAPTIC_RAMP effect does not support a duration of
slouken@3407
   732
 *  ::SDL_HAPTIC_INFINITY.
slouken@7191
   733
 *
slouken@3407
   734
 *  Button triggers may not be supported on all devices, it is advised to not
slouken@2713
   735
 *  use them if possible.  Buttons start at index 1 instead of index 0 like
philipp@7221
   736
 *  the joystick.
slouken@7191
   737
 *
slouken@3407
   738
 *  If both attack_length and fade_level are 0, the envelope is not used,
slouken@3407
   739
 *  otherwise both values are used.
slouken@7191
   740
 *
slouken@3407
   741
 *  Common parts:
slouken@3407
   742
 *  \code
slouken@3407
   743
 *  // Replay - All effects have this
slouken@3407
   744
 *  Uint32 length;        // Duration of effect (ms).
slouken@3407
   745
 *  Uint16 delay;         // Delay before starting effect.
slouken@7191
   746
 *
slouken@3407
   747
 *  // Trigger - All effects have this
slouken@3407
   748
 *  Uint16 button;        // Button that triggers effect.
slouken@3407
   749
 *  Uint16 interval;      // How soon before effect can be triggered again.
slouken@7191
   750
 *
slouken@3407
   751
 *  // Envelope - All effects except condition effects have this
slouken@3407
   752
 *  Uint16 attack_length; // Duration of the attack (ms).
slouken@3407
   753
 *  Uint16 attack_level;  // Level at the start of the attack.
slouken@3407
   754
 *  Uint16 fade_length;   // Duration of the fade out (ms).
slouken@3407
   755
 *  Uint16 fade_level;    // Level at the end of the fade.
slouken@3407
   756
 *  \endcode
slouken@2713
   757
 *
slouken@2713
   758
 *
slouken@3407
   759
 *  Here we have an example of a constant effect evolution in time:
slouken@3407
   760
 *  \verbatim
slouken@3407
   761
    Strength
slouken@3407
   762
    ^
slouken@3407
   763
    |
slouken@3407
   764
    |    effect level -->  _________________
slouken@3407
   765
    |                     /                 \
slouken@3407
   766
    |                    /                   \
slouken@3407
   767
    |                   /                     \
slouken@7191
   768
    |                  /                       \
slouken@3407
   769
    | attack_level --> |                        \
slouken@3407
   770
    |                  |                        |  <---  fade_level
slouken@3407
   771
    |
slouken@3407
   772
    +--------------------------------------------------> Time
slouken@3407
   773
                       [--]                 [---]
slouken@3407
   774
                       attack_length        fade_length
slouken@7191
   775
slouken@3407
   776
    [------------------][-----------------------]
slouken@3407
   777
    delay               length
slouken@3407
   778
    \endverbatim
slouken@7191
   779
 *
slouken@3407
   780
 *  Note either the attack_level or the fade_level may be above the actual
slouken@2713
   781
 *  effect level.
slouken@2713
   782
 *
slouken@3407
   783
 *  \sa SDL_HapticConstant
slouken@3407
   784
 *  \sa SDL_HapticPeriodic
slouken@3407
   785
 *  \sa SDL_HapticCondition
slouken@3407
   786
 *  \sa SDL_HapticRamp
icculus@7621
   787
 *  \sa SDL_HapticLeftRight
slouken@3407
   788
 *  \sa SDL_HapticCustom
slouken@2713
   789
 */
slouken@2713
   790
typedef union SDL_HapticEffect
slouken@2713
   791
{
slouken@2713
   792
    /* Common for all force feedback effects */
slouken@2713
   793
    Uint16 type;                    /**< Effect type. */
slouken@2713
   794
    SDL_HapticConstant constant;    /**< Constant effect. */
slouken@2713
   795
    SDL_HapticPeriodic periodic;    /**< Periodic effect. */
slouken@2713
   796
    SDL_HapticCondition condition;  /**< Condition effect. */
slouken@2713
   797
    SDL_HapticRamp ramp;            /**< Ramp effect. */
icculus@7621
   798
    SDL_HapticLeftRight leftright;  /**< Left/Right effect. */
slouken@2713
   799
    SDL_HapticCustom custom;        /**< Custom effect. */
slouken@2713
   800
} SDL_HapticEffect;
slouken@2713
   801
slouken@2713
   802
slouken@2713
   803
/* Function prototypes */
slouken@2713
   804
/**
philipp@7221
   805
 *  \brief Count the number of haptic devices attached to the system.
slouken@7191
   806
 *
slouken@3407
   807
 *  \return Number of haptic devices detected on the system.
slouken@2713
   808
 */
slouken@2713
   809
extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
slouken@2713
   810
slouken@2713
   811
/**
slouken@3407
   812
 *  \brief Get the implementation dependent name of a Haptic device.
slouken@7191
   813
 *
slouken@3407
   814
 *  This can be called before any joysticks are opened.
slouken@3407
   815
 *  If no name can be found, this function returns NULL.
slouken@7191
   816
 *
philipp@7125
   817
 *  \param device_index Index of the device to get its name.
slouken@3407
   818
 *  \return Name of the device or NULL on error.
slouken@2713
   819
 *
slouken@3407
   820
 *  \sa SDL_NumHaptics
slouken@2713
   821
 */
slouken@2713
   822
extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
slouken@2713
   823
slouken@2713
   824
/**
slouken@3407
   825
 *  \brief Opens a Haptic device for usage.
slouken@7191
   826
 *
slouken@7191
   827
 *  The index passed as an argument refers to the N'th Haptic device on this
slouken@3407
   828
 *  system.
slouken@2713
   829
 *
philipp@7125
   830
 *  When opening a haptic device, its gain will be set to maximum and
slouken@3407
   831
 *  autocenter will be disabled.  To modify these values use
slouken@3407
   832
 *  SDL_HapticSetGain() and SDL_HapticSetAutocenter().
slouken@2713
   833
 *
slouken@3407
   834
 *  \param device_index Index of the device to open.
slouken@3407
   835
 *  \return Device identifier or NULL on error.
slouken@2713
   836
 *
slouken@3407
   837
 *  \sa SDL_HapticIndex
slouken@3407
   838
 *  \sa SDL_HapticOpenFromMouse
slouken@3407
   839
 *  \sa SDL_HapticOpenFromJoystick
slouken@3407
   840
 *  \sa SDL_HapticClose
slouken@3407
   841
 *  \sa SDL_HapticSetGain
slouken@3407
   842
 *  \sa SDL_HapticSetAutocenter
slouken@3407
   843
 *  \sa SDL_HapticPause
slouken@3407
   844
 *  \sa SDL_HapticStopAll
slouken@2713
   845
 */
slouken@2713
   846
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index);
slouken@2713
   847
slouken@2713
   848
/**
slouken@3407
   849
 *  \brief Checks if the haptic device at index has been opened.
slouken@7191
   850
 *
slouken@3407
   851
 *  \param device_index Index to check to see if it has been opened.
slouken@3407
   852
 *  \return 1 if it has been opened or 0 if it hasn't.
slouken@7191
   853
 *
slouken@3407
   854
 *  \sa SDL_HapticOpen
slouken@3407
   855
 *  \sa SDL_HapticIndex
slouken@2713
   856
 */
slouken@2713
   857
extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index);
slouken@2713
   858
slouken@2713
   859
/**
slouken@3407
   860
 *  \brief Gets the index of a haptic device.
slouken@7191
   861
 *
slouken@3407
   862
 *  \param haptic Haptic device to get the index of.
slouken@3407
   863
 *  \return The index of the haptic device or -1 on error.
slouken@7191
   864
 *
slouken@3407
   865
 *  \sa SDL_HapticOpen
slouken@3407
   866
 *  \sa SDL_HapticOpened
slouken@2713
   867
 */
slouken@2713
   868
extern DECLSPEC int SDLCALL SDL_HapticIndex(SDL_Haptic * haptic);
slouken@2713
   869
slouken@2713
   870
/**
slouken@3407
   871
 *  \brief Gets whether or not the current mouse has haptic capabilities.
slouken@7191
   872
 *
slouken@3407
   873
 *  \return SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
slouken@7191
   874
 *
slouken@3407
   875
 *  \sa SDL_HapticOpenFromMouse
slouken@2713
   876
 */
slouken@2713
   877
extern DECLSPEC int SDLCALL SDL_MouseIsHaptic(void);
slouken@2713
   878
slouken@2713
   879
/**
slouken@3407
   880
 *  \brief Tries to open a haptic device from the current mouse.
slouken@7191
   881
 *
slouken@3407
   882
 *  \return The haptic device identifier or NULL on error.
slouken@7191
   883
 *
slouken@3407
   884
 *  \sa SDL_MouseIsHaptic
slouken@3407
   885
 *  \sa SDL_HapticOpen
slouken@2713
   886
 */
slouken@2713
   887
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(void);
slouken@2713
   888
slouken@2713
   889
/**
slouken@3407
   890
 *  \brief Checks to see if a joystick has haptic features.
slouken@7191
   891
 *
slouken@3407
   892
 *  \param joystick Joystick to test for haptic capabilities.
slouken@3407
   893
 *  \return 1 if the joystick is haptic, 0 if it isn't
slouken@3407
   894
 *          or -1 if an error ocurred.
slouken@7191
   895
 *
slouken@3407
   896
 *  \sa SDL_HapticOpenFromJoystick
slouken@2713
   897
 */
slouken@2713
   898
extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(SDL_Joystick * joystick);
slouken@2713
   899
slouken@2713
   900
/**
slouken@3407
   901
 *  \brief Opens a Haptic device for usage from a Joystick device.
slouken@7191
   902
 *
slouken@7191
   903
 *  You must still close the haptic device seperately.  It will not be closed
slouken@3407
   904
 *  with the joystick.
slouken@7191
   905
 *
slouken@3407
   906
 *  When opening from a joystick you should first close the haptic device before
slouken@2713
   907
 *  closing the joystick device.  If not, on some implementations the haptic
slouken@2713
   908
 *  device will also get unallocated and you'll be unable to use force feedback
slouken@2713
   909
 *  on that device.
slouken@7191
   910
 *
slouken@3407
   911
 *  \param joystick Joystick to create a haptic device from.
slouken@3407
   912
 *  \return A valid haptic device identifier on success or NULL on error.
slouken@7191
   913
 *
slouken@3407
   914
 *  \sa SDL_HapticOpen
slouken@3407
   915
 *  \sa SDL_HapticClose
slouken@2713
   916
 */
slouken@2713
   917
extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick *
slouken@2713
   918
                                                               joystick);
slouken@2713
   919
slouken@2713
   920
/**
slouken@3407
   921
 *  \brief Closes a Haptic device previously opened with SDL_HapticOpen().
slouken@7191
   922
 *
slouken@3407
   923
 *  \param haptic Haptic device to close.
slouken@2713
   924
 */
slouken@2713
   925
extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic);
slouken@2713
   926
slouken@2713
   927
/**
slouken@3407
   928
 *  \brief Returns the number of effects a haptic device can store.
slouken@7191
   929
 *
slouken@3407
   930
 *  On some platforms this isn't fully supported, and therefore is an
philipp@7120
   931
 *  approximation.  Always check to see if your created effect was actually
slouken@3407
   932
 *  created and do not rely solely on SDL_HapticNumEffects().
slouken@7191
   933
 *
slouken@3407
   934
 *  \param haptic The haptic device to query effect max.
slouken@3407
   935
 *  \return The number of effects the haptic device can store or
slouken@3407
   936
 *          -1 on error.
slouken@7191
   937
 *
slouken@3407
   938
 *  \sa SDL_HapticNumEffectsPlaying
slouken@3407
   939
 *  \sa SDL_HapticQuery
slouken@2713
   940
 */
slouken@2713
   941
extern DECLSPEC int SDLCALL SDL_HapticNumEffects(SDL_Haptic * haptic);
slouken@2713
   942
slouken@2713
   943
/**
slouken@7191
   944
 *  \brief Returns the number of effects a haptic device can play at the same
slouken@3407
   945
 *         time.
slouken@7191
   946
 *
slouken@7191
   947
 *  This is not supported on all platforms, but will always return a value.
philipp@7120
   948
 *  Added here for the sake of completeness.
slouken@7191
   949
 *
slouken@3407
   950
 *  \param haptic The haptic device to query maximum playing effects.
slouken@3407
   951
 *  \return The number of effects the haptic device can play at the same time
slouken@3407
   952
 *          or -1 on error.
slouken@2713
   953
 *
slouken@3407
   954
 *  \sa SDL_HapticNumEffects
slouken@3407
   955
 *  \sa SDL_HapticQuery
slouken@2713
   956
 */
slouken@2713
   957
extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic);
slouken@2713
   958
slouken@2713
   959
/**
slouken@3407
   960
 *  \brief Gets the haptic devices supported features in bitwise matter.
slouken@7191
   961
 *
slouken@7191
   962
 *  Example:
slouken@3407
   963
 *  \code
icculus@7620
   964
 *  if (SDL_HapticQuery(haptic) & SDL_HAPTIC_CONSTANT) {
slouken@3407
   965
 *      printf("We have constant haptic effect!");
slouken@3407
   966
 *  }
slouken@3407
   967
 *  \endcode
slouken@7191
   968
 *
slouken@3407
   969
 *  \param haptic The haptic device to query.
slouken@3407
   970
 *  \return Haptic features in bitwise manner (OR'd).
slouken@7191
   971
 *
slouken@3407
   972
 *  \sa SDL_HapticNumEffects
slouken@3407
   973
 *  \sa SDL_HapticEffectSupported
slouken@2713
   974
 */
slouken@2713
   975
extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(SDL_Haptic * haptic);
slouken@2713
   976
slouken@2713
   977
slouken@2713
   978
/**
slouken@3407
   979
 *  \brief Gets the number of haptic axes the device has.
slouken@7191
   980
 *
slouken@3407
   981
 *  \sa SDL_HapticDirection
slouken@2713
   982
 */
slouken@2713
   983
extern DECLSPEC int SDLCALL SDL_HapticNumAxes(SDL_Haptic * haptic);
slouken@2713
   984
slouken@2713
   985
/**
slouken@3407
   986
 *  \brief Checks to see if effect is supported by haptic.
slouken@7191
   987
 *
slouken@3407
   988
 *  \param haptic Haptic device to check on.
slouken@3407
   989
 *  \param effect Effect to check to see if it is supported.
slouken@5360
   990
 *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
slouken@7191
   991
 *
slouken@3407
   992
 *  \sa SDL_HapticQuery
slouken@3407
   993
 *  \sa SDL_HapticNewEffect
slouken@2713
   994
 */
slouken@2713
   995
extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic,
slouken@2713
   996
                                                      SDL_HapticEffect *
slouken@2713
   997
                                                      effect);
slouken@2713
   998
slouken@2713
   999
/**
slouken@3407
  1000
 *  \brief Creates a new haptic effect on the device.
slouken@7191
  1001
 *
slouken@3407
  1002
 *  \param haptic Haptic device to create the effect on.
slouken@3407
  1003
 *  \param effect Properties of the effect to create.
slouken@3407
  1004
 *  \return The id of the effect on success or -1 on error.
slouken@7191
  1005
 *
slouken@3407
  1006
 *  \sa SDL_HapticUpdateEffect
slouken@3407
  1007
 *  \sa SDL_HapticRunEffect
slouken@3407
  1008
 *  \sa SDL_HapticDestroyEffect
slouken@2713
  1009
 */
slouken@2713
  1010
extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic,
slouken@2713
  1011
                                                SDL_HapticEffect * effect);
slouken@2713
  1012
slouken@2713
  1013
/**
slouken@3407
  1014
 *  \brief Updates the properties of an effect.
slouken@7191
  1015
 *
slouken@3407
  1016
 *  Can be used dynamically, although behaviour when dynamically changing
slouken@3407
  1017
 *  direction may be strange.  Specifically the effect may reupload itself
slouken@3407
  1018
 *  and start playing from the start.  You cannot change the type either when
slouken@3407
  1019
 *  running SDL_HapticUpdateEffect().
slouken@7191
  1020
 *
slouken@3407
  1021
 *  \param haptic Haptic device that has the effect.
slouken@3407
  1022
 *  \param effect Effect to update.
slouken@3407
  1023
 *  \param data New effect properties to use.
icculus@7537
  1024
 *  \return 0 on success or -1 on error.
slouken@7191
  1025
 *
slouken@3407
  1026
 *  \sa SDL_HapticNewEffect
slouken@3407
  1027
 *  \sa SDL_HapticRunEffect
slouken@3407
  1028
 *  \sa SDL_HapticDestroyEffect
slouken@2713
  1029
 */
slouken@2713
  1030
extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic,
slouken@2713
  1031
                                                   int effect,
slouken@2713
  1032
                                                   SDL_HapticEffect * data);
slouken@2713
  1033
slouken@2713
  1034
/**
philipp@7125
  1035
 *  \brief Runs the haptic effect on its associated haptic device.
slouken@7191
  1036
 *
slouken@3407
  1037
 *  If iterations are ::SDL_HAPTIC_INFINITY, it'll run the effect over and over
slouken@2713
  1038
 *  repeating the envelope (attack and fade) every time.  If you only want the
slouken@3407
  1039
 *  effect to last forever, set ::SDL_HAPTIC_INFINITY in the effect's length
slouken@2713
  1040
 *  parameter.
slouken@7191
  1041
 *
slouken@3407
  1042
 *  \param haptic Haptic device to run the effect on.
slouken@3407
  1043
 *  \param effect Identifier of the haptic effect to run.
slouken@3407
  1044
 *  \param iterations Number of iterations to run the effect. Use
slouken@3407
  1045
 *         ::SDL_HAPTIC_INFINITY for infinity.
slouken@3407
  1046
 *  \return 0 on success or -1 on error.
slouken@7191
  1047
 *
slouken@3407
  1048
 *  \sa SDL_HapticStopEffect
slouken@3407
  1049
 *  \sa SDL_HapticDestroyEffect
slouken@3407
  1050
 *  \sa SDL_HapticGetEffectStatus
slouken@2713
  1051
 */
slouken@2713
  1052
extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic,
slouken@2713
  1053
                                                int effect,
slouken@2713
  1054
                                                Uint32 iterations);
slouken@2713
  1055
slouken@2713
  1056
/**
philipp@7125
  1057
 *  \brief Stops the haptic effect on its associated haptic device.
slouken@7191
  1058
 *
slouken@3407
  1059
 *  \param haptic Haptic device to stop the effect on.
slouken@3407
  1060
 *  \param effect Identifier of the effect to stop.
slouken@3407
  1061
 *  \return 0 on success or -1 on error.
slouken@7191
  1062
 *
slouken@3407
  1063
 *  \sa SDL_HapticRunEffect
slouken@3407
  1064
 *  \sa SDL_HapticDestroyEffect
slouken@2713
  1065
 */
slouken@2713
  1066
extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic,
slouken@2713
  1067
                                                 int effect);
slouken@2713
  1068
slouken@2713
  1069
/**
slouken@3407
  1070
 *  \brief Destroys a haptic effect on the device.
slouken@7191
  1071
 *
slouken@7191
  1072
 *  This will stop the effect if it's running.  Effects are automatically
slouken@3407
  1073
 *  destroyed when the device is closed.
slouken@7191
  1074
 *
slouken@3407
  1075
 *  \param haptic Device to destroy the effect on.
slouken@3407
  1076
 *  \param effect Identifier of the effect to destroy.
slouken@7191
  1077
 *
slouken@3407
  1078
 *  \sa SDL_HapticNewEffect
slouken@2713
  1079
 */
slouken@2713
  1080
extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic,
slouken@2713
  1081
                                                     int effect);
slouken@2713
  1082
slouken@2713
  1083
/**
slouken@3407
  1084
 *  \brief Gets the status of the current effect on the haptic device.
slouken@7191
  1085
 *
slouken@3407
  1086
 *  Device must support the ::SDL_HAPTIC_STATUS feature.
slouken@7191
  1087
 *
slouken@3407
  1088
 *  \param haptic Haptic device to query the effect status on.
philipp@7125
  1089
 *  \param effect Identifier of the effect to query its status.
philipp@7278
  1090
 *  \return 0 if it isn't playing, 1 if it is playing or -1 on error.
slouken@7191
  1091
 *
slouken@3407
  1092
 *  \sa SDL_HapticRunEffect
slouken@3407
  1093
 *  \sa SDL_HapticStopEffect
slouken@2713
  1094
 */
slouken@2713
  1095
extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic,
slouken@2713
  1096
                                                      int effect);
slouken@2713
  1097
slouken@2713
  1098
/**
slouken@3407
  1099
 *  \brief Sets the global gain of the device.
slouken@7191
  1100
 *
slouken@3407
  1101
 *  Device must support the ::SDL_HAPTIC_GAIN feature.
slouken@7191
  1102
 *
philipp@7120
  1103
 *  The user may specify the maximum gain by setting the environment variable
philipp@7278
  1104
 *  SDL_HAPTIC_GAIN_MAX which should be between 0 and 100.  All calls to
philipp@7278
  1105
 *  SDL_HapticSetGain() will scale linearly using SDL_HAPTIC_GAIN_MAX as the
slouken@2713
  1106
 *  maximum.
slouken@7191
  1107
 *
slouken@3407
  1108
 *  \param haptic Haptic device to set the gain on.
slouken@3407
  1109
 *  \param gain Value to set the gain to, should be between 0 and 100.
slouken@3407
  1110
 *  \return 0 on success or -1 on error.
slouken@7191
  1111
 *
slouken@3407
  1112
 *  \sa SDL_HapticQuery
slouken@2713
  1113
 */
slouken@2713
  1114
extern DECLSPEC int SDLCALL SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
slouken@2713
  1115
slouken@2713
  1116
/**
slouken@3407
  1117
 *  \brief Sets the global autocenter of the device.
slouken@7191
  1118
 *
slouken@7191
  1119
 *  Autocenter should be between 0 and 100.  Setting it to 0 will disable
slouken@3407
  1120
 *  autocentering.
slouken@2713
  1121
 *
slouken@3407
  1122
 *  Device must support the ::SDL_HAPTIC_AUTOCENTER feature.
slouken@2713
  1123
 *
slouken@3407
  1124
 *  \param haptic Haptic device to set autocentering on.
slouken@3407
  1125
 *  \param autocenter Value to set autocenter to, 0 disables autocentering.
slouken@3407
  1126
 *  \return 0 on success or -1 on error.
slouken@7191
  1127
 *
slouken@3407
  1128
 *  \sa SDL_HapticQuery
slouken@2713
  1129
 */
slouken@2713
  1130
extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic,
slouken@2713
  1131
                                                    int autocenter);
slouken@2713
  1132
slouken@2713
  1133
/**
slouken@3407
  1134
 *  \brief Pauses a haptic device.
slouken@7191
  1135
 *
slouken@7191
  1136
 *  Device must support the ::SDL_HAPTIC_PAUSE feature.  Call
slouken@3407
  1137
 *  SDL_HapticUnpause() to resume playback.
slouken@7191
  1138
 *
slouken@3407
  1139
 *  Do not modify the effects nor add new ones while the device is paused.
slouken@2713
  1140
 *  That can cause all sorts of weird errors.
slouken@7191
  1141
 *
slouken@3407
  1142
 *  \param haptic Haptic device to pause.
slouken@3407
  1143
 *  \return 0 on success or -1 on error.
slouken@7191
  1144
 *
slouken@3407
  1145
 *  \sa SDL_HapticUnpause
slouken@2713
  1146
 */
slouken@2713
  1147
extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic);
slouken@2713
  1148
slouken@2713
  1149
/**
slouken@3407
  1150
 *  \brief Unpauses a haptic device.
slouken@7191
  1151
 *
slouken@3407
  1152
 *  Call to unpause after SDL_HapticPause().
slouken@7191
  1153
 *
philipp@8771
  1154
 *  \param haptic Haptic device to unpause.
slouken@3407
  1155
 *  \return 0 on success or -1 on error.
slouken@7191
  1156
 *
slouken@3407
  1157
 *  \sa SDL_HapticPause
slouken@2713
  1158
 */
slouken@2713
  1159
extern DECLSPEC int SDLCALL SDL_HapticUnpause(SDL_Haptic * haptic);
slouken@2713
  1160
slouken@2713
  1161
/**
slouken@3407
  1162
 *  \brief Stops all the currently playing effects on a haptic device.
slouken@7191
  1163
 *
slouken@3407
  1164
 *  \param haptic Haptic device to stop.
slouken@3407
  1165
 *  \return 0 on success or -1 on error.
slouken@2713
  1166
 */
slouken@2713
  1167
extern DECLSPEC int SDLCALL SDL_HapticStopAll(SDL_Haptic * haptic);
slouken@2713
  1168
slouken@5360
  1169
/**
icculus@7620
  1170
 *  \brief Checks to see if rumble is supported on a haptic device.
slouken@5360
  1171
 *
slouken@5360
  1172
 *  \param haptic Haptic device to check to see if it supports rumble.
slouken@5360
  1173
 *  \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
slouken@5360
  1174
 *
slouken@5360
  1175
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1176
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1177
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1178
 */
slouken@5360
  1179
extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic);
slouken@5360
  1180
slouken@5360
  1181
/**
slouken@5360
  1182
 *  \brief Initializes the haptic device for simple rumble playback.
slouken@5360
  1183
 *
slouken@5360
  1184
 *  \param haptic Haptic device to initialize for simple rumble playback.
slouken@5360
  1185
 *  \return 0 on success or -1 on error.
slouken@5360
  1186
 *
slouken@5360
  1187
 *  \sa SDL_HapticOpen
slouken@5360
  1188
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1189
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1190
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1191
 */
slouken@5360
  1192
extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(SDL_Haptic * haptic);
slouken@5360
  1193
slouken@5360
  1194
/**
slouken@5360
  1195
 *  \brief Runs simple rumble on a haptic device
slouken@5360
  1196
 *
slouken@5360
  1197
 *  \param haptic Haptic device to play rumble effect on.
slouken@5360
  1198
 *  \param strength Strength of the rumble to play as a 0-1 float value.
philipp@7120
  1199
 *  \param length Length of the rumble to play in milliseconds.
slouken@5360
  1200
 *  \return 0 on success or -1 on error.
slouken@5360
  1201
 *
slouken@5360
  1202
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1203
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1204
 *  \sa SDL_HapticRumbleStop
slouken@5360
  1205
 */
slouken@5360
  1206
extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float strength, Uint32 length );
slouken@5360
  1207
slouken@5360
  1208
/**
slouken@5360
  1209
 *  \brief Stops the simple rumble on a haptic device.
slouken@5360
  1210
 *
slouken@5360
  1211
 *  \param haptic Haptic to stop the rumble on.
slouken@5360
  1212
 *  \return 0 on success or -1 on error.
slouken@5360
  1213
 *
slouken@5360
  1214
 *  \sa SDL_HapticRumbleSupported
slouken@5360
  1215
 *  \sa SDL_HapticRumbleInit
slouken@5360
  1216
 *  \sa SDL_HapticRumblePlay
slouken@5360
  1217
 */
slouken@5360
  1218
extern DECLSPEC int SDLCALL SDL_HapticRumbleStop(SDL_Haptic * haptic);
slouken@5360
  1219
slouken@2713
  1220
/* Ends C function definitions when using C++ */
slouken@2713
  1221
#ifdef __cplusplus
slouken@2713
  1222
}
slouken@2713
  1223
#endif
slouken@2713
  1224
#include "close_code.h"
slouken@2713
  1225
slouken@2713
  1226
#endif /* _SDL_haptic_h */
slouken@2713
  1227
slouken@2713
  1228
/* vi: set ts=4 sw=4 expandtab: */