#include "../SDL_internal.h"
#include "SDL_syshaptic.h"
#include "SDL_haptic_c.h"
#include "../joystick/SDL_joystick_c.h"
#include "SDL_assert.h"

Include dependency graph for SDL_haptic.c:

Functions
int	SDL_HapticInit (void)
static int	ValidHaptic (SDL_Haptic *haptic)
int	SDL_NumHaptics (void)
	Count the number of haptic devices attached to the system.
const char *	SDL_HapticName (int device_index)
	Get the implementation dependent name of a haptic device.
SDL_Haptic *	SDL_HapticOpen (int device_index)
	Opens a haptic device for use.
int	SDL_HapticOpened (int device_index)
	Checks if the haptic device at index has been opened.
int	SDL_HapticIndex (SDL_Haptic *haptic)
	Gets the index of a haptic device.
int	SDL_MouseIsHaptic (void)
	Gets whether or not the current mouse has haptic capabilities.
SDL_Haptic *	SDL_HapticOpenFromMouse (void)
	Tries to open a haptic device from the current mouse.
int	SDL_JoystickIsHaptic (SDL_Joystick *joystick)
	Checks to see if a joystick has haptic features.
SDL_Haptic *	SDL_HapticOpenFromJoystick (SDL_Joystick *joystick)
	Opens a haptic device for use from a joystick device.
void	SDL_HapticClose (SDL_Haptic *haptic)
	Closes a haptic device previously opened with SDL_HapticOpen().
void	SDL_HapticQuit (void)
int	SDL_HapticNumEffects (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can store.
int	SDL_HapticNumEffectsPlaying (SDL_Haptic *haptic)
	Returns the number of effects a haptic device can play at the same time.
unsigned int	SDL_HapticQuery (SDL_Haptic *haptic)
	Gets the haptic device's supported features in bitwise manner.
int	SDL_HapticNumAxes (SDL_Haptic *haptic)
	Gets the number of haptic axes the device has.
int	SDL_HapticEffectSupported (SDL_Haptic haptic, SDL_HapticEffect effect)
	Checks to see if effect is supported by haptic.
int	SDL_HapticNewEffect (SDL_Haptic haptic, SDL_HapticEffect effect)
	Creates a new haptic effect on the device.
static int	ValidEffect (SDL_Haptic *haptic, int effect)
int	SDL_HapticUpdateEffect (SDL_Haptic haptic, int effect, SDL_HapticEffect data)
	Updates the properties of an effect.
int	SDL_HapticRunEffect (SDL_Haptic *haptic, int effect, Uint32 iterations)
	Runs the haptic effect on its associated haptic device.
int	SDL_HapticStopEffect (SDL_Haptic *haptic, int effect)
	Stops the haptic effect on its associated haptic device.
void	SDL_HapticDestroyEffect (SDL_Haptic *haptic, int effect)
	Destroys a haptic effect on the device.
int	SDL_HapticGetEffectStatus (SDL_Haptic *haptic, int effect)
	Gets the status of the current effect on the haptic device.
int	SDL_HapticSetGain (SDL_Haptic *haptic, int gain)
	Sets the global gain of the device.
int	SDL_HapticSetAutocenter (SDL_Haptic *haptic, int autocenter)
	Sets the global autocenter of the device.
int	SDL_HapticPause (SDL_Haptic *haptic)
	Pauses a haptic device.
int	SDL_HapticUnpause (SDL_Haptic *haptic)
	Unpauses a haptic device.
int	SDL_HapticStopAll (SDL_Haptic *haptic)
	Stops all the currently playing effects on a haptic device.
int	SDL_HapticRumbleSupported (SDL_Haptic *haptic)
	Checks to see if rumble is supported on a haptic device.
int	SDL_HapticRumbleInit (SDL_Haptic *haptic)
	Initializes the haptic device for simple rumble playback.
int	SDL_HapticRumblePlay (SDL_Haptic *haptic, float strength, Uint32 length)
	Runs simple rumble on a haptic device.
int	SDL_HapticRumbleStop (SDL_Haptic *haptic)
	Stops the simple rumble on a haptic device.

Variables
SDL_Haptic *	SDL_haptics = NULL

Function Documentation

void SDL_HapticClose ( SDL_Haptic * haptic )

Closes a haptic device previously opened with SDL_HapticOpen().

Parameters

haptic Haptic device to close.

Definition at line 335 of file SDL_haptic.c.

References i, NULL, SDL_free, SDL_HapticDestroyEffect, SDL_haptics, SDL_SYS_HapticClose(), and ValidHaptic().

{
    int i;
    SDL_Haptic *hapticlist;
    SDL_Haptic *hapticlistprev;
    /* Must be valid */
    if (!ValidHaptic(haptic)) {
        return;
    }
    /* Check if it's still in use */
    if (--haptic->ref_count > 0) {
        return;
    }
    /* Close it, properly removing effects if needed */
    for (i = 0; i < haptic->neffects; i++) {
        if (haptic->effects[i].hweffect != NULL) {
            SDL_HapticDestroyEffect(haptic, i);
        }
    }
    SDL_SYS_HapticClose(haptic);
    /* Remove from the list */
    hapticlist = SDL_haptics;
    hapticlistprev = NULL;
    while ( hapticlist )
    {
        if (haptic == hapticlist)
        {
            if ( hapticlistprev )
            {
                /* unlink this entry */
                hapticlistprev->next = hapticlist->next;
            }
            else
            {
                SDL_haptics = haptic->next;
            }
            break;
        }
        hapticlistprev = hapticlist;
        hapticlist = hapticlist->next;
    }
    /* Free */
    SDL_free(haptic);
}

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

Definition at line 588 of file SDL_haptic.c.

References NULL, SDL_SYS_HapticDestroyEffect(), ValidEffect(), and ValidHaptic().

{
    if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
        return;
    }
    /* Not allocated */
    if (haptic->effects[effect].hweffect == NULL) {
        return;
    }
    SDL_SYS_HapticDestroyEffect(haptic, &haptic->effects[effect]);
}

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

Definition at line 458 of file SDL_haptic.c.

References SDL_FALSE, SDL_TRUE, SDL_HapticEffect::type, and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if ((haptic->supported & effect->type) != 0)
        return SDL_TRUE;
    return SDL_FALSE;
}

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 its status.

Returns: 0 if it isn't playing, 1 if it is playing or -1 on error.

See Also: SDL_HapticRunEffect; SDL_HapticStopEffect

Definition at line 606 of file SDL_haptic.c.

References SDL_HAPTIC_STATUS, SDL_SetError, SDL_SYS_HapticGetEffectStatus(), ValidEffect(), and ValidHaptic().

{
    if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
        return -1;
    }
    if ((haptic->supported & SDL_HAPTIC_STATUS) == 0) {
        return SDL_SetError("Haptic: Device does not support status queries.");
    }
    return SDL_SYS_HapticGetEffectStatus(haptic, &haptic->effects[effect]);
}

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

Definition at line 200 of file SDL_haptic.c.

References ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    return haptic->index;
}

int SDL_HapticInit ( void )

Definition at line 35 of file SDL_haptic.c.

References SDL_SYS_HapticInit().

Referenced by SDL_InitSubSystem().

{
    int status;
    status = SDL_SYS_HapticInit();
    if (status >= 0) {
        status = 0;
    }
    return status;
}

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 its name.

Returns: Name of the device or NULL on error.

See Also: SDL_NumHaptics

Definition at line 93 of file SDL_haptic.c.

References NULL, SDL_NumHaptics, SDL_SetError, and SDL_SYS_HapticName().

{
    if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
        SDL_SetError("Haptic: There are %d haptic devices available",
                     SDL_NumHaptics());
        return NULL;
    }
    return SDL_SYS_HapticName(device_index);
}

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 identifier of the effect on success or -1 on error.

See Also: SDL_HapticUpdateEffect; SDL_HapticRunEffect; SDL_HapticDestroyEffect

Definition at line 473 of file SDL_haptic.c.

References i, NULL, SDL_FALSE, SDL_HapticEffectSupported, SDL_memcpy, SDL_SetError, SDL_SYS_HapticNewEffect(), and ValidHaptic().

{
    int i;
    /* Check for device validity. */
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    /* Check to see if effect is supported */
    if (SDL_HapticEffectSupported(haptic, effect) == SDL_FALSE) {
        return SDL_SetError("Haptic: Effect not supported by haptic device.");
    }
    /* See if there's a free slot */
    for (i = 0; i < haptic->neffects; i++) {
        if (haptic->effects[i].hweffect == NULL) {
            /* Now let the backend create the real effect */
            if (SDL_SYS_HapticNewEffect(haptic, &haptic->effects[i], effect)
                != 0) {
                return -1;      /* Backend failed to create effect */
            }
            SDL_memcpy(&haptic->effects[i].effect, effect,
                       sizeof(SDL_HapticEffect));
            return i;
        }
    }
    return SDL_SetError("Haptic: Device has no free space left.");
}

int SDL_HapticNumAxes ( SDL_Haptic * haptic )

Gets the number of haptic axes the device has.

See Also: SDL_HapticDirection

Definition at line 445 of file SDL_haptic.c.

References ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    return haptic->naxes;
}

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 approximation. Always check to see if your created effect was actually created and do not rely solely on SDL_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

Definition at line 403 of file SDL_haptic.c.

References ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    return haptic->neffects;
}

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 completeness.

Parameters

haptic The haptic device to query maximum playing effects.

Returns: The number of effects the haptic device can play at the same time or -1 on error.

See Also: SDL_HapticNumEffects; SDL_HapticQuery

Definition at line 417 of file SDL_haptic.c.

References ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    return haptic->nplaying;
}

SDL_Haptic* SDL_HapticOpen ( int device_index )

Opens a haptic device for use.

The index passed as an argument refers to the N'th haptic device on this system.

When opening a haptic device, its 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

Definition at line 108 of file SDL_haptic.c.

References haptic, NULL, SDL_free, SDL_HAPTIC_AUTOCENTER, SDL_HAPTIC_GAIN, SDL_haptics, SDL_HapticSetAutocenter, SDL_HapticSetGain, SDL_malloc, SDL_memset, SDL_NumHaptics, SDL_OutOfMemory, SDL_SetError, and SDL_SYS_HapticOpen().

{
    SDL_Haptic *haptic;
    SDL_Haptic *hapticlist;
    if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
        SDL_SetError("Haptic: There are %d haptic devices available",
                     SDL_NumHaptics());
        return NULL;
    }
    hapticlist = SDL_haptics;
    /* If the haptic is already open, return it
    * TODO: Should we create haptic instance IDs like the Joystick API?
    */
    while ( hapticlist )
    {
        if (device_index == hapticlist->index) {
            haptic = hapticlist;
            ++haptic->ref_count;
            return haptic;
        }
        hapticlist = hapticlist->next;
    }
    /* Create the haptic device */
    haptic = (SDL_Haptic *) SDL_malloc((sizeof *haptic));
    if (haptic == NULL) {
        SDL_OutOfMemory();
        return NULL;
    }
    /* Initialize the haptic device */
    SDL_memset(haptic, 0, (sizeof *haptic));
    haptic->rumble_id = -1;
    haptic->index = device_index;
    if (SDL_SYS_HapticOpen(haptic) < 0) {
        SDL_free(haptic);
        return NULL;
    }
    /* Add haptic to list */
    ++haptic->ref_count;
    /* Link the haptic in the list */
    haptic->next = SDL_haptics;
    SDL_haptics = haptic;
    /* Disable autocenter and set gain to max. */
    if (haptic->supported & SDL_HAPTIC_GAIN)
        SDL_HapticSetGain(haptic, 100);
    if (haptic->supported & SDL_HAPTIC_AUTOCENTER)
        SDL_HapticSetAutocenter(haptic, 0);
    return haptic;
}

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

Definition at line 169 of file SDL_haptic.c.

References SDL_haptics, SDL_NumHaptics, and SDL_SetError.

{
    int opened;
    SDL_Haptic *hapticlist;
    /* Make sure it's valid. */
    if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
        SDL_SetError("Haptic: There are %d haptic devices available",
                     SDL_NumHaptics());
        return 0;
    }
    opened = 0;
    hapticlist = SDL_haptics;
    /* TODO Should this use an instance ID? */
    while ( hapticlist )
    {
        if (hapticlist->index == (Uint8) device_index) {
            opened = 1;
            break;
        }
        hapticlist = hapticlist->next;
    }
    return opened;
}

SDL_Haptic* SDL_HapticOpenFromJoystick ( SDL_Joystick * joystick )

Opens a haptic device for use from a joystick device.

You must still close the haptic device separately. It will not be closed with 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

Definition at line 269 of file SDL_haptic.c.

References haptic, NULL, SDL_free, SDL_haptics, SDL_malloc, SDL_memset, SDL_NumHaptics, SDL_OutOfMemory, SDL_PrivateJoystickValid(), SDL_SetError, SDL_SYS_HapticOpenFromJoystick(), SDL_SYS_JoystickIsHaptic(), and SDL_SYS_JoystickSameHaptic().

{
    SDL_Haptic *haptic;
    SDL_Haptic *hapticlist;
    /* Make sure there is room. */
    if (SDL_NumHaptics() <= 0) {
        SDL_SetError("Haptic: There are %d haptic devices available",
                     SDL_NumHaptics());
        return NULL;
    }
    /* Must be a valid joystick */
    if (!SDL_PrivateJoystickValid(joystick)) {
        SDL_SetError("Haptic: Joystick isn't valid.");
        return NULL;
    }
    /* Joystick must be haptic */
    if (SDL_SYS_JoystickIsHaptic(joystick) <= 0) {
        SDL_SetError("Haptic: Joystick isn't a haptic device.");
        return NULL;
    }
    hapticlist = SDL_haptics;
    /* Check to see if joystick's haptic is already open */
    while ( hapticlist )
    {
        if (SDL_SYS_JoystickSameHaptic(hapticlist, joystick)) {
            haptic = hapticlist;
            ++haptic->ref_count;
            return haptic;
        }
        hapticlist = hapticlist->next;
    }
    /* Create the haptic device */
    haptic = (SDL_Haptic *) SDL_malloc((sizeof *haptic));
    if (haptic == NULL) {
        SDL_OutOfMemory();
        return NULL;
    }
    /* Initialize the haptic device */
    SDL_memset(haptic, 0, sizeof(SDL_Haptic));
    haptic->rumble_id = -1;
    if (SDL_SYS_HapticOpenFromJoystick(haptic, joystick) < 0) {
        SDL_SetError("Haptic: SDL_SYS_HapticOpenFromJoystick failed.");
        SDL_free(haptic);
        return NULL;
    }
    /* Add haptic to list */
    ++haptic->ref_count;
    /* Link the haptic in the list */
    haptic->next = SDL_haptics;
    SDL_haptics = haptic;
    return haptic;
}

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

Definition at line 226 of file SDL_haptic.c.

References NULL, SDL_HapticOpen, SDL_SetError, and SDL_SYS_HapticMouse().

{
    int device_index;
    device_index = SDL_SYS_HapticMouse();
    if (device_index < 0) {
        SDL_SetError("Haptic: Mouse isn't a haptic device.");
        return NULL;
    }
    return SDL_HapticOpen(device_index);
}

int 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

Definition at line 693 of file SDL_haptic.c.

References SDL_HAPTIC_PAUSE, SDL_SetError, SDL_SYS_HapticPause(), and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if ((haptic->supported & SDL_HAPTIC_PAUSE) == 0) {
        return SDL_SetError("Haptic: Device does not support setting pausing.");
    }
    return SDL_SYS_HapticPause(haptic);
}

unsigned int SDL_HapticQuery ( SDL_Haptic * haptic )

Gets the haptic device's supported features in bitwise manner.

Example:

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

Parameters

haptic The haptic device to query.

Returns: Haptic features in bitwise manner (OR'd).

See Also: SDL_HapticNumEffects; SDL_HapticEffectSupported

Definition at line 431 of file SDL_haptic.c.

References ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return 0; /* same as if no effects were supported */
    }
    return haptic->supported;
}

void SDL_HapticQuit ( void )

Definition at line 390 of file SDL_haptic.c.

References SDL_HapticClose, SDL_haptics, and SDL_SYS_HapticQuit().

Referenced by SDL_QuitSubSystem().

{
    while (SDL_haptics) {
        SDL_HapticClose(SDL_haptics);
    }
    SDL_SYS_HapticQuit();
}

int SDL_HapticRumbleInit ( SDL_Haptic * haptic )

Initializes the haptic device for simple rumble playback.

Parameters

haptic Haptic device to initialize for simple rumble playback.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticOpen; SDL_HapticRumbleSupported; SDL_HapticRumblePlay; SDL_HapticRumbleStop

Definition at line 754 of file SDL_haptic.c.

References SDL_HapticPeriodic::attack_length, SDL_HapticPeriodic::direction, SDL_HapticPeriodic::fade_length, SDL_HapticLeftRight::large_magnitude, SDL_HapticEffect::leftright, SDL_HapticPeriodic::length, SDL_HapticLeftRight::length, SDL_HapticPeriodic::magnitude, SDL_HapticPeriodic::period, SDL_HapticEffect::periodic, SDL_HAPTIC_CARTESIAN, SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, SDL_HapticNewEffect, SDL_SetError, SDL_zerop, SDL_HapticLeftRight::small_magnitude, SDL_HapticDirection::type, SDL_HapticEffect::type, and ValidHaptic().

{
    SDL_HapticEffect *efx = &haptic->rumble_effect;
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    /* Already allocated. */
    if (haptic->rumble_id >= 0) {
        return 0;
    }
    SDL_zerop(efx);
    if (haptic->supported & SDL_HAPTIC_SINE) {
        efx->type = SDL_HAPTIC_SINE;
        efx->periodic.direction.type = SDL_HAPTIC_CARTESIAN;
        efx->periodic.period = 1000;
        efx->periodic.magnitude = 0x4000;
        efx->periodic.length = 5000;
        efx->periodic.attack_length = 0;
        efx->periodic.fade_length = 0;
    } else if (haptic->supported & SDL_HAPTIC_LEFTRIGHT) {  /* XInput? */
        efx->type = SDL_HAPTIC_LEFTRIGHT;
        efx->leftright.length = 5000;
        efx->leftright.large_magnitude = 0x4000;
        efx->leftright.small_magnitude = 0x4000;
    } else {
        return SDL_SetError("Device doesn't support rumble");
    }
    haptic->rumble_id = SDL_HapticNewEffect(haptic, &haptic->rumble_effect);
    if (haptic->rumble_id >= 0) {
        return 0;
    }
    return -1;
}

int SDL_HapticRumblePlay	(	SDL_Haptic *	haptic,
		float	strength,
		Uint32	length
	)

Runs simple rumble on a haptic device.

Parameters

haptic	Haptic device to play rumble effect on.
strength	Strength of the rumble to play as a 0-1 float value.
length	Length of the rumble to play in milliseconds.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticRumbleSupported; SDL_HapticRumbleInit; SDL_HapticRumbleStop

Definition at line 796 of file SDL_haptic.c.

References SDL_HapticLeftRight::large_magnitude, SDL_HapticEffect::leftright, SDL_HapticPeriodic::length, SDL_HapticLeftRight::length, SDL_HapticPeriodic::magnitude, SDL_HapticEffect::periodic, SDL_assert, SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, SDL_HapticRunEffect, SDL_HapticUpdateEffect, SDL_SetError, SDL_HapticLeftRight::small_magnitude, SDL_HapticEffect::type, and ValidHaptic().

{
    SDL_HapticEffect *efx;
    Sint16 magnitude;
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if (haptic->rumble_id < 0) {
        return SDL_SetError("Haptic: Rumble effect not initialized on haptic device");
    }
    /* Clamp strength. */
    if (strength > 1.0f) {
        strength = 1.0f;
    } else if (strength < 0.0f) {
        strength = 0.0f;
    }
    magnitude = (Sint16)(32767.0f*strength);
    efx = &haptic->rumble_effect;
    if (efx->type == SDL_HAPTIC_SINE) {
        efx->periodic.magnitude = magnitude;
        efx->periodic.length = length;
    } else if (efx->type == SDL_HAPTIC_LEFTRIGHT) {
        efx->leftright.small_magnitude = efx->leftright.large_magnitude = magnitude;
        efx->leftright.length = length;
    } else {
        SDL_assert(0 && "This should have been caught elsewhere");
    }
    if (SDL_HapticUpdateEffect(haptic, haptic->rumble_id, &haptic->rumble_effect) < 0) {
        return -1;
    }
    return SDL_HapticRunEffect(haptic, haptic->rumble_id, 1);
}

int SDL_HapticRumbleStop ( SDL_Haptic * haptic )

Stops the simple rumble on a haptic device.

Parameters

haptic Haptic to stop the rumble on.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticRumbleSupported; SDL_HapticRumbleInit; SDL_HapticRumblePlay

Definition at line 839 of file SDL_haptic.c.

References SDL_HapticStopEffect, SDL_SetError, and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if (haptic->rumble_id < 0) {
        return SDL_SetError("Haptic: Rumble effect not initialized on haptic device");
    }
    return SDL_HapticStopEffect(haptic, haptic->rumble_id);
}

int SDL_HapticRumbleSupported ( SDL_Haptic * haptic )

Checks to see if rumble is supported on a haptic device.

Parameters

haptic Haptic device to check to see if it supports rumble.

Returns: SDL_TRUE if effect is supported, SDL_FALSE if it isn't or -1 on error.

See Also: SDL_HapticRumbleInit; SDL_HapticRumblePlay; SDL_HapticRumbleStop

Definition at line 740 of file SDL_haptic.c.

References SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    /* Most things can use SINE, but XInput only has LEFTRIGHT. */
    return ((haptic->supported & (SDL_HAPTIC_SINE|SDL_HAPTIC_LEFTRIGHT)) != 0);
}

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

Runs the haptic effect on its associated 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

Definition at line 551 of file SDL_haptic.c.

References SDL_SYS_HapticRunEffect(), ValidEffect(), and ValidHaptic().

{
    if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
        return -1;
    }
    /* Run the effect */
    if (SDL_SYS_HapticRunEffect(haptic, &haptic->effects[effect], iterations)
        < 0) {
        return -1;
    }
    return 0;
}

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

Definition at line 668 of file SDL_haptic.c.

References SDL_HAPTIC_AUTOCENTER, SDL_SetError, SDL_SYS_HapticSetAutocenter(), and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if ((haptic->supported & SDL_HAPTIC_AUTOCENTER) == 0) {
        return SDL_SetError("Haptic: Device does not support setting autocenter.");
    }
    if ((autocenter < 0) || (autocenter > 100)) {
        return SDL_SetError("Haptic: Autocenter must be between 0 and 100.");
    }
    if (SDL_SYS_HapticSetAutocenter(haptic, autocenter) < 0) {
        return -1;
    }
    return 0;
}

int SDL_HapticSetGain	(	SDL_Haptic *	haptic,
		int	gain
	)

Sets the global gain of the device.

Device must support the SDL_HAPTIC_GAIN feature.

The user may specify the maximum 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

Definition at line 623 of file SDL_haptic.c.

References NULL, SDL_atoi, SDL_getenv, SDL_HAPTIC_GAIN, SDL_SetError, SDL_SYS_HapticSetGain(), and ValidHaptic().

{
    const char *env;
    int real_gain, max_gain;
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if ((haptic->supported & SDL_HAPTIC_GAIN) == 0) {
        return SDL_SetError("Haptic: Device does not support setting gain.");
    }
    if ((gain < 0) || (gain > 100)) {
        return SDL_SetError("Haptic: Gain must be between 0 and 100.");
    }
    /* We use the envvar to get the maximum gain. */
    env = SDL_getenv("SDL_HAPTIC_GAIN_MAX");
    if (env != NULL) {
        max_gain = SDL_atoi(env);
        /* Check for sanity. */
        if (max_gain < 0)
            max_gain = 0;
        else if (max_gain > 100)
            max_gain = 100;
        /* We'll scale it linearly with SDL_HAPTIC_GAIN_MAX */
        real_gain = (gain * max_gain) / 100;
    } else {
        real_gain = gain;
    }
    if (SDL_SYS_HapticSetGain(haptic, real_gain) < 0) {
        return -1;
    }
    return 0;
}

int 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.

Definition at line 727 of file SDL_haptic.c.

References SDL_SYS_HapticStopAll(), and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    return SDL_SYS_HapticStopAll(haptic);
}

int SDL_HapticStopEffect	(	SDL_Haptic *	haptic,
		int	effect
	)

Stops the haptic effect on its associated 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

Definition at line 570 of file SDL_haptic.c.

References SDL_SYS_HapticStopEffect(), ValidEffect(), and ValidHaptic().

{
    if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
        return -1;
    }
    /* Stop the effect */
    if (SDL_SYS_HapticStopEffect(haptic, &haptic->effects[effect]) < 0) {
        return -1;
    }
    return 0;
}

int SDL_HapticUnpause ( SDL_Haptic * haptic )

Unpauses a haptic device.

Call to unpause after SDL_HapticPause().

Parameters

haptic Haptic device to unpause.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticPause

Definition at line 710 of file SDL_haptic.c.

References SDL_HAPTIC_PAUSE, SDL_SYS_HapticUnpause(), and ValidHaptic().

{
    if (!ValidHaptic(haptic)) {
        return -1;
    }
    if ((haptic->supported & SDL_HAPTIC_PAUSE) == 0) {
        return 0;               /* Not going to be paused, so we pretend it's unpaused. */
    }
    return SDL_SYS_HapticUnpause(haptic);
}

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

Updates the properties of an effect.

Can be used dynamically, although behavior 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 SDL_HapticUpdateEffect().

Parameters

haptic	Haptic device that has the effect.
effect	Identifier of the effect to update.
data	New effect properties to use.

Returns: 0 on success or -1 on error.

See Also: SDL_HapticNewEffect; SDL_HapticRunEffect; SDL_HapticDestroyEffect

Definition at line 523 of file SDL_haptic.c.

References SDL_memcpy, SDL_SetError, SDL_SYS_HapticUpdateEffect(), SDL_HapticEffect::type, ValidEffect(), and ValidHaptic().

{
    if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
        return -1;
    }
    /* Can't change type dynamically. */
    if (data->type != haptic->effects[effect].effect.type) {
        return SDL_SetError("Haptic: Updating effect type is illegal.");
    }
    /* Updates the effect */
    if (SDL_SYS_HapticUpdateEffect(haptic, &haptic->effects[effect], data) <
        0) {
        return -1;
    }
    SDL_memcpy(&haptic->effects[effect].effect, data,
               sizeof(SDL_HapticEffect));
    return 0;
}

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 occurred.

See Also: SDL_HapticOpenFromJoystick

Definition at line 245 of file SDL_haptic.c.

References SDL_FALSE, SDL_PrivateJoystickValid(), SDL_SYS_JoystickIsHaptic(), and SDL_TRUE.

{
    int ret;
    /* Must be a valid joystick */
    if (!SDL_PrivateJoystickValid(joystick)) {
        return -1;
    }
    ret = SDL_SYS_JoystickIsHaptic(joystick);
    if (ret > 0)
        return SDL_TRUE;
    else if (ret == 0)
        return SDL_FALSE;
    else
        return -1;
}

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

Definition at line 214 of file SDL_haptic.c.

References SDL_FALSE, SDL_SYS_HapticMouse(), and SDL_TRUE.

{
    if (SDL_SYS_HapticMouse() < 0)
        return SDL_FALSE;
    return SDL_TRUE;
}

int SDL_NumHaptics ( void )

Count the number of haptic devices attached to the system.

Returns: Number of haptic devices detected on the system.

Definition at line 83 of file SDL_haptic.c.

References SDL_SYS_NumHaptics().

{
    return SDL_SYS_NumHaptics();
}

static int ValidEffect	(	SDL_Haptic *	haptic,
		int	effect
	)

static

Definition at line 510 of file SDL_haptic.c.

References SDL_SetError.

Referenced by SDL_HapticDestroyEffect(), SDL_HapticGetEffectStatus(), SDL_HapticRunEffect(), SDL_HapticStopEffect(), and SDL_HapticUpdateEffect().

{
    if ((effect < 0) || (effect >= haptic->neffects)) {
        SDL_SetError("Haptic: Invalid effect identifier.");
        return 0;
    }
    return 1;
}

static int ValidHaptic ( SDL_Haptic * haptic )

static

Definition at line 52 of file SDL_haptic.c.

References NULL, SDL_haptics, and SDL_SetError.

Referenced by SDL_HapticClose(), SDL_HapticDestroyEffect(), SDL_HapticEffectSupported(), SDL_HapticGetEffectStatus(), SDL_HapticIndex(), SDL_HapticNewEffect(), SDL_HapticNumAxes(), SDL_HapticNumEffects(), SDL_HapticNumEffectsPlaying(), SDL_HapticPause(), SDL_HapticQuery(), SDL_HapticRumbleInit(), SDL_HapticRumblePlay(), SDL_HapticRumbleStop(), SDL_HapticRumbleSupported(), SDL_HapticRunEffect(), SDL_HapticSetAutocenter(), SDL_HapticSetGain(), SDL_HapticStopAll(), SDL_HapticStopEffect(), SDL_HapticUnpause(), and SDL_HapticUpdateEffect().

{
    int valid;
    SDL_Haptic *hapticlist;
    valid = 0;
    if (haptic != NULL) {
        hapticlist = SDL_haptics;
        while ( hapticlist )
        {
            if (hapticlist == haptic) {
                valid = 1;
                break;
            }
            hapticlist = hapticlist->next;
        }
    }
    /* Create the error here. */
    if (valid == 0) {
        SDL_SetError("Haptic: Invalid haptic device identifier");
    }
    return valid;
}

Variable Documentation

SDL_Haptic* SDL_haptics = NULL

Definition at line 29 of file SDL_haptic.c.

Referenced by SDL_HapticClose(), SDL_HapticOpen(), SDL_HapticOpened(), SDL_HapticOpenFromJoystick(), SDL_HapticQuit(), and ValidHaptic().

Functions

Variables

Function Documentation

Variable Documentation