ConditionForceEffect
ConditionForceEffect
ConditionForceEffect
ConditionForceEffect
Class
Definition
Conditional force effects are forces applied in response to current sensor values within the device. In other words, conditional force effects require information about device motion, such as position or velocity of a joystick handle. In general, conditional force effects are not associated with individual events during a game or other application. They represent ambient phenomena, such as the stiffness or looseness of a flight stick, or the tendency of a steering wheel to return to a straight-ahead position. A conditional force effect does not have a predefined magnitude. The magnitude is scaled in proportion to the movement or position of the input object.
public : sealed class ConditionForceEffect : IConditionForceEffect, IForceFeedbackEffectpublic sealed class ConditionForceEffect : IConditionForceEffect, IForceFeedbackEffectPublic NotInheritable Class ConditionForceEffect Implements IConditionForceEffect, IForceFeedbackEffect// You can use this class in JavaScript.
- Attributes
| Device family |
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v3)
|
Constructors
ConditionForceEffect(ConditionForceEffectKind) ConditionForceEffect(ConditionForceEffectKind) ConditionForceEffect(ConditionForceEffectKind) ConditionForceEffect(ConditionForceEffectKind)
Creates an instance of ConditionForceEffect.
public : ConditionForceEffect(ConditionForceEffectKind effectKind)public ConditionForceEffect(ConditionForceEffectKind effectKind)Public Sub New(effectKind As ConditionForceEffectKind)// You can use this method in JavaScript.
- effectKind
- ConditionForceEffectKind ConditionForceEffectKind ConditionForceEffectKind ConditionForceEffectKind
The type of effect to create.
Properties
Gain Gain Gain Gain
Specifies the percentage by which to reduce the force of the effect.
public : double Gain { get; set; }public double Gain { get; set; }Public ReadWrite Property Gain As double// You can use this property in JavaScript.
- Value
- double double double double
Specifies the percentage by which to reduce the force of the effect.
Kind Kind Kind Kind
The type of force feedback effect.
public : ConditionForceEffectKind Kind { get; }public ConditionForceEffectKind Kind { get; }Public ReadOnly Property Kind As ConditionForceEffectKind// You can use this property in JavaScript.
- Value
- ConditionForceEffectKind ConditionForceEffectKind ConditionForceEffectKind ConditionForceEffectKind
The type of force feedback effect.
State State State State
The current state of the effect.
public : ForceFeedbackEffectState State { get; }public ForceFeedbackEffectState State { get; }Public ReadOnly Property State As ForceFeedbackEffectState// You can use this property in JavaScript.
- Value
- ForceFeedbackEffectState ForceFeedbackEffectState ForceFeedbackEffectState ForceFeedbackEffectState
The current state of the effect.
Methods
SetParameters(Vector3, Single, Single, Single, Single, Single, Single) SetParameters(Vector3, Single, Single, Single, Single, Single, Single) SetParameters(Vector3, Single, Single, Single, Single, Single, Single) SetParameters(Vector3, Single, Single, Single, Single, Single, Single)
Sets the parameters for the conditional force feedback effect.
public : void SetParameters(Vector3 direction, float positiveCoefficient, float negativeCoefficient, float maxPositiveMagnitude, float maxNegativeMagnitude, float deadZone, float bias)public void SetParameters(Vector3 direction, Single positiveCoefficient, Single negativeCoefficient, Single maxPositiveMagnitude, Single maxNegativeMagnitude, Single deadZone, Single bias)Public Function SetParameters(direction As Vector3, positiveCoefficient As Single, negativeCoefficient As Single, maxPositiveMagnitude As Single, maxNegativeMagnitude As Single, deadZone As Single, bias As Single) As void// You can use this method in JavaScript.
- direction
- Vector3 Vector3 Vector3 Vector3
A vector describing the direction and magnitude of the effect on each axis. Each individual axis has a range of -1.0 to 1.0 and is independent of the other axes. Specifying a negative value for an axis reverses the input values from the axis.
- positiveCoefficient
- float Single Single Single
The slope of the line describing how rapidly the force increases as the input moves away from the center point in the positive direction along the specified axis. Range is from -infinity to +infinity.
- negativeCoefficient
- float Single Single Single
The slope of the line describing how rapidly the force increases as the input moves away from the center point in the negative direction along the specified axis. Range is from -infinity to +infinity.
- maxPositiveMagnitude
- float Single Single Single
The maximum magnitude of the force feedback as the input moves away from the center point in the positive direction along the specified axis. Range is from 0 to 1.0.
- maxNegativeMagnitude
- float Single Single Single
The maximum magnitude of the force feedback as the input moves away from the center point in the negative direction along the specified axis. Range is from 0 to 1.0.
- deadZone
- float Single Single Single
Specifies the value below which the force feedback is not applied. Range is from 0.0 to 1.0 and is applied asymmetrically around the center point.
- bias
- float Single Single Single
The offset to the center point in effect calculations. Range is from -1.0 to 1.0.
Examples
// Create a spring effect and load it into the device. This is an async operation
// since it might take a brief amount of time for the driver to complete this.
ConditionForceEffect ^ springEffect = ref new ConditionForceEffect(ConditionEffectKind::Spring);
if (springEffect)
{
IAsyncAction ^ action = motor->LoadEffectAsync(springEffect);
concurrency::create_task(action).then([=]()
{
// Make sure the effect was loaded successfully. There is a finite amount
// of storage available for effects in the hardware, so this is expected
// to fail if there is not enough room. Alternatively, the motor might
// not support the requested effect (although this is rare).
if (action->Status == AsyncStatus::Completed)
{
// Set the parameters for the spring effect. Note how the parameters
// can be modified after the effect has been loaded into the hardware.
springEffect->SetParameters(
{ 1.0f, 0.0f, 0.0f }, // Unit vector indicating the effect applies to the X axis
1.0f, -1.0f, // Full strength when the wheel is turned to its maximum angle
0.3f, -0.3f, // Limit the maximum feedback force to 30%
0.025f, // Apply a small dead zone when the wheel is centered
0.0f); // Equal force in both directions
// Go ahead and start the effect, since we want this running all the time
springEffect->StartEffect();
}
});
}
Remarks
The following image illustrates the effects of the arguments to SetParameters:
In the image, all coefficient values are positive. A negative value for the coefficient will cause the force (the green line) to go negative below the orange axis line, effectively, reversing the direction of the force. This is not recommended because unless done carefully it will typically result in a positive feedback loop that will cause the motor to saturate in that direction. Magnitude and dead zone values are always positive, and symmetrical about their respective axes. (This is illustrated for the dead zone, but the magnitude works the same way – a value of 0.5 limits the feedback force to anywhere between -0.5 and +0.5.) The bias is shown here at 0.0, but changing the value just slides the medium orange line one way or the other. Note that this does not affect the slope of the green lines, defined by the coefficient values.
Start() Start() Start() Start()
Starts the force feedback effect.
public : void Start()public void Start()Public Function Start() As void// You can use this method in JavaScript.