1ALLEGRO_HAPTIC_EFFECT(3) ALLEGRO_HAPTIC_EFFECT(3)
2
6 ALLEGRO_HAPTIC_EFFECT - Allegro 5 API
7
9 #include <allegro5/allegro.h>
10 struct ALLEGRO_HAPTIC_EFFECT
12
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 Fields:
19 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 • 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 • 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 • 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 • 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 • 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 • 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 • 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 • 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 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 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 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 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 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 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 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 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 data Determines in detail the parameters of the haptic effect to play
106 back.
107 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
221 5.1.8
222 [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.
226Allegro reference manual ALLEGRO_HAPTIC_EFFECT(3)