Conditions

Conditions are forces applied in response to current sensor values within the device. In other words, conditions require information about device motion such as position or velocity of a joystick handle.

In general, conditions 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 condition does not have a predefined magnitude; the magnitude is scaled in proportion to the movement or position of the input object.

DirectInput defines the following types of condition effects:

Friction. The force is applied when the axis is moved, and depends on the defined friction coefficient.
Damper. The force increases in proportion to the velocity with which the user moves the axis.
Inertia. The force increases in proportion to the acceleration of the axis.
Spring. The force increases in proportion to the distance of the axis from a defined neutral point.

Most hardware devices do not support the application of envelopes to conditions. To determine whether a particular effect supports an envelope, check for the DIEP_ENVELOPE flag in the dwStaticParams member of the DIEFFECTINFO structure.

Conditions have the following type-specific parameters:

Offset.: The offset from the zero reading of the appropriate sensor value where the condition begins to be applied. For a spring effect, the neutral point — that is, the point along the axis where the spring would be considered at rest — would be defined by the offset for the condition. For a damper, the offset would define the greatest velocity value for which damping force is zero. Offset is not normally used for inertia or friction effects.
Coefficient.: A multiplier that scales the effect. For some devices, you can set separate coefficients for the positive and negative direction along the axis associated with the condition. For example, a flight stick controlling a damaged aircraft might move more easily to the right than to the left.
Saturation.: In force feedback, saturation is an expression of the maximum possible force for an effect. For example, suppose a flight stick has a spring condition on the x-axis. The offset is 0 and the coefficient is 10,000, so the maximum force is normally exerted when the stick is furthest from the center. But if you define a positive and negative saturation of 5,000, the force does not increase after the stick has been moved halfway to the right or left.
Deadband.: The deadband is a zone around the offset of an axis where the condition is not active. In the case of a spring that is at rest in the middle of an axis, the deadband enlarges this area of rest.

Conditions can have duration, though in most cases you would probably want to set the duration to INFINITE and stop the effect only in response to some event in the application.

To create a condition, pass one of the following values in the rguid parameter of the IDirectInputDevice2::CreateEffect method:

GUID_Spring
GUID_Damper
GUID_Inertia
GUID_Friction

You can also pass any other GUID obtained by the IDirectInputDevice2::EnumEffects method, provided the low byte of the dwEffType member of the DIEFFECTINFO structure (DIEFT_GETTYPE(dwEfftype)) is equal to DIEFT_CONDITION. In this way you can use hardware-specific conditions designed by the manufacturer.

The type-specific structure for conditions is DICONDITION. For multiple-axis conditions you may provide an array of such structures, one for each axis, or a single structure that defines the condition in the specified direction. In either case you need to set the cbTypeSpecificParams member of the DIEFFECT structure to the actual number of bytes used; that is, to sizeof(DICONDITION) * n, where n is the number of structures provided. For more information on how to use either single or multiple structures, see the Remarks for the DICONDITION structure.

An application should call the IDirectInputDevice2::GetEffectInfo method or the IDirectInputDevice2::EnumEffects method and examine the dwEffectType member of the DIEFFECTINFO structure in order to determine if the both a positive and negative coefficient and saturation for the effect are supported on the device. If the effect does not return the DIEFT_POSNEGCOEFFICIENTS flag, it will ignore the value in the lNegativeCoefficient member and the value in lPositiveCoefficient will be applied to the entire axis. Likewise, if the effect does not return the DIEFT_POSNEGSATURATION flag, it will ignore the value in the dwNegativeSaturation and the value in dwPositiveSaturation will be used as the negative saturation level. Finally, if the effect does not return the DIEFT_SATURATION flag, it will ignore both the lPositiveSaturation and lNegativeSaturation values and no saturation will be applied.

Note that you can set a coefficient to a negative value, and this has the effect of generating the force in the opposite direction. For example, for a spring effect it would cause the spring to push away from the offset point rather than pulling toward it.

You should also check the dwEffectType member for the DIEFT_DEADBAND flag, to see if deadband is supported for the condition. If it is not supported, the value in the lDeadBand member of the DICONDITION structure will be ignored.