IOForceFeedbackLib.h

Overview

This header contains the public interfaces and constants used to develop Force Feedback plug ins. A force feedback device manufacturer might need to implement a plug in to allow the Force Feedback Library to control the device. This header file describes the functions that need to be implemented. This interface definition follows Microsoft Windows IDirectInputEffectDriver definition wherever it makes sense to do so. This plug in architecture uses the CFPlugIn model (COM). The Force Feedback Framework will find available plug ins and will use this interface to communicate with the hardware.

Certain functions may contain more or fewer parameters than the corresponding Windows IDirectInputEffectDriver version.

Functions

DestroyEffect

This function commands the device to "destroy" a currently downloaded effect. The effect ID and any data that is associated with the effect are freed and available for reallocation.

DownloadEffect

This function sends an effect to the device.

Escape

This function escapes to the driver. This method is called in response to an application invoking the FFEffectEscape or FFDeviceEscape methods.

ForceFeedbackGetVersion

This function is used to determine driver and API version information.

GetEffectStatus

This function returns the device effect's status.

GetForceFeedbackCapabilities

This function escapes to the driver. This method is called in response to an application invoking the FFEffectEscape or FFDevicEscape methods.

GetForceFeedbackState

This function returns the state of the device.

InitializeTerminate

This function is used to "create and destroy" particular device instances. It provides the FF plug-in driver with all the necessary start-up parameters.

SendForceFeedbackCommand

This function sends a command to the device.

SetProperty

This function sets properties that define the device behavior.

StartEffect

This function commands the device to play back an effect that was previously loaded.

StopEffect

This function commands the device to stop an effect that was previously started.

This function commands the device to "destroy" a currently downloaded effect. The effect ID and any data that is associated with the effect are freed and available for reallocation.

HRESULT ( *DestroyEffect)(
    void *self,
    FFEffectDownloadID downloadID );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

downloadID

Indicates the effect ID that was obtained from the device when the effect was downloaded.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INVALIDDOWNLOADID
FFERR_GENERIC
FFERR_INTERNAL

This function sends an effect to the device.

HRESULT ( *DownloadEffect)(
    void *self,
    CFUUIDRef effectType,
    FFEffectDownloadID *pDownloadID, 
    FFEFFECT *pEffect,
    FFEffectParameterFlag flags );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

effectType

Indicates the type of effect being created. Valid UUIDs are listed as kFFEffectType_* constants in the ForceFeedbackConstants.h file. (Supported effect types include Sine, Square, Triangle, SawtoothUp, SawtoothDown, Constant, Spring, Damper, etc.).

pDownloadID

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 FFEffectDownloadID pointed to by this parameter contains the new effect handle. On failure, the FFEffectDownloadID 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.

pEffect

The new parameters for the effect.
IMPORTANT NOTE: Unlike the IDirectInputEffectDriver specification, the axis and button values are NOT converted to object identifiers before they are handed over to the driver. In this case, the only supported method used to assign triggers and output axes is through object offsets, defined by the FFJOFS_* constants. Therefore, if a button is assigned to trigger an effect, FFEFFECT.dwTriggerButton will contain a constant of the form FFJOFS_BUTTONn. Similarly, output axes will be identified in FFEFFECT.rgdwAxes[n] as FFJOFS_X, FFJOFS_Y, etc.

flags

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 FFEFFECT structure that are pointed to by the pEffect parameter are valid, and a driver may choose simply to update all parameters of the effect at each download. There may be zero, one, or more of the following:

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

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

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

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

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

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

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

FFEP_ENVELOPE
Indicates the lpEnvelope member of the FFEFFECT 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.

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

FFEP_STARTDELAY
Indicates the dwStartDelay member of the FFEFFECT structure is being downloaded for the first time or has changed since its last download.

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

FFEP_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 FFEP_NODOWNLOAD and FFEP_START flags override this flag.

FFEP_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 FF_OK if successful, or an error value otherwise:

FFERR_DEVICEPAUSED
FFERR_DEVICEFULL
FFERR_INVALIDDOWNLOADID
FFERR_INTERNAL
FFERR_EFFECTTYPEMISMATCH

This function escapes to the driver. This method is called in response to an application invoking the FFEffectEscape or FFDeviceEscape methods.

HRESULT ( *Escape)(
    void *self,
    FFEffectDownloadID downloadID,
    FFEFFESCAPE *pEscape );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

downloadID

Specifies the effect at which the command is directed, or zero if the command is directed at the device itself and not any particular effect.

pEscape

Pointer to a FFEFFESCAPE structure that describes the command to be sent. On success, the cbOutBuffer member contains the number of output buffer bytes actually used.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_UNSUPPORTED

This function is used to determine driver and API version information.

HRESULT ( *ForceFeedbackGetVersion) (
    void *self,
    ForceFeedbackVersion *version);  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

version

Pointer to ForceFeedbackVersion structure that is to receive the required info. See the structure description for details.

Return Value

Returns FF_OK if successful, or an error value otherwise.

This function returns the device effect's status.

HRESULT ( *GetEffectStatus)(
    void *self,
    FFEffectDownloadID downloadID,
    FFEffectStatusFlag *pStatusCode );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

downloadID

Indicates the effect to be queried.

pStatusCode

Receives the effect status. The FFEffectStatusFlag pointed to by this parameter should be filled in with one of the following values:

FFEGES_PLAYING
The effect is still playing.

FFEGES_NOTPLAYING
The effect is not playing.

Return Value

Returns FF_OK.

This function escapes to the driver. This method is called in response to an application invoking the FFEffectEscape or FFDevicEscape methods.

HRESULT ( *GetForceFeedbackCapabilities)(
    void *self,
    FFCAPABILITIES *pCapabilities );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

pCapabilities

Pointer to a FFCAPABILITIES structure that should be filled in with version information describing the hardware, firmware, and driver.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INTERNAL
FFERR_NOINTERFACE

This function returns the state of the device.

HRESULT ( *GetForceFeedbackState)(
    void *self,
    ForceFeedbackDeviceState *pDeviceState );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

pDeviceState

Pointer to a ForceFeedbackDeviceState structure that receives the device state. FF API sets the dwSize member of the ForceFeedbackDeviceState structure to sizeof(ForceFeedbackDeviceState) before calling this method.

Return Value

Returns FF_OK.

This function is used to "create and destroy" particular device instances. It provides the FF plug-in driver with all the necessary start-up parameters.

HRESULT ( *InitializeTerminate)(
    void *self,
    NumVersion forceFeedbackAPIVersion,
    io_object_t hidDevice,
    boolean_t begin );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

forceFeedbackAPIVersion

The version number of FF API that loaded the effect driver. The plugIn should check that the major version of the forceFeedbackAPI version is the same as the major version of the API at the time the plugIn was compiled. If the major versions are different, then the plugIn API has changed and the plugIn will NOT be compatible with it.
If begin is false, this parameter is ignored.

hidDevice

A device object that can be used by the FF plug-in to establish a connection to and communicate with the device. The caller will release the hidDevice device object with a call to IOObjectRelease() once the FF plug-in completes its InitializeTerminate processing, so a FF plug-in implementation should not make a copy of the io_object_t variable with the intention of using it outside the context of this call.
If begin is false, this parameter is ignored. (You can pass NULL.)

begin

Nonzero if access to the device is beginning. Zero if the access to the device is ending. The FF API will call InitializeTerminate( begin=TRUE) when a FF device is first selected for use, and InitializeTerminate( begin=false) when the FF device is no longer needed.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INVALIDPARAM
FFERR_NOINTERFACE
FFERR_OUTOFMEMORY

This function sends a command to the device.

HRESULT ( *SendForceFeedbackCommand)(
    void *self,
    FFCommandFlag state );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

state

Indicates the command being sent. That command can be one of the following:

FFSFFC_RESET
Indicates that playback of any active effects should be been stopped and that all effects should be removed from the device. Once the device has been reset, all effects are no longer valid and must be re-created.

FFSFFC_STOPALL
Indicates that playback of all effects should be stopped. Sending the FFSFFC_STOPALL command is equivalent to invoking the FFEffect_Stop method on all effects that are playing. If the device is in a paused state, the device driver is permitted to lose the paused state.

FFSFFC_PAUSE
Indicates that playback of all effects should be paused. When effects are paused, time "stops" until the FFSFFC_CONTINUE command is sent. For example, suppose an effect of five seconds' duration is started. After one second, all effects are paused. After two more seconds, all effects are continued. The effect should then play for four additional seconds. While a force-feedback device is paused, starting a new effect or modifying existing ones can cause the paused state to be lost.

FFSFFC_CONTINUE
Indicates that playback should be resumed at the point at which it was interrupted for those effects that were paused by a previous FFSCFFC_PAUSE command.

FFSFFC_SETACTUATORSON
Indicates that the device's force-feedback actuators should be enabled.

FFSFFC_SETACTUATORSOFF
Indicates that the device's force-feedback actuators should be disabled. If successful, force-feedback effects are "muted". Note that time continues to elapse while actuators are off. For example, suppose an effect of five seconds' duration is started. After one second, actuators are turned off. After two more seconds, actuators are turned back on. The effect should then play for two additional seconds.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INTERNAL
FFERR_INVALIDPARAM

This function sets properties that define the device behavior.

HRESULT ( *SetProperty)(
    void *self,
    FFProperty property,
    void *pValue );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

property

The following property values are defined for a FF device:

FFPROP_AUTOCENTER
Specifies whether the actuated FF axes are self-centering. This property controls the device's "default centering spring".
The pValue member points to a UInt32 and can be one of the following values.

0 - OFF: The device should not automatically center when the user releases the device. An application that uses force feedback should disable autocentering before playing effects.

1 - ON: The device should automatically center when the user releases the device.

Not all devices support the autocenter property.

FFPROP_FFGAIN
Sets the gain for the device.

The pValue member points to a UInt32 that contains a gain value that is applied to all effects created on the device. The value is an integer in the range from 0 through 10,000, specifying the amount by which effect magnitudes should be scaled for the device. For example, a value of 10,000 indicates that all effect magnitudes are to be taken at face value. A value of 9,000 indicates that all effect magnitudes are to be reduced to 90% of their nominal magnitudes.

Setting a gain value is useful when an application wants to scale down the strength of all force-feedback effects uniformly, based on user preferences.

pValue

Address of the location where the property value is to be read. This function will assume that the data is valid, and of the correct type.

Return Value

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

FFERR_INVALIDPARAM

This function commands the device to play back an effect that was previously loaded.

HRESULT ( *StartEffect)(
    void *self,
    FFEffectDownloadID downloadID,
    FFEffectStartFlag mode,
    UInt32 iterations );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

downloadID

Indicates the effect to be played.

mode

Specifies how the effect is to affect other effects. Only the mode listed below can be used; all other modes are reserved. For example, the driver never receives the FFES_NODOWNLOAD flag because it is managed by the FF API and not the PlugIn driver. This parameter can be zero, one, or more of the following flags:

FFES_SOLO
Indicates that all other effects on the device should be stopped before the specified effect is played. If this flag is omitted, the effect is mixed with existing effects that have already started on the device.

iterations

Specifies the number of times to perform the effect. If the value is FF_INFINITE, then the effect should be repeated until explicitly stopped or paused.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INTERNAL
FFERR_DEVICEPAUSED
FFERR_DEVICEFULL
FFERR_GENERIC
FFERR_INVALIDDOWNLOADID

This function commands the device to stop an effect that was previously started.

HRESULT ( *StopEffect)(
    void *self,
    UInt32 downloadID );  

Parameters

self

Pointer to the FFPlugInDriver implementation instance.

downloadID

Indicates the effect to be stopped.

Return Value

Returns FF_OK if successful, or an error value otherwise:

FFERR_INTERNAL
FFERR_GENERIC
FFERR_INVALIDDOWNLOADID

Typedefs

Unique identification for an effect.

typedef UInt32 FFEffectDownloadID;  

Returns information about the state of a force feedback device.

ForceFeedbackDeviceState

typedef struct ForceFeedbackDeviceState ForceFeedbackDeviceState;  

Fields

dwSize

Specifies the size of the structure in bytes. This member must be initialized before the structure is used.

dwState

Indicates various aspects of the device state. Can indicate zero, one, or more of the following:

FFGFFS_EMPTY

Indicates that the force feedback device is devoid of any downloaded effects.

FFGFFS_STOPPED

Indicates that no effects are currently playing and the device is not paused.

FFGFFS_PAUSED

Indicates that playback of effects has been paused by a previous FFSFFC_PAUSE command.

FFGFFS_ACTUATORSON

Indicates that the device's force-feedback actuators are enabled.

FFGFFS_ACTUATORSOFF

Indicates that the device's force-feedback actuators are disabled.

FFGFFS_POWERON

Indicates that power to the force-feedback system is currently available. If the device cannot report the power state, then neither FFGFFS_POWERON nor FFGFFS_POWEROFF should be returned.

FFGFFS_POWEROFF Indicates that power to the force-feedback system is not currently available. If the device cannot report the power state, then neither FFGFFS_POWERON nor FFGFFS_POWEROFF should be returned.

FFGFFS_SAFETYSWITCHON

Indicates that the safety switch (dead-man switch) is currently on, meaning that the device can operate. If the device cannot report the state of the safety switch, then neither FFGFFS_SAFETYSWITCHON nor FFGFFS_SAFETYSWITCHOFF should be returned.

FFGFFS_SAFETYSWITCHOFF

Indicates that the safety switch (dead-man switch) is currently off, meaning that the device cannot operate. If the device cannot report the state of the safety switch, then neither FFGFFS_SAFETYSWITCHON nor FFGFFS_SAFETYSWITCHOFF should be returned.

FFGFFS_USERFFSWITCHON

Indicates that the user force-feedback switch is currently on, meaning that the device can operate. If the device cannot report the state of the user force-feedback switch, then neither FFGFFS_USERFFSWITCHON nor FFGFFS_USERFFSWITCHOFF should be returned.

FFGFFS_USERFFSWITCHOFF

Indicates that the user force-feedback switch is currently off, meaning that the device cannot operate. If the device cannot report the state of the user force-feedback switch, then neither FFGFFS_USERFFSWITCHON nor FFGFFS_USERFFSWITCHOFF should be returned.

FFGFFS_DEVICELOST

Indicates that the device suffered an unexpected failure and is in an indeterminate state. It must be reset either by unacquiring and reacquiring the device, or by explicitly sending a FFSFFC_RESET command. For example, the device may be lost if the user suspends the computer, causing on-board memory on the device to be lost.

dwLoad

A value indicating the percentage of device memory in use. A value of zero indicates that the device memory is completely available. A value of 100 indicates that the device is full

Used to return plugIn version information.

ForceFeedbackVersion

typedef struct ForceFeedbackVersion ForceFeedbackVersion;  

Fields

apiVersion

The version of the plugIn API that is implemented by this driver

plugInVersion

Vendor-determined version of the plugIn.

Structs and Unions

Returns information about the state of a force feedback device.

ForceFeedbackDeviceState

struct ForceFeedbackDeviceState { 
    UInt32 dwSize; 
    UInt32 dwState; 
    UInt32 dwLoad;  
};  

Used to return plugIn version information.

ForceFeedbackVersion

struct ForceFeedbackVersion { 
    NumVersion apiVersion; 
    NumVersion plugInVersion; 
};  

Enumerations

enum { 
    kFFPlugInAPIMajorRev = 1, 
    kFFPlugInAPIMinorAndBugRev = 0, 
    kFFPlugInAPIStage = finalStage, 
    kFFPlugInAPINonRelRev = 0 
};  

Discussion

This refers the Force Feedback PlugIn API (and not the Framework API).

#defines

PFFDEVICESTATE

#define FFDEVICESTATE ForceFeedbackDeviceState
#define PFFDEVICESTATE ForceFeedbackDeviceStatePtr

Discussion

Mac OS versions of these definitions

FFDEVICESTATE

#define PFFDEVICESTATE ForceFeedbackDeviceStatePtr 

Discussion

Mac OS versions of these definitions

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11