IDirectInputDevice2::CreateEffect

The IDirectInputDevice2::CreateEffect method creates and initializes an instance of an effect identified by the effect GUID.

HRESULT CreateEffect(
  REFGUID rguid,                 
  LPCDIEFFECT lpeff,             
  LPDIRECTINPUTEFFECT * ppdeff,  
  LPUNKNOWN punkOuter            
);

Parameters

rguid
The identity of the effect to be created. This can be a predefined effect GUID, or it can be a GUID obtained from IDirectInputDevice2::EnumEffects.

The following effect GUIDs are defined:

GUID_ConstantForce
GUID_RampForce
GUID_Square
GUID_Sine
GUID_Triangle
GUID_SawtoothUp
GUID_SawtoothDown
GUID_Spring
GUID_Damper
GUID_Inertia
GUID_Friction
GUID_CustomForce

lpeff
A DIEFFECT structure that provides parameters for the created effect. This parameter is optional. If it is NULL, then the effect object is created without parameters. The application must then call the IDirectInputEffect::SetParameters method to set the parameters of the effect before it can download the effect.
ppdeff
Location of the pointer to the IDirectInputEffect interface, if successful.
punkOuter
The controlling unknown for COM aggregation. The value is NULL if the interface is not aggregated. Most callers will pass NULL.

Return Values

If the method succeeds, the return value is DI_OK or S_FALSE.

If the method fails, the return value may be one of the following error values:

DIERR_DEVICENOTREG
DIERR_DEVICEFULL
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

If the return value is S_FALSE, the effect was created and the parameters of the effect were updated, but the effect could not be downloaded because the associated device is not acquired in exclusive mode.

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in dinput.h.
  Import Library: Use dinput.lib.