1ALLEGRO_HAPTIC_EFFECT(3)                              ALLEGRO_HAPTIC_EFFECT(3)
2
3
4

NAME

6       ALLEGRO_HAPTIC_EFFECT - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              struct ALLEGRO_HAPTIC_EFFECT
12

DESCRIPTION

14       This  struct  models a particular haptic or vibration effect.  It needs
15       to be filled in correctly and uploaded to a haptic  device  before  the
16       device can play it back.
17
18       Fields:
19
20       type   The  type  of the haptic effect.  May be one of the ALLEGRO_HAP‐
21              TIC_CONSTANTS constants between or equal to  ALLEGRO_HAPTIC_RUM‐
22              BLE and ALLEGRO_HAPTIC_RAMP.
23
24              • If  type is set to ALLEGRO_HAPTIC_RUMBLE, then the effect is a
25                simple “rumble” or vibration effect that  shakes  the  device.
26                In  some cases, such as on a mobile platform, the whole device
27                may shake.
28
29              • If type is set to ALLEGRO_HAPTIC_PERIODIC,  the  effect  is  a
30                shake  or  vibration of which the intensity is a periodic wave
31                form.
32
33              • If type is set to ALLEGRO_HAPTIC_CONSTANT,  the  effect  is  a
34                constant  pressure, motion or push-back in a certain direction
35                of the axes of the device.
36
37              • If type is set  to  ALLEGRO_HAPTIC_SPRING,  the  effect  is  a
38                springy  kind  of resistance against motion of the axes of the
39                haptic device.
40
41              • If type is set to ALLEGRO_HAPTIC_FRICTION,  the  effect  is  a
42                friction  kind of resistance against motion of the axes of the
43                haptic device.
44
45              • If type is set  to  ALLEGRO_HAPTIC_DAMPER,  the  effect  is  a
46                damper  kind  of  resistance against motion of the axes of the
47                haptic device.
48
49              • If type is set to ALLEGRO_HAPTIC_INERTIA,  the  effect  causes
50                inertia  or  slowness of motions on the axes of the haptic de‐
51                vice.
52
53              • If type is set to ALLEGRO_HAPTIC_RAMP,  the  effect  causes  a
54                pressure  or  push-back that ramps up or down depending on the
55                position of the axis.
56
57       direction
58              The direction of location in 3D space where the effect should be
59              played.  Allegro haptic devices model directions in 3D space us‐
60              ing spherical coordinates.  However, the haptic device  may  not
61              support  localized  effects,  or  may not support all coordinate
62              components.
63
64              In Allegro’s coordinate system, the value in direction.angle de‐
65              termines  the  planar angle between the effect and the direction
66              of the user who holds the device, expressed  in  radians.   This
67              angle  increases  clockwise  away  from the user.  So, an effect
68              with an angle 0.0 takes place in the direction of  the  user  of
69              the  haptic  device, an angle of π/2 is to the left of the user,
70              an angle of π means the direction away from the user, and an an‐
71              gle of 3π/2 means to the right of the user.
72
73              If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_AN‐
74              GLE set, then setting direction.angle is supported.   Otherwise,
75              it is unsupported, and you should set it to 0.
76
77              The  value  in  direction.radius is a relative value between 0.0
78              and 1.0 that determines the relative distance from the center of
79              the  haptic  device at which the effect will play back.  A value
80              of 0 means that the effect should play back at the center of the
81              device.   A  value of 1.0 means that the effect should play back
82              away from the center as far as is possible.
83
84              If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_RA‐
85              DIUS  set,  then  setting direction.radius is supported.  Other‐
86              wise, it is unsupported, and you should set it to 0.
87
88              The value in direction.azimuth determines  the  elevation  angle
89              between  the  effect  and the plane in which the user is holding
90              the device, expressed in radians.  An effect with an azimuth 0.0
91              plays back in the plane in which the user is holding the device,
92              an azimuth +π/2 means the effect plays back vertically above the
93              user plane, and an azimuth -π/2 means the effect plays back ver‐
94              tically below the user plane.
95
96              If al_get_haptic_capabilities(3) has the flag ALLEGRO_HAPTIC_AZ‐
97              IMUTH  set, then setting direction.azimuth is supported.  Other‐
98              wise, it is unsupported, and you should set it to 0.
99
100       replay Determines how the effect should be played back.   replay.length
101              is  the  duration  in seconds of the effect, and replay.delay is
102              the time in seconds that the effect playback should  be  delayed
103              when playback is started with al_play_haptic_effect(3).
104
105       data   Determines in detail the parameters of the haptic effect to play
106              back.
107
108              If  type  is  set  to  ALLEGRO_HAPTIC_RUMBLE,   then   data.rum‐
109              ble.strong_magnitude must be set to a relative magnitude between
110              0.0 and 1.0 to determine how intensely the “large” rumble  motor
111              of  the  haptic device will vibrate, and data.rumble.weak_magni‐
112              tude must be set to relative magnitude between 0.0  and  1.0  to
113              determine how intensely the “weak” ruble motor of the haptic de‐
114              vice will vibrate.  Not all devices  have  a  “weak”  motor,  in
115              which  case  the value set in data.rumble.weak_magnitude will be
116              ignored.
117
118              If type is set  to  ALLEGRO_HAPTIC_PERIODIC,  then  data.period‐
119              ic.waveform  must  be set to one of ALLEGRO_HAPTIC_SQUARE, ALLE‐
120              GRO_HAPTIC_TRIANGLE, ALLEGRO_HAPTIC_SINE, ALLEGRO_HAPTIC_SAW_UP,
121              ALLEGRO_HAPTIC_SAW_DOWN,  ALLEGRO_HAPTIC_CUSTOM.  This will then
122              determine the wave form of the vibration  effect  that  will  be
123              played on the haptic device.
124
125              In  these  cases, data.periodic.period must be set to the period
126              in seconds of the wave form.  The field  data.periodic.magnitude
127              must  be set to the relative magnitude of intensity between -1.0
128              and 1.0 at which the wave form of the vibration will  be  played
129              back.  The field data.periodic.offset must be filled in with the
130              offset from origin in seconds of the wave form of vibration, and
131              the  field  data.periodic.phase is the phase of the wave form of
132              vibration in seconds.
133
134              If data.periodic.waveform is set to ALLEGRO_HAPTIC_CUSTOM,  then
135              data.periodic.custom_data must point to an array of data.period‐
136              ic.custom_len doubles, each with values between  -1.0  and  1.0.
137              This  value  array  will determine the shape of the wave form of
138              the haptic effect.  ALLEGRO_HAPTIC_CUSTOM is  not  supported  on
139              some platforms, so use al_get_haptic_capabilities(3) to check if
140              it’s available.  If it isn’t, you may want to play back  a  non-
141              custom wave effect as a substitute instead.
142
143              If  type  is  set  to  ALLEGRO_HAPTIC_CONSTANT,  then  data.con‐
144              stant.level must be set to a relative  intensity  value  between
145              0.0 and 1.0 to determine the intensity of the effect.
146
147              If  type  is  set  to any of ALLEGRO_HAPTIC_SPRING, ALLEGRO_HAP‐
148              TIC_FRICTION, ALLEGRO_HAPTIC_DAMPER, ALLEGRO_HAPTIC_INERTIA, AL‐
149              LEGRO_HAPTIC_RAMP,  then  the  data.condition  struct  should be
150              filled in.  To explain this better, it’s best to  keep  in  mind
151              that  these  kinds of effects are most useful for steering-wheel
152              kind of devices, where resistance or inertia should  be  applied
153              when  turning  the device’s wheel a certain distance to the left
154              or right.
155
156              The field data.condition.right_saturation must be filled in with
157              a  relative  magnitude between -1.0 and 1.0 to determine the in‐
158              tensity of resistance or inertia on the “right” side of the  ax‐
159              is.   Likewise, data.condition.left_saturation must be filled in
160              with a relative magnitude between -1.0 and 1.0 to determine  the
161              intensity of resistance or inertia on the “left” side of the ax‐
162              is.
163
164              The field data.condition.deadband must be filled in with a rela‐
165              tive  value  between 0.0 and 1.0 to determine the relative width
166              of the “dead band” of the haptic effect.  As long as the axis of
167              the  haptic  device  remains in the “dead band” area, the effect
168              will not be applied.  A value of 0.0  means  there  is  no  dead
169              band,  and  a value of 1.0 means it applied over the whole range
170              of the axis in question.
171
172              The field data.condition.center must be filled in with  a  rela‐
173              tive  value between -1.0 and 1.0 to determine the relative posi‐
174              tion of the “center” of the effect around which the dead band is
175              centered.  It should be set to 0.0 in case the center should not
176              be shifted.
177
178              The    field    data.condition.right_coef    and     data.condi‐
179              tion.right_left_coef  must  be filled in with a relative coeffi‐
180              cient, that will determine how quickly the effect  ramps  up  on
181              the right and left side.  If set to 1.0, then the effect will be
182              immediately at full intensity when outside of the dead band.  If
183              set to 0.0 the effect will not be felt at all.
184
185              If type is set to ALLEGRO_HAPTIC_RAMP, then data.ramp.start_lev‐
186              el should be set to a relative magnitude value between -1.0  and
187              1.0  to  determine  the  initial intensity of the haptic effect.
188              The field data.ramp.end_level should be set to a relative magni‐
189              tude value between -1.0 and 1.0 to determine the final intensity
190              of the haptic effect at the end of playback.
191
192              If type is set to any of  ALLEGRO_HAPTIC_PERIODIC,  ALLEGRO_HAP‐
193              TIC_CONSTANT, ALLEGRO_HAPTIC_RAMP, then data.envelope determines
194              the “envelope” of the effect.  That is, it determines the  dura‐
195              tion  and  intensity for the ramp-up attack or “fade in” and the
196              ramp-down or “fade out” of the effect.
197
198              In these cases the field data.envelope.attack_level must be  set
199              to  a relative value between 0.0 and 1.0 that determines the in‐
200              tensity the effect should have when it starts playing (after re‐
201              play.delay  seconds have passed since the playback was started).
202              The field data.envelope.attack_length must be set to the time in
203              seconds  that the effect should ramp up to the maximum intensity
204              as set by the other parameters.  If  data.envelope.attack_length
205              is 0, then the effect will play immediately at full intensity.
206
207              The  field  data.envelope.fade_level  must  be set to a relative
208              value between 0.0 and 1.0 that determines the intensity the  ef‐
209              fect should have when it stops playing after replay.length + re‐
210              play.delay seconds have passed since the playback of the  effect
211              started.  The field data.envelope.fade_length must be set to the
212              time in seconds that the effect should fade out before  it  fin‐
213              ishes  playing.  If data.envelope.fade_length is 0, then the ef‐
214              fect will not fade out.
215
216              If you don’t want to use an envelope, then set all  four  fields
217              of data.envelope to 0.0.  The effect will then play back at full
218              intensity throughout its playback.
219

SINCE

221       5.1.8
222
223              [Unstable API]: Perhaps could be simplified due to limited  sup‐
224              port  for  all the exposed features across all of the platforms.
225              Awaiting feedback from users.
226
227
228
229Allegro reference manual                              ALLEGRO_HAPTIC_EFFECT(3)
Impressum