Effect Enumeration

The IDirectInputDevice8::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 is a basic type which a device is capable of playing, such as a constant force. However, a constant force by itself has no properties such as magnitude, direction, duration, attack, or fade. These properties are set when you create a specific effect object in your application by shaping the raw effect type with an envelope or setting the values of a DIEFFECT structure. A supported effect can be represented by many effect objects, each with different parameters - for example, several constant forces, each with different duration, magnitude, and direction.

For information about enumerating created effects, see Effect Object Enumeration.

Like other DirectInput enumerations, the IDirectInputDevice8::EnumEffects method requires a callback function. This is documented with the placeholder name DIEnumEffectsCallback, but you can use a different name if you prefer. This function is called for each effect enumerated. Within the function you can obtain the globally unique identifier (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.

The following code example sets the enumeration in motion. Assume that g_lpdid is an initialized pointer to the IDirectInputDevice8 Interface interface of the device.

 
HRESULT hr = g_lpdid->EnumEffects(&DIEnumEffectsCallback,
        g_lpdid, DIEFT_ALL);

A skeletal callback is shown in the following code. The pvRef parameter of the callback could be any 32-bit value, but in this case it is a pointer to the device interface (the global g_lpdid in the previous example), which is used for getting information about effects supported by the device and for creating effect objects.

BOOL CALLBACK DIEnumEffectsCallback(LPCDIEffectInfo pdei, 
                                LPVOID pvRef)
{
    HRESULT              hr;
    LPDIRECTINPUTDEVICE8 lpdid = (LPDIRECTINPUTDEVICE8)pvRef;   
// Pointer to calling device
    LPDIRECTINPUTEFFECT  lpdiEffect;      // Pointer to created effect
    DIEFFECT             diEffect;        // Params for created effect
    DICONSTANTFORCE      diConstantForce; // Type-specific parameters
 

    if (DIEFT_GETTYPE(pdei->dwEffType) == DIEFT_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. 
       .
       .
       .
        hr = lpdid->CreateEffect(pdei->guid,
                                &diEffect,
                                &lpdiEffect,
                                NULL);
       .
       .
       .
    }
    // And so on for other types of effect
   .
   .
   .
 
    return DIENUM_CONTINUE;
    }  // End of callback

For a detailed example of creating an effect, and for more information about how to initialize an effect, see Creating an Effect.