/* SDL - Simple DirectMedia Layer Copyright (C) 2008 Edgar Simo This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Sam Lantinga slouken@libsdl.org */ /** \file SDL_haptic.h */ /** * \mainpage SDL_haptic * * The SDL Haptic subsystem allows you to control haptic (force feedback) * devices. * * The basic usage is as follows: * - Initialize the Subsystem (SDL_INIT_HAPTIC). * - Open a Haptic Device. * - SDL_HapticOpen(...) to open from index. * - SDL_HapticOpenFromJoystick(...) to open from an existing joystick. * - Create an effect (SDL_HapticEffect). * - Upload the effect with SDL_HapticNewEffect(...). * - Run the effect with SDL_HapticRunEffect(...). * - (optional) Free the effect with SDL_HapticDestroyEffect(...). * - Close the haptic device with SDL_HapticClose(...). * * * Example: * * \code * int test_haptic( SDL_Joystick * joystick ) { * SDL_Haptic *haptic; * SDL_HapticEffect effect; * int effect_id; * * // Open the device * haptic = SDL_HapticOpenFromJoystick( joystick ); * if (haptic == NULL) return -1; // Most likely joystick isn't haptic * * // See if it can do sine waves * if ((SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_SINE)==0) { * SDL_HapticClose(haptic); // No sine effect * return -1; * } * * // Create the effect * memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default * effect.type = SDL_HAPTIC_SINE; * effect.periodic.period = 1000; // 1000 ms * effect.periodic.magnitude = 20000; // 20000/32767 strength * effect.periodic.length = 5000; // 5 seconds long * effect.periodic.attack_length = 1000; // Takes 1 second to get max strength * effect.periodic.fade_length = 1000; // Takes 1 second to fade away * * // Upload the effect * effect_id = SDL_HapticNewEffect( haptic, &effect ); * * // Test the effect * SDL_HapticRunEffect( haptic, effect_id ); * SDL_Delay( 5000); // Wait for the effect to finish * * // We destroy the effect, although closing the device also does this * SDL_HapticDestroyEffect( haptic, effect_id ); * * // Close the device * SDL_HapticClose(haptic); * * return 0; // Success * } * \endcode * * \author Edgar Simo Serra */ #ifndef _SDL_haptic_h #define _SDL_haptic_h #include "SDL_stdinc.h" #include "SDL_error.h" #include "SDL_joystick.h" #include "begin_code.h" /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus /* *INDENT-OFF* */ extern "C" { /* *INDENT-ON* */ #endif /* __cpluspuls */ /** * \struct SDL_Haptic * * \brief The haptic structure used to identify an SDL haptic. * * \sa SDL_HapticOpen * \sa SDL_HapticOpenFromJoystick * \sa SDL_HapticClose */ struct _SDL_Haptic; typedef struct _SDL_Haptic SDL_Haptic; /* * Different haptic features a device can have. */ /** * \def SDL_HAPTIC_CONSTANT * * \brief Constant haptic effect. * * \sa SDL_HapticCondition */ #define SDL_HAPTIC_CONSTANT (1<<0) /* Constant effect supported */ /** * \def SDL_HAPTIC_SINE * * \brief Periodic haptic effect that simulates sine waves. * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SINE (1<<1) /* Sine wave effect supported */ /** * \def SDL_HAPTIC_SQUARE * * \brief Periodic haptic effect that simulates square waves. * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SQUARE (1<<2) /* Square wave effect supported */ /** * \def SDL_HAPTIC_TRIANGLE * * \brief Periodic haptic effect that simulates triangular waves. * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_TRIANGLE (1<<3) /* Triangle wave effect supported */ /** * \def SDL_HAPTIC_SAWTOOTHUP * * \brief Periodic haptic effect that simulates saw tooth up waves. * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */ /** * \def SDL_HAPTIC_SAWTOOTHDOWN * * \brief Periodic haptic effect that simulates saw tooth down waves. * * \sa SDL_HapticPeriodic */ #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */ /** * \def SDL_HAPTIC_RAMP * * \brief Ramp haptic effect. * * \sa SDL_HapticRamp */ #define SDL_HAPTIC_RAMP (1<<6) /* Ramp effect supported */ /** * \def SDL_HAPTIC_SPRING * * \brief Condition haptic effect that simulates a spring. Effect is based on the * axes position. * * \sa SDL_HapticCondition */ #define SDL_HAPTIC_SPRING (1<<7) /* Spring effect supported - uses axes position */ /** * \def SDL_HAPTIC_DAMPER * * \brief Condition haptic effect that simulates dampening. Effect is based on the * axes velocity. * * \sa SDL_HapticCondition */ #define SDL_HAPTIC_DAMPER (1<<8) /* Damper effect supported - uses axes velocity */ /** * \def SDL_HAPTIC_INERTIA * * \brief Condition haptic effect that simulates inertia. Effect is based on the axes * acceleration. * * \sa SDL_HapticCondition */ #define SDL_HAPTIC_INERTIA (1<<9) /* Inertia effect supported - uses axes acceleration */ /** * \def SDL_HAPTIC_FRICTION * * \brief Condition haptic effect that simulates friction. Effect is based on the axes * movement. * * \sa SDL_HapticCondition */ #define SDL_HAPTIC_FRICTION (1<<10) /* Friction effect supported - uses axes movement */ /** * \def SDL_HAPTIC_CUSTOM * * \brief User defined custom haptic effect. TODO. */ #define SDL_HAPTIC_CUSTOM (1<<11) /* Custom effect is supported */ /* These last two are features the device has, not effects */ /** * \def SDL_HAPTIC_GAIN * * \brief Device supports setting the global gain. * * \sa SDL_HapticSetGain */ #define SDL_HAPTIC_GAIN (1<<12) /* Device can set global gain */ /** * \def SDL_HAPTIC_AUTOCENTER * * \brief Device supports setting autocenter. * * \sa SDL_HapticSetAutocenter */ #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */ /** * \def SDL_HAPTIC_STATUS * * \brief Device can be queried for effect status. * * \sa SDL_HapticGetEffectStatus */ #define SDL_HAPTIC_STATUS (1<<14) /* Device can be queried for effect status */ /** * \struct SDL_HapticConstant * * \brief A structure containing a template for a Constant effect. * * The struct is exclusive to the SDL_HAPTIC_CONSTANT effect. * * \sa SDL_HAPTIC_CONSTANT * \sa SDL_HapticEffect */ typedef struct SDL_HapticConstant { /* Header */ Uint16 type; /**< SDL_HAPTIC_CONSTANT */ Uint16 direction; /* Replay */ Uint16 length; /**< Duration of the effect. */ Uint16 delay; /**< Delay before starting the effect. */ /* Trigger */ Uint16 button; /**< Button that triggers the effect. */ Uint16 interval; /**< How soon it can be triggered again after button. */ /* Constant */ Sint16 level; /**< Strength of the constant effect. */ /* Envelope */ Uint16 attack_length; /**< Duration of the attack. */ Uint16 attack_level; /**< Level at the start of the attack. */ Uint16 fade_length; /**< Duration of the fade. */ Uint16 fade_level; /**< Level at the end of the fade. */ } SDL_HapticConstant; /** * \struct SDL_HapticPeriodic * * \brief A structure containing a template for a Periodic effect. * * The struct handles the following effects: * - SDL_HAPTIC_SINE * - SDL_HAPTIC_SQUARE * - SDL_HAPTIC_TRIANGLE * - SDL_HAPTIC_SAWTOOTHUP * - SDL_HAPTIC_SAWTOOTHDOWN * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE * \sa SDL_HAPTIC_TRIANGLE * \sa SDL_HAPTIC_SAWTOOTHUP * \sa SDL_HAPTIC_SAWTOOTHDOWN * \sa SDL_HapticEffect */ typedef struct SDL_HapticPeriodic { /* Header */ Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */ Uint16 direction; /* Replay */ Uint16 length; /**< Duration of the effect. */ Uint16 delay; /**< Delay before starting the effect. */ /* Trigger */ Uint16 button; /**< Button that triggers the effect. */ Uint16 interval; /**< How soon it can be triggered again after button. */ /* Periodic */ Uint16 period; /**< Period of the wave. */ Sint16 magnitude; /**< Peak value. */ Sint16 offset; /**< Mean value of the wave. */ Uint16 phase; /**< Horizontal shift. */ /* Envelope */ Uint16 attack_length; /**< Duration of the attack. */ Uint16 attack_level; /**< Level at the start of the attack. */ Uint16 fade_length; /**< Duration of the fade. */ Uint16 fade_level; /**< Level at the end of the fade. */ } SDL_HapticPeriodic; /** * \struct SDL_HapticCondition * * \brief A structure containing a template for a Condition effect. * * The struct handles the following effects: * - SDL_HAPTIC_SPRING * - SDL_HAPTIC_DAMPER * - SDL_HAPTIC_INERTIA * - SDL_HAPTIC_FRICTION * * \sa SDL_HAPTIC_SPRING * \sa SDL_HAPTIC_DAMPER * \sa SDL_HAPTIC_INERTIA * \sa SDL_HAPTIC_FRICTION * \sa SDL_HapticEffect */ typedef struct SDL_HapticCondition { /* Header */ Uint16 type; /**< SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */ Uint16 direction; /* Replay */ Uint16 length; /**< Duration of the effect. */ Uint16 delay; /**< Delay before starting the effect. */ /* Trigger */ Uint16 button; /**< Button that triggers the effect. */ Uint16 interval; /**< How soon it can be triggered again after button. */ /* Condition */ Uint16 right_sat; /**< Level when joystick is to the right. */ Uint16 left_sat; /**< Level when joystick is to the left. */ Sint16 right_coeff; /**< How fast to increase the force towards the right. */ Sint16 left_coeff; /**< How fast to increase the force towards the left. */ Uint16 deadband; /**< Size of the dead zone. */ Sint16 center; /**< Position of the dead zone. */ } SDL_HapticCondition; /** * \struct SDL_HapticRamp * * \brief A structure containing a template for a Ramp effect. * * This struct is exclusively for the SDL_HAPTIC_RAMP effect. * * \sa SDL_HAPTIC_RAMP * \sa SDL_HapticEffect */ typedef struct SDL_HapticRamp { /* Header */ Uint16 type; /**< SDL_HAPTIC_RAMP */ Uint16 direction; /* Replay */ Uint16 length; /**< Duration of the effect. */ Uint16 delay; /**< Delay before starting the effect. */ /* Trigger */ Uint16 button; /**< Button that triggers the effect. */ Uint16 interval; /**< How soon it can be triggered again after button. */ /* Ramp */ Sint16 start; /**< Beginning strength level. */ Sint16 end; /**< Ending strength level. */ /* Envelope */ Uint16 attack_length; /**< Duration of the attack. */ Uint16 attack_level; /**< Level at the start of the attack. */ Uint16 fade_length; /**< Duration of the fade. */ Uint16 fade_level; /**< Level at the end of the fade. */ } SDL_HapticRamp; /* * \union SDL_HapticEffect * * \brief The generic template for any haptic effect. * * All values max at 32767 (0x7fff). Signed values also can be negative. * Time values unless specified otherwise are in milliseconds. * * Common parts: * * Replay: * Uint16 length; Duration of effect. * Uint16 delay; Delay before starting effect. * * Trigger: * Uint16 button; Button that triggers effect. * Uint16 interval; How soon before effect can be triggered again. * * Envelope: * Uint16 attack_length; Duration of the attack. * Uint16 attack_level; Level at the start of the attack. * Uint16 fade_length; Duration of the fade out. * Uint16 fade_level; Level at the end of the fade. * * \sa SDL_HapticConstant * \sa SDL_HapticPeriodic * \sa SDL_HapticCondition * \sa SDL_HaptiRamp */ typedef union SDL_HapticEffect { /* Common for all force feedback effects */ Uint16 type; /**< Effect type */ SDL_HapticConstant constant; /**< Constant effect */ SDL_HapticPeriodic periodic; /**< Periodic effect */ SDL_HapticCondition condition; /**< Condition effect */ SDL_HapticRamp ramp; /**< Ramp effect */ } SDL_HapticEffect; /* Function prototypes */ /* * \fn int SDL_NumHaptics(void) * * \brief Count the number of joysticks attached to the system. * * \return Number of haptic devices detected on the system. */ extern DECLSPEC int SDLCALL SDL_NumHaptics(void); /* * \fn const char * SDL_HapticName(int device_index) * * \brief Get the implementation dependent name of a Haptic device. * This can be called before any joysticks are opened. * If no name can be found, this function returns NULL. * * \param device_index Index of the device to get it's name. * \return Name of the device or NULL on error. * * \sa SDL_NumHaptics */ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); /* * \fn SDL_Haptic * SDL_HapticOpen(int device_Index) * * \brief Opens a Haptic device for usage - the index passed as an * argument refers to the N'th Haptic device on this system. * * This function returns a Haptic device identifier, or Null * if an error occurred. * * \param device_index Index of the device to open. * \return Device identifier or NULL on error. * * \sa SDL_HapticOpenFromJoystick * \sa SDL_HapticClose */ extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index); /* * \fn int SDL_JoystickIsHaptic(SDL_Joystick * joysticke) * * \brief Checks to see if a joystick has haptic features. * * \param joystick Joystick to test for haptic capabilities. * \return SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't * or -1 if an error ocurred. * * \sa SDL_HapticOpenFromJoystick */ extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick); /* * \fn SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick) * * \brief Opens a Haptic device for usage from a Joystick device. Still has * to be closed seperately to the joystick. * * \param joystick Joystick to create a haptic device from. * \return A valid haptic device identifier on success or NULL on error. * * \sa SDL_HapticOpen * \sa SDL_HapticClose */ extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick); /* * \fn void SDL_HapticClose(SDL_Haptic * haptic) * * \brief Closes a Haptic device previously opened with SDL_HapticOpen. * * \param haptic Haptic device to close. */ extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic); /* * \fn int SDL_HapticNumEffects(SDL_Haptic * haptic) * * \brief Returns the number of effects a haptic device can store. * * \param haptic The haptic device to query effect max. * \return The number of effects the haptic device can store or * -1 on error. * * \sa SDL_HapticQuery */ extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic); /* * \fn unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic) * * \brief Gets the haptic devices supported features in bitwise matter. * * Example: * \code * if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) { * printf("We have constant haptic effect!"); * } * \endcode * * * \param haptic The haptic device to query. * \return Haptic features in bitwise manner (OR'd). * * \sa SDL_HapticNumEffects * \sa SDL_HapticEffectSupported */ extern DECLSPEC unsigned int SDL_HapticQuery(SDL_Haptic * haptic); /* * \fn int SDL_HapticEffectSupported * * \brief Checks to see if effect is supported by haptic. * * \param haptic Haptic device to check on. * \param effect Effect to check to see if it is supported. * \return SDL_TRUE if effect is supported, SDL_FALSE if it isn't or * -1 on error. * * \sa SDL_HapticQuery * \sa SDL_HapticNewEffect */ extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect); /* * \fn int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect) * * \brief Creates a new haptic effect on the device. * * \param haptic Haptic device to create the effect on. * \param effect Properties of the effect to create. * \return The id of the effect on success or -1 on error. * * \sa SDL_HapticUpdateEffect * \sa SDL_HapticRunEffect * \sa SDL_HapticDestroyEffect */ extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect); /* * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data) * * \brief Updates an effect. Can be used dynamically, although behaviour when * dynamically changing direction may be strange. Specifically the effect * may reupload itself and start playing from the start. You cannot change * the type either when running UpdateEffect. * * \param haptic Haptic device that has the effect. * \param effect Effect to update. * \param data New effect properties to use. * \return The id of the effect on success or -1 on error. * * \sa SDL_HapticNewEffect * \sa SDL_HapticRunEffect * \sa SDL_HapticDestroyEffect */ extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data); /* * \fn int SDL_HapticRunEffects(SDL_Haptic * haptic, int effect) * * \brief Runs the haptic effect on it's assosciated haptic device. * * \param haptic Haptic device to run the effect on. * \param effect Identifier of the haptic effect to run. * \return 0 on success or -1 on error. * * \sa SDL_HapticStopEffect * \sa SDL_HapticDestroyEffect * \sa SDL_HapticGetEffectStatus */ extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect); /* * \fn int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect) * * \brief Stops the haptic effect on it's assosciated haptic device. * * \param haptic Haptic device to stop the effect on. * \praam effect Identifier of the effect to stop. * \return 0 on success or -1 on error. * * \sa SDL_HapticRunEffect * \sa SDL_HapticDestroyEffect */ extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect); /* * \fn void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect) * * \brief Destroys a haptic effect on the device. This will stop the effect * if it's running. Effects are automatically destroyed when the device is * closed. * * \param haptic Device to destroy the effect on. * \param effect Identifier of the effect to destroy. * * \sa SDL_HapticNewEffect */ extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect); /* * \fn int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect) * * \brief Gets the status of the current effect on the haptic device. * * Device must support the SDL_HAPTIC_STATUS feature. * * \param haptic Haptic device to query the effect status on. * \param effect Identifier of the effect to query it's status. * \return 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing * or -1 on error. * * \sa SDL_HapticRunEffect * \sa SDL_HapticStopEffect */ extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect); /* * \fn int SDL_HapticSetGain(SDL_Haptic * haptic, int gain) * * \brief Sets the global gain of the device. Gain should be between 0 and 100. * * Device must support the SDL_HAPTIC_GAIN feature. * * \param haptic Haptic device to set the gain on. * \param gain Value to set the gain to, should be between 0 and 100. * \return 0 on success or -1 on error. * * \sa SDL_HapticQuery */ extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain); /* * \fn int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter) * * \brief Sets the global autocenter of the device. Autocenter should be between * 0 and 100. Setting it to 0 will disable autocentering. * * Device must support the SDL_HAPTIC_AUTOCENTER feature. * * \param haptic Haptic device to set autocentering on. * \param autocenter Value to set autocenter to, 0 disables autocentering. * \return 0 on success or -1 on error. * * \sa SDL_HapticQuery */ extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter); /* Ends C function definitions when using C++ */ #ifdef __cplusplus /* *INDENT-OFF* */ } /* *INDENT-ON* */ #endif #include "close_code.h" #endif /* _SDL_haptic_h */ /* vi: set ts=4 sw=4 expandtab: */