The IDirectInputEffect::Start method begins playing an effect. If the effect is already playing, it is restarted from the beginning. If the effect has not been downloaded or has been modified since its last download, then it will be downloaded before being started. This default behavior can be suppressed by passing the DIES_NODOWNLOAD flag.
HRESULT Start(
DWORD dwIterations,
DWORD dwFlags
);
Parameters
dwIterations
Number of times to play the effect in sequence. The envelope is re-articulated with each iteration.
To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE. To play the effect until explicitly stopped without re-articulating the envelope, modify the effect parameters with the IDirectInputEffect::SetParameters method and change its dwDuration member to INFINITE.
dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:
DIES_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
DIES_NODOWNLOAD
Do not automatically download the effect.
Return Values
If the method succeeds, the return value is DI_OK.
If the method fails, the return value may be one of the following error values:
| DIERR_INVALIDPARAM |
| DIERR_INCOMPLETEEFFECT |
| DIERR_NOTEXCLUSIVEACQUIRED |
| DIERR_NOTINITIALIZED |
| DIERR_UNSUPPORTED |
Remarks
The device must be acquired at the exclusive cooperative level for this method to succeed.
Not all devices support multiple iterations.
QuickInfo
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 OSR2 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in dinput.h.
Import Library: Use dinput.lib.