Haptic functions support force feedback and vibration on input devices. These functions are declared in the main Allegro header file:
#include <allegro5/allegro.h>
Currently force feedback is fully supported on Linux and on Windows for DirectInput compatible devices. There is also minimal support for Android. It is not yet supported on OSX, iOS, or on Windows for XInput compatible devices.
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
See also: al_get_haptic_from_joystick
Examples:
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 played.
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.
See also: al_get_haptic_capabilities, ALLEGRO_HAPTIC_EFFECT
struct ALLEGRO_HAPTIC_EFFECT
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.
Fields:
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.
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. 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.
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.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.
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
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_HAPTIC_CUSTOM is
not supported on some platforms, so use al_get_haptic_capabilities
to check if it’s available. If it isn’t, you may want to play back a
non-custom wave effect as a substitute instead.
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 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
device’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 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 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 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 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
replay.delay
seconds have passed since the playback was
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. 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 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 finishes 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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;
This struct is used as a handle to control playback of a haptic effect and should be considered opaque. Its implementation is visible merely to allow allocation by the users of the Allegro library.
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.
Examples:
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 in case of error.
For portability you should first open a display before calling al_install_haptic. On some platforms, such as DirectInput under Windows, al_install_haptic will only work if at least one active display is available. This display must stay available until al_uninstall_haptic is called.
If you need to close and reopen your active display for example, then you should call al_uninstall_haptic before closing the display, and al_install_haptic after opening it again.
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.
Examples:
void al_uninstall_haptic(void)
Uninstalls the haptic device subsystem. This is useful since on some platforms haptic effects are bound to the active display.
If you need to close and reopen your active display for example, then you should call al_uninstall_haptic before closing the display, and al_install_haptic after opening it again.
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.
bool al_is_haptic_installed(void)
Returns true if the haptic device subsystem is installed, false if not.
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.
bool al_is_mouse_haptic(ALLEGRO_MOUSE *dev)
Returns true if the mouse has haptic capabilities, false if not.
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.
bool al_is_keyboard_haptic(ALLEGRO_KEYBOARD *dev)
Returns true if the keyboard has haptic capabilities, false if not.
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.
bool al_is_display_haptic(ALLEGRO_DISPLAY *dev)
Returns true if the display has haptic capabilities, false if not. This mainly concerns force feedback that shakes a hand held device, such as a phone or a tablet.
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.
Examples:
bool al_is_joystick_haptic(ALLEGRO_JOYSTICK *dev)
Returns true if the joystick has haptic capabilities, false if not.
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.
Examples:
bool al_is_touch_input_haptic(ALLEGRO_TOUCH_INPUT *dev)
Returns true if the touch input device has haptic capabilities, false if not.
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.
*al_get_haptic_from_mouse(ALLEGRO_MOUSE *dev) ALLEGRO_HAPTIC
If the mouse has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.
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.
*al_get_haptic_from_keyboard(ALLEGRO_KEYBOARD *dev) ALLEGRO_HAPTIC
If the keyboard has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.
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.
*al_get_haptic_from_display(ALLEGRO_DISPLAY *dev) ALLEGRO_HAPTIC
If the display has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.
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.
Examples:
*al_get_haptic_from_joystick(ALLEGRO_JOYSTICK *dev) ALLEGRO_HAPTIC
If the joystick has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL. It’s necessary to call this again every time the joystick configuration changes, such as through hot plugging. In that case, the old haptic device must be released using al_release_haptic.
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.
Examples:
*al_get_haptic_from_touch_input(ALLEGRO_TOUCH_INPUT *dev) ALLEGRO_HAPTIC
If the touch input device has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.
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.
bool al_release_haptic(ALLEGRO_HAPTIC *haptic)
Releases the haptic device and its 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. This function also automatically releases all haptic effects that are still uploaded to the device and that have not been released manually using al_release_haptic_effect.
Returns true on success or false if the haptic device couldn’t be released for any reason, such as NULL being passed, the device not being active or failure in the driver.
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.
Examples:
bool al_is_haptic_active(ALLEGRO_HAPTIC *hap)
Returns true if the haptic device can currently be used, false if not.
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.
Examples:
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
bool al_is_haptic_capable(ALLEGRO_HAPTIC * hap, int query) {
Returns true if the haptic device supports the feature indicated by the query parameter, false if the feature is not supported. The query parameter must be one of the values of ALLEGRO_HAPTIC_CONSTANTS.
Since: 5.1.9
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
See also: al_get_haptic_capabilities
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 successfully, 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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
bool al_set_haptic_autocenter(ALLEGRO_HAPTIC *hap, double intensity)
Turns on or off the automatic centering feature of the haptic device if supported. Depending on the device automatic centering may ensure that the axes of the device are centered again automatically after playing a haptic effect. The intensity parameter should be passed with a value between 0.0 and 1.0. The value 0.0 means automatic centering is disabled, and 1.0 means full strength automatic centering. Any value in between those two extremes will result in partial automatic centering. Some platforms do not support partial automatic centering. If that is the case, a value of less than 0.5 will turn it off, while a value equal to or higher to 0.5 will turn it on. Returns true if set successfully, false if not. Can only work if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_AUTOCENTER set. If not, this function returns false.
Since: 5.1.9
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
double al_get_haptic_autocenter(ALLEGRO_HAPTIC *hap)
Returns the current automatic centering intensity of the device. Depending on the device automatic centering may ensure that the axes of the device are centered again automatically after playing a haptic effect. The return value can be between 0.0 and 1.0. The value 0.0 means automatic centering is disabled, and 1.0 means automatic centering is enabled at full strength. Any value in between those two extremes means partial automatic centering is enabled. Some platforms do not support partial automatic centering. If that is the case, a value of less than 0.5 means it is turned off, while a value equal to or higher to 0.5 means it is turned on. Can only work if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_AUTOCENTER set. If not, this function returns 0.0.
Since: 5.1.9
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
int al_get_max_haptic_effects(ALLEGRO_HAPTIC *hap)
Returns the maximum amount of haptic effects that can be uploaded to the device. This depends on the operating system, driver, platform and the device itself. This may return a value as low as 1.
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.
Examples:
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
bool al_upload_haptic_effect(ALLEGRO_HAPTIC *hap,
*effect, ALLEGRO_HAPTIC_EFFECT_ID *id) ALLEGRO_HAPTIC_EFFECT
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 function al_get_max_haptic_effects returns how many effects can be uploaded to the device at the same time.
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
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 successfully or false if not.
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.
Examples:
bool al_upload_and_play_haptic_effect(ALLEGRO_HAPTIC *hap,
*effect, ALLEGRO_HAPTIC_EFFECT_ID *id, int loop) ALLEGRO_HAPTIC_EFFECT
Uploads the haptic effect to the device and starts playback immediately. Returns true if the upload and playback were successful, false if either failed.
In case false is returned, the haptic effect will be automatically released as if al_release_haptic_effect had been called, so there is no need to call it again manually in this case. However, if true is returned, it is necessary to call al_release_haptic_effect when the effect isn’t needed anymore, to prevent the amount of available effects on the haptic devicefrom running out.
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.
See also: al_upload_haptic_effect, al_play_haptic_effect
Examples:
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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
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 has already finished 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
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
Examples:
double al_get_haptic_effect_duration(ALLEGRO_HAPTIC_EFFECT * effect)
Returns the estimated duration in seconds of a single loop of the
given haptic effect. The effect’s effect.replay
must have
been filled in correctly before using this function.
Since: 5.1.9
Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.
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.
This function is called automatically when you call al_release_haptic on a ALLEGRO_HAPTIC for all effects that are still uploaded to the device. Therefore this function is most useful if you want to upload and release haptic effects dynamically, for example as a way to circumvent the limit imposed by al_get_max_haptic_effects.
Returns true on success, false if the effect couldn’t be released for any reason such as when NULL is passed, the effect is not active or failure to release the effect by the driver.
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.
Examples:
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.
In case false is returned, the rumble effect will be automatically released as if al_release_haptic_effect had been called, so there is no need to call it again manually in this case. However, if true is returned, it is necessary to call al_release_haptic_effect when the effect isn’t needed anymore, to prevent the amount of available effects on the haptic device from running out.
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.