DIEFFECT Structure

Used by the IDirectInputDevice8::CreateEffect method to initialize a new IDirectInputEffect Interface object. It is also used by the IDirectInputEffect::SetParameters and IDirectInputEffect::GetParameters methods.

Syntax

typedef struct DIEFFECT {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwDuration;
    DWORD dwSamplePeriod;
    DWORD dwGain;
    DWORD dwTriggerButton;
    DWORD dwTriggerRepeatInterval;
    DWORD cAxes;
    LPDWORD rgdwAxes;
    LPLONG rglDirection;
    LPDIENVELOPE lpEnvelope;
    DWORD cbTypeSpecificParams;
    LPVOID lpvTypeSpecificParams;
    DWORD dwStartDelay;
} DIEFFECT, *LPDIEFFECT;

Members

• dwSize
  Specifies the size, in bytes, of the structure. This member must be initialized before the structure is used.

• dwFlags
  Flags associated with the effect. This value can be a combination of one or more of the following values:

  • DIEFF_CARTESIAN
    The values of rglDirection are to be interpreted as Cartesian coordinates.
  • DIEFF_OBJECTIDS
    The values of dwTriggerButton and rgdwAxes are object identifiers as obtained by IDirectInputDevice8::EnumObjects.
  • DIEFF_OBJECTOFFSETS
    The values of dwTriggerButton and rgdwAxes are data format offsets.
  • DIEFF_POLAR
    The values of rglDirection are to be interpreted as polar coordinates.
  • DIEFF_SPHERICAL
    The values of rglDirection are to be interpreted as spherical coordinates.

• dwDuration
  The total duration of the effect, in microseconds. If this value is INFINITE, the effect has infinite duration. If an envelope has been applied to the effect, the attack is applied, followed by an infinite sustain.

• dwSamplePeriod
  The period at which the device should play back the effect, in microseconds. A value of 0 indicates that the default playback sample rate should be used.

  If the device is not capable of playing back the effect at the specified rate, it chooses the supported rate that is closest to the requested value.

  Setting a custom dwSamplePeriod can be used for special effects. For example, playing a sine wave at an artificially large sample period results in a rougher texture.

• dwGain
  The gain to be applied to the effect, in the range from 0 through 10,000. The gain is a scaling factor applied to all magnitudes of the effect and its envelope.

• dwTriggerButton
  The identifier or offset of the button to be used to trigger playback of the effect. The flags DIEFF_OBJECTIDS and DIEFF_OBJECTOFFSETS determine the semantics of the value. If this member is set to DIEB_NOTRIGGER, no trigger button is associated with the effect.

• dwTriggerRepeatInterval
  The interval, in microseconds, between the end of one playback and the start of the next when the effect is triggered by a button press and the button is held down. Setting this value to INFINITE suppresses repetition.

  Support for trigger repeat for an effect is indicated by the presence of the DIEP_TRIGGERREPEATINTERVAL flag in the dwStaticParams member of the DIEffectInfo structure.

• cAxes
  Number of axes involved in the effect. This member must be filled in by the calling application if changing or setting the axis list or the direction list.

  The number of axes for an effect cannot be changed once it has been set.

• rgdwAxes
  Pointer to a DWORD array (of cAxes elements) containing identifiers or offsets identifying the axes to which the effect is to be applied. The flags DIEFF_OBJECTIDS and DIEFF_OBJECTOFFSETS determine the semantics of the values in the array.

  The list of axes associated with an effect cannot be changed once it has been set.

  No more than 32 axes can be associated with a single effect.

• rglDirection
  Pointer to a LONG array (of cAxes elements) containing either Cartesian coordinates, polar coordinates, or spherical coordinates. The flags DIEFF_CARTESIAN, DIEFF_POLAR, and DIEFF_SPHERICAL determine the semantics of the values in the array.

  If Cartesian, each value in rglDirection is associated with the corresponding axis in rgdwAxes.

  If polar, the angle is measured in hundredths of degrees from the (0, - 1) direction, rotated in the direction of (1, 0). This usually means that north is away from the user, and east is to the user's right. The last element is not used.

  If spherical, the first angle is measured in hundredths of a degree from the (1, 0) direction, rotated in the direction of (0, 1). The second angle (if the number of axes is three or more) is measured in hundredths of a degree toward (0, 0, 1). The third angle (if the number of axes is four or more) is measured in hundredths of a degree toward (0, 0, 0, 1), and so on. The last element is not used.

• lpEnvelope
  Optional pointer to a DIENVELOPE structure that describes the envelope to be used by this effect. Not all effect types use envelope. If no envelope is to be applied, the member should be set to NULL.

• cbTypeSpecificParams
  Number of bytes of additional type-specific parameters for the corresponding effect type.

• lpvTypeSpecificParams
  Pointer to type-specific parameters, or NULL if there are no type-specific parameters.

  If the effect is of type DIEFT_CONDITION, this member contains a pointer to an array of DICONDITION structures that define the parameters for the condition. A single structure may be used, in which case the condition is applied in the direction specified in the rglDirection array. Otherwise, there must be one structure for each axis, in the same order as the axes in rgdwAxes array. If a structure is supplied for each axis, the effect should not be rotated; you should use the following values in the rglDirection array:

  • DIEFF_SPHERICAL: 0, 0, ...

  • DIEFF_POLAR: 9000, 0, ...

  • DIEFF_CARTESIAN: 1, 0, ...

  If the effect is of type DIEFT_CUSTOMFORCE, this member contains a pointer to a DICUSTOMFORCE structure that defines the parameters for the custom force.

  If the effect is of type DIEFT_PERIODIC, this member contains a pointer to a DIPERIODIC structure that defines the parameters for the effect.

  If the effect is of type DIEFT_CONSTANTFORCE, this member contains a pointer to a DICONSTANTFORCE structure that defines the parameters for the constant force.

  If the effect is of type DIEFT_RAMPFORCE, this member contains a pointer to a DIRAMPFORCE structure that defines the parameters for the ramp force.

• dwStartDelay
  Time (in microseconds) that the device should wait after an IDirectInputEffect::Start call before playing the effect. If this value is 0, effect playback begins immediately. This member is not present in versions prior to DirectX 7.0.

Remarks