More documentation.

SDL_HapticPeriodic.phase now should make sense.
More explicit if you try to update an effect type.

include/SDL_haptic.h

@@ -434,6 +434,14 @@ typedef struct SDL_HapticConstant {
  *  over time.  The type determines the shape of the wave and the parameters
  *  determine the dimensions of the wave.
  *
+ * Phase is given by hundredth of a cyle meaning that giving the phase a value
+ *  of 9000 will displace it 25% of it's period.  Here are sample values:
+ *    -     0: No phase displacement.
+ *    -  9000: Displaced 25% of it's period.
+ *    - 18000: Displaced 50% of it's period.
+ *    - 27000: Displaced 75% of it's period.
+ *    - 36000: Displaced 100% of it's period, same as 0, but 0 is preffered.
+ *
  * Examples:
  * \code
  * SDL_HAPTIC_SINE
@@ -488,7 +496,7 @@ typedef struct SDL_HapticPeriodic {
    Uint16 period; /**< Period of the wave. */
    Sint16 magnitude; /**< Peak value. */
    Sint16 offset; /**< Mean value of the wave. */
-   Uint16 phase; /**< Horizontal shift. */
+   Uint16 phase; /**< Horizontal shift given by hundredth of a cycle. */
 
    /* Envelope */
    Uint16 attack_length; /**< Duration of the attack. */
@@ -592,7 +600,7 @@ typedef struct SDL_HapticRamp {
  *
  * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value.
  *  Neither delay, interval, attack_length nor fade_length support 
- *  SDL_HAPTIC_INFINITY.
+ *  SDL_HAPTIC_INFINITY.  Fade will also not be used since effect never ends.
  *
  * Common parts:
  * \code
@@ -875,10 +883,12 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticE
 /**
  * \fn int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
  *
- * \brief Updates an effect.  Can be used dynamically, although behaviour when
- * dynamically changing direction may be strange.  Specifically the effect
- * may reupload itself and start playing from the start.  You cannot change
- * the type either when running UpdateEffect.
+ * \brief Updates the properties of an effect.
+ *
+ * Can be used dynamically, although behaviour when dynamically changing
+ * direction may be strange.  Specifically the effect may reupload itself
+ * and start playing from the start.  You cannot change the type either when
+ * running UpdateEffect.
  *
  *    \param haptic Haptic device that has the effect.
  *    \param effect Effect to update.
@@ -896,6 +906,11 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effe
  *
  * \brief Runs the haptic effect on it's assosciated haptic device.
  *
+ * If iterations are SDL_HAPTIC_INFINITY, it'll run the effect over and over
+ *  repeating the envelope (attack and fade) every time.  If you only want the
+ *  effect to last forever, set SDL_HAPTIC_INFINITY in the effect's length
+ *  parameter.
+ *
  *    \param haptic Haptic device to run the effect on.
  *    \param effect Identifier of the haptic effect to run.
  *    \param iterations Number of iterations to run the effect. Use

src/haptic/SDL_haptic.c

@@ -440,6 +440,8 @@ SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect)
          if (SDL_SYS_HapticNewEffect(haptic,&haptic->effects[i],effect) != 0) {
             return -1; /* Backend failed to create effect */
          }
+
+         SDL_memcpy(&haptic->effects[i].effect, effect, sizeof(SDL_HapticEffect));
          return i;
       }
    }
@@ -471,11 +473,18 @@ SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data)
       return -1;
    }
 
+   /* Can't change type dynamically. */
+   if (data->type != haptic->effects[effect].effect.type) {
+      SDL_SetError("Haptic: Updating effect type is illegal.");
+      return -1;
+   }
+
    /* Updates the effect */
    if (SDL_SYS_HapticUpdateEffect(haptic,&haptic->effects[effect],data) < 0) {
       return -1;
    }
 
+   SDL_memcpy(&haptic->effects[effect].effect, data, sizeof(SDL_HapticEffect));
    return 0;
 }
 

src/haptic/linux/SDL_syshaptic.c

@@ -493,6 +493,7 @@ SDL_SYS_ToDirection( SDL_HapticDirection * dir )
 static int
 SDL_SYS_ToFFEffect( struct ff_effect * dest, SDL_HapticEffect * src )
 {
+   Uint32 tmp;
    SDL_HapticConstant *constant;
    SDL_HapticPeriodic *periodic;
    SDL_HapticCondition *condition;
@@ -563,7 +564,9 @@ SDL_SYS_ToFFEffect( struct ff_effect * dest, SDL_HapticEffect * src )
          dest->u.periodic.period = CLAMP(periodic->period);
          dest->u.periodic.magnitude = periodic->magnitude;
          dest->u.periodic.offset = periodic->offset;
-         dest->u.periodic.phase = CLAMP(periodic->phase);
+         /* Phase is calculated based of offset from period and then clamped. */
+         tmp = ((periodic->phase % 36000) * dest->u.periodic.period) / 36000;
+         dest->u.periodic.phase = CLAMP(tmp);
 
          /* Envelope */
          dest->u.periodic.envelope.attack_length = CLAMP(periodic->attack_length);