The IDirectInputDevice2::EnumEffects method returns information about the support offered by the device for various kinds of effects.
It is important to distinguish between supported effects and created effects, or effect objects. A supported effect might be a constant force that can be shaped by an envelope. However, this effect has no properties such as magnitude, direction, duration, attack, or fade. You set these properties when you create an effect object in your application. A supported effect may be represented by many effect objects, each with different parameters¾for example, several constant forces each with different duration, magnitude, and direction.
For information on enumerating created effects, see Effect Object Enumeration.
Like other DirectInput enumerations, the IDirectInputDevice2::EnumEffects method requires a callback function; this is documented with the placeholder name DIEnumEffectsProc, but you can use a different name if you wish. This function is called for each effect enumerated. Within the function you can obtain the GUID for each effect, get information about the extent of hardware support, and create one or more effect objects whose methods you can use to manipulate the effect.
Here is a skeletal C++ example of the callback function, and the call to the IDirectInputDevice2::EnumEffects method that sets the enumeration in motion. Note that the pvRef parameter of the callback can be any 32-bit value; in this case it is a pointer to the device interface, used for getting information about effects supported by the device and for creating effect objects.
HRESULT hr;
// LPDIRECTINPUTDEVICE lpdid2; // already initialized
BOOL CALLBACK DIEnumEffectsProc(LPCDIEFFECTINFO pdei,
LPVOID pvRef)
{
LPDIRECTINPUTDEVICE2 lpdid = pvRef; // pointer to calling device
LPDIRECTINPUTEFFECT lpdiEffect; // pointer to created effect
DIEFFECT diEffect; // params for created effect
DICONSTANTFORCE diConstantForce; // type-specific parameters
// for diEffect
if (DIEF_GETTYPE(pdei->dwEffType) == DIEFFT_CONSTANTFORCE)
{
/* Here you can extract information about support for the
effect type (from pdei), and tailor your effects
accordingly. For example, the device might not support
envelopes for this type of effect. */
.
.
.
// Create one or more constant force effects.
// For each you have to initialize a DICONSTANTFORCE
// and a DIEFFECT structure.
// See detailed example at Creating an Effect
.
.
.
hr = pdid->CreateEffect(pdei->guid,
&diEffect,
&lpdiEffect,
NULL);
.
.
.
}
// And so on for other types of effect
.
.
.
return DIENUM_CONTINUE;
} // end of callback
.
.
.
// Set the callback into motion
hr = lpdid2->EnumEffects(&EnumEffectsProc,
lpdid2, DIEFT_ALL);
For more information on how to initialize an effect, see Creating an Effect.