Provided by: allegro5-doc_5.2.8.0+dfsg-1_all bug

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 uploaded 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 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.

       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.

              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(3alleg5) 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(3alleg5) 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(3alleg5)  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 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  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(3alleg5) 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.