The Force API(
Release 1.05
Revised December 10, 1996
(c) Copyright 1996, Immersion Corporation
TABLE OF CONTENTS
Overview of Force Feedback and I-FORCE
A Partial List of Game Titles Supporting I-FORCE Force Feedback
Compatibility
Which gaming peripheral manufacturers support I-FORCE technology?
Will I-FORCE joysticks work with existing games?
Will I-FORCE joysticks work with the USB?
Do I need an I-FORCE force feedback joystick to start my force feedback development?
The I-FORCE Force Feedback Architecture
How simple is it to program? Will it slow down my game?
Summary of Basic I-FORCE Force Effects
Superposition of Force Effects
Typical Game Sensations and Their Corresponding I-FORCE API Calls
I-FORCE API Specifications: Version 1.05
Changes from Version 1.0: Windows 95 DLL, Missed Command Recovery
Changes from Version 1.01: Addition of XSpring and YSpring Command
Changes from Version 1.01: Digital Position Reporting Mode (DOS only)
Initialization and Control Function Calls
Force Effect Function Calls
I-FORCE API Preliminary Specifications: Version 2.0
Advanced Force Effect Function Calls
User-Programmable and Downloadable Force Feedback Profiles (FFPs)
Incorporating Force Feedback Into Your Application
Using the I-FORCE Force Feedback Joystick Simulator Program
Immersion Contact Information
APPENDICES
Appendix A: Joystick Status Byte Encoding
Appendix B: Sample Programs
Overview of Force Feedback and I-FORCE
I-FORCE adds "FEEL" Sensations to PC Video Games
Immersion Corporation of San Jose, California has recently unveiled I-FORCE, a hardware architecture standard and universal software protocol that empower PC gaming peripherals such as Joysticks, Steering Wheels, and Flight Yokes with the ability to provide realistic physical "feel" sensations.
Known as force feedback, the "feel" technology pioneered by Immersion Corporation has generated major excitement among peripheral manufacturers and video game developers. By adding physical sensations to joysticks and other peripherals, the I-FORCE standard will revolutionize the gaming experience. Imagine flying a space ship across the galaxy and feeling realistic re-entry forces as you navigate into a planet's atmosphere. Imagine driving a race car off the road and feeling the jarring and bouncing jolts as you tackle rough terrain. Imagine feeling g-forces as you pull a tight turn on your simulated F-16 aircraft. Imagine grabbing an icon in a Windows desktop and feeling its weight, or resizing a window and feeling its compliance. Imagine interacting with another user over the internet and feeling realistic physical forces as you tug on the same piece of cyber-material. The possibilities are endless.
Numerous peripheral manufacturers have already endorsed the I-FORCE standard from Immersion Corporation including CH Products of Vista, California, Advanced Gravis of Burnaby BC, Canada, Interactive IO of Orange, California, and SC&T2 International of Phoenix, Arizona. Force feedback gaming peripherals will range in retail price from $100 to $149 upon initial release. One major manufacturer, CH Products of Vista, California, has already incorporated the I-FORCE technology into their popular line of joystick controllers and has scheduled commercial release of their Force-FX joystick in time for the 1996 Christmas season. Another manufacturer, Interactive IO, has incorporated I-FORCE technology into a high performance driving cockpit, complete with force feedback steering wheel and anticipates commercial release in mid 1996. Advanced Gravis plans to produce I-FORCE joysticks which are functional with their innovative GrIP game port architecture.
In addition, many high-profile game development firms have already incorporated support for the I-FORCE technology into their gaming applications. Parallax Software of Ann Arbor, MI has incorporated the I-FORCE API into their smash-hit game Descent II, allowing players to actually feel blasts and explosions as they battle into the depths of the post-Terran mines. Mission Studios of Inverness, IL has incorporated the I-FORCE API into Jet Fighter III, allowing players to experience air combat with realistic physical sensations never before possible. Accolade of San Jose, CA has incorporated the I-FORCE API into Unnecessary Roughness '96, allowing players to feel the bone-jarring hits and tackles of NFL football. Other titles by major software developers that have incorporated I-FORCE API include Need for Speed - SE by Electronic Arts, Silent Thunder from Sierra On-Line, Warbirds from ICI Games, Fighter Duel SE from Philips Media Games, and Monday Night Football from OT Sports/Microprose/Spectrum Holobyte. Dozens of other I-FORCE titles from Activision, Rocket Science, LucasArts Entertainment, Domark, Sierra, Papyrus, Lookinglass, Kesmai, Segasoft, Microprose, 3D Realms, id Software, and many others are expected. The response from the game development community has been overwhelming, -- developers are lining up to get this technology into their upcoming titles. To satisfy the demand, Immersion Corporation has made the I-FORCE software drivers available free by download to all software developers who visit the I-FORCE web site at WWW.FORCE-FEEDBACK.COM
When the first I-FORCE compatible products hit the retail channels in the 1996 Christmas season, force feedback will revolutionize the video game industry. Immersion Corporation predicts that within 4 years, over 75% of all computer gaming peripherals sold for personal computers and home gaming consoles will support some level of force feedback capability. The I-FORCE standard has already gained significant support from both hardware vendors and software developers on PC and game consoles and it is well on its way towards becoming the cross-platform industry standard. Computing is not just visual anymore and Immersion Corporation intends to put the technology of "feel" into the hands of mainstream computer users everywhere.
For more information, contact:
Dean Chang, Ph.D.
Director of Developer Program
Tel: (408) 467-1900
Fax: (408) 467-1901
e-mail: dean@immerse.com
Mail: Immersion Corporation
2158 Paragon Drive
San Jose, CA 95131
For online information, visit our web sites:
Immersion Corporation: www.immerse.com
I-FORCE software protocol information: www.force-feedback.com
Virtual Vehicle from Interactive IO ForceFX Joystick from CH Products
A Partial List of Game Titles Supporting I-FORCE Force Feedback
DESCENT II Parallax Software of Ann Arbor, MI has incorporated the I-FORCE API into their smash-hit game Descent II. Players can actually feel blasts, explosions, force fields, and other robots as they battle into the depths of the post-Terran mines.
NEED FOR SPEED SE Electronic Arts has integrated the I-FORCE API into their network racing simulation game Need for Speed SE. Players can actually feel vibrations from driving on rough roads, g-forces from hard cornering and spinouts, and collisions with other cars, guard rails, and road signs.
SILENT THUNDER Sierra On-Line of Bellevue, WA has integrated the I-FORCE API into their combat flight simulator Silent Thunder. Sierra also plans to add I-FORCE support in the upcoming titles Earth Siege 2, Trophy Bass, and Red Baron 2.
FIGHTER DUEL SE Philips Media Games and SPGS have incorporated the I-FORCE API into their combat flight simulator Fighter Duel, allowing players to feel explosions, turbulence, and g-forces as they battle in dogfights with other players.
WARBIRDS ICI Games of Grapevine, TX has incorporated the I-FORCE API into their internet, multi-player combat flight simulator Warbirds. Players can actually feel explosions, turbulence, and g-forces as they battle in dogfights with hundreds of other players.
MONDAY NIGHT FOOTBALL OverTime Sports , a new joint venture formed by Spectrum Holobyte, Microprose, and ABC/Capital Cities, has integrated the I-FORCE API into their football simulation game Monday Night Football.
JET FIGHTER III Mission Studios of Inverness, IL has incorporated the I-FORCE API into their flight simulator Jet Fighter III, allowing players to experience air combat with realistic physical sensations never before possible.
UNNECESSARY ROUGHNESS Accolade of San Jose, CA has incorporated the I-FORCE API into Unnecessary Roughness '96, allowing players to feels tackles and experience a true contact sport video game.
More titles are continually supporting I-FORCE.
You can check for a more updated list at the I-FORCE website:
http://www.force-feedback.com
Compatibility
Which gaming peripheral manufacturers support I-FORCE technology?
CH Products of Vista, CA has already incorporated I-FORCE technology into their popular line of FlightStick and CombatStick joysticks. These first-of-its-kind force feedback joysticks, called the FORCE-FX joysticks, are scheduled for commercial release this fall in time for Christmas. Interactive I/O of Orange, CA has incorporated I-FORCE technology into a high performance driving cockpit complete with force feedback steering wheel and anticipates commercial release in mid 1996. Advanced Gravis of Burnaby, BC, Canada plans to produce I-FORCE joysticks which are functional with their innovative GrIP game port architecture. SC&T2 of Phoenix, Arizona plans to add I-FORCE to their popular line of computer peripherals. Other peripheral manufacturers will announce release dates soon.
Will I-FORCE joysticks work with existing games?
The current I-FORCE hardware architecture for the PC uses a proprietary combination of both game port and serial port interfaced simultaneously. This unique architecture allows the joystick to function in a "legacy" mode where it will be 100% compatible with standard joystick protocols. Thus I-FORCE force feedback joysticks are backwards compatible with ALL games which support standard joysticks. This compatibility provides two significant advantages:
1. All I-FORCE compatible joysticks will be fully functional with the enormous library of existing software titles that use standard joysticks.
2. No new function calls or special drivers are needed to read the position and buttons of an I-FORCE joystick. If using the I-FORCE API, game developers can concentrate solely on adding force effects and not on learning how to interface to an entirely new kind of joystick.
Will I-FORCE joysticks work with the USB?
Future versions of I-FORCE hardware will function with the upcoming Universal Serial Bus (USB) standard. Immersion Corporation has been instrumental in defining a new class in the USB standard known as the Physical Interface Device (PID) Class. Immersion has helped define the PID standard and has ensured that it will be fully compatible with the I-FORCE architecture.
Do I need an I-FORCE force feedback joystick to start my force feedback development?
Your Immersion I-FORCE SDK includes a DOS simulator program for PCs that allows you to develop and test force feedback programs even if you do not have an I-FORCE force feedback joystick. The simulator program is called IMMSIM.EXE and runs on any PC with a serial port. The simulator PC acts like the joystick and graphically displays all incoming joystick commands, all active force effects, and joystick status bytes. Once you develop your force feedback program with the simulator, you can simply unplug your serial cable from the simulator PC and plug it into a force feedback joystick. If your game worked with the simulator, it will work the joystick!
The I-FORCE Force Feedback Architecture
How simple is it to program? Will it slow down my game?
Immersion Corporation has developed a proprietary architecture for force feedback computer peripherals which allows high performance force effects to be generated with little to virtually no burden on the host application. This is made possible by a microprocessor on board the I-FORCE product which receives only high level commands from the host PC and then produces all force feedback effects independent of host supervision. For example, the host computer requests the hi-level command Vibration() and specifies the magnitude, frequency, and duration. The on-board microprocessor then generates the vibration, thus relieving the PC of all burden and allowing for easy programming. In addition to the microprocessor, Immersion Corporation has developed a proprietary concept known as the FORCE REFLEX. A force reflex is an automatic reaction that occurs on the I-FORCE product and does not require any supervision by the host. These reflexes can be configured by the host to allow for custom force effects, but once set up, the host hands all responsibility for these force reflexes over to the on-board microprocessor for extended periods of time. Therefore, adding force feedback to your application using the I-FORCE API requires little to virtually no overhead on the host side. For example, the I-FORCE API supports a command called ButtonReflexJolt() which sets up a force reflex on the joystick that produces a Jolt() every time a specified joystick button is pressed. You might choose to configure this force reflex to produce a jolt of 57% magnitude from the N-W direction every time button #4 is pressed. Furthermore, you could configure this reflex with a repeat-rate of 10 cycles per second when the button is held down to simulate the feel of a rapid-fire weapon. Many reflexes can be easily pre-programmed on the joystick, and they will remain active during game play. Reflexes can be modified or disabled at any real time to allow the joystick to react appropriately as game conditions change.
Force Feedback Profiles. Another powerful feature of the proprietary I-FORCE architecture is the ability to download "Force Feedback Profiles" (FFPs) to the stick. FFPs allow custom force effects to be created by both game developers and game players. Using a simple graphical editor, users can design their own force effect or FFP and play it back. These custom force effects or FFPs can then be saved to a .FFP file and downloaded to the joystick to be used in any game that supports the I-FORCE API. FFPs provide infinite flexibility to create your own force sensations. For example, you have designed a game with a special "hyper-turbo-ultra-torpedo" weapon and you want it to have a signature feel which has a subtle vibration followed by a substantial kick to the left. You can create a custom force profile, download it to the joystick, and then call it. Simple. You can even set up reflexes using ButtonReflexFFP() to trigger an FFP automatically whenever autonomously a specified button is depressed. Simple and Fun. (The FFP commands are only available in I-FORCE API version 1.1 and are described later in this document).
A sample program is given Appendix B showing how easy it is to integrate force feedback into your game using the I-FORCE API.
Summary of Basic I-FORCE Force Effects
See the section entitled "I-FORCE API Specifications" for function prototypes and detailed descriptions of each of these commands.
Jolt
This command causes a jolt or whack on the joystick. Jolt parameters include Magnitude, Axis Direction, and Duration. This is a useful command to use when a plane gets shot, when a car bumps into another car, when a space-ship hits an asteroid, etc. To simulate weapon fire recoil after a button press, programmers should use ButtonReflexJolt.
ButtonReflexJolt
This command causes the joystick to set up a background reflex that causes a Jolt in response to a specific joystick button press. The advantage of ButtonReflexJolt over Jolt is that it allows the stick to produce the desired jolts without continuous software monitoring by the host. The reflex is resident on the joystick, so button-triggered jolts do not require explicit Jolt commands every time from the host. Reflexes allow the game software to run quickly and make programming very easy. For example, the joystick can be set up to give a jolt of a given magnitude and direction whenever trigger #1 is pulled. A different type of jolt can be set up for whenever trigger #2 is pulled. The assignment of jolts to buttons can be changed or disabled on the fly, allowing the joystick to maintain consistency with game events (e.g., change of weapon, out of ammunition). Also included in this command is a RepeatRate parameter which causes a rapid series of jolts when the button is held down. RepeatRate allows easy implementation of automatic weapon fire sensations. Other parameters include ButtonAssignment, Axis Direction, Magnitude, and Duration.
Vibration
This command implements a vibration of a given frequency and magnitude on one or both axes. Vibration is ideal for simulating the feel of driving over rough terrain or the hum of an airplane engine. The parameters include Magnitude, Direction, and Frequency.
Buffeting
This command is similar to Vibration but varies direction and magnitude simultaneously. The sensation feels similar to what you might expect when flying a plane through turbulence.
VectorForce
This command outputs a force of a given magnitude on a given axis. Parameters include Magnitude and Direction. VectorForce is a very basic command which can be used to create a wide variety of force sensations such as g-forces when a plane makes a tight turn, strong cross-winds while flying, or driving into a wall at an angle.
Spring
This function creates a compliant restoring force that causes the joystick to return to a specified point in the joystick's range of motion. The farther away the joystick is from the specified point, the stronger this spring return force is. Spring is particularly useful for flight sims and driving games to simulate stiffening of the joystick due to aerodynamic or g-forces. The command can also simulate many other things like resistance from moving through mud, pushing objects, or walls.
Superposition of Force Effects
An powerful feature of the I-FORCE architecture is that multiple force effects can be active simultaneously. For example, a Vector Force and a Vibration can be applied concurrently to get a much more interesting compound effect. Another example is being blasted from the left and behind simultaneously and being able to feel both effects.
Typical Game Sensations and Their Corresponding I-FORCE API Calls
Here are some typical sensations found in many games and how one might implement them using the I-FORCE API. You are encouraged to experiment to find better ways of representing these and other sensations, particularly by using superposition of commands to create even more convincing effects.
Effect I-FORCE API Call
Revolver Recoil ButtonReflexJolt(0,50,0,10,250)
Machine Gun Recoil ButtonReflexJolt(0,75,0,30,80)
Shotgun Recoil ButtonReflexJolt(0,100,20,400,1000)
Hit by Laser Pulse Jolt(90,0,20)
Hit by Laser Blast Jolt(100,10,120)
Hit by Rocket Launcher Jolt(100,30,600)
Tank_Tread_Forward_Slow YVibration(0,65,6)
Tank_Tread_Forward_Fast YVibration(0,65,12)
Tank_Tread_Backward_Slow YVibration(65,0,6)
Tank_Tread_Backward_Fast YVibration(65,0,12)
Rough Road Buffeting(25)
Engine Hum Low Gear XVibration(10,15,17)
Engine Hum Medium Gear XVibration(20,15,20)
Engine Hum High Gear XVibration(70,60,40)
Heart Beat YVibration(70,70,3)
Clock Tick YVibration(60,60,1)
Air Turbulence Buffeting(35)
Explosion Buffeting(55)
Destruction Buffeting(75)
High Speed Turn G-Force XSpring(0,50,50)
High Speed Dive Aero Force YSpring(0,750,75)
I-FORCE API Specifications: Version 1.05
Changes from Version 1.0: Windows 95 DLL, Missed Command Recovery
I-FORCE SDK v1.01 has a few very important changes from v1.0 with significant implications to your program. V1.01 now has a DLL for Windows 95/NT development. I-FORCE joysticks under SDK v1.0 would sometimes miss commands if sent two or more successive commands, one immediately following the other (e.g., DisableForces() immediately followed by ClearForces()). Under such circumstances, the joystick sometimes missed the second command while processing the first. When making two successive joystick command calls, it was therefore necessary to wait a short time (3-7 ms) between the calls and to check the joystick status with GetStickStatus() to determine if the commands were successfully received. I-FORCE SDK v1.01 corrects this problem by keeping a local record of the following force effect commands and their parameters when they are sent: Enable Forces, DisableForces, ClearForces, ButtonReflexJolt, ButtonReflexClear, XVibration, XVibrationClear, YVibration, YVibrationClear, Buffeting, BuffetingClear, VectorForce, XYVectorForce, and VectorForceClear. If any of these commands are successfully called by your program (return value of TRUE) but missed by the joystick for any reason (e.g., the joystick was still processing a previous command, the serial connection became unplugged, power to the joystick was lost), the missed command(s) will automatically be resent in the background until the joystick state correctly matches the commanded joystick state. This new missed command recovery feature ensures that the joystick will always accurately reflect what is happening in your game and eliminates the need to wait between successive joystick commands and constantly check the joystick status with GetStickStatus(). Again, command recovery only works if the return value of the I-FORCE command was TRUE. If the return value was FALSE, the missed command will not be resent.
Changes from Version 1.01: Addition of XSpring and YSpring Command
I-FORCE SDK v1.05 has added XSpring and YSpring commands which are ideal for flight sims and driving games to simulate stiffening of the joystick due to aerodynamic or g-forces. The commands can also simulate many other things like resistance from moving through mud , pushing objects, or walls. The Spring commands are only supported in production model joysticks which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord struct.
Changes from Version 1.01: Digital Position Reporting Mode (DOS only)
I-FORCE SDK v1.05 has added digital position reporting capability. If digital position reporting is enabled, joystick position can be read either over the serial port or through traditional analog game port polling. Reading joystick position digitally should be both faster and more exact than game port polling. The Digital Position commands are only supported in production model joysticks which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord struct. Digital Position Reporting can be enabled and read in DOS games using the EnablePositionReporting and GetStickPosition commands. In Win95, Digital Position Reporting Mode is integrated with DirectX. Win95 developers should not use the EnablePositionReporting and GetStickPosition commands. Win95 users can choose analog or digital mode from the Joystick Properties Control Panel.
Initialization and Control Function Calls
All functions except GetStickError(), SetStickPort() and SetStickAddressIRQ() return a Boolean value indicating whether the command was successfully sent. A value of True or 1 indicates success, and a value of False or 0 indicates failure. Unless specified otherwise, these functions do not check to see if the command was successfully received by the joystick. This was explicitly done to prevent the host game from ever having to wait for a serial message from the joystick and thereby bog down the game. However, due to the missed command recovery feature mentioned above, you no longer need to wait between successive joystick commands and constantly check the joystick status with GetStickStatus() to ensure your command was received by the joystick as long as the return value was True.
void SetJoystickPort(int port)
This function specifies which of the standard serial ports (COM1-4) the joystick is connected to. SetJoystickPort() must be called once at the very beginning of any program before calling InitStick().
void SetJoystickAddressIRQ(unsigned int addr, int irq) optional/advanced
This function is an alternative to SetJoystickPort() and allows the user to specify the address and IRQ number of the joystick serial port. If you have a non-standard serial port, you must use this function instead of SetJoystickPort().
Bool InitStick(JoystickRecord *StickRec)
This function must be called once at the very beginning of any program and after joystick powerup to initialize communications with the joystick and to clear any previous force effects and button reflex jolt settings. StickRec is a pointer to the struct JoystickRecord. See I-FORCE.H for a definition of the JoystickRecord struct, which contains joystick data such as model number, serial number, firmware version and date, and joystick capabilities. If a JoystickRecord StickRec is declared in the main program and InitStick(&StickRec) is called, all joystick data will be uploaded into StickRec (see FDBKTEST.C for an example). If no JoystickRecord struct is declared in the main program, you can call InitStick with the parameter NULL (i.e., InitStick(NULL)), and joystick data will not be uploaded. The return value of InitStick() is true only if the command was both successfully sent and received.
Bool IForceAuthenticate(void) optional/advanced
Queries I-FORCE compatible joystick for the Immersion copyright message to verify authenticity. A return value of true indicates the Immersion copyright message was successfully received from the joystick.
Bool EnableForces(void)
Enables all force effects. The joystick is incapable of generating any forces until EnableForces() is called. Force effects and ButtonReflexJolt() settings can be programmed prior to calling EnableForces() and are unchanged by EnableForces(). However, they will not become active until after forces are enabled. Once EnableForces() is called, force effects remain enabled until DisableForces() or CloseStick() is called.
Bool DisableForces(void)
Disables all force effects. Once DisableForces() is called, the joystick is incapable of generating forces until EnableForces() is called. This function allows all force effects to be temporarily turned off (e.g., when a game is paused). Previous force effect settings remain unchanged, and new force effect settings can be programmed while forces are disabled. Therefore, all force effects (including button reflex jolts) active prior to calling DisableForces() will become active again once EnableForces() is called. To clear all force effect settings, use the ClearForces() command.
Bool ClearForces(void)
Clears all active force effects and button reflex jolt settings. It does not disable force effects. GetStickStatus() can be called to confirm if this command was successfully processed by the joystick.
Bool CloseStick(void)
This function clears all current force effects and button reflex jolt settings, disables force effects, and closes all joystick communications. This function should be called at the very end of any program. If you are polling the COM ports at the beginning of the game to see if the I-FORCE device is present, you must also call CloseStick() after any unsuccessful InitStick() calls. For example, if InitStick() fails on COM 1, you must call CloseStick() before attempting InitStick() again on COM 2.
Bool GetStickStatus(char *StickStatus)
This function reads the most recent joystick status bytes. On powerup, the joystick automatically sends four status bytes to the host or game computer roughly every two seconds. These status bytes then reside on the host and are automatically updated every time the joystick sends them. GetStickStatus() reads the status bytes from the host, and therefore, does not wait for a response from the joystick. StickStatus is a pointer to an array of chars of length 4. If a char array StickStatus[4] is declared in the main program and GetStickStatus(StickStatus) is called, the four joystick status bytes will be copied to the StickStatus array (see FDBKTEST.C for an example). If the joystick status was successfully updated, the return value is true. The encoding of the four status bytes is explained in Appendix A: Joystick Status Byte Encoding. Programmers can check the status bytes with GetStickStatus() at any time to determine which force effects are active, whether forces are enabled, etc. on the joystick.
Bool Echo(void) optional/advanced
This function requests a simple echo from the joystick and can be used to test if the joystick is connected and functioning. The return value is true only if an echo was successfully received from the joystick. A return value of false indicates that the joystick is not properly connected.
int GetStickError(void) optional/advanced
This function returns the error code associated with the last API function called. A return value of 0 indicates that the call was successful.
DOS-Only Commands
The following commands are for DOS only and should not be used by Win95 developers. The functionality of these commands has been integrated directly into DirectX and can be accessed from the Win95 Joystick Properties Control Panel.
Bool EnablePositionReporting(int Period) optional/advanced
This command is only supported in production model joysticks, which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord. If called after a successful InitStick() command, this function enables Digital Position Reporting Mode. If digital position reporting is enabled, joystick position can be read either over the serial port or through traditional analog game port polling. Reading joystick position digitally should be both faster and more exact than game port polling. The int Period specifies how many milliseconds between position updates (e.g., a Period of 50 will cause the joystick to update its position every 50 ms). If GetStickPosition() is called more often than Period, the previous position will continue to be reported until Period has elapsed. The minimum value of Period is 20 ms.
Bool DisablePositionReporting(void) optional/advanced
This command is only supported in production model joysticks, which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord. This function disables Digital Position Reporting Mode.
Bool GetStickPosition(JoystickPosition *StickPos) optional/advanced
This command is only supported in production model joysticks, which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord. This function copies the current digital position to the JoystickPosition struct StickPos (see types.h for typedef of JoystickPosition).
CH Force FX Digital Mode Decoding
x 0-255 0: full left, 255: full right
y 0-255 0: full up, 255: full down
throttle n/a unused
buttons 0x0000-0xFFFF 1: pressed/down/close, 0: not pressed/up/open
bit 0 button A1, trigger
bit 1 button A2
bit 2 button B1
bit 3 button B2
bit 4 button X1
bit 5 button X2
bit 6 unused
bit 7 unused
bit 8 POV hat 1 up
bit 9 POV hat 1 right
bit 10 POV hat 1 down
bit 11 POV hat 1 left
bit 12 POV hat 2 up
bit 13 POV hat 2 right
bit 14 POV hat 2 down
bit 15 POV hat 2 left
Force Effect Function Calls
All force effect functions return a Boolean value indicating whether the command was successfully sent. A value of True or 1 indicates success, and a value of False or 0 indicates failure. Unless specified otherwise, these functions do not check to see if the force effect was successfully received by the joystick. This was explicitly done to prevent the host game from ever having to wait for a serial message from the joystick and thereby bog down the game. However, due to the missed command recovery feature mentioned above, you no longer need to wait between successive joystick commands and constantly check the joystick status with GetStickStatus() to ensure your command was received by the joystick.
All force effects assume the following orientation convention for the joystick:
+Y
0/N
Top View 270/W 90/E +X
180/S
The force effect functions Jolt(), ButtonReflexJolt(), and VectorForce() all have Direction arguments. The Direction is an angle in degrees corresponding to the illustration above. All three functions assume an event is occurring from or to the Direction angle and will cause the joystick to react in the direction opposite the Direction angle. This convention is further explained below with examples for each function.
Bool Jolt(unsigned int Magnitude, int Direction, unsigned int Duration)
Magnitude 0-100 percent of maximum joystick force
Direction 0-360 direction in degrees of source of jolt, causes jolt motion in opposite direction (i.e., Direction-180), 0 = jolt in backward or down direction
Duration 0-2500 time duration of jolt in milliseconds
If an object comes from the right side and hits the right side of the player, Direction should be 90. Jolt() with Direction = 90 will cause the joystick to react in the direction opposite the Direction angle. Therefore, the player will feel a jolt to the left. If something hits the player diagonally from behind and from the left, Direction should be 225, and Jolt() will cause the joystick to be knocked forward and to the right.
Effect Examples
mag
dir
dur
plane shot from right side
75
90
10
car bumped from behind
100
180
150
Bool ButtonReflexJolt(unsigned int ButtonAssign, unsigned int Magnitude, int Direction, unsigned int Duration, unsigned int RepeatRate)
ButtonAssign 0-15 assign effect to button # 0-15. Only buttons #0-3 currently supported.
Magnitude 0-100 percent of maximum joystick force
Direction 0-360 direction in degrees of source of jolt, causes jolt motion in opposite direction (i.e., Direction-180), 0 = jolt in backward or down direction
Duration 0-2500 time duration of jolt in milliseconds
RepeatRate 0-2500 minimum time between start times of successive jolt reflexes in milliseconds
The ButtonReflexJolt() should be used to program background reflexes that cause jolts in response to specific joystick button presses. With a ButtonReflexJolt() call, button number 0 can be programmed to cause a jolt of given Magnitude, Direction and Duration whenever button number 0 is pressed. With a second ButtonReflexJolt() call, button number 1 can be programmed to cause a jolt of different Magnitude, Direction and Duration whenever button number 1 is pressed.
Button reflexes can be programmed or modified using ButtonReflexJolt() (or disabled using the ButtonReflexClear() function below) at any time. The advantage of ButtonReflexJolt() over Jolt() is that once button reflexes have been programmed, button-triggered jolts do not require explicit Jolt() commands every time. Using explicit Jolt() commands requires the game to be responsible for monitoring the button states and creating the button-triggered jolts. Using ButtonReflexJolt() hands this responsibility over to the joystick.
Like the Jolt() command, ButtonReflexJolt() causes the joystick to react in the direction opposite the Direction angle. To program the trigger button to give the player a gunfire recoil jolt every time it is pressed, Direction should be 0 to indicate that the player is shooting directly ahead. The player would then feel a backward recoil jolt whenever the trigger button is pressed.
The RepeatRate parameter specifies the delay in milliseconds between start times of successive jolts when the assigned button is held down. Different rapid fire intervals can be created by adjusting this parameter. RepeatRate should always be greater than or equal to Duration.
Effect Examples
but
mag
dir
dur
rep
program pistol recoil on button 0
0
50
0
30
230
program machine gun recoil on button 0
0
100
0
30
80
program grenade launcher recoil on button 1
1
100
0
150
550
Bool ButtonReflexClear(unsigned int ButtonAssign)
ButtonAssign 0-15 assign effect to button # 0-15. Only buttons #0-3 currently supported.
Button reflexes can be cleared using this command at any time. Only the button reflex assigned to ButtonAssign is cleared. If several buttons have been programmed with ButtonReflexJolt() commands, ButtonReflexClear() must be called once for each ButtonAssign to clear them all.
Effect Examples
but
clear pistol recoil on button 0
0
clear grenade launcher recoil on button 1
1
Bool XVibration(unsigned int Lmagnitude, unsigned int Rmagnitude, unsigned int Frequency)
Lmagnitude 0-100 percent of maximum joystick force in the left direction
Rmagnitude 0-100 percent of maximum joystick force in the right direction
Frequency 0-50 frequency of vibration in cycles per second (Hz)
Vibration in the left/right or West/East direction. To generate vibrations of equal force back and forth in both directions, Lmagnitude and Rmagnitude should be equal. To generate vibrations with a bias to the right, Rmagnitude should be greater than Lmagnitude. Only one XVibration() effect can be active at a time. If a second XVibration() call is made with a prior XVibration() effect still active, the first will end and be replaced with the second.
Effect Examples
lmag
rmag
freq
driving with flat tire
50
50
7
driving with flat tire that pulls car more to right
0
100
7
driving over dirt road
25
25
20
engine hum
25
25
50
Bool XVibrationClear(void)
Ends any XVibration() effect.
Bool YVibration(unsigned int Umagnitude, unsigned int Dmagnitude, unsigned int Frequency)
Umagnitude 0-100 percent of maximum joystick force in the up direction
Dmagnitude 0-100 percent of maximum joystick force in the down direction
Frequency 0-50 frequency of vibration in cycles per second (Hz)
Vibration in the up/down or North/South direction. To generate vibrations of equal force back and forth in both directions, Umagnitude and Dmagnitude should be equal. To generate vibrations with a bias up, Umagnitude should be greater than Dmagnitude. Only one YVibration() effect can be active at a time. If a second YVibration() call is made with a prior YVibration() effect still active, the first will end and be replaced with the second.
Effect Examples
umag
dmag
freq
driving over rumble strips
0
75
10
engine hum
25
25
50
Bool YVibrationClear(void)
Ends any YVibration() effect.
Bool Buffeting(unsigned int Magnitude)
Magnitude 0-100 percent of maximum buffeting
Only one Buffeting() effect can be active at a time. If a second Buffeting()call is made with a prior Buffeting() effect still active, the first will end and be replaced with the second.
Effect Examples
mag
driving over irregular, rough terrain
50
flying thru turbulence
30
flying with damaged rudders thru turbulence
70
Bool BuffetingClear(void)
Ends any Buffeting() effect.
Bool VectorForce(unsigned int Magnitude,int Direction)
Magnitude 0-100 percent of maximum joystick force
Direction 0-360 direction in degrees of source of force, causes force in opposite direction (i.e., Direction-180), 0 = force in backward or down direction
Like the Jolt() and ButtonReflexJolt() commands, VectorForce() causes the joystick to react with a constant force in the direction opposite the Direction angle. If a constant force affecting the player emanates from the right side of the player, Direction should be 90. VectorForce() with Direction = 90 will cause the joystick to react in the direction opposite the Direction angle. Therefore, the player will feel a constant force to the left.
Only one VectorForce() effect can be active at a time. If a second VectorForce() call is made with a prior VectorForce() effect still active, the first will end and be replaced with the second. XYVectorForce() is another type of VectorForce(). If a VectorForce() effect is active, an XYVectorForce() will replace that effect and vice-versa.
Effect Examples
mag
dir
Crosswind From Left to Right (L/R)
50
270
Crosswind R/L and Headwind U/D
75
45
G-force from plane acceleration
75
0
Bool XYVectorForce(int XMagnitude,int YMagnitude)
XMagnitude -100 to 100 percent of maximum joystick force, sign indicates direction
YMagnitude -100 to 100 percent of maximum joystick force, sign indicates direction
XYVectorForce() is an alternative to VectorForce() for creating a constant force. Instead of taking Magnitude and Direction arguments, XYVectorForce() takes the magnitude in the X and Y directions, Xmagnitude and Ymagnitude, as arguments. Therefore, XYVectorForce() allows independent control of the forces in both the X and Y directions. The signs of Xmagnitude and Ymagnitude specify the direction of the forces based on the joystick orientation convention shown earlier. Positive magnitudes correspond to the positive X and Y directions, and negative magnitudes correspond to the opposite directions.
Only one VectorForce() effect can be active at a time. If a second VectorForce() call is made with a prior VectorForce() effect still active, the first will end and be replaced with the second. XYVectorForce() is another type of VectorForce(). If a VectorForce() effect is active, an XYVectorForce() will replace that effect and vice-versa.
Effect Examples
XMag
YMag
Crosswind From Left to Right (L/R)
50
0
Crosswind R/L and Headwind U/D
-50
-50
G-force from plane acceleration
0
-75
Bool VectorForceClear(void)
Ends any current VectorForce() or XYVectorForce() effect.
Bool XSpring(int Origin, unsigned int StiffnessLeft, unsigned int XStiffnessRight)
Origin -100 to 100 spring center position. -100 is full travel left, 0 is center, 100 is full travel right.
StiffnessLeft 0 - 100 spring stiffness in negative X direction (left)
StiffnessRight 0 - 100 spring stiffness in positive X direction (right)
The Spring commands are only supported in production model joysticks which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord.
This function creates a compliant restoring force that causes the joystick to return to a specified X position Origin in the joystick's X range of motion. The farther away the joystick is from Origin, the stronger this spring return force is. The strengths of the spring forces in the X directions are independently specified by the StiffnessLeft and StiffnessRight arguments. To create a bi-directional centering spring that resists in both left and right directions equally, both stiffness arguments should be set to the same value. To create a uni-directional spring that only resists motions left but not right, StiffnessLeft should be non-zero and StiffnessRight should be zero. Only one XSpring() effect can be active at a time. If a second XSpring() call is made with a prior XSpring() effect still active, the first will end and be replaced with the second.
Effect Examples
Origin
StiffnessLeft
StiffnessRight
plane in hard dive (stiffen stick in both directions)
0
100
100
wall on right side
10
0
100
g-forces from racecar (stiffen stick in both directions)
0
50
50
Bool XSpringClear(void)
Ends any current XSpring() effect.
Bool YSpring(int Origin, unsigned int StiffnessUp, unsigned int XStiffnessDown)
Origin -100 to 100 spring center position. -100 is full travel down, 0 is center, 100 is full travel up.
StiffnessUp 0 - 100 spring stiffness in positive Y direction (up)
StiffnessDown 0 - 100 spring stiffness in negative Y direction (down)
The Spring commands are only supported in production model joysticks which support position reporting capability (model #102). Position reporting capability can be determined with the InitStick(&StickRec) command by examining either the model number or the position feedback availability in the JoystickRecord.
This function creates a compliant restoring force that causes the joystick to return to a specified Y position Origin in the joystick's Y range of motion. The farther away the joystick is from Origin, the stronger this spring return force is. The strengths of the spring forces in the Y directions are independently specified by the StiffnessUp and StiffnessDown arguments. To create a bi-directional centering spring that resists in both up and down directions equally, both stiffness arguments should be set to the same value. To create a uni-directional spring that only resists motions up but not down, StiffnessUp should be non-zero and StiffnessDown should be zero. Only one YSpring() effect can be active at a time. If a second YSpring() call is made with a prior YSpring() effect still active, the first will end and be replaced with the second.
Effect Examples
Origin
StiffnessUp
StiffnessDown
plane in hard dive (stiffen stick in both directions)
0
100
100
wall behind
-10
0
100
moving through mud (stiffen stick in both directions)
0
50
50
Bool YSpringClear(void)
Ends any current YSpring() effect.
I-FORCE API Preliminary Specifications: Version 2.0
Advanced Force Effect Function Calls
The Immersion I-FORCE Force Feedback API will support many exciting additional commands including Force Feedback Profiles (FFPs) in Version 2.0. Preliminary prototypes and descriptions of these commands are presented here. These functions may change and are not meant for actual code development until I-FORCE API 2.0 is officially released (mid 1997). If there is something you would like to see incorporated into the I-FORCE API, please send us your suggestions and feedback.
Bool Damping(XViscosity, YViscosity)
This function creates a viscous damping force that resists joystick motions. The faster the joystick moves, the greater the resistance force. XViscosity and YViscosity independently specify how viscous the joystick feels in the X and Y directions. Higher values of XViscosity and YViscosity cause the joystick to feel like it is in very thick molasses or mud. Smaller values of XViscosity and YViscosity cause the joystick to feel like it is in water.
Bool Texture(XRoughness, YRoughness)
This function allows the user to feel textures as the joystick moves around. XRoughness and YRoughness independently specify how fine or how rough the textures feel in the X and Y directions. Smaller values of XRoughness and YRoughness represent very fine textures like sand while higher values of XRoughness and YRoughness represent very rough surfaces like coarse gratings.
User-Programmable and Downloadable Force Feedback Profiles (FFPs)
The I-FORCE API 2.0 will also support user-programmable Force Feedback Profiles (FFPs). Using a simple graphical editor, users can design their own force effect or FFP and play it back. For example, a game player could design a custom weapon recoil that begins with a slight trembling as the weapon charges, a quick and small forward kick, and finally a sudden and large backward kick as the weapon fires. These custom force effects or FFPs can then be saved and downloaded to the joystick to be used in any game that supports the I-FORCE API. FFPs provide infinite flexibility to create your own force sensations, and only Immersion's I-FORCE Force Feedback API will have it. The following commands allow developers to incorporate FFPs into their games.
int LoadFFP(Filename, Flags)
This function reads a .FFP file and loads it into the joystick's memory. It returns an Index value which is used by other FFP commands to access this particular FFP. Several FFPs can be loaded into the joystick's memory, each having a different Index value. Flags specifies on which axes the FFP will be played.
Bool PlayFFP(Index, Rate, Repeat)
This function plays the FFP loaded into memory and assigned to Index by LoadFFP(). Rate specifies how fast the FFP should be played, and Repeat specifies whether the FFP should be played once or continuously.
Bool ClearFFP(Index)
This function clears the FFP loaded into memory and assigned to Index by LoadFFP(). The freed Index can be assigned to a new FFP using LoadFFP().
Bool ButtonReflexFFP(ButtonAssign, Rate, Repeat)
The ButtonReflexFFP() command is similar to the ButtonReflexJolt() command, but assigns an FFP response to specific joystick button presses rather than a jolt. Button reflexes can be programmed or modified using ButtonReflexFFP() or ButtonReflexJolt() (or disabled using the ButtonReflexClear() function) at any time. The advantage of ButtonReflexFFP() over PlayFFP() is that once button reflexes have been programmed, button-triggered FFPs do not require explicit PlayFFP() commands every time. Using explicit PlayFFP() commands requires the game to be responsible for monitoring the button states and creating the button-triggered FFPs. Using ButtonReflexFFP() hands this responsibility over to the joystick.
Incorporating Force Feedback Into Your Application
You can download the most recent I-FORCE SDK from Immersion's I-FORCE web site:
www.force-feedback.com
To incorporate force feedback into your joystick DOS or Windows application, follow these simple steps:
1. #include "I-FORCE.H" in your program
2. At the beginning of your program, call SetJoystickPort(PortNum) and then InitStick(NULL). Check that the return value for InitStick() indicates that the stick is connected (return value of true)
<or>
Alternatively, if you want to upload data from the joystick, declare a variable of type JoystickRecord (e.g, JoystickRecord MyStick;) in your program and call SetJoystickPort(PortNum) and then InitStick(&MyStick). Again, check that the return value indicates that the stick is connected (return value of true)
3. When you want force effects to become active, call EnableForces().
4. Add force effects wherever desired using the commands described in Force Effect Function Calls.
5. At the end of your program, call CloseStick().
For DOS applications, compile and link your source file, I-FORCE.C, SERIAL.C, and SERIALPC.C. For Windows95/NT applications, use the 32-bit Windows Dynamic Link Library, IFORCE.DLL. Refer to the file FDBKTEST.C for an example DOS force feedback program. FTESTWIN.EXE and FTEST32.EXE are 16-bit Windows 3.1x and 32-bit Windows 95/NT versions of FDBKTEST.EXE with graphical user interfaces. FTEST32.EXE uses IFORCE.DLL. FDBKTEST.EXE will work on either COM1 or COM2, but FTESTWIN.EXE and FTEST32.EXE only uses COM1.
Using the I-FORCE Force Feedback Joystick Simulator Program
Your Immersion I-FORCE SDK includes a DOS simulator program for PCs that allows you to develop and test force feedback programs even if you do not have an I-FORCE force feedback joystick. The simulator program is called IMMSIM.EXE and runs on any PC with a serial port. The default port for IMMSIM.EXE is COM1. Type IMMSIM 2 to run IMMSIM.EXE using COM2. The simulator PC acts like the joystick and graphically displays all incoming joystick commands, all active force effects, and joystick status bytes 2 through 0 on the simulator screen. To use the simulator, connect the host computer running your force feedback program to the simulator PC using a null modem serial cable. If you are not using a null modem cable or a standard serial cable with a null modem adapter, the simulator will not work. The simulator runs on any of the standard COM ports (1-4). The default is COM1. To use a different serial port, type IMMSIM X where X is the number of the serial port you want to use. (This is not to be confused with the serial port on the host computer running your force feedback program. Your force feedback program must set which serial port it is using to control the joystick with either the SetJoystickPort() or SetJoystickAddressIRQ() commands.)
Immersion Contact Information
The Immersion I-FORCE(tm) Force Feedback API and Force Feedback Joysticks are revolutionary technologies. We are eager to see what can be achieved when they are integrated into your programs. We welcome questions, suggestions, or any other feedback. Please contact us at:
Immersion Corporation
2158 Paragon Drive
San Jose, CA 95131
(408) 467-1900 phone
(408) 467-1901 fax
I-FORCE Force Feedback API Information:
www.force-feedback.com
Immersion Corporation General Information:
www.immerse.com
E-mail questions to us at:
force@immerse.com
APPENDICES
Appendix A: Joystick Status Byte Encoding
Bit Meaning
Byte 0 0 Forces enabled (software)
0 -- forces are disabled by command
1 -- forces are enabled by command
1 Forces enabled (hardware)
0 -- forces are disabled by serial line DTR state
1 -- forces are enabled by serial line DTR state
2 Deadman switch status
0 -- deadman is active (forces are disabled)
1 -- deadman is inactive (forces are enabled)
3 Power status
0 -- external power is not connected
1 -- external power is connected
4 Copyright request received
0 - copyright message has been received
1 - copyright message has not been received
5 Position output status
0 -- position is not currently being reported
1 - position is being reported periodically
6 Overheat 1
0 - no overheat condition on axis 1
1 - overheat condition on axis 1
7 Overheat 2
0 - no overheat condition on axis 2
1 - overheat condition on axis 2
Bit Meaning
Byte 1 0 X vibration state
0 -- effect is not active
1 -- effect is currently active
1 Y vibration state
0 -- effect is not active
1 -- effect is currently active
2 Buffeting state
0 -- effect is not active
1 -- effect is currently active
3 Vector force state
0 -- effect is not active
1 -- effect is currently active
4 X spring state
0 -- effect is not active
1 -- effect is currently active
5 Y spring state
0 -- effect is not active
1 -- effect is currently active
6
7
Bit Meaning
Byte 2 0 Button 0 response state
0 -- no response defined for button 0
1 -- response defined for button 0
1 Button 1 response state
0 -- no response defined for button 1
1 -- response defined for button 1
2 Button 2 response state
0 -- no response defined for button 2
1 -- response defined for button 2
3 Button 3 response state
0 -- no response defined for button 3
1 -- response defined for button 3
4
5
6
7
Bit Meaning
Byte 3 0
1
2
3
4
5
6
7
Appendix B: Sample Programs
Pseudo-Code Flying Program
Below is a very simple example of how you might use the I-FORCE API to integrate force feedback into your programs. I-FORCE commands are shown in bold. I-FORCE return values are not checked in this pseudo-code example. For best results, your program should check return values.
main(void)
{
Bool IFResult;
SetJoystickPort(1); /* Joystick connected to serial port 1 */
IFResult=InitStick(NULL); /* Initialize communications with joystick */
IFResult=EnableForces(); /* Force effects will not work until EnableForces() is called */
StartTurbineEngine();
IFResult=XVibration(25,25,50); /* Simulate engine hum with 25% Magnitude, 50 Hz Vibration */
TakeOff();
IFResult=VectorForce(20,45); /* Simulate crosswind with 25% Magnitude, NE (45 degrees) VectorForce */
ArmMachineGun();
IFResult=ButtonReflexJolt (0,100,0,50,80); /* Set up a reflex gun recoil on button 0 (trigger),
100% magnitude, firing North (0 degrees), jolt lasting
40 ms, repeat jolt every 80 ms */
FireGun(); /* No Jolt call necessary since ButtonReflexJolt() has been set up */
ShotFromRightSide();
IFResult=Jolt(75,90,40); /* Simulate explosion on right side with 75% Magnitude Jolt at 90 degrees for 40 ms */
PlungingHardDive();
IFResult=XSpring(0,100,100); /* Simulate stiffening of flight stick from hard dive with XSpring
centered at origin 0 and maximum stiffness 100 both left and right */
IFResult=YSpring(0,100,100); /* Simulate stiffening of flight stick from hard dive with YSpring
centered at origin 0 and maximum stiffness 100 both up and down */
BlownUp();
IFResult=Buffeting(50); /* Cause stick to buffet wildly due to explosion of plane */
EndGame();
IFResult=ClearForces(); /* Clear all current force effects */
IFResult=CloseStick(); /* End serial communications with stick */
}
I-FORCE: The Force Feedback API from Immersion Corporation
Page 2
Page 33
Table of Contents
Overview of Force Feedback and I-FORCE
Compatibility
Compatibility
The I-FORCE Force Feedback Architecture
I-FORCE: The Force Feedback API from Immersion Corporation
I-FORCE API Specifications: Version 1.02
I-FORCE API Preliminary Specifications: Version 2.
Incorporating Force Feedback Into Your Application and Using the Joystick Simulator
Immersion Contact Information
APPENDICES
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.