SDL  2.0
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"
+ Include dependency graph for SDL_haptic.h:
+ This graph shows which files directly or indirectly include this file:

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_HapticLeftRight
 A structure containing a template for a Left/Right 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...
 

Macros

#define SDL_HAPTIC_GAIN   (1u<<12)
 Device can set global gain. More...
 
#define SDL_HAPTIC_AUTOCENTER   (1u<<13)
 Device can set autocenter. More...
 
#define SDL_HAPTIC_STATUS   (1u<<14)
 Device can be queried for effect status. More...
 
#define SDL_HAPTIC_PAUSE   (1u<<15)
 Device can be paused. More...
 
#define SDL_HAPTIC_INFINITY   4294967295U
 Used to play a device an infinite number of times. More...
 
Haptic effects
#define SDL_HAPTIC_CONSTANT   (1u<<0)
 Constant effect supported. More...
 
#define SDL_HAPTIC_SINE   (1u<<1)
 Sine wave effect supported. More...
 
#define SDL_HAPTIC_LEFTRIGHT   (1u<<2)
 Left/Right effect supported. More...
 
#define SDL_HAPTIC_TRIANGLE   (1u<<3)
 Triangle wave effect supported. More...
 
#define SDL_HAPTIC_SAWTOOTHUP   (1u<<4)
 Sawtoothup wave effect supported. More...
 
#define SDL_HAPTIC_SAWTOOTHDOWN   (1u<<5)
 Sawtoothdown wave effect supported. More...
 
#define SDL_HAPTIC_RAMP   (1u<<6)
 Ramp effect supported. More...
 
#define SDL_HAPTIC_SPRING   (1u<<7)
 Spring effect supported - uses axes position. More...
 
#define SDL_HAPTIC_DAMPER   (1u<<8)
 Damper effect supported - uses axes velocity. More...
 
#define SDL_HAPTIC_INERTIA   (1u<<9)
 Inertia effect supported - uses axes acceleration. More...
 
#define SDL_HAPTIC_FRICTION   (1u<<10)
 Friction effect supported - uses axes movement. More...
 
#define SDL_HAPTIC_CUSTOM   (1u<<11)
 Custom effect is supported. More...
 
Direction encodings
#define SDL_HAPTIC_POLAR   0
 Uses polar coordinates for the direction. More...
 
#define SDL_HAPTIC_CARTESIAN   1
 Uses cartesian coordinates for the direction. More...
 
#define SDL_HAPTIC_SPHERICAL   2
 Uses spherical coordinates for the direction. More...
 

Functions

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

Detailed Description

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

The basic usage is as follows:

Simple rumble example:
SDL_Haptic *haptic;
// Open the device
haptic = SDL_HapticOpen( 0 );
if (haptic == NULL)
return -1;
// Initialize simple rumble
if (SDL_HapticRumbleInit( haptic ) != 0)
return -1;
// Play effect at 50% strength for 2 seconds
if (SDL_HapticRumblePlay( haptic, 0.5, 2000 ) != 0)
return -1;
SDL_Delay( 2000 );
// Clean up
SDL_HapticClose( haptic );
Complete example:
int test_haptic( SDL_Joystick * joystick ) {
SDL_Haptic *haptic;
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.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
}

Definition in file SDL_haptic.h.

Macro Definition Documentation

◆ SDL_HAPTIC_AUTOCENTER

#define SDL_HAPTIC_AUTOCENTER   (1u<<13)

Device can set autocenter.

Device supports setting autocenter.

See also
SDL_HapticSetAutocenter

Definition at line 280 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), SDL_HapticOpen(), and SDL_HapticSetAutocenter().

◆ SDL_HAPTIC_CARTESIAN

#define SDL_HAPTIC_CARTESIAN   1

Uses cartesian coordinates for the direction.

See also
SDL_HapticDirection

Definition at line 317 of file SDL_haptic.h.

Referenced by main().

◆ SDL_HAPTIC_CONSTANT

#define SDL_HAPTIC_CONSTANT   (1u<<0)

Constant effect supported.

Constant haptic effect.

See also
SDL_HapticCondition

Definition at line 152 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_CUSTOM

#define SDL_HAPTIC_CUSTOM   (1u<<11)

Custom effect is supported.

User defined custom haptic effect.

Definition at line 258 of file SDL_haptic.h.

Referenced by HapticPrintSupported().

◆ SDL_HAPTIC_DAMPER

#define SDL_HAPTIC_DAMPER   (1u<<8)

Damper effect supported - uses axes velocity.

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

See also
SDL_HapticCondition

Definition at line 231 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_FRICTION

#define SDL_HAPTIC_FRICTION   (1u<<10)

Friction effect supported - uses axes movement.

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

See also
SDL_HapticCondition

Definition at line 251 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_GAIN

#define SDL_HAPTIC_GAIN   (1u<<12)

Device can set global gain.

Device supports setting the global gain.

See also
SDL_HapticSetGain

Definition at line 271 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), SDL_HapticOpen(), and SDL_HapticSetGain().

◆ SDL_HAPTIC_INERTIA

#define SDL_HAPTIC_INERTIA   (1u<<9)

Inertia effect supported - uses axes acceleration.

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

See also
SDL_HapticCondition

Definition at line 241 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_INFINITY

#define SDL_HAPTIC_INFINITY   4294967295U

Used to play a device an infinite number of times.

See also
SDL_HapticRunEffect

Definition at line 339 of file SDL_haptic.h.

◆ SDL_HAPTIC_LEFTRIGHT

#define SDL_HAPTIC_LEFTRIGHT   (1u<<2)

Left/Right effect supported.

Haptic effect for direct control over high/low frequency motors.

See also
SDL_HapticLeftRight
Warning
this value was SDL_HAPTIC_SQUARE right before 2.0.0 shipped. Sorry, we ran out of bits, and this is important for XInput devices.

Definition at line 172 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), main(), SDL_HapticRumbleInit(), SDL_HapticRumblePlay(), and SDL_HapticRumbleSupported().

◆ SDL_HAPTIC_PAUSE

#define SDL_HAPTIC_PAUSE   (1u<<15)

Device can be paused.

See also
SDL_HapticPause
SDL_HapticUnpause

Definition at line 297 of file SDL_haptic.h.

Referenced by SDL_HapticPause(), and SDL_HapticUnpause().

◆ SDL_HAPTIC_POLAR

#define SDL_HAPTIC_POLAR   0

Uses polar coordinates for the direction.

See also
SDL_HapticDirection

Definition at line 310 of file SDL_haptic.h.

Referenced by main().

◆ SDL_HAPTIC_RAMP

#define SDL_HAPTIC_RAMP   (1u<<6)

Ramp effect supported.

Ramp haptic effect.

See also
SDL_HapticRamp

Definition at line 211 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_SAWTOOTHDOWN

#define SDL_HAPTIC_SAWTOOTHDOWN   (1u<<5)

Sawtoothdown wave effect supported.

Periodic haptic effect that simulates saw tooth down waves.

See also
SDL_HapticPeriodic

Definition at line 202 of file SDL_haptic.h.

Referenced by HapticPrintSupported().

◆ SDL_HAPTIC_SAWTOOTHUP

#define SDL_HAPTIC_SAWTOOTHUP   (1u<<4)

Sawtoothup wave effect supported.

Periodic haptic effect that simulates saw tooth up waves.

See also
SDL_HapticPeriodic

Definition at line 193 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_SINE

#define SDL_HAPTIC_SINE   (1u<<1)

Sine wave effect supported.

Periodic haptic effect that simulates sine waves.

See also
SDL_HapticPeriodic

Definition at line 161 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), main(), SDL_HapticRumbleInit(), SDL_HapticRumblePlay(), and SDL_HapticRumbleSupported().

◆ SDL_HAPTIC_SPHERICAL

#define SDL_HAPTIC_SPHERICAL   2

Uses spherical coordinates for the direction.

See also
SDL_HapticDirection

Definition at line 324 of file SDL_haptic.h.

◆ SDL_HAPTIC_SPRING

#define SDL_HAPTIC_SPRING   (1u<<7)

Spring effect supported - uses axes position.

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

See also
SDL_HapticCondition

Definition at line 221 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and main().

◆ SDL_HAPTIC_STATUS

#define SDL_HAPTIC_STATUS   (1u<<14)

Device can be queried for effect status.

Device can be queried for effect status.

See also
SDL_HapticGetEffectStatus

Definition at line 289 of file SDL_haptic.h.

Referenced by HapticPrintSupported(), and SDL_HapticGetEffectStatus().

◆ SDL_HAPTIC_TRIANGLE

#define SDL_HAPTIC_TRIANGLE   (1u<<3)

Triangle wave effect supported.

Periodic haptic effect that simulates triangular waves.

See also
SDL_HapticPeriodic

Definition at line 184 of file SDL_haptic.h.

Referenced by HapticPrintSupported().

Function Documentation

◆ SDL_HapticClose()

void SDL_HapticClose ( SDL_Haptic *  haptic)

Closes a Haptic device previously opened with SDL_HapticOpen().

Parameters
hapticHaptic device to close.

Definition at line 334 of file SDL_haptic.c.

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

335 {
336  int i;
337  SDL_Haptic *hapticlist;
338  SDL_Haptic *hapticlistprev;
339 
340  /* Must be valid */
341  if (!ValidHaptic(haptic)) {
342  return;
343  }
344 
345  /* Check if it's still in use */
346  if (--haptic->ref_count > 0) {
347  return;
348  }
349 
350  /* Close it, properly removing effects if needed */
351  for (i = 0; i < haptic->neffects; i++) {
352  if (haptic->effects[i].hweffect != NULL) {
354  }
355  }
357 
358  /* Remove from the list */
359  hapticlist = SDL_haptics;
360  hapticlistprev = NULL;
361  while ( hapticlist )
362  {
363  if (haptic == hapticlist)
364  {
365  if ( hapticlistprev )
366  {
367  /* unlink this entry */
368  hapticlistprev->next = hapticlist->next;
369  }
370  else
371  {
372  SDL_haptics = haptic->next;
373  }
374 
375  break;
376  }
377  hapticlistprev = hapticlist;
378  hapticlist = hapticlist->next;
379  }
380 
381  /* Free */
382  SDL_free(haptic);
383 }
void SDL_free(void *mem)
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
return Display return Display Bool Bool int int int return Display XEvent Bool(*) XPointer return Display return Display Drawable _Xconst char unsigned int unsigned int return Display Pixmap Pixmap XColor XColor unsigned int unsigned int return Display _Xconst char char int char return Display Visual unsigned int int int char unsigned int unsigned int in i)
Definition: SDL_x11sym.h:50
#define NULL
Definition: begin_code.h:143
static SDL_Haptic * haptic
Definition: testhaptic.c:25
void SDL_SYS_HapticClose(SDL_Haptic *haptic)
void SDL_HapticDestroyEffect(SDL_Haptic *haptic, int effect)
Destroys a haptic effect on the device.
Definition: SDL_haptic.c:585
SDL_Haptic * SDL_haptics
Definition: SDL_haptic.c:28

◆ SDL_HapticDestroyEffect()

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
hapticDevice to destroy the effect on.
effectIdentifier of the effect to destroy.
See also
SDL_HapticNewEffect

Definition at line 585 of file SDL_haptic.c.

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

Referenced by SDL_HapticClose().

586 {
587  if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
588  return;
589  }
590 
591  /* Not allocated */
592  if (haptic->effects[effect].hweffect == NULL) {
593  return;
594  }
595 
596  SDL_SYS_HapticDestroyEffect(haptic, &haptic->effects[effect]);
597 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
void SDL_SYS_HapticDestroyEffect(SDL_Haptic *haptic, struct haptic_effect *effect)
#define NULL
Definition: begin_code.h:143
static SDL_Haptic * haptic
Definition: testhaptic.c:25
static int ValidEffect(SDL_Haptic *haptic, int effect)
Definition: SDL_haptic.c:507

◆ SDL_HapticEffectSupported()

int SDL_HapticEffectSupported ( SDL_Haptic *  haptic,
SDL_HapticEffect effect 
)

Checks to see if effect is supported by haptic.

Parameters
hapticHaptic device to check on.
effectEffect 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 455 of file SDL_haptic.c.

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

Referenced by SDL_HapticNewEffect().

456 {
457  if (!ValidHaptic(haptic)) {
458  return -1;
459  }
460 
461  if ((haptic->supported & effect->type) != 0)
462  return SDL_TRUE;
463  return SDL_FALSE;
464 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticGetEffectStatus()

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
hapticHaptic device to query the effect status on.
effectIdentifier 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 603 of file SDL_haptic.c.

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

604 {
605  if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
606  return -1;
607  }
608 
609  if ((haptic->supported & SDL_HAPTIC_STATUS) == 0) {
610  return SDL_SetError("Haptic: Device does not support status queries.");
611  }
612 
613  return SDL_SYS_HapticGetEffectStatus(haptic, &haptic->effects[effect]);
614 }
int SDL_SYS_HapticGetEffectStatus(SDL_Haptic *haptic, struct haptic_effect *effect)
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
#define SDL_HAPTIC_STATUS
Device can be queried for effect status.
Definition: SDL_haptic.h:289
static int ValidEffect(SDL_Haptic *haptic, int effect)
Definition: SDL_haptic.c:507

◆ SDL_HapticIndex()

int SDL_HapticIndex ( SDL_Haptic *  haptic)

Gets the index of a haptic device.

Parameters
hapticHaptic 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().

201 {
202  if (!ValidHaptic(haptic)) {
203  return -1;
204  }
205 
206  return haptic->index;
207 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticName()

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_indexIndex 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().

94 {
95  if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
96  SDL_SetError("Haptic: There are %d haptic devices available",
97  SDL_NumHaptics());
98  return NULL;
99  }
100  return SDL_SYS_HapticName(device_index);
101 }
const char * SDL_SYS_HapticName(int index)
int SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
Definition: SDL_haptic.c:83
#define NULL
Definition: begin_code.h:143
#define SDL_SetError

◆ SDL_HapticNewEffect()

int SDL_HapticNewEffect ( SDL_Haptic *  haptic,
SDL_HapticEffect effect 
)

Creates a new haptic effect on the device.

Parameters
hapticHaptic device to create the effect on.
effectProperties 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

Definition at line 470 of file SDL_haptic.c.

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

Referenced by SDL_HapticRumbleInit().

471 {
472  int i;
473 
474  /* Check for device validity. */
475  if (!ValidHaptic(haptic)) {
476  return -1;
477  }
478 
479  /* Check to see if effect is supported */
480  if (SDL_HapticEffectSupported(haptic, effect) == SDL_FALSE) {
481  return SDL_SetError("Haptic: Effect not supported by haptic device.");
482  }
483 
484  /* See if there's a free slot */
485  for (i = 0; i < haptic->neffects; i++) {
486  if (haptic->effects[i].hweffect == NULL) {
487 
488  /* Now let the backend create the real effect */
489  if (SDL_SYS_HapticNewEffect(haptic, &haptic->effects[i], effect)
490  != 0) {
491  return -1; /* Backend failed to create effect */
492  }
493 
494  SDL_memcpy(&haptic->effects[i].effect, effect,
495  sizeof(SDL_HapticEffect));
496  return i;
497  }
498  }
499 
500  return SDL_SetError("Haptic: Device has no free space left.");
501 }
#define SDL_memcpy
int SDL_HapticEffectSupported(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Checks to see if effect is supported by haptic.
Definition: SDL_haptic.c:455
The generic template for any haptic effect.
Definition: SDL_haptic.h:785
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
return Display return Display Bool Bool int int int return Display XEvent Bool(*) XPointer return Display return Display Drawable _Xconst char unsigned int unsigned int return Display Pixmap Pixmap XColor XColor unsigned int unsigned int return Display _Xconst char char int char return Display Visual unsigned int int int char unsigned int unsigned int in i)
Definition: SDL_x11sym.h:50
#define NULL
Definition: begin_code.h:143
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
int SDL_SYS_HapticNewEffect(SDL_Haptic *haptic, struct haptic_effect *effect, SDL_HapticEffect *base)

◆ SDL_HapticNumAxes()

int SDL_HapticNumAxes ( SDL_Haptic *  haptic)

Gets the number of haptic axes the device has.

See also
SDL_HapticDirection

Definition at line 442 of file SDL_haptic.c.

References ValidHaptic().

443 {
444  if (!ValidHaptic(haptic)) {
445  return -1;
446  }
447 
448  return haptic->naxes;
449 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticNumEffects()

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
hapticThe 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 400 of file SDL_haptic.c.

References ValidHaptic().

401 {
402  if (!ValidHaptic(haptic)) {
403  return -1;
404  }
405 
406  return haptic->neffects;
407 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticNumEffectsPlaying()

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
hapticThe 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 414 of file SDL_haptic.c.

References ValidHaptic().

415 {
416  if (!ValidHaptic(haptic)) {
417  return -1;
418  }
419 
420  return haptic->nplaying;
421 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticOpen()

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, its gain will be set to maximum and autocenter will be disabled. To modify these values use SDL_HapticSetGain() and SDL_HapticSetAutocenter().

Parameters
device_indexIndex 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().

Referenced by SDL_HapticOpenFromMouse().

109 {
110  SDL_Haptic *haptic;
111  SDL_Haptic *hapticlist;
112 
113  if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
114  SDL_SetError("Haptic: There are %d haptic devices available",
115  SDL_NumHaptics());
116  return NULL;
117  }
118 
119  hapticlist = SDL_haptics;
120  /* If the haptic is already open, return it
121  * TODO: Should we create haptic instance IDs like the Joystick API?
122  */
123  while ( hapticlist )
124  {
125  if (device_index == hapticlist->index) {
126  haptic = hapticlist;
127  ++haptic->ref_count;
128  return haptic;
129  }
130  hapticlist = hapticlist->next;
131  }
132 
133  /* Create the haptic device */
134  haptic = (SDL_Haptic *) SDL_malloc((sizeof *haptic));
135  if (haptic == NULL) {
136  SDL_OutOfMemory();
137  return NULL;
138  }
139 
140  /* Initialize the haptic device */
141  SDL_memset(haptic, 0, (sizeof *haptic));
142  haptic->rumble_id = -1;
143  haptic->index = device_index;
144  if (SDL_SYS_HapticOpen(haptic) < 0) {
145  SDL_free(haptic);
146  return NULL;
147  }
148 
149  /* Add haptic to list */
150  ++haptic->ref_count;
151  /* Link the haptic in the list */
152  haptic->next = SDL_haptics;
154 
155  /* Disable autocenter and set gain to max. */
156  if (haptic->supported & SDL_HAPTIC_GAIN)
157  SDL_HapticSetGain(haptic, 100);
158  if (haptic->supported & SDL_HAPTIC_AUTOCENTER)
159  SDL_HapticSetAutocenter(haptic, 0);
160 
161  return haptic;
162 }
#define SDL_HAPTIC_AUTOCENTER
Device can set autocenter.
Definition: SDL_haptic.h:280
#define SDL_HAPTIC_GAIN
Device can set global gain.
Definition: SDL_haptic.h:271
int SDL_SYS_HapticOpen(SDL_Haptic *haptic)
int SDL_HapticSetGain(SDL_Haptic *haptic, int gain)
Sets the global gain of the device.
Definition: SDL_haptic.c:620
void SDL_free(void *mem)
int SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
Definition: SDL_haptic.c:83
int SDL_HapticSetAutocenter(SDL_Haptic *haptic, int autocenter)
Sets the global autocenter of the device.
Definition: SDL_haptic.c:665
#define NULL
Definition: begin_code.h:143
#define SDL_OutOfMemory()
Definition: SDL_error.h:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
#define SDL_malloc
#define SDL_memset
SDL_Haptic * SDL_haptics
Definition: SDL_haptic.c:28

◆ SDL_HapticOpened()

int SDL_HapticOpened ( int  device_index)

Checks if the haptic device at index has been opened.

Parameters
device_indexIndex 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.

170 {
171  int opened;
172  SDL_Haptic *hapticlist;
173 
174  /* Make sure it's valid. */
175  if ((device_index < 0) || (device_index >= SDL_NumHaptics())) {
176  SDL_SetError("Haptic: There are %d haptic devices available",
177  SDL_NumHaptics());
178  return 0;
179  }
180 
181  opened = 0;
182  hapticlist = SDL_haptics;
183  /* TODO Should this use an instance ID? */
184  while ( hapticlist )
185  {
186  if (hapticlist->index == (Uint8) device_index) {
187  opened = 1;
188  break;
189  }
190  hapticlist = hapticlist->next;
191  }
192  return opened;
193 }
uint8_t Uint8
An unsigned 8-bit integer type.
Definition: SDL_stdinc.h:143
int SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
Definition: SDL_haptic.c:83
#define SDL_SetError
SDL_Haptic * SDL_haptics
Definition: SDL_haptic.c:28

◆ SDL_HapticOpenFromJoystick()

SDL_Haptic* SDL_HapticOpenFromJoystick ( SDL_Joystick *  joystick)

Opens a Haptic device for usage 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
joystickJoystick 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().

270 {
271  SDL_Haptic *haptic;
272  SDL_Haptic *hapticlist;
273 
274  /* Make sure there is room. */
275  if (SDL_NumHaptics() <= 0) {
276  SDL_SetError("Haptic: There are %d haptic devices available",
277  SDL_NumHaptics());
278  return NULL;
279  }
280 
281  /* Must be a valid joystick */
282  if (!SDL_PrivateJoystickValid(joystick)) {
283  SDL_SetError("Haptic: Joystick isn't valid.");
284  return NULL;
285  }
286 
287  /* Joystick must be haptic */
288  if (SDL_SYS_JoystickIsHaptic(joystick) <= 0) {
289  SDL_SetError("Haptic: Joystick isn't a haptic device.");
290  return NULL;
291  }
292 
293  hapticlist = SDL_haptics;
294  /* Check to see if joystick's haptic is already open */
295  while ( hapticlist )
296  {
297  if (SDL_SYS_JoystickSameHaptic(hapticlist, joystick)) {
298  haptic = hapticlist;
299  ++haptic->ref_count;
300  return haptic;
301  }
302  hapticlist = hapticlist->next;
303  }
304 
305  /* Create the haptic device */
306  haptic = (SDL_Haptic *) SDL_malloc((sizeof *haptic));
307  if (haptic == NULL) {
308  SDL_OutOfMemory();
309  return NULL;
310  }
311 
312  /* Initialize the haptic device */
313  SDL_memset(haptic, 0, sizeof(SDL_Haptic));
314  haptic->rumble_id = -1;
315  if (SDL_SYS_HapticOpenFromJoystick(haptic, joystick) < 0) {
316  SDL_free(haptic);
317  return NULL;
318  }
319 
320  /* Add haptic to list */
321  ++haptic->ref_count;
322  /* Link the haptic in the list */
323  haptic->next = SDL_haptics;
325 
326  return haptic;
327 }
int SDL_SYS_HapticOpenFromJoystick(SDL_Haptic *haptic, SDL_Joystick *joystick)
int SDL_PrivateJoystickValid(SDL_Joystick *joystick)
Definition: SDL_joystick.c:200
int SDL_SYS_JoystickSameHaptic(SDL_Haptic *haptic, SDL_Joystick *joystick)
void SDL_free(void *mem)
int SDL_NumHaptics(void)
Count the number of haptic devices attached to the system.
Definition: SDL_haptic.c:83
int SDL_SYS_JoystickIsHaptic(SDL_Joystick *joystick)
#define NULL
Definition: begin_code.h:143
#define SDL_OutOfMemory()
Definition: SDL_error.h:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
#define SDL_malloc
#define SDL_memset
SDL_Haptic * SDL_haptics
Definition: SDL_haptic.c:28

◆ SDL_HapticOpenFromMouse()

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().

227 {
228  int device_index;
229 
230  device_index = SDL_SYS_HapticMouse();
231 
232  if (device_index < 0) {
233  SDL_SetError("Haptic: Mouse isn't a haptic device.");
234  return NULL;
235  }
236 
237  return SDL_HapticOpen(device_index);
238 }
int SDL_SYS_HapticMouse(void)
SDL_Haptic * SDL_HapticOpen(int device_index)
Opens a Haptic device for usage.
Definition: SDL_haptic.c:108
#define NULL
Definition: begin_code.h:143
#define SDL_SetError

◆ SDL_HapticPause()

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
hapticHaptic device to pause.
Returns
0 on success or -1 on error.
See also
SDL_HapticUnpause

Definition at line 690 of file SDL_haptic.c.

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

691 {
692  if (!ValidHaptic(haptic)) {
693  return -1;
694  }
695 
696  if ((haptic->supported & SDL_HAPTIC_PAUSE) == 0) {
697  return SDL_SetError("Haptic: Device does not support setting pausing.");
698  }
699 
700  return SDL_SYS_HapticPause(haptic);
701 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
#define SDL_HAPTIC_PAUSE
Device can be paused.
Definition: SDL_haptic.h:297
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
int SDL_SYS_HapticPause(SDL_Haptic *haptic)

◆ SDL_HapticQuery()

unsigned int SDL_HapticQuery ( SDL_Haptic *  haptic)

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

Example:

printf("We have constant haptic effect!");
}
Parameters
hapticThe haptic device to query.
Returns
Haptic features in bitwise manner (OR'd).
See also
SDL_HapticNumEffects
SDL_HapticEffectSupported

Definition at line 428 of file SDL_haptic.c.

References ValidHaptic().

429 {
430  if (!ValidHaptic(haptic)) {
431  return 0; /* same as if no effects were supported */
432  }
433 
434  return haptic->supported;
435 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticRumbleInit()

int SDL_HapticRumbleInit ( SDL_Haptic *  haptic)

Initializes the haptic device for simple rumble playback.

Parameters
hapticHaptic 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 751 of file SDL_haptic.c.

References SDL_HapticPeriodic::attack_length, 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_LEFTRIGHT, SDL_HAPTIC_SINE, SDL_HapticNewEffect(), SDL_SetError, SDL_zerop, SDL_HapticLeftRight::small_magnitude, SDL_HapticEffect::type, and ValidHaptic().

752 {
753  SDL_HapticEffect *efx = &haptic->rumble_effect;
754 
755  if (!ValidHaptic(haptic)) {
756  return -1;
757  }
758 
759  /* Already allocated. */
760  if (haptic->rumble_id >= 0) {
761  return 0;
762  }
763 
764  SDL_zerop(efx);
765  if (haptic->supported & SDL_HAPTIC_SINE) {
766  efx->type = SDL_HAPTIC_SINE;
767  efx->periodic.period = 1000;
768  efx->periodic.magnitude = 0x4000;
769  efx->periodic.length = 5000;
770  efx->periodic.attack_length = 0;
771  efx->periodic.fade_length = 0;
772  } else if (haptic->supported & SDL_HAPTIC_LEFTRIGHT) { /* XInput? */
773  efx->type = SDL_HAPTIC_LEFTRIGHT;
774  efx->leftright.length = 5000;
775  efx->leftright.large_magnitude = 0x4000;
776  efx->leftright.small_magnitude = 0x4000;
777  } else {
778  return SDL_SetError("Device doesn't support rumble");
779  }
780 
781  haptic->rumble_id = SDL_HapticNewEffect(haptic, &haptic->rumble_effect);
782  if (haptic->rumble_id >= 0) {
783  return 0;
784  }
785  return -1;
786 }
int SDL_HapticNewEffect(SDL_Haptic *haptic, SDL_HapticEffect *effect)
Creates a new haptic effect on the device.
Definition: SDL_haptic.c:470
#define SDL_HAPTIC_SINE
Sine wave effect supported.
Definition: SDL_haptic.h:161
#define SDL_zerop(x)
Definition: SDL_stdinc.h:362
The generic template for any haptic effect.
Definition: SDL_haptic.h:785
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
SDL_HapticLeftRight leftright
Definition: SDL_haptic.h:793
#define SDL_HAPTIC_LEFTRIGHT
Left/Right effect supported.
Definition: SDL_haptic.h:172
SDL_HapticPeriodic periodic
Definition: SDL_haptic.h:790

◆ SDL_HapticRumblePlay()

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

Runs simple rumble on a haptic device.

Parameters
hapticHaptic device to play rumble effect on.
strengthStrength of the rumble to play as a 0-1 float value.
lengthLength 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 792 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().

793 {
794  SDL_HapticEffect *efx;
795  Sint16 magnitude;
796 
797  if (!ValidHaptic(haptic)) {
798  return -1;
799  }
800 
801  if (haptic->rumble_id < 0) {
802  return SDL_SetError("Haptic: Rumble effect not initialized on haptic device");
803  }
804 
805  /* Clamp strength. */
806  if (strength > 1.0f) {
807  strength = 1.0f;
808  } else if (strength < 0.0f) {
809  strength = 0.0f;
810  }
811  magnitude = (Sint16)(32767.0f*strength);
812 
813  efx = &haptic->rumble_effect;
814  if (efx->type == SDL_HAPTIC_SINE) {
815  efx->periodic.magnitude = magnitude;
816  efx->periodic.length = length;
817  } else if (efx->type == SDL_HAPTIC_LEFTRIGHT) {
818  efx->leftright.small_magnitude = efx->leftright.large_magnitude = magnitude;
819  efx->leftright.length = length;
820  } else {
821  SDL_assert(0 && "This should have been caught elsewhere");
822  }
823 
824  if (SDL_HapticUpdateEffect(haptic, haptic->rumble_id, &haptic->rumble_effect) < 0) {
825  return -1;
826  }
827 
828  return SDL_HapticRunEffect(haptic, haptic->rumble_id, 1);
829 }
GLfloat f
#define SDL_HAPTIC_SINE
Sine wave effect supported.
Definition: SDL_haptic.h:161
The generic template for any haptic effect.
Definition: SDL_haptic.h:785
int SDL_HapticRunEffect(SDL_Haptic *haptic, int effect, Uint32 iterations)
Runs the haptic effect on its associated haptic device.
Definition: SDL_haptic.c:548
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
#define SDL_assert(condition)
Definition: SDL_assert.h:167
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
SDL_HapticLeftRight leftright
Definition: SDL_haptic.h:793
int SDL_HapticUpdateEffect(SDL_Haptic *haptic, int effect, SDL_HapticEffect *data)
Updates the properties of an effect.
Definition: SDL_haptic.c:520
GLuint GLsizei GLsizei * length
#define SDL_HAPTIC_LEFTRIGHT
Left/Right effect supported.
Definition: SDL_haptic.h:172
SDL_HapticPeriodic periodic
Definition: SDL_haptic.h:790
int16_t Sint16
A signed 16-bit integer type.
Definition: SDL_stdinc.h:147

◆ SDL_HapticRumbleStop()

int SDL_HapticRumbleStop ( SDL_Haptic *  haptic)

Stops the simple rumble on a haptic device.

Parameters
hapticHaptic to stop the rumble on.
Returns
0 on success or -1 on error.
See also
SDL_HapticRumbleSupported
SDL_HapticRumbleInit
SDL_HapticRumblePlay

Definition at line 835 of file SDL_haptic.c.

References SDL_HapticStopEffect(), SDL_SetError, and ValidHaptic().

836 {
837  if (!ValidHaptic(haptic)) {
838  return -1;
839  }
840 
841  if (haptic->rumble_id < 0) {
842  return SDL_SetError("Haptic: Rumble effect not initialized on haptic device");
843  }
844 
845  return SDL_HapticStopEffect(haptic, haptic->rumble_id);
846 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
int SDL_HapticStopEffect(SDL_Haptic *haptic, int effect)
Stops the haptic effect on its associated haptic device.
Definition: SDL_haptic.c:567

◆ SDL_HapticRumbleSupported()

int SDL_HapticRumbleSupported ( SDL_Haptic *  haptic)

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

Parameters
hapticHaptic 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 737 of file SDL_haptic.c.

References SDL_HAPTIC_LEFTRIGHT, SDL_HAPTIC_SINE, and ValidHaptic().

738 {
739  if (!ValidHaptic(haptic)) {
740  return -1;
741  }
742 
743  /* Most things can use SINE, but XInput only has LEFTRIGHT. */
744  return ((haptic->supported & (SDL_HAPTIC_SINE|SDL_HAPTIC_LEFTRIGHT)) != 0);
745 }
#define SDL_HAPTIC_SINE
Sine wave effect supported.
Definition: SDL_haptic.h:161
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_HAPTIC_LEFTRIGHT
Left/Right effect supported.
Definition: SDL_haptic.h:172

◆ SDL_HapticRunEffect()

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
hapticHaptic device to run the effect on.
effectIdentifier of the haptic effect to run.
iterationsNumber 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 548 of file SDL_haptic.c.

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

Referenced by SDL_HapticRumblePlay().

549 {
550  if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
551  return -1;
552  }
553 
554  /* Run the effect */
555  if (SDL_SYS_HapticRunEffect(haptic, &haptic->effects[effect], iterations)
556  < 0) {
557  return -1;
558  }
559 
560  return 0;
561 }
static int iterations
Definition: testsprite2.c:43
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
static int ValidEffect(SDL_Haptic *haptic, int effect)
Definition: SDL_haptic.c:507
int SDL_SYS_HapticRunEffect(SDL_Haptic *haptic, struct haptic_effect *effect, Uint32 iterations)

◆ SDL_HapticSetAutocenter()

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
hapticHaptic device to set autocentering on.
autocenterValue to set autocenter to, 0 disables autocentering.
Returns
0 on success or -1 on error.
See also
SDL_HapticQuery

Definition at line 665 of file SDL_haptic.c.

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

Referenced by SDL_HapticOpen().

666 {
667  if (!ValidHaptic(haptic)) {
668  return -1;
669  }
670 
671  if ((haptic->supported & SDL_HAPTIC_AUTOCENTER) == 0) {
672  return SDL_SetError("Haptic: Device does not support setting autocenter.");
673  }
674 
675  if ((autocenter < 0) || (autocenter > 100)) {
676  return SDL_SetError("Haptic: Autocenter must be between 0 and 100.");
677  }
678 
679  if (SDL_SYS_HapticSetAutocenter(haptic, autocenter) < 0) {
680  return -1;
681  }
682 
683  return 0;
684 }
#define SDL_HAPTIC_AUTOCENTER
Device can set autocenter.
Definition: SDL_haptic.h:280
int SDL_SYS_HapticSetAutocenter(SDL_Haptic *haptic, int autocenter)
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError

◆ SDL_HapticSetGain()

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
hapticHaptic device to set the gain on.
gainValue 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 620 of file SDL_haptic.c.

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

Referenced by SDL_HapticOpen().

621 {
622  const char *env;
623  int real_gain, max_gain;
624 
625  if (!ValidHaptic(haptic)) {
626  return -1;
627  }
628 
629  if ((haptic->supported & SDL_HAPTIC_GAIN) == 0) {
630  return SDL_SetError("Haptic: Device does not support setting gain.");
631  }
632 
633  if ((gain < 0) || (gain > 100)) {
634  return SDL_SetError("Haptic: Gain must be between 0 and 100.");
635  }
636 
637  /* We use the envvar to get the maximum gain. */
638  env = SDL_getenv("SDL_HAPTIC_GAIN_MAX");
639  if (env != NULL) {
640  max_gain = SDL_atoi(env);
641 
642  /* Check for sanity. */
643  if (max_gain < 0)
644  max_gain = 0;
645  else if (max_gain > 100)
646  max_gain = 100;
647 
648  /* We'll scale it linearly with SDL_HAPTIC_GAIN_MAX */
649  real_gain = (gain * max_gain) / 100;
650  } else {
651  real_gain = gain;
652  }
653 
654  if (SDL_SYS_HapticSetGain(haptic, real_gain) < 0) {
655  return -1;
656  }
657 
658  return 0;
659 }
#define SDL_HAPTIC_GAIN
Device can set global gain.
Definition: SDL_haptic.h:271
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
#define SDL_atoi
#define SDL_getenv
#define NULL
Definition: begin_code.h:143
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
int SDL_SYS_HapticSetGain(SDL_Haptic *haptic, int gain)

◆ SDL_HapticStopAll()

int SDL_HapticStopAll ( SDL_Haptic *  haptic)

Stops all the currently playing effects on a haptic device.

Parameters
hapticHaptic device to stop.
Returns
0 on success or -1 on error.

Definition at line 724 of file SDL_haptic.c.

References SDL_SYS_HapticStopAll(), and ValidHaptic().

725 {
726  if (!ValidHaptic(haptic)) {
727  return -1;
728  }
729 
731 }
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
int SDL_SYS_HapticStopAll(SDL_Haptic *haptic)

◆ SDL_HapticStopEffect()

int SDL_HapticStopEffect ( SDL_Haptic *  haptic,
int  effect 
)

Stops the haptic effect on its associated haptic device.

Parameters
hapticHaptic device to stop the effect on.
effectIdentifier of the effect to stop.
Returns
0 on success or -1 on error.
See also
SDL_HapticRunEffect
SDL_HapticDestroyEffect

Definition at line 567 of file SDL_haptic.c.

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

Referenced by SDL_HapticRumbleStop().

568 {
569  if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
570  return -1;
571  }
572 
573  /* Stop the effect */
574  if (SDL_SYS_HapticStopEffect(haptic, &haptic->effects[effect]) < 0) {
575  return -1;
576  }
577 
578  return 0;
579 }
int SDL_SYS_HapticStopEffect(SDL_Haptic *haptic, struct haptic_effect *effect)
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
static SDL_Haptic * haptic
Definition: testhaptic.c:25
static int ValidEffect(SDL_Haptic *haptic, int effect)
Definition: SDL_haptic.c:507

◆ SDL_HapticUnpause()

int SDL_HapticUnpause ( SDL_Haptic *  haptic)

Unpauses a haptic device.

Call to unpause after SDL_HapticPause().

Parameters
hapticHaptic device to unpause.
Returns
0 on success or -1 on error.
See also
SDL_HapticPause

Definition at line 707 of file SDL_haptic.c.

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

708 {
709  if (!ValidHaptic(haptic)) {
710  return -1;
711  }
712 
713  if ((haptic->supported & SDL_HAPTIC_PAUSE) == 0) {
714  return 0; /* Not going to be paused, so we pretend it's unpaused. */
715  }
716 
718 }
int SDL_SYS_HapticUnpause(SDL_Haptic *haptic)
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
#define SDL_HAPTIC_PAUSE
Device can be paused.
Definition: SDL_haptic.h:297
static SDL_Haptic * haptic
Definition: testhaptic.c:25

◆ SDL_HapticUpdateEffect()

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 SDL_HapticUpdateEffect().

Parameters
hapticHaptic device that has the effect.
effectEffect to update.
dataNew effect properties to use.
Returns
0 on success or -1 on error.
See also
SDL_HapticNewEffect
SDL_HapticRunEffect
SDL_HapticDestroyEffect

Definition at line 520 of file SDL_haptic.c.

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

Referenced by SDL_HapticRumblePlay().

522 {
523  if (!ValidHaptic(haptic) || !ValidEffect(haptic, effect)) {
524  return -1;
525  }
526 
527  /* Can't change type dynamically. */
528  if (data->type != haptic->effects[effect].effect.type) {
529  return SDL_SetError("Haptic: Updating effect type is illegal.");
530  }
531 
532  /* Updates the effect */
533  if (SDL_SYS_HapticUpdateEffect(haptic, &haptic->effects[effect], data) <
534  0) {
535  return -1;
536  }
537 
538  SDL_memcpy(&haptic->effects[effect].effect, data,
539  sizeof(SDL_HapticEffect));
540  return 0;
541 }
#define SDL_memcpy
The generic template for any haptic effect.
Definition: SDL_haptic.h:785
static int ValidHaptic(SDL_Haptic *haptic)
Definition: SDL_haptic.c:52
int SDL_SYS_HapticUpdateEffect(SDL_Haptic *haptic, struct haptic_effect *effect, SDL_HapticEffect *data)
static SDL_Haptic * haptic
Definition: testhaptic.c:25
#define SDL_SetError
static int ValidEffect(SDL_Haptic *haptic, int effect)
Definition: SDL_haptic.c:507

◆ SDL_JoystickIsHaptic()

int SDL_JoystickIsHaptic ( SDL_Joystick *  joystick)

Checks to see if a joystick has haptic features.

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

Definition at line 245 of file SDL_haptic.c.

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

246 {
247  int ret;
248 
249  /* Must be a valid joystick */
250  if (!SDL_PrivateJoystickValid(joystick)) {
251  return -1;
252  }
253 
254  ret = SDL_SYS_JoystickIsHaptic(joystick);
255 
256  if (ret > 0)
257  return SDL_TRUE;
258  else if (ret == 0)
259  return SDL_FALSE;
260  else
261  return -1;
262 }
int SDL_PrivateJoystickValid(SDL_Joystick *joystick)
Definition: SDL_joystick.c:200
int SDL_SYS_JoystickIsHaptic(SDL_Joystick *joystick)

◆ SDL_MouseIsHaptic()

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.

215 {
216  if (SDL_SYS_HapticMouse() < 0)
217  return SDL_FALSE;
218  return SDL_TRUE;
219 }
int SDL_SYS_HapticMouse(void)

◆ SDL_NumHaptics()

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().

Referenced by SDL_HapticName(), SDL_HapticOpen(), SDL_HapticOpened(), and SDL_HapticOpenFromJoystick().

84 {
85  return SDL_SYS_NumHaptics();
86 }
int SDL_SYS_NumHaptics()