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.