/Users/hercules/trunk/SDL/include/SDL_haptic.h File Reference

The SDL Haptic subsystem allows you to control haptic (force feedback) devices. More...

#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_joystick.h"
#include "begin_code.h"
#include "close_code.h"

Go to the source code of this file.

Data Structures

struct  SDL_HapticDirection
 Structure that represents a haptic direction. More...
struct  SDL_HapticConstant
 A structure containing a template for a Constant effect. More...
struct  SDL_HapticPeriodic
 A structure containing a template for a Periodic effect. More...
struct  SDL_HapticCondition
 A structure containing a template for a Condition effect. More...
struct  SDL_HapticRamp
 A structure containing a template for a Ramp effect. More...
struct  SDL_HapticCustom
 A structure containing a template for the SDL_HAPTIC_CUSTOM effect. More...
union  SDL_HapticEffect
 The generic template for any haptic effect. More...

Defines

#define SDL_HAPTIC_CONSTANT   (1<<0)
 Constant haptic effect.
#define SDL_HAPTIC_SINE   (1<<1)
 Periodic haptic effect that simulates sine waves.
#define SDL_HAPTIC_SQUARE   (1<<2)
 Periodic haptic effect that simulates square waves.
#define SDL_HAPTIC_TRIANGLE   (1<<3)
 Periodic haptic effect that simulates triangular waves.
#define SDL_HAPTIC_SAWTOOTHUP   (1<<4)
 Periodic haptic effect that simulates saw tooth up waves.
#define SDL_HAPTIC_SAWTOOTHDOWN   (1<<5)
 Periodic haptic effect that simulates saw tooth down waves.
#define SDL_HAPTIC_RAMP   (1<<6)
 Ramp haptic effect.
#define SDL_HAPTIC_SPRING   (1<<7)
 Condition haptic effect that simulates a spring. Effect is based on the axes position.
#define SDL_HAPTIC_DAMPER   (1<<8)
 Condition haptic effect that simulates dampening. Effect is based on the axes velocity.
#define SDL_HAPTIC_INERTIA   (1<<9)
 Condition haptic effect that simulates inertia. Effect is based on the axes acceleration.
#define SDL_HAPTIC_FRICTION   (1<<10)
 Condition haptic effect that simulates friction. Effect is based on the axes movement.
#define SDL_HAPTIC_CUSTOM   (1<<11)
 User defined custom haptic effect.
#define SDL_HAPTIC_GAIN   (1<<12)
 Device supports setting the global gain.
#define SDL_HAPTIC_AUTOCENTER   (1<<13)
 Device supports setting autocenter.
#define SDL_HAPTIC_STATUS   (1<<14)
 Device can be queried for effect status.
#define SDL_HAPTIC_PAUSE   (1<<15)
 Device can be paused.
#define SDL_HAPTIC_POLAR   0
 Uses polar coordinates for the direction.
#define SDL_HAPTIC_CARTESIAN   1
 Uses cartesian coordinates for the direction.
#define SDL_HAPTIC_SPHERICAL   2
 Uses spherical coordinates for the direction.
#define SDL_HAPTIC_INFINITY   4294967295U
 Used to play a device an infinite number of times.

Typedefs

typedef struct _SDL_Haptic SDL_Haptic
 The haptic structure used to identify an SDL haptic.

Functions

DECLSPEC int SDLCALL SDL_NumHaptics (void)
 Count the number of joysticks attached to the system.
DECLSPEC const char *SDLCALL SDL_HapticName (int device_index)
 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.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen (int device_index)
 Opens a Haptic device for usage - the index passed as an argument refers to the N'th Haptic device on this system.
DECLSPEC int SDLCALL SDL_HapticOpened (int device_index)
 Checks if the haptic device at index has been opened.
DECLSPEC int SDLCALL SDL_HapticIndex (SDL_Haptic *haptic)
 Gets the index of a haptic device.
DECLSPEC int SDLCALL SDL_MouseIsHaptic (void)
 Gets whether or not the current mouse has haptic capabilities.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse (void)
 Tries to open a haptic device from the current mouse.
DECLSPEC int SDLCALL SDL_JoystickIsHaptic (SDL_Joystick *joystick)
 Checks to see if a joystick has haptic features.
DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick (SDL_Joystick *joystick)
 Opens a Haptic device for usage from a Joystick device. Still has to be closed seperately to the joystick.
DECLSPEC void SDLCALL SDL_HapticClose (SDL_Haptic *haptic)
 Closes a Haptic device previously opened with SDL_HapticOpen.
DECLSPEC int SDLCALL SDL_HapticNumEffects (SDL_Haptic *haptic)
 Returns the number of effects a haptic device can store.
DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying (SDL_Haptic *haptic)
 Returns the number of effects a haptic device can play at the same time.
DECLSPEC unsigned int SDLCALL SDL_HapticQuery (SDL_Haptic *haptic)
 Gets the haptic devices supported features in bitwise matter.
DECLSPEC int SDLCALL SDL_HapticNumAxes (SDL_Haptic *haptic)
 Gets the number of haptic axes the device has.
DECLSPEC int SDLCALL SDL_HapticEffectSupported (SDL_Haptic *haptic, SDL_HapticEffect *effect)
 Checks to see if effect is supported by haptic.
DECLSPEC int SDLCALL SDL_HapticNewEffect (SDL_Haptic *haptic, SDL_HapticEffect *effect)
 Creates a new haptic effect on the device.
DECLSPEC int SDLCALL SDL_HapticUpdateEffect (SDL_Haptic *haptic, int effect, SDL_HapticEffect *data)
 Updates the properties of an effect.
DECLSPEC int SDLCALL SDL_HapticRunEffect (SDL_Haptic *haptic, int effect, Uint32 iterations)
 Runs the haptic effect on it's assosciated haptic device.
DECLSPEC int SDLCALL SDL_HapticStopEffect (SDL_Haptic *haptic, int effect)
 Stops the haptic effect on it's assosciated haptic device.
DECLSPEC void SDLCALL SDL_HapticDestroyEffect (SDL_Haptic *haptic, int effect)
 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.
DECLSPEC int SDLCALL SDL_HapticGetEffectStatus (SDL_Haptic *haptic, int effect)
 Gets the status of the current effect on the haptic device.
DECLSPEC int SDLCALL SDL_HapticSetGain (SDL_Haptic *haptic, int gain)
 Sets the global gain of the device. Gain should be between 0 and 100.
DECLSPEC int SDLCALL SDL_HapticSetAutocenter (SDL_Haptic *haptic, int autocenter)
 Sets the global autocenter of the device. Autocenter should be between 0 and 100. Setting it to 0 will disable autocentering.
DECLSPEC int SDLCALL SDL_HapticPause (SDL_Haptic *haptic)
 Pauses a haptic device.
DECLSPEC int SDLCALL SDL_HapticUnpause (SDL_Haptic *haptic)
 Unpauses a haptic device.
DECLSPEC int SDLCALL SDL_HapticStopAll (SDL_Haptic *haptic)
 Stops all the currently playing effects on a haptic device.

Detailed Description

The SDL Haptic subsystem allows you to control haptic (force feedback) devices.

The basic usage is as follows:

Example:

 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_HapticQuery(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.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
    effect.periodic.direction.dir[0] = 18000; // Force comes from south
    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, 1 );
    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
 }

Author:
Edgar Simo Serra

Define Documentation

#define SDL_HAPTIC_AUTOCENTER   (1<<13)

Device supports setting autocenter.

See also:
SDL_HapticSetAutocenter

#define SDL_HAPTIC_CARTESIAN   1

Uses cartesian coordinates for the direction.

See also:
SDL_HapticDirection

#define SDL_HAPTIC_CONSTANT   (1<<0)

Constant haptic effect.

See also:
SDL_HapticCondition

#define SDL_HAPTIC_DAMPER   (1<<8)

Condition haptic effect that simulates dampening. Effect is based on the axes velocity.

See also:
SDL_HapticCondition

#define SDL_HAPTIC_FRICTION   (1<<10)

Condition haptic effect that simulates friction. Effect is based on the axes movement.

See also:
SDL_HapticCondition

#define SDL_HAPTIC_GAIN   (1<<12)

Device supports setting the global gain.

See also:
SDL_HapticSetGain

#define SDL_HAPTIC_INERTIA   (1<<9)

Condition haptic effect that simulates inertia. Effect is based on the axes acceleration.

See also:
SDL_HapticCondition

#define SDL_HAPTIC_INFINITY   4294967295U

Used to play a device an infinite number of times.

See also:
SDL_HapticRunEffect

#define SDL_HAPTIC_PAUSE   (1<<15)

Device can be paused.

See also:
SDL_HapticPause

SDL_HapticUnpause

#define SDL_HAPTIC_POLAR   0

Uses polar coordinates for the direction.

See also:
SDL_HapticDirection

#define SDL_HAPTIC_RAMP   (1<<6)

Ramp haptic effect.

See also:
SDL_HapticRamp

#define SDL_HAPTIC_SAWTOOTHDOWN   (1<<5)

Periodic haptic effect that simulates saw tooth down waves.

See also:
SDL_HapticPeriodic

#define SDL_HAPTIC_SAWTOOTHUP   (1<<4)

Periodic haptic effect that simulates saw tooth up waves.

See also:
SDL_HapticPeriodic

#define SDL_HAPTIC_SINE   (1<<1)

Periodic haptic effect that simulates sine waves.

See also:
SDL_HapticPeriodic

#define SDL_HAPTIC_SPHERICAL   2

Uses spherical coordinates for the direction.

See also:
SDL_HapticDirection

#define SDL_HAPTIC_SPRING   (1<<7)

Condition haptic effect that simulates a spring. Effect is based on the axes position.

See also:
SDL_HapticCondition

#define SDL_HAPTIC_SQUARE   (1<<2)

Periodic haptic effect that simulates square waves.

See also:
SDL_HapticPeriodic

#define SDL_HAPTIC_STATUS   (1<<14)

Device can be queried for effect status.

See also:
SDL_HapticGetEffectStatus

#define SDL_HAPTIC_TRIANGLE   (1<<3)

Periodic haptic effect that simulates triangular waves.

See also:
SDL_HapticPeriodic

Typedef Documentation

SDL_Haptic

The haptic structure used to identify an SDL haptic.

See also:
SDL_HapticOpen

SDL_HapticOpenFromJoystick

SDL_HapticClose

Function Documentation

void SDL_HapticClose ( SDL_Haptic *  haptic  ) 

Closes a Haptic device previously opened with SDL_HapticOpen.

Parameters:
haptic Haptic device to close.

void SDL_HapticDestroyEffect ( SDL_Haptic *  haptic,
int  effect 
)

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.

Parameters:
haptic Device to destroy the effect on.
effect Identifier of the effect to destroy.
See also:
SDL_HapticNewEffect

int SDL_HapticEffectSupported ( SDL_Haptic *  haptic,
SDL_HapticEffect *  effect 
)

Checks to see if effect is supported by haptic.

Parameters:
haptic Haptic device to check on.
effect Effect to check to see if it is supported.
Returns:
SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.
See also:
SDL_HapticQuery

SDL_HapticNewEffect

int SDL_HapticGetEffectStatus ( SDL_Haptic *  haptic,
int  effect 
)

Gets the status of the current effect on the haptic device.

Device must support the SDL_HAPTIC_STATUS feature.

Parameters:
haptic Haptic device to query the effect status on.
effect Identifier of the effect to query it's status.
Returns:
0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing or -1 on error.
See also:
SDL_HapticRunEffect

SDL_HapticStopEffect

int SDL_HapticIndex ( SDL_Haptic *  haptic  ) 

Gets the index of a haptic device.

Parameters:
haptic Haptic device to get the index of.
Returns:
The index of the haptic device or -1 on error.
See also:
SDL_HapticOpen

SDL_HapticOpened

const char * SDL_HapticName ( int  device_index  ) 

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.

Parameters:
device_index Index of the device to get it's name.
Returns:
Name of the device or NULL on error.
See also:
SDL_NumHaptics

int SDL_HapticNewEffect ( SDL_Haptic *  haptic,
SDL_HapticEffect *  effect 
)

Creates a new haptic effect on the device.

Parameters:
haptic Haptic device to create the effect on.
effect Properties of the effect to create.
Returns:
The id of the effect on success or -1 on error.
See also:
SDL_HapticUpdateEffect

SDL_HapticRunEffect

SDL_HapticDestroyEffect

int SDL_HapticNumAxes ( SDL_Haptic *  haptic  ) 

Gets the number of haptic axes the device has.

See also:
SDL_HapticDirection

int SDL_HapticNumEffects ( SDL_Haptic *  haptic  ) 

Returns the number of effects a haptic device can store.

On some platforms this isn't fully supported, and therefore is an aproximation. Always check to see if your created effect was actually created and do not rely solely on HapticNumEffects.

Parameters:
haptic The haptic device to query effect max.
Returns:
The number of effects the haptic device can store or -1 on error.
See also:
SDL_HapticNumEffectsPlaying

SDL_HapticQuery

int SDL_HapticNumEffectsPlaying ( SDL_Haptic *  haptic  ) 

Returns the number of effects a haptic device can play at the same time.

This is not supported on all platforms, but will always return a value. Added here for the sake of completness.

Parameters:
haptic The haptic device to query maximum playing effect.s
Returns:
The number of effects the haptic device can play at the same time or -1 on error.
See also:
SDL_HapticNumEffects

SDL_HapticQuery

SDL_Haptic * SDL_HapticOpen ( int  device_index  ) 

Opens a Haptic device for usage - the index passed as an argument refers to the N'th Haptic device on this system.

When opening a haptic device, it's gain will be set to maximum and autocenter will be disabled. To modify these values use SDL_HapticSetGain and SDL_HapticSetAutocenter

Parameters:
device_index Index of the device to open.
Returns:
Device identifier or NULL on error.
See also:
SDL_HapticIndex

SDL_HapticOpenFromMouse

SDL_HapticOpenFromJoystick

SDL_HapticClose

SDL_HapticSetGain

SDL_HapticSetAutocenter

SDL_HapticPause

SDL_HapticStopAll

int SDL_HapticOpened ( int  device_index  ) 

Checks if the haptic device at index has been opened.

Parameters:
device_index Index to check to see if it has been opened.
Returns:
1 if it has been opened or 0 if it hasn't.
See also:
SDL_HapticOpen

SDL_HapticIndex

SDL_Haptic * SDL_HapticOpenFromJoystick ( SDL_Joystick *  joystick  ) 

Opens a Haptic device for usage from a Joystick device. Still has to be closed seperately to the joystick.

When opening from a joystick you should first close the haptic device before closing the joystick device. If not, on some implementations the haptic device will also get unallocated and you'll be unable to use force feedback on that device.

Parameters:
joystick Joystick to create a haptic device from.
Returns:
A valid haptic device identifier on success or NULL on error.
See also:
SDL_HapticOpen

SDL_HapticClose

SDL_Haptic * SDL_HapticOpenFromMouse ( void   ) 

Tries to open a haptic device from the current mouse.

Returns:
The haptic device identifier or NULL on error.
See also:
SDL_MouseIsHaptic

SDL_HapticOpen

DECLSPEC int SDLCALL SDL_HapticPause ( SDL_Haptic *  haptic  ) 

Pauses a haptic device.

Device must support the SDL_HAPTIC_PAUSE feature. Call SDL_HapticUnpause to resume playback.

Do not modify the effects nor add new ones while the device is paused. That can cause all sorts of weird errors.

Parameters:
haptic Haptic device to pause.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticUnpause

unsigned int SDL_HapticQuery ( SDL_Haptic *  haptic  ) 

Gets the haptic devices supported features in bitwise matter.

Example: 

 if (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT) {
    printf("We have constant haptic effect!");
 }

Parameters:
haptic The haptic device to query.
Returns:
Haptic features in bitwise manner (OR'd).
See also:
SDL_HapticNumEffects

SDL_HapticEffectSupported

int SDL_HapticRunEffect ( SDL_Haptic *  haptic,
int  effect,
Uint32  iterations 
)

Runs the haptic effect on it's assosciated haptic device.

If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over repeating the envelope (attack and fade) every time. If you only want the effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length parameter.

Parameters:
haptic Haptic device to run the effect on.
effect Identifier of the haptic effect to run.
iterations Number of iterations to run the effect. Use SDL_HAPTIC_INFINITY for infinity.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticStopEffect

SDL_HapticDestroyEffect

SDL_HapticGetEffectStatus

int SDL_HapticSetAutocenter ( SDL_Haptic *  haptic,
int  autocenter 
)

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.

Parameters:
haptic Haptic device to set autocentering on.
autocenter Value to set autocenter to, 0 disables autocentering.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticQuery

int SDL_HapticSetGain ( SDL_Haptic *  haptic,
int  gain 
)

Sets the global gain of the device. Gain should be between 0 and 100.

Device must support the SDL_HAPTIC_GAIN feature.

The user may specify the maxmimum gain by setting the environment variable SDL_HAPTIC_GAIN_MAX which should be between 0 and 100. All calls to SDL_HapticSetGain will scale linearly using SDL_HAPTIC_GAIN_MAX as the maximum.

Parameters:
haptic Haptic device to set the gain on.
gain Value to set the gain to, should be between 0 and 100.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticQuery

DECSLPEC int SDLCALL SDL_HapticStopAll ( SDL_Haptic *  haptic  ) 

Stops all the currently playing effects on a haptic device.

Parameters:
haptic Haptic device to stop.
Returns:
0 on success or -1 on error.

int SDL_HapticStopEffect ( SDL_Haptic *  haptic,
int  effect 
)

Stops the haptic effect on it's assosciated haptic device.

Parameters:
haptic Haptic device to stop the effect on.
effect Identifier of the effect to stop.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticRunEffect

SDL_HapticDestroyEffect

DECLSPEC int SDLCALL SDL_HapticUnpause ( SDL_Haptic *  haptic  ) 

Unpauses a haptic device.

Call to unpause after SDL_HapticPause.

Parameters:
haptic Haptic device to pause.
Returns:
0 on success or -1 on error.
See also:
SDL_HapticPause

int SDL_HapticUpdateEffect ( SDL_Haptic *  haptic,
int  effect,
SDL_HapticEffect *  data 
)

Updates the properties of 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.

Parameters:
haptic Haptic device that has the effect.
effect Effect to update.
data New effect properties to use.
Returns:
The id of the effect on success or -1 on error.
See also:
SDL_HapticNewEffect

SDL_HapticRunEffect

SDL_HapticDestroyEffect

int SDL_JoystickIsHaptic ( SDL_Joystick *  joystick  ) 

Checks to see if a joystick has haptic features.

Parameters:
joystick Joystick to test for haptic capabilities.
Returns:
SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't or -1 if an error ocurred.
See also:
SDL_HapticOpenFromJoystick

int SDL_MouseIsHaptic ( void   ) 

Gets whether or not the current mouse has haptic capabilities.

Returns:
SDL_TRUE if the mouse is haptic, SDL_FALSE if it isn't.
See also:
SDL_HapticOpenFromMouse

int SDL_NumHaptics ( void   ) 

Count the number of joysticks attached to the system.

Returns:
Number of haptic devices detected on the system.

Generated on Mon Sep 21 21:32:25 2009 for Simple DirectMedia Layer by  doxygen 1.5.8