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.
The saturation point is the point on an axis at which a force is considered to be at its maximum or minimum. Increases or decreases in magnitude beyond this point are ignored. For example, suppose a flight stick has a spring condition on the x-axis. The formula for the condition causes the force to keep increasing with the distance of the axis from the neutral point, but on some devices you could set the positive and negative saturation points so that the full force of the effect is reached when the stick has been moved halfway to the right or left, and does not increase beyond that point.
Deadband.
The deadband is a zone in an axis where a condition does not apply. Taking the spring example again, the deadband would define a zone within which the axis was considered to be at the neutral point, and no force would be applied.
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 IDirectInputDevice2::GetEffectInfo or IDirectInputDevice2::EnumEffects 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.