DIEffectInfo Structure

  • Article

Used by the IDirectInputDevice8::EnumEffects and IDirectInputDevice8::GetEffectInfo methods to return information about a particular effect supported by a device.

Syntax

typedef struct DIEffectInfo {
    DWORD dwSize;
    GUID guid;
    DWORD dwEffType;
    DWORD dwStaticParams;
    DWORD dwDynamicParams;
    TCHAR tszName[MAX_PATH];
} DIEffectInfo, *LPDIEffectInfo;

Members

  • dwSize
    Size of the structure in bytes. During enumeration, the application can inspect this value to determine how many members of the structure are valid. This member must be initialized before the structure is passed to the IDirectInputDevice8::GetEffectInfo method.

  • guid
    Identifier of the effect.

  • dwEffType
    Zero or more of the following values:

    • DIEFT_ALL
      Valid only for IDirectInputDevice8::EnumEffects. Enumerate all effects, regardless of type. This flag cannot be combined with any of the other flags.

    • DIEFT_CONDITION
      The effect represents a condition. When creating or modifying a condition, the lpvTypeSpecificParams member of the DIEFFECT structure must point to an array of DICONDITION structures (one per axis), and the cbTypeSpecificParams member must be set to cAxis * sizeof(DICONDITION).

      Not all devices support all the parameters of conditions. Check the effect capability flags to determine which capabilities are available.

      The flag can be passed to IDirectInputDevice8::EnumEffects to restrict the enumeration to conditions.

    • DIEFT_CONSTANTFORCE
      The effect represents a constant-force effect. When creating or modifying a constant-force effect, the lpvTypeSpecificParams member of the DIEFFECT must point to a DICONSTANTFORCE structure, and the cbTypeSpecificParams member must be set to sizeof(DICONSTANTFORCE).

      The flag can be passed to IDirectInputDevice8::EnumEffects to restrict the enumeration to constant-force effects.

    • DIEFT_CUSTOMFORCE
      The effect represents a custom-force effect. When creating or modifying a custom-force effect, the lpvTypeSpecificParams member of the DIEFFECT structure must point to a DICUSTOMFORCE structure, and the cbTypeSpecificParams member must be set to sizeof(DICUSTOMFORCE).

      The flag can be passed to IDirectInputDevice8::EnumEffects to restrict the enumeration to custom-force effects.

    • DIEFT_DEADBAND
      The effect generator for this condition effect supports the lDeadBand parameter.

    • DIEFT_FFATTACK
      The effect generator for this effect supports the attack envelope parameter. If the effect generator does not support attack, the attack level and attack time parameters of the DIENVELOPE structure are ignored by the effect.

      If neither DIEFT_FFATTACK nor DIEFT_FFFADE is set, the effect does not support an envelope, and any provided envelope is ignored.

    • DIEFT_FFFADE
      The effect generator for this effect supports the fade parameter. If the effect generator does not support fade, the fade level and fade time parameters of the DIENVELOPE structure are ignored by the effect.

      If neither DIEFT_FFATTACK nor DIEFT_FFFADE is set, the effect does not support an envelope, and any provided envelope is ignored.

    • DIEFT_HARDWARE
      The effect represents a hardware-specific effect. For additional information about using a hardware-specific effect, consult the hardware documentation.

      The flag can be passed to the IDirectInputDevice8::EnumEffects method to restrict the enumeration to hardware-specific effects.

    • DIEFT_PERIODIC
      The effect represents a periodic effect. When creating or modifying a periodic effect, the lpvTypeSpecificParams member of the DIEFFECT structure must point to a DIPERIODICstructure, and the cbTypeSpecificParams member must be set to sizeof(DIPERIODIC).

      The flag can be passed to IDirectInputDevice8::EnumEffects to restrict the enumeration to periodic effects.

    • DIEFT_POSNEGCOEFFICIENTS
      The effect generator for this effect supports two coefficient values for conditions, one for the positive displacement of the axis and one for the negative displacement of the axis. If the device does not support both coefficients, the negative coefficient in the DICONDITION structure is ignored, and the positive coefficient is used in both directions.

    • DIEFT_POSNEGSATURATION
      The effect generator for this effect supports a maximum saturation for both positive and negative force output. If the device does not support both saturation values, the negative saturation in the DICONDITION structure is ignored, and the positive saturation is used in both directions.

    • DIEFT_RAMPFORCE
      The effect represents a ramp-force effect. When creating or modifying a ramp-force effect, the lpvTypeSpecificParams member of the DIEFFECT structure must point to a DIRAMPFORCE structure, and the cbTypeSpecificParams member must be set to sizeof(DIRAMPFORCE).

      The flag can be passed to IDirectInputDevice8::EnumEffects to restrict the enumeration to ramp-force effects.

    • DIEFT_SATURATION
      The effect generator for this effect supports the saturation of condition effects. If the effect generator does not support saturation, the force generated by a condition is limited only by the maximum force that the device can generate.

    • DIEFT_STARTDELAY
      The effect has a delay before it plays rather than beginning immediately. This can be used to offset effects so that they play in sequence.

  • dwStaticParams
    Zero or more DIEP_* values describing the parameters supported by the effect. For example, if DIEP_ENVELOPE is set, the effect supports an envelope. For a list of possible values, see IDirectInputEffect::GetParameters.

    It is not an error for an application to attempt to use effect parameters that are not supported by the device. The unsupported parameters are ignored.

    This information is provided to enable the application to tailor its use of force feedback to the capabilities of the specific device.

  • dwDynamicParams
    Zero or more DIEP_* values denoting parameters of the effect that can be modified while the effect is playing. For a list of possible values, see IDirectInputEffect::GetParameters.

    If an application attempts to change a parameter while the effect is playing and the driver does not support modifying that effect dynamically, the driver is permitted to stop the effect, update the parameters, then restart it. For more information, see IDirectInputEffect::SetParameters.

  • tszName
    Name of the effect; for example, "Sawtooth up" or "Constant force".

Remarks

Use the DIDFT_GETTYPE macro to extract the effect type from the dwEffType flags.