Function

FFEffectGetParameters(_:_:_:)

Retrieves information about an effect.

Declaration

func FFEffectGetParameters(_ effectReference: FFEffectObjectReference!, _ pFFEffect: UnsafeMutablePointer<FFEFFECT>!, _ flags: FFEffectParameterFlag) -> HRESULT

Parameters

efffectRef

An opaque reference handle to an effect object. This is obtained from a previous call to FFDeviceCreateEffect.

pFFEffect

Address of a FFEFFECT structure that receives effect information. The dwSize member must be filled in by the application before calling this method.

flags

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:

FFEP_ALLPARAMS

The union of all other FFEP_* flags, indicating that all members of the FFEFFECT structure are being requested.

FFEP_AXES

The cAxes and rgdwAxes members should receive data. The cAxes member on entry contains the size (in DWORDs) of the buffer pointed to by the rgdwAxes member. If the buffer is too small, the method returns FFERR_MOREDATA and sets cAxes to the necessary size of the buffer.

FFEP_DIRECTION

The cAxes and rglDirection members should receive data. The cAxes member on entry contains the size (in DWORDs) of the buffer pointed to by the rglDirection member. If the buffer is too small, the GetParameters method returns FFERR_MOREDATA and sets cAxes to the necessary size of the buffer.

The dwFlags member must include at least one of the coordinate system flags (FFEFF_CARTESIAN, FFEFF_POLAR, or FFEFF_SPHERICAL). The API 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 the FF API used. In particular, passing all three coordinate system flags retrieves the coordinates in exactly the same format in which they were set.

FFEP_DURATION

The dwDuration member should receive data.

FFEP_ENVELOPE

The lpEnvelope member points to a FFENVELOPE structure that should receive data. If the effect does not have an envelope associated with it, the lpEnvelope member is set to NULL.

FFEP_GAIN

The dwGain member should receive data.

FFEP_SAMPLEPERIOD

The dwSamplePeriod member should receive data.

FFEP_STARTDELAY

The dwStartDelay member should receive data.

FFEP_TRIGGERBUTTON

The dwTriggerButton member should receive data.

FFEP_TRIGGERREPEATINTERVAL

The dwTriggerRepeatInterval member should receive data.

FFEP_TYPESPECIFICPARAMS

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 FFERR_MOREDATA, and the cbTypeSpecificParams member contains the required size of the buffer in bytes.

Return Value

If the method succeeds, the return value is FF_OK. If the method fails, the return value can be one of the following error values:

FFERR_INVALIDPARAM

FFERR_NOTDOWNLOADED

FFERR_MOREDATA

Discussion

Common errors resulting in a FFERR_INVALIDPARAM error include not setting the dwSize member of the FFEFFECT structure, passing invalid flags, or not setting up the members in the FFEFFECT structure properly in preparation for receiving the effect information.

See Also

Miscellaneous

func FFCreateDevice(io_service_t, UnsafeMutablePointer<FFDeviceObjectReference?>!) -> HRESULT

Creates a new API device object from an OS object in preparation to use the device for force feedback.

func FFDeviceReleaseEffect(FFDeviceObjectReference!, FFEffectObjectReference!) -> HRESULT

Disposes of an API effect object created with FFDeviceCreateEffect.

func FFEffectDownload(FFEffectObjectReference!) -> HRESULT

Places the effect on the device. If the effect is already on the device, the existing effect is updated to match the values set by the FFEffectSetParameters method.

func FFEffectStart(FFEffectObjectReference!, UInt32, FFEffectStartFlag) -> HRESULT

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, it is downloaded before being started. This default behavior can be suppressed by passing the FFES_NODOWNLOAD flag.

func FFEffectUnload(FFEffectObjectReference!) -> HRESULT

Removes the effect from the device. If the effect is playing, it is automatically stopped before it is unloaded.

func FFIsForceFeedback(io_service_t) -> HRESULT

Used to determine if a particular device provided by HID Manager is a force feedback device.

func FFReleaseDevice(FFDeviceObjectReference!) -> HRESULT

Disposes of an API device object created with FFCreateDevice.