Miguel Ruiz / SDL_lib

SDL standard library

Dependents:   H261_encoder

SDL_haptic.h@0:dda4f4550403, 2016-09-07 (annotated)

Committer:
miruga27
Date:
Wed Sep 07 18:46:53 2016 +0000
Revision:
0:dda4f4550403
7/09/2016;

Who changed what in which revision?

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