DIEFFECT

The DIEFFECT structure is used by the IDirectInputDevice2::CreateEffect method to initialize a new IDirectInputEffect object. It is also used by the IDirectInputEffect::SetParameters and IDirectInputEffect::GetParameters methods.

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; 
 } DIEFFECT, *LPDIEFFECT; 
 
typedef const DIEFFECT *LPCDIEFFECT;
 

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 IDirectInputDevice::EnumObjects.

DIEFF_OBJECTOFFSETS

The values of dwTriggerButton and rgdwAxes are data format offsets, relative to the data format selected by IDirectInput::SetDataFormat.

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, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain.

dwSamplePeriod

The period at which the device should play back the effect, in microseconds. A value of zero 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 will choose 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 0 to 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, then 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 caller 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 or polar coordinates. The flags DIEFF_CARTESIAN, DIEFF_POLAR, and DIEFF_SPHERICAL determine the semantics of the values in the array.

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

If polar, then 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, then the first angle is measured in hundredths of degrees 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 degrees towards (0, 0, 1). The third angle (if the number of axes is four or more) is measured in hundredths of degrees towards (0, 0, 0, 1), and so on. The last element is not used.

Note  The rglDirection array must contain cAxes entries, even if polar or spherical coordinates are given. In these cases the last element in the rglDirection array is reserved for future use and must be zero.

lpEnvelope

Optional pointer to a DIENVELOPE structure that describes the envelope to be used by this effect. Note that not all effect types use envelopes. If no envelope is to be applied, then 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, then 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, then 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, then this member contains a pointer to a DIPERIODIC structure that defines the parameters for the effect.

If the effect is of type DIEFT_CONSTANTFORCE, then 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, then this member contains a pointer to a DIRAMPFORCE structure that defines the parameters for the ramp force.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dinput.h.