.TH "ALLEGRO_HAPTIC_EFFECT" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
ALLEGRO_HAPTIC_EFFECT \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>

struct\ ALLEGRO_HAPTIC_EFFECT
\f[]
.fi
.SH DESCRIPTION
.PP
This struct models a particular haptic or vibration effect.
It needs to be filled in correctly and uploaded to a haptic device
before the device can play it back.
.PP
\f[I]Fields:\f[]
.TP
.B 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.
.RS
.IP \[bu] 2
If \f[C]type\f[] 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.
.IP \[bu] 2
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_PERIODIC, the effect is a
shake or vibration of which the intensity is a periodic wave form.
.IP \[bu] 2
If \f[C]type\f[] 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.
.IP \[bu] 2
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_SPRING, the effect is a
springy kind of resistance against motion of the axes of the haptic
device.
.IP \[bu] 2
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_FRICTION, the effect is a
friction kind of resistance against motion of the axes of the haptic
device.
.IP \[bu] 2
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_DAMPER, the effect is a damper
kind of resistance against motion of the axes of the haptic device.
.IP \[bu] 2
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_INERTIA, the effect causes
inertia or slowness of motions on the axes of the haptic device.
.IP \[bu] 2
If \f[C]type\f[] 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.
.RE
.TP
.B 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.
.RS
.PP
In Allegro\[aq]s coordinate system, the value in
\f[C]direction.angle\f[] 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 direction 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.
.PP
If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_ANGLE set,
then setting \f[C]direction.angle\f[] is supported.
Otherwise, it is unsupported, and you should set it to 0.
.PP
The value in \f[C]direction.radius\f[] 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.
.PP
If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_RADIUS set,
then setting \f[C]direction.radius\f[] is supported.
Otherwise, it is unsupported, and you should set it to 0.
.PP
The value in \f[C]direction.azimuth\f[] 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.
.PP
If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_AZIMUTH
set, then setting \f[C]direction.azimuth\f[] is supported.
Otherwise, it is unsupported, and you should set it to 0.
.RE
.TP
.B replay
Determines how the effect should be played back.
\f[C]replay.length\f[] is the duration in seconds of the effect, and
\f[C]replay.delay\f[] is the time in seconds that the effect playback
should be delayed when playback is started with
al_play_haptic_effect(3).
.RS
.RE
.TP
.B data
Determines in detail the parameters of the haptic effect to play back.
.RS
.PP
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_RUMBLE, then
\f[C]data.rumble.strong_magnitude\f[] 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
\f[C]data.rumble.weak_magnitude\f[] 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
\f[C]data.rumble.weak_magnitude\f[] will be ignored.
.PP
If \f[C]type\f[] 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.
.PP
In these cases, \f[C]data.periodic.period\f[] must be set to the period
in seconds of the wave form.
The field \f[C]data.periodic.magnitude\f[] 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 \f[C]data.periodic.offset\f[] must be filled in with the
offset from origin in seconds of the wave form of vibration, and the
field \f[C]data.periodic.phase\f[] is the phase of the wave form of
vibration in seconds.
.PP
If \f[C]data.periodic.waveform\f[] is set to ALLEGRO_HAPTIC_CUSTOM, then
\f[C]data.periodic.custom_data\f[] must point to an array of
\f[C]data.periodic.custom_len\f[] 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(3) to check if it\[aq]s available.
If it isn\[aq]t, you may want to play back a non\-custom wave effect as
a substitute instead.
.PP
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_CONSTANT, then
\f[C]data.constant.level\f[] must be set to a relative intensity value
between 0.0 and 1.0 to determine the intensity of the effect.
.PP
If \f[C]type\f[] is set to any of ALLEGRO_HAPTIC_SPRING,
ALLEGRO_HAPTIC_FRICTION, ALLEGRO_HAPTIC_DAMPER, ALLEGRO_HAPTIC_INERTIA,
ALLEGRO_HAPTIC_RAMP, then the \f[C]data.condition\f[] struct should be
filled in.
To explain this better, it\[aq]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 device\[aq]s
wheel a certain distance to the left or right.
.PP
The field \f[C]data.condition.right_saturation\f[] 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, \f[C]data.condition.left_saturation\f[] 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.
.PP
The field \f[C]data.condition.deadband\f[] 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.
.PP
The field \f[C]data.condition.center\f[] 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.
.PP
The field \f[C]data.condition.right_coef\f[] and
\f[C]data.condition.right_left_coef\f[] 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.
.PP
If \f[C]type\f[] is set to ALLEGRO_HAPTIC_RAMP, then
\f[C]data.ramp.start_level\f[] 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 \f[C]data.ramp.end_level\f[] 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.
.PP
If \f[C]type\f[] is set to any of ALLEGRO_HAPTIC_PERIODIC,
ALLEGRO_HAPTIC_CONSTANT, ALLEGRO_HAPTIC_RAMP, then
\f[C]data.envelope\f[] 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.
.PP
In these cases the field \f[C]data.envelope.attack_level\f[] 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
\f[C]replay.delay\f[] seconds have passed since the playback was
started).
The field \f[C]data.envelope.attack_length\f[] must be set to the time
in seconds that the effect should ramp up to the maximum intensity as
set by the other parameters.
If \f[C]data.envelope.attack_length\f[] is 0, then the effect will play
immediately at full intensity.
.PP
The field \f[C]data.envelope.fade_level\f[] must be set to a relative
value between 0.0 and 1.0 that determines the intensity the effect
should have when it stops playing after
\f[C]replay.length\ +\ replay.delay\f[] seconds have passed since the
playback of the effect started.
The field \f[C]data.envelope.fade_length\f[] must be set to the time in
seconds that the effect should fade out before it finishes playing.
If \f[C]data.envelope.fade_length\f[] is 0, then the effect will not
fade out.
.PP
If you don\[aq]t want to use an envelope, then set all four fields of
\f[C]data.envelope\f[] to 0.0.
The effect will then play back at full intensity throughout its
playback.
.RE
.SH SINCE
.PP
5.1.8
.RS
.PP
\f[I][Unstable API]:\f[] Perhaps could be simplified due to limited
support for all the exposed features across all of the platforms.
Awaiting feedback from users.
.RE