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