Platform SDK: DirectX |
Hardware drivers can support special effects that do not fit into the categories defined by DirectInput. The type-specific parameters for these effects can be hard-coded or modifiable by the application.
If type-specific parameters are modifiable, the application developer must obtain a header file declaring the data structure required by the effect.
The hardware vendor must provide a GUID identifying the device-specific effect and might provide a custom structure for the type-specific parameters of the effect. Your application then must initialize a DIEFFECT structure and a type-specific structure, as with any other effect. You then call the IDirectInputDevice7::CreateEffect method, passing the device-specific GUID and a pointer to the DIEFFECT structure.
When you obtain information about a device-specific effect in a DIEFFECTINFO structure, the low byte of the dwEffType member (DIEFT_GETTYPE(dwEfftype)) indicates into which of the predefined DirectInput effect categories (constant force, ramp force, periodic, or condition) the effect falls. If it does not fall into any of the predefined categories, the value is DIEFT_HARDWARE.
If a device-specific effect falls into one of the predefined categories, the lpvTypeSpecificParams member of the DIEFFECT structure must point to the corresponding DICONSTANTFORCE, DIRAMPFORCE, DIPERIODIC, or DICONDITION structure, and the cbTypeSpecificParams member must be equal to the size of that structure.
If the (DIEFT_GETTYPE(dwEfftype) == DIEFT_HARDWARE), the values of the lpvTypeSpecificParams and cbTypeSpecificParams members depend on whether the effect requires custom type-specific parameters. If it does, these values must refer to the appropriate structure defined in the manufacturer's header file and declared and initialized by your application. If the effect does not require custom parameters—that is, if the dwStaticParms member of the DIEFFECTINFO structure for the hardware effect does not have the DIEP_TYPESPECIFICPARAMS flag—lpvTypeSpecificParams must be NULL and cbTypeSpecificParams must be 0.
DirectInput passes the GUID and the DIEFFECT structure to the device driver for verification. If the GUID is unknown, the device returns DIERR_DEVICENOTREG. If the GUID is known but the type-specific data is incorrect for that effect, the device returns DIERR_INVALIDPARAM.
DirectX for Visual Basic does not support hardware effects that require custom type-specific parameters.
The hardware vendor must provide a GUID identifying the device-specific effect. Your application then must initialize a DIEFFECT type, as with any other effect. You then pass this type, along with the GUID, to the DirectInputDevice.CreateEffect method.
When you obtain information about a device-specific effect in a DirectInputEnumEffects enumeration, the low byte of the return value of DirectInputEnumEffects.GetType indicates into which of the predefined DirectInput effect categories (constant force, ramp force, periodic, or condition) the effect falls. If it does not fall into any of the predefined categories, the value is DIEFT_HARDWARE.
If a device-specific effect falls into one of the predefined categories, the DIEFFECT type must be initialized, as it would be for a standard force of that category. For example, if the effect type is DIEFT_CONSTANTFORCE, the constantForce member must be initialized.
DirectInput passes the GUID and the DIEFFECT structure to the device driver for verification. If the GUID is unknown, the device returns DIERR_DEVICENOTREG. If the GUID is known but the type-specific data is incorrect for that effect, the device returns DIERR_INVALIDPARAM.