Share via

DownloadEffect routine

  • Article

The DownloadEffect callback sends an effect to the device.

Syntax

HRESULT DownloadEffect(
   DWORD      dwDeviceID,
   DWORD      dwInternalEffectType,
   LPDWORD    lpdwDnloadID,
   LPDIEFFECT lpEffect,
   DWORD      dwFlags
);

Parameters

dwDeviceID

Indicates the external joystick number being addressed.

dwInternalEffectType

Indicates the dwEffectId member of the DIEFFECTATTRIBUTES structure which is associated with the effect that the application is attempting to create. The DIEFFECTATTRIBUTES structure is stored in the registry under the registry key for the corresponding effect as a 32-bit value. DirectInput passes this 32-bit value to the driver with no interpretation.

lpdwDnloadID

On entry, this parameter points to the handle of the effect being downloaded. If the parameter points to a zero, then a new effect is downloaded. On exit, the DWORD pointed to by this parameter contains the new effect handle. On failure, the DWORD pointed to by this parameter is set to zero if the effect is lost, or left alone if the effect is still valid with its old parameters. Note that zero is never a valid effect handle.

lpEffect

Points to the new parameters for the effect. The axis and button values have been converted to object identifiers, which consist of the following:

One type specifier:

DIDFT_RELAXIS

DIDFT_ABSAXIS

DIDFT_PSHBUTTON

DIDFT_TGLBUTTON

DIDFT_POV

One instance identifier:

DIDFT_MAKEINSTANCE(n)

Other bits in the object identifier are reserved and should be ignored.

For example, 0x02000104 = DIDFT_PSHBUTTON | DIDFT_MAKEINSTANCE(1) | and so on

This value indicates that the effect uses button 1.

dwFlags

Specifies which portions of the effect information have changed from the effect already on the device. This information is passed to drivers to allow for the optimization of effect modification. If an effect is being modified, a driver may be able to update the effect in its original position and transmit to the device only the information that has changed. Drivers are not, however, required to implement this optimization. All members of the DIEFFECT structure that are pointed to by the peff parameter are valid, and a driver may choose simply to update all parameters of the effect at each download. (For information about the DIEFFECT structure, see the DirectInput section of the stand alone DirectX SDK. There may be zero, one, or more of the following:

  • DIEP_DURATION
    Indicates the dwDuration member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download.

  • DIEP_SAMPLEPERIOD
    Indicates the dwSamplePeriod member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download.

  • DIEP_GAIN
    Indicates the dwGain member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download.

  • DIEP_TRIGGERBUTTON
    Indicates the dwTriggerButton member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download.

  • DIEP_TRIGGERREPEATINTERVAL
    Indicates the dwTriggerRepeatInterval member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download.

  • DIEP_AXES
    Indicates the cAxes and rgdwAxes members of the DIEFFECT structure are being downloaded for the first time or have changed since their last download.

  • DIEP_DIRECTION
    Indicates the cAxes and rglDirection members of the DIEFFECT structure are being downloaded for the first time or have changed since their last download. (The dwFlags member of the DIEFFECT structure specifies, through DIEFF_CARTESIAN or DIEFF_POLAR, the coordinate system in which the values should be interpreted.)

  • DIEP_ENVELOPE
    Indicates the lpEnvelope member of the DIEFFECT structure is being downloaded for the first time or has changed since its last download. If this flag is set and the lpEnvelope member is a NULL pointer, then the effect is being created with no envelope, or the existing envelope is being deleted.

  • DIEP_TYPESPECIFICPARAMS
    Indicates the cbTypeSpecificParams and lpTypeSpecificParams members of the DIEFFECT structure are being downloaded for the first time or have changed since their last download.

  • DIEP_START
    Indicates that the effect is to be restarted from the beginning after the parameters of the effect have been updated. Note that the DIEP_NODOWNLOAD flag overrides the DIEP_START flag.

  • DIEP_NORESTART
    If this flag is not specified, the effect device driver is permitted to restart the effect if doing so is necessary to change the specified parameters. Note that the DIEP_NODOWNLOAD and DIEP_START flags override this flag.

  • DIEP_NODOWNLOAD
    Suppresses the automatic download that is normally performed after the parameters are updated. If this flag is set, the driver should validate parameters without performing an actual download.

Return value

Returns S_OK if successful; otherwise, returns an error code.

Requirements

Target platform

Header

 Dinputd.h

 

 

Send comments about this topic to Microsoft