Skinetic::HapticEffect
Component that handle an haptic effect instance.
Inherits from MonoBehaviour
Public Types
| Name | |
|---|---|
| enum class | State { E_PLAY = 2, E_MUTE = 1, E_INITIALIZED = 0, E_STOP = -1} Effect's state. |
| enum class | PlayStrategy { E_DEFAULT = 0, E_FORCE = 1, E_PULLED = 2} Play strategy. |
Public Functions
| Name | |
|---|---|
| bool | PlayEffect() Play an haptic effect based on a loaded pattern and return the effectID of this instance. |
| bool | StopEffect(float time) Stop the effect instance. |
| State | GetEffectState() Get the current state of an effect. |
Public Properties
| Name | |
|---|---|
| PlayStrategy | StrategyOnPlay Defines the haptic effect behavior when PlayEffect() is called. |
| int | PriorityLevel Level of priority [1; 10] of the effect. |
| float | Volume Volume of the pattern. |
| float | Speed Speed of the pattern. |
| int | RepeatCount Number of repetition of the pattern as the effect is playing. |
| float | RepeatDelay Pause in second between two repetition of the pattern. |
| float | PlayAtTime Time in the pattern at which the effect start to play. |
| float | MaxDuration Maximum duration of the effect. |
| int | EffectBoost Boost intensity level percent. |
| bool | OverridePatternBoost Property to override the default pattern boost with a custom value for the effect. |
| float | HeightTranslation Height in meter to translate the pattern by. |
| float | HeadingRotation Heading angle in degree to rotate the pattern by in the horizontal plan (y axis). |
| float | TiltingRotation Tilting angle in degree to rotate the pattern by in the sagittal plan (x axis). |
| bool | FrontBackInversion Invert the direction of the pattern on the front-back axis. |
| bool | UpDownInversion Invert the direction of the pattern on the up-down axis. |
| bool | RightLeftInversion Invert the direction of the pattern on the right-left axis. |
| bool | FrontBackAddition Perform a front-back addition of the pattern on the front-back axis. |
| bool | UpDownAddition Perform a up-down addition of the pattern on the front-back axis. |
| bool | RightLeftAddition Perform a right-left addition of the pattern on the front-back axis. |
| SkineticDevice.EffectProperties | Properties Structure containing all properties of an haptic effect instance. |
| PatternAsset | TargetPattern Device to which the effect will be played on. |
| SkineticDevice | TargetDevice PatternAsset from which the effect will be instantiated. |
Public Types Documentation
enum State
| Enumerator | Value | Description |
|---|---|---|
| E_PLAY | 2 | Effect is playing. |
| E_MUTE | 1 | Effect is muted. |
| E_INITIALIZED | 0 | Effect is initialized and should play as soon as possible. |
| E_STOP | -1 | Effect is stopped. |
Effect's state.
enum PlayStrategy
| Enumerator | Value | Description |
|---|---|---|
| E_DEFAULT | 0 | By default, an effect can only play once. While it is playing, any call to PlayEffect() is ignored. |
| E_FORCE | 1 | Immediately stop the current playing instance and start a new one. |
| E_PULLED | 2 | Each call to PlayEffect() starts a new independent instance of the effect. StopEffect() simultaenously stops all pulled effects that are still playing. |
Play strategy.
Defines the haptic effect behavior when PlayEffect() is called. By default, an effect can only play once. While it is playing, any call to PlayEffect() is ignored. The force strategy immediatly stops the current playing instance and starts a new one. The pull strategy starts a new independent instance of the effect at PlayEffect(). When StopEffect() is called all pulled effects are simultaneously stopped.
Public Functions Documentation
function PlayEffect
bool PlayEffect()
Play an haptic effect based on a loaded pattern and return the effectID of this instance.
Return: true on success, false otherwise.
The instance index is positive. Each call to playEffect() using the same patternID generates a new haptic effect instance totally uncorrelated to the previous ones. The instance is destroyed once it stops playing.
The haptic effect instance reproduces the pattern with variations describes in the structure ski_effect_properties_t.More information on these parameters and how to used them can be found in the structure's description.
If the pattern is unloaded, the haptic effect is not interrupted.
function StopEffect
bool StopEffect(
float time
)
Stop the effect instance.
Parameters:
- time duration of the fadeout in seconds.
Return: true on success, false otherwise.
The effect is stop in "time" seconds with a fade out to prevent abrupt transition. If time is set to 0, no fadeout are applied and the effect is stopped as soon as possible.
function GetEffectState
State GetEffectState()
Get the current state of an effect.
Return: the current state of the effect.
If the haptic effect is invalid, the 'stop' state will be return.
Public Property Documentation
property StrategyOnPlay
PlayStrategy StrategyOnPlay;
Defines the haptic effect behavior when PlayEffect() is called.
By default, an effect can only play once. While it is playing, any call to PlayEffect() is ignore. The force strategy immediatly stops the current playing instance and starts a new one. The pull strategy starts a new independent instance of the effect at PlayEffect(). When StopEffect() is called all pulled effects are simultaneously stopped.
property PriorityLevel
int PriorityLevel;
Level of priority [1; 10] of the effect.
In case too many effects are playing simultaneously, the effect with lowest priority(10) will be muted.
property Volume
float Volume;
Volume of the pattern.
The volume is a percentage of the base volume between [0; 250]%: [0;100[% the pattern attenuated, 100% the pattern's base volume is preserved, ]100; 250]% the pattern is amplified. Too much amplification may lead to the clipping of the haptic effects, distorting them and producing audible noise.
property Speed
float Speed;
Speed of the pattern.
The speed is a time scale between [0.01; 100]: [0.01; 1[the pattern is slowed down, 1 the pattern timing is preserved, ]1; 100] the pattern is accelerated. The resulting speed between the haptic effect's and the samples' speed within the pattern cannot exceed these bounds. Slowing down or accelerating a sample too much may result in an haptically poor effect.
property RepeatCount
int RepeatCount;
Number of repetition of the pattern as the effect is playing.
If 0, the pattern is repeated indefinitely until it is either stopped with stopEffect() or reach the maxDuration value.
property RepeatDelay
float RepeatDelay;
Pause in second between two repetition of the pattern.
This value is not affected by the speed parameter.
property PlayAtTime
float PlayAtTime;
Time in the pattern at which the effect start to play.
This value need to be lower than the maxDuration. It also takes into account the repeatCount and the repeatDelay of the pattern.
property MaxDuration
float MaxDuration;
Maximum duration of the effect.
It is automatically stopped if the duration is reached without any regards for the actual state of the repeatCount. A maxDuration of 0 remove the duration limit, making the effect ables to play indefinitely.
property EffectBoost
int EffectBoost;
Boost intensity level percent.
Boost intensity level percent [-100; 100] of the effect to use instead of the default pattern value if overridePatternBoost is set to true. By using a negative value, can decrease or even nullify the global intensity boost set by the user.
property OverridePatternBoost
bool OverridePatternBoost;
Property to override the default pattern boost with a custom value for the effect.
By setting this boolean to true, the effect will use the effectBoost value instead of the default pattern value.
property HeightTranslation
float HeightTranslation;
Height in meter to translate the pattern by.
property HeadingRotation
float HeadingRotation;
Heading angle in degree to rotate the pattern by in the horizontal plan (y axis).
property TiltingRotation
float TiltingRotation;
Tilting angle in degree to rotate the pattern by in the sagittal plan (x axis).
property FrontBackInversion
bool FrontBackInversion;
Invert the direction of the pattern on the front-back axis.
Can be combine with other inversion or addition.
property UpDownInversion
bool UpDownInversion;
Invert the direction of the pattern on the up-down axis.
Can be combine with inversion or addition.
property RightLeftInversion
bool RightLeftInversion;
Invert the direction of the pattern on the right-left axis.
Can be combine with other inversion or addition.
property FrontBackAddition
bool FrontBackAddition;
Perform a front-back addition of the pattern on the front-back axis.
Overrides the frontBackInversion. Can be combine with other inversion or addition.
property UpDownAddition
bool UpDownAddition;
Perform a up-down addition of the pattern on the front-back axis.
Overrides the upDownInversion. Can be combine with other inversion or addition.
property RightLeftAddition
bool RightLeftAddition;
Perform a right-left addition of the pattern on the front-back axis.
Overrides the rightLeftInversion. Can be combine with other inversion or addition.
property Properties
SkineticDevice.EffectProperties Properties;
Structure containing all properties of an haptic effect instance.
The HapticEffect component has a base EffectProperties structure that can be override.
property TargetPattern
PatternAsset TargetPattern;
Device to which the effect will be played on.
property TargetDevice
SkineticDevice TargetDevice;
PatternAsset from which the effect will be instantiated.
A default scriptable object can be set in the inspector. However, it can also be set at runtime through scripting. Notice that the target device should have already loaded the PatternAsset before the HapticEffect can be played.
Updated on 2024-01-05 at 15:08:44 +0000