More documentation. gsoc2008_force_feedback
authorEdgar Simo <bobbens@gmail.com>
Fri, 18 Jul 2008 08:00:16 +0000
branchgsoc2008_force_feedback
changeset 25262d88b82ce781
parent 2525 1fb3fba13a2c
child 2527 924a32719b6f
More documentation.
SDL_HapticPeriodic.phase now should make sense.
More explicit if you try to update an effect type.
include/SDL_haptic.h
src/haptic/SDL_haptic.c
src/haptic/linux/SDL_syshaptic.c
     1.1 --- a/include/SDL_haptic.h	Thu Jul 17 16:08:46 2008 +0000
     1.2 +++ b/include/SDL_haptic.h	Fri Jul 18 08:00:16 2008 +0000
     1.3 @@ -434,6 +434,14 @@
     1.4   *  over time.  The type determines the shape of the wave and the parameters
     1.5   *  determine the dimensions of the wave.
     1.6   *
     1.7 + * Phase is given by hundredth of a cyle meaning that giving the phase a value
     1.8 + *  of 9000 will displace it 25% of it's period.  Here are sample values:
     1.9 + *    -     0: No phase displacement.
    1.10 + *    -  9000: Displaced 25% of it's period.
    1.11 + *    - 18000: Displaced 50% of it's period.
    1.12 + *    - 27000: Displaced 75% of it's period.
    1.13 + *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
    1.14 + *
    1.15   * Examples:
    1.16   * \code
    1.17   * SDL_HAPTIC_SINE
    1.18 @@ -488,7 +496,7 @@
    1.19     Uint16 period; /**< Period of the wave. */
    1.20     Sint16 magnitude; /**< Peak value. */
    1.21     Sint16 offset; /**< Mean value of the wave. */
    1.22 -   Uint16 phase; /**< Horizontal shift. */
    1.23 +   Uint16 phase; /**< Horizontal shift given by hundredth of a cycle. */
    1.24  
    1.25     /* Envelope */
    1.26     Uint16 attack_length; /**< Duration of the attack. */
    1.27 @@ -592,7 +600,7 @@
    1.28   *
    1.29   * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
    1.30   *  Neither delay, interval, attack_length nor fade_length support 
    1.31 - *  SDL_HAPTIC_INFINITY.
    1.32 + *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
    1.33   *
    1.34   * Common parts:
    1.35   * \code
    1.36 @@ -875,10 +883,12 @@
    1.37  /**
    1.38   * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
    1.39   *
    1.40 - * \brief Updates an effect.  Can be used dynamically, although behaviour when
    1.41 - * dynamically changing direction may be strange.  Specifically the effect
    1.42 - * may reupload itself and start playing from the start.  You cannot change
    1.43 - * the type either when running UpdateEffect.
    1.44 + * \brief Updates the properties of an effect.
    1.45 + *
    1.46 + * Can be used dynamically, although behaviour when dynamically changing
    1.47 + * direction may be strange.  Specifically the effect may reupload itself
    1.48 + * and start playing from the start.  You cannot change the type either when
    1.49 + * running UpdateEffect.
    1.50   *
    1.51   *    \param haptic Haptic device that has the effect.
    1.52   *    \param effect Effect to update.
    1.53 @@ -896,6 +906,11 @@
    1.54   *
    1.55   * \brief Runs the haptic effect on it's assosciated haptic device.
    1.56   *
    1.57 + * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
    1.58 + *  repeating the envelope (attack and fade) every time.  If you only want the
    1.59 + *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
    1.60 + *  parameter.
    1.61 + *
    1.62   *    \param haptic Haptic device to run the effect on.
    1.63   *    \param effect Identifier of the haptic effect to run.
    1.64   *    \param iterations Number of iterations to run the effect. Use
     2.1 --- a/src/haptic/SDL_haptic.c	Thu Jul 17 16:08:46 2008 +0000
     2.2 +++ b/src/haptic/SDL_haptic.c	Fri Jul 18 08:00:16 2008 +0000
     2.3 @@ -440,6 +440,8 @@
     2.4           if (SDL_SYS_HapticNewEffect(haptic,&haptic->effects[i],effect) != 0) {
     2.5              return -1; /* Backend failed to create effect */
     2.6           }
     2.7 +
     2.8 +         SDL_memcpy(&haptic->effects[i].effect, effect, sizeof(SDL_HapticEffect));
     2.9           return i;
    2.10        }
    2.11     }
    2.12 @@ -471,11 +473,18 @@
    2.13        return -1;
    2.14     }
    2.15  
    2.16 +   /* Can't change type dynamically. */
    2.17 +   if (data->type != haptic->effects[effect].effect.type) {
    2.18 +      SDL_SetError("Haptic: Updating effect type is illegal.");
    2.19 +      return -1;
    2.20 +   }
    2.21 +
    2.22     /* Updates the effect */
    2.23     if (SDL_SYS_HapticUpdateEffect(haptic,&haptic->effects[effect],data) < 0) {
    2.24        return -1;
    2.25     }
    2.26  
    2.27 +   SDL_memcpy(&haptic->effects[effect].effect, data, sizeof(SDL_HapticEffect));
    2.28     return 0;
    2.29  }
    2.30  
     3.1 --- a/src/haptic/linux/SDL_syshaptic.c	Thu Jul 17 16:08:46 2008 +0000
     3.2 +++ b/src/haptic/linux/SDL_syshaptic.c	Fri Jul 18 08:00:16 2008 +0000
     3.3 @@ -493,6 +493,7 @@
     3.4  static int
     3.5  SDL_SYS_ToFFEffect( struct ff_effect * dest, SDL_HapticEffect * src )
     3.6  {
     3.7 +   Uint32 tmp;
     3.8     SDL_HapticConstant *constant;
     3.9     SDL_HapticPeriodic *periodic;
    3.10     SDL_HapticCondition *condition;
    3.11 @@ -563,7 +564,9 @@
    3.12           dest->u.periodic.period = CLAMP(periodic->period);
    3.13           dest->u.periodic.magnitude = periodic->magnitude;
    3.14           dest->u.periodic.offset = periodic->offset;
    3.15 -         dest->u.periodic.phase = CLAMP(periodic->phase);
    3.16 +         /* Phase is calculated based of offset from period and then clamped. */
    3.17 +         tmp = ((periodic->phase % 36000) * dest->u.periodic.period) / 36000;
    3.18 +         dest->u.periodic.phase = CLAMP(tmp);
    3.19           
    3.20           /* Envelope */
    3.21           dest->u.periodic.envelope.attack_length = CLAMP(periodic->attack_length);