Step 3: Enumerating Supported Effects

Now that you have successfully enumerated and created a force-feedback device, you can enumerate the effect types it supports.

Effect enumeration is not strictly necessary if you want to create only standard effects that will be available on any device, such as constant forces. When creating the effect object, you can identify the desired effect type simply by using one of the predefined GUIDs, such as GUID_ConstantForce. For a complete list of these identifiers, see IDirectInputDevice8::CreateEffect.

Another more flexible approach is to enumerate supported effects of a particular type, then obtain the GUID for the effect from the callback function. You could use the callback to obtain more information about the device's support for the effect— for example, whether it supports an envelope—but in this tutorial you obtain only the effect GUID.

First, create the callback function that Microsoft® DirectInput® calls for each effect enumerated. For information on this standard callback, see DIEnumEffectsCallback. You can give the function any name you like.

BOOL  EffectFound = FALSE;  // global flag
 
BOOL CALLBACK DIEnumEffectsProc(LPCDIEFFECTINFO pei, LPVOID pv)
{
    *((GUID *)pv) = pei->guid;
    EffectFound = TRUE;
    return DIENUM_STOP;  // one is enough
}
 

The GUID variable pointed to by the application-defined value pv is assigned the value passed in the DIEFFECTINFO structure created by DirectInput for the effect.

To obtain the effect GUID, set the callback in motion by calling the IDirectInputDevice8::EnumEffects method, as follows:

HRESULT  hr;
GUID     guidEffect;
 
hr = g_lpDIDevice->EnumEffects(
                         (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
                          &guidEffect, 
                          DIEFT_PERIODIC);
if (FAILED(hr))
{
    // Note that success does not mean that any effects were found,
    // only that the process went smoothly.
}
 

Note that you pass the address of a GUID variable, guidEffect, to the EnumEffects method. This address is passed in turn to the callback as the pv parameter. You also restrict the enumeration to periodic effects by setting the flag DIEFT_PERIODIC.

Once your application can enumerate supported effects, go to Step 4: Creating an Effect.