From b70c97aca391436b340ebe09a5a28a0651e7b928 Mon Sep 17 00:00:00 2001 From: Edgar Simo Date: Fri, 18 Jul 2008 08:00:16 +0000 Subject: [PATCH] More documentation. SDL_HapticPeriodic.phase now should make sense. More explicit if you try to update an effect type. --- include/SDL_haptic.h | 27 +++++++++++++++++++++------ src/haptic/SDL_haptic.c | 9 +++++++++ src/haptic/linux/SDL_syshaptic.c | 5 ++++- 3 files changed, 34 insertions(+), 7 deletions(-) diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index 248b81216..ec089a9a4 100644 --- a/include/SDL_haptic.h +++ b/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 diff --git a/src/haptic/SDL_haptic.c b/src/haptic/SDL_haptic.c index 5e1146099..bffc6ffe6 100644 --- a/src/haptic/SDL_haptic.c +++ b/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; } diff --git a/src/haptic/linux/SDL_syshaptic.c b/src/haptic/linux/SDL_syshaptic.c index 502e6adbf..9185f2f9a 100644 --- a/src/haptic/linux/SDL_syshaptic.c +++ b/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);