Haptic functions support force feedback and vibration on input devices. These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_HAPTIC

typedef struct ALLEGRO_HAPTIC ALLEGRO_HAPTIC;

This is an abstract data type representing a haptic device that supports force feedback or vibration.

Since: 5.1.8

See also: al_get_haptic_from_joystick

ALLEGRO_HAPTIC_CONSTANTS

enum ALLEGRO_HAPTIC_CONSTANTS

This enum contains flags that are used to define haptic effects and capabilities. If the flag is set in the return value of al_get_haptic_capabilities, it means the device supports the given effect. The value of these flags should be set into a ALLEGRO_HAPTIC_EFFECT struct to determine what kind of haptic effect should be caused when it is played.

Since: 5.1.8

See also: al_get_haptic_capabilities, ALLEGRO_HAPTIC_EFFECT

ALLEGRO_HAPTIC_EFFECT

struct ALLEGRO_HAPTIC_EFFECT

This struct models a particular haptic or vibration effect. It needs to be filled correctly in and uploaded to a haptic device, before the device can play it back.

Fields:

type

The type of the haptic effect. May be one of the ALLEGRO_HAPTIC_CONSTANTS constants between or equal to ALLEGRO_HAPTIC_RUMBLE and ALLEGRO_HAPTIC_RAMP.

  • If type is set to ALLEGRO_HAPTIC_RUMBLE, then the effect is a simple "rumble" or vibration effect that shakes the device. In some cases, such as on a mobile platform, the whole device may shake.

  • If type is set to ALLEGRO_HAPTIC_PERIODIC, the effect is a shake or vibration of which the intensity is a periodic wave form.

  • If type is set to ALLEGRO_HAPTIC_CONSTANT, the effect is a constant pressure, motion or push-back in a certain direction of the axes of the device.

  • If type is set to ALLEGRO_HAPTIC_SPRING, the effect is a springy kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_FRICTION, the effect is a friction kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_DAMPER, the effect is a damper kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_INERTIA, the effect causes inertia or slowness of motions on the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_RAMP, the effect causes a pressure or push-back that ramps up or down depending on the position of the axis.

direction

The direction of location in 3D space where the effect should be played. Allegro haptic devices model directions in 3D space using spherical coordinates. However, the haptic device may not support localized effects, or may not support all coordinate components.

In Allegro's coordinate system, the value in direction.angle determines the planar angle between the effect and the direction of the user who holds the device, expressed in radians. So, an effect with an angle 0.0 takes place in the direction of the user of the haptic device, and an angle of π means in the direction away from the user.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_ANGLE set, then setting direction.angle is supported. Otherwise, it is unsupported, and you should set it to 0.

The value in direction.radius is a relative value between 0.0 and 1.0 that determines the relative distance from the center of the haptic device at which the effect will play back. A value of 0 means that the effect should play back at the center of the device. A value of 1.0 means that the effect should play back away from the center as far as is possible.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_RADIUS set, then setting direction.radius is supported. Otherwise, it is unsupported, and you should set it to 0.

The value in direction.azimuth determines the elevation angle between the effect and the plane in which the user is holding the device, expressed in radians. An effect with an azimuth 0.0 plays back in the plane in which the user is holding the device, an azimuth +π/2 means the effect plays back vertically above the user plane, and an azimuth -π/2 means the effect plays back vertically below the user plane.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_AZIMUTH set, then setting direction.azimuth is supported. Otherwise, it is unsupported, and you should set it to 0.

replay

Determines how the effect should be played back. replay.length is the duration in seconds of the effect, and replay.delay is the time in seconds that the effect playback should be delayed when playback is started with al_play_haptic_effect.

data

Determines in detail the parameters of the haptic effect to play back.

If type is set to ALLEGRO_HAPTIC_RUMBLE, then data.rumble.strong_magnitude must be set to a relative magnitude between 0.0 and 1.0 to determine how intensely the "large" rumble motor of the haptic device will vibrate, and data.rumble.weak_magnitude must be set to relative magnitude between 0.0 and 1.0 to determine how intensely the "weak" ruble motor of the haptic device will vibrate. Not all devices have a "weak" motor, in which case the value set in data.rumble.weak_magnitude will be ignored.

If type is set to ALLEGRO_HAPTIC_PERIODIC, then data.periodic.waveform must be set to one of ALLEGRO_HAPTIC_SQUARE, ALLEGRO_HAPTIC_TRIANGLE, ALLEGRO_HAPTIC_SINE, ALLEGRO_HAPTIC_SAW_UP, ALLEGRO_HAPTIC_SAW_DOWN, ALLEGRO_HAPTIC_CUSTOM. This will then determine the wave form of the vibration effect that will be played on the haptic device.

In these cases, data.periodic.period muust be set to the period in seconds of the wave form. The field data.periodic.magnitude must be set to the relative magnitude of intensity between -1.0 and 1.0 at which the wave form of the vibration will be played back. The field data.periodic.offset must be filled in with the offset from origin in seconds of the wave form of vibration, and the field data.periodic.phase is the phase of the wave form of vibration in seconds.

If data.periodic.waveform is set to ALLEGRO_HAPTIC_CUSTOM, then data.periodic.custom_data must point to an array of data.periodic.custom_len doubles, each with values between -1.0 and 1.0. This value array will determine the shape of the wave form of the haptic effect. ALLEGRO_HAPTIC_CUSTOM is not supported on some platforms, so use al_get_haptic_capabilities to check if it's available. If not, then it's a good idea play back a non-custom wave effect instead as a substitute.

If type is set to ALLEGRO_HAPTIC_CONSTANT, then data.constant.level must be set to a relative intensity value between 0.0 and 1.0 to determine the intensity of the effect.

If type is set to any of ALLEGRO_HAPTIC_SPRING, ALLEGRO_HAPTIC_FRICTION, ALLEGRO_HAPTIC_DAMPER, ALLEGRO_HAPTIC_INERTIA, ALLEGRO_HAPTIC_RAMP, then the data.condition struct shuld be filled in. To explain this better, it's best to keep in mind that this kind of effects is most useful for steering-wheel kind of devices, where resistance or inertia should be applied when turning the wheel of the device a certain distance to the right or the left.

The field data.condition.right_saturation must be filled in with a relative magnitude between -1.0 and 1.0 to determine the the intensity of resistance or inertia on the "right" side of the axis. Likewise, data.condition.left_saturation must be filled in with a relative magnitude between -1.0 and 1.0 to determine the the intensity of resistance or inertia on the "left" side of the axis.

The field data.condition.deadband must be filled in with a relative value between 0.0 and 1.0, to determine the relative width of the "dead band" of the haptic effect. As long as the axis of the haptic device remains in the "dead band" area, the effect will not be applied. A value of 0.0 means there is no dead band, and a value of 1.0 means it applied over the whole range of the axis in question.

The field data.condition.center must be filled in with a relative value between -1.0 and 1.0, to determine the relative position of the "center" of the effect around which the dead band is centered. It should be set to 0.0 in case the center should not be shifted.

The field data.condition.right_coef and data.condition.right_left_coef must be filled in with a relative coefficient, that will detemine how quickly the effect ramps up on the right and left side. If set to 1.0, then the effect will be immediately at full intensity when outside of the dead band. If set to 0.0 the effect will not be felt at all.

If type is set to ALLEGRO_HAPTIC_RAMP, then data.ramp.start_level should be set to a relative magnitude value between -1.0 and 1.0 to determine the initial intensity of the haptic effect. The field data.ramp.end_level should be set to a relative magnitude value between -1.0 and 1.0 to determine the final intensity of the haptic effect at the end of playback.

If type is set to any of ALLEGRO_HAPTIC_PERIODIC, ALLEGRO_HAPTIC_CONSTANT, ALLEGRO_HAPTIC_RAMP, then data.envelope determines the "envelope" of the effect. That is, it determines the duration and intensity for the ramp-up attack or "fade in" and the ramp-down "fade out" of the effect.

In these cases the field data.envelope.attack_level must be set to a relative value between 0.0 and 1.0 that determines the intensity the effect should have when it starts playing after replay.delay seconds have passed since the playback started. The field data.envelope.attack_length must be set to the time in seconds that the effect should ramp up to the maximum intensity as set by the other parameters of the effect. If data.envelope.attack_length is 0, then the effect will play immediately at full intensity.

The field data.envelope.fade_level must be set to a relative value between 0.0 and 1.0 that determines the intensity the effect should have when at the moment it stops playing after replay.length + replay.delay seconds have passed since the playback of the effect started. The field data.envelope.fade_length must be set to the time in seconds that the effect should fade out before it finished playing. If data.envelope.fade_length is 0, then the effect will not fade out.

If you don't want to use an envelope, then set all four fields of data.envelope to 0.0. The effect will then play back at full intensity throughout its playback.

Since: 5.1.8

ALLEGRO_HAPTIC_EFFECT_ID

typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;

This struct is used as a handle to control playback of a haptic effect. The struct should be considered opaque. Its implementation is visible merely to allow allocation by the users of the Allegro library.

Since: 5.1.8

al_install_haptic

bool al_install_haptic(void)

Installs the haptic (force feedback) device subsystem. This must be called before using any other haptic-related functions. Returns true if the haptics subsystem could be initialized correctly, false if not.

Since: 5.1.8

al_uninstall_haptic

void al_uninstall_haptic(void)

Uninstalls the haptic device subsystem.

Since: 5.1.8

al_is_haptic_installed

bool al_is_haptic_installed(void)

Returns true if the haptic device subsystem is installed, false if not.

Since: 5.1.8

al_is_mouse_haptic

bool al_is_mouse_haptic(ALLEGRO_MOUSE *dev)

Returns true if the mouse has haptic capabilities, false if not.

Since: 5.1.8

al_is_keyboard_haptic

bool al_is_keyboard_haptic(ALLEGRO_KEYBOARD *dev)

Returns true if the keyboard has haptic capabilities, false if not.

Since: 5.1.8

al_is_display_haptic

bool al_is_display_haptic(ALLEGRO_DISPLAY *dev)

Returns true if the display has haptic capabilities, false if not. To be more precise, this is mainly meant for force feedback that shakes a hand held device, such as a phone or a tablet.

Since: 5.1.8

al_is_joystick_haptic

bool al_is_joystick_haptic(ALLEGRO_JOYSTICK *dev)

Returns true if the joystick has haptic capabilities, false if not.

Since: 5.1.8

al_is_touch_input_haptic

Returns true if the touch input device has haptic capabilities, false if not.

Since: 5.1.8

al_get_haptic_from_mouse

ALLEGRO_HAPTIC *al_get_haptic_from_mouse(ALLEGRO_MOUSE *dev)

If the mouse has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

al_get_haptic_from_keyboard

ALLEGRO_HAPTIC *al_get_haptic_from_keyboard(ALLEGRO_KEYBOARD *dev)

If the keyboard has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

al_get_haptic_from_display

ALLEGRO_HAPTIC *al_get_haptic_from_display(ALLEGRO_DISPLAY *dev)

If the display has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

al_get_haptic_from_joystick

ALLEGRO_HAPTIC *al_get_haptic_from_joystick(ALLEGRO_JOYSTICK *dev)

If the joystick has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL. It's neccesary to call this again every time the joystick configuration changes, such as though hot plugging.

Since: 5.1.8

al_get_haptic_from_touch_input

ALLEGRO_HAPTIC *al_get_haptic_from_touch_input(ALLEGRO_TOUCH_INPUT *dev)

If the touch input device has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

al_release_haptic

bool al_release_haptic(ALLEGRO_HAPTIC *haptic)

Releases the haptic device and it's resources when it's not needed anymore. Should also be used in case the joystick configuration changed, such as when a joystick is hot plugged.

Since: 5.1.8

al_get_haptic_active

bool al_get_haptic_active(ALLEGRO_HAPTIC *hap)

Returns true if the haptic device can currently be used, false if not.

Since: 5.1.8

al_get_haptic_capabilities

int al_get_haptic_capabilities(ALLEGRO_HAPTIC *hap)

Returns an integer with or'ed values from ALLEGRO_HAPTIC_CONSTANTS, which, if set, indicate that the haptic device supports the given feature.

Since: 5.1.8

al_set_haptic_gain

bool al_set_haptic_gain(ALLEGRO_HAPTIC *hap, double gain)

Sets the gain of the haptic device if supported. Gain is much like volume for sound, it is as if every effect's intensity is multiplied by it. Gain is a value between 0.0 and 1.0. Returns true if set sucessfully, false if not. Only works if al_get_haptic_capabilities returns a value that has [ALLEGRO_HAPTIC_GAIN] set. If not, this function returns false, and all effects will be played without any gain influence.

Since: 5.1.8

al_get_haptic_gain

double al_get_haptic_gain(ALLEGRO_HAPTIC *hap)

Returns the current gain of the device. Gain is much like volume for sound, it is as if every effect's intensity is multiplied by it. Gain is a value between 0.0 and 1.0. Only works correctly if al_get_haptic_capabilities returns a value that has [ALLEGRO_HAPTIC_GAIN] set. If this is not set, this function will simply return 1.0 and all effects will be played without any gain influence.

Since: 5.1.8

al_get_num_haptic_effects

int al_get_num_haptic_effects(ALLEGRO_HAPTIC *hap)

Returns the maximum amount of haptic effects that can be uploaded to the device. This depends on the platform and the device.

Since: 5.1.8

al_is_haptic_effect_ok

bool al_is_haptic_effect_ok(ALLEGRO_HAPTIC *hap, ALLEGRO_HAPTIC_EFFECT *effect)

Returns true if the haptic device can play the haptic effect as given, false if not. The haptic effect must have been filled in completely and correctly.

Since: 5.1.8

al_upload_haptic_effect

bool al_upload_haptic_effect(ALLEGRO_HAPTIC *hap,
   ALLEGRO_HAPTIC_EFFECT *effect, ALLEGRO_HAPTIC_EFFECT_ID *id)

Uploads the haptic effect to the device. The haptic effect must have been filled in completely and correctly. You must also pass in a pointer to a user allocated ALLEGRO_HAPTIC_EFFECT_ID. This id can be used to control playback of the effect. Returns true if the effect was successfully uploaded, false if not.

The same haptic effect can be uploaded several times, as long as care is taken to pass in a different ALLEGRO_HAPTIC_EFFECT_ID.

Since: 5.1.8

al_play_haptic_effect

bool al_play_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id, int loop)

Plays back a previously uploaded haptic effect. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

The haptic effect will be played back loop times in sequence. If loop is less than or equal to 1, then the effect will be played once only.

This function returns immediately and doesn't wait for the playback to finish. It returns true if the playback was started sucessfully or false if not.

Since: 5.1.8

al_upload_and_play_haptic_effect

bool al_upload_and_play_haptic_effect(ALLEGRO_HAPTIC *hap,
   ALLEGRO_HAPTIC_EFFECT *effect, int loop, ALLEGRO_HAPTIC_EFFECT_ID *id)

Uploads and immediately plays back the haptic effect to the device. Returns true if the upload and playback were successful, false if either failed.

Since: 5.1.8

See also: al_upload_haptic_effect, al_play_haptic_effect

al_stop_haptic_effect

bool al_stop_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id)

Stops playing a previously uploaded haptic effect. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

Since: 5.1.8

al_is_haptic_effect_playing

bool al_is_haptic_effect_playing(ALLEGRO_HAPTIC_EFFECT_ID *id)

Returns true if the haptic effect is currently playing. Returns false if the effect has been stopped or if it finsihed playing, or if it has not been played yet. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

Since: 5.1.8

al_release_haptic_effect

bool al_release_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id)

Releases a previously uploaded haptic effect from the device it has been uploaded to, allowing for other effects to be uploaded. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

Since: 5.1.8

al_rumble_haptic

bool al_rumble_haptic(ALLEGRO_HAPTIC *hap,
   double intensity, double duration, ALLEGRO_HAPTIC_EFFECT_ID *id)

Uploads a simple rumble effect to the haptic device and starts playback immediately. The parameter intensity is a relative magnitude between 0.0 and 1.0 that determines the intensity of the rumble effect. The duration determines the duration of the effect in seconds.

You must also pass in a pointer to a user allocated ALLEGRO_HAPTIC_EFFECT_ID. It it is stored a reference to be used to control playback of the effect. Returns true if the rumble effect was successfully uploaded and started, false if not.

Since: 5.1.8

Allegro version 5.1.8 (WIP) - Last updated: 2014-01-12 03:33:09 UTC