Function

FFDeviceCreateEffect(_:_:_:_:)

Creates and initializes an instance of an effect identified by the effect UUID on the device.

Declaration

func FFDeviceCreateEffect(_ deviceReference: FFDeviceObjectReference!, _ uuidRef: CFUUID!, _ pEffectDefinition: UnsafeMutablePointer<FFEFFECT>!, _ pEffectReference: UnsafeMutablePointer<FFEffectObjectReference?>!) -> HRESULT

Parameters

deviceReference

An opaque reference handle to a device object. This is obtained from a previous call to FFCreateDevice.

uuidRef

Reference to the UUID identifying the effect to be created. Only predefined effect UUIDs are accepted. The following standard effect UUIDs are defined:

kFFEffectType_ConstantForce_ID

kFFEffectType_RampForce_ID

kFFEffectType_Square_ID

kFFEffectType_Sine_ID

kFFEffectType_Triangle_ID

kFFEffectType_SawtoothUp_ID

kFFEffectType_SawtoothDown_ID

kFFEffectType_Spring_ID

kFFEffectType_Damper_ID

kFFEffectType_Inertia_ID

kFFEffectType_Friction_ID

kFFEffectType_CustomForce_ID

pEffectDefinition

Pointer to FFEFFECT structure that provides parameters for the created effect. This parameter is optional. If it is NULL, the effect object is created without parameters. The application must then call the FFEffectSetParameters function to set the parameters of the effect before it can download the effect.

pEffectReference

Address of a variable to receive an opaque reference handle to a new effect object. This reference can be used in subsequent calls to FFEffect* functions.

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_UNSUPPORTEDAXIS

FFERR_OUTOFMEMORY

FFERR_DEVICEPAUSED

FFERR_DEVICEFULL

FFERR_INVALIDDOWNLOADID

FFERR_INTERNAL

FFERR_EFFECTTYPEMISMATCH

Discussion

When you are finished with the effect, FFReleaseEffect must be called on the reference received in this function to dispose of the API effect object.

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.