Step 3: Enumerating Supported Effects

Now that you've 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 IDirectInputDevice2::CreateEffect.)

Another, more flexible approach is to enumerate supported effects of a particular type, and obtain the GUID for the effect from the callback function. This is the approach taken in the FFDonuts sample application in the DirectX code samples in the Platform SDK, and you'll adopt it here as well. You could, of course, 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'll get only the effect GUID.

First, create the callback function that will be called by DirectInput for each effect enumerated. For information on this standard callback, see DIEnumEffectsProc. 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.

In order to obtain the effect GUID, you set the callback in motion by calling the IDirectInputDevice2::EnumEffects method, as follows:

HRESULT  hr;
GUID     guidEffect;

hr = g_lpdid2Game->EnumEffects( 
     (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
     &guidEffect, 
     DIEFT_PERIODIC);
if (FAILED(hr))
  {
  OutputDebugString("Effect enumeration failed\n");
  // Note: success doesn't mean 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.