Mercurial > sdl-ios-xcode

comparison include/SDL_haptic.h @ 2498:ab567bd667bf gsoc2008_force_feedback

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed various mistakes in the doxygen.
author Edgar Simo <bobbens@gmail.com>
date Sun, 06 Jul 2008 17:06:37 +0000
parents 0893fbf73b3d
children cc2b270608b2
comparison
equal deleted inserted replaced
2497:0893fbf73b3d 2498:ab567bd667bf
18 18
19 Sam Lantinga 19 Sam Lantinga
20 slouken@libsdl.org 20 slouken@libsdl.org
21 */ 21 */
22 22
23 /** \file SDL_haptic.h */ 23 /** \file SDL_Haptic.h */
24
24 /** 25 /**
25 * \mainpage SDL_haptic 26 * \mainpage SDL_haptic
26 * 27 *
27 * The SDL Haptic subsystem allows you to control haptic (force feedback) 28 * \brief The SDL Haptic subsystem allows you to control haptic (force feedback)
28 * devices. 29 * devices.
29 * 30 *
30 * The basic usage is as follows: 31 * The basic usage is as follows:
31 * - Initialize the Subsystem (SDL_INIT_HAPTIC). 32 * - Initialize the Subsystem (SDL_INIT_HAPTIC).
32 * - Open a Haptic Device. 33 * - Open a Haptic Device.
100 extern "C" { 101 extern "C" {
101 /* *INDENT-ON* */ 102 /* *INDENT-ON* */
102 #endif /* __cpluspuls */ 103 #endif /* __cpluspuls */
103 104
104 /** 105 /**
105 * \struct SDL_Haptic 106 * \typedef SDL_Haptic
106 * 107 *
107 * \brief The haptic structure used to identify an SDL haptic. 108 * \brief The haptic structure used to identify an SDL haptic.
108 * 109 *
109 * \sa SDL_HapticOpen 110 * \sa SDL_HapticOpen
110 * \sa SDL_HapticOpenFromJoystick 111 * \sa SDL_HapticOpenFromJoystick
387 Uint16 attack_length; /**< Duration of the attack. */ 388 Uint16 attack_length; /**< Duration of the attack. */
388 Uint16 attack_level; /**< Level at the start of the attack. */ 389 Uint16 attack_level; /**< Level at the start of the attack. */
389 Uint16 fade_length; /**< Duration of the fade. */ 390 Uint16 fade_length; /**< Duration of the fade. */
390 Uint16 fade_level; /**< Level at the end of the fade. */ 391 Uint16 fade_level; /**< Level at the end of the fade. */
391 } SDL_HapticRamp; 392 } SDL_HapticRamp;
392 /* 393 /**
393 * \union SDL_HapticEffect 394 * \union SDL_HapticEffect
394 * 395 *
395 * \brief The generic template for any haptic effect. 396 * \brief The generic template for any haptic effect.
396 * 397 *
397 * All values max at 32767 (0x7fff). Signed values also can be negative. 398 * All values max at 32767 (0x7fff). Signed values also can be negative.
427 SDL_HapticRamp ramp; /**< Ramp effect */ 428 SDL_HapticRamp ramp; /**< Ramp effect */
428 } SDL_HapticEffect; 429 } SDL_HapticEffect;
429 430
430 431
431 /* Function prototypes */ 432 /* Function prototypes */
432 /* 433 /**
433 * \fn int SDL_NumHaptics(void) 434 * \fn int SDL_NumHaptics(void)
434 * 435 *
435 * \brief Count the number of joysticks attached to the system. 436 * \brief Count the number of joysticks attached to the system.
436 * 437 *
437 * \return Number of haptic devices detected on the system. 438 * \return Number of haptic devices detected on the system.
438 */ 439 */
439 extern DECLSPEC int SDLCALL SDL_NumHaptics(void); 440 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
440 441
441 /* 442 /**
442 * \fn const char * SDL_HapticName(int device_index) 443 * \fn const char * SDL_HapticName(int device_index)
443 * 444 *
444 * \brief Get the implementation dependent name of a Haptic device. 445 * \brief Get the implementation dependent name of a Haptic device.
445 * This can be called before any joysticks are opened. 446 * This can be called before any joysticks are opened.
446 * If no name can be found, this function returns NULL. 447 * If no name can be found, this function returns NULL.
450 * 451 *
451 * \sa SDL_NumHaptics 452 * \sa SDL_NumHaptics
452 */ 453 */
453 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); 454 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
454 455
455 /* 456 /**
456 * \fn SDL_Haptic * SDL_HapticOpen(int device_Index) 457 * \fn SDL_Haptic * SDL_HapticOpen(int device_Index)
457 * 458 *
458 * \brief Opens a Haptic device for usage - the index passed as an 459 * \brief Opens a Haptic device for usage - the index passed as an
459 * argument refers to the N'th Haptic device on this system. 460 * argument refers to the N'th Haptic device on this system.
460 * 461 *
467 * \sa SDL_HapticOpenFromJoystick 468 * \sa SDL_HapticOpenFromJoystick
468 * \sa SDL_HapticClose 469 * \sa SDL_HapticClose
469 */ 470 */
470 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index); 471 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
471 472
472 /* 473 /**
473 * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke) 474 * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joystick)
474 * 475 *
475 * \brief Checks to see if a joystick has haptic features. 476 * \brief Checks to see if a joystick has haptic features.
476 * 477 *
477 * \param joystick Joystick to test for haptic capabilities. 478 * \param joystick Joystick to test for haptic capabilities.
478 * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't 479 * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
480 * 481 *
481 * \sa SDL_HapticOpenFromJoystick 482 * \sa SDL_HapticOpenFromJoystick
482 */ 483 */
483 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick); 484 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
484 485
485 /* 486 /**
486 * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick) 487 * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick)
487 * 488 *
488 * \brief Opens a Haptic device for usage from a Joystick device. Still has 489 * \brief Opens a Haptic device for usage from a Joystick device. Still has
489 * to be closed seperately to the joystick. 490 * to be closed seperately to the joystick.
490 * 491 *
494 * \sa SDL_HapticOpen 495 * \sa SDL_HapticOpen
495 * \sa SDL_HapticClose 496 * \sa SDL_HapticClose
496 */ 497 */
497 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick); 498 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
498 499
499 /* 500 /**
500 * \fn void SDL_HapticClose(SDL_Haptic * haptic) 501 * \fn void SDL_HapticClose(SDL_Haptic * haptic)
501 * 502 *
502 * \brief Closes a Haptic device previously opened with SDL_HapticOpen. 503 * \brief Closes a Haptic device previously opened with SDL_HapticOpen.
503 * 504 *
504 * \param haptic Haptic device to close. 505 * \param haptic Haptic device to close.
505 */ 506 */
506 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic); 507 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
507 508
508 /* 509 /**
509 * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic) 510 * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic)
510 * 511 *
511 * \brief Returns the number of effects a haptic device can store. 512 * \brief Returns the number of effects a haptic device can store.
512 * 513 *
513 * \param haptic The haptic device to query effect max. 514 * \param haptic The haptic device to query effect max.
516 * 517 *
517 * \sa SDL_HapticQuery 518 * \sa SDL_HapticQuery
518 */ 519 */
519 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic); 520 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
520 521
521 /* 522 /**
522 * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic) 523 * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic)
523 * 524 *
524 * \brief Gets the haptic devices supported features in bitwise matter. 525 * \brief Gets the haptic devices supported features in bitwise matter.
525 * 526 *
526 * Example: 527 * Example:
537 * \sa SDL_HapticNumEffects 538 * \sa SDL_HapticNumEffects
538 * \sa SDL_HapticEffectSupported 539 * \sa SDL_HapticEffectSupported
539 */ 540 */
540 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic); 541 extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic);
541 542
542 /* 543 /**
543 * \fn int SDL_HapticEffectSupported 544 * \fn int SDL_HapticEffectSupported
544 * 545 *
545 * \brief Checks to see if effect is supported by haptic. 546 * \brief Checks to see if effect is supported by haptic.
546 * 547 *
547 * \param haptic Haptic device to check on. 548 * \param haptic Haptic device to check on.
552 * \sa SDL_HapticQuery 553 * \sa SDL_HapticQuery
553 * \sa SDL_HapticNewEffect 554 * \sa SDL_HapticNewEffect
554 */ 555 */
555 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect); 556 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
556 557
557 /* 558 /**
558 * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect) 559 * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
559 * 560 *
560 * \brief Creates a new haptic effect on the device. 561 * \brief Creates a new haptic effect on the device.
561 * 562 *
562 * \param haptic Haptic device to create the effect on. 563 * \param haptic Haptic device to create the effect on.
567 * \sa SDL_HapticRunEffect 568 * \sa SDL_HapticRunEffect
568 * \sa SDL_HapticDestroyEffect 569 * \sa SDL_HapticDestroyEffect
569 */ 570 */
570 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect); 571 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
571 572
572 /* 573 /**
573 * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data) 574 * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
574 * 575 *
575 * \brief Updates an effect. Can be used dynamically, although behaviour when 576 * \brief Updates an effect. Can be used dynamically, although behaviour when
576 * dynamically changing direction may be strange. Specifically the effect 577 * dynamically changing direction may be strange. Specifically the effect
577 * may reupload itself and start playing from the start. You cannot change 578 * may reupload itself and start playing from the start. You cannot change
586 * \sa SDL_HapticRunEffect 587 * \sa SDL_HapticRunEffect
587 * \sa SDL_HapticDestroyEffect 588 * \sa SDL_HapticDestroyEffect
588 */ 589 */
589 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data); 590 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
590 591
591 /* 592 /**
592 * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect) 593 * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect)
593 * 594 *
594 * \brief Runs the haptic effect on it's assosciated haptic device. 595 * \brief Runs the haptic effect on it's assosciated haptic device.
595 * 596 *
596 * \param haptic Haptic device to run the effect on. 597 * \param haptic Haptic device to run the effect on.
601 * \sa SDL_HapticDestroyEffect 602 * \sa SDL_HapticDestroyEffect
602 * \sa SDL_HapticGetEffectStatus 603 * \sa SDL_HapticGetEffectStatus
603 */ 604 */
604 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect); 605 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
605 606
606 /* 607 /**
607 * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect) 608 * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect)
608 * 609 *
609 * \brief Stops the haptic effect on it's assosciated haptic device. 610 * \brief Stops the haptic effect on it's assosciated haptic device.
610 * 611 *
611 * \param haptic Haptic device to stop the effect on. 612 * \param haptic Haptic device to stop the effect on.
615 * \sa SDL_HapticRunEffect 616 * \sa SDL_HapticRunEffect
616 * \sa SDL_HapticDestroyEffect 617 * \sa SDL_HapticDestroyEffect
617 */ 618 */
618 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect); 619 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
619 620
620 /* 621 /**
621 * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect) 622 * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect)
622 * 623 *
623 * \brief Destroys a haptic effect on the device. This will stop the effect 624 * \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 * if it's running. Effects are automatically destroyed when the device is
625 * closed. 626 * closed.
629 * 630 *
630 * \sa SDL_HapticNewEffect 631 * \sa SDL_HapticNewEffect
631 */ 632 */
632 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect); 633 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
633 634
634 /* 635 /**
635 * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect) 636 * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect)
636 * 637 *
637 * \brief Gets the status of the current effect on the haptic device. 638 * \brief Gets the status of the current effect on the haptic device.
638 * 639 *
639 * Device must support the SDL_HAPTIC_STATUS feature. 640 * Device must support the SDL_HAPTIC_STATUS feature.
646 * \sa SDL_HapticRunEffect 647 * \sa SDL_HapticRunEffect
647 * \sa SDL_HapticStopEffect 648 * \sa SDL_HapticStopEffect
648 */ 649 */
649 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect); 650 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
650 651
651 /* 652 /**
652 * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain) 653 * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain)
653 * 654 *
654 * \brief Sets the global gain of the device. Gain should be between 0 and 100. 655 * \brief Sets the global gain of the device. Gain should be between 0 and 100.
655 * 656 *
656 * Device must support the SDL_HAPTIC_GAIN feature. 657 * Device must support the SDL_HAPTIC_GAIN feature.
661 * 662 *
662 * \sa SDL_HapticQuery 663 * \sa SDL_HapticQuery
663 */ 664 */
664 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain); 665 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
665 666
666 /* 667 /**
667 * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter) 668 * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter)
668 * 669 *
669 * \brief Sets the global autocenter of the device. Autocenter should be between 670 * \brief Sets the global autocenter of the device. Autocenter should be between
670 * 0 and 100. Setting it to 0 will disable autocentering. 671 * 0 and 100. Setting it to 0 will disable autocentering.
671 * 672 *