Miguel Ruiz / SDL_lib2

SDL Library

Dependents:   H261_decoder

SDL_haptic.h@0:7fb6877b5d7c, 2016-09-22 (annotated)

Committer:
miruga27
Date:
Thu Sep 22 00:03:09 2016 +0000
Revision:
0:7fb6877b5d7c
SDL

Who changed what in which revision?

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