IDirectInputEffect::SetParameters Method

Sets the characteristics of an effect.

Syntax

HRESULT SetParameters(      

    LPCDIEFFECT peff,
    DWORD dwFlags
);

Parameters

peff
DIEFFECT structure that contains effect information. The dwSize member must be filled in by the application before calling this method, as well as any members specified by corresponding bits in the dwFlags parameter.
dwFlags
Flags that specify which portions of the effect information are to be set and how the downloading of the parameters should be handled. The value can be 0 or one or more of the following constants:
DIEP_AXES
The cAxes and rgdwAxes members contain data.
DIEP_DIRECTION
The cAxes and rglDirection members contain data. The dwFlags member specifies (with DIEFF_CARTESIAN or DIEFF_POLAR) the coordinate system in which the values should be interpreted.
DIEP_DURATION
The dwDuration member contains data.
DIEP_ENVELOPE
The lpEnvelope member points to a DIENVELOPE structure that contains data. To detach any existing envelope from the effect, pass this flag and set the lpEnvelope member to NULL.
DIEP_GAIN
The dwGain member contains data.
DIEP_NODOWNLOAD
Suppress the automatic IDirectInputEffect::Download that is normally performed after the parameters are updated. See Remarks.
DIEP_NORESTART
Suppress the stopping and restarting of the effect to change parameters. See Remarks.
DIEP_SAMPLEPERIOD
The dwSamplePeriod member contains data.
DIEP_START
The effect is to be started (or restarted if it is currently playing) after the parameters are updated. By default, the play state of the effect is not altered.
DIEP_STARTDELAY
The dwStartDelay member contains data.
DIEP_TRIGGERBUTTON
The dwTriggerButton member contains data.
DIEP_TRIGGERREPEATINTERVAL
The dwTriggerRepeatInterval member contains data.
DIEP_TYPESPECIFICPARAMS
The lpvTypeSpecificParams and cbTypeSpecificParams members of the DIEFFECT structure contain the address and size of type-specific data for the effect.

Return Value

If the method succeeds, the return value can be DI_DOWNLOADSKIPPED, DI_EFFECTRESTARTED, DI_OK, DI_TRUNCATED, or DI_TRUNCATEDANDRESTARTED. If the method fails, the return value can be DIERR_NOTINITIALIZED, DIERR_INCOMPLETEEFFECT, DIERR_INPUTLOST, DIERR_INVALIDPARAM, or DIERR_EFFECTPLAYING.
DI_DOWNLOADSKIPPED The parameters of the effect were successfully updated, but the effect could not be downloaded because the associated device was not acquired in exclusive mode.
DI_EFFECTRESTARTED The effect was stopped, the parameters were updated, and the effect was restarted.
DI_OK The operation completed successfully. This value is equal to the S_OK standard Component Object Model (COM) return value.
DI_TRUNCATED The parameters of the effect were successfully updated, but some of them were beyond the capabilities of the device and were truncated to the nearest supported value.
DI_TRUNCATEDANDRESTARTED Equal to DI_EFFECTRESTARTED | DI_TRUNCATED.
DIERR_NOTINITIALIZED The object has not been initialized.
DIERR_INCOMPLETEEFFECT The effect could not be downloaded because essential information is missing. For example, no axes have been associated with the effect, or no type-specific information has been supplied.
DIERR_INPUTLOST Access to the input device has been lost. It must be reacquired.
DIERR_INVALIDPARAM An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard COM return value.
DIERR_EFFECTPLAYING The parameters were updated in memory but were not downloaded to the device because the device does not support updating an effect while it is still playing.

Remarks

The dwDynamicParams member of the DIEFFECTINFO structure for the effect specifies which parameters can be dynamically updated while the effect is playing.
The IDirectInputEffect::SetParameters method automatically downloads the effect, but this behavior can be suppressed by setting the DIEP_NODOWNLOAD flag. If automatic download has been suppressed, you can manually download the effect by invoking the IDirectInputEffect::Download method.
If the effect is playing while the parameters are changed, the new parameters take effect as if they were the parameters when the effect started.
For example, suppose a periodic effect with a duration of three seconds is started. After two seconds, the direction of the effect is changed. The effect then continues for one additional second in the new direction. The envelope, phase, amplitude, and other parameters of the effect continue smoothly, as if the direction had not changed.
In the same situation, if after two seconds the duration of the effect were changed to 1.5 seconds, the effect would stop.
Normally, if the driver cannot update the parameters of a playing effect, the driver is permitted to stop the effect, update the parameters, and then restart the effect. Passing the DIEP_NORESTART flag suppresses this behavior. If the driver cannot update the parameters of an effect while it is playing, the error code DIERR_EFFECTPLAYING is returned, and the parameters are not updated.
No more than one of the DIEP_NODOWNLOAD, DIEP_START, and DIEP_NORESTART flags should be set. (It is also valid to pass none of them.)
These three flags control download and playback behavior as follows:
If DIEP_NODOWNLOAD is set, the effect parameters are updated but not downloaded to the device.
If the DIEP_START flag is set, the effect parameters are updated and downloaded to the device, and the effect is started just as if the IDirectInputEffect::Start method had been called with the dwIterations parameter set to 1 and with no flags. (Combining the update with DIEP_START is slightly faster than calling IDirectInputEffect::Start separately, because it requires less information to be transmitted to the device.)
If neither DIEP_NODOWNLOAD nor DIEP_START is set and the effect is not playing, the parameters are updated and downloaded to the device.
If neither DIEP_NODOWNLOAD nor DIEP_START is set and the effect is playing, the parameters are updated if the device supports on-the-fly updating. Otherwise the behavior depends on the state of the DIEP_NORESTART flag. If it is set, the error code DIERR_EFFECTPLAYING is returned. If it is clear, the effect is stopped, the parameters are updated, and the effect is restarted.

DI_DOWNLOADSKIPPED	The parameters of the effect were successfully updated, but the effect could not be downloaded because the associated device was not acquired in exclusive mode.
DI_EFFECTRESTARTED	The effect was stopped, the parameters were updated, and the effect was restarted.
DI_OK	The operation completed successfully. This value is equal to the S_OK standard Component Object Model (COM) return value.
DI_TRUNCATED	The parameters of the effect were successfully updated, but some of them were beyond the capabilities of the device and were truncated to the nearest supported value.
DI_TRUNCATEDANDRESTARTED	Equal to DI_EFFECTRESTARTED \| DI_TRUNCATED.
DIERR_NOTINITIALIZED	The object has not been initialized.
DIERR_INCOMPLETEEFFECT	The effect could not be downloaded because essential information is missing. For example, no axes have been associated with the effect, or no type-specific information has been supplied.
DIERR_INPUTLOST	Access to the input device has been lost. It must be reacquired.
DIERR_INVALIDPARAM	An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard COM return value.
DIERR_EFFECTPLAYING	The parameters were updated in memory but were not downloaded to the device because the device does not support updating an effect while it is still playing.