|Microsoft DirectX 9.0|
Retrieves information about an effect.
LPDIEFFECT peff, DWORD dwFlags );
- Address of a DIEFFECT structure that receives effect information. The dwSize member must be filled in by the application before calling this method.
- Flags that specify which parts of the effect information are to be retrieved. The value can be 0 or one or more of the following constants:
- The union of all other DIEP_* flags, indicating that all members of the DIEFFECT structure are being requested.
- The union of all other DIEP_* flags except the DIEP_STARTDELAY flag.
- The cAxes and rgdwAxes members should receive data. The cAxes member on entry contains the size (in DWORD) of the buffer pointed to by the rgdwAxes member. If the buffer is too small, the method returns DIERR_MOREDATA and sets cAxes to the necessary size of the buffer.
- The cAxes and rglDirection members should receive data. The cAxes member on entry contains the size (in DWORD) of the buffer pointed to by the rglDirection member. If the buffer is too small, the IDirectInputEffect::GetParameters method returns DIERR_MOREDATA and sets cAxes to the necessary size of the buffer. The dwFlags member must include at least one of the coordinate system flags (DIEFF_CARTESIAN, DIEFF_POLAR, or DIEFF_SPHERICAL). Microsoft?DirectInput?returns the direction of the effect in one of the coordinate systems you specified, converting between coordinate systems as necessary. On exit, exactly one of the coordinate system flags is set in the dwFlags member, indicating which coordinate system DirectInput used. In particular, passing all three coordinate system flags retrieves the coordinates in exactly the same format in which they were set.
- The dwDuration member should receive data.
- The lpEnvelope member points to a DIENVELOPE structure that should receive data. If the effect does not have an envelope associated with it, the lpEnvelope member is set to NULL.
- The dwGain member should receive data.
- The dwSamplePeriod member should receive data.
- The dwStartDelay member should receive data.
- The dwTriggerButton member should receive data.
- The dwTriggerRepeatInterval member should receive data.
- The lpvTypeSpecificParams member points to a buffer whose size is specified by the cbTypeSpecificParams member. On return, the buffer is filled in with the type-specific data associated with the effect, and the cbTypeSpecificParams member contains the number of bytes copied. If the buffer supplied by the application is too small to contain all the type-specific data, the method returns DIERR_MOREDATA, and the cbTypeSpecificParams member contains the required size of the buffer in bytes.
If the method succeeds, the return value is DI_OK.
If the method fails, the return value can be one of the following error values:
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 Component Object Model (COM) return value. DIERR_MOREDATA Not all the requested information fitted into the buffer. DIERR_NOTINITIALIZED The object has not been initialized.
Common errors resulting in a DIERR_INVALIDPARAM error include not setting the dwSize member of the DIEFFECT structure, passing invalid flags, or not setting up the members in the DIEFFECT structure properly in preparation for receiving the effect information. For example, if information is to be retrieved in the dwTriggerButton member, the dwFlags member must be set to either DIEFF_OBJECTIDS or DIEFF_OBJECTOFFSETS so that DirectInput knows how to describe the button.