Provided by: allegro5-doc_5.2.9.1+dfsg-1.1build4_all 
NAME
ALLEGRO_HAPTIC_EFFECT - Allegro 5 API
SYNOPSIS
#include <allegro5/allegro.h>
struct ALLEGRO_HAPTIC_EFFECT
DESCRIPTION
This struct models a particular haptic or vibration effect. It needs to be filled in correctly and up‐
loaded 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 ef‐
fect 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 in‐
tensity 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 mo‐
tion 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 mo‐
tion 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 sup‐
port 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. This angle
increases clockwise away from the user. So, an effect with an angle 0.0 takes place in the direc‐
tion of the user of the haptic device, an angle of π/2 is to the left of the user, an angle of π
means the direction away from the user, and an angle of 3π/2 means to the right of the user.
If al_get_haptic_capabilities(3alleg5) has the flag ALLEGRO_HAPTIC_ANGLE set, then setting direc‐
tion.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(3alleg5) has the flag ALLEGRO_HAPTIC_RADIUS set, then setting direc‐
tion.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(3alleg5) has the flag ALLEGRO_HAPTIC_AZIMUTH set, then setting di‐
rection.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(3alleg5).
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 rela‐
tive magnitude between 0.0 and 1.0 to determine how intensely the “large” rumble motor of the hap‐
tic 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 ALLE‐
GRO_HAPTIC_SQUARE, ALLEGRO_HAPTIC_TRIANGLE, ALLEGRO_HAPTIC_SINE, ALLEGRO_HAPTIC_SAW_UP, ALLE‐
GRO_HAPTIC_SAW_DOWN, ALLEGRO_HAPTIC_CUSTOM. This will then determine the wave form of the vibra‐
tion effect that will be played on the haptic device.
In these cases, data.periodic.period must 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_HAP‐
TIC_CUSTOM is not supported on some platforms, so use al_get_haptic_capabilities(3alleg5) to check
if it’s available. If it isn’t, you may want to play back a non-custom wave effect as a substi‐
tute instead.
If type is set to ALLEGRO_HAPTIC_CONSTANT, then data.constant.level must be set to a relative in‐
tensity 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 should be filled in.
To explain this better, it’s best to keep in mind that these kinds of effects are most useful for
steering-wheel kind of devices, where resistance or inertia should be applied when turning the de‐
vice’s wheel a certain distance to the left or right.
The field data.condition.right_saturation must be filled in with a relative magnitude between -1.0
and 1.0 to determine 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 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 cen‐
tered. 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 determine 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 mag‐
nitude 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 de‐
termine 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 or “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 re‐
play.delay seconds have passed since the playback was started). The field data.envelope.at‐
tack_length must be set to the time in seconds that the effect should ramp up to the maximum in‐
tensity as set by the other parameters. 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 deter‐
mines the intensity the effect should have when it stops playing after replay.length + replay.de‐
lay seconds have passed since the playback of the effect started. The field data.enve‐
lope.fade_length must be set to the time in seconds that the effect should fade out before it fin‐
ishes 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 ef‐
fect will then play back at full intensity throughout its playback.
SINCE
5.1.8
[Unstable API]: Perhaps could be simplified due to limited support for all the exposed features
across all of the platforms. Awaiting feedback from users.
Allegro reference manual ALLEGRO_HAPTIC_EFFECT(3alleg5)