Mercurial > sdl-ios-xcode

comparison include/SDL_haptic.h @ 2497:0893fbf73b3d gsoc2008_force_feedback

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Renamed SDL_HapticQueryEffects to SDL_HapticQuery. Added doxygen to SDL_Haptic.h.
author Edgar Simo <bobbens@gmail.com>
date Sun, 06 Jul 2008 16:53:32 +0000
parents 66c02abeef0e
children ab567bd667bf
comparison
equal deleted inserted replaced
2496:8f840a6cdf01 2497:0893fbf73b3d
18 18
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** 23 /** \file SDL_haptic.h */
24 * \file SDL_haptic.h 24 /**
25 * 25 * \mainpage SDL_haptic
26 * Include file for SDL haptic subsystem 26 *
27 * The SDL Haptic subsystem allows you to control haptic (force feedback)
28 * devices.
29 *
30 * The basic usage is as follows:
31 * - Initialize the Subsystem (SDL_INIT_HAPTIC).
32 * - Open a Haptic Device.
33 * - SDL_HapticOpen(...) to open from index.
34 * - SDL_HapticOpenFromJoystick(...) to open from an existing joystick.
35 * - Create an effect (SDL_HapticEffect).
36 * - Upload the effect with SDL_HapticNewEffect(...).
37 * - Run the effect with SDL_HapticRunEffect(...).
38 * - (optional) Free the effect with SDL_HapticDestroyEffect(...).
39 * - Close the haptic device with SDL_HapticClose(...).
40 *
41 *
42 * Example:
43 *
44 * \code
45 * int test_haptic( SDL_Joystick * joystick ) {
46 * SDL_Haptic *haptic;
47 * SDL_HapticEffect effect;
48 * int effect_id;
49 *
50 * // Open the device
51 * haptic = SDL_HapticOpenFromJoystick( joystick );
52 * if (haptic == NULL) return -1; // Most likely joystick isn't haptic
53 *
54 * // See if it can do sine waves
55 * if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) {
56 * SDL_HapticClose(haptic); // No sine effect
57 * return -1;
58 * }
59 *
60 * // Create the effect
61 * memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
62 * effect.type = SDL_HAPTIC_SINE;
63 * effect.periodic.period = 1000; // 1000 ms
64 * effect.periodic.magnitude = 20000; // 20000/32767 strength
65 * effect.periodic.length = 5000; // 5 seconds long
66 * effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
67 * effect.periodic.fade_length = 1000; // Takes 1 second to fade away
68 *
69 * // Upload the effect
70 * effect_id = SDL_HapticNewEffect( haptic, &effect );
71 *
72 * // Test the effect
73 * SDL_HapticRunEffect( haptic, effect_id );
74 * SDL_Delay( 5000); // Wait for the effect to finish
75 *
76 * // We destroy the effect, although closing the device also does this
77 * SDL_HapticDestroyEffect( haptic, effect_id );
78 *
79 * // Close the device
80 * SDL_HapticClose(haptic);
81 *
82 * return 0; // Success
83 * }
84 * \endcode
85 *
86 * \author Edgar Simo Serra
27 */ 87 */
28 88
29 #ifndef _SDL_haptic_h 89 #ifndef _SDL_haptic_h
30 #define _SDL_haptic_h 90 #define _SDL_haptic_h
31 91
37 /* Set up for C function definitions, even when using C++ */ 97 /* Set up for C function definitions, even when using C++ */
38 #ifdef __cplusplus 98 #ifdef __cplusplus
39 /* *INDENT-OFF* */ 99 /* *INDENT-OFF* */
40 extern "C" { 100 extern "C" {
41 /* *INDENT-ON* */ 101 /* *INDENT-ON* */
42 #endif 102 #endif /* __cpluspuls */
43 103
44 /* The haptic structure used to identify an SDL haptic */ 104 /**
105 * \struct SDL_Haptic
106 *
107 * \brief The haptic structure used to identify an SDL haptic.
108 *
109 * \sa SDL_HapticOpen
110 * \sa SDL_HapticOpenFromJoystick
111 * \sa SDL_HapticClose
112 */
45 struct _SDL_Haptic; 113 struct _SDL_Haptic;
46 typedef struct _SDL_Haptic SDL_Haptic; 114 typedef struct _SDL_Haptic SDL_Haptic;
47 115
48 116
49 /* 117 /*
50 * Different haptic features a device can have. 118 * Different haptic features a device can have.
51 */ 119 */
120 /**
121 * \def SDL_HAPTIC_CONSTANT
122 *
123 * \brief Constant haptic effect.
124 *
125 * \sa SDL_HapticCondition
126 */
52 #define SDL_HAPTIC_CONSTANT (1<<0) /* Constant effect supported */ 127 #define SDL_HAPTIC_CONSTANT (1<<0) /* Constant effect supported */
128 /**
129 * \def SDL_HAPTIC_SINE
130 *
131 * \brief Periodic haptic effect that simulates sine waves.
132 *
133 * \sa SDL_HapticPeriodic
134 */
53 #define SDL_HAPTIC_SINE (1<<1) /* Sine wave effect supported */ 135 #define SDL_HAPTIC_SINE (1<<1) /* Sine wave effect supported */
136 /**
137 * \def SDL_HAPTIC_SQUARE
138 *
139 * \brief Periodic haptic effect that simulates square waves.
140 *
141 * \sa SDL_HapticPeriodic
142 */
54 #define SDL_HAPTIC_SQUARE (1<<2) /* Square wave effect supported */ 143 #define SDL_HAPTIC_SQUARE (1<<2) /* Square wave effect supported */
144 /**
145 * \def SDL_HAPTIC_TRIANGLE
146 *
147 * \brief Periodic haptic effect that simulates triangular waves.
148 *
149 * \sa SDL_HapticPeriodic
150 */
55 #define SDL_HAPTIC_TRIANGLE (1<<3) /* Triangle wave effect supported */ 151 #define SDL_HAPTIC_TRIANGLE (1<<3) /* Triangle wave effect supported */
152 /**
153 * \def SDL_HAPTIC_SAWTOOTHUP
154 *
155 * \brief Periodic haptic effect that simulates saw tooth up waves.
156 *
157 * \sa SDL_HapticPeriodic
158 */
56 #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */ 159 #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
160 /**
161 * \def SDL_HAPTIC_SAWTOOTHDOWN
162 *
163 * \brief Periodic haptic effect that simulates saw tooth down waves.
164 *
165 * \sa SDL_HapticPeriodic
166 */
57 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */ 167 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
168 /**
169 * \def SDL_HAPTIC_RAMP
170 *
171 * \brief Ramp haptic effect.
172 *
173 * \sa SDL_HapticRamp
174 */
58 #define SDL_HAPTIC_RAMP (1<<6) /* Ramp effect supported */ 175 #define SDL_HAPTIC_RAMP (1<<6) /* Ramp effect supported */
176 /**
177 * \def SDL_HAPTIC_SPRING
178 *
179 * \brief Condition haptic effect that simulates a spring. Effect is based on the
180 * axes position.
181 *
182 * \sa SDL_HapticCondition
183 */
59 #define SDL_HAPTIC_SPRING (1<<7) /* Spring effect supported - uses axes position */ 184 #define SDL_HAPTIC_SPRING (1<<7) /* Spring effect supported - uses axes position */
185 /**
186 * \def SDL_HAPTIC_DAMPER
187 *
188 * \brief Condition haptic effect that simulates dampening. Effect is based on the
189 * axes velocity.
190 *
191 * \sa SDL_HapticCondition
192 */
60 #define SDL_HAPTIC_DAMPER (1<<8) /* Damper effect supported - uses axes velocity */ 193 #define SDL_HAPTIC_DAMPER (1<<8) /* Damper effect supported - uses axes velocity */
194 /**
195 * \def SDL_HAPTIC_INERTIA
196 *
197 * \brief Condition haptic effect that simulates inertia. Effect is based on the axes
198 * acceleration.
199 *
200 * \sa SDL_HapticCondition
201 */
61 #define SDL_HAPTIC_INERTIA (1<<9) /* Inertia effect supported - uses axes acceleration */ 202 #define SDL_HAPTIC_INERTIA (1<<9) /* Inertia effect supported - uses axes acceleration */
203 /**
204 * \def SDL_HAPTIC_FRICTION
205 *
206 * \brief Condition haptic effect that simulates friction. Effect is based on the axes
207 * movement.
208 *
209 * \sa SDL_HapticCondition
210 */
62 #define SDL_HAPTIC_FRICTION (1<<10) /* Friction effect supported - uses axes movement */ 211 #define SDL_HAPTIC_FRICTION (1<<10) /* Friction effect supported - uses axes movement */
212 /**
213 * \def SDL_HAPTIC_CUSTOM
214 *
215 * \brief User defined custom haptic effect. TODO.
216 */
63 #define SDL_HAPTIC_CUSTOM (1<<11) /* Custom effect is supported */ 217 #define SDL_HAPTIC_CUSTOM (1<<11) /* Custom effect is supported */
64 /* These last two are features the device has, not effects */ 218 /* These last two are features the device has, not effects */
219 /**
220 * \def SDL_HAPTIC_GAIN
221 *
222 * \brief Device supports setting the global gain.
223 *
224 * \sa SDL_HapticSetGain
225 */
65 #define SDL_HAPTIC_GAIN (1<<12) /* Device can set global gain */ 226 #define SDL_HAPTIC_GAIN (1<<12) /* Device can set global gain */
227 /**
228 * \def SDL_HAPTIC_AUTOCENTER
229 *
230 * \brief Device supports setting autocenter.
231 *
232 * \sa SDL_HapticSetAutocenter
233 */
66 #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */ 234 #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
235 /**
236 * \def SDL_HAPTIC_STATUS
237 *
238 * \brief Device can be queried for effect status.
239 *
240 * \sa SDL_HapticGetEffectStatus
241 */
67 #define SDL_HAPTIC_STATUS (1<<14) /* Device can be queried for effect status */ 242 #define SDL_HAPTIC_STATUS (1<<14) /* Device can be queried for effect status */
68 243
69 244
70 /* 245 /**
246 * \struct SDL_HapticConstant
247 *
248 * \brief A structure containing a template for a Constant effect.
249 *
250 * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect.
251 *
252 * \sa SDL_HAPTIC_CONSTANT
253 * \sa SDL_HapticEffect
254 */
255 typedef struct SDL_HapticConstant {
256 /* Header */
257 Uint16 type; /**< SDL_HAPTIC_CONSTANT */
258 Uint16 direction;
259
260 /* Replay */
261 Uint16 length; /**< Duration of the effect. */
262 Uint16 delay; /**< Delay before starting the effect. */
263
264 /* Trigger */
265 Uint16 button; /**< Button that triggers the effect. */
266 Uint16 interval; /**< How soon it can be triggered again after button. */
267
268 /* Constant */
269 Sint16 level; /**< Strength of the constant effect. */
270
271 /* Envelope */
272 Uint16 attack_length; /**< Duration of the attack. */
273 Uint16 attack_level; /**< Level at the start of the attack. */
274 Uint16 fade_length; /**< Duration of the fade. */
275 Uint16 fade_level; /**< Level at the end of the fade. */
276 } SDL_HapticConstant;
277 /**
278 * \struct SDL_HapticPeriodic
279 *
280 * \brief A structure containing a template for a Periodic effect.
281 *
282 * The struct handles the following effects:
283 * - SDL_HAPTIC_SINE
284 * - SDL_HAPTIC_SQUARE
285 * - SDL_HAPTIC_TRIANGLE
286 * - SDL_HAPTIC_SAWTOOTHUP
287 * - SDL_HAPTIC_SAWTOOTHDOWN
288 *
289 * \sa SDL_HAPTIC_SINE
290 * \sa SDL_HAPTIC_SQUARE
291 * \sa SDL_HAPTIC_TRIANGLE
292 * \sa SDL_HAPTIC_SAWTOOTHUP
293 * \sa SDL_HAPTIC_SAWTOOTHDOWN
294 * \sa SDL_HapticEffect
295 */
296 typedef struct SDL_HapticPeriodic {
297 /* Header */
298 Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
299 Uint16 direction;
300
301 /* Replay */
302 Uint16 length; /**< Duration of the effect. */
303 Uint16 delay; /**< Delay before starting the effect. */
304
305 /* Trigger */
306 Uint16 button; /**< Button that triggers the effect. */
307 Uint16 interval; /**< How soon it can be triggered again after button. */
308
309 /* Periodic */
310 Uint16 period; /**< Period of the wave. */
311 Sint16 magnitude; /**< Peak value. */
312 Sint16 offset; /**< Mean value of the wave. */
313 Uint16 phase; /**< Horizontal shift. */
314
315 /* Envelope */
316 Uint16 attack_length; /**< Duration of the attack. */
317 Uint16 attack_level; /**< Level at the start of the attack. */
318 Uint16 fade_length; /**< Duration of the fade. */
319 Uint16 fade_level; /**< Level at the end of the fade. */
320 } SDL_HapticPeriodic;
321 /**
322 * \struct SDL_HapticCondition
323 *
324 * \brief A structure containing a template for a Condition effect.
325 *
326 * The struct handles the following effects:
327 * - SDL_HAPTIC_SPRING
328 * - SDL_HAPTIC_DAMPER
329 * - SDL_HAPTIC_INERTIA
330 * - SDL_HAPTIC_FRICTION
331 *
332 * \sa SDL_HAPTIC_SPRING
333 * \sa SDL_HAPTIC_DAMPER
334 * \sa SDL_HAPTIC_INERTIA
335 * \sa SDL_HAPTIC_FRICTION
336 * \sa SDL_HapticEffect
337 */
338 typedef struct SDL_HapticCondition {
339 /* Header */
340 Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
341 Uint16 direction;
342
343 /* Replay */
344 Uint16 length; /**< Duration of the effect. */
345 Uint16 delay; /**< Delay before starting the effect. */
346
347 /* Trigger */
348 Uint16 button; /**< Button that triggers the effect. */
349 Uint16 interval; /**< How soon it can be triggered again after button. */
350
351 /* Condition */
352 Uint16 right_sat; /**< Level when joystick is to the right. */
353 Uint16 left_sat; /**< Level when joystick is to the left. */
354 Sint16 right_coeff; /**< How fast to increase the force towards the right. */
355 Sint16 left_coeff; /**< How fast to increase the force towards the left. */
356 Uint16 deadband; /**< Size of the dead zone. */
357 Sint16 center; /**< Position of the dead zone. */
358 } SDL_HapticCondition;
359 /**
360 * \struct SDL_HapticRamp
361 *
362 * \brief A structure containing a template for a Ramp effect.
363 *
364 * This struct is exclusively for the SDL_HAPTIC_RAMP effect.
365 *
366 * \sa SDL_HAPTIC_RAMP
367 * \sa SDL_HapticEffect
368 */
369 typedef struct SDL_HapticRamp {
370 /* Header */
371 Uint16 type; /**< SDL_HAPTIC_RAMP */
372 Uint16 direction;
373
374 /* Replay */
375 Uint16 length; /**< Duration of the effect. */
376 Uint16 delay; /**< Delay before starting the effect. */
377
378 /* Trigger */
379 Uint16 button; /**< Button that triggers the effect. */
380 Uint16 interval; /**< How soon it can be triggered again after button. */
381
382 /* Ramp */
383 Sint16 start; /**< Beginning strength level. */
384 Sint16 end; /**< Ending strength level. */
385
386 /* Envelope */
387 Uint16 attack_length; /**< Duration of the attack. */
388 Uint16 attack_level; /**< Level at the start of the attack. */
389 Uint16 fade_length; /**< Duration of the fade. */
390 Uint16 fade_level; /**< Level at the end of the fade. */
391 } SDL_HapticRamp;
392 /*
393 * \union SDL_HapticEffect
394 *
395 * \brief The generic template for any haptic effect.
396 *
71 * All values max at 32767 (0x7fff). Signed values also can be negative. 397 * All values max at 32767 (0x7fff). Signed values also can be negative.
72 * Time values unless specified otherwise are in milliseconds. 398 * Time values unless specified otherwise are in milliseconds.
73 * 399 *
74 * Common parts: 400 * Common parts:
75 * 401 *
84 * Envelope: 410 * Envelope:
85 * Uint16 attack_length; Duration of the attack. 411 * Uint16 attack_length; Duration of the attack.
86 * Uint16 attack_level; Level at the start of the attack. 412 * Uint16 attack_level; Level at the start of the attack.
87 * Uint16 fade_length; Duration of the fade out. 413 * Uint16 fade_length; Duration of the fade out.
88 * Uint16 fade_level; Level at the end of the fade. 414 * Uint16 fade_level; Level at the end of the fade.
89 */ 415 *
90 typedef struct SDL_HapticConstant { 416 * \sa SDL_HapticConstant
91 /* Header */ 417 * \sa SDL_HapticPeriodic
92 Uint16 type; /* SDL_HAPTIC_CONSTANT */ 418 * \sa SDL_HapticCondition
93 Uint16 direction; 419 * \sa SDL_HaptiRamp
94 420 */
95 /* Replay */
96 Uint16 length;
97 Uint16 delay;
98
99 /* Trigger */
100 Uint16 button;
101 Uint16 interval;
102
103 /* Constant */
104 Sint16 level; /* Strength of the constant effect. */
105
106 /* Envelope */
107 Uint16 attack_length;
108 Uint16 attack_level;
109 Uint16 fade_length;
110 Uint16 fade_level;
111 } SDL_HapticConstant;
112 typedef struct SDL_HapticPeriodic {
113 /* Header */
114 Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
115 Uint16 direction;
116
117 /* Replay */
118 Uint16 length;
119 Uint16 delay;
120
121 /* Trigger */
122 Uint16 button;
123 Uint16 interval;
124
125 /* Periodic */
126 Uint16 period; /* Period of the wave */
127 Sint16 magnitude; /* Peak value */
128 Sint16 offset; /* Mean value of the wave */
129 Uint16 phase; /* Horizontal shift */
130
131 /* Envelope */
132 Uint16 attack_length;
133 Uint16 attack_level;
134 Uint16 fade_length;
135 Uint16 fade_level;
136 } SDL_HapticPeriodic;
137 typedef struct SDL_HapticCondition {
138 /* Header */
139 Uint16 type; /* SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
140 Uint16 direction;
141
142 /* Replay */
143 Uint16 length;
144 Uint16 delay;
145
146 /* Trigger */
147 Uint16 button;
148 Uint16 interval;
149
150 /* Condition */
151 Uint16 right_sat; /* Level when joystick is to the right. */
152 Uint16 left_sat; /* Level when joystick is to the left */
153 Sint16 right_coeff; /* How fast to increase the force towards the right */
154 Sint16 left_coeff; /* How fast to increase the force towards the left */
155 Uint16 deadband; /* Size of the dead zone */
156 Sint16 center; /* Position of the dead zone */
157 } SDL_HapticCondition;
158 typedef struct SDL_HapticRamp {
159 /* Header */
160 Uint16 type; /* SDL_HAPTIC_RAMP */
161 Uint16 direction;
162
163 /* Replay */
164 Uint16 length;
165 Uint16 delay;
166
167 /* Trigger */
168 Uint16 button;
169 Uint16 interval;
170
171 /* Ramp */
172 Sint16 start; /* Beginning strength level. */
173 Sint16 end; /* Ending strength level. */
174
175 /* Envelope */
176 Uint16 attack_length;
177 Uint16 attack_level;
178 Uint16 fade_length;
179 Uint16 fade_level;
180 } SDL_HapticRamp;
181
182 typedef union SDL_HapticEffect { 421 typedef union SDL_HapticEffect {
183 /* Common for all force feedback effects */ 422 /* Common for all force feedback effects */
184 Uint16 type; /* Effect type */ 423 Uint16 type; /**< Effect type */
185 SDL_HapticConstant constant; /* Constant effect */ 424 SDL_HapticConstant constant; /**< Constant effect */
186 SDL_HapticPeriodic periodic; /* Periodic effect */ 425 SDL_HapticPeriodic periodic; /**< Periodic effect */
187 SDL_HapticCondition condition; /* Condition effect */ 426 SDL_HapticCondition condition; /**< Condition effect */
188 SDL_HapticRamp ramp; /* Ramp effect */ 427 SDL_HapticRamp ramp; /**< Ramp effect */
189 } SDL_HapticEffect; 428 } SDL_HapticEffect;
190 429
191 430
192 /* Function prototypes */ 431 /* Function prototypes */
193 /* 432 /*
194 * Count the number of joysticks attached to the system 433 * \fn int SDL_NumHaptics(void)
434 *
435 * \brief Count the number of joysticks attached to the system.
436 *
437 * \return Number of haptic devices detected on the system.
195 */ 438 */
196 extern DECLSPEC int SDLCALL SDL_NumHaptics(void); 439 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
197 440
198 /* 441 /*
199 * Get the implementation dependent name of a Haptic device. 442 * \fn const char * SDL_HapticName(int device_index)
443 *
444 * \brief Get the implementation dependent name of a Haptic device.
200 * This can be called before any joysticks are opened. 445 * This can be called before any joysticks are opened.
201 * If no name can be found, this function returns NULL. 446 * If no name can be found, this function returns NULL.
447 *
448 * \param device_index Index of the device to get it's name.
449 * \return Name of the device or NULL on error.
450 *
451 * \sa SDL_NumHaptics
202 */ 452 */
203 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); 453 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
204 454
205 /* 455 /*
206 * Opens a Haptic device for usage - the index passed as an 456 * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
457 *
458 * \brief Opens a Haptic device for usage - the index passed as an
207 * argument refers to the N'th Haptic device on this system. 459 * argument refers to the N'th Haptic device on this system.
208 * 460 *
209 * This function returns a Haptic device identifier, or Null 461 * This function returns a Haptic device identifier, or Null
210 * if an error occurred. 462 * if an error occurred.
463 *
464 * \param device_index Index of the device to open.
465 * \return Device identifier or NULL on error.
466 *
467 * \sa SDL_HapticOpenFromJoystick
468 * \sa SDL_HapticClose
211 */ 469 */
212 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index); 470 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
213 471
214 /* 472 /*
215 * Checks to see if a joystick has haptic features. 473 * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke)
216 * 474 *
217 * Returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't 475 * \brief Checks to see if a joystick has haptic features.
218 * and -1 on error. 476 *
477 * \param joystick Joystick to test for haptic capabilities.
478 * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
479 * or -1 if an error ocurred.
480 *
481 * \sa SDL_HapticOpenFromJoystick
219 */ 482 */
220 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick); 483 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
221 484
222 /* 485 /*
223 * Opens a Haptic device for usage from a Joystick device. 486 * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
224 * 487 *
225 * Returns a valid pointer to a haptic device on success or NULL 488 * \brief Opens a Haptic device for usage from a Joystick device. Still has
226 * if an error occurred. 489 * to be closed seperately to the joystick.
490 *
491 * \param joystick Joystick to create a haptic device from.
492 * \return A valid haptic device identifier on success or NULL on error.
493 *
494 * \sa SDL_HapticOpen
495 * \sa SDL_HapticClose
227 */ 496 */
228 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick); 497 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
229 498
230 /* 499 /*
231 * Closes a Haptic device previously opened with SDL_HapticOpen. 500 * \fn void SDL_HapticClose(SDL_Haptic * haptic)
501 *
502 * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
503 *
504 * \param haptic Haptic device to close.
232 */ 505 */
233 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic); 506 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
234 507
235 /* 508 /*
236 * Returns the number of effects a haptic device can store. 509 * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
510 *
511 * \brief Returns the number of effects a haptic device can store.
512 *
513 * \param haptic The haptic device to query effect max.
514 * \return The number of effects the haptic device can store or
515 * -1 on error.
516 *
517 * \sa SDL_HapticQuery
237 */ 518 */
238 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic); 519 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
239 520
240 /* 521 /*
241 * Returns the supported effects. Individual effects can be queried by 522 * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
242 * bitwise operators. 523 *
243 * 524 * \brief Gets the haptic devices supported features in bitwise matter.
244 * Example: (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) 525 *
245 */ 526 * Example:
246 extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic); 527 * \code
247 528 * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
248 /* 529 * printf("We have constant haptic effect!");
249 * Checks to see if effect is supported by haptic. 530 * }
250 * 531 * \endcode
251 * Returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't and -1 532 *
252 * on error. 533 *
534 * \param haptic The haptic device to query.
535 * \return Haptic features in bitwise manner (OR'd).
536 *
537 * \sa SDL_HapticNumEffects
538 * \sa SDL_HapticEffectSupported
539 */
540 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
541
542 /*
543 * \fn int SDL_HapticEffectSupported
544 *
545 * \brief Checks to see if effect is supported by haptic.
546 *
547 * \param haptic Haptic device to check on.
548 * \param effect Effect to check to see if it is supported.
549 * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or
550 * -1 on error.
551 *
552 * \sa SDL_HapticQuery
553 * \sa SDL_HapticNewEffect
253 */ 554 */
254 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect); 555 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
255 556
256 /* 557 /*
257 * Creates a new haptic effect on the device. 558 * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
258 * 559 *
259 * Returns the id of the effect on success, -1 on failure. 560 * \brief Creates a new haptic effect on the device.
561 *
562 * \param haptic Haptic device to create the effect on.
563 * \param effect Properties of the effect to create.
564 * \return The id of the effect on success or -1 on error.
565 *
566 * \sa SDL_HapticUpdateEffect
567 * \sa SDL_HapticRunEffect
568 * \sa SDL_HapticDestroyEffect
260 */ 569 */
261 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect); 570 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
262 571
263 /* 572 /*
264 * Uploads an effect. Can be used dynamically, although behaviour when 573 * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
574 *
575 * \brief Updates an effect. Can be used dynamically, although behaviour when
265 * dynamically changing direction may be strange. Specifically the effect 576 * dynamically changing direction may be strange. Specifically the effect
266 * may reupload itself and start playing from the start. You cannot change 577 * may reupload itself and start playing from the start. You cannot change
267 * the type either when running UpdateEffect. 578 * the type either when running UpdateEffect.
268 * 579 *
269 * Returns the id of the effect on success, -1 on failure. 580 * \param haptic Haptic device that has the effect.
581 * \param effect Effect to update.
582 * \param data New effect properties to use.
583 * \return The id of the effect on success or -1 on error.
584 *
585 * \sa SDL_HapticNewEffect
586 * \sa SDL_HapticRunEffect
587 * \sa SDL_HapticDestroyEffect
270 */ 588 */
271 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data); 589 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
272 590
273 /* 591 /*
274 * Runs the haptic effect on it's assosciated haptic device. 592 * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
275 * 593 *
276 * Returns 0 on success or -1 on failure. 594 * \brief Runs the haptic effect on it's assosciated haptic device.
595 *
596 * \param haptic Haptic device to run the effect on.
597 * \param effect Identifier of the haptic effect to run.
598 * \return 0 on success or -1 on error.
599 *
600 * \sa SDL_HapticStopEffect
601 * \sa SDL_HapticDestroyEffect
602 * \sa SDL_HapticGetEffectStatus
277 */ 603 */
278 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect); 604 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
279 605
280 /* 606 /*
281 * Stops the haptic effect on it's assosciated haptic device. 607 * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
282 * 608 *
283 * Returns 0 on success or -1 on failure. 609 * \brief Stops the haptic effect on it's assosciated haptic device.
610 *
611 * \param haptic Haptic device to stop the effect on.
612 * \praam effect Identifier of the effect to stop.
613 * \return 0 on success or -1 on error.
614 *
615 * \sa SDL_HapticRunEffect
616 * \sa SDL_HapticDestroyEffect
284 */ 617 */
285 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect); 618 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
286 619
287 /* 620 /*
288 * Destroys a haptic effect on the device. This will stop the effect if it's 621 * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
289 * running. 622 *
623 * \brief Destroys a haptic effect on the device. This will stop the effect
624 * if it's running. Effects are automatically destroyed when the device is
625 * closed.
626 *
627 * \param haptic Device to destroy the effect on.
628 * \param effect Identifier of the effect to destroy.
629 *
630 * \sa SDL_HapticNewEffect
290 */ 631 */
291 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect); 632 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
292 633
293 /* 634 /*
294 * Gets the status of the current effect on the haptic device. 635 * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
295 * 636 *
296 * Returns 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing 637 * \brief Gets the status of the current effect on the haptic device.
297 * or -1 on failure. 638 *
639 * Device must support the SDL_HAPTIC_STATUS feature.
640 *
641 * \param haptic Haptic device to query the effect status on.
642 * \param effect Identifier of the effect to query it's status.
643 * \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
644 * or -1 on error.
645 *
646 * \sa SDL_HapticRunEffect
647 * \sa SDL_HapticStopEffect
298 */ 648 */
299 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect); 649 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
300 650
301 /* 651 /*
302 * Sets the global gain of the device. Gain should be between 0 and 100. 652 * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
303 * 653 *
304 * Returns 0 on success or -1 on failure. 654 * \brief Sets the global gain of the device. Gain should be between 0 and 100.
655 *
656 * Device must support the SDL_HAPTIC_GAIN feature.
657 *
658 * \param haptic Haptic device to set the gain on.
659 * \param gain Value to set the gain to, should be between 0 and 100.
660 * \return 0 on success or -1 on error.
661 *
662 * \sa SDL_HapticQuery
305 */ 663 */
306 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain); 664 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
307 665
308 /* 666 /*
309 * Sets the global autocenter of the device. Autocenter should be between 667 * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
668 *
669 * \brief Sets the global autocenter of the device. Autocenter should be between
310 * 0 and 100. Setting it to 0 will disable autocentering. 670 * 0 and 100. Setting it to 0 will disable autocentering.
311 * 671 *
312 * Returns 0 on success or -1 on failure. 672 * Device must support the SDL_HAPTIC_AUTOCENTER feature.
673 *
674 * \param haptic Haptic device to set autocentering on.
675 * \param autocenter Value to set autocenter to, 0 disables autocentering.
676 * \return 0 on success or -1 on error.
677 *
678 * \sa SDL_HapticQuery
313 */ 679 */
314 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter); 680 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
315 681
316 682
317 /* Ends C function definitions when using C++ */ 683 /* Ends C function definitions when using C++ */