Creating an Effect

You create an effect object by using the IDirectInputDevice2::CreateEffect method, as in the following C++ example, where pdev2 points to an instance of the interface. This example creates a very simple effect that will pull the joystick away from the user at full force for half a second.

HRESULT  hr;
LPDIRECTINPUTEFFECT lpdiEffect;  // receives pointer to created effect
DIEFFECT diEffect;               // parameters for created effect
 
DWORD    dwAxes[2] = { DIJOFS_X, DIJOFS_Y };
LONG     lDirection[2] = { 18000, 0 };
 
DICONSTANTFORCE diConstantForce; 
 
diConstantForce.lMagnitude = DI_FFNOMINALMAX;   // full force
 
diEffect.dwSize = sizeof(DIEFFECT); 
diEffect.dwFlags = DIEFF_POLAR | DIEFF_OBJECTOFFSETS; 
diEffect.dwDuration = 0.5 * DI_SECONDS;
diEffect.dwSamplePeriod = 0;               // = default 
diEffect.dwGain = DI_FFNOMINALMAX;         // no scaling
diEffect.dwTriggerButton = DIEB_NOTRIGGER; // not a button response
diEffect.dwTriggerRepeatInterval = 0;      // not applicable
diEffect.cAxes = 2; 
diEffect.rgdwAxes = &dwAxes; 
diEffect.rglDirection = &lDirection; 
diEffect.lpEnvelope = NULL; 
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;  
 
hr = pdev2->CreateEffect(GUID_ConstantForce,
                         &diEffect,
                         &lpdiEffect,
                         NULL);
 

In the method call, the first parameter identifies the supported effect with which the created effect is to be associated. The example uses one of the predefined GUIDs found in Dinput.h. Note that if you use a predefined GUID, the call will fail if the device doesn't support the effect.

The second parameter sets the parameters as specified in the DIEFFECT structure.

The third parameter receives a pointer to the effect object if the call is successful.

The DIEFF_POLAR flag specifies the type of coordinates used for the direction of the force. (See Effect Direction.) It is combined with DIEFF_OBJECTOFFSETS, which indicates that any buttons or axes used in other members will be identified by their offsets within the DIDATAFORMAT structure for the device. The alternative is to use the DIEFF_OBJECTIDS flag, signifying that buttons and axes will be identified by the dwType member of the DIDEVICEOBJECTINSTANCE structure returned for the object when it was enumerated with the IDirectInputDevice::EnumObjects method.

For more information on the members of the DIEFFECT structure, see Effect Direction.