Welcome

IFC Reference

Immersion Tools and Libraries
Overview and Documentation

IFC

Immersion Foundation Classes and the Immersion logo are trademarks of Immersion Corporation.

ã Immersion Corporation 1998-2002

801 Fox Lane . San Jose, CA 95131

Phone (408) 467-1900 . Fax (408) 467-1901

Version 2.3 Reference Manual

March 6, 2002

What's New in IFC 2.3

The latest version of this document can be downloaded at:

www.immersion.com


What's New in IFC 2.3

IFC 2.3 brings several changes to the CImmProject, CImmCompoundEffect, and CImmDevice classes. These new functions allow easier access to effect information by not requiring a device to be associated with the CImmProject before making effect data available for inspection. This also allows the CImmProject to write out complete IFR files without first having to create them on a device.

Internal changes have also lead to a simplification of the CImmProject member functions. The following table shows the names of new functions and functions that are now obsolete. Use this information to convert applications that previously used IFC2.2 to use IFC2.3.

Other changes include support for DirectX 8 interfaces in the CImmDXDevice class.

New Functions
CImmCondition
ChangeCenter | Changes the center point of a Condition.
CImmDevice
StopAll | Stops all effects playing on device.
CImmCompoundEffect
GetNumberOfContainedSounds | Returns number of Sound data objects in a CImmCompoundEffect.
GetContainedSound | Returns the name of the contained Sound.
GetTypeName | Returns the name of the effect type assigned by Immersion Studio.
CImmProject
AddSoundInfo | Adds a new Sound info object to CImmProject.
AddToCompound | Adds a new sound of effect object to a Compound contained in CImmProject.
CreateCompound | Adds a new Compound object to CImmProject.
GetEffect | Returns a pointer that allows access to a data object in CImmProject. The effect does not need to be created beforehand.
GetEffectName | Returns the effect name.
GetEffectType | Return the type of effect.
GetTypeName | Returns the name of the effect type assign by Immersion Studio.
GetNumEffects | Returns the count of all effects in CImmProject including those that have not been created.
GetNumSounds | Returns the number of Sound info objects in CImmProject.
GetSoundName | Returns the name of a Sound in CImmProject.
GetSoundPath | Returns the path info contained in a Sound object.
GetSoundData | Returns the duration and start delay values for the sound.
RemoveFromCompound | Removes a sound or effect object from a Compound contained in CImmProject.
RemoveSound | Completely removes a Sound object from CImmProject and from any Compounds that contain it.
RemoveEffect | Completely removes an Effect object from CImmProject and from any Compounds that contain it.
WriteToFile | Now writes IFR files as well as FFE files.
Obsolete Functions
CImmProject
GetCreatedEffect | see GetEffect for compatibility issues.
GetEffectNameFromIFRbyIndex | see GetEffectName for compatibility issues.
GetEffectTypeFromIFR | see GetEffectType for compatibility issues.
GetNumCreatedEffects | see GetNumEffects for compatibility issues.
GetNumEffectsFromIFR | see GetNumEffects for compatibility issues.
GetEffectSoundPathFromIFR | see GetSoundPath for compatibility issues.


Immersion Software License Agreement

IMMERSION FOUNDATION CLASSES (IFC) LICENSE AGREEMENT

PLEASE READ THIS SOFTWARE LICENSE AGREEMENT ("AGREEMENT") CAREFULLY BEFORE INSTALLING THE "IMMERSION FOUNDATION CLASSES" SOFTWARE. BY CLICKING ON THE "YES" BUTTON BELOW, YOU INDICATE YOUR ACCEPTANCE OF THE TERMS AND CONDITIONS OF THIS LEGAL AND BINDING AGREEMENT, AND CONSENT TO BE BOUND BY SUCH TERMS AND CONDITIONS. IF YOU DO NOT AGREE TO ALL OF THE TERMS AND CONDITIONS OF THIS AGREEMENT, CLICK THE "NO" BUTTON AND THE APPLICATION WILL IMMEDIATELY TERMINATE.

This Agreement is entered into between you (hereinafter "Developer"), and Immersion Corporation, a California Corporation having its principal place of business at 801 Fox Lane Drive, San Jose, California 95131.

1. Definitions

a) A “Developer” creates End-User Products through the use, in whole or in part, of the Licensed Software.

b) An “End-User Product” is software which contains Embedded Code.

c) The “Licensed Software” is Immersion Corporation’s “IMMERSION FOUNDATION CLASSES” software libraries, in executable form, which, in conjunction with compatible hardware peripheral products, may be used for creating and modifying force feedback effects.

d) The “Embedded Code” is code that is incorporated into or modified within an End-User Product in whole or in part through the use of the Licensed Software by Developer, or as a result of the copying or duplication by Developer of code created by a third-party in whole or in part through the use of the Licensed Software.

e) A “Publisher” causes the End-User Product to be reproduced and distributed to end-users, whether directly or indirectly, via the Internet or otherwise. A Publisher may also be the Developer, or may have retained Developer to create the End-User Product.

2. Grant of Rights

a) Immersion grants to Developer a non-exclusive, non-transferable, perpetual, worldwide, royalty free license (a) to download and use one (1) copy of the Licensed Software to create End-User Product(s); (b) to use, reproduce, publicly display, promote, publish and distribute End-User Product(s) over the Internet or otherwise; and (c) to sublicense Publisher(s) to publicly display, promote, publish and distribute End-User Product(s) over the Internet or otherwise, subject to and in compliance with the terms of this Agreement. Developer and its sublicensees have no right to, and agree not to, display, perform, copy, distribute, license or sub-license copies of the Licensed Software or the Embedded Code except as a part of or within an End-User Product.

b) Developer’s use of the Licensed Software is subject to the following additional terms:

(i) Developer may use the Licensed Software only on a single computer workstation;

(ii) Developer may make one (1) backup copy of the Licensed Software in machine-readable form solely for backup purposes, and must reproduce all applicable copyright and other proprietary legends on such copy;

(iii) Developer shall not make or distribute copies of the Licensed Software, except as permitted in (ii) above, and shall not electronically transfer the Licensed Software over a network;

(iv) Developer shall not decompile, reverse engineer, disassemble or otherwise reduce the Licensed Software to human-readable form;

(v) Developer shall not export the Licensed Software or the End User Products into any country prohibited by applicable export restrictions.

c) DEVELOPER’S SUBLICENSE AGREEMENT WITH PUBLISHER(S) SHALL CONTAIN ALL OF THE RESTRICTIONS IMPOSED UPON DEVELOPER BY THIS AGREEMENT, AND SHALL REQUIRE PUBLISHER(S) TO AGREE TO BE BOUND BY ALL SUCH TERMS PRIOR TO SUCH SUBLICENSE BECOMING EFFECTIVE. IN ADDITION, DEVELOPER’S SUBLICENSE AGREEMENT WITH PUBLISHER SHALL SPECIFY THAT IMMERSION CORPORATION IS A THIRD PARTY BENEFICIARY OF THE SUBLICENSE AGREEMENT, AND SHALL INCLUDE IMMERSION’S ADDRESS, AS SET FORTH ABOVE. DEVELOPER’S FAILURE TO ENTER INTO SUCH A SUBLICENSE AGREEMENT WITH EACH PUBLISHER WILL BE DEEMED A MATERIAL BREACH OF THIS AGREEMENT.

d) The foregoing license gives Developer limited rights to use the Licensed Software. Immersion retains all title to, and ownership in, the Licensed Software, and all copies thereof. Except as specifically set forth herein, no rights to use Immersion intellectual property is granted, either expressly or by implication, including, without limitation, any rights to any updates, enhancements, corrections or new versions of the Licensed Software. If Developer wishes to obtain any updates, enhancements, corrections and new versions of the Licensed Software, Developer may contact Immersion for a license to such software.

e) The foregoing license gives Developer limited rights to use the Licensed Software. Immersion retains all title to, and ownership in, the Licensed Software, and all copies thereof. Except as specifically set forth herein, no rights to use Immersion intellectual property is granted, either expressly or by implication, including, without limitation, any rights to any updates, enhancements, corrections or new versions of the Licensed Software, or any rights to practice under any Immersion patents. If Developer wishes to obtain any updates, enhancements, corrections and new versions of the Licensed Software, Developer may contact Immersion for a license to such software. If Developer wishes to obtain a license under any Immersion patents, it may contact Immersion for that purpose as well.

3. General Provisions

a) Indemnification of Immersion. With the exception of claims relating solely to the Licensed Software itself, Developer shall indemnify and hold Immersion harmless from and against all claims, demands, suits, liabilities, expenses, damages and judgments (including reasonable attorneys fees) arising out of third-party claims against Immersion relating to the display, promotion, performance and/or content of End-User Product(s).

b) Liability Exclusions and Limitations. IN NO EVENT SHALL IMMERSION BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES OF ANY KIND (INCLUDING BUT NOT LIMITED TO LOST PROFITS, LOSS OF USE OR INTERRUPTION OF BUSINESS), OR FOR LEGAL FEES, COSTS AND EXPENSES, ARISING OUT OF USE OF THE LICENSED SOFTWARE, REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT, TORT, STRICT PRODUCT LIABILITY OR OTHERWISE, EVEN IF IMMERSION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages under certain circumstances, so the above exclusions may not apply to Developer.

c) Disclaimer of Warranties. THE LICENSED SOFTWARE IS PROVIDED “AS IS,” WITHOUT WARRANTY OF ANY KIND. ALL WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD-PARTY RIGHTS, ARE HEREBY DISCLAIMED. IF SUCH A DISCLAIMER IS NOT ALLOWED UNDER APPLICABLE LAW, IMMERSION LIMITS SUCH WARRANTIES TO NINETY (90) DAYS FROM THE DATE DEVELOPER INSTALLED THE LICENSED SOFTWARE ON DEVELOPER’S COMPUTER. SOME STATES DO NOT ALLOW THE LIMITATION ON HOW LONG AN IMPLIED WARRANTY LASTS, SO SUCH LIMITATIONS MAY NOT APPLY TO DEVELOPER.

d) Termination. This license is effective until terminated. Developer may terminate the Agreement at any time by returning or destroying the Licensed Software and all copies to Immersion as set forth below. This Agreement and Developer’s right to use the Licensed Software shall terminate automatically if Developer materially breaches any part of this Agreement. Within five (5) days of termination for any reason, Developer agrees to return or destroy of all copies of the Licensed Software, and within two (2) weeks after any such termination, Developer shall specify in writing to Immersion that Developer has done so.

e) U.S. Government Rights: The Licensed Software is “commercial computer software” developed exclusively at private expense. In accordance with 48 CFR 12.212 or 48 CFR 227.7202, as applicable, use, duplication, or disclosure by the Government is subject to restrictions set forth in this Agreement.

f) Governing Law and Forum Selection. This Agreement shall be governed by the internal laws of the State of California, without regard to California conflict of laws provisions, and any disputes arising out of or relating to this agreement shall be filed in the state or federal courts located within Santa Clara County. Developer agrees to submit to the jurisdiction of such courts for purposes of resolving such disputes.

g) Entire Agreement. This Agreement is the entire agreement between you and Immersion relating to the Licensed Software, and supersedes all prior written or oral statements, promises, representations and agreements. It may be modified only by a writing executed by an authorized representative of Immersion.

h) You hereby acknowledge that you have read this Agreement, understand it, and agree to be bound by its terms and conditions.


IFC Introduction

IFC Reference

Introduction to the Immersion Foundation Classes

Quick Start

Situation: You have two days to add force feedback into your application, and you don’t know the first thing about the DirectX API for force feedback gaming controllers or the TouchSense API for Immersion pointing devices (e.g. Logitech’s tactile mouse). You can spend most of the two days reading through the DirectX SDK Help file and the source code to the DX SDK sample program FFDonuts (which shows only the most elementary concepts) and still be left dazed and confused. Or you can use the Immersion Foundation Classes (IFC) helper libraries and tools and cut and paste from the IFC SDK sample applications (which show just about everything you would ever want to do in a force feedback application) and have support for both standard DirectX and Immersion devices working in your application with just a few lines of code in a matter of minutes. All parts of the IFC SDK, including a great tutorial, are fully documented in the following chapters. If you need a quick start, read the IFC introduction then jump directly to the tutorial. Also, be sure to glance over the section about Maximizing Performance to avoid common mistakes and find useful concepts that will make your touch-enabled application more effective, more flexible, and better for the end user.

IFC: Write Once, Support All

The Immersion Foundation Classes (IFC) is a powerful new set of tools and libraries that allow developers to easily create "write-once, support all" force feedback devices software. Software applications that use IFC to create their tactile sensations will work both through the DirectX API on all DirectX force feedback gaming products and through the Immersion TouchSense API on all Immersion pointing products. IFC also fully supports Immersion Studio, the premier tactile-editing tool widely used by many developers today to design their DirectX force feedback effects. IFC can be used to touch-enable gaming and entertainment applications as well as business and productivity applications and is also the backbone for touch-enabled web pages and applications. Furthermore, IFC will support future platforms and future Immersion products.

What is IFC?

Written in C++, IFC provides much of the code necessary for creating and managing the force feedback device and effect COM interfaces required by the DirectX and Immersion TouchSense APIs. While COM interfaces are powerful and extensible, they also require tedious and lengthy bookkeeping tasks. By wrapping these complicated interfaces into intuitive, easy-to-use classes and helper tools, IFC allows developers to concentrate on the actual touch sensation design rather than laboring with COM. IFC was designed and created by force feedback programming experts at Immersion to make touch sensation programming easier and more intuitive, shorten development times, make code cleaner and more portable, and provide all the functionality of the underlying COM-based APIs without reducing programming freedom and flexibility.

IFC – Immersion Foundation Classes

Works with DirectX API

Yes

Works with Immersion TouchSense COM API

Yes

For Gaming/Entertainment Applications

Yes

For Business/Productivity Applications

Yes

For Web Applications

Yes

Works with DirectX Force Feedback Gaming Products (sticks, wheels, yokes, other)*

Yes

Works with Immersion Pointing Products (mice, trackballs, other)**

Yes

Works with Immersion Studio

Yes

* includes all Immersion gaming products, Immersion pointing device products in joystick-compatibility mode, as well as Microsoft’s Sidewinder FF products

** includes all Immersion pointing device products


I-FORCE 2.0 and DirectX

IFC Reference

Yesterday: I-FORCE 2.0 and DirectX

I-FORCE is a thin layer that works on top of the DirectX API

While DirectInput allows programmers to use a common interface for a variety of gaming controllers, the interface requires many steps and pages of code before even one force feedback effect can be described and played. Immersion created Immersion Studio to rapidly prototype force feedback effects and save effect information to a resource file (.ifr). The functions necessary to access an ifr file and fill the proper DirectInput structures are located in the I-FORCE 2.0 helper library. This is only a thin layer that works on top of DirectInput to make effect design faster and easier. DirectInput provides functions to access game controllers while the I-FORCE 2.0 library provides an easy way to read effect information out of an ifr file and into DirectInput. Since DirectInput is used to interface with the device, the use of the I-FORCE 2.0 library is fully compatible with DirectX. The I-FORCE 2.0 library has now been replaced by the much more powerful and flexible Immersion Foundation Classes, so developers who used to use the I-FORCE 2.0 helper library should now use IFC. The exception, developers who are still using straight C compilers and cannot use C++ classes. These C developers can continue to use the I-FORCE 2.0 helper library.


IFC and DirectX

IFC Reference

Today: IFC and DirectX

DirectInput contains all the necessary functionality to access and control force feedback joysticks and wheels but not mice. While you can get mouse input from a TouchSense enabled mouse through DirectInput, DirectInput currently does not have the ability to create tactile sensations on an Immersion TouchSense mouse. Although future versions of DirectX may add this ability, an API is needed for developers to use today. That API is the Immersion TouchSense API, which is largely similar to DirectInput in functionality and architecture but also allows programmers to create tactile effects for an Immersion TouchSense mouse.

IFC is a thin layer that works on top of the DirectX and Immersion TouchSense API

The I-FORCE 2.0 helper library provided a very simple way to load DX force feedback effects from Immersion Studio .ifr files and was widely used by many developers to speed up and simplify their force feedback development efforts. IFC takes this a step further by combining the same easy-to-use functionality of the I-FORCE 2.0 helper library with powerful and intuitive wrapper classes for creating and managing all aspects of the force feedback devices and effects for both gaming and pointing TouchSense devices. Whether the goal is to support a TouchSense gaming controller or a TouchSense mouse, IFC simplifies the process significantly. When accessing a TouchSense joystick or wheel, IFC uses DirectInput calls. When accessing a mouse with TouchSense Technology, IFC uses Immersion TouchSense API calls. IFC provides a single, consistent, and intuitive interface that can be used for all force feedback devices.

This overview provides details for how IFC works with the various APIs. For more details about compatibility between various TouchSense hardware refer to the Compatibility section.


DirectX, Immersion TouchSense API, and IFC Compatibility

At present, there are twenty-four hardware manufacturers that have announced plans to produce force feedback hardware gaming products including Logitech, ThrustMaster, Microsoft Hardware Group, CH Products, Primax, LMP, Mouse Systems, ACT Labs, SC&T, Anko, Mad Catz, and many more. Twenty-two of these manufacturers are using Immersion gaming technology, formerly I-FORCE 2.0, which supports 100% of the DirectX DirectInput Force Feedback API. Furthermore, Logitech’s Wingman Force Feedback Mouse uses Immersion’s Immersion pointing device technology, which works through the Immersion TouchSense API but can also be made to work through DirectX as a game controller. This section will further clarify the current state of force feedback so that your force feedback development plan can be a single, easy effort that ensures support for the largest number of hardware products possible.


DirectInput API and Immersion Gaming Products

Immersion Corporation and Microsoft worked closely together to spec out and add force feedback to DirectX. Immersion gaming products support 100% of the DirectInput Force Feedback features. There is no Immersion gaming device API; DirectInput is the only API for Immersion gaming devices. If you are developing an application for a DirectX force feedback gaming product (i.e., joystick, wheel, yoke), you should use the IFC helper tools and libraries, which work through the standard DirectInput API. All upcoming gaming products using Immersion gaming technology will be 100% DirectInput force feedback compatible. This includes all new force feedback gaming products from Logitech, Thrustmaster, CH Products, Primax, LMP, ACT Labs, Mouse Systems, SC&T, Anko, Mad Catz, and others.


DirectInput API, Immersion TouchSense API, and Immersion Pointing Device Products

As described in the previous section, DirectInput contains all the necessary functionality to access and control Immersion gaming controllers but not Immersion pointing devices. While you can get mouse input from a TouchSense enabled mouse through DirectInput, DirectInput currently does not have the ability to create forces on a TouchSense enabled mouse. Although future versions of DirectX may add this ability, an API is needed for developers to use today. That API is the Immersion TouchSense API, which is largely similar to DirectInput in functionality and architecture but also allows programmers to create tactile effects for an Immersion TouchSense mouse. If you are developing an application for an Immersion pointing device, you should use the IFC helper tools and libraries, which work through the standard Immersion TouchSense API.

For force feedback applications with a joystick as the preferred input device (instead of a mouse), it is possible to use a Wingman Force Feedback mouse as a gaming controller and therefore work with that application through the DirectInput API. However, in order to do so, the Wingman Force Feedback mouse must be switched into a “joystick-compatibility” mode and the gaming controller driver loaded from the Game Controllers control panel. In this mode, the Wingman Force Feedback mouse will stop providing mouse input and instead start providing joystick input. In other words, you will not be able to control the cursor in your application with the Wingman Force Feedback mouse, but you will be able to use it like a miniature joystick. For some games requiring fine joystick control, this mode works very well. In addition, all DX force feedback effects you created for a joystick are fully supported and will actually play on the Wingman Force Feedback mouse although they might need to be made stronger or weaker to feel best on the mouse. While this mode exists, it is not a replacement for Immersion TouchSense mouse support. If your application’s preferred input device is a mouse and not a joystick, the correct procedure is use IFC and to add touch sensations to your application through the Immersion TouchSense COM API.

In addition to full Force Feedback devices, Immersion has a class of devices based on Immersion’s Inertial Harmonic Driveä (IHD). Different from full Force Feedback that contains various mechnical designs for controlling the motion of an input device, IHD provides tactile senations through a wide range of vibrations without affecting device postion. The first retail IHD device, the tactile feedback mouse from Logitech, uses various vibrations to create effect primates such as Constants Forces, Dampers, Friction, Inertia, Grids, Springs, Periodics, Ramp Forces, Textures, Ellipses, and Enclosures. The class of mice that use IHD are also called Tactile Feedback mice. Unlike the Wingman Force Feedback mouse, iFeel does not have a joystick compatibility mode.


I-FORCE 1.x API and Products

The Force FX from CH Products is an I-FORCE 1.x device. This was a first generation consumer force feedback gaming product released in 1996. It was designed to work with the I-FORCE 1.x API, which is now obsolete and replaced by DX.

Old Win95 applications written using the obsolete I-FORCE 1.x API (Need For Speed II, Air Warrior II, Rocket Jockey, Descent II, etc) can be made to work on any DirectX force feedback device using the Immersion DX iforce.dll. The Immersion DX5 iforce.dll translates I-FORCE 1.x API calls into DX DirectInput API calls. Simply replace the old I-FORCE 1.x iforce.dll with the new DX iforce.dll.


IFC and Immersion Studio

Unfortunately, direct coding with the DirectX or TouchSense API is not the best way to rapidly design touch sensations because design is an iterative process that requires assigning parameters, touch sensations, and modifying parameters until you get the sensation just right. Thus, programming through the DX or Immersion TouchSense API alone is a slow and difficult way to design sensations: “Should I try 2.35 Hz or 3.12 Hz? What’s the button trigger offset mask? Should I use Polar or Cartesian coordinates?”

Immersion Corporation has developed a graphical programming environment called Immersion Studio that is ideal for designing, testing, and implementing DX and Immersion force feedback sensations. By simplifying the entire force feedback programming process, Immersion Studio allows you to focus on designing your touch sensations rather than worrying about the syntax of the DirectX or Immersion TouchSense API. Immersion Studio for games was designed to be 100% compatible with DirectX, which means it supports all of DirectX’s features and will play effects on ANY DirectX force feedback device. Furthermore, effects designed in Immersion Studio for Applications and Web are 100% compatible with the Immersion TouchSense API and will play on any Immersion pointing device product. A summary of Immersion Studio features and capabilities is outlined in the table at the end of this chapter.

Any standard DirectX or TouchSense enabled Mouse effect can be created in Immersion Studio and saved in Immersion Force Resource (.IFR) files. Applications which use IFC functions like InitializeFromProject() can load these standard DirectX and Immersion effects from the .IFR file at runtime to be played on ANY TouchSense product. If tactile effects need to be modified, no recompile is necessary. Changes simply need to be made directly in Immersion Studio and the .IFR re-saved. Since Immersion Studio will also be distributed to end consumers, using .IFR files in an application empowers end consumers to customize tactile effects in the application at any time. Two sample applications with source code called HelloIFC and IFCDonuts are included in the IFC SDK and show how easy it is to create an Immersion TouchSense enabled application using Immersion Studio and .IFR files.


Microsoft SidewinderFF SDK

The Microsoft Hardware Group (which is separate from the DirectX Group) has released the Sidewinder Force Feedback joystick (SWFF). The SWFF also works with the DX DirectInput API, but does not support 100% of DX’s features and capabilities. The limitations of the SWFF are outlined in the table at the end of this chapter.

The SWFF SDK used to include a graphical force feedback editing tool called Visual Force Factory. Unlike Immersion Studio, Visual Force Factory was not designed to work with DX-compatible hardware. It uses a proprietary SWFF API and therefore cannot play tactile effects on a non-SWFF force feedback device, even if it is 100% compatible with DX. Visual Force Factory also does not allow many standard DX force feedback features. Finally, Visual Force Factory will not be distributed to end consumers. These limitations are outlined in the table at the end of this section.

The SWFF SDK includes ROM effects and VFX effects (created from Visual Force Factory .FRC files), which are not compatible with a non-SWFF force feedback device. These effects are not part of the standard DX force feedback effect set and will fail creation on anything other than a SWFF device. Therefore, applications which use SWFF SDK functions like SWFF_CreateVFXEffectFromFile() or SWFF_CreateROMEffect() will not be compatible with most DX devices. This includes most of the sample applications in the SWFF SDK, including Tigershark. The SDK functions SWFF_CreateDIEffectFromFile() and SWFF_CreateDIEffectFromFileEx() will attempt to translate VFX effects from a Visual Force Factory .FRC file into the closest standard DX effects that will work on any DX force feedback device, but results can not be guaranteed.

IMPORTANT: Unfortunately, a small number of games were written using this proprietary Microsoft Hardware SWFF API instead of with the industry-standard Microsoft DX force feedback API or IFC libraries. These games will not work with any Immersion device, and some are listed below. Again, Immersion gaming devices are 100% DX force feedback compatible. The incompatibility with these games is due to the fact that the games did not support standard DX.

Bug Riders
Die by the Sword
Interstate 76
MDK
Sierra Ski Racing
Tigershark
Trophy Rivers


Summary

To ensure your touch-enabled applications are fully compatible with all current and upcoming DirectX force feedback gaming products and Immersion pointing products, you have two choices. You can have two separate development efforts: one for the DirectX gaming controllers using the standard DirectInput API (which is somewhat tedious but guarantees compatibility among all DirectX force feedback products) and one for Immersion pointing products using the Immersion TouchSense API (which is also somewhat tedious). Your alternative is to use Immersion Studio and the IFC libraries, which guarantees compatibility among all DirectX force feedback products and all Immersion pointing products. Furthermore, using Immersion Studio allows runtime touch sensation customization for both the developer and the end user. You can download the complete IFC SDK from our website, www.immersion.com. The SDK includes IFC header and library files, IFC sample programs, IFC documentation (including a great tutorial), Immersion Studio, and everything else you need to start incorporating touch into your applications.


Compatibility Table

 | I-FORCE 1.x Devices | Immersion Gaming Devices | Microsoft Sidewinder FF
Manufacturers | CH Products Interactive I/O | ACT Labs Anko Electronics AVB Broeder CH Products Chic Genius Guillemot Happ Controls Immersion Interactive I/O KYE LMP Logitech Mad Catz Mouse Systems Padix Primax Rockfire SC&T International SMFC Thrustmaster Trust | Microsoft Hardware Group
Release Date | Fall 1996 | Throughout 1998 & 1999 | Fall 1997
Position Reporting | Analog or Digital | Digital | Digital
Interface | Serial and/or Standard Game Port | Serial or USB | Sound Blaster 16 Game Port with MIDI
Maximum Device Communication Rate | 9600 baud | Serial: 38400 baud USB: 1200000 baud | 31250 baud
Force Coprocessor | 4 MHz, 8 bit microprocessor | 48 MHz, 16 bit RISC microprocess if using Immersion TouchSense Processor, or 24 MHz, 16 bit microprocessor | 25 MHz, 16 bit microprocessor
Maximum Non-Aliased Frequency for Periodic Effect | ~40 Hz | ~350 Hz | ~30 Hz
AC Cooling Fan | Not Required | Not Required | Required
Noise Level | 0 decibels | 0 decibels | 30 decibels (fan)
Force Feedback API | Designed for I-FORCE 1.x API. Minimal support for DirectX API | 100% Support for DirectX API with additional Immersion features | Designed for Sidewinder Force Feedback API. Incomplete support for DirectX API


Overview of Immersion Studio

The challenge of programming for force feedback is not the act of coding, it is the act of designing touch sensations that appropriately match your gaming events and environments. Designing touch requires a creative and interactive process where parameters are defined, experienced, and modified until the sensations are just right.

To let software developers best take advantage of the new creative medium of touch, Immersion Corporation has produced an interactive and intuitive environment for touch sensation design. Immersion Studio is a fully animated graphical environment for rapidly adjusting physical parameters, touching sensations, and then saving them as Immersion resources which can be automatically loaded and executed by your application through the DirectX or Immersion TouchSense API. Programmers craft tactile sensations by stretching springs, manipulating surfaces, placing liquids, and adjusting other intuitive physical metaphors that represent each associated tactile phenomenon.

Immersion Studio is fully compatible with all Immersion gaming controllers (e.g., joysticks and steering wheels) that work with standard DirectX as well as Immersion pointing devices like the Logitech Wingman Force Feedback Mouse and the tactile feedback mouse. Another important feature of Immersion Studio is that it empowers end users with the ability to edit the Immersion Force Resource (IFR) file using the same intuitive animated graphical controls used by the game designer. In other words, Immersion Studio allows game players to tweak the touch sensations of their games from home. Imagine adjusting the hum of your laser gun, the rev of your V8 engine, or the swish of your tennis racquet. It is almost as fun to edit touch sensations using Immersion Studio as it is to play the actual game. This can only be done if the game developer uses Immersion Studio to produce the standard DirectX or Immersion effects.


Features and Benefits

  • Intuitive Graphical Metaphors: Adjust force feedback parameters using easy-to-understand, editable, pictorial controls. See a wave form, feel a wave form. See a spring, feel a spring. See water, feel water.
  • Fully Interactive and Animated: Adjust parameters by simply dragging the pictorial control points, adjusting sliders and dials, or typing in numbers directly. Experience the resulting sensations in real-time as you manipulate controls.
  • Fully Customizable Sensations and Numerous Preset Examples: Create your own custom sensations or use one of the many predefined effects (e.g., Lasers, Cannons, Mud, Slippery Ice). You can save, copy, modify, or combine them to create a library of your favorite touch sensations.
  • Seamless Integration with DirectX, TouchSense, and IFC: Immersion Studio saves your sensations as resources compatible with both the DirectX and Immersion TouchSense APIs. Developers can then use IFC to automatically load the resources, instantiate and fill all the necessary DirectX or Immersion structures, and execute your specified effects in your application.
  • Simplifies DirectX/Immersion Programming: Immersion Studio handles all of the complex and tedious bookkeeping necessary required by the COM-based DirectX and Immersion TouchSense APIs. You never have to acquire or enumerate devices, track coordinate frames, or set axis masks. Immersion Studio takes care of all that for you!
  • Easily Modify Effects from your Applications: Parameters for existing Immersion Studio effects can be easily altered directly from your application with the powerful and easy-to-use library of classes provided in IFC.


IFC Tutorial

As mentioned in the introduction, the Immersion Foundation Classes (IFC) abstracts all of the tedious details of the COM interfaces required by the DirectX and Immersion TouchSense APIs and offers C++ programmers an extremely simple and fast way of adding touch sensations to any application. Setting up the standard force feedback COM interfaces require dozens of lines of code to query the interface, enumerate objects, and perform all the other necessary setup tasks – not to mention the actual code for creating and starting effects. With the Immersion Foundation Classes, just a few minutes and a few lines of code will transform your software into an application that can communicate with users through the sense of touch! This section offers a brief tutorial showing how this is done.

Step 1: Include and Lib Files

Step 2: Create a Device and Object

Step 3: Create Effect Objects

Step 4: Play and Modify Effects

Step 5: Clean Up Device and Effects

Code Example


Include and Lib Files

IFC Reference

Step 1:
Include the IFC header file and link to the necessary libraries

#include "ifc.h"

The header file ifc.h can be found in the inc folder of the IFC SDK install directory. Also set up your development environment to link to ifc*.lib, which can be found in the lib folder. If DirectX functionality is required dinput.lib, dxguid.lib will also be needed. The last two can be found in the DirectX SDK and are for the DirectInput API for force feedback gaming controllers. If you are still getting linker errors you may need to explicitly add those three lib files to your project settings.

Note: New versions of IFC libraries with updates and new features will be periodically released. The dll and lib files will be called ifc*.dll and ifc*.lib where * denotes the revision number. Make sure to get the newest versions of these libraries of the IFC SDK and to check the SDK release notes for important information about IFC revisions. Also, to avoid versioning conflicts, MSDN recommends including all dll runtime libraries in the same folder as your executable when deploying your application.

Optional: You can turn on error messages that can be useful when debugging your IFC applications. You can send error messages to a debug output window, to a dialog box, or to both. To turn it on, add the following macro to your code:

IFC_SET_ERROR_HANDLING( IFC_OUTPUT_ERR_TO_DEBUG | IFC_OUTPUT_ERR_TO_DIALOG );


Create a Device Object

IFC Reference

Step 2:
Create a Device Object

The CImmDevice class is the abstract base class for all force feedback device classes. Since CImmDevice is an abstract class, an object of CImmDevice should not be created. Instead, one of the derived classes should be instantiated to access a corresponding device. Currently, there are only two derived classes. The first is CImmMouse for Immersion pointing devices. The second is CImmDXDevice for all DirectX-compatible force feedback gaming controllers like Immersion joysticks and steering wheels. As additional types of force feedback devices become available, new classes will be introduced that derive from CImmDevice.

If you need to call a method of the IFeelitDevice or IDirectInputDevice2 interface (e.g. SetProperty), use this GetDevice to get the device interface and call the method directly. If you are calling the DirectX API you will need to cast LPIIMM_DEVICE to LPDIRECTINPUTDEVICE2.


Mouse Only Application

IFC Reference

Case 1:
What do I do if my application only uses a mouse?

If your application is exclusively for pointing products like a Logitech tactile feedback mouse or Wingman Force Feedback Mouse, you should use a CImmMouse object. In your application code, declare a CImmMouse object pointer and initialize it.

CImmMouse* m_pTSMouse;

// initialize to NULL

m_pTSMouse = NULL;

// Initialize the ImmMouse and check success or failure

m_pTSMouse = new CImmMouse;

if ( !(m_pTSMouse->Initialize( AfxGetInstanceHandle(), m_pMainWnd->m_hWnd )) )

{

// failed Initialize call

delete m_pTSMouse;

m_pTSMouse = NULL;

}

Tactile sensations can feel quite differently on a full force feedback device versus a tactile feedback mouse, so it is sometime necessary to detect the type of mouse that has been found. IFC21 currently does not have an easy to use function to accomplish this, but the following code shows how it should be done. IFC22 will contain a better interface that will allow developers easy access to this information.

// check the type of the device

LPIIMM_DEVICE piDevice= m_pTSMouse->GetDevice();

if (piDevice)

{

IMM_DEVCAPS devcaps;

devcaps.dwSize = sizeof(IMM_DEVCAPS);

HRESULT hRes = piDevice->GetCapabilities(&devcaps);

if (SUCCEEDED(hRes))

{

switch(devcaps.dwDevType)

{

case 0x00000022: //Old API

case 0x00000202: //New API

//Full force feedback device found!

break;

case 0x00000302: //New API only

//Tactile feedback mouse found!

break;

}

}

}

Since any TouchSense enabled mouse is a standard system mouse, there are no methods to read mouse position in IFC. You can use the same methods to read input from a regular mouse. IFC is solely for output. That said, you do need to know how your application currently reads mouse input. If your application is not using the standard Win32 mouse messages (e.g., WM_MOUSEMOVE) and functions (e.g., GetCursorPos) to read mouse movement and display the cursor, you will also need to notify IFC that your CImmMouse device should work in relative mode. (Information concerning absolute mode is only applicable to full Force Feedback mice that are attached to their mouse pad such as the Wingman Force Feedback mice. The tactile feedback mice report information in relative mode and will work with standard windows and Dinput position calls). The CImmMouse is by default in absolute mode, meaning it reports an actual screen cursor position and assumes your application is using the standard Win32 mouse services. DirectX is not part of the standard Win32 mouse services, so if you are using DirectX, you need to switch your CImmMouse object to relative mode with the following method:

// change from standard Win32 mouse services to relative position reporting

m_pTSMouse->UsesWin32MouseServices(FALSE);

If you are not sure which mode to use, use the following guidelines. Applications that don’t have a screen cursor and/or allow you to move the physical mouse infinitely in one direction and continually rotate or pan (e.g., 1st person action games) generally use relative mode. Applications that actually have a cursor that stops at the edge of the screen even if you keep moving the physical mouse further generally use the absolute Win32 mouse services. A game like Microsoft’s Age of Empires allows continual panning. However, the actual cursor stops at the edge of the screen while panning, so it is using absolute mode.

IMPORTANT: If while using your Immersion device you can move the cursor in other applications but cannot get mouse movement in your application, you most likely need to either switch your CImmMouse to relative mode or use GetCursorPos if that is suitable for your application.

IMPORTANT: If your application switches your CImmMouse to relative mode, you will not be able to use the two screen-position based effects - Enclosure and Ellipse. Both these effects require you to specify their screen locations and are active only when the cursor is in those locations. If you want to use Enclosure and Ellipse effects, your application needs to leave the CImmMouse object in absolute mode and use the Win32 mouse services for mouse input.


Joystick or Wheel Only Application

IFC Reference

Case 2:
What do I do if my application only uses a joystick or wheel?

If your application is exclusively for DirectX gaming controllers like an Immersion joystick, wheel, or yoke, you should use a CImmDXDevice object. In your application code, declare a CImmDXDevice object pointer and initialize it.

CImmDXDevice* m_pDXDevice;

// initialize to NULL

m_pDXDevice = NULL;

// Initialize the ImmDXDevice and check success or failure

m_pDXDevice = new CImmDXDevice;

if ( !(m_pDXDevice ->Initialize( AfxGetInstanceHandle(), m_pMainWnd->m_hWnd )) )

{

// failed Initialize call

delete m_pDXDevice;

m_pDXDevice = NULL;

}


Mouse, Joystick, or Wheel

IFC Reference

Case 3:
What do I do if my application uses either a mouse or a joystick/wheel?

If your application can use either a pointing product or a DirectX gaming controller, you can 1) create one of each object and use the one that successfully initializes, or 2) create a single object pointer of the CImmDevice abstract class and ask it to initialize a device for you. If a user has both an Immersion pointing device and a DirectX force feedback device connected, both will successfully initialize. Therefore, if you are supporting both types of devices and using method #1, you should decide which should be the default and try initializing that device first. If the default device initialization succeeds, use that device object throughout the rest of your program and do not use the secondary device object. If the default device fails initialization, try initializing the secondary device object and use that object if it succeeds. In the example below, the default input device is a mouse and the secondary input device is a joystick.

CImmMouse* m_pTSMouse;

CImmDXDevice* m_pDXDevice;

// initialize to NULL

m_pTSMouse = NULL;

m_pDXDevice = NULL;

// Initialize the ImmMouse and check success or failure

m_pTSMouse = new CImmMouse;

if ( !(m_pTSMouse->Initialize( AfxGetInstanceHandle(), m_pMainWnd->m_hWnd )) )

{

// failed Initialize call

delete m_pTSMouse;

m_pTSMouse = NULL;

// Initialize the ImmDXDevice and check success or failure

m_pDXDevice = new CImmDXDevice;

if ( !(m_pDXDevice ->Initialize( AfxGetInstanceHandle(), m_pMainWnd->m_hWnd )) )

{

// failed Initialize call

delete m_pDXDevice;

m_pDXDevice = NULL;

}

}

Method #2 lets the CImmDevice::CreateDevice method automatically initialize the first device it finds for you. It will always look for a CImmMouse first, then a CImmDXDevice second.

CImmDevice* m_pImmDevice;

// initialize to NULL

m_pImmDevice = NULL;

// Initialize a ImmDevice and check success or failure

m_pImmDevice = CImmDevice::CreateDevice( AfxGetInstanceHandle(), m_pMainWnd->m_hWnd )

if ( !m_pImmDevice)

{

// failed CreateDevice call

delete m_pImmDevice;

m_pImmDevice = NULL;

}

else

{

if (m_pImmDevice->GetDeviceType() == IMM_DEVICETYPE_MOUSE)

OutputDebugString("Found Immersion Mouse\n");

else if (m_pImmDevice->GetDeviceType() == IMM_DEVICETYPE_DIRECTINPUT)

OutputDebugString("Found DirectInput FF Device\n");

}

IMPORTANT: Note that CImmDevice::CreateDevice must always be called with the full scope specifier as follows:

CImmDevice::CreateDevice(hinst, hwnd);

IMPORTANT: Since CImmDevice is an abstract base class, you should never directly create or allocate a CImmDevice object like you can with one of the derived classes. You can only directly create a CImmDevice object pointer and use this pointer to store the return value of CImmDevice::CreateDevice. Notice in the above code example, the new operator is not used to allocate a CImmDevice like it is in Method #1 to allocate a CImmMouse or CImmDXDevice.

IMPORTANT: Note that Method #2 does not let you use pre-existing DirectX COM interfaces. This is explained in more detail below in Case 4 and Case 5.

Alternatively, you can intentionally create and initialize both a CImmMouse and a CImmDXDevice. This actually allows you to have force feedback effects on both the gaming device and the pointing device simultaneously (however each device would have its own effects independent from the other device). This mode of operation would be interesting for applications where a user would control the pointing device (e.g. a Logitech tactile feedback mouse) with one hand and the gaming device (e.g., an Immersion steering wheel) with the other hand or for two users each using a different controller on the same computer. Obviously, this would only work on computers that actually have one of each device connected.

Note that the same guidelines from Case 1 regarding absolute versus relative position mode for the CImmMouse still apply here.

IMPORTANT: In all the code examples above, note that Initialize requires both the application’s HINSTANCE and HWND. The examples are from MFC applications and use the MFC function AfxGetInstanceHandle. If you do not use MFC, you will not be able to use this function.

IMPORTANT: Note that in all the examples above, if the Initialize call fails, the CImmDevice object is deleted and set to NULL. This makes it easy to prevent accidental attempts to access a non-existent device, which can cause your application to crash. Simply perform a NULL check prior to any attempts to access the device, which includes creating and starting effects. If you wish to determine the cause of any failed IFC call, use the IFC_GET_LAST_ERROR macro, which returns the HRESULT of the operation.


Existing DX Force Feedback

IFC Reference

Case 4:
What if I already have force feedback in my application using DirectX?

If your application already supports force feedback using DirectX, you can leave that part just the way it is. If you would like to also support Immersion pointing products like the Logitech tactile feedback mouse or Wingman Force Feedback Mouse, you should use IFC to add a CImmMouse object to your application like in Case 1 above. You will not be able to use the DX force feedback effects you have already created with your CImmMouse object. However, since the Immersion effects are a superset of DirectX effect types, you should be able to very quickly make the equivalents for all the DX effects with IFC effects for the CImmMouse. You can then tweak the feels so that they are more suitable for a mouse and create more feels that are only possible on a mouse (e.g., textures, enclosures/gravity wells, etc.).

IMPORTANT: The rules from Case 3 regarding determining a default device still apply here.

While the above process is perfectly acceptable and correct, it does result in two force feedback implementations – one using DirectX for gaming controllers and one using IFC for pointing products. Both implementations will do very similar things and actually play similar effects at mostly the same places. There is no performance loss since if one of the devices is not present, all functions relating to that device and any effects associated with it will immediately return FALSE. Furthermore, all Immersion products, both pointing and gaming devices, have microprocessors built in that take care of generating all the tactile effects, so there is no burden on the host with the addition of force feedback on Immersion products.

Alternatively, you can change your existing DirectX implementation into an IFC implementation so that there is a single set of IFC calls for both Immersion gaming controllers and pointing devices. This single implementation is described in Case 3.


Existing DX Code without FF

IFC Reference

Case 5:
What if I already use DirectX in my application but don’t have force feedback yet?

If your application already uses the COM interfaces of DirectInput (only DX5 or later), but you don’t have force feedback implemented yet, again you can leave that part just the way it is. Simply use IFC according to one of the first three cases above with one exception. The exception is that the Initialize method for a CImmDXDevice has optional third and fourth arguments for existing LPDIRECTINPUT and LPDIRECTINPUTDEVICE2 interface pointers. If you have already created an IDirectInput interface in your application, simply pass a pointer to this interface as the third parameter in your Initialize call for your CImmDXDevice. If you have already created an IDirectInputDevice2 interface in your application, simply pass a pointer to this interface as the fourth parameter in your Initialize call for your CImmDXDevice. IFC will then forego creating another instance of these interfaces and simply use the pre-existing one(s) for the DirectX force feedback implementation.

IMPORTANT: The IDirectInputDevice2 interface must be for a force feedback device. If no IDirectInputDevice2 interface for a force feedback device exists, pass in ONLY the IDirectInput interface and IFC will create its own IDirectInputDevice2 interface.

IMPORTANT: Normally IFC will create the IDirectInput and IDirectInputDevice2 interfaces in the CImmDXDevice::Initialize method and release the interfaces when the CImmDXDevice object is deleted. If you pass in a pre-existing IDirectInput or IDirectInputDevice2 interface to the Initialize method, IFC will AddRef those interfaces before releasing them when the device object is deleted. Using AddRef and Release ensures that the reference count stays accurate. The COM object will deallocate itself when the reference count reaches 0. It is your application’s responsibility to also release those interfaces since your application created them independently of IFC.


Create Effect Objects

IFC Reference

Step 3:
Create Effect Objects

The CImmEffect class is the base class for all derived IFC effects. This base class only provides the common functionality for all the IFC effects. Effect-specific information (aka type-specific parameters) and functionality exist only in the derived classes, so you should always use the lowest possible derived effect class (e.g., use CImmSpring instead of CImmCondition or CImmEffect).

If you need to call a method of the IFeelitEffect or IDirectInputEffect interface (e.g. GetEffectStatus), use GetEffect to get the device interface and call the method directly. If you are calling the DirectX API you will need to cast LPIIMM_EFFECT to LPDIEFFECT.


Effects from Scratch

IFC Reference

Method 1:
You provide the effect parameters

The code below shows how to add a Spring (for a Stretch effect), a Square Wave (for a Pop effect), and an Enclosure (for a Gravity Well/Snap effect) to an application with you providing the parameters describing the effects. In your application code, declare the effect object pointers and initialize them. Note that you can provide some, none, or all the parameters to the effect Initialize method. IFC will fill in default values for those left unspecified. If you designed your effects in Immersion Studio, you can enter the parameter values you came up with into the Initialize call.

CImmSpring* m_pSpringStretch;

CImmPeriodic* m_pPop;

CImmEnclosure* m_pEnclosureSnap;

// check for valid CImmMouse object

if (m_pTSMouse)

{

BOOL bRes;

// Create Spring effect

m_pSpringStretch = new CImmSpring;

bRes = m_pSpringStretch->Initialize(

m_pTSMouse, // CImmDevice* pDevice

10000, // LONG Coefficient

10000 // DWORD Saturation

);

if (!bRes)

{

delete m_pSpringStretch;

m_pSpringStretch = NULL;

}

// Square Wave Vibration

m_pPop = new CImmPeriodic( GUID_Imm_Square );

bRes = m_pPop->Initialize(

m_pTSMouse, // CImmDevice* pDevice

3000, // DWORD Magnitude

15, // DWORD Period (ms)

15 // DWORD Duration (ms)

);

if (!bRes)

{

delete m_pPop;

m_pPop = NULL;

}

// Create Snap effect

m_pEnclosureSnap = new CImmEnclosure;

// Initially start Snap at screen coords 200,200

POINT enclosureCenter;

enclosureCenter.x = enclosureCenter.y = 200;

bRes = m_pEnclosureSnap->Initialize(

m_pTSMouse, // CImmDevice* pDevice,

50, // DWORD dwWidth

50, // DWORD dwHeight

3000, // LONG lHorizStiffness

5000, // LONG lVertStiffness

20, // DWORD dwHorizWallWidth

20, // DWORD dwVertWallWidth

3000, // DWORD dwHorizSaturation

5000, // DWORD dwVertSaturation

IMM_STIFF_INNERANYWALL, // DWORD dwStiffnessMask,

0x0, // DWORD dwClippingMask,

enclosureCenter, // POINT pntCenter,

NULL // CImmEffect* pInsideEffect

);

if (!bRes)

{

delete m_pEnclosureSnap;

m_pEnclosureSnap = NULL;

}

} // end of if (m_pTSMouse)

IMPORTANT: This example is for an application that only uses a pointing device and therefore uses a CImmMouse object. Remember that Enclosure effects (along with Ellipse effects) will only work on a CImmMouse device in absolute mode and would not work on a CImmDXDevice or on a CImmMouse in relative mode. Also, the Spring effect created here uses the default value of FALSE for the bUseDeviceCoordinates argument in Initialize, which makes it a screen-based spring instead of a device-based spring.

IMPORTANT: Note that the code performs the NULL CImmMouse check described in Step 2. This NULL check allow the application to skip unnecessary effect initialization calls if a device does not exist and also prevents possible problems from trying to access a non-existent device object. Furthermore, just like in the device object initialization in Step 2, if the Initialize call fails during effect object initialization, the object is deleted and set to NULL. This makes it easy to prevent accidental attempts to access a non-existent effect, which can cause your application to crash. Simply perform a NULL check prior to any attempts to access the effect, which includes modifying, starting, and deleting effects. If you wish to determine the cause of any failed IFC call, use the IFC_GET_LAST_ERROR macro, which returns the HRESULT of the operation.

This example uses an Enclosure effect, which can create a box with either repulsive or attractive walls. By adjusting the parameters, you can make the box bigger or smaller, stronger or weaker, with thick walls or thin walls, or partly open (i.e., missing one of more walls). Furthermore, you can turn off the walls altogether and use the Enclosure merely as a bounding box for another effect. For example, we could have created the Enclosure effect slightly differently like below.

bRes = m_pEnclosureSnap->Initialize(

m_pTSMouse, // CImmDevice* pDevice,

50, // DWORD dwWidth

50, // DWORD dwHeight

0, // LONG lHorizStiffness

0, // LONG lVertStiffness

1, // DWORD dwHorizWallWidth

1, // DWORD dwVertWallWidth

0, // DWORD dwHorizSaturation

0, // DWORD dwVertSaturation

IMM_STIFF_INNERANYWALL, // DWORD dwStiffnessMask,

0x0, // DWORD dwClippingMask,

enclosureCenter, // POINT pntCenter,

m_pPop // CImmEffect* pInsideEffect

);

In this case, the stiffnesses have been set to zero and the wall widths set to 1 pixel. The pInsideEffect has been set to m_pPop, which is the Square wave effect we created. Now when the Enclosure effect is started, you won’t feel any of the walls, but if the cursor enters the rectangular region delineated by the Enclosure, the mouse will experience the Pop effect. In this manner, you can easily create regions on the screen where effects automatically turn on and automatically turn off when the cursor leaves the region. Vibrations (using Periodics), Damping, Friction, and Texture are all examples of effects that work really well inside Enclosure. The same can be done with Ellipses.


Effects from Immersion Studio

IFC Reference

Method 2:
Immersion Studio provides the effect parameters

The example shown above requires you to provide the parameters for each effect in Initialize. If you were clever and savvy enough to have used Immersion Studio to create your effects (hint, hint), the actual code to create the effects becomes even more simplified and allows you to modify effects without recompiling. There are three methods to create effects from Immersion Studio files.

Method 2a – CImmEffect::InitializeFromProject

Method 2b – CImmProject::CreateEffect

Method 2c – CImmProject::Start

Summary of Methods


Using InitializeFromProject

IFC Reference

Method 2a:

If the Pop effect were created and saved as “Pop” in an Immersion Studio resource file named ifc.ifr, here’s one way you could go about loading it into your application using CImmEffect::InitializeFromProject.

// Open Immersion Studio resource file
CImmProject myProject;

if (myProject.OpenFile("ifc.ifr", m_pTSMouse))
{
// Square Wave Vibration from Immersion Studio resource file
m_pPop = new CImmPeriodic();
bRes = m_pPop->InitializeFromProject(myProject, "Pop");
if (!bRes)
{
delete m_pPop;
m_pPop = NULL;
}
}

IMPORTANT: Note that to use effects created in Immersion Studio, you must create a CImmProject object that will manage accessing the .ifr file and creating the effects in the .ifr file.

If you created Compound effects in Immersion Studio (effects made up of two or more individual effects), you can load them in two ways. The first is to manually create each of the component effects separately by name. This method works just fine, but to play the Compound effect, you will have to call Start on each of the component effects. You also have to know the type of the effect beforehand so that you can instantiate the correct type of derived effect object prior to loading it (in the example above, m_pPop is declared as a CImmPeriodic). This means you can change the effect parameters in Immersion Studio, but you can’t change the effect type and still successfully load the effect. However, this method also means you have the effect pointer readily available to change the effect parameters later on.


Using CreateEffect

IFC Reference

Method 2b:

IFC also provides a second method of loading Compound effects that uses a CImmCompoundEffect object to consider all the component effects as a single entity just as Immersion Studio did. If the Pop effect were a compound effect created and saved as “CompoundPop” in an Immersion Studio resource file named ifc.ifr, here’s how you would go about loading it into your application.

// Open Immersion resource file
CImmProject myProject;
CImmCompoundEffect* m_pCompoundPop = NULL;

if (myProject.OpenFile("ifc.ifr", m_pTSMouse))
{
// Compound Pop from Immersion Studio resource file
m_pCompoundPop = myProject.CreateEffect("CompoundPop", m_pTSMouse);
if (!m_pCompoundPop)
{
delete m_pCompoundPop;
m_pCompoundPop = NULL;
}
}

You can use this method even if “CompoundPop” isn’t really a compound effect. The CImmCompoundEffect merely will contain only one effect. The nice thing about CImmProject::CreateEffect is that you don’t have to know the effect type prior to loading it like you do in the method above. This means you can change both effect parameters and effect type in Immersion Studio and still successfully load the compound effect. You can even add or remove component effects from the compound effect.

The disadvantage of using this method is that if you want to change the parameters of the effects in the CImmCompoundEffect, you will need to use CImmCompoundEffect::GetNumberOfContainedEffects and CImmCompoundEffect::GetContainedEffect to access the individual effect objects. CImmCompoundEffect::GetContainedEffect returns an object that may be of any class derived from CImmEffect. If you want to change the base effect parameters like duration, direction, or gain, you can then use CImmEffect::ChangeBaseParams. For example, to change the direction of all the component effects of “CompoundPop” to 45 degrees, you would do the following:

for (int i = 0; i < m_pCompoundPop->GetNumberOfContainedEffects; i++)
{
if (m_pCompoundPop->GetContainedEffect(i))
m_pCompoundPop->GetContainedEffect(i)->ChangeBaseParamsPolar(4500);
// or alternatively call ChangeDirection(4500)
}

However, if you want to change type-specific parameters like magnitude, period, or stiffness, you will need to first call CImmEffect::GetGUID to determine its real type and then cast the object to the appropriate class to call the derived effect’s methods (e.g., CImmSpring::ChangeCenter).


Using Start

IFC Reference

Method 2c:

Finally, if all you wanted to do is to load in an effect from an .ifr file and have it play immediately, you can use a simplest form: CImmProject::Start. This method also works for Compound effects .

// Open Immersion Studio resource file
CImmProject myProject;

if (myProject.OpenFile("ifc.ifr", m_pTSMouse))
{
// Play square Wave Vibration from Immersion Studio resource file
myProject.Start("Pop");
}

IMPORTANT: The benefits of using this simpler form are that you do not need to create an effect object and can start playing the effect immediately. However, since you do not have an effect object, you will not be able to modify the effects later on. You will only be able to play the effect exactly as-is from the .ifr file.


Method Summary

 | Advantages ... | But ...
CImmEffect:: InitializeFromProject Method 2a | CImmEffect-derived class object readily available for changing both base and type-specific parameters. Can change effect parameters in Immersion Studio IFR file at any time | Must load and start each component of compound effects separately Must know effect type prior to loading Can’t change effect type in Immersion Studio IFR file at any time
CImmProject::CreateEffect Method 2b | Can load single or compound effects Does not require prior knowledge of effect type Can change both effect parameters and types in Immersion Studio IFR file at any time | Changing effect base parameters requires one extra step Changing effect type-specific parameters requires several extra steps
CImmProject::Start Method 2c | Can load single or compound effects Does not require prior knowledge of effect type Can change both effect parameters and types in Immersion Studio IFR file at any time | Can not change effect base or type specific parameters from within app

All forms are demonstrated in the HelloIFC and IFCDonuts sample applications included in the IFC SDK.


Play and Modify the Effects

IFC Reference

Step 4:
Play and Modify the Effects

When you want an effect to start, just call Start. If you want to stop the effect before its duration has expired, just call Stop. This example code gets the current cursor position and modifies the Spring created in Step 3 so that the mouse will be sucked to that position like falling into a gravity well.

BOOL bRes;

GetCursorPos(&m_ptCenterCoord);

// if Spring effects exists (!= NULL), set spring center and start

if (m_pSpringStretch)

{

bRes = m_pSpringStretch->ChangeCenter( m_ptCenterCoord );

if (!bRes)

OutputDebugString("CImmSpring::ChangeCenter failed\n");

bRes = m_pSpringStretch->Start();

if (!bRes)

OutputDebugString("CImmSpring::Start failed\n");

}

To modify effects, you will almost always be using methods named ChangeParameters or something similar. These methods are overloaded with multiple forms that let you change anything about an effect from its type-specific parameters (e.g., coefficient, frequency, magnitude, offset) to its general parameters (direction, duration, gain, envelope). All forms let you easily change as few as one parameter at a time to all the parameters. Refer to the documentation, and choose the form that best suits your needs. The code immediately above changes the Spring with ChangeCenter, which is merely a simplified form of ChangeConditionParams.

The gravity well effect in this example was created using a 2-axis XY Spring. An Enclosure could also have been used to create the same effect with one key difference. The gravity well effect of a Spring exists everywhere so that no matter where on the screen the mouse is, there will always be a force pulling the mouse towards the well center. A directional 1-axis spring can also be used to create a snap to a line at an arbitrary angle. The Enclosure from Step 3 was created with dimensions of 50 pixels by 50 pixels. Therefore, the gravity well effect would only be felt by the mouse in a 50 by 50 pixel window centered around the well location. In your application, use the effect type that best matches the feels you are trying to create.


Cleanup the Device and Effects

IFC Reference

Step 5:
Cleanup the Device and Effects

Finally, don’t forget to clean up the device and effects when your application is closing.

if (m_pSpringStretch)

delete m_pSpringStretch;

if (m_pEnclosureSnap)

delete m_pEnclosureSnap;

if (m_pPop)

delete m_pPop;

if (m_pTSMouse)

delete m_pTSMouse;

IMPORTANT: Make sure you delete the effect objects before deleting the device object. Since the effect objects are associated with the device object, deleting the device object first can cause problems when trying to delete the effect objects afterwards.


IFC Tutorial WriteToFile

IFC Reference

Writing Out Effect Information To a File

In cases where effect information needs to be stored in a file, use CImmProject::WriteToFile(). The following is a code example of how to write to an FFE file. The FFE format was introduced in DirectX 7. Having a previous version of DirectX installed in the system will cause CImmProject::WriteToFile() to fail.

CImmDevice* pDevice = NULL;

CImmProject MyProject;

pDevice = CImmDevice::CreateDevice(hInstance, ghWnd);

if(!pDevice)

return 0;

//The extension is used to determine if the file

//to be opened will be read as an IFR or FFE file.

if(!MyProject.OpenFile("Effects.ffe", pDevice))

return 0;

//Effects.ffe may contain more than one effect.

//Since "Buzz" is the only effect created and played,

//"Buzz" will be the only effect written to BuzzOut.ffe.

MyProject.Start("Buzz");

MyProject.WriteToFile("BuzzOut.ffe");

MyProject.Close();

if(pDevice)

{

delete pDevice;

pDevice = NULL;

}


IFC Code Example

IFC Reference

Immersion Foundation Classes Code Example
Putting It All Together in an MFC App

To conclude this tutorial, we’ve taken the code from the five steps above and put it in the context of an MFC application. In the application header file, include the IFC definitions.

#include "IFC.h"

Add the device and effect object pointer members to the application class and initialize them to NULL in the constructor.

class CIFCApp : public CWinApp

{

public:

CIFCApp();

~CIFCApp();

//Attributes

CImmMouse* m_pTSMouse;

CImmSpring* m_pSpringStretch;

CImmEnclosure* m_pEnclosureSnap;

CImmPeriodic* m_pPop;

CImmProject m_ImmProject;

// rest of class definition

}

CIFCApp:: CIFCApp ()

{

m_pTSMouse = NULL;

m_pSpringStretch = NULL;

m_pEnclosureSnap = NULL;

m_pPop = NULL;

// rest of constructor code

}

Create the effects in the InitInstance member function.

BOOL CIFCApp::InitInstance()

{

// rest of InitInstance()

// check for valid CImmMouse object

if (m_pTSMouse)

{

BOOL bRes;

// Create Spring effect

m_pSpringStretch = new CImmSpring;

bRes = m_pSpringStretch->Initialize(

m_pTSMouse, // CImmDevice* pDevice

10000, // LONG Coefficient

10000 // DWORD Saturation

);

if (!bRes)

{

delete m_pSpringStretch;

m_pSpringStretch = NULL;

}

if (m_ImmProject.OpenFile("ifcapp.ifr", m_pTSMouse))

{

// Square Wave Vibration from Immersion Studio resource file

m_pPop = new CImmPeriodic( GUID_Imm_Square );

bRes = m_pPop->InitializeFromProject(m_ImmProject, "Pop");

if (!bRes)

{

delete m_pPop;

m_pPop = NULL;

}

}

// Create Snap effect

m_pEnclosureSnap = new CImmEnclosure;

// Initially start Snap at screen coords 200,200

POINT enclosureCenter;

enclosureCenter.x = enclosureCenter.y = 200;

bRes = m_pEnclosureSnap->Initialize(

m_pTSMouse, // CImmDevice* pDevice,

50, // DWORD dwWidth

50, // DWORD dwHeight

3000, // LONG lHorizStiffness

5000, // LONG lVertStiffness

20, // DWORD dwHorizWallWidth

20, // DWORD dwVertWallWidth

3000, // DWORD dwHorizSaturation

5000, // DWORD dwVertSaturation

IMM_STIFF_INNERANYWALL, // DWORD dwStiffnessMask,

0x0, // DWORD dwClippingMask,

enclosureCenter, // POINT pntCenter,

NULL // CImmEffect* pInsideEffect

);

if (!bRes)

{

delete m_pEnclosureSnap;

m_pEnclosureSnap = NULL;

}

} // end of if (m_pTSMouse)

} // end of InitInstance()

In this example, the Spring starts when the middle button is pressed in OnMButtonDown.

void CIFCView::OnMButtonDown(UINT nFlags, CPoint point)

{

BOOL bRes;

DWORD dwErrorCode;

bRes = GetCursorPos(&m_ptCenterCoord);

if (!bRes) {

TRACE0("GetCursorPos failed\n");

dwErrorCode = GetLastError();

}

// if Spring effects exists (!= NULL), set spring center and start

if (GetApp()->m_pSpringStretch)

{

bRes = GetApp()->m_pSpringStretch->ChangeCenter( m_ptCenterCoord );

if (!bRes)

OutputDebugString("CImmSpring::ChangeCenter failed\n");

bRes = GetApp()->m_pSpringStretch->Start();

if (!bRes)

OutputDebugString("CImmSpring::Start failed\n");

}

CRichEditView::OnMButtonDown(nFlags, point);

}

Finally, clean up the device and effects in ExitInstance.

int CIFCApp::ExitInstance()

{

if (m_pSpringStretch)

delete m_pSpringStretch;

if (m_pEnclosureSnap)

delete m_pEnclosureSnap;

if (m_pPop)

delete m_pPop;

if (m_pTSMouse)

delete m_pTSMouse;

// rest of ExitInstance()

}

That’s all there is to it. For a complete example of using the Immersion Foundation Classes in an MFC application, refer to the example applications in the Samples directory of the IFC SDK.


Benefits of IFC vs DirectX

IFC Reference

How does this IFC code compare to using DirectX?

Remember that IFC is just a set of helper tools and libraries that actually makes native DirectX and Immersion TouchSense API calls. However, by wrapping these complicated COM interfaces into intuitive, easy-to-use classes and tools, IFC makes TouchSense programming easier and more intuitive, shortens development times, and makes code cleaner and more portable without sacrificing any of the functionality and flexibility of the underlying COM-based APIs.

To illustrate this point, look at the code used in this tutorial to create three effects. There are roughly two pages of program code, with the majority of it being comments and error-checking. The DirectX SDK sample program FFDonuts also creates three effects, but using straight DirectInput API calls. While our IFC sample uses roughly two pages of code, FFDonuts uses SEVENTEEN (no, that’s not a misprint) pages of code to perform essentially the exact same tasks! Furthermore, if you use Immersion Studio to create your effects, IFC becomes even simpler to use. FFDonuts has been ported to IFC using Immersion Studio to illustrate this point and is included in the IFC SDK samples with source code. The new application is called IFCDonuts.


Immersion Foundation Classes Reference

This chapter provides a detailed description of each Immersion Class.

The Immersion Foundation Classes appear in alphabetical order. Each class description includes a brief overview of the class, followed by a detailed description of each member function. The member functions of each class appear in alphabetical order.

The individual hierarchy charts of each class description are useful in locating base classes of a particular Immersion Foundation Class. In the case of CImmDevice and CImmEffect, the child classes are shown instead of the base classes. In all cases, the documented class appears in the diagram in bold face.

This reference usually does not describe inherited member functions. For information on these functions, refer to the base classes depicted in the hierarchy diagrams.

Only Public member functions are documented.


CImmBox

The CImmBox class is derived from the CImmEnclosure class and is used for creating effects of type IMM_EFFECTTYPE_ENCLOSURE. Currently only Immersion pointing devices support this type of effect. Also not available when an Immersion device is in relative positioning mode. CImmBox is a specific type of CImmEnclosure that always has all four inner and all four outer walls active, wall saturation 10000, and clipping off. Enclosure coordinates, wall stiffness, wall width, and an inside effect can be specified and modified by the member functions.

The following table summarizes the CImmBox class members:

Construction
CImmBox | Constructs a CImmBox object.
Initialization
Initialize | Creates an Enclosure effect on the device and attaches it to the CImmBox object. Allows box coordinates to be specified as either a rect or as a center point and height and width.
Attributes
ChangeParameters | Changes the parameters of the CImmBox object and updates the effect on the device. Allows box coordinates to be specified as either a rect or as a center point and height and width.

Class Hierarchy:

CImmEffect

CImmEnclosure

CImmBox


CImmBox::CImmBox

Constructs a CImmBox object.

CImmBox();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and the effect downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmBox::ChangeParameters

Call this member to change any of the enclosure effect’s parameters.

BOOL ChangeParameters(
LPCRECT prectBoundary,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwWallThickness = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE
);

BOOL ChangeParameters(
POINT pntCenter,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwHeight = IMM_EFFECT_DONT_CHANGE,
DWORD dwWallThickness = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE
);

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the box in screen coordinates. This cannot be set to NULL. If you do not wish to specify the rectangle, use the other form of ChangeParameters with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the box in screen coordinates. To leave the center point unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT. To use the mouse position at the time the effect is started as the center point, use the value IMM_EFFECT_MOUSE_POS_AT_START.
dwWidth
Specifies the width of the box in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwHeight
Specifies the height of the box in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lStiffness
Stiffness of the box walls. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the box walls. Must be between -10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwWallThickness
Specifies the wall width or thickness of the edges of the box in pixels. Each edge has an inside and outside wall, so the thickness of all inside walls would be changed to dwWallThickness and all outside walls to dwWallThinkness. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the box. If no effect is to be played inside the enclosure, then the member should be set to NULL. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use this member function to set parameters of a box other than the box position. To change box position only, use the ChangeCenter or ChangeRect inherited member functions. To change base effect parameters (e.g., duration, trigger), use the base class member function CImmEffect::ChangeBaseParams(). The following example shows how you would change the duration of a CImmBox object:

m_pBox->ChangeBaseParams(
IMM_EFFECT_DONT_CHANGE, // DirectionX
IMM_EFFECT_DONT_CHANGE, // DirectionY
5 * IMM_SECONDS // Duration
);

ChangeParameters has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::ChangeBaseParams()


CImmBox::Initialize

Call this member to create an enclosure effect on the device and attach it to the CImmBox object.

BOOL Initialize (
CImmDevice* pDevice,
LPCRECT prectBoundary,
LONG lStiffness = IMM_BOX_DEFAULT_STIFFNESS,
DWORD dwWallThickness = IMM_BOX_DEFAULT_WALL_WIDTH,
CImmEffect* pInsideEffect = NULL,
DWORD dwNoDownload = 0
);

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwWidth = IMM_ENCLOSURE_DEFAULT_WIDTH,
DWORD dwHeight = IMM_ENCLOSURE_DEFAULT_HEIGHT,
LONG lStiffness = IMM_BOX_DEFAULT_STIFFNESS,
DWORD dwWallThickness = IMM_BOX_DEFAULT_WALL_WIDTH,
POINT pntCenter = IMM_BOX_DEFAULT_CENTER_POINT,
CImmEffect* pInsideEffect = NULL,
DWORD dwNoDownload = 0
);

Parameters

pDevice

Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.

prectBoundary
A pointer to a LPCRECT structure specifying the box in screen coordinates. This cannot be set to NULL. If you do not wish to specify the rectangle, use the other form of ChangeParameters with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the box in screen coordinates. To use the default center point, use the value IMM_ENCLOSURE_DEFAULT_CENTER_POINT.
dwWidth
Specifies the width of the box in screen coordinates. To use the default width, use the value IMM_ENCLOSURE_DEFAULT_WIDTH.
dwHeight
Specifies the height of the box in screen coordinates. To use the default height, use the value IMM_ENCLOSURE_DEFAULT_HEIGHT.
lStiffness
Stiffness of the Box walls. Defines the amount of vertical force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the mouse is in any of the box walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To use the default stiffness, use the value IMM_BOX_DEFAULT_STIFFNESS.
dwWallThickness
Specifies the wall width or thickness of the edges of the box in pixels. Each edge has an inside and outside wall, so the thickness of all inside walls would be changed to dwWallThickness and all outside walls to dwWallThinkness. To use the default thickness, use the value IMM_BOX_DEFAULT_WALL_WIDTH.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the box. If no effect is to be played inside the enclosure, then the member should be set to NULL.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Initialize has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmCompoundEffect

CImmCompoundEffect represents a compound effect containing one or more sub-effects or sound objects. You can perform operations such as Start on all the contained effects at once by calling methods of CImmCompoundEffect. Or you can use CImmCompoundEffect::GetNumberOfContainedEffects and CImmCompoundEffect::GetContainedEffect to access individual effect objects yourself. CImmCompoundEffects are created, used, and returned by CImmProject; you should not attempt to create them yourself. Sound objects contain useful path information to related wave files, but calling Start on a CImmCompoundEffect will not play any wave files. Only the effects will be played.

The following table summarizes the CImmCompoundEffect class members:

Attributes
GetContainedEffect | Returns an effect contained in the compound effect.
GetEffectType | Returns an identifier for the effect type.
GetTypeName | Returns the name of the effect type assigned by Immersion Studio.
GetName | Returns the compound effect’s name.
GetNumberOfContainedEffects | Returns the number of effects contained in the compound effect.
GetContainedSound | Returns the name of the contained Sound.
GetNumberOfContainedSounds | Returns number of Sound data objects in a CImmCompoundEffect.
Operations
Start | Starts all the effects in the compound effect.
Stop | Stops all the effects in the compound effect.

Class Hierarchy:

CImmCompoundEffect


CImmCompoundEffect::GetContainedEffect

Returns an effect contained in the compound effect.

GENERIC_EFFECT_PTR GetContainedEffect(long index);

GENERIC_EFFECT_PTR GetContainedEffect(
LPCSTR lpszEffectName
);

Parameters

index
The index’th effect is returned. The index must be between 0 and GetNumberOfContainedEffects() - 1.
lpszEffectName
Name of contained effect. The effect name is case sensitive.

Return Values

If the function succeeds, the return value is a valid CImmEffect pointer. Otherwise, NULL is returned.

CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The object that is returned may be of any class descended from CImmEffect. To call derived class methods on this object, first call CImmEffect::GetGUID or CImmEffect::GetEffectType to determine its real type, then cast the object to the appropriate class.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()

GetName()

GetNumberOfContainedEffects()


CImmCompoundEffect::GetContainedSound

Returns the name of a sound in the compound effect.

LPCSTR GetContainedSound(long index);

Parameters

index
The index’th sound name is returned. The index must be between 0 and GetNumberOfContainedSounds() - 1.

Return Values

If the function succeeds, the return value is a pointer to a NULL terminated character array. Otherwise, NULL is returned.

CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The name of the sound object can be used in CImmProject::GetSoundPath to retrieve the path information for the sound's .wav file.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetNumberOfContainedSounds()

CImmProject::GetSoundPath()


CImmCompoundEffect::GetEffectType

A Compound can contain one or more effects. GetEffectType() can be used to determine if the CImmCompoundEffect object contains one or multiple effect primitives.

DWORD GetEffectType();

Parameters

None.

Return Values

In the case that the object contains multiple primitives, IMM_EFFECTTYPE_COMPOUND will be returned. If only one primitive is contained in a compound, that primitive’s effect type will be returned. If the compound effect is empty, zero is returned and IFC_ERR_NO_EFFECTS_FOUND will be returned by GetLastErrorCode().

The following effect types can be returned by GetEffectType().

IMM_EFFECTTYPE_COMPOUND
IMM_EFFECTTYPE_CONDITION
IMM_EFFECTTYPE_CONSTANTFORCE
IMM_EFFECTTYPE_ELLIPSE
IMM_EFFECTTYPE_ENCLOSURE
IMM_EFFECTTYPE_PERIODIC
IMM_EFFECTTYPE_RAMPFORCE
IMM_EFFECTTYPE_TEXTURE
IMM_EFFECTTYPE_CUSTOMFORCE

Remarks

While this function will not provide information for differentiating sub-categories of effects such as a Spring vs a Damper, it will give enough information to determine how a CImmEffect pointer should be cast.

GetTypeName can be used to obtain more detail information on the effect sub-category.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetContainedEffect()

GetName()

GetTypeName()

GetNumberOfContainedEffects()


CImmCompoundEffect::GetName

Returns the CImmCompoundEffect's name.

const char* GetName() const;

Parameters

None.

Return Values

If the function succeeds, a pointer to a character array is returned.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

CImmCompoundEffect objects can either be an effect primitive or a true compound effect. GetName returns the name of the underlying effect. To determine if the CImmCompoundEffect is a primitive or true compound effect call GetEffectType.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetContainedEffect()

GetEffectType()

GetNumberOfContainedEffects()

CImmProject::AddEffect()


CImmCompoundEffect::GetNumberOfContainedEffects

Use to find the number effects that comprise this Compound effect.

long GetNumberOfContainedEffects() const;

Parameters

None.

Return Values

Returns the number of effects contained in the compound effect.

Remarks

Each compound effect consists of one or more contained effects. This method gets the number of effects. The returned value may be used to iterate through the list of contained effects. By using GetContainedEffect, access to each effect primitive is possible.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetContainedEffect()

GetEffectType()

GetName()


CImmCompoundEffect::GetNumberOfContainedSounds

Returns the number sounds in the Compound effect.

long GetNumberOfContainedSounds() const;

Parameters

None.

Return Values

The total number of sounds contained in the compound effect.

Remarks

Each compound effect can contain one or more sound objects. The number returned can be used with GetContainedSound to iterate through all contained sounds and obtain the name of each sound object. A sound object contains path information to the .wav file associated with the compound effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetContainedSound()


CImmCompoundEffect::GetTypeName

Returns a string for the effect type.

LPCSTR GetTypeName();

Parameters

None.

Return Values

If the function succeeds, a pointer to a character array is returned.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

IFR files contain information about the name of the effect type. The valid strings are generated by Immersion Studio. While GetEffectType provides enough information to differentiate between CImmEffect class types, GetTypeName can be useful when a more descriptive type name is required.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()


CImmCompoundEffect::Start

Starts all the effects in the compound effect. Returns TRUE if successful.

BOOL Start(
DWORD dwIterations = IMM_EFFECT_DONT_CHANGE,
DWORD dwFlags = 0,
);

Parameters

dwIterations

Number of times to play the effect in sequence. The envelope is re-articulated with each iteration. To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE. If the effect was loaded in through an IFR file, the number of iterations set in the IFR file will be used as the default.

dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:
IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Start() iterates through the list of effects contained in the Compound and sends a start command to the device. If any of the contained effects fail to start, iteration is haulted, and the function fails. Any perviously started effects in the Compound will continue to play.

A value other than IMM_EFFECT_DONT_CHANGE will override the iterations setting only during the current call to Start() but will not permanently change the iterations value.

Although CImmCompoundEffects can contain sound objects, these sound objects only contain useful path information to related wave files. Calling Start on a CImmCompoundEffect will not play any wave files. Only the effects will be played.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmCompoundEffect::Stop

Stops all the effects in the compound effect.

BOOL Stop();

Parameters

None.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If one of the contained effects fails the stop command sent to the device, iteration through the rest of the effects will hault and FALSE will be returned. Note that calling stop on a currently stopped effect is not an error.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Stop()


CImmCondition

The CImmCondition class is the base class used for creating effects of type IMM_EFFECTTYPE_CONDITION. These include:

  • Springs
  • Dampers
  • Friction
  • Inertia
  • Grids

The GUID identifying the specific effect is specified as a parameter to the constructor. There is also a specialized class, derived from CImmCondition, for each of the above effects. Therefore, a particular condition can be created by either using the base CImmCondition class, or by using the appropriate child class (CImmSpring, CImmDamper, CImmFriction, CImmInertia, or CImmGrid).

In general, you will want to create the effect using the specialized child class, and use the more general CImmCondition base class members as needed.

The following table summarizes the CImmCondition class members:

Construction
CImmCondition | Creates a Condition effect on the device and attaches it to the CImmCondition object. Direction is specified as a Cartesian XY vector.
Initialization
InitCondition | Creates a Condition effect on the device and attaches it to the CImmCondition object. Direction is specified as a Cartesian XY vector.
InitConditionPolar | Same as InitCondition, but allows direction to be specified in polar coordinates.
Attributes
ChangeConditionParams | Changes the parameters of a condition and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeConditionParamsPolar | Same as ChangeConditionParams, but allows direction to be specified in polar coordinates.
ChangeCenter | Changes the center point of a 2-axis condition, and updates the effect on the device. (screen coordinates)
Get Parameter Functions | Functions used for retrieving type specific parameters.
Operations
Start | Causes the effect to play on the device.

Class Hierarchy:

CImmEffect

CImmCondition


CImmCondition::CImmCondition

Constructs a CImmCondition object.

CImmCondition( const GUID& rguidEffect );

Parameters

rguidEffect

Identifier of the condition effect to create (damper, friction, grid, inertia, and spring).

GUID_Imm_Damper

GUID_Imm_Friction

GUID_Imm_Grid

GUID_Imm_Inertia

GUID_Imm_Spring

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and the effect downloaded to the device in the InitCondition member function.

A particular condition can be created by either using the base CImmCondition class, or by using the appropriate child class (CImmSpring, CImmDamper, CImmFriction, CImmInertia, or CImmGrid). In general, it is recommended to create the effect using the specialized child class. Use the more general CImmCondition base class members as needed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Effect GUIDs

InitCondition()


CImmCondition::ChangeConditionParams

Call this member to change the parameters of a condition effect after you have initialized it.

/* This function may be used with single-axis and dual-axis effects*/
BOOL ChangeConditionParams(
LPCIMM_CONDITION pConditionX,
LPCIMM_CONDITION pConditionY
);

/* This function may be used for directional effects*/
BOOL ChangeConditionParams(
LPCIMM_CONDITION pCondition,
LONG lDirectionX,
LONG lDirectionY
);

/* This function may be used for single-axis, dual-axis symetrical, or directional effects*/
BOOL ChangeConditionParams(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient = IMM_EFFECT_DONT_CHANGE,
DWORD dwPositiveSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegativeSaturation = IMM_EFFECT_DONT_CHANGE,
LONG lDeadBand = IMM_EFFECT_DONT_CHANGE,
POINT pntCenter = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM _EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM _EFFECT_DONT_CHANGE
);

Parameters

pConditionX
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with the X-axis. If NULL, the condition is assumed to be a 1-axis condition on the Y-axis, and pConditionY must not be NULL.
pConditionY
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with the Y-axis. If NULL, the condition is assumed to be a 1-axis condition on the X-axis, and pConditionX must not be NULL.
pCondition
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with a directional condition.
lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by dwfAxis parameter passed in through the InitCondition member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional condition, specifies the y-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by dwfAxis parameter passed in through the InitCondition member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lPositiveCoefficient
Force coefficient on the positive side of the center, in the range –10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the dead band for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center-point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When using the first two forms of this member function, you can use the value IMM_EFFECT_DONT_CHANGE for individual members of any of the IMM_CONDITION structures (pConditionX, pConditionY, or pCondition). For example, to change only the positive coefficient along the Y-axis of a 2-axis condition effect, you could do the following:

IMM_CONDITION conditionX;
conditionX.lCenter = IMM_EFFECT_DONT_CHANGE;
conditionX.lPositiveCoefficient = IMM_EFFECT_DONT_CHANGE;
conditionX.lNegativeCoefficient = IMM_EFFECT_DONT_CHANGE;
conditionX.dwPositiveSaturation = IMM_EFFECT_DONT_CHANGE;
conditionX.dwNegativeSaturation = IMM_EFFECT_DONT_CHANGE;
conditionX.lDeadband = IMM_EFFECT_DONT_CHANGE;

IMM_CONDITION conditionY = conditionX;
conditionY.lPositiveCoefficient = 6000;

m_pSpringCond->ChangeConditionParams( &conditionX, & conditionY );

Be sure to use a form of this member that is consistent with the form that was used to initialize the effect. For example, if you initialize the effect with the following (1- or 2-axis) form:

BOOL InitCondition(
CImmDevice* pDevice,
LPCIMM_CONDITION pConditionX,
LPCIMM_CONDITION pConditionY
);

then it would be an error to change parameters using the following (directional) form:

BOOL ChangeConditionParams(
LPCIMM_CONDITION pCondition,
LONG lDirectionX,
LONG lDirectionY
);

For more information about when to use each form, see the InitCondition member.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParamsX,Y

ChangeConditionParamsPolar()

ChangeConditionParamsPolarX,Y

InitCondition()


CImmCondition::ChangeConditionParamsX,Y

Call these functions to change the parameters of a condition effect after you have initialized it. The parameters passed in by these functions affect the condition associated with either the X-Axis or Y-Axis only.

BOOL ChangeConditionParamsX(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient = IMM_EFFECT_DONT_CHANGE,
DWORD dwPositiveSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegativeSaturation = IMM_EFFECT_DONT_CHANGE,
LONG lDeadBand = IMM_EFFECT_DONT_CHANGE,
POINT pntCenter = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

BOOL ChangeConditionParamsY(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient = IMM_EFFECT_DONT_CHANGE,
DWORD dwPositiveSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegativeSaturation = IMM_EFFECT_DONT_CHANGE,
LONG lDeadBand = IMM_EFFECT_DONT_CHANGE,
POINT pntCenter = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lPositiveCoefficient
Force coefficient on the positive side of the center, in the range –10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the dead band for both axes. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center-point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT.
lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by dwfAxis parameter passed in through the InitCondition member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional condition, specifies the y-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by dwfAxis parameter passed in through the InitCondition member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When the desired change is to affect both axes, the general ChangeConditionParameters function should be used. Change functions for each parameter are available for modifying an individual parameter. When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParams()

ChangeConditionParamsPolar()

ChangeConditionParamsPolarX,Y


CImmCondition::ChangeConditionParamsPolar

Call this member to change the parameters of a directional condition effect after you have initialized it.

BOOL ChangeConditionParamsPolar(
LPCIMM_CONDITION pCondition,
LONG lAngle
);

BOOL ChangeConditionParamsPolar(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient,
DWORD dwPositiveSaturation,
DWORD dwNegativeSaturation,
LONG lDeadBand,
POINT pntCenter,
LONG lAngle
);

Parameters

pCondition
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with the condition.
lAngle
Specifies the angle of the radial direction vector. The angle must be given in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lPositiveCoefficient
Force coefficient on the positive side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center-point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

It is only valid to use this member function with directional condition effects. This method is largely the same as ChangeConditionParams, except that it allows you to specify the angle of the direction instead of its X and Y components. See ChangeConditionParams for more information.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParamsPolarX,Y

ChangeConditionParams()

ChangeConditionParamsX,Y


CImmCondition::ChangeConditionParamsPolarX,Y

Call this member to change the parameters of a polar condition effect after you have initialized it. The parameters passed in by these functions affect the condition associated with either the X-Axis or Y-Axis only.

BOOL ChangeConditionParamsPolarX(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient,
DWORD dwPositiveSaturation,
DWORD dwNegativeSaturation,
LONG lDeadBand,
POINT pntCenter,
LONG lAngle
);

BOOL ChangeConditionParamsPolarY(
LONG lPositiveCoefficient,
LONG lNegativeCoefficient,
DWORD dwPositiveSaturation,
DWORD dwNegativeSaturation,
LONG lDeadBand,
POINT pntCenter,
LONG lAngle
);

Parameters

lPositiveCoefficient
Force coefficient on the positive side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range –10000 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center-point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT.
lAngle
Specifies the angle of the radial direction vector. The angle must be given in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When the desired change is to affect both axes, the general ChangeConditionParameters function should be used. Change functions for each parameter are available for modifying an individual parameter. When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase the frequency of communication with the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParams()

ChangeConditionParamsX,Y

ChangeConditionParamsPolar()


CImmCondition Get Parameter Functions

To find out the current value of an effect parameter pass a variable of the appropriate data type to one of the get functions. The value returned in that variable will be the current setting.

BOOL GetPositiveCoefficientX( LONG &lPositiveCoefficient );
BOOL GetNegativeCoefficientX( LONG &lNegativeCoefficient );
BOOL GetPositiveSaturationX( DWORD &dwPositiveSaturation );
BOOL GetNegativeSaturationX( DWORD &dwNegativeSaturation );
BOOL GetDeadBandX( LONG &lDeadBand );

BOOL GetPositiveCoefficientY( LONG &lPositiveCoefficient );
BOOL GetNegativeCoefficientY( LONG &lNegativeCoefficient );
BOOL GetPositiveSaturationY( DWORD &dwPositiveSaturation );
BOOL GetNegativeSaturationY( DWORD &dwNegativeSaturation );
BOOL GetDeadBandY( LONG &lDeadBand );

BOOL GetAxis( DWORD &dwfAxis );
BOOL GetCenter( POINT &pntCenter );

Parameters

lPositiveCoefficient
Force coefficient on the positive side of the center, in the range -10000 to 10000. Exact meaning is effect-specific.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect.

Can be one of the following values:

IMM_EFFECT_AXIS_X
IMM_EFFECT_AXIS_Y
IMM_EFFECT_AXIS_BOTH
IMM_EFFECT_AXIS_DIRECTIONAL
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center-point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The use of these get functions does not increase the frequency of communication with the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParams()


CImmCondition::InitCondition

Call this member to create a condition effect on the device and attach it to the CImmCondition object.

BOOL InitCondition (
CImmDevice* pDevice,
LPCIMM_CONDITION pConditionX,
LPCIMM_CONDITION pConditionY,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

BOOL InitCondition (
CImmDevice* pDevice,
LPCIMM_CONDITION pCondition,
LONG lDirectionX,
LONG lDirectionY,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

BOOL InitCondition (
CImmDevice* pDevice,
LONG lPositiveCoefficient = IMM_CONDITION_DEFAULT_COEFFICIENT,
LONG lNegativeCoefficient = IMM_CONDITION_DEFAULT_COEFFICIENT,
DWORD dwPositiveSaturation = IMM_CONDITION_DEFAULT_SATURATION,
DWORD dwNegativeSaturation = IMM_CONDITION_DEFAULT_SATURATION,
LONG lDeadBand = IMM_CONDITION_DEFAULT_DEADBAND,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
POINT pntCenter = IMM_CONDITION_DEFAULT_CENTER_POINT,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
pConditionX
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with the X-axis. If NULL, the condition is assumed to be a 1-axis condition on the Y-axis, and pConditionY must not be NULL.
pConditionY
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with the Y-axis. If NULL, the condition is assumed to be a 1-axis condition on the X-axis, and pConditionX must not be NULL.
pCondition
Points to a IMM_CONDITION structure that specifies the condition parameters to associate with a directional condition.
lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lDirectionY
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lPositiveCoefficient
Force coefficient on the positive side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the coefficient for both axes.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the saturation for both axes.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific. For a 2-axis condition, this parameter specifies the deadband for both axes.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect. Can be one of the following values:

IMM_EFFECT_AXIS_X

IMM_EFFECT_AXIS_Y

IMM_EFFECT_AXIS_BOTH

IMM_EFFECT_AXIS_DIRECTIONAL

pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor.
bUseDeviceCoordinates
Set this to TRUE when creating a condition on a CImmDXDevice object.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitCondition creates the effect object, but does not cause it to play. After calling InitCondition, call the Start member function to play the effect.

The first form allows you to create 1-axis, 2-axis conditions. The second form allows you to create directional conditions. Together, the two of them provide a general way of creating any type of condition effect supported by the API. However, they do require you to create and set up one or two IMM_CONDITION structures.

The third form is simpler to use, although slightly more limiting than the first two. Specifically, the third form allows you to easily create 1-axis, 2-axis, and directional conditions, with the limitation that the parameters must be the same for each axis of a 2-axis condition. In other words, you can only supply one of each of the following, which apply to both X and Y axes:

  • positive coefficient
  • negative coefficient
  • positive saturation
  • negative saturation
  • dead band
The following table should assist you in determining which form to use:
 | 1-Axis | 2-Axis (X- and Y-axis do not differ) | 2-Axis (X-and Y-axis differ) | Directional
1st Form | X | X | X |
2 nd Form |  |  |  | X
3rd Form | X | X |  | X

Note: Directional conditions cause the effect to act only in that direction and have no effect in the perpendicular direction. For example, a directional grid or spring at 45 degrees means you will feel the grid or spring moving along one diagonal but not along the other diagonal. Directional springs can be used to create snaps to lines at arbitrary angles. See CImmSpring::Initialize for more information about snapping to lines. If using angles to specify your directional condition, a compass heading convention is used so that 0 degrees is due north or up and 90 degrees is due east or right. If using a vector to specify your directional condition, the screen X,Y convention is used so that positive X is towards the right and positive Y is down or towards the user. Therefore, (1,0) is to the right, (0,1) is down, and (1,1) is down and to the right.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitConditionPolar()


CImmCondition::InitConditionPolar

Call this member to create a condition effect on the device and attach it to the CImmCondition object.

BOOL InitConditionPolar(
CImmDevice* pDevice,
LPCIMM_CONDITION pCondition,
LONG lAngle,
BOOL bUseDeviceCoordinates,
DWORD dwNoDownload
);

BOOL InitConditionPolar(
CImmDevice* pDevice,
LONG lPositiveCoefficient = IMM_CONDITION_DEFAULT_COEFFICIENT,
LONG lNegativeCoefficient = IMM_CONDITION_DEFAULT_COEFFICIENT,
DWORD dwPositiveSaturation = IMM_CONDITION_DEFAULT_SATURATION,
DWORD dwNegativeSaturation = IMM_CONDITION_DEFAULT_SATURATION,
LONG lDeadBand = IMM_CONDITION_DEFAULT_DEADBAND,
POINT pntCenter = IMM_CONDITION_DEFAULT_CENTER_POINT,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
pCondition
Points to a IMM_CONDITION structure that specifies the condition parameters.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
lPositiveCoefficient
Force coefficient on the positive side of the center, in the range -10000 to 10000. Exact meaning is effect-specific.
lNegativeCoefficient
Force coefficient on the negative side of the center, in the range -10000 to 10000. Exact meaning is effect-specific.
dwPositiveSaturation
Maximum force output on the positive side of the center, in the range 0 to 10000. Exact meaning is effect-specific.
dwNegativeSaturation
Maximum force output on the negative side of the center, in the range 0 to 10000. Exact meaning is effect-specific.
lDeadBand
The region where the condition is not active, in the range 0 to 10000. Exact meaning is effect-specific.
pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor.

bUseDeviceCoordinates
Set this to TRUE when creating a condition on a CImmDXDevice object.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

It is only valid to use this member function with directional condition effects. This method is largely the same as InitCondition, except that it allows you to specify the angle of the direction instead of its X and Y components. See InitCondition for more information.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitCondition()


CImmCondition::ChangeCenter

Call this member to change the center point of a condition.

BOOL ChangeCenter(
POINT pntCenter
);

Parameters

pntCenter
Depending on the type of condition, pntCenter can have one of the following meanings:

The center point, in screen coordinates, of the effect.

Horizontal and vertical directional offsets to the dead band range.

In the former case, you can use the value IMM_EFFECT_MOUSE_POS_AT_START. Supplying that value will cause the assignment of the center point to be delayed until you call the Start member. At that time, the center point will be set to the current position of the mouse cursor.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should use this member when the only parameter you want to change is the center point. If you want to change other parameters as well as the center point, use the ChangeConditionParams method.

When changing the center of a single-axis condition, only one member of the pntCenter is considered — the one that corresponds to the axis of the condition. For example, to change the center of a Y-axis condition to 200, use the following code:

POINT pntCenter = { 0, 200 };
m_pSpringY->ChangeCenter( pntCenter );

In the example above, the X-component of pntCenter is ignored, and therefore set to 0.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeConditionParams()

ChangeConditionParamsPolar()


CImmCondition::Start

Call this member to start playing the condition effect.

virtual BOOL Start(
DWORD dwIterations = 1,
DWORD dwFlags = 0
);

Parameters

dwIterations
Number of times to play the effect in sequence. The envelope is re-articulated with each iteration. To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE.
dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:
IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function overrides the base method, CEffect::Start(), to allow for the automatic assignment of the center point to the current position of the mouse cursor. See CEffect::Start() for more information.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmCompoundEffect::Start()

CImmEffect::Start()


CImmConstant

The CImmConstant class is used for creating effects of type IMM_EFFECTTYPE_CONSTANTFORCE.

The following table summarizes the CImmConstant class members:

Construction
CImmConstant | Constructs a CImmConstant object.
Initialization
Initialize | Creates an effect on the device and attaches it to the CImmConstant object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of a constant force effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
ChangeMagnitude | Changes the magnitude of the constant force effect.
GetMagnitude | Retrieves the current magnitude value.

Class Hierarchy:

CImmEffect

CImmConstant


CImmConstant::CImmConstant

Constructs a CImmConstant object.

CImmConstant();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmConstant::ChangeParameters

Call this member to change any of the constant force effect’s parameters.

BOOL ChangeParameters(
LONG lDirectionX,
LONG lDirectionY,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lMagnitude = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = IMM_EFFECT_DONT_CHANGE_PTR
);

Parameters

lDirectionX
The X component of the direction vector. A constant force direction vector specifies the force's direction of origination. An (X,Y) vector of (1,0) points east and creates a force that pushes toward the user's left. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
The Y component of the direction vector. Note that the positive Y-axis points down toward the user. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. If no envelope is needed, then this parameter should be set to NULL. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_PTR.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

ChangeParameters provides a way to modify parameters specific to constant forces. To change other parameters common to all effects, use the inherited function ChangeBaseParams. The effect must have been initialized before using this member function otherwise ChangeParameters will fail.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParametersPolar()

ChangeMagnitude()

CImmEffect::ChangeBaseParams()


CImmConstant::ChangeParametersPolar

Call this member to change any of the constant force effect’s parameters.

BOOL ChangeParametersPolar (
LONG lAngle,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lMagnitude = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = IMM_EFFECT_DONT_CHANGE_PTR
);

Parameters

lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. This angle specifies the force's direction of origination. For instance, value of 0 points north and causes a force that pushes toward the user. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. If no envelope is needed, then this parameter should be set to NULL. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE_PTR.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

ChangeParametersPolar provides a way to modify parameters specific to constant forces. To change other parameters common to all effects, use the inherited function ChangeBaseParamsPolar. The effect must have been initialized before using this member function otherwise ChangeParametersPolar will fail.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeMagnitude()

CImmEffect::ChangeBaseParamsPolar()


CImmConstant::ChangeMagnitude

This function changes the magnitude of a Constant force effect.

BOOL ChangeMagnitude(
LONG lMagnitude
);

Parameters

lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Magnitude is the only type specific parameter for a constant force. If a direction change is needed in addition to a magnitude change, use the ChangeParameters() call.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeParametersPolar()

GetMagnitude()

CImmEffect::ChangeBaseParams()


CImmConstant::GetMagnitude

Retrieves the current magnitude value for the Constant force.

BOOL GetMagnitude(
LONG &lMagnitude
);

Parameters

lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function stores the current magnitude value in the variable passed to GetMagnitude().

Magnitude is the only type specific parameter for a constant force. For other base parameters common to all effects, use the get functions available in the base class, CImmEffect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeMagnitude()


CImmConstant::Initialize

Call this member to create a Cartesian constant force effect on the device and attach it to the CImmConstant object.

BOOL Initialize(
CImmDevice* pDevice,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwDuration = IMM_CONSTANT_DEFAULT_DURATION,
LONG lMagnitude = IMM_CONSTANT_DEFAULT_MAGNITUDE,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
lDirectionX
The X component of the direction vector. A constant force direction vector specifies the force's direction of origination. An (X,Y) vector of (1,0) points east and creates a force that pushes toward the user left. To use the default X-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
The Y component of the direction vector. Note that the positive Y-axis points down toward the user. To use the default Y-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_Y.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To use the default duration, use the value IMM_CONSTANT_DEFAULT_DURATION.
lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration. To use the default magnitude, use the value IMM_CONSTANT_DEFAULT_MAGNITUDE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. If no envelope is to be applied, then the member should be set to NULL.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect. Initialize creates a constant force effect that has a direction vector specified in Cartesian coordinates. For a constant force that specifies direction with polar coordinates, use the InitializePolar member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitializePolar()


CImmConstant::InitializePolar

Call this member to create a Polar constant force effect on the device and attach it to the CImmConstant object.

BOOL InitializePolar(
CImmDevice* pDevice,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwDuration = IMM_CONSTANT_DEFAULT_DURATION,
LONG lMagnitude = IMM_CONSTANT_DEFAULT_MAGNITUDE,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. This angle specifies the force's direction of origination. For instance, value of 0 points north and causes a force that pushes toward the user. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To use the default duration, use the value IMM_CONSTANT_DEFAULT_DURATION.
lMagnitude
The magnitude of the effect, in the range -10,000 to 10,000. If an envelope is applied to this effect, then the value represents the magnitude of the sustain. If no envelope is applied, then the value represents the amplitude of the effect throughout the entire duration. To use the default magnitude, use the value IMM_CONSTANT_DEFAULT_MAGNITUDE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. If no envelope is to be applied, then the member should be set to NULL.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitializePolar creates the effect object, but does not cause it to play. After calling InitializePolar, call the Start member function to play the effect. InitializePolar creates a constant force effect that has a direction vector specified in Polar coordinates. For a constant force that specifies direction with Cartesian coordinates, use the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmDamper

The CImmDamper class is used for creating damper effects of type IMM_EFFECTTYPE_CONDITION.

The following table summarizes the CImmDamper class members:

Construction
CImmDamper | Constructs a CImmDamper object.
Initialization
Initialize | Creates a damper effect on the device and attaches it to the CImmDamper object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of a damper effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
ChangeMinVelocity | Changes the minumum velocity of the Damper.
ChangeViscosity | Changes the viscosity of the Damper.
Get Parameter Functions | Functions that retrieve current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmCondition

CImmDamper


CImmDamper::CImmDamper

Constructs a CImmDamper object.

CImmDamper();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmDamper::ChangeParameters

Call this member to change the parameters of a damper effect after you have initialized it.

BOOL ChangeParameters(
DWORD dwViscosity,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwMinVelocity = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwViscosity controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
For a directional damper, specifies the x-component of the direction vector. The direction vector defines the axis on which the dampening force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional damper, specifies the y-component of the direction vector. The direction vector defines the axis on which the dampening force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParameters to modify damper specific parameters. To change parameters common to all effects use the inherited ChangeBaseParams function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParametersPolar()

ChangeMinVelocity()

ChangeViscosity()

CImmEffect::ChangeBaseParams()


CImmDamper::ChangeParametersPolar

Call this member to change the parameters of a damper effect after you have initialized it.

BOOL ChangeParametersPolar (
DWORD dwViscosity,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwMinVelocity = IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwViscosity controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the dampening force is felt. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParametersPolar to modify damper specific parameters. To change parameters common to all effects use the inherited ChangeBaseParamsPolar function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeMinVelocity()

ChangeViscosity()

CImmEffect::ChangeBaseParamsPolar()


CImmDamper::ChangeMinVelocity

Modifies the minimum velocity for a Damper effect.

BOOL ChangeMinVelocity( DWORD dwMinVelocity );
BOOL ChangeMinVelocityX( DWORD dwMinVelocity );
BOOL ChangeMinVelocityY( DWORD dwMinVelocity );

Parameters

dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

While ChangeMinVelocity affects both the axes using the same value passed in, the functions designated with a trailing X or Y will only affect the minimum velocity for the X - Axis or Y - Axis.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeViscosity()


CImmDamper::ChangeViscosity

Modifies the viscosity value of an initialized Damper effect.

BOOL ChangeViscosity(
LONG lViscosity
);

Parameters

lViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters, use the ChangeParameters() call.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeMinVelocity()


CImmDamper Get Parameter Functions

These functions retrieve the current individual parameter values of a Damper effect.

BOOL GetViscosity( LONG &lViscosity );
BOOL GetMinVelocityX( DWORD &dwMinVelocity );
BOOL GetMinVelocityY( DWORD &dwMinVelocity );

Parameters

lViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The effect’s current parameter values are returned through the variables passed in. The use of these Get functions does not increase the frequency of communication with the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()


CImmDamper::Initialize

Call this member to create a damper effect on the device and attach it to the CImmDamper object.

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwViscosity = IMM_DAMPER_DEFAULT_VISCOSITY,
DWORD dwSaturation = IMM_DAMPER_DEFAULT_SATURATION,
DWORD dwMinVelocity = IMM_DAMPER_DEFAULT_MIN_VELOCITY,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default viscosity, use the value IMM_DAMPER_DEFAULT_VISCOSITY.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwViscosity controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_DAMPER_DEFAULT_SATURATION.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minumum velocity, use the value IMM_DAMPER_DEFAULT_MIN_VELOCITY.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect.
Can be one of the following values:

IMM_EFFECT_AXIS_X
IMM_EFFECT_AXIS_Y
IMM_EFFECT_AXIS_BOTH
IMM_EFFECT_AXIS_DIRECTIONAL

The default axis flag is IMM_EFFECT_AXIS_BOTH.
lDirectionX
For a directional damper, specifies the X-component of the direction vector. The direction vector defines the axis on which the dampening force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default X-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
For a directional damper, specifies the Y-component of the direction vector. The direction vector defines the axis on which the dampening force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default Y-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_Y.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitializePolar()


CImmDamper::InitializePolar

Call this member to create a damper effect on the device and attach it to the CImmDamper object.

BOOL InitializePolar (
CImmDevice* pDevice,
DWORD dwViscosity,
DWORD dwSaturation,
DWORD dwMinVelocity,
LONG lAngle,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwViscosity
The rate at which an opposing force increases with respect to velocity. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default viscosity, use the value IMM_DAMPER_DEFAULT_VISCOSITY.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwViscosity controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_DAMPER_DEFAULT_SATURATION.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minumum velocity, use the value IMM_DAMPER_DEFAULT_MIN_VELOCITY.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the dampening force is felt. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitializePolar creates the effect object, but does not cause it to play. After calling InitializePolar, call the Start member function to play the effect. InitializePolar automatically sets dwfAxis to IMM_EFFECT_AXIS_DIRECTIONAL.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmDevice

The CImmDevice class is the abstract base class for all force feedback device classes. Currently, there are only two derived classes. The first is CImmMouse for TouchSense-enabled pointing devices like the Logitech WingMan Force-Feedback Mouse and tactile feedback mouse. The second is CImmDXDevice for all DirectX-compatible force feedback gaming controllers like TouchSense-enabled joysticks and steering wheels. As additional types of force feedback devices become available, new classes will be introduced that derive from CImmDevice.

To create a device object, you can either 1) instantiate one of the derived classes like CImmMouse or CImmDXDevice and call the Initialize member function, or 2) create a CImmDevice pointer directly and use the CreateDevice member function. To add forces to your application, you will need to pass a pointer to the CImmDevice or CImmDevice derived object to the initialization member functions of the IFC effects in your application.

Note: Since CImmDevice is an abstract base class, you should never directly create or allocate a CImmDevice object like you can with one of the derived classes. You can only directly create a CImmDevice object pointer and use this pointer to store the return value of CreateDevice.

The following table summarizes the CImmDevice class members:

Construction
CImmDevice | Constructs a CImmDevice object.
Attributes
GetDevice | Retrieves the IFeelitDevice or IDirectInputDevice2 interface pointer associated with this object.
GetDeviceType | Retrieves the force feedback device type.
GetDriverVersion | Retrieves version information as reported by the driver.
GetIFCVersion | Retrieves version information for IFC.
GetImmAPIVersion | Retrieves version information about the Immersion API.
GetDXVersion | Retrieves version information about Dinput.
GetProductGUID | Returns the manufacturers GUID for this product.
GetProductGUIDString | Returns the GUID in string form.
GetProductName | Retrieves the name for the product.
GetProductType | Returns an identifier for the product type.
Operations
CreateDevice | Enumerates attached Immersion and DirectX devices and initializes the Immersion TouchSense COM or DirectX COM objects for the first one found. Must be called with scope identifier.

Class Hierarchy:

CImmDevice

CImmDXDevice

CImmMouse


CImmDevice::CImmDevice

Constructs a CImmDevice object.

CImmDevice();

Parameters

None.

Return Values

NA

Remarks

This constructor is typically not called directly by the user. Rather, it is called by the constructor of one of the child classes (which inherit from CImmDevice), such as CImmMouse. The constructors do not create the corresponding Immersion or DirectX COM objects. They only initialize a class object and assign the device GUID. The Immersion or DirectX API COM objects are created in the CImmDevice::CreateDevice or derived class Initialize member functions.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmDevice::CreateDevice

Depending on on the type of device attached to the system, this member function creates and initializes the Immersion TouchSense API IFeelit/IFeelitDevice or DirectX API IDirectInput/IDirectInputDevice2 COM objects and associates them with the CImmDevice object.

static CImmDevice*
CreateDevice(
HINSTANCE hinstApp,
HWND hwndApp
);

Parameters

hinstApp
Instance handle to the application or DLL that is creating the COM object.
hwndApp
Window handle to be associated with the device. This parameter must be a valid top-level window handle that belongs to the process. The window associated with the device must not be destroyed while the device is still active.

Return Values

If the function succeeds, the returned value points to a CImmMouse or CImmDXDevice object (the mouse is attempted first). Make sure to call delete on pDevice when the CImmDevice object is no longer needed. Failure to do so will result in memory leaks.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Call with a scope specifier as follows:

CImmDevice* pDevice = CImmDevice::CreateDevice(hinst, hwnd);

Since CImmDevice is an abstract base class, you should never directly create or allocate a CImmDevice object like you can with one of the derived classes. You can only directly create a CImmDevice object pointer and use this pointer to store the return value of CreateDevice.

It first looks for attached devices of device type IMM_DEVICETYPE_MOUSE. If one is found, it calls CImmMouse::Initialize and creates the IFeelit and IFeelitDevice COM objects for the first Immersion pointing device found. If no Immersion pointing device is found, it then looks for attached devices of device type IMM_DEVICETYPE_DIRECTINPUT. If one is found, it calls CImmDXDevice::Initialize and creates the IDirectInput and IDirectInputDevice2 COM objects for the first DX force feedback device found.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmDXDevice::Initialize()

CImmMouse::Initialize()


CImmDevice::GetDevice

Call this member to retrieve a pointer to the IFeelitDevice or IDirectInputDevice2 interface associated with the CImmDevice object.

LPIIMM_DEVICE GetDevice();

Parameters

None.

Return Values

If the function succeeds, the return value is a COM interface point.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should only call this member function after having successfully initialized the device via the CImmDevice::CreateDevice or derived class Initialize member functions.

If you need to call a method of the IFeelitDevice or IDirectInputDevice2 interface (e.g., to call the SetProperty method), use this function to get the device interface and call the method directly. If you are calling the DirectX API you will need to cast the LPIIMM_DEVICE to an LPDIRECTINPUTDEVICE2.

GetDevice does not increment the reference count of the underlying IFeelitDevice or IDirectInputDevice2 COM object. Therefore, you should not call the Release method of the COM object when you are finished using the pointer returned by GetDevice. Furthermore, you should not attempt to use the interface pointer returned by this member function after the associated CImmDevice object is destroyed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetDeviceType()


CImmDevice::GetDeviceType

Call this member to determine the type of device associated with the CImmDevice object.

DWORD GetDeviceType();

Parameters

None.

Return Values

NULL
CImmDevice has not been Initialized
IMM_DEVICETYPE_DEVICE
Generic CImmDevice object
IMM_DEVICETYPE_MOUSE
CImmMouse object
IMM_DEVICETYPE_DIRECTINPUT
CImmDXDevice object

Remarks

The device type is not set until CreateDevice or derived class Initialize has been called. Device types will be added as other child classes are implemented.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateDevice()

GetDevice()


CImmDevice::GetDriverVersion

This function returns version numbers reported by the driver.

BOOL GetDriverVersion(
DWORD &dwFFDriverVersion,
DWORD &dwFirmwareRevision,
DWORD &dwHardwareRevision
);

Parameters

dwFFDriverVersion
Version number of the device driver.
dwFirmwareRevision
Specifies the firmware revision of the device.
dwHardwareRevision
Hardware revision of the device.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function retrieves information from the driver by calling the GetCapabilities() function found in either the Direct Input or the Immersion API.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetIFCVersion()

GetImmAPIVersion()

GetDXVersion()


CImmDevice::GetIFCVersion

Returns the file version numbers for the IFC DLL.

BOOL GetIFCVersion(
DWORD &dwMajor,
DWORD &dwMinor,
DWORD &dwBuild,
DWORD &dwBuildMinor
);

Parameters

dwMajor
Major release value which only changes with significant modifications.
dwMinor
Minor release value which changes when the class interfaces change.
dwBuild
Build value, updated when internal changes/improvements that do not affect the interface are made.
dwBuildMinor
Currently unused.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function provides an easy way to check the version of IFC installed on the system.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetDriverVersion()

GetImmAPIVersion()

GetDXVersion()


CImmDevice::GetImmAPIVersion

Retrieves the version information of the underlying Immersion API DLL.

BOOL GetImmAPIVersion(
DWORD &dwMajor,
DWORD &dwMinor,
DWORD &dwBuild,
DWORD &dwBuildMinor
);

Parameters

dwMajor
Major release value which only changes with significant modifications.
dwMinor
Minor release value which changes when the class interfaces change.
dwBuild
Build value, updated when internal changes/improvements that do not affect the interface are made.
dwBuildMinor
Currently unused.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Since the Immersion API is a COM object, it’s possible to initialize a version of the API that is not intended for use with a particular application. Although probing the API’s interface is preferred for determining its appropriate use, this function provides a quick way to check for a particular version of the API.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetDriverVersion()

GetIFCVersion()

GetDXVersion()


CImmDevice::GetDXVersion

The Function function does something completely amazing.

BOOL GetDXVersion(
DWORD &dwMajor,
DWORD &dwMinor,
DWORD &dwBuild,
DWORD &dwBuildMinor
);

Parameters

dwMajor
Major release number which only changes with significant modifications.
dwMinor
Minor release number.
dwBuild
Build number.
dwBuildMinor
Minor build number.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These values are the same given when viewing the file properties. Note that the version numbering of dinput.dll maybe different on different operating systems.

Since the Direct Input is a COM object, it’s possible to initialize a version of Dinput that is not intended for use with a particular application. Although probing the Direct Input interface is preferred for determining its appropriate use, this function provides a quick way to check for a particular version of the API.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetDriverVersion()

GetIFCVersion()

GetImmAPIVersion()


CImmDevice::GetProductGUID

Returns the manufacturer supplied GUID for the product.

GUID GetProductGUID();

Parameters

None.

Return Values

If the function succeeds, the return value is the product's GUID.

If the function fails, the return value is GUID_NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The product GUID is a unique identifier for the attached device. Currently, due to a Direct X issue, only Immersion pointing devices properly return a product GUID. Alternatively, product names can be used to identify products.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetProductGUIDString()

GetProductName()

GetProductType()


CImmDevice::GetProductGUIDString

Provides the product GUID in string form.

int GetProductGUIDString(
LPTSTR lpszGUID,
int nMaxCount
);

Parameters

lpszGUID
Pointer to a character array where the product GUID will be copied.
nMaxCount
Length of array.

Return Values

This function returns a NULL terminated string in the given character array. If the function fails, zero is return. When the function succeeds the return value is the length of the string copied into that array excluding the NULL character. If the array provided is too short, the GUID is concatenated to fit in the given array, and nMaxCount - 1 is returned.

CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The product GUID is a unique identifier for the attached device. Currently, due to a Direct X issue, only Immersion pointing devices properly return a product GUID. Alternatively, product names can be used to identify products.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetProductGUID()

GetProductName()

GetProductType()


CImmDevice::GetProductName

Copies the device name into the provided character array.

int GetProductName(
LPTSTR lpszProductName,
int nMaxCount
);

Parameters

lpszProductName
Pointer to a character array where the product name will be copied.
nMaxCount
Length of array.

Return Values

This function returns a NULL terminated string in the given character array. If the function fails or no name is available, zero is return. When the function succeeds the return value is the length of the string copied into that array excluding the NULL character. If the array provided is too short, the product name is concatenated to fit in the given array, and nMaxCount - 1 is returned.

CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The names of products may differ from language to language.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetProductGUID()

GetProductGUIDString()


CImmDevice::GetProductType

This function provides information to differentiate categories of force feedback devices and technologies.

DWORD GetProductType();

Parameters

None.

Return Values

The HIWORD contains a device type constant while the LOWORD contains a bit mask value for the TouchSense technology type. Device types include joysticks, wheels, gamepads, absolute mice, and relative mice. Technology types include Full Force Feedback and Inertial Harmonic Drive.

Device Type Constants

IMM_OTHERDEVICE
IMM_JOYSTICK
IMM_WHEEL
IMM_GAMEPAD
IMM_ABSMOUSE
IMM_RELMOUSE

Technology Type Bit Values

IMM_OTHERTECH
IMM_FULLFF
IMM_IHDFF

Remarks

The return value contains information on the type of device and the type of force feedback technology.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetDevice()

GetDeviceType()


CImmDevice::StopAll

Stops all effects playing on the device.

BOOL StopAll();

Parameters

None

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Instead of calling stop on each effect being played, Stop() can be called to cease the playback of all effects on the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmDevices

The CImmDevices class is used for managing multiple TouchSense devices on one system. It provides a simple interface for finding and using multiple TouchSense devices in one application.

The following table summarizes the CImmDevices class members:

Initialization
CreateDevices | Enumerates for the requested number of devices and initializes them.
Attributes
GetDevice | Retrieves the device object pointer of the device specified by the index.
GetNumDevices | Returns the number of devices found by the CreateDevices call.
Operations
AddDevice | Adds a CImmDevice to the device list.

Class Hierarchy:

CImmDevices


CImmDevices::AddDevice

Adds a CImmDevice to the device list.

void AddDevice(
IMM_DEVICE_PTR pDevice
);

Parameters

pDevice
Pointer to a CImmDevice object.

Return Values

None.

Remarks

CreateDevices uses this function to add devices as they are enumerated. There is no need to use this function if CreateDevices is used to enumerate through attached TouchSense devices.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateDevices()


CImmDevices::CreateDevices

This function enumerates for the requested number of devices and initializes them.

long CreateDevices(
HINSTANCE hinstApp,
HWND hwndApp,
long lMaximumDevices = -1,
IMM_ENUMERATE type = IMM_ENUMERATE_ALL,
IMM_ENUMERATE_PREFERENCE preference = IMM_NO_PREFERENCE
);

Parameters

hinstApp
Instance handle of the application.
hwndApp
Window handle of the application's top most window.
lMaximumDevices
Number of TouchSense devices that will be used in the application. CreateDevices will try to provide the requested number of devices unless too few are attached. When -1 is passed all attached devices will be intialized.
type
Use this parameter to specify whether a TouchSense pointing device or a TouchSense gaming device is needed. Excluding a device type will prevent enumeration for that type of device.
IMM_ENUMERATE_IMM_DEVICES
IMM_ENUMERATE_DX_DEVICES
IMM_ENUMERATE_ALL
preference
Specify the preferred device type in this parameter.
IMM_NO_PREFERENCE
IMM_PREFER_IMM_DEVICES
IMM_PREFER_DX_DEVICES

Return Values

The number of successfully created devices is returned. Use GetDevice to access the individual CImmDevice pointers.

Remarks

Use IMM_PREFER_DX_DEVICES when a gaming device is preferred. If there are not enough gaming devices to satisfy the number given in lMaximumDevices and IMM_ENUMERATE_IMMDEVICES is set, pointing devices attached to the system will be enumerated and initialized. Passing in IMM_PREFER_IMM_DEVICES will force pointing devices to be enumerated before gaming devices. The default behavior is to enumerate for pointing devices first.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddDevice()

GetDevice()

GetNumDevices()


CImmDevices::GetDevice

Retrieves the device object pointer of the device specified by the index.

IMM_DEVICE_PTR GetDevice(
long lIndex
);

Parameters

lIndex
Index number for the device in the Devices list.

Return Values

If successful, a device object is returned. Otherwise, NULL is returned.

Remarks

Device pointers returned by this function should not be used after the Devices object has been destroyed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetNumDevices()


CImmDevices::GetNumDevices

Returns the number of devices found by the CreateDevices call.

long GetNumDevices();

Parameters

None.

Return Values

If zero is returned after calling CreateDevices, no force feedback devices of the requested type was found on the system.

Remarks

The returned value is not valid until the CreateDevices function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateDevices()

GetDevice()


CImmDXDevice

The CImmDXDevice class is derived from CImmDevice and should be used for applications using a DirectX force feedback gaming device like an Immersion joystick or wheel. To add forces to your application, you will need to create and initialize a CImmDXDevice object and pass a pointer to that object to the initialization member functions of the IFC effects in your application. The CImmDXDevice class adds two member functions that are new or that override the CImmDevice base member functions. Refer to the CImmDevice documentation for a detailed description of the base class members.

The following table summarizes the CImmDXDevice class members:

Construction
CImmDXDevice | Constructs a CImmDXDevice object.
Initialization
Initialize | Enumerates attached DX force feedback devices and initializes the DirectX API COM objects for the first one found.

Class Hierarchy:

CImmDevice

CImmDXDevice


CImmDXDevice::CImmDXDevice

Constructs a CImmDXDevice object.

CImmDXDevice();

Parameters

None.

Return Values

NA

Remarks

The CImmDXDevice constructor does not create the corresponding IDirectInputDevice2 COM object. It only initializes a class object and assigns the device GUID. The DirectX API COM object is created in the CImmDXDevice::Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmDXDevice::Initialize

Call this member function to create and initialize an IDirectInputDevice2 COM object and associate it with the CImmDXDevice object.

BOOL Initialize (
HINSTANCE hinstApp,
HWND hwndApp,
LPDIRECTINPUT pDI = NULL,
LPDIRECTINPUTDEVICE2 piDevice = NULL
);

Parameters

hinstApp
Instance handle to the application or DLL that is creating the IDirectInput/IDirectInputDevice2 COM objects.
hwndApp
Window handle to be associated with the device. This parameter must be a valid top-level window handle that belongs to the process. The window associated with the device must not be destroyed while the device is still active.
pDI
DirectInput COM object interface pointer. See explanation below. Default value if omitted is NULL.
piDevice
DirectInput Device2 COM object interface pointer. See explanation below. Default value if omitted is NULL.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This member function will enumerate all attached devices of device type IMM_DEVICETYPE_DIRECTINPUT. If DirectX 8 is installed, Initialize will create an IDirectInputDevice8 API COM object for the first DX force feedback device it finds. If a previous version of DirectX is installed, Initialize will create an DirectInputDevice2 API COM object instead. From then on, this DirectX API COM object is associated with the CImmDXDevice object. The COM object is automatically released in the CImmDXDevice destructor, except in certain cases (see below). Normally, the third and fourth arguments can be omitted except in the case described below.

If your application already has the COM interfaces of DirectInput (only DX5 or later), or DirectInput8 (only DX8 or later), but you have not added force feedback yet, you can still use IFC to implement force feedback for DX force feedback devices. Simply use IFC according to one of the first three cases described Step 2 of the IFC tutorial with one exception. The exception is that the Initialize method for a CImmDXDevice has optional third and fourth arguments for existing LPDIRECTINPUT and LPDIRECTINPUTDEVICE2 interface pointers. If you have already created an IDirectInput interface in your application, simply pass a pointer to this interface as the third parameter in your Initialize call for your CImmDXDevice. If you have already created an IDirectInputDevice2 interface in your application, simply pass a pointer to this interface as the fourth parameter in your Initialize call for your CImmDXDevice. IFC will then forego creating another instance of these interfaces and simply use the pre-existing one(s) for the DirectX force feedback implementation. If you are using DirectX 8, simply cast your IDirectInput8 and IDirectInputDevice8 interface pointers to IDirectInput and IDirectInputDevice2, respectively, and pass them into the Initialize call.

IMPORTANT: The IDirectInputDevice2 interface must be for a force feedback device. If no IDirectInputDevice2 interface for a force feedback device exists, pass in ONLY the IDirectInput interface and IFC will create its own IDirectInputDevice2 interface. IFC will not release the IDirectInput interface that was passed in, but it will release the IDirectInputDevice2 interface created by CImmDXDevice::Initialize once the object is destroyed.

IMPORTANT: Normally IFC will create the IDirectInput and IDirectInputDevice2 interfaces in the CImmDXDevice::Initialize method and release the interfaces when the CImmDXDevice object is deleted. If you pass in a pre-existing IDirectInput or IDirectInputDevice2 interface to the Initialize method, IFC will not release those interfaces when the device object is deleted. It is your application’s responsibility to release those interfaces since your application created them independently of IFC.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmEffect

The CImmEffect class is the base class used for creating all effects. The purpose of CImmEffect is to provide common functionality for the following type-specific effect classes that derive from it:

  • CImmCondition
  • CImmConstant
  • CImmEllipse
  • CImmEnclosure
  • CImmPeriodic
  • CImmRamp
  • CImmTexture

To create an effect, use one of the above derivatives (child classes) of CImmEffect. However, you may want to use some of the base members functions provided by CImmEffect.

The following table summarizes the CImmEffect class members:

Construction
CImmEffect | Constructs a CImmEffect object.
Initialization
InitializeFromProject | Creates an effect on the device using data from an IFR file and attaches it to the CImmEffect object.
Attributes
ChangeBaseParams | Changes the base parameters of an effect and updates the effect on the device. Base parameters are those common to all effect types.
ChangeBaseParamsPolar | Same as ChangeBaseParams, but allows directions to be specified in polar coordinates.
Change Parameter Functions | Functions for changing base parameters individually.
ChangeDirection | Changes the direction of a directional effect, and updates the effect on the device.
ChangeEnvelope | Changes the envelope of an effect, and updates the effect on the device.
GetEffect | Retrieves the Immersion TouchSense COM interface pointer associated with the effect.
GetEffectType | Returns an identifier for the type of effect.
GetGUID | Retrieves the effect's GUID.
GetIsCompatibleGUID | Reports wether or not a given GUID is comptible with the effect.
GetName | Returns a pointer to the effect name.
Get Parameter Functions | Functions for retrieving currect base parameter values.
GetParameters | Retrieves the raw effect information from the driver.
GetStatus | Returns the current status of the effect.
Operations
Start | Causes the effect to play on the device.
Stop | Causes the effect to stop playing.
Globals
NewObjectFromGUID | Creates the proper IFC effect object for the given GUID.

Class Hierarchy:

CImmEffect

CImmCondition

CImmConstant

CImmEllipse

CImmEnclosure

CImmPeriodic

CImmRamp

CImmTexture


CImmEffect::CImmEffect

Constructs a CImmEffect object.

CImmEffect( const GUID& rguidEffect );

Parameters

rguidEffect
Identifier of the effect to create. The following table shows the relationship between effect classes and effect GUIDs. In most cases, a particular effect should be created using the appropriate effect class and not by constructing a CImmEffect object with the corresponding GUID.

CImmConstant GUID_Imm_ConstantForce
CImmDamper GUID_Imm_Damper
CImmEllipse GUID_Imm_Ellipse
CImmEnclosure GUID_Imm_Enclosure
CImmFriction GUID_Imm_Friction
CImmGrid GUID_Imm_Grid
CImmInertia GUID_Imm_Inertia
CImmPeriodic GUID_Imm_SawtoothUp
CImmPeriodic GUID_Imm_SawtoothDown
CImmPeriodic GUID_Imm_Sine
CImmPeriodic GUID_Imm_Square
CImmPeriodic GUID_Imm_Triangle
CImmRamp GUID_Imm_RampForce
CImmSpring GUID_Imm_Spring
CImmTexture GUID_Imm_Texture

Return Values

NA

Remarks

This constructor is typically not called directly by the user. Rather, it is called by the constructor of one of the child classes (which inherit from CImmEffect). The Immersion Foundation Classes' constructors do not create the corresponding Immersion TouchSense COM object. They only initialize a class object and assign the effect GUID. The Immersion TouchSense COM object is created and downloaded to the device in the Initalize or InitializeCondition member function of one of the CImmEffect child classes.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmEffect::ChangeBaseParams

Call this member to change an effect’s base parameters (i.e. those parameters that are common to all effect types).

BOOL ChangeBaseParams(
LONG lDirectionX,
LONG lDirectionY,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
IMM_ENVELOPE pEnvelope = IMM_EFFECT_DONT_CHANGE_PTR,
DWORD dwSamplePeriod = IMM_EFFECT_DONT_CHANGE,
DWORD dwGain = IMM_EFFECT_DONT_CHANGE,
DWORD dwTriggerButton = IMM_EFFECT_DONT_CHANGE,
DWORD dwTriggerRepeatInterval = IMM_EFFECT_DONT_CHANGE,
DWORD dwStartDelay = IMM_EFFECT_DONT_CHANGE
);

Parameters

lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional condition, specifies the y-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. Note that not all effect types use envelopes. If no envelope is to be applied, then the member should be set to NULL. To leave this effect parameter unchanged, use the value (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR.
dwSamplePeriod
Reserved.
dwGain
The gain to be applied to the effect, in the range 0 to 10,000. The gain is a scaling factor applied to all magnitudes of the effect and its envelope. If you do not want the original magnitudes to be attenuated, specify a gain of 10,000.
dwTriggerButton
The offset of the button to be used to trigger playback of the effect. Use the following values to set the effect trigger button.

IMM_MOUSEOFFSET_BUTTON0
IMM_MOUSEOFFSET_BUTTON1
IMM_MOUSEOFFSET_BUTTON2
IMM_MOUSEOFFSET_BUTTON3

If this member is set to IMM_PARAM_NOTRIGGER, then no trigger button is associated with the effect. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

dwTriggerRepeatInterval
The interval, in microseconds, between the end of one playback and the start of the next when the effect is triggered by a button press and the button is held down. Setting this value to INFINITE suppresses repetition. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwStartDelay
After calling CImmEffect::Start(), the effect will begin after dwStartDelay, in milliseconds, has elapsed. Each time the effect is started the StartDelay will be included. If dwStartDelay is zero, the effect will play immediately after calling Start(). To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use this member function to set parameters that are not otherwise changeable using members of the child class. For example, CImmCondition and all of its subclasses assume that the duration will always be infinite, since conditions are typically turned on and off in response to discrete events. Therefore, they do not give you a way to set the duration. However, in some special instances, you may want to create a condition that plays for a specified period of time, and then turns off on its own. In order to do so, you could create and initialize a CImmCondition object, and then call the ChangeBaseParams base member to set the duration as follows:

m_pDamper->ChangeBaseParams(
IMM_EFFECT_DONT_CHANGE, // DirectionX
IMM_EFFECT_DONT_CHANGE, // DirectionY
5 * IMM_SECONDS // Duration
);

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeBaseParamsPolar()

Change Parameter Functions


CImmEffect::ChangeBaseParamsPolar

Call this member to change an effect’s base parameters (i.e. those parameters that are common to all effect types).

BOOL ChangeBaseParamsPolar(
LONG lAngle,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
IMM_ENVELOPE pEnvelope = IMM_EFFECT_DONT_CHANGE_PTR,
DWORD dwSamplePeriod = IMM_EFFECT_DONT_CHANGE,
DWORD dwGain = IMM_EFFECT_DONT_CHANGE,
DWORD dwTriggerButton = IMM_EFFECT_DONT_CHANGE,
DWORD dwTriggerRepeatInterval = IMM_EFFECT_DONT_CHANGE,
DWORD dwStartDelay = IMM_EFFECT_DONT_CHANGE
);

Parameters

lAngle
Specifies the angle of the radial direction vector. The angle must be given in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Optional pointer to a IMM_ENVELOPE structure that describes the envelope to be used by this effect. Note that not all effect types use envelopes. If no envelope is to be applied, then the member should be set to NULL. To leave this effect parameter unchanged, use the value (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR.
dwSamplePeriod
Reserved.
dwGain
The gain to be applied to the effect, in the range 0 to 10,000. The gain is a scaling factor applied to all magnitudes of the effect and its envelope. If you do not want the original magnitudes to be attenuated, specify a gain of 10,000.
dwTriggerButton
The offset of the button to be used to trigger playback of the effect. Use the following values to set the effect trigger button.

IMM_MOUSEOFFSET_BUTTON0
IMM_MOUSEOFFSET_BUTTON1
IMM_MOUSEOFFSET_BUTTON2
IMM_MOUSEOFFSET_BUTTON3

If this member is set to IMM_PARAM_NOTRIGGER, then no trigger button is associated with the effect. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

dwTriggerRepeatInterval
The interval, in microseconds, between the end of one playback and the start of the next when the effect is triggered by a button press and the button is held down. Setting this value to INFINITE suppresses repetition. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwStartDelay
After calling CImmEffect::Start(), the effect will begin after dwStartDelay, in milliseconds, has elapsed. Each time the effect is started the StartDelay will be included. If dwStartDelay is zero, the effect will play immediately after calling Start(). To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

It is only valid to use this member function with directional condition effects. This method is largely the same as ChangeBaseParams, except that it allows you to specify the angle of the direction instead of its X and Y components. See ChangeBaseParams for more information.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeBaseParams()

Change Parameter Functions


CImmEffect Change Parameter Functions

Use these functions to change a single parameter at a time. These parameters are common to all effects. Functions to change type specific parameters are available in the child classes.

BOOL ChangeDirection(
LONG lDirectionX,
LONG lDirectionY
);
BOOL ChangeDirection( LONG lAngle );
BOOL ChangeDuration( DWORD dwDuration );
BOOL ChangeEnvelope(
DWORD dwAttackLevel,
DWORD dwAttackTime, // microseconds
DWORD dwFadeLevel,
DWORD dwFadeTime // microseconds
);
BOOL ChangeEnvelope( LPIMM_ENVELOPE pEnvelope );
BOOL ChangeGain( DWORD dwGain );
BOOL ChangeIterations( DWORD dwIterations );
BOOL ChangeStartDelay( DWORD dwStartDelay );
BOOL ChangeTriggerButton( DWORD dwTriggerButton );
BOOL ChangeTriggerRepeatInterval( DWORD dwTriggerRepeatInterval );

Parameters

lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lDirectionY
For a directional condition, specifies the y-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lAngle
Specifies the angle of the radial direction vector. The angle must be in hundredths of degrees from 0 to 36000.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain.
pEnvelope
Pointer to an IMM_ENVELOPE structure that describes the envelope to be used by this effect. Note that not all effect types use envelopes. If no envelope is available, then NULL is returned.
dwGain
The gain of the effect, in the range 0 to 10,000. The gain is a scaling factor applied to all magnitudes of the effect and its envelope.
dwIterations
The number of times the effect is to be played after calling Start(). If the value is INFINITE, the effect will repeat until Stop() is called. The entire effect including the StartDelay will play with each repetition.
dwStartDelay
After calling CImmEffect::Start(), the effect will begin after dwStartDelay, in milliseconds, has elapsed. Each time the effect is started the StartDelay will be included. If dwStartDelay is zero, the effect will play immediately after calling Start().
dwTriggerButton
The offset of the button to be used to trigger playback of the effect. Use the following values to set the effect trigger button.

IMM_MOUSEOFFSET_BUTTON0
IMM_MOUSEOFFSET_BUTTON1
IMM_MOUSEOFFSET_BUTTON2
IMM_MOUSEOFFSET_BUTTON3

If this member is set to IMM_PARAM_NOTRIGGER, then no trigger button is associated with the effect.

dwTriggerRepeatInterval
The interval, in microseconds, between the end of one playback and the start of the next when the effect is triggered by a button press and the button is held down. A value of INFINITE suppresses repetition.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeBaseParams()

ChangeBaseParamsPolar()

ChangeDirection()


CImmEffect::ChangeDirection

Call this member to change an effect’s direction.

BOOL ChangeDirection(
LONG lDirectionX,
LONG lDirectionY
);

BOOL ChangeDirection(
LONG lAngle
);

Parameters

lDirectionX
Specifies the X-component of the direction vector.
lDirectionY
Specifies the Y-component of the direction vector.
lAngle
Specifies the angle of the direction vector.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

It is only valid to use this member function with directional effects. You should use this member when the only parameter you want to change is the direction. If you want to change other parameters as well as the direction, use the ChangeBaseParams member function or the appropriate ChangeParameters member function of the child class.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeBaseParams()

ChangeBaseParamsPolar()

Change Parameter Functions


CImmEffect::GetEffect

Call this member function to retrieve the Immersion TouchSense COM interface pointer associated with the effect.

LPIIMM_EFFECT GetEffect();

Parameters

None.

Return Values

If the function succeeds, the function returns the COM interface pointer created when the effect was initialized.

If the function fails, the return value is NULL.

Remarks

This member function is provided to allow you to use the lower-level API functions to manipulate effects that you have created using IFC.

If you need to call a method of the IFeelitEffect or IDirectInputEffect interface (e.g. GetEffectStatus), use this function to get the device interface and call the method directly. If you are calling the DirectX API you will need to cast the LPIIMM_EFFECT to an LPDIRECTINPUTEFFECT. For example, the following code could be used to retrieve an effect’s type specific parameters:

LPDIRECTINPUTEFFECT lpiDIEffect = (LPDIRECTINPUTEFFECT)pEffect->GetEffect();

DICONSTANTFORCE buffer;

DIEFFECT dieffect;

dieffect.dwSize = sizeof (effect);

dieffect.dwFlags = DIEFF_CARTESIAN | DIEFF_OBJECTIDS ;

dieffect.lpvTypeSpecificParams = (void *)&buffer;

dieffect.cbTypeSpecificParams = sizeof (buffer);

HRESULT hr = lpiDIEffect->GetParameters(&dieffect, DIEP_TYPESPECIFICPARAMS);

GetEffect does not increment the reference count of the Immersion TouchSense COM object. Therefore, you should not call the Release member of the COM object when you are finished using the pointer. Furthermore, you should not attempt to use the interface pointer returned by this member function after the associated CImmEffect object is destroyed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetStatus()


CImmEffect::GetEffectType

Returns an identifier for the type of effect.

DWORD GetEffectType();

Parameters

None.

Return Values

If the function fails, zero is returned. Otherwise, one of the following values is returned.

IMM_EFFECTTYPE_CONDITION
IMM_EFFECTTYPE_CONSTANTFORCE
IMM_EFFECTTYPE_ELLIPSE
IMM_EFFECTTYPE_ENCLOSURE
IMM_EFFECTTYPE_PERIODIC
IMM_EFFECTTYPE_RAMPFORCE
IMM_EFFECTTYPE_TEXTURE

Remarks

When receiving a CImmEffect pointer it may be necessary to cast the pointer as a particular effect class. This function provides an easy way of determining an object’s type. Although GetGUID will provide a way to differentiate effects, GetEffectType only categorizes as far as the basic effect type, and it’s return value is much simpler to deal with than GUIDs.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetGUID()

GetName()


CImmEffect::GetGUID

Returns the object’s GUID.

GUID GetGUID();

Parameters

None.

Return Values

The object's GUID.

Remarks

Use this when you have a GENERIC_EFFECT_PTR and need to know what kind of object it points to.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()

GetName()


CImmEffect::GetIsCompatibleGUID

Use this function to determine an effect's class or exact type.

BOOL GetIsCompatibleGUID(
GUID& guid
);

Parameters

guid
The GUID you want to check compatibility with.

Return Values

Returns TRUE if the given GUID is compatible with this type of object. Otherwise, FALSE is returned.

Remarks

For example, if this is really is a CImmRamp object then GetIsCompatibleGUID will only return TRUE if GUID_Imm_RampForce is passed in. If it is CImmPeriodic then the method will return TRUE for several GUIDs: GUID_Imm_Sine, GUID_Imm_Triangle, etc.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()

GetGUID()

GetName()


CImmEffect::GetName

Effect names are optional and can only be assigned internally by IFC. Use this function to access an effect name.

LPCSTR GetName();

Parameters

None.

Return Values

If the function succeeds, a pointer to a character array is returned.

If the function fails or no name exists, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function is for retrieving effect names assigned within IFR files. Effect Projects use names to identify effects.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()


CImmEffect Get Parameter Functions

These functions return the current values of parameters that are common to all effects. Get functions for type specific parameters defined in child classes.

BOOL GetDirection(
LONG& lDirectionX,
LONG& lDirectionY
);
BOOL GetDirection( LONG& lAngle );
BOOL GetDuration( DWORD& dwDuration );
BOOL GetEnvelope( LPIMM_ENVELOPE pEnvelope );
BOOL GetGain( DWORD& dwGain );
BOOL GetIterations( DWORD& dwIterations );
BOOL GetStartDelay( DWORD& dwStartDelay );
BOOL GetTriggerButton( DWORD& dwTriggerButton );
BOOL GetTriggerRepeatInterval( DWORD& dwTriggerRepeatInterval );

Parameters

lDirectionX
For a directional condition, specifies the x-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lDirectionY
For a directional condition, specifies the y-component of the direction vector. For a 1-axis or 2-axis condition, this parameter is ignored.
lAngle
Specifies the angle of the radial direction vector. The angle is given in hundredths of degrees from 0 to 36000.
dwDuration
The total duration of the effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain.
pEnvelope
Memory address of a valid IMM_ENVELOPE structure. Envelope data will be copied to the provided structure. Note that not all effect types use envelopes. If no envelope is available, then FALSE is returned and the structure is left unmodified.
dwGain
The gain of the effect, in the range 0 to 10,000. The gain is a scaling factor applied to all magnitudes of the effect and its envelope.
dwIterations
The number of times the effect is played after calling Start(). If the value is INFINITE, the effect will repeat until Stop() is called. The entire effect including the StartDelay will play with each repetition.
dwStartDelay
After calling CImmEffect::Start(), the effect will begin after dwStartDelay, in milliseconds, has elapsed. Each time the effect is started the StartDelay will be included. If dwStartDelay is zero, the effect will play immediately after calling Start().
dwTriggerButton
The offset of the button to be used to trigger playback of the effect. The following values are valid settings for trigger button.

IMM_MOUSEOFFSET_BUTTON0
IMM_MOUSEOFFSET_BUTTON1
IMM_MOUSEOFFSET_BUTTON2
IMM_MOUSEOFFSET_BUTTON3

If this member is set to IMM_PARAM_NOTRIGGER, then no trigger button is associated with the effect.
dwTriggerRepeatInterval
The interval, in microseconds, between the end of one playback and the start of the next when the effect is triggered by a button press and the button is held down. A value of INFINITE suppresses repetition.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

With exception to the GetDirection call, these functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetParameters()


CImmEffect::GetParameters

This function fills an Effect struct with data from the driver.

void GetParameters(
IMM_EFFECT &Effect
);

Parameters

Effect
Pass the Effect struct that will be filled with the current effect information.

Return Values

NA

Remarks

Information returned in this structure is unmodified from the driver, so any time based values will be given in microseconds. If only individual parameter values are needed, use the parameter specific Get functions instead.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Get Parameter Functions


CImmEffect::GetStatus

Call this member to get the status of an effect.

BOOL GetStatus(
DWORD* pdwStatus
);

Parameters

pdwStatus
Points to a DWORD to receive the status flags for the effect. The value may be zero, or one or more of the following constants:

IMM_STATUS_PLAYING | The effect is playing.
IMM_STATUS_EMULATED | The effect is emulated.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The effect must first be initialized for this function to work properly.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Start()

Stop()


CImmEffect::InitializeFromProject

Initializes an effect object from the parameters stored in an effect from an IFR file and creates the effect on the device.

BOOL InitializeFromProject (
CImmProject& project,
LPCSTR lpszEffectName,
CImmDevice* pDevice = NULL,
DWORD dwNoDownload = 0
);

Parameters

project
An open project to read the effect from.
lpszEffectName
The effect’s name in the IFR file.
pDevice
Specifies the device that the effect will be created on. If left as NULL, the device passed to CImmProject::OpenFile will be used.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use InitializeFromProject when you want to use effects stored in an IFR file, but also want to have a copy of the effect object. If you don’t need to manipulate effect objects yourself, it may be simpler to use CImmProject methods like Start and Stop.

If myProject is an open CImmProject, here is an example of how you might initialize a periodic object from an IFR effect:

CImmPeriodic periodic;

periodic.InitializeFromProject(myProject, "Laser");

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmProject::Start()

CImmProject::Stop()


CImmEffect::NewObjectFromGUID

Allocates an object of the correct IFC class from the given GUID. This is a static member function.

static GENERIC_EFFECT_PTR NewObjectFromGUID(
GUID &guid
);

Parameters

guid
The GUID you want the new object to have.

Return Values

If the function succeeds, the return value is a pointer to an effect object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The object that is allocated and returned is really of a type based on the GUID you pass. For example, if you pass GUID_Imm_Sine, then a pointer to a CPeriodic will be returned.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()

GetGUID()


CImmEffect::ChangeEnvelope

Call this member to change an effect’s envelope.

BOOL ChangeEnvelope(
LPIMM_ENVELOPE pEnvelope
);
BOOL ChangeEnvelope(
DWORD dwAttackLevel,
DWORD dwAttackTime,
DWORD dwFadeLevel,
DWORD dwFadeTime
);

Parameters

pEnvelope
Pointer to a IMM_ENVELOPE structure that describes the new envelope to be used by this effect.
dwAttackLevel
Amplitude for the start of the envelope, relative to the baseline, in the range 0 to 10,000. If the effect's type-specific data does not specify a baseline, then the amplitude is relative to zero.
dwAttackTime
The time, in microseconds, to reach the sustain level.
dwFadeLevel
Amplitude for the end of the envelope, relative to the baseline, in the range 0 to 10,000. If the effect's type-specific data does not specify a baseline, then the amplitude is relative to zero.
dwFadeTime
The time, in microseconds, to reach the fade level.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note that the time based parameters in this function are in microseconds and not milliseconds.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeBaseParameters()

Change Parameter Functions


CImmEffect::Start

Call this member function to begin playing an effect.

BOOL Start(
DWORD dwIterations = IMM_EFFECT_DONT_CHANGE,
DWORD dwFlags = 0
);

Parameters

dwIterations
Number of times to play the effect in sequence. The envelope is re-articulated with each iteration. To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE. If the effect was loaded in through an IFR file, the number of iterations set in the IFR file will be used as the default.
dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:

IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If the effect is already playing, it is restarted from the beginning.

A value other than IMM_EFFECT_DONT_CHANGE will override the iterations setting only during the current call to Start() but will not permanently change the iterations value. In order to affect subsequent calls to Start(), use CImmEffect::ChangeIterations to change the iterations value.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetStatus()

Stop()


CImmEffect::Stop

Call this member to stop a playing effect.

BOOL Stop();

Parameters

None.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If the effect is not playing, this member function returns TRUE, but otherwise has no effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetStatus()

Start()


CImmEllipse

The CImmEllipse class is used for creating effects of type IMM_EFFECTTYPE_ELLIPSE. Currently only Immersion devices support this type of effect. Also not available when an Immersion device is in relative positioning mode.

The following table summarizes the CImmEllipse class members:

Construction
CImmEllipse | Constructs a CImmEllipse object.
Initialization
Initialize | Creates an Ellipse effect on the device and attaches it to the CImmEllipse object. Allows ellipse coordinates to be specified as either a rect or as a center point and height and width.
Attributes
ChangeParameters | Changes the parameters of the CImmEllipse object and updates the effect on the device. Allows ellipse coordinates to be specified as either a rect or as a center point and height and width.
ChangeCenter | Changes the center point of an existing ellipse. Allows center point to be specified as an XY pair or as a point.
ChangeRect | Changes the bounding rect of an existing ellipse.
Change Parameter Functions | Functions for changing type specific parameters individually.
Get Parameter Functions | Functions for retrieving the current parameter values.
GetInsideEffect | Returns a pointer to the inside effect.
Operations
Start | Causes the effect to play on the device.

Class Hierarchy:

CImmEffect

CImmEllipse


CImmEllipse::CImmEllipse

Constructs a CImmEllipse object.

CImmEllipse();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmEllipse::ChangeParameters

Call this member to change any of the ellipse effect’s parameters.

BOOL ChangeParameters(
LPCRECT prectBoundary,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwStiffnessMask = IMM_EFFECT_DONT_CHANGE,
DWORD dwClippingMask = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

BOOL ChangeParameters(
POINT pntCenter,
DWORD dwWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwHeight = IMM_EFFECT_DONT_CHANGE,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwStiffnessMask = IMM_EFFECT_DONT_CHANGE,
DWORD dwClippingMask = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the ellipse in screen coordinates. This cannot be set to NULL. If you do not wish to specify the bounding rectangle, use the other form of ChangeParameters with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the bounding rectangle of the ellipse in screen coordinates. To leave the center point unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT. To use the mouse position at the time the effect is started as the center point, use the value IMM_EFFECT_MOUSE_POS_AT_START.
dwWidth
Specifies the width of the bounding rectangle of the ellipse in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwHeight
Specifies the height of the bounding rectangle of the ellipse in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lStiffness
Specifies the inner and outer wall stiffness of the ellipse. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring condition that is applied when the cursor is in any of the ellipse walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwWallThickness
Specifies the wall width or thickness of the ellipse in pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Specifies the maximum value of the wall force of the ellipse, in the range 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwStiffnessMask
Specifies the stiffness mask of the ellipse. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwClippingMask
Specifies the clipping mask of the ellipse. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the ellipse. If no effect is to be played inside the ellipse, then the member should be set to NULL. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
Specifies the angle in degrees used to rotate the Ellipse around its center. The center is located at the midpoint of the length and width of the Ellipse. Positive degrees rotate the Ellipse clockwise. Negative degrees rotate the Ellipse counter-clockwise. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use this member function to set parameters of an ellipse other than the ellipse position. To change ellipse position only, use the ChangeCenter or ChangeRect member functions. To change base effect parameters (e.g., duration, trigger), use the base class member function CImmEffect::ChangeBaseParams(). The following example shows how you would change the duration of a CImmEllipse object:

m_pEllipse->ChangeBaseParams(
IMM_EFFECT_DONT_CHANGE, // DirectionX
IMM_EFFECT_DONT_CHANGE, // DirectionY
5 * IMM_SECONDS // Duration
);

ChangeParameters has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeCenter()

ChangeRect()

Change Parameter Functions


CImmEllipse Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeRect( LPCRECT prectBoundary );
BOOL ChangeCenter( POINT pntCenter );
BOOL ChangeCenter( LONG x, LONG y );
BOOL ChangeStiffness( LONG lStiffness );
BOOL ChangeWallThickness( DWORD dwThickness );
BOOL ChangeSaturation( DWORD dwSaturation );
BOOL ChangeStiffnessMask( DWORD dwStiffnessMask );
BOOL ChangeClippingMask( DWORD dwClippingMask );
BOOL ChangeInsideEffect( CImmEffect* pInsideEffect );

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the ellipse in screen coordinates.
pntCenter
Specifies the center point of the bounding rectangle of the ellipse in screen coordinates.
lStiffness
Specifies the inner and outer wall stiffness of the ellipse. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring condition that is applied when the cursor is in any of the ellipse walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
dwWallThickness
Specifies the wall width or thickness of the ellipse in pixels.
dwSaturation
Specifies the maximum value of the wall force of the ellipse, in the range 0 to 10,000.
dwStiffnessMask
Specifies the stiffness mask of the ellipse.
dwClippingMask
Specifies the clipping mask of the ellipse.
pInsideEffect
Pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the ellipse. If no effect is to be played inside the ellipse, then the member should be set to NULL. Inside and “outside” effects have a one to one relationship. An inside effect can only belong to one outside effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeCenter()

ChangeRect()


CImmEllipse Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetRect( RECT* prectBoundary );
BOOL GetCenter( POINT &pntCenter );
BOOL GetCenter( LONG &x, LONG &y);
BOOL GetStiffness( LONG &lStiffness );
BOOL GetWallThickness( DWORD &dwWallThickness );
BOOL GetSaturation( DWORD &dwSaturation );
BOOL GetStiffnessMask( DWORD &dwStiffnessMask );
BOOL GetClippingMask( DWORD &dwClippingMask );
CImmEffect* GetInsideEffect ();

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the ellipse in screen coordinates.
pntCenter
Specifies the center point of the bounding rectangle of the ellipse in screen coordinates.
lStiffness
Specifies the inner and outer wall stiffness of the ellipse. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring condition that is applied when the cursor is in any of the ellipse walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
dwWallThickness
Specifies the wall width or thickness of the ellipse in pixels.
dwSaturation
Specifies the maximum value of the wall force of the ellipse, in the range 0 to 10,000.
dwStiffnessMask
Specifies the stiffness mask of the ellipse.
dwClippingMask
Specifies the clipping mask of the ellipse.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetInsideEffect()


CImmEllipse::GetInsideEffect

Returns a pointer to the CImmEffect object being used as an inside effect.

CImmEffect* GetInsideEffect ();

Parameters

None.

Return Values

If the function succeeds, the return value is valid pointer to an effect object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Inside and “outside” effects have a one to one relationship. An inside effect can only belong to one outside effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Get Parameter Functions


CImmEllipse::Initialize

Call this member to create an ellipse effect on the device and attach it to the CImmEllipse object.

BOOL Initialize(
CImmDevice* pDevice,
LPCRECT prectBoundary,
LONG lStiffness = IMM_ELLIPSE_DEFAULT_STIFFNESS,
DWORD dwWallThickness = IMM_ELLIPSE_DEFAULT_WALL_WIDTH,
DWORD dwSaturation = IMM_ELLIPSE_DEFAULT_SATURATION,
DWORD dwStiffnessMask = IMM_ELLIPSE_DEFAULT_STIFFNESS_MASK,
DWORD dwClippingMask = IMM_ELLIPSE_DEFAULT_CLIPPING_MASK,
CImmEffect* pInsideEffect = NULL,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwNoDownload = 0
);

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwWidth = IMM_ELLIPSE_DEFAULT_WIDTH,
DWORD dwHeight = IMM_ELLIPSE_DEFAULT_HEIGHT,
LONG lStiffness = IMM_ELLIPSE_DEFAULT_STIFFNESS,
DWORD dwWallThickness = IMM_ELLIPSE_DEFAULT_WALL_WIDTH,
DWORD dwSaturation = IMM_ELLIPSE_DEFAULT_SATURATION,
DWORD dwStiffnessMask = IMM_ELLIPSE_DEFAULT_STIFFNESS_MASK,
DWORD dwClippingMask = IMM_ELLIPSE_DEFAULT_CLIPPING_MASK,
POINT pntCenter = IMM_ELLIPSE_DEFAULT_CENTER_POINT,
CImmEffect* pInsideEffect = NULL,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the ellipse in screen coordinates. This can not be set to NULL. If you do not wish to specify the bounding rectangle, use the other form of Initialize with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the bounding rectangle of the ellipse in screen coordinates. To use the default center point, use the value IMM_ELLIPSE_DEFAULT_CENTER_POINT.
dwWidth
Specifies the width of the bounding rectangle of the ellipse in screen coordinates. To use the default width, use the value IMM_ELLIPSE_DEFAULT_WIDTH.
dwHeight
Specifies the height of the bounding rectangle of the ellipse in screen coordinates. To use the default height, use the value IMM_ELLIPSE_DEFAULT_HEIGHT.
lStiffness
Specifies the wall stiffness of the ellipse. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring condition that is applied when the cursor is in any of the ellipse walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To use the default stiffness, use the value IMM_ELLIPSE_DEFAULT_STIFFNESS.
dwWallThickness
Specifies the wall width or thickness of the ellipse in pixels. To use the default thickness, use the value IMM_ELLIPSE_DEFAULT_WALL_WIDTH.
dwSaturation
Specifies the maximum value of the wall force of the ellipse. To use the default saturation, use the value IMM_ELLIPSE_DEFAULT_SATURATION.
dwStiffnessMask
Specifies the stiffness mask of the ellipse. To use the default stiffness mask, use the value IMM_ELLIPSE_DEFAULT_STIFFNESS_MASK.
IMM_STIFF_NONE
No forces are felt in the ellipse walls.
IMM_STIFF_OUTERANYWALL
Forces are felt when the cursor is inside of an outer wall of the ellipse.
IMM_STIFF_INNERANYWALL
Forces are felt when the cursor is inside of an inner wall of the ellipse.
IMM_STIFF_ANYWALL
Forces are felt when the cursor is inside of any wall of the ellipse.
dwClippingMask
Specifies the clipping mask of the ellipse. To use the default clipping mask, use the value IMM_ELLIPSE_DEFAULT_CLIPPING_MASK.
IMM_CLIP_NONE
Clipping is not applied at all.
IMM_CLIP_OUTERANYWALL
Clipping is applied when the cursor is inside of an outer wall of the ellipse.
IMM_CLIP_INNERANYWALL
Clipping is applied when the cursor is inside of an inner wall of the ellipse.
IMM_CLIP_ANYWALL
Clipping is applied when the cursor is inside of any wall of the ellipse.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the ellipse. If no effect is to be played inside the ellipse, then the member should be set to NULL.
lAngle
Specifies the angle in degrees used to rotate the Ellipse around its center. The center is located at the midpoint of the length and width of the Ellipse. Positive degrees rotate the Ellipse clockwise. Negative degrees rotate the Ellipse counter-clockwise. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Initialize has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Start()


CImmEllipse::ChangeCenter

Call this member to change the center of the ellipse.

BOOL ChangeCenter (
LONG x,
LONG y
);
BOOL
ChangeCenter (
POINT pntCenter
);

Parameters

x
Specifies the X screen coordinate of the new ellipse center point.
y
Specifies the Y screen coordinate of the new ellipse center point.
pntCenter
Specifies the center point of the bounding rectangle of the ellipse in screen coordinates.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should only use this member function when the only parameter you want to change is the center point. If you want to change other parameters as well as the center point, use the ChangeParameters member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeRect()

Change Parameter Functions


CImmEllipse::ChangeRect

Call this member to change the size and location of the ellipse.

BOOL ChangeRect (
LPCRECT pRect
);

Parameters

pRect
Specifies the new bounding rectangle of the ellipse in screen coordinates.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should only use this member function when the only parameter you want to change is the ellipse-bounding rectangle. If you want to change other parameters as well as the ellipse-bounding rectangle, use the ChangeParameters member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeCenter()

Change Parameter Functions


CImmEllipse::Start

Call this member to start playing the ellipse effect.

BOOL Start (
DWORD dwFlags = 0
);

Parameters

dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:

IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function overrides the base method, CImmEffect::Start(), to allow for the automatic assignment of the center point to the current position of the mouse cursor.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmEnclosure

The CImmEnclosure class is used for creating effects of type IMM_EFFECTTYPE_ENCLOSURE. Currently only Immersion devices support this type of effect. Also not available when an Immersion device is in relative positioning mode.

The following table summarizes the CImmEnclosure class members:

Construction
CImmEnclosure | Constructs a CImmEnclosure object.
Initialization
Initialize | Creates an Enclosure effect on the device and attaches it to the CImmEnclosure object. Allows enclosure coordinates to be specified as either a rect or as a center point and height and width.
Attributes
ChangeParameters | Changes the parameters of the CImmEnclosure object and updates the effect on the device. Allows enclosure coordinates to be specified as either a rect or as a center point and height and width.
ChangeCenter | Changes the center point of an existing enclosure. Allows center point to be specified as an XY pair or as a point.
ChangeRect | Changes the bounding rect of an existing enclosure.
Change Parameter Functions | Functions for changing type specific parameters individually.
Get Parameter Functions | Functions for retrieving the current parameter values.
GetInsideEffect | Returns a pointer to the inside effect.
ShowRect | A design technique, this function shows the placement of an Enclosure.
Operations
Start | Causes the effect to play on the device.

Class Hierarchy:

CImmEffect

CImmEnclosure


CImmEnclosure::CImmEnclosure

Constructs a CImmEnclosure object.

CImmEnclosure();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only creates a class object and assigns the effect GUID. The API COM object is created, and the effect is downloaded to the device in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmEnclosure::ChangeParameters

Call this member to change any of the enclosure effect’s parameters.

BOOL ChangeParameters(
LPCRECT prectBoundary,
LONG lTopAndBottomWallStiffness = IMM_EFFECT_DONT_CHANGE,
LONG lLeftAndRightWallStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwTopAndBottomWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwLeftAndRightWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwTopAndBottomSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwLeftAndRightSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwStiffnessMask = IMM_EFFECT_DONT_CHANGE,
DWORD dwClippingMask = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

BOOL ChangeParameters(
POINT pntCenter,
DWORD dwWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwHeight = IMM_EFFECT_DONT_CHANGE,
LONG lTopAndBottomWallStiffness = IMM_EFFECT_DONT_CHANGE,
LONG lLeftAndRightWallStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwTopAndBottomWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwLeftAndRightWallThickness = IMM_EFFECT_DONT_CHANGE,
DWORD dwTopAndBottomSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwLeftAndRightSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwStiffnessMask = IMM_EFFECT_DONT_CHANGE,
DWORD dwClippingMask = IMM_EFFECT_DONT_CHANGE,
CImmEffect* pInsideEffect = (CImmEffect*) IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the rectangular enclosure in screen coordinates. This can not be set to NULL. If you do not wish to specify the rectangle, use the other form of ChangeParameters with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the rectangular enclosure in screen coordinates. To leave the center point unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT. To use the mouse position at the time the effect is started as the center point, use the value IMM_EFFECT_MOUSE_POS_AT_START.
dwWidth
Specifies the width of the rectangular enclosure in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwHeight
Specifies the height of the rectangular enclosure in screen coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lTopAndBottomWallStiffness
Specifies the stiffness of the top and bottom walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lLeftAndRightWallStiffness
Specifies the stiffness of the left and right walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwTopAndBottomWallThickness
Specifies the wall width or thickness of the top and bottom walls of the enclosure in pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwLeftAndRightWallThickness
Specifies the wall width or thickness of the left and right walls of the enclosure in pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwTopAndBottomWallSaturation
Specifies the maximum value of the top and bottom wall forces of the enclosure. Must be between 0 and 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwLeftAndRightWallSaturation
Specifies the maximum value of the left and right wall forces of the enclosure. Must be between 0 and 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwStiffnessMask
Specifies the stiffness mask of the enclosure. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwClippingMask
Specifies the clipping mask of the enclosure. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the enclosure. If no effect is to be played inside the enclosure, then the member should be set to NULL. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
Specifies the angle in degrees used to rotate the Enclosure around the top-left corner. Positive degrees rotate the Enclosure clockwise. Negative degrees rotate the Enclosure counter-clockwise. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use this member function to set parameters of an enclosure other than the enclosure position. To change enclosure position only, use the ChangeCenter or ChangeRect member functions. To change base effect parameters (e.g., duration, trigger), use the base class member function CImmEffect::ChangeBaseParams(). The following example shows how you would change the duration of a CImmEnclosure object:

m_pEnclosure->ChangeBaseParams(
IMM_EFFECT_DONT_CHANGE, // DirectionX
IMM_EFFECT_DONT_CHANGE, // DirectionY
5 * IMM_SECONDS // Duration
);

ChangeParameters has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeCenter()

ChangeRect()

Change Parameter Functions


CImmEnclosure Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeRect( LPCRECT prectBoundary );
BOOL ChangeCenter( POINT pntCenter );
BOOL ChangeCenter( LONG x, LONG y );
BOOL ChangeTopAndBottomWallStiffness( LONG lTopBottomWallStiffness );
BOOL ChangeLeftAndRightWallStiffness( LONG lLeftRightWallStiffness );
BOOL ChangeTopAndBottomWallThickness( DWORD dwTopBottomWallThickness );
BOOL ChangeLeftAndRightWallThickness( DWORD dwLeftRightWallThickness );
BOOL ChangeTopAndBottomWallSaturation(DWORD dwTopBottomWallSaturation);
BOOL ChangeLeftAndRightWallSaturation(DWORD dwLeftRightWallSaturation);
BOOL ChangeStiffnessMask( DWORD dwStiffnessMask );
BOOL ChangeClippingMask( DWORD dwClippingMask );
BOOL ChangeInsideEffect( CImmEffect* pInsideEffect );

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the enclosure in screen coordinates.
pntCenter
Specifies the center point of the bounding rectangle of the enclosure in screen coordinates.
lTopAndBottomWallStiffness
Specifies the stiffness of the top and bottom walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
lLeftAndRightWallStiffness
Specifies the stiffness of the left and right walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
dwTopAndBottomWallThickness
Specifies the wall width or thickness of the top and bottom walls of the enclosure in pixels.
dwLeftAndRightWallThickness
Specifies the wall width or thickness of the left and right walls of the enclosure in pixels.
dwTopAndBottomWallSaturation
Specifies the maximum value of the top and bottom wall forces of the enclosure. Must be between 0 and 10,000.
dwLeftAndRightWallSaturation
Specifies the maximum value of the left and right wall forces of the enclosure. Must be between 0 and 10,000.
dwStiffnessMask
Specifies the stiffness mask of the enclosure.
dwClippingMask
Specifies the clipping mask of the enclosure.
pInsideEffect
Pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the enclosure. If no effect is to be played inside the enclosure, then the member should be set to NULL. Inside and “outside” effects have a one to one relationship. An inside effect can only belong to one outside effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeCenter()

ChangeRect()


CImmEnclosure Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetRect( RECT* prectBoundary );
BOOL GetCenter( POINT &pntCenter );
BOOL GetCenter( LONG &x, LONG &y);
BOOL GetTopAndBottomWallStiffness ( LONG &lTopAndBottomWallStiffness );
BOOL GetLeftAndRightWallStiffness ( LONG &lLeftAndRightWallStiffness );
BOOL GetTopAndBottomWallThickness ( DWORD &dwTopAndBottomWallThickness );
BOOL GetLeftAndRightWallThickness ( DWORD &dwLeftAndRightWallThickness );
BOOL GetTopAndBottomWallSaturation ( DWORD &dwTopAndBottomWallSaturation );
BOOL GetLeftAndRightWallSaturation ( DWORD &dwLeftAndRightWallSaturation );
BOOL GetStiffnessMask ( DWORD &dwStiffnessMask );
BOOL GetClippingMask ( DWORD &dwClippingMask );
CImmEffect* GetInsideEffect();

Parameters

prectBoundary
A pointer to a LPCRECT structure specifying the bounding rectangle of the enclosure in screen coordinates.
pntCenter
Specifies the center point of the bounding rectangle of the enclosure in screen coordinates.
lTopAndBottomWallStiffness
Specifies the stiffness of the top and bottom walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
lLeftAndRightWallStiffness
Specifies the stiffness of the left and right walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor.
dwTopAndBottomWallThickness
Specifies the wall width or thickness of the top and bottom walls of the enclosure in pixels.
dwLeftAndRightWallThickness
Specifies the wall width or thickness of the left and right walls of the enclosure in pixels.
dwTopAndBottomWallSaturation
Specifies the maximum value of the top and bottom wall forces of the enclosure. Must be between 0 and 10,000.
dwLeftAndRightWallSaturation
Specifies the maximum value of the left and right wall forces of the enclosure. Must be between 0 and 10,000.
dwStiffnessMask
Specifies the stiffness mask of the enclosure.
dwClippingMask
Specifies the clipping mask of the enclosure.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetInsideEffect()


CImmEnclosure::GetInsideEffect

Returns a pointer to the CImmEffect object being used as an inside effect.

CImmEffect* GetInsideEffect ();

Parameters

None.

Return Values

If the function succeeds, the return value is a valid pointer to an effect object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Inside and “outside” effects have a one to one relationship. An inside effect can only belong to one outside effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Get Parameter Functions


CImmEnclosure::Initialize

Call this member to create an enclosure effect on the device and attach it to the CImmEnclosure object.

BOOL Initialize(
CImmDevice* pDevice,
LPCRECT prectBoundary,
LONG lTopAndBottomWallStiffness = IMM_ENCLOSURE_DEFAULT_STIFFNESS,
LONG lLeftAndRightWallStiffness = IMM_ENCLOSURE_DEFAULT_STIFFNESS,
DWORD dwTopAndBottomWallThickness = IMM_ENCLOSURE_DEFAULT_WALL_WIDTH,
DWORD dwLeftAndRightWallThickness = IMM_ENCLOSURE_DEFAULT_WALL_WIDTH,
DWORD dwTopAndBottomWallSaturation = IMM_ENCLOSURE_DEFAULT_SATURATION,
DWORD dwLeftAndRightWallSaturation = IMM_ENCLOSURE_DEFAULT_SATURATION,
DWORD dwStiffnessMask = IMM_ENCLOSURE_DEFAULT_STIFFNESS_MASK,
DWORD dwClippingMask = IMM_ENCLOSURE_DEFAULT_CLIPPING_MASK,
CImmEffect* pInsideEffect = NULL,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwNoDownload = 0
);

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwWidth = IMM_ENCLOSURE_DEFAULT_WIDTH,
DWORD dwHeight = IMM_ENCLOSURE_DEFAULT_HEIGHT,
LONG lTopAndBottomWallStiffness = IMM_ENCLOSURE_DEFAULT_STIFFNESS,
LONG lLeftAndRightWallStiffness = IMM_ENCLOSURE_DEFAULT_STIFFNESS,
DWORD dwTopAndBottomWallThickness = IMM_ENCLOSURE_DEFAULT_WALL_WIDTH,
DWORD dwLeftAndRightWallThickness = IMM_ENCLOSURE_DEFAULT_WALL_WIDTH,
DWORD dwTopAndBottomWallSaturation = IMM_ENCLOSURE_DEFAULT_SATURATION,
DWORD dwLeftAndRightWallSaturation = IMM_ENCLOSURE_DEFAULT_SATURATION,
DWORD dwStiffnessMask = IMM_ENCLOSURE_DEFAULT_STIFFNESS_MASK,
DWORD dwClippingMask = IMM_ENCLOSURE_DEFAULT_CLIPPING_MASK,
POINT pntCenter = IMM_ENCLOSURE_DEFAULT_CENTER_POINT,
CImmEffect* pInsideEffect = NULL,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
prectBoundary
A pointer to a LPCRECT structure specifying the rectangular enclosure in screen coordinates. This cannot be set to NULL. If you do not wish to specify the rectangle, use the other form of Initialize with pntCenter, dwWidth, and dwHeight as parameters.
pntCenter
Specifies the center point of the rectangular enclosure in screen coordinates. To use the default center point, use the value IMM_ENCLOSURE_DEFAULT_CENTER_POINT.
dwWidth
Specifies the width of the rectangular enclosure in screen coordinates. To use the default width, use the value IMM_ENCLOSURE_DEFAULT_WIDTH.
dwHeight
Specifies the height of the rectangular enclosure in screen coordinates. To use the default height, use the value IMM_ENCLOSURE_DEFAULT_HEIGHT.
lTopAndBottomWallStiffness
Specifies the stiffness of the top and bottom walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To use the default stiffness, use the value IMM_ENCLOSURE_DEFAULT_STIFFNESS.
lLeftAndRightWallStiffness
Specifies the stiffness of the left and right walls of the enclosure. Defines the amount of force felt by the user when attempting to break through a wall. This value is the negative and positive coefficient for the spring conditions that are applied when the cursor is in any of the enclosure walls. Must be between –10000 and 10000. A positive value specifies that the walls attract the cursor. A negative value specifies that the walls repel the cursor. To use the default stiffness, use the value IMM_ENCLOSURE_DEFAULT_STIFFNESS.
dwTopAndBottomWallThickness
Specifies the wall width or thickness of the top and bottom walls of the enclosure in pixels. To use the default thickness, use the value IMM_ENCLOSURE_DEFAULT_WALL_WIDTH.
dwLeftAndRightWallThickness
Specifies the wall width or thickness of the left and right walls of the enclosure in pixels. To use the default thickness, use the value IMM_ENCLOSURE_DEFAULT_WALL_WIDTH.
dwTopAndBottomWallSaturation
Specifies the maximum value of the top and bottom wall forces of the enclosure. Must be between 0 and 10,000. To use the default saturation, use the value IMM_ENCLOSURE_DEFAULT_SATURATION.
dwLeftAndRightWallSaturation
Specifies the maximum value of the left and right wall forces of the enclosure. Must be between 0 and 10,000. To use the default saturation, use the value IMM_ENCLOSURE_DEFAULT_SATURATION.
dwStiffnessMask
Specifies the stiffness mask of the enclosure. To use the default stiffness mask, use the value IMM_ENCLOSURE_DEFAULT_STIFFNESS_MASK.
IMM_STIFF_NONE
No forces are felt on any wall
IMM_STIFF_OUTERTOPWALL
Forces are felt when the cursor is inside of the outer top wall of the enclosure.
IMM_STIFF_OUTERBOTTOMWALL
Forces are felt when the cursor is inside of the outer bottom wall of the enclosure.
IMM_STIFF_OUTERLEFTWALL
Forces are felt when the cursor is inside of the outer left wall of the enclosure.
IMM_STIFF_OUTERRIGHTWALL
Forces are felt when the cursor is inside of the outer right wall of the enclosure.
IMM_STIFF_INNERTOPWALL
Forces are felt when the cursor is inside of the inner top wall of the enclosure.
IMM_STIFF_INNERBOTTOMWALL
Forces are felt when the cursor is inside of the inner bottom wall of the enclosure.
IMM_STIFF_INNERLEFTWALL
Forces are felt when the cursor is inside of the inner left wall of the enclosure.
IMM_STIFF_INNERRIGHTWALL
Forces are felt when the cursor is inside of the inner right wall of the enclosure.
IMM_STIFF_OUTERANYWALL
Forces are felt when the cursor is inside of any outer wall of the enclosure.
IMM_STIFF_INNERANYWALL
Forces are felt when the cursor is inside of any inner wall of the enclosure.
IMM_STIFF_ANYWALL
Forces are felt when the cursor is inside of any wall of the enclosure.
dwClippingMask
Specifies the clipping mask of the enclosure. To use the default clipping mask, use the value IMM_ENCLOSURE_DEFAULT_CLIPPING_MASK.
IMM_CLIP_NONE
Clipping is not applied to any wall
IMM_CLIP_OUTERTOPWALL
Clipping is applied when the cursor is inside of the outer top wall of the enclosure.
IMM_CLIP_OUTERBOTTOMWALL
Clipping is applied when the cursor is inside of the outer bottom wall of the enclosure.
IMM_CLIP_OUTERLEFTWALL
Clipping is applied when the cursor is inside of the outer left wall of the enclosure.
IMM_CLIP_OUTERRIGHTWALL
Clipping is applied when the cursor is inside of the outer right wall of the enclosure.
IMM_CLIP_INNERTOPWALL
Clipping is applied when the cursor is inside of the inner top wall of the enclosure.
MM_CLIP_INNERBOTTOMWALL
Clipping is applied when the cursor is inside of the inner bottom wall of the enclosure.
IMM_CLIP_INNERLEFTWALL
Clipping is applied when the cursor is inside of the inner left wall of the enclosure.
IMM_CLIP _INNERRIGHTWALL
Clipping is applied when the cursor is inside of the inner right wall of the enclosure.
IMM_CLIP_OUTERANYWALL
Clipping is applied when the cursor is inside of any outer wall of the enclosure.
IMM_CLIP_INNERANYWALL
Clipping is applied when the cursor is inside of any inner wall of the enclosure.
IMM_CLIP_ANYWALL
Clipping is applied when the cursor is inside of any wall of the enclosure.
pInsideEffect
Optional pointer to a CImmEffect object that describes the effect to be played when the cursor is inside the enclosure. If no effect is to be played inside the enclosure, then the member should be set to NULL.
lAngle
Specifies the angle in degrees used to rotate the Enclosure around the top-left corner. Positive degrees rotate the Enclosure clockwise. Negative degrees rotate the Enclosure counter-clockwise. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Initialize has two forms. Use whichever one is more convenient or appropriate.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Start()


CImmEnclosure::ChangeCenter

Call this member to change the center of the enclosure.

BOOL ChangeCenter (
LONG x,
LONG y
);
BOOL
ChangeCenter (
POINT pntCenter
);

Parameters

x
Specifies the X screen coordinate of the new enclosure center point.
y
Specifies the Y screen coordinate of the new enclosure center point.
pntCenter
Specifies the center point of the rectangular enclosure in screen coordinates.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should only use this member function when the only parameter you want to change is the center point. If you want to change other parameters as well as the center point, use the ChangeParameters member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeRect()

Change Parameter Functions


CImmEnclosure::ChangeRect

Call this member to change the size and location of the enclosure.

BOOL ChangeRect (
LPCRECT pRect
);

Parameters

pRect
Specifies the new rectangular enclosure in screen coordinates.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

You should only use this member function when the only parameter you want to change is the enclosure bounding rectangle. If you want to change other parameters as well as the enclosure bounding rectangle, use the ChangeParameters member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeCenter()

Change Parameter Functions


CImmEnclosure::Start

Call this member to start playing the enclosure effect.

BOOL Start (
DWORD dwFlags = 0
);

Parameters

dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:

IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function overrides the base method, CImmEffect::Start(), to allow for the automatic assignment of the center point to the current position of the mouse cursor.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmEnclosure::ShowRect

Call this member function to draw an outline around the Enclosure. This should only be used for debugging purposes.

BOOL ShowRect(
BOOL bRectOn
);

Parameters

bRectOn
Turns enclosure outline drawing on or off.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

For debugging purposes, it’s useful to be able to see where the enclosure has been placed. Enclosure outlining is turned off by default. Set this function to TRUE to turn outlining on.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmFriction

The CImmFriction class is used for creating friction effects of type IMM_EFFECTTYPE_CONDITION.

The following table summarizes the CImmFriction class members:

Construction
CImmFriction | Constructs a CImmFriction object.
Initialization
Initialize | Creates a friction effect on the device and attaches it to the CImmFrictionobject. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of a friction force effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmCondition

CImmFriction


CImmFriction::CImmFriction

Constructs a CImmFriction object.

CImmFriction();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmFriction::ChangeParameters

Call this member to change the parameters of a friction effect after you have initialized it.

BOOL ChangeParameters(
DWORD dwCoefficient,
DWORD dwMinVelocity = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwCoefficient
The amount of opposing frictional force when in motion. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
For a directional friction force, specifies the x-component of the direction vector. The direction vector defines the axis on which the frictional force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional friction force, specifies the y-component of the direction vector. The direction vector defines the axis on which the frictional force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParameters to modify friction specific parameters. To change parameters common to all effects use the inherited ChangeBaseParams function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParametersPolar()

Change Parameter Functions


CImmFriction::ChangeParametersPolar

Call this member to change the parameters of a friction effect after you have initialized it.

BOOL ChangeParametersPolar (
DWORD dwCoefficient,
DWORD dwMinVelocity = IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwCoefficient
The amount of opposing frictional force when in motion. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the frictional force is felt. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParametersPolar to modify friction specific parameters. To change parameters common to all effects use the inherited ChangeBaseParamsPolar function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

Change Parameter Functions


CImmFriction Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeMinVelocity( DWORD dwMinVelocity );
BOOL ChangeMinVelocityX( DWORD dwMinVelocity );
BOOL ChangeMinVelocityY( DWORD dwMinVelocity );

Parameters

dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The functions that specify an X or Y Axis apply the minimum velocity change only to the noted axis while the function that does not specify an axis changes both axes minimum velocity to the same dwMinVelocity value.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeParametersPolar()


CImmFriction Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetMinVelocityX( DWORD &dwMinVelocity );
BOOL GetMinVelocityY( DWORD &dwMinVelocity );

Parameters

dwMinVelocity
Range of velocity in which the effect is not active.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use the corresponding function to get the minimum velocity for the axis of interest. No generic function exists for getting both values at the same time. If the ChangeMinVelocity was used to change both axes at once, either function can be used to retrieve the current setting.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeMinVelocity()


CImmFriction::Initialize

Call this member to create a friction effect on the device and attach it to the CImmFriction object.

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwCoefficient = IMM_FRICTION_DEFAULT_COEFFICIENT,
DWORD dwMinVelocity = IMM_FRICTION_DEFAULT_MIN_VELOCITY,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwCoefficient
The amount of opposing frictional force when in motion. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default coefficient, use the value IMM_FRICTION_DEFAULT_COEFFICIENT.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minumum velocity, use the value IMM_FRICTION_DEFAULT_MIN_VELOCITY.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect.
Can be one of the following values:

IMM_EFFECT_AXIS_X

IMM_EFFECT_AXIS_Y

IMM_EFFECT_AXIS_BOTH

IMM_EFFECT_AXIS_DIRECTIONAL

The default axis flag is IMM_EFFECT_AXIS_BOTH.

lDirectionX
For a directional friction force, specifies the X-component of the direction vector. The direction vector defines the axis on which the frictional force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default X-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
For a directional friction force, specifies the Y-component of the direction vector. The direction vector defines the axis on which the frictional force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default Y-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_Y.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitializePolar()

CImmCondition::Start()


CImmFriction::InitializePolar

Call this member to create a friction effect on the device and attach it to the CImmFriction object.

BOOL InitializePolar (
CImmDevice* pDevice,
DWORD dwCoefficient,
DWORD dwMinVelocity,
LONG lAngle,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwCoefficient
The amount of opposing frictional force when in motion. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default coefficient, use the value IMM_FRICTION_DEFAULT_COEFFICIENT.
dwMinVelocity
Range of velocity in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minimum velocity, use the value IMM_FRICTION_DEFAULT_MIN_VELOCITY.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the frictional force is felt. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitializePolar creates the effect object, but does not cause it to play. After calling InitializePolar, call the Start member function to play the effect. InitializePolar automatically sets dwfAxis to IMM_EFFECT_AXIS_DIRECTIONAL.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()

CImmCondition::Start()


CImmGrid

The CImmGrid class is used for creating grid effects of type IMM_EFFECTTYPE_CONDITION. Currently only Immersion pointing devices support this type of effect.

The following table summarizes the CImmGrid class members:

Construction
CImmGrid | Constructs a CImmGrid object.
Initialization
Initialize | Creates a grid effect on the device and attaches it to the CImmGrid object. Direction is specified as a Cartesian XY vector.
Attributes
ChangeParameters | Changes the parameters of a grid force effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmCondition

CImmGrid


CImmGrid::CImmGrid

Constructs a CImmGrid object.

CImmGrid();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The Immersion TouchSense COM object is created and downloaded to the device in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmGrid::ChangeParameters

Call this member to change any of the grid effect’s parameters.

BOOL ChangeParameters(
DWORD dwHorizSpacing = IMM_EFFECT_DONT_CHANGE,
DWORD dwVertSpacing = IMM_EFFECT_DONT_CHANGE,
LONG lHorizNodeStrength = IMM_EFFECT_DONT_CHANGE,
LONG lVertNodeStrength = IMM_EFFECT_DONT_CHANGE,
DWORD dwHorizOffset = IMM_EFFECT_DONT_CHANGE,
DWORD dwVertOffset = IMM_EFFECT_DONT_CHANGE,
DWORD dwHorizNodeSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwVertNodeSaturation = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwHorizSpacing
Specifies the horizontal center-to-center spacing of the grid lines in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwVertSpacing
Specifies the vertical center-to-center spacing of the grid lines in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lHorizNodeStrength
Specifies the strength of the node points in the horizontal direction in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lVertNodeStrength
Specifies the strength of the node points in the vertical direction in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwHorizOffset
Specifies the offset of the first node point in the horizontal direction in pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwVertOffset
Specifies the offset of the first node point in the vertical direction in pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwHorizSaturation
Specifies the saturation value of the node points in the horizontal direction in the range 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwVertSaturation
Specifies the saturation value of the node points in the vertical direction in the range 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use this member function to set parameters of a grid effect. For clarity, the parameters of CImmGrid::ChangeParameters() are named differently than the parameters to the base class member function CImmCondition::ChangeConditionParams(). Spacing parameters are mapped to Deadband, NodeStrength parameters are mapped to Coefficient, Offset parameters are mapped to Center, and Saturation parameters are mapped to Saturation. Refer to the IMM_CONDITION grid structure definition for more details.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions

CImmCondition::ChangeConditionParams()


CImmGrid Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeHSpacing( DWORD dwHorizSpacing );
BOOL ChangeVSpacing( DWORD dwVertSpacing );
BOOL ChangeHNodeStrength( LONG lHorizNodeStrength );
BOOL ChangeVNodeStrength( LONG lVertNodeStrength );
BOOL ChangeOffset( POINT pntOffset );
BOOL ChangeHNodeSaturation( DWORD dwHorizNodeSaturation );
BOOL ChangeVNodeSaturation( DWORD dwVertNodeSaturation );

Parameters

dwHorizSpacing
Specifies the horizontal center-to-center spacing of the grid lines in screen pixels.
dwVertSpacing
Specifies the vertical center-to-center spacing of the grid lines in screen pixels.
lHorizNodeStrength
Specifies the strength of the node points in the horizontal direction in the range -10,000 to 10,000.
lVertNodeStrength
Specifies the strength of the node points in the vertical direction in the range -10,000 to 10,000.
pntOffset
Specifies the offset of the first node point in pixels.
dwHorizSaturation
Specifies the saturation value of the node points in the horizontal direction in the range 0 to 10,000.
dwVertSaturation
Specifies the saturation value of the node points in the vertical direction in the range 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

Get Parameter Functions


CImmGrid Get Parameter Functions

These functions provide the current setting of individual parameters.

BOOL GetHSpacing( DWORD &dwHorizSpacing );
BOOL GetVSpacing( DWORD &dwVertSpacing );
BOOL GetHNodeStrength( LONG &lHorizNodeStrength );
BOOL GetVNodeStrength( LONG &lVertNodeStrength );
BOOL GetOffset( POINT &pntOffset );
BOOL GetHNodeSaturation( DWORD &dwHorizNodeSaturation );
BOOL GetVNodeSaturation( DWORD &dwVertNodeSaturation );

Parameters

dwHorizSpacing
Specifies the horizontal center-to-center spacing of the grid lines in screen pixels.
dwVertSpacing
Specifies the vertical center-to-center spacing of the grid lines in screen pixels.
lHorizNodeStrength
Specifies the strength of the node points in the horizontal direction in the range -10,000 to 10,000.
lVertNodeStrength
Specifies the strength of the node points in the vertical direction in the range -10,000 to 10,000.
pntOffset
Specifies the offset of the first node point in pixels.
dwHorizSaturation
Specifies the saturation value of the node points in the horizontal direction in the range 0 to 10,000.
dwVertSaturation
Specifies the saturation value of the node points in the vertical direction in the range 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmGrid::Initialize

Call this member to create a grid effect on the device and attach it to the CImmGrid object.

BOOL Initialize(
CImmDevice* pDevice,
DWORD dwHorizSpacing = IMM_GRID_DEFAULT_HORIZ_SPACING,
DWORD dwVertSpacing = IMM_GRID_DEFAULT_VERT_SPACING,
LONG lHorizNodeStrength = IMM_GRID_DEFAULT_NODE_STRENGTH,
LONG lVertNodeStrength = IMM_GRID_DEFAULT_NODE_STRENGTH,
DWORD dwHorizOffset = IMM_GRID_DEFAULT_HORIZ_OFFSET,
DWORD dwVertOffset = IMM_GRID_DEFAULT_VERT_OFFSET,
DWORD dwHorizNodeSaturation = IMM_GRID_DEFAULT_NODE_SATURATION,
DWORD dwVertNodeSaturation = IMM_GRID_DEFAULT_NODE_SATURATION,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwHorizSpacing
Specifies the horizontal center-to-center spacing of the grid lines in screen pixels. To use the default spacing, set this parameter to IMM_GRID_DEFAULT_HORIZ_SPACING.
dwVertSpacing
Specifies the vertical center-to-center spacing of the grid lines in screen pixels. To use the default spacing, set this parameter to IMM_GRID_DEFAULT_VERT_SPACING.
lHorizNodeStrength
Specifies the strength of the node points in the horizontal direction in the range -10,000 to 10,000. To use the default strength, set this parameter to IMM_GRID_DEFAULT_NODE_STRENGTH.
lVertNodeStrength
Specifies the strength of the node points in the vertical direction in the range -10,000 to 10,000. To use the default strength, set this parameter to IMM_GRID_DEFAULT_NODE_STRENGTH.
dwHorizOffset
Specifies the offset of the first node point in the horizontal direction in pixels. To use the default offset, set this parameter to IMM_GRID_DEFAULT_HORIZ_OFFSET.
dwVertOffset
Specifies the offset of the first node point in the vertical direction in pixels. To use the default offset, set this parameter to IMM_GRID_DEFAULT_VERT_OFFSET.
dwHorizSaturation
Specifies the saturation value of the node points in the horizontal direction in the range 0 to 10,000. To use the default saturation, set this parameter to IMM_GRID_DEFAULT_NODE_SATURATION.
dwVertSaturation
Specifies the saturation value of the node points in the vertical direction in the range 0 to 10,000. To use the default saturation, set this parameter to IMM_GRID_DEFAULT_NODE_SATURATION.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

For clarity, the parameters of CImmGrid::Initialize () are named differently than the parameters to the base class member function CImmCondition::InitCondition(). Spacing parameters are mapped to Deadband, NodeStrength parameters are mapped to Coefficient, Offset parameters are mapped to Center, and Saturation parameters are mapped to Saturation. Refer to the IMM_CONDITION grid structure definitions for more details.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmCondition::Start()

CImmCondition::InitCondition()


CImmInertia

The CImmInertia class is used for creating inertia effects of type IMM_EFFECTTYPE_CONDITION.

The following table summarizes the CImmInertia class members:

Construction
CImmInertia | Constructs a CImmInertia object.
Initialization
Initialize | Creates a inertia effect on the device and attaches it to the CImmInertia object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of an inertia force effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmCondition

CImmInertia


CImmInertia::CImmInertia

Constructs a CImmInertia object.

CImmInertia();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmInertia::ChangeParameters

Call this member to change the parameters of an inertia effect after you have initialized it.

BOOL ChangeParameters(
DWORD dwCoefficient,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwMinAcceleration = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwCoefficient
The rate at which an opposing force increases with respect to acceleration. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwCoefficient controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinAcceleration
Range of acceleration in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
For a directional inertia force, specifies the x-component of the direction vector. The direction vector defines the axis on which the inertial force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional inertia force, specifies the y-component of the direction vector. The direction vector defines the axis on which the inertial force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParameters to modify friction specific parameters. To change parameters common to all effects use the inherited ChangeBaseParams function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParametersPolar()

Change Parameter Functions


CImmInertia::ChangeParametersPolar

Call this member to change the parameters of an inertia effect after you have initialized it.

BOOL ChangeParametersPolar (
DWORD dwCoefficient,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwMinAcceleration = IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

dwCoefficient
The rate at which an opposing force increases with respect to acceleration. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwCoefficient controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwMinAcceleration
Range of acceleration in which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the inertial force is felt. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParametersPolar to modify friction specific parameters. To change parameters common to all effects use the inherited ChangeBaseParamsPolar function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

Change Parameter Functions


CImmInertia Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeMinAcceleration( DWORD dwMinAcceleration );
BOOL ChangeMinAccelerationX( DWORD dwMinAcceleration );
BOOL ChangeMinAccelerationY( DWORD dwMinAcceleration );

Parameters

dwMinAcceleration
Range of acceleration in which the effect is not active. Must be in the range of 0 to 10,000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The functions that specify an X or Y Axis apply the minimum acceleration change only to the noted axis while the function that does not specify an axis, changes both axes minimum acceleration to the same dwMinAcceleration value.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()

ChangeParametersPolar()


CImmInertia Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetMinAccelerationX( DWORD &dwMinAcceleration );
BOOL GetMinAccelerationY( DWORD &dwMinAcceleration );

Parameters

dwMinAcceleration
Range of acceleration in which the effect is not active.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Minimum acceleration is similar to the deadband in a Spring except that deadband is the area around the Spring's center in which no force is felt. For Inertia, a minimum threshhold acceleration must be exceeded before the Interial force is felt.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmInertia::Initialize

Call this member to create an inertia effect on the device and attach it to the CImmInertia object.

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwCoefficient = IMM_INERTIA_DEFAULT_COEFFICIENT,
DWORD dwSaturation = IMM_INERTIA_DEFAULT_SATURATION,
DWORD dwMinAcceleration = IMM_INERTIA_DEFAULT_MIN_ACCELERATION,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwCoefficient
The rate at which an opposing force increases with respect to acceleration. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default coefficient, use the value IMM_INERTIA_DEFAULT_COEFFICIENT.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwCoefficient controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_INERTIA_DEFAULT_SATURATION.
dwMinAcceleration
Range of acceleration in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minimum acceleration, use the value IMM_INERTIA_DEFAULT_MIN_ACCELERATION.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect.
Can be one of the following values:

IMM_EFFECT_AXIS_X

IMM_EFFECT_AXIS_Y

IMM_EFFECT_AXIS_BOTH

IMM_EFFECT_AXIS_DIRECTIONAL

The default axis flag is IMM_EFFECT_AXIS_BOTH.

lDirectionX
For a directional inertia force, specifies the X-component of the direction vector. The direction vector defines the axis on which the inertial force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default X-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
For a directional inertia force, specifies the Y-component of the direction vector. The direction vector defines the axis on which the inertial force is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default Y-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_Y.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitializePolar()

CImmCondition::Start()


CImmInertia::InitializePolar

Call this member to create an inertia effect on the device and attach it to the CImmInertia object.

BOOL InitializePolar (
CImmDevice* pDevice,
DWORD dwCoefficient,
DWORD dwMinAcceleration,
LONG lAngle,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwCoefficient
The rate at which an opposing force increases with respect to acceleration. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default coefficient, use the value IMM_INERTIA_DEFAULT_COEFFICIENT.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwCoefficient controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_INERTIA_DEFAULT_SATURATION.
dwMinAcceleration
Range of acceleration in which the effect is not active. Must be in the range of 0 to 10,000. To use the default minimum acceleration, use the value IMM_INERTIA_DEFAULT_MIN_ACCELERATION.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the inertial force is felt. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitializePolar creates the effect object, but does not cause it to play. After calling InitializePolar, call the Start member function to play the effect. InitializePolar automatically sets dwfAxis to IMM_EFFECT_AXIS_DIRECTIONAL.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()

CImmCondition::Start()


CImmMouse

The CImmMouse class is derived from CImmDevice and should be used for applications using an Immersion pointing device. To add forces to your application, you will need to create and initialize a CImmMouse object and pass a pointer to that object to the initialization member functions of the IFC effects in your application. The CImmMouse class adds three member functions that are new or that override the CImmDevice base member functions. Refer to the CImmDevice documentation for a detailed description of the base class members.

The following table summarizes the CImmMouse class members:

Construction
CImmMouse | Constructs a CImmMouse object.
Initialization
Initialize | Enumerates attached Immersion devices and initializes the Immersion TouchSense COM objects for the first one found.
Attributes
UsesWin32MouseServices SwitchToAbsoluteMode | Selects standard Win32 mouse services or DirectX for mouse input.

Class Hierarchy:

CImmDevice

CImmMouse


CImmMouse::CImmMouse

Constructs a CImmMouse object.

CImmMouse();

Parameters

None.

Return Values

NA

Remarks

The CImmMouse constructor does not create the corresponding Immersion TouchSense COM device object. It only initializes a class object and assigns the device GUID. The Immersion TouchSense COM object is created in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmMouse::Initialize

Call this member function to create and initialize an Immersion TouchSense COM device object and associate it with the CImmMouse object.

BOOL Initialize(
HINSTANCE hinstApp,
HWND hwndApp
);

Parameters

hinstApp
Instance handle to the application or DLL that is creating the Immersion TouchSense COM objects.
hwndApp
Window handle to be associated with the device. This parameter must be a valid top-level window handle that belongs to the process. The window associated with the device must not be destroyed while the device is still active.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This member function will enumerate all attached devices of device type IMM_DEVICETYPE_MOUSE. Initialize will create an Immersion TouchSense COM object for the first Immersion device it finds. From then on, the Immersion TouchSense COM device object is associated with the CImmMouse object. The COM object is automatically released in the CImmMouse destructor.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmDevice Base Member Functions


CImmMouse::SwitchToAbsoluteMode

IFC Reference

CImmMouse::SwitchToAbsoluteMode, CImmMouse::UsesWin32MouseServices

These class members are identical. Call either one to select between standard Win32 mouse services and DirectX for mouse input from your CImmMouse object.

BOOL UsesWin32MouseServices(
BOOL bWin32MouseServ
);
BOOL SwitchToAbsoluteMode(
BOOL bAbsMode
);

Parameters

bWin32MouseServ, bAbsMode
Boolean indicating whether the CImmMouse device should operate in relative or absolute mode. A value of TRUE indicates that the application uses standard Win32 Mouse Services and that the device should be in absolute mode, while a value of FALSE indicates that the application does not use standard Win32 Mouse Services and that the device should be in relative mode. By default, all CImmMouse devices will be in absolute mode unless this function is called.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If your application is not using the standard Win32 mouse messages (e.g., WM_MOUSEMOVE) and functions (e.g., GetCursorPos) to read mouse movement and display the cursor, you need to notify IFC that your CImmMouse device should work in relative mode. The CImmMouse is by default in absolute mode, meaning it reports an actual screen cursor position and assumes your application is using the standard Win32 mouse services. DirectX is not part of the standard Win32 mouse services, so if you are using DirectX, you need to switch your CImmMouse object to relative mode with the following method: This function should not be used with Tactile Feedback Mice. The function should only be used with full Force Feedback, absolute style mice like the Wingman Force Feedback Mouse.

// change CImmMouse from absolute to relative position reporting

m_pTSMouse->UsesWin32MouseServices(FALSE);

or

m_pTSMouse->SwitchToAbsoluteMode(FALSE);

If you are not sure which mode to use, use the following guidelines. Applications that don’t have a screen cursor and/or allow you to move the physical mouse infinitely in one direction and continually rotate or pan (e.g., 1st person action games) generally use relative mode. Applications that actually have a cursor that stops at the edge of the screen even if you keep moving the physical mouse further generally use the absolute Win32 mouse services. A game like Microsoft’s Age of Empires allows continual panning. However, the actual cursor stops at the edge of the screen while panning, so it is using absolute mode.

IMPORTANT: If while using your Immersion device you can move the cursor in other applications but cannot get mouse movement in your application, you most likely need to either switch your CImmMouse to relative mode or use GetCursorPos if that is suitable for your application.

IMPORTANT: If your application switches your CImmMouse to relative mode, you will not be able to use the two screen-position based effects - Enclosure and Ellipse. Both these effects require you to specify their screen locations and are active only when the cursor is in those locations. If you want to use Enclosure and Ellipse effects, your application needs to leave the CImmMouse object in absolute mode and use the Win32 mouse services for mouse input.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmDevice Base Member Functions


CImmPeriodic

The CImmPeriodic class is used for creating effects of type IMM_EFFECTTYPE_PERIODIC.

The following table summarizes the CImmPeriodic class members:

Construction
CImmPeriodic | Constructs a CImmPeriodic object.
Initialization
Initialize | Creates a Periodic effect on the device and attaches it to the CImmPeriodic object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of a periodic effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmPeriodic


CImmPeriodic::CImmPeriodic

Constructs a CImmPeriodic object.

CImmPeriodic( const GUID& rguidEffect );

Parameters

rguidEffect

Identifier of the effect to create (e.g., sine wave, square wave, triangle wave, sawtooth wave, etc)

GUID_Imm_SawtoothUp

GUID_Imm_SawtoothDown

GUID_Imm_Sine

GUID_Imm_Square

GUID_Imm_Triangle

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmPeriodic::ChangeParameters/Polar

Call these members to change any of the periodic effect’s parameters.

BOOL
ChangeParameters(
DWORD dwMagnitude = IMM_EFFECT_DONT_CHANGE,
DWORD dwPeriod = IMM_EFFECT_DONT_CHANGE,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE,
LONG lOffset = IMM_EFFECT_DONT_CHANGE,
DWORD dwPhase = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR
);

BOOL ChangeParametersPolar(
DWORD dwMagnitude = IMM_EFFECT_DONT_CHANGE,
DWORD dwPeriod = IMM_EFFECT_DONT_CHANGE,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE,
LONG lOffset = IMM_EFFECT_DONT_CHANGE,
DWORD dwPhase = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR
);

Parameters

dwMagnitude
Specifies the magnitude of the periodic effect from 0 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPeriod
Specifies the period of the periodic effect in milliseconds. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
Specifies the total duration of the periodic effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
Specifies the polar direction of the effect in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lOffset
Specifies the magnitude offset of the periodic effect from -10000 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPhase
Specifies the phase of the periodic effect in milliseconds. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Pointer to a IMM_ENVELOPE structure that describes the new envelope to be used by this effect. If no envelope is to be applied, then this member should be set to NULL. To leave this effect parameter unchanged, use the value (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use these member functions to set parameters of a periodic effect. Both a Cartesian and a polar version of this member are provided. Use whichever is most suitable or convenient.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmPeriodic Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeMagnitude( DWORD dwMagnitude );
BOOL ChangePeriod( DWORD dwPeriod );
BOOL ChangeOffset( LONG lOffset );
BOOL ChangePhase( DWORD dwPhase );

Parameters

dwMagnitude
Specifies the magnitude of the periodic effect from 0 to 10000.
dwPeriod
Specifies the period of the periodic effect in milliseconds.
lOffset
Specifies the magnitude offset of the periodic effect from -10000 to 10000.
dwPhase
Specifies the phase of the periodic effect in milliseconds.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()


CImmPeriodic Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetMagnitude( DWORD &dwMagnitude );
BOOL GetPeriod( DWORD &dwPeriod );
BOOL GetOffset( LONG &lOffset );
BOOL GetPhase( DWORD &dwPhase );

Parameters

dwMagnitude
Specifies the magnitude of the periodic effect from 0 to 10000.
dwPeriod
Specifies the period of the periodic effect in milliseconds.
lOffset
Specifies the magnitude offset of the periodic effect from -10000 to 10000.
dwPhase
Specifies the phase of the periodic effect in milliseconds.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmPeriodic::Initialize/Polar

Call these members to create a periodic effect on the device and attach it to the CImmPeriodic object.

BOOL Initialize (
CImmDevice* pDevice,
DWORD dwMagnitude = IMM_PERIODIC_DEFAULT_MAGNITUDE,
DWORD dwPeriod = IMM_PERIODIC_DEFAULT_PERIOD,
DWORD dwDuration = IMM_PERIODIC_DEFAULT_DURATION,
LONG lDirectionX = IMM_PERIODIC_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_PERIODIC_DEFAULT_DIRECTION_Y,
LONG lOffset = IMM_PERIODIC_DEFAULT_OFFSET,
DWORD dwPhase = IMM_PERIODIC_DEFAULT_PHASE,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);

BOOL InitializePolar(
CImmDevice* pDevice,
DWORD dwMagnitude = IMM_PERIODIC_DEFAULT_MAGNITUDE,
DWORD dwPeriod = IMM_PERIODIC_DEFAULT_PERIOD,
DWORD dwDuration = IMM_PERIODIC_DEFAULT_DURATION,
LONG lAngle = IMM_PERIODIC_DEFAULT_ANGLE,
LONG lOffset = IMM_PERIODIC_DEFAULT_OFFSET,
DWORD dwPhase = IMM_PERIODIC_DEFAULT_PHASE,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
dwMagnitude
Specifies the magnitude of the periodic effect from 0 to 10000. To use the default magnitude, set this parameter to IMM_PERIODIC_DEFAULT_MAGNITUDE.
dwPeriod
Specifies the period of the periodic effect in milliseconds. To use the default period, set this parameter to IMM_PERIODIC_DEFAULT_PERIOD.
dwDuration
Specifies the total duration of the periodic effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To use the default duration, set this parameter to IMM_PERIODIC_DEFAULT_DURATION.
lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates To use the default X component, set this parameter to IMM_PERIODIC_DEFAULT_DIRECTION_X.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates. To use the default Y component, set this parameter to IMM_PERIODIC_DEFAULT_DIRECTION_Y.
lAngle
Specifies the polar direction of the effect in hundredths of degrees from 0 to 36000. To use the default angle, set this parameter to IMM_PERIODIC_DEFAULT_ANGLE.
lOffset
Specifies the magnitude offset of the periodic effect from -10000 to 10000. To use the default offset, set this parameter to IMM_PERIODIC_DEFAULT_OFFSET.
dwPhase
Specifies the phase of the periodic effect in milliseconds. To use the default phase, set this parameter to IMM_PERIODIC_DEFAULT_PHASE.
pEnvelope
Pointer to a IMM_ENVELOPE structure that describes the new envelope to be used by this effect. If no envelope is to be applied, then this member should be set to NULL.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Both a Cartesian and a polar version of this member are provided. Use whichever is most suitable or convenient.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmProject

The CImmProject class is used for managing effects stored in an IFR file. It provides a simple interface for reading effects from an IFR and playing them.

The following table summarizes the CImmProject class members:

Construction
CImmProject | Constructs a CImmProject object.
Initialization
LoadProjectFromMemory | Reads IFR data from memory and associates it and a device with the project.
LoadProjectFromResource | Loads the specified IFR resource and associates it and a device with the project.
OpenFile | Opens the specified IFR or FFE file and associates it and a device with the project.
Deletion
Close | Releases all created effects and closes the project. This is called automatically from ~CImmProject.
Attributes
GetDevice | Returns the device associated with the project.
GetEffect | Returns a pointer that allows access to a data object in CImmProject. The effect does not need to be created beforehand.
GetEffectName | Returns the effect name.
GetEffectType | Return the type of effect.
GetTypeName | Returns the name of the effect type assign by Immersion Studio.
GetNumEffects | Returns the count of all effects in CImmProject including those that have not been created.
GetNumSounds | Returns the number of Sound info objects in CImmProject.
GetSoundName | Returns the name of a Sound object in CImmProject.
GetSoundPath | Returns the path info contained in a Sound object.
GetSoundData | Returns the duration and start delay values for the sound.
GetIsOpen | Returns TRUE if and only if a file has been opened for or data exists in the project.
Operations
AddEffect | Adds an existing created effect to the project’s list of effects.
AddSoundInfo | Adds a new Sound info object to CImmProject.
AddToCompound | Adds a new sound or effect object to a Compound contained in CImmProject.
CreateCompound | Adds a new Compound object to CImmProject.
CreateEffect | Creates the specified effect on the device.
CreateEffectByIndex | Creates the specified effect on the device.
RemoveFromCompound | Removes a sound or effect object from a Compound contained in CImmProject.
RemoveSound | Completely removes a Sound object from CImmProject and from any Compounds that contain it.
RemoveEffect | Completely removes an Effect object from CImmProject and from any Compounds that contain it.
Start | Starts the named effect, creating it if necessary.
Stop | Stops the named effect.
WriteToFile | Writes effect and sound data contained in the project to an IFR or FFE file.
Obsolete Functions
GetCreatedEffect | see GetEffect for compatibility issues.
GetEffectNameFromIFRbyIndex | see GetEffectName for compatibility issues.
GetEffectTypeFromIFR | see GetEffectType for compatibility issues.
GetNumCreatedEffects | see GetNumEffects for compatibility issues.
GetNumEffectsFromIFR | see GetNumEffects for compatibility issues.
GetEffectSoundPathFromIFR | see GetSoundPath for compatibility issues.

Class Hierarchy:

CImmProject


CImmProject::AddEffect

Adds an existing, created effect to the project’s list of effects.

CImmCompoundEffect* AddEffect(
LPCSTR lpszEffectName,
GENERIC_EFFECT_PTR pObject
);

Parameters

lpszEffectName
Specifies the name of the effect to be added. The name can be used to access the effect at a later time.
pObject
A pointer to a CImmEffect object that has already been initialized.

Return Values

If the function succeeds, the return value is valid CImmCompoundEffect pointer.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

AddEffect copies the effect parameters from the CImmEffect passed in. That data along with the effect name is used to create and add a new effect to the project's list of effects. If an effect by the same name is already contained in the project, the function will fail.

NOTE: pObject is not added to the list. Effect data is only copied from pObject. CImmProject will delete all effects it creates, but clean up of pObject must be handled by the application.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateEffect()

RemoveEffect()


CImmProject::AddSoundInfo

Adds a sound information object to the Project’s list of sounds.

BOOL AddSoundInfo(
LPCSTR lpszSoundName,
LPCSTR lpszAbsolutePath,
LPCSTR lpszRelativePath
);

Parameters

lpszSoundName
Specifies the name of the sound object to be added. The name can be used to access the effect at a later time.
lpszAbsolutePath
The absolute path to the wave file for this sound.
lpszRelativePath
The relative path to the wave file for this sound.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Sound objects contain the path information to a wave file. These sound objects must first be added to the project before they can be added to a compound effect.

A successful call to this function increments the number of sounds in the project. The index of the newly added sound object is GetNumSounds - 1.

If a sound object with the same name is contained in the project, this function will fail.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddToCompound()

CreateCompound()

GetSoundName()

GetSoundPath()

GetNumSounds()


CImmProject::AddToCompound

Adds a sound object or effect to an existing compound effect.

BOOL AddToCompound(
LPCSTR lpszCompoundName,
LPCSTR lpszObjectName
);

Parameters

lpszCompoundName
Specifies the name of the compound effect. This compound effect must exist in the project's effect list.
lpszObjectName
Specifies the name of the effect or sound object to be added to the compound effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function is used to add to the number of objects contained in a compound effect. To remove an object from a compound's contained elements use RemoveFromCompound.

The compound and the object to be added to the compound must exist in the project before using this function. If the project cannot find either the compound effect or the object to be added, the call will fail.

To add an effect or sound to a project, use AddEffect or AddSoundInfo.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateCompound()

RemoveFromCompound()

AddEffect()

AddSoundInfo()


CImmProject::CreateCompound

Creates an empty compound effect in the project.

BOOL CreateCompound(
LPCSTR lpszCompoundName
);

Parameters

lpszCompoundName
Specifies the name assigned to the compound effect.

Return Values

If the function succeeds, the return value TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

CreateCompound adds an empty compound effect to the project list. Once a compound effect is in the project, AddToCompound can be used to fill the compound effect with effect primitives and/or sound objects. Use GetEffect to retrieve the CImmCompoudEffect pointer for this object.

OpenFile or one of the Load functions does not have to be called before using this function. If the project has no effects or sound objects when CreateCompound is called, this function will make the created compound effect the initial effect in the project. Any functions that require at least one effect to be present in the project can be used after CreateCompound returns successfully.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddToCompound()

GetEffect()


CImmProject::Close

Closes the project. Releases all created effects and cleans up.

void Close();

Parameters

None.

Return Values

NA

Remarks

It is very important that the CImmDevice is not destroyed while a project that uses it is still open. Close is called automatically from ~CImmProject. Either destroy the project or explicitly call Close, before deleting the CImmDevice.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateEffect()

Start()


CImmProject::CreateEffect

Initializes an effect from the project onto the device.

CImmCompoundEffect* CreateEffect(
LPCSTR lpszEffectName,
CImmDevice* pDevice = NULL,
DWORD dwNoDownload = 0
);

Parameters

lpszEffectName
Specifies the effect in the project.
pDevice
The CImmDevice the effect will be created on. When left as NULL, the device that the project was opened with will be used. If the project was opened with a NULL device and no device is specified here, the function will fail.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is valid CImmCompoundEffect pointer.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

CreateEffect does not start the effect. It provides a way to preload an effect, so it is ready to play quickly when needed.

When successful a pointer to a CImmCompoundEffect object is returned. If the named effect is a primitive effect, then a pointer to a CImmCompoundEffect containing only a single effect will be returned.

Do not call delete the pointer returned. When a project is closed it will delete all of its created objects.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddEffect()

Start()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::CreateEffectByIndex

Initializes an effect from the project onto the device.

CImmCompoundEffect* CreateEffectByIndex(
int nEffectIndex,
CImmDevice* pDevice = NULL,
DWORD dwNoDownload = 0
);

Parameters

nEffectIndex
Specifies the zero based index of an effect in the project.
pDevice
The CImmDevice the effect will be created on. When left as NULL, the device that the project was opened with will be used. If the project was opened with a NULL device and no device is specified here, the function will fail.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is valid CImmCompoundEffect pointer.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

CreateEffectByIndex does not start the effect. It provides a way to preload an effect, so it is ready to play quickly when needed.

When successful a pointer to a CImmCompoundEffect object is returned. If the effect is a primitive effect then a pointer to a CImmCompoundEffect containing only a single effect object will be returned.

Do not call delete on the returned pointer. When a project is closed it will delete all of its created objects.

This function can be used with GetNumEffects to iterate through the project list and create all effects. However, allowing Start to dynamically create an effect when first played is the preferred method of downloading effect information to a device. Using Start to create the effects at various points in the application allows for smoother effect caching if needed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddEffect()

GetNumEffects()

Start()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetDevice

Returns the pointer to the CImmDevice object that was passed to LoadProjectFromMemory, LoadProjectFromResource, or OpenFile.

CImmDevice* GetDevice();

Parameters

None.

Return Values

If the function succeeds, the return value is a CImmDevice pointer.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

A return value of NULL is not an indication of an error. LoadProjectFromMemory, LoadProjectFromResource, and OpenFile can be called without specifying a device. If the current device is NULL, the initail Start call must specify the device to be used.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()

Start()


CImmProject::GetEffect

Returns an effect previously loaded into the project by either AddEffect, CreateCompound, OpenFile, or one of the Load functions.

CImmCompoundEffect* GetEffect(
LPCSTR lpszEffectName
);
CImmCompoundEffect* GetEffect(
int nIndex
);

Parameters

lpszEffectName
Name of contained effect. The effect name is case sensitive.
nIndex
Zero based index number of the requested effect. nIndex must be in the range of 0 to GetNumEffects().

Return Values

If the function succeeds, the return value is a pointer to a CImmCompoundEffect object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function will return a CImmCompoundEffect pointer for all valid nIndex values and effect names. CreateEffect or Start does NOT need to be called on this effect before a CImmCompoundEffect* can be obtained.

GetCreatedEffect was made obsolete due to this function. Note: GetCreatedEffect had the limitation that the effect retrieved had to have been previously created.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddEffect()

OpenFile()

LoadProjectFromMemory()

LoadProjectFromResource()


CImmProject::GetEffectName

Returns the name of an effect in the project. The effect need not have been previously created through CreateEffect to access its name through this function.

LPCSTR GetEffectName(
int nEffectIndex
);

Parameters

nEffectIndex
An integer from 0 to GetNumEffects – 1 assuming GetNumEffects returns a value greater than zero.

Return Values

If the function succeeds, the return value is pointer to a charater array.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

GetEffectName will return NULL if data has not been loaded into the project. OpenFile, LoadProjectFromResource, or LoadProjectFromMemory can be used to load IFR data into the project.

Note: GetEffectNameFromIFRbyIndex was made obsolete by this function. All effect information including effect name can be accessed once data has been loaded into the project using OpenFile or one of the Load functions.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetNumEffects()

GetEffectType()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetEffectType

Use to determine the effect type.

DWORD GetEffectType(
LPCSTR lpszEffectName
);

Parameters

lpszEffectName
Name of effect within the project.

Return Values

The following are valid return values:

IMM_EFFECTTYPE_CONSTANTFORCE
IMM_EFFECTTYPE_RAMPFORCE
IMM_EFFECTTYPE_PERIODIC
IMM_EFFECTTYPE_CONDITION
IMM_EFFECTTYPE_ENCLOSURE
IMM_EFFECTTYPE_ELLIPSE
IMM_EFFECTTYPE_TEXTURE
IMM_EFFECTTYPE_COMPOUND
IMM_EFFECTTYPE_CUSTOMFORCE

If the function fails, the return value is zero, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function provides a simpler way of identifying the type of a given effect. The information can be used to decide how to cast a CImmEffect pointer into a more specific effect object.

Note: GetEffectTypeFromIFR retrieved the same information and is is now obsolete.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::GetEffectType()


CImmProject::GetIsOpen

Determines if a project has been intialized and loaded with data.

BOOL GetIsOpen() const;

Parameters

None.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

A project is initialized once it has been provided with effect data from a file, resource, or memory.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

OpenFile()
LoadProjectFromMemory()
LoadProjectFromResource()
AddEffect()
CreateCompound()


CImmProject::GetNumEffects

Returns the number of effects in the project.

int GetNumEffects();

Parameters

None.

Return Values

If the function succeeds, the return value is the number of effects contained in the project.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If data has not been loaded into the project by calling OpenFile, LoadProjectFromResource, or LoadProjectFromMemory the function will fail. In the case of an empty project, zero will be returned.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffect()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetNumSounds

Returns the number of sounds loaded in the Project.

int GetNumSounds();

Parameters

None.

Return Values

If the function succeeds, the return value is the number of sounds in the Project.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If Project data has not been loaded by calling OpenFile, LoadProjectFromResource, or LoadProjectFromMemory the function will fail. In the case of an empty Project, zero will be returned.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetSoundName()

GetSoundPath()

AddSoundInfo()

OpenFile()


CImmProject::GetSoundName

Allows access to sound object names contained in the project.

LPCSTR GetSoundName(
int nSoundIndex
);

Parameters

nSoundIndex
An integer from 0 to GetNumSounds – 1 assuming GetNumSounds returns a value greater than zero.

Return Values

If the function succeeds, the return value is a pointer to a charater array.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

GetSoundName will return NULL if data has not been loaded into the project or if the index is not in the valid range. OpenFile, LoadProjectFromResource, or LoadProjectFromMemory can be used to load IFR data into the project.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetNumSounds()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetSoundPath

Provides the path and filename of the wave file associated with a sound object.

LPCSTR GetSoundPath(
LPCSTR lpszSoundName,
BOOL bAbsPath
);

Parameters

lpszSoundName
The name of the Sound object that contains the wave file path information.
bAbsPath
Set this to TRUE to obtain the abolute path. Set this to FALSE to obtain the relative path.

Return Values

If the function succeeds, the return value is a character array.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Sound objects contain location information of wave files. The wave file from a sound object included in a compound effect should be played while the effect is played.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetSoundName()

GetNumSounds()


CImmProject::GetSoundData

Returns parameter information contained in the sound object.

DWORD GetSoundData(
LPCSTR lpszSoundName,
int nParamID
);

Parameters

lpszSoundName
The name of the Sound object containing the data of interest.
nParamID
Used to determine the parameter value returned. Set this to one of the following:
IMM_PARAM_DURATION
IMM_PARAM_STARTDELAY

Return Values

If the function succeeds, the return value is a positive value.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Sound objects contain information such as start delay and sound duration. Start delay is the amount of time that passes before playing the sound. Duration is the amount of time that the sound plays. Both time values are given in milliseconds.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetSoundName()

GetNumSounds()


CImmProject::GetTypeName

Returns a string for the effect type.

LPCSTR GetTypeName(
LPCSTR lpszEffectName
);
LPCSTR GetTypeName(
int nEffectIndex
);

Parameters

lpszEffectName
Name of effect within the project.
nEffectIndex
An integer from 0 to GetNumEffects – 1 assuming GetNumEffects returns a value greater than zero.

Return Values

If the function succeeds, a pointer to a character array is returned.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

IFR files contain information about the name of the effect type. The valid strings are generated by Immersion Studio. While GetEffectType provides enough information to differentiate between CImmEffect class types, GetTypeName can be useful when a more descriptive type name is required.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()


CImmProject::LoadProjectFromMemory

Reads IFR data from a location in memory and associates it and a device with the project.

BOOL LoadProjectFromMemory(
LPVOID pProjectDef,
CImmDevice *pDevice
);

Parameters

pProjectDef
Specifies a pointer to memory that contains information in IFR format.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

In cases where a file or resource is not available directly, the calling application can use this function to initialize a project with IFR data contained at a memory location.

Passing in NULL for pDevice is allowed. This is useful for gaining access to effect and sound object data even when a device is not available for effect creation and playback. To assign a device after using OpenFile or one of the Load functions with pDevice set to NULL, pass a valid pDevice when using CreateEffect or Start. The device will then be associated with the Project until Close.

Once file data is loaded and a device is associated with the Project, effects can be created by calling CreateEffect or Start.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromResource()

OpenFile()

CreateEffect()

Start()


CImmProject::LoadProjectFromResource

Loads IFR data from a resource and associates it and a device with the project.

BOOL LoadProjectFromResource(
HMODULE hRsrcModule,
LPCSTR pRsrcName,
CImmDevice *pDevice
);

Parameters

hRsrcModule
Specifies the handle of the executable or DLL containing the IFR resource.
pRsrcName
Specifies the name or MAKEINTRESOURCE(id) identifier of the resource to load.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function is similar to OpenFile. It's used in cases where effect information is located in an IFR resource instead of an IFR file. The resource type must be IMMERSION; otherwise, LoadProjectFromResource will not recognize it as valid IFR data.

Passing in NULL for pDevice is allowed. This is useful for gaining access to effect and sound object data even when a device is not available for effect creation and playback. To assign a device after using OpenFile or one of the Load functions with pDevice set to NULL, pass a valid pDevice when using CreateEffect or Start. The device will then be associated with the Project until Close.

Once file data is loaded and a device is associated with the Project, effects can be created by calling CreateEffect or Start.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

OpenFile()

CreateEffect()

Start()


CImmProject::OpenFile

Opens an IFR or FFE file to be associated with the project.

BOOL OpenFile(
LPCSTR lpszFilePath,
CImmDevice* pDevice
);

Parameters

lpszFilePath
Specifies the path and filename to the IFR or FFE file to be opened. The file extension determines which file type to read.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Passing in NULL for pDevice is allowed. This is useful for gaining access to effect and sound object data even when a device is not available for effect creation and playback. To assign a device after using OpenFile or one of the Load functions with pDevice set to NULL, pass a valid pDevice when using CreateEffect or Start. The device will then be associated with the Project until Close.

Once file data is loaded and a device is associated with the Project, effects can be created by calling CreateEffect or Start.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

LoadProjectFromResource()

CreateEffect()

Start()


CImmProject::Start

Call to start playing an effect.

BOOL Start(
LPCSTR lpszEffectName,
DWORD dwIterations = IMM_EFFECT_DONT_CHANGE,
DWORD dwFlags = 0,
CImmDevice *pDevice = NULL
);

Parameters

lpszEffectName
Specifies the effect from the IFR or FFE file you want to start playing.
dwIterations
Number of times to play the effect in sequence. The envelope is re-articulated with each iteration. To play the effect exactly once, pass 1. To play the effect repeatedly until explicitly stopped, pass INFINITE. If the effect was loaded in through an IFR file, the number of iterations set in the IFR file will be used as the default.
dwFlags
Flags that describe how the effect should be played by the device. The value may be zero or one or more of the following values:

IMM_START_SOLO
All other effects on the device should be stopped before the specified effect is played. If this flag is omitted, then the effect is mixed with existing effects already started on the device.
IMM_START_NODOWNLOAD
Do not automatically download the effect.
pDevice
The CImmDevice the effect will be created on. When left as NULL, the device that the project was initialized with will be used.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

A value other than IMM_EFFECT_DONT_CHANGE will override the iterations setting only during the current call to Start but will not permanently change the iterations value. In order to affect subsequent calls to Start, use CImmEffect::ChangeIterations to change the iterations value.

Start first looks to see if the effect has already been used by this project. If not, CreateEffect is called to create it on the device. Then the effect is started. Since this is done automatically, it isn't necessary to call CreateEffect before calling Start.

The project must be open before calling this method.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateEffect()

CImmEffect::Start()

CImmEffect::ChangeIterations()


CImmProject::Stop

Call to stop playing an effect or effects.

BOOL Stop(
LPCSTR lpszEffectName = NULL
);

Parameters

lpszEffectName
Specifies the named created effect in the project that you want to stop playing. If this is left as NULL, all effects that have been started by this project will be stopped.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Call with the same name you used in your call to Start.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Start()


CImmProject::RemoveFromCompound

Removes a sound object or effect from a compound effect.

BOOL RemoveFromCompound(
LPCSTR lpszCompoundName,
LPCSTR lpszObjectName
);

Parameters

lpszCompoundName
Specifies the name of the compound effect. This compound effect must exist in the project's effect list.
lpszObjectName
Specifies the name of the effect or sound object to be removed from the compound effect.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This function is used to remove an object contained in a compound effect. To add an object to a compound's contained elements use AddToCompound.

The object will be removed from the compound effect, but not the project. To remove an effect or sound from a project, use RemoveEffect or RemoveSound.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CreateCompound()

AddToCompound()

RemoveEffect()

RemoveSound()


CImmProject::RemoveEffect

Removes an effect from the project’s list of effects.

BOOL RemoveEffect(
LPCSTR lpszEffectName
);

Parameters

lpszEffectName
Specifies the name of the effect to be removed.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

RemoveEffect removes the effect from the project and any compound effects that contain it.

A successful call to this function decrements the number of effects in the project. The indices of effects in the project list following the removed effect will be affected by this removal.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddEffect()

GetNumEffects()


CImmProject::RemoveSound

Removes a sound object from the project’s list of sounds.

BOOL RemoveSound(
LPCSTR lpszSoundName
);

Parameters

lpszSoundName
Specifies the name of the sound object to be removed.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

RemoveSound removes the sound object from the project and any compound effects that contain it.

A successful call to this function decrements the number of sounds in the project. The indices of sound objects in the project list following the removed sound object will be affected by this removal.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddSoundInfo()

GetNumSounds()


CImmProject::WriteToFile

Writes data in the project to an IFR or FFE file.

BOOL WriteToFile(
LPCSTR lpszFilename
);

Parameters

lpszFilename
Specifies the name of the file in which the effect information will be written. The file extension must be specified, and the only valid file extensions are .ifr or .ffe.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

All sounds and effects in the project will be written to the output file. Sound objects and Non-Standard DirectX 7 effects such as Compounds, Ellipses, Enclosures, Grids, and Textures cannot be written to an FFE file; however, these can be written to an IFR. Any modifications previously made to the effects will be written to file. Also, several functions can be used to add and remove sounds and effects from the project. These changes will also be reflected in the output file.

The writing of FFE files requires Microsoft DirectX 7. If DX7 or greater is not installed the function will fail and return FALSE.

If WriteToFile returns FALSE, one one of the following codes can be retrieved using CIFCErrors::GetLastErrorCode().

IFC_ERR_NULL_PARAMETER
IFC_ERR_NO_DX7_DEVICE
IFC_ERR_NO_EFFECTS_FOUND
IFC_ERR_ALLOCATION_FAILED

Note: WriteToFile in IFC 2.2 was limited to only writing out effects that had been previously created by calling CreateEffect(), or Start(). In IFC 2.3, this limitation was removed.

Code Example

CImmDevice* pDevice = NULL;
CImmProject MyProject;

pDevice = CImmDevice::CreateDevice(hInstance, ghWnd);

if(!pDevice)
return 0;

if(!MyProject.OpenFile("Effects.ffe", pDevice))
return 0;

MyProject.WriteToFile("BuzzOut.ffe");

MyProject.WriteToFile("BuzzOut.ifr");

MyProject.Close();
if(pDevice)
{
delete pDevice;
pDevice = NULL;
}

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()

AddEffect()

RemoveEffect()

AddSoundInfo()

RemoveSound()

CreateCompound()

AddToCompound()

RemoveFromCompound()


CImmProject::GetCreatedEffect

(OBSOLETE: See GetEffect and note below) Returns the named effect in the project that has been added to the project by either AddEffect or CreateEffect.

CImmCompoundEffect* GetCreatedEffect(
LPCSTR lpszEffectName
);
CImmCompoundEffect* GetCreatedEffect(
int nIndex
);

Parameters

lpszEffectName
Name of contained effect. The effect name is case sensitive.
nIndex
Zero based index number of the requested effect.

Return Values

If the function succeeds, the return value is a pointer to a CImmCompoundEffect object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note: This function is no longer available as of IFC 2.3. The same fuctionality exists in GetEffect. CImmProject lists now contain both created effects (downloaded to a device) and effects that have not been created. Effects need not be created before their data is available through CImmProject and CImmCompoundEffect.

If the effect has not been created, NULL is returned.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

AddEffect()

CreateEffect()

Start()


CImmProject::GetEffectNameFromIFRbyIndex

(OBSOLETE: See GetEffectName and note below) Allows access to effect names contained in IFR data related to the project. The effect need not have been previously loaded through CreateEffect to access its name through this function.

LPCSTR GetEffectNameFromIFRbyIndex(
int nEffectIndex
);

Parameters

nEffectIndex
An integer from 0 to GetNumEffectsFromIFR – 1 assuming GetNumEffectsFromIFR returns a value greater than zero.

Return Values

If the function succeeds, the return value is pointer to a charater array.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note: As of IFC 2.3, all IFR data are loaded into CImmProject during OpenFile. This function is now obsolete. Use GetEffectName as the replacement for this function.

GetEffectNameFromIFRbyIndex will return NULL if IFR data has not been loaded into the project. OpenFile, LoadProjectFromResource, or LoadProjectFromMemory can be used to load IFR data into the project. Names of effects added to the project through AddEffect are not accessible by this function. Only the names of effects contained in the project’s IFR can be obtained through this function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetNumEffectsFromIFR()

GetEffectType()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetEffectTypeFromIFR

(OBSOLETE: See GetEffectType and note below)This function can probe within an IFR file to determine an effect’s type even before the effect is created in the project.

DWORD GetEffectTypeFromIFR(
LPCSTR lpszEffectName
);
DWORD GetEffectTypeFromIFR(
int nEffectIndex
);

Parameters

lpszEffectName
Name of effect within the project.
nEffectIndex
An integer from 0 to GetNumEffectsFromIFR – 1 assuming GetNumEffectsFromIFR returns a value greater than zero.

Return Values

The following are valid return values:

IMM_EFFECTTYPE_CONSTANTFORCE
IMM_EFFECTTYPE_RAMPFORCE
IMM_EFFECTTYPE_PERIODIC
IMM_EFFECTTYPE_CONDITION
IMM_EFFECTTYPE_ENCLOSURE
IMM_EFFECTTYPE_ELLIPSE
IMM_EFFECTTYPE_TEXTURE
IMM_EFFECTTYPE_COMPOUND
IMM_EFFECTTYPE_CUSTOMFORCE

If the function fails, the return value is zero, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note: As of IFC 2.3, all IFR data are loaded into CImmProject during OpenFile. This function is now obsolete. Use GetEffectType as the replacement for this function.

This function provides a simpler way of identifying the type of a given effect. The information can be used to decide how to cast a CImmEffect pointer into a more specific effect object.

This function differs from GetEffectType in that GetEffectTypeFromIFR requires that IFR data be available. GetEffectType will access effects that have already been created OR effects that are in an IFR if available.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectType()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()

CImmEffect::GetEffectType()


CImmProject::GetNumEffectsFromIFR

(OBSOLETE: See GetNumEffects and note below) Use this function to find the number of effects in an IFR file.

int GetNumEffectsFromIFR();

Parameters

None.

Return Values

If the function succeeds, the return value is the number of effects contained in an IFR file or resource.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note: As of IFC 2.3, all IFR data are loaded into CImmProject during OpenFile. This function is now obsolete. Use GetNumEffects as the replacement for this function.

If IFR data has not been loaded into the project by calling OpenFile, LoadProjectFromResource, or LoadProjectFromMemory the function will fail. In the case of an empty IFR file, zero will be returned.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectTypeFromIFR()

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProject::GetEffectSoundPathFromIFR

(OBSOLETE: See GetSoundPath and note below) Provides the path and filename of the wave file associated with a compound effect.

LPCSTR GetEffectSoundPathFromIFR(
LPCSTR lpszFilename
);

Parameters

lpszFilename
The optional path and filename of the sound file associated with a compound effect. This information is only available in IFR files written by Immersion Studio 3.4 and greater.

Return Values

If the function succeeds, the return value is character array.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Note: As of IFC 2.3, a new function that provides both absolute and relative paths was created. This function is now obsolete. Use GetSoundPath as the replacement for this function.

This function provides the relative path in the returned string.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetEffectNameFromIFRbyIndex()

GetIsOpen()

GetNumEffectsFromIFR()


CImmProjects

The CImmProjects class is used for managing a set of projects. It’s useful when several IFR files are to be used.

The following table summarizes the CImmProjects class members:

Construction
CImmProjects | Constructs a CImmProjects object.
Initialization
LoadProjectFromMemory | Reads IFR data from memory and associates it and a device with a new project. The project is added to CImmProjects.
LoadProjectFromResource | Loads the IFR resource and associates it and a device with a new project. The project is added to CImmProjects.
OpenFile | Opens the specified IFR file and associates it and a device with a new project. The project is added to CImmProjects.
Deletion
Close | Closes all associated projects. This is called automatically from ~CImmProjects.
Attributes
GetProject | Returns a pointer to the project with the given index.
Operations
Stop | Stops all playing effects in all associated projects.

Class Hierarchy:

CImmProjects


CImmProjects::Close

Closes all associated projects.

void Close();

Parameters

None.

Return Values

NA

Remarks

This is called automatically from the CImmProjects destructor. Note that projects must be closed to release their effects before the device that those effects were created on is released.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmProjects::GetProject

Use this function to find a project in the CImmProjects list.

CImmProject* GetProject(int index = 0);

Parameters

index
Pass in a project index returned by OpenFile, LoadProjectFromMemory, or LoadProjectFromResource.

Return Values

If the function succeeds, the return value is pointer to the requested CImmProject object.

If the function fails, the return value is NULL, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Do not delete this project as it will be destroyed when CImmProjects is destroyed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

LoadProjectFromResource()

OpenFile()


CImmProjects::LoadProjectFromMemory

Reads IFR data from a location in memory and associates it and a device with a new project. The project is added to the CImmProjects object. In cases where a file or resource is not available directly, the calling application may use this function to add a project from IFR data contained at a memory location.

long LoadProjectFromMemory(
LPVOID pProjectDef,
CImmDevice *pDevice
);

Parameters

pProjectDef
Specifies a pointer to memory that contains information in IFR format.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is a zero-based index value.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The index value returned can be passed to GetProject() to gain access to the associated CImmProject in the projects list. This function returns a negative number if the project can’t be opened.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromResource()

OpenFile()

GetProject()


CImmProjects::LoadProjectFromResource

Loads IFR data from a resource and associates it and a device with a new project. The project is added to the CImmProjects object. This function is similar to OpenFile, and is used in cases where effect information is located in an IFR resource instead of an IFR file.

long LoadProjectFromResource(
HMODULE hRsrcModule,
LPCSTR pRsrcName,
CImmDevice *pDevice
);

Parameters

hRsrcModule
Specifies the handle of the module containing the IFR resource.
pRsrcName
Specifies the name or MAKEINTRESOURCE(id) identifier of the resource to load.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is a zero-based index value.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

IFR resources MUST be of type IMMERSION for this function to recognize the data as valid IFR information.

The index value returned can be passed to GetProject() to gain access to the associated CImmProject in the projects list. This function returns a negative number if the project can’t be opened.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

OpenFile()

GetProject()


CImmProjects::OpenFile

Opens the specified IFR file and associates it and a device with a new project. The project is added to the CImmProjects object.

long OpenFile(
LPCSTR lpszFilePath,
CImmDevice *pDevice
);

Parameters

lpszFilePath
Specifies the path and filename to the IFR you wish to open.
pDevice
Specifies the device that will be used.

Return Values

If the function succeeds, the return value is a zero-based index value.

If the function fails, the return value is -1, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The index value returned can be passed to GetProject() to gain access to the associated CImmProject in the projects list. This function returns a negative number if the project can’t be opened.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

LoadProjectFromMemory()

LoadProjectFromResource()

GetProject()


CImmProjects::Stop

Stops all playing effects in all associated projects.

BOOL Stop();

Parameters

None

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When managing multiple projects with effects playing in all projects, Stop() can be called to stop all effects.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib


CImmRamp

The CImmRamp class is used for creating effects of type IMM_EFFECTTYPE_RAMPFORCE.

The following table summarizes the CImmRamp class members:

Construction
CImmRamp | Constructs a CImmRamp object.
Initialization
Initialize | Creates a Ramp effect on the device and attaches it to the CImmRamp object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of the CImmBox object and updates the effect on the device. Allows box coordinates to be specified as either a rect or as a center point and height and width.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect

CImmRamp


CImmRamp::CImmRamp

Constructs a CImmRamp object.

CImmRamp();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initalize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmRamp::ChangeParameters/Polar

Call these members to change any of the ramp effect’s parameters.

BOOL ChangeParameters(
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lMagStart = IMM_EFFECT_DONT_CHANGE,
LONG lMagEnd = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR
);
BOOL ChangeParametersPolar(
LONG lAngle = IMM_EFFECT_DONT_CHANGE,
DWORD dwDuration = IMM_EFFECT_DONT_CHANGE,
LONG lMagStart = IMM_EFFECT_DONT_CHANGE,
LONG lMagEnd = IMM_EFFECT_DONT_CHANGE,
LPIMM_ENVELOPE pEnvelope = (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR
);

Parameters

lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
Specifies the ramp direction of the effect in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDuration
Specifies the total duration of the ramp effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lMagStart
Specifies the starting magnitude of the ramp effect from -10000 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lMagEnd
Specifies the ending magnitude of the ramp effect from -10000 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pEnvelope
Pointer to a IMM_ENVELOPE structure that describes the new envelope to be used by this effect. If no envelope is to be applied, then this member should be set to NULL. To leave this effect parameter unchanged, use the value (LPIMM_ENVELOPE) IMM_EFFECT_DONT_CHANGE_PTR.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use these member functions to set parameters of a ramp effect. Both a Cartesian and a polar version of this member are provided. Use whichever is most suitable or convenient.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmRamp Change Parameter Functions

These functions change individual effect parameters.

BOOL ChangeStartMagnitude( LONG lMagStart );
BOOL ChangeEndMagnitude( LONG lMagEnd );

Parameters

lMagStart
Specifies the starting magnitude of the ramp effect from -10000 to 10000.
lMagEnd
Specifies the ending magnitude of the ramp effect from -10000 to 10000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParameters()


CImmRamp Get Parameter Functions

These functions get the current values of the effect’s type specific parameters.

BOOL GetStartMagnitude( LONG &lMagStart );
BOOL GetEndMagnitude( LONG &lMagEnd );

Parameters

lMagStart
Specifies the starting magnitude of the ramp effect from -10000 to 10000.
lMagEnd
Specifies the ending magnitude of the ramp effect from -10000 to 10000.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

These functions do not communicate with the device each time a get function is called.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmRamp::Initialize/Polar

Call these members to create a ramp effect on the device and attach it to the CImmRamp object.

BOOL Initialize (
CImmDevice* pDevice,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwDuration = IMM_RAMP_DEFAULT_DURATION,
LONG lMagStart = IMM_RAMP_DEFAULT_MAGNITUDE_START,
LONG lMagEnd = IMM_RAMP_DEFAULT_MAGNITUDE_END,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);
BOOL InitializePolar(
CImmDevice* pDevice,
LONG lAngle = IMM_EFFECT_DEFAULT_ANGLE,
DWORD dwDuration = IMM_RAMP_DEFAULT_DURATION,
LONG lMagStart = IMM_RAMP_DEFAULT_MAGNITUDE_START,
LONG lMagEnd = IMM_RAMP_DEFAULT_MAGNITUDE_END,
LPIMM_ENVELOPE pEnvelope = NULL,
DWORD dwNoDownload = 0
);

Parameters

lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates. To use the default X component, set this parameter to IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates To use the default Y component, set this parameter to IMM_EFFECT_DEFAULT_DIRECTION_Y.
lAngle
Specifies the ramp direction of the effect in hundredths of degrees from 0 to 36000. To use the default angle, set this parameter to IMM_EFFECT_DEFAULT_ANGLE.
dwDuration
Specifies the total duration of the ramp effect in milliseconds. If this value is INFINITE, then the effect has infinite duration. If an envelope has been applied to the effect, then the attack will be applied, followed by an infinite sustain. To use the default duration, set this parameter to IMM_RAMP_DEFAULT_DURATION.
lMagStart
Specifies the starting magnitude of the ramp effect from -10000 to 10000. To use the default magnitude, set this parameter to IMM_RAMP_DEFAULT_MAGNITUDE_START.
lMagEnd
Specifies the ending magnitude of the ramp effect from -10000 to 10000. To use the default magnitude, set this parameter to IMM_RAMP_DEFAULT_MAGNITUDE_END.
pEnvelope
Pointer to a IMM_ENVELOPE structure that describes the new envelope to be used by this effect. If no envelope is to be applied, then this member should be set to NULL.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Both a Cartesian and a polar version of this member are provided. Use whichever is most suitable or convenient.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmSpring

The CImmSpring class is used for creating spring effects of type IMM_EFFECTTYPE_CONDITION. This effect can be used to create snaps to lines at arbitrary angles (see Initialize for more info).

The following table summarizes the CImmSpring class members:

Construction
CImmSpring | Constructs a CImmSpring object.
Initialization
Initialize | Creates a spring effect on the device and attaches it to the CImmSpring object. Direction is specified as a Cartesian XY vector.
InitializePolar | Same as Initialize, but allows direction to be specified in polar coordinates.
Attributes
ChangeParameters | Changes the parameters of a spring effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeParametersPolar | Same as ChangeParameters, but allows direction to be specified in polar coordinates.

Class Hierarchy:

CImmEffect

CImmCondition

CImmSpring


CImmSpring::CImmSpring

Constructs a CImmSpring object.

CImmSpring();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the Initialize member function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmSpring::ChangeParameters

Call this member to change the parameters of a spring effect after you have initialized it.

BOOL ChangeParameters(
POINT pntCenter,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwDeadband = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

pntCenter
The equilibrium point of the spring in screen coordinates. To leave the center point unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT. To use the mouse position at the time the effect is started as the center point unchanged, use the value IMM_EFFECT_MOUSE_POS_AT_START.
lStiffness
The spring coefficient that controls the rate of opposing force increase with respect to position. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwStiffness controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDeadband
Distance in pixels from the center within which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
For a directional spring, specifies the x-component of the direction vector. The direction vector defines the axis on which the spring is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
For a directional spring, specifies the y-component of the direction vector. The direction vector defines the axis on which the spring is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter passed in through the Initialize member function. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParameters to modify spring specific parameters. To change parameters common to all effects use the inherited ChangeBaseParams function.

Springs at an angle can be used to allow the cursor to snap to a line at an arbitrary angle passing through an arbitrary point on the screen. The arbitrary point is specified by pntCenter, and the arbitrary angle is specified by a vector defined by lDirectionX and lDirectionY. Remember that the positive Y direction is defined as down or towards the user. Furthermore, the spring force acts along the vector defined by lDirectionX and lDirectionY, so the mouse is free to move perpendicular to that vector. Therefore, specifying a vector of (1,0) and a pntCenter of (320,240) creates a spring acting along the X direction that passes through the point (320,240). This means the mouse can move freely in the Y direction and is held at X = 320. Similarly, a vector of (0,1) through the same point means the mouse can move freely in the X direction and is held at Y = 240. A vector of (1,1) means the spring acts approximately from the upper left corner of the screen to the lower right of the screen. Using the same pntCenter of (320,240), this would restrict the mouse to moving approximately from the lower left corner of the screen to the upper right corner of the screen and passing through (320,240). Note: We say approximately because screen resolutions are usually wider than they are tall, so a vector of (1,1) in pixels will not go exactly from corner to corner. To specify angles instead of vectors, use the polar form of this function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParametersPolar()


CImmSpring::ChangeParametersPolar

Call this member to change the parameters of a spring effect after you have initialized it.

BOOL ChangeParametersPolar (
POINT pntCenter,
LONG lStiffness = IMM_EFFECT_DONT_CHANGE,
DWORD dwSaturation = IMM_EFFECT_DONT_CHANGE,
DWORD dwDeadband = IMM_EFFECT_DONT_CHANGE,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

Parameters

pntCenter
The equilibrium point of the spring in screen coordinates. To leave the center point unchanged, use the value IMM_EFFECT_DONT_CHANGE_POINT. To use the mouse position at the time the effect is started as the center point unchanged, use the value IMM_EFFECT_MOUSE_POS_AT_START.
lStiffness
The spring coefficient that controls the rate of opposing force increase with respect to position. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwStiffness controls the rate of force increase, dwSaturation limits the maximum force level. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwDeadband
Distance in pixels from the center within which the effect is not active. Must be in the range of 0 to 10,000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the spring is felt. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Use ChangeParametersPolar to modify friction specific parameters. To change parameters common to all effects use the inherited ChangeBaseParamsPolar function.

Springs at an angle can be used to allow the cursor to snap to a line at an arbitrary angle passing through an arbitrary point on the screen. The arbitrary point is specified by pntCenter, and the arbitrary angle is specified by an angle defined by lAngle. Remember that lAngle uses a compass headings convention so that 0 degrees is due north or up and 90 degrees is due east or right. Furthermore, the spring force acts along the angle, so the mouse is free to move perpendicular to that angle. Therefore, specifying a lAngle of 9000 (90 degrees) and a pntCenter of (320,240) creates a spring acting along the X direction that passes through the point (320,240). This means the mouse can move freely in the Y direction and is held at X = 320. Similarly, a lAngle of 0 through the same point means the mouse can move freely in the X direction and is held at Y = 240. A lAngle of -4500 (-45 degrees) means the spring acts approximately from the upper left corner of the screen to the lower right of the screen. Using the same pntCenter of (320,240), this would restrict the mouse to moving approximately from the lower left corner of the screen to the upper right corner of the screen and passing through (320,240). Note: We say approximately because screen resolutions are usually wider than they are tall, so a 45 degree angle in pixels will not go exactly from corner to corner. To specify vectors instead of angles, use the non-polar form of this function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeParamters()


CImmSpring::Initialize

Call this member to create a spring effect on the device and attach it to the CImmSpring object.

BOOL Initialize (
CImmDevice* pDevice,
LONG lStiffness = IMM_SPRING_DEFAULT_STIFFNESS,
DWORD dwSaturation = IMM_SPRING_DEFAULT_SATURATION,
DWORD dwDeadband = IMM_SPRING_DEFAULT_DEADBAND,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
POINT pntCenter = IMM_SPRING_DEFAULT_CENTER_POINT,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
lStiffness
The spring coefficient that controls the rate of opposing force increase with respect to position. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default stiffness, use the value IMM_SPRING_DEFAULT_STIFFNESS.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwStiffness controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_SPRING_DEFAULT_SATURATION.
dwDeadband
Distance in pixels from the center within which the effect is not active. Must be in the range of 0 to 10,000. To use the default deadband, use the value IMM_SPRING_DEFAULT_DEADBAND.
dwfAxis
Flag indicating whether to create a 1-axis, 2-axis or directional effect.
Can be one of the following values:
IMM_EFFECT_AXIS_X
IMM_EFFECT_AXIS_Y
IMM_EFFECT_AXIS_BOTH
IMM_EFFECT_AXIS_DIRECTIONAL

The default axis flag is IMM_EFFECT_AXIS_BOTH.

pntCenter
The equilibrium point of the spring in screen coordinates. To use the default center point, use the value IMM_SPRING_DEFAULT_CENTER_POINT. To use the mouse position at the time the effect is started as the center point unchanged, use the value IMM_EFFECT_MOUSE_POS_AT_START.
lDirectionX
For a directional spring, specifies the X-component of the direction vector. The direction vector defines the axis on which the spring is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default X-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
For a directional spring, specifies the Y-component of the direction vector. The direction vector defines the axis on which the spring is felt. For a 1-axis or 2-axis condition, this parameter is ignored. The effect's axis type is determined by the dwfAxis parameter. To use the default Y-axis vector component, use the value IMM_EFFECT_DEFAULT_DIRECTION_Y.
bUseDeviceCoordinates
Set this flag to TRUE to create springs whose center point can be described in the range -10,000 to 10,000 instead of screen coordinates. Device coordinate springs are needed when using CImmDXDevice objects and relative mode CImmMouse objects. The bUseDeviceCoordinates flag is set only during initialization and cannot be changed with a change parameters function. A spring's center point is usually given in screen coordinates, so this flag is set to FALSE by default.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

Initialize creates the effect object, but does not cause it to play. After calling Initialize, call the Start member function to play the effect.

Springs at an angle can be used to allow the cursor to snap to a line at an arbitrary angle passing through an arbitrary point on the screen. The arbitrary point is specified by pntCenter, and the arbitrary angle is specified by a vector defined by lDirectionX and lDirectionY. Remember that the positive Y direction is defined as down or towards the user. Furthermore, the spring force acts along the vector defined by lDirectionX and lDirectionY, so the mouse is free to move perpendicular to that vector. Therefore, specifying a vector of (1,0) and a pntCenter of (320,240) creates a spring acting along the X direction that passes through the point (320,240). This means the mouse can move freely in the Y direction and is held at X = 320. Similarly, a vector of (0,1) through the same point means the mouse can move freely in the X direction and is held at Y = 240. A vector of (1,1) means the spring acts approximately from the upper left corner of the screen to the lower right of the screen. Using the same pntCenter of (320,240), this would restrict the mouse to moving approximately from the lower left corner of the screen to the upper right corner of the screen and passing through (320,240). Note: We say approximately because screen resolutions are usually wider than they are tall, so a vector of (1,1) in pixels will not go exactly from corner to corner. To specify angles instead of vectors, use the polar form of this function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitializePolar()


CImmSpring::InitializePolar

Call this member to create a spring effect on the device and attach it to the CImmSpring object.

BOOL InitializePolar (
CImmDevice* pDevice,
LONG lStiffness,
DWORD dwSaturation,
DWORD dwDeadband,
POINT pntCenter,
LONG lAngle,
BOOL bUseDeviceCoordinates = FALSE,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
lStiffness
The spring coefficient that controls the rate of opposing force increase with respect to position. This value is applied to both positive and negative directions of travel. Must be in the range -10,000 to 10,000. To use the default stiffness, use the value IMM_SPRING_DEFAULT_STIFFNESS.
dwSaturation
Maximum opposing force. Must be in the range 0 - 10,000. This value is applied to both positive and negative directions of travel. While dwStiffness controls the rate of force increase, dwSaturation limits the maximum force level. To use the default saturation, use the value IMM_SPRING_DEFAULT_SATURATION.
dwDeadband
Distance in pixels from the center within which the effect is not active. Must be in the range of 0 to 10,000. To use the default deadband, use the value IMM_SPRING_DEFAULT_DEADBAND.
pntCenter
The equilibrium point of the spring in screen coordinates. To use the default center point, use the value IMM_SPRING_DEFAULT_CENTER_POINT. To use the mouse position at the time the effect is started as the center point unchanged, use the value IMM_EFFECT_MOUSE_POS_AT_START.
lAngle
The angle of the radial direction vector. This must be given in hundredths of degrees from 0 to 36000. The direction vector defines the axis on which the spring is felt. To use the default angle, use the value IMM_EFFECT_DEFAULT_ANGLE.
bUseDeviceCoordinates
Set this flag to TRUE to create springs whose center point can be described in the range -10,000 to 10,000 instead of screen coordinates. Device coordinate springs are needed when using CImmDXDevice objects and relative mode CImmMouse objects. The bUseDeviceCoordinates flag is set only during initialization and cannot be changed with a change parameters function. A spring's center point is usually given in screen coordintates, so this flag is set to FALSE by default.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitializePolar creates the effect object, but does not cause it to play. After calling InitializePolar, call the Start member function to play the effect. InitializePolar automatically sets dwfAxis to IMM_EFFECT_AXIS_DIRECTIONAL.

Springs at an angle can be used to allow the cursor to snap to a line at an arbitrary angle passing through an arbitrary point on the screen. The arbitrary point is specified by pntCenter, and the arbitrary angle is specified by an angle defined by lAngle. Remember that lAngle uses a compass headings convention so that 0 degrees is due north or up and 90 degrees is due east or right. Furthermore, the spring force acts along the angle, so the mouse is free to move perpendicular to that angle. Therefore, specifying a lAngle of 9000 (90 degrees) and a pntCenter of (320,240) creates a spring acting along the X direction that passes through the point (320,240). This means the mouse can move freely in the Y direction and is held at X = 320. Similarly, a lAngle of 0 through the same point means the mouse can move freely in the X direction and is held at Y = 240. A lAngle of -4500 (-45 degrees) means the spring acts approximately from the upper left corner of the screen to the lower right of the screen. Using the same pntCenter of (320,240), this would restrict the mouse to moving approximately from the lower left corner of the screen to the upper right corner of the screen and passing through (320,240). Note: We say approximately because screen resolutions are usually wider than they are tall, so a 45 degree angle in pixels will not go exactly from corner to corner. To specify vectors instead of angles, use the non-polar form of this function.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Initialize()


CImmTexture

The CImmTexture class is used for creating effects of type IMM_EFFECTTYPE_TEXTURE. Currently only Immersion pointing devices support this type of effect. CImmTexture behaves very similarly to the CImmCondition in that you can create single axis textures, dual axis textures, and directional textures. Please refer to the CImmCondition section for more information about how the CImmTexture class works.

The following table summarizes the CImmTexture class members:

Construction
CImmTexture | Constructs a CImmTexture object.
Initialization
InitTexture | Creates a texture effect on the device and attaches it to the CImmTexture object. Direction is specified as a Cartesian XY vector.
InitTexturePolar | Same as InitTexture, but allows direction to be specified in polar coordinates.
Attributes
ChangeTextureParams | Changes the parameters of a texture effect and updates the effect on the device. Direction is specified as a Cartesian XY vector.
ChangeTextureParamsPolar | Same as ChangeTextureParams, but allows direction to be specified in polar coordinates.
ChangeOffset | Changes the offset of a 2-axis texture, and updates the effect on the device.
Change Parameter Functions | Functions for changing individual type specific parameters.
Get Parameter Functions | Functions for retrieving current type specific parameter values.

Class Hierarchy:

CImmEffect
CImmTexture


CImmTexture::CImmTexture

Constructs a CImmTexture object.

CImmTexture();

Parameters

None.

Return Values

NA

Remarks

This constructor does not create the corresponding Immersion TouchSense COM effect object. It only initializes a class object and assigns the effect GUID. The API COM object is created and downloaded to the device in the InitTexture and InitTexturePolar member functions.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

InitiTexture()


CImmTexture::ChangeTextureParams/Polar

Call these members to change any of the texture effect’s parameters.

/* Use this form for single-axis, dual-axis symetrical, or directional effects */
BOOL ChangeTextureParams(
LONG lPosBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpSpacing = IMM_EFFECT_DONT_CHANGE,
LONG lNegBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpSpacing = IMM_EFFECT_DONT_CHANGE,
POINT pntOffset = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

/* Use this form for single-axis and dual-axis effects */
BOOL ChangeTextureParams(
LPCIMM_TEXTURE pTextureX,
LPCIMM_TEXTURE pTextureY
);

/* Use this form for directional effects */
BOOL ChangeTextureParams(
LPCIMM_TEXTURE pTexture,
LONG lDirectionX,
LONG lDirectionY
);

/* Use this form for single-axis, dual-axis symetrical, or directional effects */
BOOL ChangeTextureParamsPolar(
LONG lPosBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpSpacing = IMM_EFFECT_DONT_CHANGE,
LONG lNegBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpSpacing = IMM_EFFECT_DONT_CHANGE,
POINT pntOffset = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lAngle = IMM_EFFECT_DONT_CHANGE
);

/* Use this form for directional effects */
BOOL ChangeTextureParamsPolar(
LPCIMM_TEXTURE pTexture,
LONG lAngle
);

Parameters

lPosBumpMag
Specifies the magnitude of the texture bumps when moving in the positive direction from -10000 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPosBumpWidth
Specifies the width of a texture bump when moving in the positive direction in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwPosBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the positive direction in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lNegBumpMag
Specifies the magnitude of the texture bumps when moving in the negative direction from -10000 to 10000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegBumpWidth
Specifies the width of a texture bump when moving in the negative direction in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
dwNegBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the negative direction in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pntOffset
Specifies the offset from the left or top edge of the screen or enclosure to the first texture bump in screen pixels. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
lAngle
Specifies the positive direction of the effect in hundredths of degrees from 0 to 36000. To leave this effect parameter unchanged, use the value IMM_EFFECT_DONT_CHANGE.
pTexture
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters.
pTextureX
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters for the X axis.
pTextureY
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters for the Y axis.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

This member function has several forms and behaves very similarly to the CImmCondition::ChangeConditionParams and CImmCondition::ChangeConditionParamsPolar member functions.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeOffset()

Change Function Parameters

CImmCondition::ChangeConditionParams()

CImmCondition::ChangeConditionParamsPolar()


CImmTexture Change Parameter Functions

Call these functions to change the parameters of a Texture effect after you have initialized it. The parameters passed in by these functions affect the Texture in either the X-Axis or Y-Axis only.

BOOL ChangeTextureParamsX(
LONG lPosBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpSpacing = IMM_EFFECT_DONT_CHANGE,
LONG lNegBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpSpacing = IMM_EFFECT_DONT_CHANGE,
POINT pntOffset = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);
BOOL ChangeTextureParamsY(
LONG lPosBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwPosBumpSpacing = IMM_EFFECT_DONT_CHANGE,
LONG lNegBumpMag = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpWidth = IMM_EFFECT_DONT_CHANGE,
DWORD dwNegBumpSpacing = IMM_EFFECT_DONT_CHANGE,
POINT pntOffset = IMM_EFFECT_DONT_CHANGE_POINT,
LONG lDirectionX = IMM_EFFECT_DONT_CHANGE,
LONG lDirectionY = IMM_EFFECT_DONT_CHANGE
);

Parameters

lPosBumpMag
Specifies the magnitude of the texture bumps when moving in the positive direction from -10000 to 10000.
dwPosBumpWidth
Specifies the width of a texture bump when moving in the positive direction in screen pixels.
dwPosBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the positive direction in screen pixels.
lNegBumpMag
Specifies the magnitude of the texture bumps when moving in the negative direction from -10000 to 10000.
dwNegBumpWidth
Specifies the width of a texture bump when moving in the negative direction in screen pixels.
dwNegBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the negative direction in screen pixels.
pntOffset
Specifies the offset from the left or top edge of the screen or enclosure to the first texture bump in screen pixels.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

When the desired change is to affect both axes, the general ChangeTextureParameters function should be used. Change functions for each parameter are available for modifying an individual parameter. When changing multiple parameters at once do not use the individual parameter change functions. Making multiple calls will increase communication to the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeOffset()

ChangeTextureParameters()


CImmTexture Get Parameter Functions

To find out the current value of an effect parameter pass a variable of the appropriate data type to one of the get functions. The value returned in that variable will be the current setting.

BOOL GetPositiveBumpMagX( LONG &lPosBumpMag );
BOOL GetNegativeBumpMagX( LONG &lNegBumpMag );
BOOL GetPositiveBumpSpacingX( DWORD &dwPosBumpSpacing );
BOOL GetNegativeBumpSpacingX( DWORD &dwNegBumpSpacing );
BOOL GetPositiveBumpWidthX( DWORD &dwPosBumpWidth );
BOOL GetNegativeBumpWidthX( DWORD &dwNegBumpWidth );
BOOL GetPositiveBumpMagY( LONG &lPosBumpMag );
BOOL GetNegativeBumpMagY( LONG &lNegBumpMag );
BOOL GetPositiveBumpSpacingY( DWORD &dwPosBumpSpacing );
BOOL GetNegativeBumpSpacingY( DWORD &dwNegBumpSpacing );
BOOL GetPositiveBumpWidthY( DWORD &dwPosBumpWidth );
BOOL GetNegativeBumpWidthY( DWORD &dwNegBumpWidth );
BOOL GetOffset( POINT &pntOffset );

Parameters

lPosBumpMag
Specifies the magnitude of the texture bumps when moving in the positive direction from -10000 to 10000.
dwPosBumpWidth
Specifies the width of a texture bump when moving in the positive direction in screen pixels.
dwPosBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the positive direction in screen pixels.
lNegBumpMag
Specifies the magnitude of the texture bumps when moving in the negative direction from -10000 to 10000.
dwNegBumpWidth
Specifies the width of a texture bump when moving in the negative direction in screen pixels.
dwNegBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the negative direction in screen pixels.
pntOffset
Specifies the offset from the left or top edge of the screen or enclosure to the first texture bump in screen pixels.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

The use of these get functions does not increase the frequency of communication with the device.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

Change Parameter Functions


CImmTexture::InitTexturePolar

Call this member to create a texture effect on the device and attach it to the CImmTexture object.

/* Use this form for single-axis and dual-axis effects */
BOOL InitTexture(
CImmDevice* pDevice,
LPCIMM_TEXTURE pTextureX,
LPCIMM_TEXTURE pTextureY,
DWORD dwNoDownload = 0
);

/* Use this form for directional effects */
BOOL InitTexture(
CImmDevice* pDevice,
LPCIMM_TEXTURE pTexture,
LONG lDirectionX,
LONG lDirectionY,
DWORD dwNoDownload = 0
);

/* Use this form for directional effects */
BOOL InitTexturePolar(
CImmDevice* pDevice,
LPCIMM_TEXTURE pTexture,
LONG lAngle,
DWORD dwNoDownload = 0
);

/* Use this form for single-axis, dual-axis or symetrical effects */
BOOL InitTexture(
CImmDevice* pDevice,
LONG lPosBumpMag = IMM_TEXTURE_DEFAULT_MAGNITUDE,
DWORD dwPosBumpWidth = IMM_TEXTURE_DEFAULT_WIDTH,
DWORD dwPosBumpSpacing = IMM_TEXTURE_DEFAULT_SPACING,
LONG lNegBumpMag = IMM_TEXTURE_DEFAULT_MAGNITUDE,
DWORD dwNegBumpWidth = IMM_TEXTURE_DEFAULT_WIDTH,
DWORD dwNegBumpSpacing = IMM_TEXTURE_DEFAULT_SPACING,
DWORD dwfAxis = IMM_EFFECT_AXIS_BOTH,
POINT pntOffset = IMM_TEXTURE_DEFAULT_OFFSET_POINT,
LONG lDirectionX = IMM_EFFECT_DEFAULT_DIRECTION_X,
LONG lDirectionY = IMM_EFFECT_DEFAULT_DIRECTION_Y,
DWORD dwNoDownload = 0
);

Parameters

pDevice
Points to CImmDevice object that represents the device on which the effect is to be created. The device must have been successfully initialized, or this member function will fail.
lPosBumpMag
Specifies the magnitude of the texture bumps when moving in the positive direction from -10000 to 10000. To use the default magnitude, set this parameter to IMM_TEXTURE_DEFAULT_MAGNITUDE.
dwPosBumpWidth
Specifies the width of a texture bump when moving in the positive direction in screen pixels. To use the default width, set this parameter to IMM_TEXTURE_DEFAULT_WIDTH.
dwPosBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the positive direction in screen pixels. To use the default spacing, set this parameter to IMM_TEXTURE_DEFAULT_SPACING.
lNegBumpMag
Specifies the magnitude of the texture bumps when moving in the negative direction from -10000 to 10000. To use the default magnitude, set this parameter to IMM_TEXTURE_DEFAULT_MAGNITUDE.
dwNegBumpWidth
Specifies the width of a texture bump when moving in the negative direction in screen pixels. To use the default width, set this parameter to IMM_TEXTURE_DEFAULT_WIDTH.
dwNegBumpSpacing
Specifies the center-to-center spacing of the texture bumps when moving in the negative direction in screen pixels. To use the default spacing, set this parameter to IMM_TEXTURE_DEFAULT_SPACING.
pntOffset
Specifies the offset from the left or top edge of the screen or enclosure to the first texture bump in screen pixels. To use the default spacing, set this parameter to IMM_TEXTURE_DEFAULT_OFFSET_POINT.
lDirectionX
Specifies the X component of the effect direction in Cartesian coordinates. To use the default X component, set this parameter to IMM_EFFECT_DEFAULT_DIRECTION_X.
lDirectionY
Specifies the Y component of the effect direction in Cartesian coordinates To use the default Y component, set this parameter to IMM_EFFECT_DEFAULT_DIRECTION_Y.
lAngle
Specifies the positive direction of the effect in hundredths of degrees from 0 to 36000. To use the default angle, set this parameter to IMM_EFFECT_DEFAULT_ANGLE.
pTexture
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters.
pTextureX
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters for the X axis.
pTextureY
Pointer to a IMM_TEXTURE structure filled with the desired texture parameters for the Y axis.
dwNoDownload
Optional flag that postpones effect download to the device until the effect is played. Set to IMM_PARAM_NODOWNLOAD to prevent download on initialize. This option is recommended if many effects are being initialized at one time.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

InitTexture creates the effect object, but does not cause it to play. After calling InitTexture, call the Start member function to play the effect.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

CImmEffect::Start()


CImmTexture::ChangeOffset

Call this member to change the texture effect’s offset only.

BOOL ChangeOffset(
POINT pntOffset
);

Parameters

pntOffset
Specifies the offset from the left or top edge of the screen or enclosure to the first texture bump in screen pixels.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, and CIFCErrors::GetLastErrorCode() can be used to retrieve more information about the function failure.

Remarks

If multiple parameters need to be changed, use the one of the chnage parameters calls instead of the individual change functions.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

ChangeTextureParameters()

Change Texture Functions


ClFCErrors

IFC Reference

CIFCErrors

Many calls in IFC return a BOOL indicating whether the call succeeded or failed. The CIFCErrors class maintains information about errors encountered during calls to IFC, so you and your code can examine why a call fails.

The following table summarizes the CIFCErrors class members:

Globals
GetLastErrorCode | Returns the last error code from an IFC routine.
SetErrorHandling | Tells IFC how you want errors to be handled.

Class Hierarchy:

CIFCErrors


CIFCErrors::GetLastErrorCode

Returns the last error code from an IFC routine. Alternatively, the IFC_GET_LAST_ERROR macro can be used for easier coding. IFC_GET_LAST_ERROR is defined as CIFCErrors::GetLastErrorCode().

static HRESULT GetLastErrorCode();

Parameters

None.

Return Values

The result will either be the error code portion of an HRESULT (i.e. hresult & 0xFFFF) or one of the following codes defined in IFCErrors.h:

IFC_ERR_OK
IFC_ERR_UNKNOWN_ERROR

IFC_ERR_ALLOCATION_FAILED
IFC_ERR_INVALID_PARAMETER
IFC_ERR_NULL_PARAMETER
IFC_ERR_WRONG_FORM

IFC_ERR_DEVICE_IS_NULL
IFC_ERR_INVALID_GUID
IFC_ERR_EFFECT_NOT_INITIALIZED

IFC_ERR_CANT_INITIALIZE_DEVICE
IFC_ERR_CANT_CREATE_EFFECT
IFC_ERR_CANT_CREATE_EFFECT_FROM_IFR
IFC_ERR_NO_EFFECTS_FOUND
IFC_ERR_EFFECT_NOT_FOUND
IFC_ERR_EFFECT_IS_COMPOUND

IFC_ERR_PROJECT_ALREADY_OPEN
IFC_ERR_PROJECT_NOT_OPEN

IFC_ERR_NO_DX7_DEVICE
IFC_ERR_CANT_WRITE_IFR

IFC_ERR_DINPUT_NOT_FOUND
IFC_ERR_IMMAPI_NOT_FOUND

IFC_ERR_FILE_NOT_FOUND
IFC_ERR_NO_VERSION_INFO

Remarks

When an IFC call returns FALSE, indicating a failure, GetLastErrorCode lets you see why the call failed.

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

SetErrorHandling()


CIFCErrors::SetErrorHandling

Tells IFC how you want errors to be handled. Alternatively, the IFC_SET_ERROR_HANDLING(flag) macro can be used for easier coding. IFC_SET_ERROR_HANDLING(flag) is defined as CIFCErrors::SetErrorHandling(flag).

static void SetErrorHandling(
unsigned long dwFlags
);

Parameters

dwFlags
A combination of zero or more of the following flags defined in IFCErrors.h:
IFC_OUTPUT_ERR_TO_DEBUG
IFC_OUTPUT_ERR_TO_DIALOG
These flags should be "or"ed together. Pass 0 to turn off special error handling.

Return Values

NA

Remarks

The flags have the following meanings.

IFC_OUTPUT_ERR_TO_DEBUG: When an error occurs log a description to the debug window.

IFC_OUTPUT_ERR_TO_DIALOG: When an error occurs display an error dialog. Note that most error messages are technical and indicate some error in the calling program, so are unsuitable for users of your program.

Note that the error code accessible by GetLastErrorCode will be set regardless of the error handling setting.

The default error handling setting is 0 (none).

Requirements

Hardware: Requires an Immersion TouchSense device.
Windows NT/2000: Requires Windows 2000.
Windows 95/98/ME: Requires Windows 98 or later.
Header: Requires IFC.h.
Import Library: IFC23.lib

See Also

GetLastErrorCode()


Maximizing IFC Performance in Your Application

This book offers some suggestions for getting the most out of the Immersion Foundation Classes (IFC). Implementing these concepts in your application will make your touch-enabled applications more effective, more flexible, and better for the end user.

Good Touch Sensations Are Designed

Good audio in a game is not a lot of sounds all played at high volume simultaneously. It is also not one or two sounds played a total of a few times over the entire game sequence. The sounds should be realistic, distinguishable, informative, and well designed to match the mood and environment. The same rules apply to good tactile effect design in any application. In fact, when done really well, both sound and touch should seem like natural extensions of the application that add more realism and offer cues not possible with graphics alone. A good implementation of tactile effects will make a user feel like an important part of the application is missing when those effects are turned off. At the same time, a user should not feel fatigued or numb after using the application for just a short while.


User Adjustable Force Levels

Microsoft Flight Simulator 98 has a nice property page that allows users to adjust the magnitude of all the tactile effects (e.g., engine vibration, g-forces, collisions, etc.). Some players may like a lot of engine vibration for realism, others may want a more subtle engine vibration, and still others may think it is distracting and not want it on at all. Other touch-enabled applications can benefit greatly from a similar level of adjustability. For example, if an application lets users customize the feel of different Windows controls and operations, some users may want to feel a strong snap to window borders while others may want a more subtle feeling. It is really valuable to be able to individually turn on or off and adjust each type of tactile effect in your application. In addition, there should also be an overall force magnitude slider that globally affects all tactile effects in the application. Some people have big, strong hands, and other people have smaller, delicate hands. Furthermore, different devices might vary slightly in strength. A global force magnitude adjustment allows everyone to find a force level comfortable for them and their device.

User Customizable Tactile Effects

As mentioned earlier in the chapter about Immersion Studio, embedding all your tactile effects in an Immersion Studio Resource file allows both you and the end user to customize the forces at any time, even after the application has been released. This is another way of letting the user individually adjust the magnitude of each effect in the application. Furthermore players can share the effects they customize with friends or others on the Internet.

Providing a method for customizing the effects does not mean that a developer is off the hook for implementing a set of default parameters that work well. In fact, there should be a clear way for users to easily return to the default parameters in case they are unable to design a customized set of parameters to their liking. If your application uses an IFR file, this means it should be able to either 1) restore the IFR file to its original state (e.g., from the CD-ROM), or 2) allow the user to disable the use of the external IFR file. For option two, you would actually compile the IFR file as a resource directly into your application and also allow the same IFR file to be read in dynamically. If the user chooses to disable the external IFR file, the application would just use the compiled-in IFR resource instead of the external one.


Use Immersion Studio and IFC

Using Immersion Studio will make your job much easier and your product better. The FFDonuts sample application included in the DX SDK creates three very simple forces. If you look at the source code to FFDonuts, there are three full pages of source code dedicated to creating those three simple effects and seventeen pages of force feedback code overall. The sample application IFCDonuts (included with the IFC SDK) is exactly the same as FFDonuts except for the fact that it uses an IFR file to create the three forces and IFC to help implement the rest of the force feedback. The IFR file took less than five minutes to create in Immersion Studio. Instead of the three full pages of source code to create the effects in FFDonuts, IFCDonuts instead uses less than ten lines of code to generate the exact same effects. And the seventeen pages of force feedback code becomes merely two pages with IFC, with most of it being error-checking and comments. Furthermore, customizing or changing the effects is now a simple task of opening the IFR file in Immersion Studio and changing away without having to rebuild the application.

If you need to modify the effect (e.g., to change its direction or magnitude), you need to use the either the IDirectInputEffect::SetParameters or IFeelitEffect::SetParameters methods. These methods are tricky to use since you have to initialize quite a bit of data and call the method with an assortment of flags depending on what you want to do. IFC provides helper classes for the effects which make it trivial to modify anything about any of the effects you have created.


Creating Realistic Tactile Effects

How Do I Simulate...

These following sections offer many examples of how to use force feedback to add a little zing and excitement to common events in games and applications.

Simulating Steering and Aerodynamic Forces

Use a Spring effect instead of a Constant Force effect to stimulate the g-forces or aerodynamic forces of going through turns instead of a Constant Force effect. A Spring effect is much simpler to use and will give a much smoother transition of forces. Once a Spring effect is created, the Immersion device (not your application) will continually compute how far the joystick is from the Spring Center and output a force proportional to this distance. Therefore, moving the joystick all the way left (a very hard turn) automatically gives more force than moving the joystick halfway to the left (a moderate turn). This is all done with a single Spring effect call. Since the Immersion device is doing this computation, it does not have to wait for further instructions from the host and results in very smooth force transitions as you move the joystick left and right.

High speed turns should have a stronger force (feel stiffer) than low speed turns. Therefore, as you increase speed, you can modify the Spring effect parameters with a higher Stiffness parameter. If you are computing forces already, you can update the Stiffness so that it is proportional to the newly computed force.

If you use a Constant Force effect by itself to simulate steering or aerodynamic forces, force transitions must be done by the host successively updating the Constant Force parameters every frame (or faster). Since smooth force transitions ideally require updates at least every millisecond, relying on the host to update the Constant Force effect will result in very jerky and unstable forces. If you try it both ways (Spring vs. Constant Force), you should definitely feel the difference, particularly if the forces are strong and you try swerving back and forth quickly several times.

This concept also applies to non-driving and non-flying applications. In general, do not let your application try to close the loop with the Immersion device by continually changing the magnitude of a Constant Fore effect. Instead, try to use a Spring effect (or possibly even an Enclosure or Ellipse) and either modify the stiffness or move the center to adjust the feel. With that said, Microsoft Flight Simulator 98 implements its aerodynamic forces using a Constant Force instead of a Spring and does so very convincingly. So it can be done and done well. Just keep in mind that generally a Spring implementation will be easier and never feel bad. Both Gremlin Interactive’s Motorhead and Electronic Arts’ Need For Speed III have really good implementations of steering forces, and both were done using springs.

Catching Air, Fishtailing, or Driving in Grass or Snow

If you simulate the steering forces using a Spring, you can easily create some very cool effects for going airborne, losing traction and fishtailing, or driving through grass or snow. Simply reduce the stiffness significantly (perhaps even setting it to zero) to suddenly make the stick or wheel feel very loose. To exaggerate the effect in snow or ice conditions, use some negative Damping to really make the stick or wheel feel like it has absolutely no traction. Just don’t forget to turn it off!

Simulating Mud, Water, or Ice

If the game has water or mud, you can make your character or vehicle feel like it’s slogging through the water or mud using a Damping effect. The coefficient varies the viscosity so that a high value will feel like very thick molasses or mud and a low value will feel like a thin liquid. As mentioned above, a negative value actually makes the stick or wheel feel slippery like it’s on ice.

Simulating Gravel, Cobblestones, or Wooden Planks

If you are driving over gravel, cobblestones, wooden planks, railroad tracks, or some other kind of rough surface, use a simple periodic effect to simulate vibrations you would feel in such conditions. A square wave and a sine wave of equal magnitude will not feel the same. The square wave will feel stronger or rougher because it has much sharper transitions. The sine wave has very smooth transitions and will therefore feel smoother. A triangle wave falls somewhere in between a square wave and a sine wave. Experiment in Immersion Studio to create a vibration that is best suited for what you are trying simulate.

Simulating Engine Vibration, Jetpack Hum

As mentioned above, a sine wave can generate a very smooth, subtle vibration. This characteristic makes it ideal for simulating engine vibrations or the hum from a jetpack. Use IFC’s ChangeParameters method to modify the period of the effect to match the frequency of the vibration. Microsoft Flight Simulator 98 uses this technique very effectively on takeoff of the Cessna aircraft. Ubisoft’s Redline Racer also does this extremely well.

Simulating Collisions, Bumps, and Getting Hit

One way to really enhance the realism and gameplay is to provide directional information from collisions, bumps, or getting hit by a weapon. If you get hit from behind, set the direction of a Constant Force so that it gives a jolt from behind. Same thing if the hit comes from the side. Also, change the magnitude of the Constant Force so that it corresponds to the magnitude of the collision or hit. By doing these two things, you offer the player convincing environmental cues that just cannot be conveyed with visuals and sounds alone. Again, Ubisoft’s Redline Racer does an exceptional job of simulating the jolts and jars of a motorcycle bouncing up and down while racing across a sandy beach.

Note: If you have a spring effect playing, its restoring force to center can oppose the collision or hit force to the point of making it almost imperceptible. To prevent this from happening and really enhance the hit, turn the spring off right before playing the hit force and turn it back on right after the hit force has finished playing. You can use the GetEffectStatus() method to determine if the effect has finished playing or not. Alternatively, since you know the duration of the hit force, you can restart the spring yourself after you know the duration has elapsed.

The Many Uses of Springs

The Spring command is one of the most versatile and powerful effects you can use. As mentioned above, you can simulate very realistic driving and flying effects with a Spring. You can also create a lot of other really cool effects by cleverly using a Spring. Here are some examples:

Don't Forget a Centering Spring

Most Immersion peripherals replace the physical centering springs with a control panel slider or other type of control that allows the user to decrease the simulated centering spring force or turn it off altogether. A stronger centering spring will tend to reduce the effect of other forces in the game because the spring's force will oppose and or even cancel out a force in the opposite direction. Therefore, many users will turn the default centering spring off in the control panel in order to increase the fidelity of forces. If your game requires spring centering to either aid the user or to enhance gameplay, be sure to create a spring effect. Do not rely on the control panel's automatic spring centering since not everyone's device will have this feature active.

Guide the User, Autopilot

By shifting the center point of the Spring around, you can cause the device to move around by itself, or at least physically guide the user’s movements if the device has a safety sensor that prevents it from moving by itself. Using this method, you can implement a pretty cool autopilot that flies or drives by itself. You can also give the user hints by nudging the device in the right direction. If you want to nudge a joystick forward a bit, just create a Y-axis Spring and set the offset to a negative value (e.g., -2000) to cause the stick to push up slightly.

Simulating a Cliff Ledge

One of the hardest things to do in an action game is to jump from one ledge to another. Inch up a little too far before you jump, and you fall off the cliff. Don’t inch up far enough, and you won’t make it across when you jump. You can use a Spring effect to simulate the feel of toeing the ledge of a cliff and better judge when you’ve inched up as far as possible. The best way to try this quickly is to launch Immersion Studio and play with the Slope effect. In the Slope effect, you’re a little ball on the ledge of a hill, and as soon as you move towards the downward slope, you start to fall down the hill. The slope effect is merely a Spring with a negative spring coefficient.

If you want to simulate the feel of a ledge directly in front of you, create a Y-axis Spring effect with an offset of zero, a positive coefficient of zero (no force if moving backwards), and a negative coefficient of less than zero (e.g., -10000 gives a force that pulls forward if moving forward). Start the effect as soon as the player is right at the edge of the ledge. Now if the player moves forward in the slightest, the joystick or mouse will want to fall forward right off the ledge!

Creating a Black Hole

If you have a black hole or some kind of gravity field, use a Spring to simulate the feel of being pulled into and getting stuck in the field. Imagine an Asteroids-type game (or Space Donuts for you DX SDK fans) with a black hole floating around the screen. If you create a 2-Axis Spring and continually update the X and Y Spring offsets to be proportional to the X and Y screen distances from the ship to the black hole, you will end up with a tractor beam force that always pulls the device towards the black hole. Furthermore, once the ship actually goes into the black hole, the player will feel “stuck.” Because the Spring center will have been set to the current device position, the player will feel a spring resistance in all directions that impedes motion away from the black hole.


Design for Immersion Wheels

If you are developing a driving simulation or some other application that might be used with an Immersion wheel, remember that Immersion wheels only have forces in the X axis. The Y axis is usually controlled by either foot pedals or buttons, neither of which have force feedback. Therefore, any Y axis force in your application will not be felt at all on an Immersion wheel. This also means any effects at an angle will be attenuated by an amount dependent on the angle. For example, a Constant Force of Magnitude 10000 at 45 degrees would push an Immersion joystick in both X and Y to the bottom left corner. However, on an Immersion wheel, only an X force of Magnitude 7071 (square root of 0.5) would be felt. Therefore, it would be greatly beneficial to have a check box in your application that allows the user to specify whether an Immersion joystick or wheel is being used. If the user specifies that he/she is using an Immersion wheel, forces should be mapped as best as possible to give the more effects on the X axis and fewer on the Y axis.

To simulate a jolt on the Y axis, it is very effective to instead use a quick side-to-side jolt on the X axis. For instance, one or two periods of a square wave (created by setting duration to one or two times the period) at about 4 to 8 Hz provides a very convincing bump from behind or shock from hitting the ground after being airborne. Ubisoft’s POD uses this method to create excellent effects for hitting the ground after going airborne and head-on collisions.

Important Note: Some wheel manufacturers try to map forces on the Y axis to the X axis in the device drivers. This allows a force feedback game that has forces primarily on the Y axis because it was not designed for wheels to still get all the effects on an X axis-only wheel. However, not all devices support this functionality. Furthermore, this mapping can cause problems in certain situations. For instance, if a game is using a strong Y axis force to push the joystick backwards to simulate a headwind, mapping this force to the X axis now causes a wheel to be pushed forcefully to the right. Therefore, to avoid wheel mapping problems, the best thing to do is to assume there is no mapping of Y axis forces and design your force feedback properly for a wheel from the outset.


Return Codes

IFC Reference

Check for NULL Pointers and FAILED Return Codes

All the IFC functions return a BOOL indicating whether these functions succeeded or failed. By using the error helper functions described in the tutorial, you can find out the actual HRESULT of the underlying DirectX or Immersion TouchSense API call. Since trying to use a device or effect that failed initialization can cause your application to perform an illegal operation, it is essential to check return values as shown in the tutorial. Ideally, you should check the return codes for all the functions. However, if you are going to check the return code of only one function, make sure you do it for all Initialization calls. This will give you immediate notification if the device did not properly initialize, if the effect you are trying to create is not one of the standard DirectInput effect types, if the device is out of memory, or if the device you are using just doesn’t support the effect. If the effect fails on creation, it obviously will not successfully start when you try to play it. Therefore, performing error checking on initialization is an absolute must.

Common HRESULT Return Codes

Some common HRESULT return codes are listed below. Refer to dinput.h and winerror.h for a more comprehensive list and explanations. There is also an error lookup utility included with Microsoft’s Visual C++ (ERRLOOK.EXE) that translates possible error codes into error messages.

0x00000000L
The operation completed successfully.
0x00000001L
The device exists but is not currently attached.
0x00000001L
The change in device properties had no effect.
0x00000003L
The parameters of the effect were successfully updated, but the effect was not downloaded because the device is not exclusively acquired or because the NODOWNLOAD flag was passed.
0x80070057L
An invalid parameter was passed to the returning function, or the object was not in a state that admitted the function to be called.
0x80040201L
The device is full.
0x80040205L
The operation cannot be performed unless the device is acquired in EXCLUSIVE mode.
0x80040206L
The effect could not be downloaded because essential Information is missing. For example, no axes have been associated with the effect, or no type-specific information has been created.
0x80040208L
An attempt was made to modify parameters of an effect while it is playing. Not all hardware devices support altering the parameters of an effect while it is playing.


Effect Caching

In order to simplify the process of creating touch enabled software, Immersion has included Effect Caching in IFC. Since each device has limited memory, loading too many effects at once will prevent some effects from being played (see Managing Device Memory). To MINIMIZE the occurrence of effect overloading, Effect Caching manages the current number of effects loaded on a device.

Many times an effect will be loaded, played, and left on the device. In this case and in other cases when an effect is not currently playing, IFC will unload a stopped effect in order to load and play another effect as needed. If a previously unloaded effect is required at a later time, IFC searches for an effect to swap out to make room to reload that effect.

Even with Effect Caching managing memory in the background, there are situations when too many effects have been requested for playing. In these instances, IFC will try to manage the requests in the best way possible. To avoid these situations, limit the number of INFINITE playing effects and follow the suggestions in Managing Device Memory.


Managing Device Memory (It’s Not Unlimited!)

IFC Reference

Managing Device Memory

Although IFC does manage device memory usage through Effect Caching, there are some limitations. If there are too many effects playing simultaneously, follow these guidelines.

One of the HRESULT return codes listed in the Check Return Values section is for indicating that the device is full. This means that too many effects have been downloaded to the device, and that there is not enough onboard memory left on the device to download any more. Different devices have different amounts of memory. Some devices may allow you to create twenty effects and have them all reside on the device during the entire duration of your application. Other devices may only successfully create the first ten, then fail creation of the remaining ten once it’s out of memory.

One way to know if a device is out of memory is to check the return codes. However, if you want to be proactive in managing device memory usage instead of waiting until you receive an error, you can use the IDirectInputDevice::GetProperty or IFeelitDevice::GetProperty method with the DIPROP_FFLOADREFGUID or FEELITPROP_FFLOADREFGUID to find out how much memory is still available for use. (Remember, to call DirectX or Immersion TouchSense COM calls from IFC, just get the COM device interface pointer using GetDevice).

The following table shows how much memory different types of effects require on Immersion devices and should help you better optimize your effects. At the time of this writing, there are Immersion gaming devices with 200Kbytes of memory and 400Kbytes of memory for effects and Immersion pointing devices with 400Kbytes of memory. Both are shown in the table.

Force Effect Type | Percentage of Total Effect Memory
 | 200K Memory | 400K Memory
Constant Force | 1% | 0.5%
Ramp Force | 6% | 3%
Periodic | 6% | 3%
Envelope | 7% | 3.5%
1-Axis Condition | 8% | 4%
2-Axis Condition | 16% | 8%
Dynamic | 6% | 3%

In addition to the amount of memory each effect occupies, you must also pay attention to how many total effects are resident on the device. At the time of this writing, some Immersion gaming devices have a maximum of 10 effect slots, and others have a maximum of 20 effect slots, while some Immersion pointing devices have 20 effect slots.

For example, in a device with 200K of memory and a maximum of 10 effect slots, you can successfully download up to 10 Constant forces with envelopes.

(1%constant + 7% envelope) * 10 = 80% full

In this situation, the memory is not completely filled, but there are no more effect slots available. Alternatively, you can have ten 1-axis Springs, but only six 2-axis Springs. In the 2-axis Spring case, memory is the limiting factor.

(16%2-axis condition) * 6 = 96% full

If you exceed the memory limit or the effect slot limit, any further effects will fail on download to the device. Since there is a finite amount of memory on any device, you should optimize the number of effects you implement in your application. Below are a few simple ways of doing so.

Destroy Unused Effects

If you have an effect that is used only once in the entire application, delete the CImmEffect immediately after it has finished playing. Once it has finished playing it does nothing but take up valuable memory on the device until it is destroyed. This practice can also be applied to effects that are used more than once. If you have several effects that are only used in the third level of ten total levels, don’t create them until the third level starts, and destroy them when the third level is over. This frees up more device memory for the remaining levels.

Use ChangeParameters To Represent Several Similar Effects

If you have two or more effects of the same type that are never played simultaneously, create just a single CImmEffect and save the actual parameters for the effects in static variables. Then you need only call ChangeParameters (or its equivalent) with the appropriate parameters to switch between the different effects before playing them. For example, say you have four different types of weapons that all use a periodic effect to simulate firing recoil. If you can only fire one weapon at a time, you only need to create one effect on the device and just modify the duration, magnitude, envelope, and whatever else whenever the user changes weapons. Keep each weapon’s parameters in a separate static variables and call ChangeParameters with the appropriate weapon’s parameters to switch weapons.

Don’t Use Extraneous Envelopes

Adding an envelope to a periodic or constant force effect adds more parameters to the effect and therefore requires more memory on the device. Envelopes are an essential part of creating realistic sensations. However, if your designed sensation has an envelope with little or no effect, just set it to NULL rather than let it take up valuable memory on the device. An example of an envelope with no effect is one in which the attack and fade levels are both equal to the force effect magnitude. Also, envelopes with attack and fade times both less than 50 milliseconds have virtually no effect. The time interval is so small that the envelopes are pretty much imperceptible. In such cases, just do away with the envelope altogether. In Immersion Studio, the default attack and fade times are zero, which result in the envelope being set to NULL.

Don’t Generate White Noise Effects

Just as too many musical notes played simultaneously become indistinguishable and garbled, too many force effects played at once will feel like random noise. You might want to use two or even perhaps three periodic forces each at a very distinct frequency to create very interesting harmonics and a great, single, compound sensation. However, adding more effects to the compound sensation unnecessarily takes up more device memory and just starts to muddy up the overall force effect.


Upcoming Products, Support, and Marketing Opportunities

Upcoming Immersion Products

Immersion Corporation is the leader in Immersion gaming devices (formerly I-FORCE), the force-feedback technology standard that enables gaming peripherals to generate realistic touch sensations. Immersion has been designed to support joysticks, steering wheels, flight yokes, game pads, and other common peripheral products. There are already over two dozen manufacturers of Immersion gaming products (visit our web site to find out about these products). These products have already won numerous awards, and there are many more Immersion products to come.

Immersion Corporation also developed Immersion pointing device technology, a sophisticated “information technology” that enables by-directional physical communication between user and machine. The TouchSense enabled mouse can add so much to traditional mouse applications like educational and children’s software, adventure games, RPG, board games, strategy, etc. With textures, grids, gravity wells, snap-tos, repulsion as well as the traditional DirectX force feedback effects, you can make applications much more tactile, intuitive, and immersive. Logitech’s Wingman Force Feedback Mouse was the first consumer product to use the Immersion pointing device technology and was launched in November 1999.

Opportunities for Software Makers: Branding & Testing

As a software developer who has added force feedback support to your application, you should let your customers know that your title is fully compatible with Immersion hardware peripherals of today and tomorrow. To help you do this, Immersion has established the Immersion Software Branding Program. The intent is to help consumers identify touch-enabled software that works well with their Immersion hardware products. The key to the branding program is the Immersion TouchSense logo: Under terms of their license, all hardware manufacturers that produce Immersion products must affix the Immersion TouchSense logo to their commercial packaging in a prominent location. The Immersion TouchSense logo indicates that the given force feedback peripheral is fully compatible with the Immersion hardware technology standard. All of these hardware products will bear the logo shown below:

As a software maker, you too can take advantage of this widely recognized symbol. Display of the Immersion logo on your packaging will tell consumers that your software is fully compatible with all of the force feedback products mentioned above. If your title was created using Microsoft’s DirectX only or using Immersion Studio and IFC in conjunction with DirectX, your software should be fully compatible with Immersion hardware and is therefore eligible to bear the Immersion mark. If your title was created using the Immersion TouchSense COM API directly or using Immersion Studio and IFC, your software should be fully compatible with Immersion hardware and is therefore eligible to bear the Immersion mark. To participate in the free Branding Program, you simply need to contact developer@immersion.com or register at www.immersion.com. Just look for Software Branding Program in the Developer Area, and you can download the following artwork.

In addition to branding, Immersion offers a free software testing service for developers. If you submit a beta copy of your software title to Immersion, our engineers will test the force feedback functionality on all Immersion products. We will let you know if we find a problem with any of the hardware embodiments mentioned above and ensure your software works well on all of the diverse products that use the Immersion standards. This is a fast and easy way to confirm compatibility with today’s shipping Immersion products as well as tomorrow’s soon-to-be shipping products. Furthermore, by submitting a copy of your software for compatibility testing, you are automatically entered into our annual Immersion Gaming Awards Competition for excellence in force feedback implementations in games. These awards are announced each year at the Game Developer’s Conference with winners receiving trophies as well as possible OEM relationships with Immersion licensees.

To take part in the Immersion Software Testing Program, just send a copy of your software to us at the address at the end of this chapter. If you require a non-disclosure agreement, you can send your NDA by email, mail, or fax.

As always, Immersion is happy to support you in your efforts to add touch sensations to your software titles. For general developer support on force feedback technology, including programming under DirectX, Immersion TouchSense COM, IFC, and Immersion Studio, contact us by email, mail, phone, or fax.

And remember, to keep up to date on force feedback hardware and software development issues, you should check in regularly at our web site: www.immersion.com.

Promotional and Marketing Opportunities

Immersion and all our partners are always demonstrating the newest DirectX force feedback games and touch-enabled applications at all the major trade shows, so it represents an excellent opportunity to get a lot of exposure for your application. Many of our partners also seek to bundle these applications with their products when they ship. We would be happy to help facilitate these OEM relationships. We also continually receive requests from the press for demonstrations of Immersion products with the latest force feedback applications. It is a great chance to get some favorable press about your application in magazines, newspapers, and television shows. If you are interested in any of these opportunities, please contact us.

For TouchSense Software Testing
Attn: Immersion Software Testing

For Developer Relations & Support
Attn: Developer Relations & Support

Immersion Corporation
801 Fox Lane
San Jose, CA 95131

Voice (408) 467-1900
FAX (408) 467-1901

developer@immersion.com

www.immersion.com


Effect GUIDs

CImmConstant GUID_Imm_ConstantForce

CImmDamper GUID_Imm_Damper

CImmEllipse GUID_Imm_Ellipse

CImmEnclosure GUID_Imm_Enclosure

CImmFriction GUID_IMM_Friction

CImmGrid GUID_Imm_Grid

CImmInertia GUID_Imm_Inertia

CImmPeriodic GUID_Imm_SawtoothUp

CImmPeriodic GUID_Imm_SawtoothDown

CImmPeriodic GUID_Imm_Sine

CImmPeriodic GUID_Imm_Square

CImmPeriodic GUID_Imm_Triangle

CImmRamp GUID_Imm_RampForce

CImmSpring GUID_Imm_Spring

CImmTexture GUID_Imm_Texture


Condition Structure

The IMM_CONDITION structure as described below.

typedef struct IMM_CONDITION {
LONG lCenter;
LONG lPositiveCoefficient;
LONG lNegativeCoefficient;
DWORD dwPositiveSaturation;
DWORD dwNegativeSaturation;
LONG lDeadBand;
} IMM_CONDITION;

Members

LCenter
Depending on the type of condition, can have one of the following meanings:

Either the horizontal or the vertical component of the center-point, in screen coordinates. Which component lCenter refers depends on the axis associated with the given IMM_CONDITION structure.

Horizontal, vertical, or directional offset to the dead band range.
LPositiveCoefficient
The coefficient constant on the positive side of the center, in the range -10000 to 10000.
LNegativeCoefficient
The coefficient constant on the negative side of the center, in the range -10000 to 10000.
DwPositiveSaturation
The maximum force output on the positive side of the center, in the range 0 to 10000.
DwNegativeSaturation
The maximum force output on the negative side of the center, in the range 0 to 10000.
LDeadBand
The region where the condition is not active, in the range 0 to 10000.

Friction

For friction, the IMM_CONDITION members have the following meanings:

LCenter
Offset to dead band, with respect to either horizontal, vertical, or directional velocity (depending on the axis associated with the IMM_CONDITION structure that this member is a part of).
LPositiveCoefficient
Coefficient of friction (magnitude of opposing force) for positive direction of travel. Must be in the range -10000 to 10000.
LNegativeCoefficient
Coefficient of friction (magnitude of opposing force) for negative direction of travel. Must be in the range -10000 to 10000.
DwPositiveSaturation
Ignored.
DwNegativeSaturation
Ignored.
LDeadBand
Range of velocity in which effect is not active. Must be in the range 0 to 10000. When adjusted by lCenter, the dead band is from lCenter -DeadBand/2 to lCenter + lDeadBand/2.
Dampers

For damper, the IMM_CONDITION members have the following meanings:

LCenter
Offset to dead band, with respect to either horizontal, vertical, or directional velocity (depending on the axis associated with the IMM_CONDITION structure that this member is a part of).
LPositiveCoefficient
Coefficient of damping (rate at which opposing force increases with respect to velocity) for positive direction of travel. Must be in the range -10000 to 10000.
LNegativeCoefficient
Coefficient of damping (rate at which opposing force increases with respect to velocity) for negative direction of travel. Must be in the range -10000 to 10000.
DwPositiveSaturation
Maximum opposing force for positive direction of travel.
DwNegativeSaturation
Maximum opposing force for negative direction of travel.
LDeadBand
Range of velocity in which effect is not active. Must be in the range 0 to 10000. When adjusted by lCenter, the dead band is from lCenter -DeadBand/2 to lCenter + lDeadBand/2.
Grids

For a grid, the IMM_CONDITION members have the following meanings:

LCenter
If the grid is inside of an enclosure, defines the horizontal and vertical distance, in pixels, from the upper left corner of the enclosure’s deadband to the first snap point. If the grid is stand-alone, defines the horizontal and vertical distance, in pixels, from the upper left corner of screen to the first snap point.
LPositiveCoefficient
Strength of snap points. Must be in the range -10000 to 10000.
LNegativeCoefficient
Ignored.
DwPositiveSaturation
Saturation of snap points. Must be in the range 0 to 10000.
DwNegativeSaturation
Ignored.
LDeadBand
Vertical and horizontal spacing, in pixels, between snap points. Must be in the range 0 to 10000.
Inertia

For inertia, the IMM_CONDITION members have the following meanings:

LCenter
Offset to dead band, with respect to either horizontal, vertical, or directional acceleration (depending on the axis associated with the IMM_CONDITION structure that this member is a part of).
LPositiveCoefficient
Coefficient of inertia (rate at which opposing force increases with respect to acceleration) for positive direction of travel. Must be in the range –10000 to 10000.
LNegativeCoefficient
Coefficient of inertia (rate at which opposing force increases with respect to acceleration) for negative direction of travel. Must be in the range -10000 to 10000.
DwPositiveSaturation
Maximum opposing force for positive direction of travel.
DwNegativeSaturation
Maximum opposing force for negative direction of travel.
LDeadBand
Range of acceleration in which effect is not active. Must be in the range 0 to 10000. When adjusted by lCenter, the dead band is from lCenter -DeadBand/2 to lCenter + lDeadBand/2.
Springs

For springs, the IMM_CONDITION members have the following meanings:

LCenter
Either the horizontal or the vertical component of the center (equilibrium) point of the spring, in screen coordinates. Which component lCenter refers depends on the axis associated with the given IMM_CONDITION structure.
LPositiveCoefficient
Spring coefficient (rate at which opposing force increases with respect to position) for positive direction of travel. Must be in the range -10000 to 10000.
LNegativeCoefficient
Spring coefficient (rate at which opposing force increases with respect to position) for negative direction of travel. Must be in the range -10000 to 10000.
DwPositiveSaturation
Maximum opposing force for positive direction of travel.
DwNegativeSaturation
Maximum opposing force for negative direction of travel.
LDeadBand

Distance in pixels from center-point within which the effect is not active. For a two-axis effect, the dead band area is defined by the following RECT:

{
lCenterhoriz - lDeadBandhoriz/2, // left
lCentervert - lDeadBandvert/2, // right
lCenterhoriz + lDeadBandhoriz/2, // top
lCentervert + lDeadBandvert/2 // bottom
}


Effect Envelope Struct

The IMM_ENVELOPE structure is used by the IMM_EFFECT structure to specify the optional envelope parameters for an effect. The sustain level for the envelope is represented by the dwMagnitude member of the IMM_PERIODIC structure and the lMagnitude member of the IMM_CONSTANTFORCE structure. The sustain time is represented by dwDuration member of the IMM_EFFECT structure.

typedef struct IMM_ENVELOPE {
DWORD dwSize;
DWORD dwAttackLevel;
DWORD dwAttackTime;
DWORD dwFadeLevel;
DWORD dwFadeTime;
} IMM_ENVELOPE, *LPIMM_ENVELOPE;

Members

dwSize
Size of the structure in bytes. This member must be initialized before the structure is used. Set to sizeof( IMM_ENVELOPE ).
dwAttackLevel
Amplitude for the start of the envelope, relative to the baseline, in the range 0 to 10,000. If the effect's type-specific data does not specify a baseline, then the amplitude is relative to zero.
dwAttackTime
The time, in microseconds, to reach the sustain level.
dwFadeLevel
Amplitude for the end of the envelope, relative to the baseline, in the range 0 to 10,000. If the effect's type-specific data does not specify a baseline, then the amplitude is relative to zero.
dwFadeTime
The time, in microseconds, to reach the fade level.


Texture Struct

The IMM_TEXTURE structure defines type-specific parameters for textures. Like IMM_CONDITION, a single IMM_TEXTURE structure is used for each axis. Therefore, either a pointer to a single IMM_TEXTURE structure or an array of IMM_TEXTURE structures is passed in the lpvTypeSpecificParams member of the IMM_EFFECT structure. IMM_TEXTURE’s are used in the IFeelitDevice::CreateEffect method to initialize a new FeelitEffect object. They are also used by the IFeelitEffect::SetParameters and IFeelitEffect::GetParameters methods.

typedef struct IMM_TEXTURE {
DWORD dwSize;
LONG lOffset;
LONG lPosBumpMag;
DWORD dwPosBumpWidth;
DWORD dwPosBumpSpacing;
LONG lNegBumpMag;
DWORD dwNegBumpWidth;
DWORD dwNegBumpSpacing;
} IMM_TEXTURE, *LPIMM_TEXTURE;

Members

dwSize
Size of the structure in bytes. This member must be initialized before the structure is used. Set to sizeof( IMM_TEXTURE ).
lOffset
Offset in pixels of first bump from left or top edge.
lPosBumpMag
Magnitude of damping effect felt when the mouse is traveling in positive direction over a bump. Must be in the range -10000 to 10000.
dwPosBumpWidth
Width, in pixels, of bumps felt when the mouse is traveling in positive direction.
dwPosBumpSpacing
Center-to-Center horizontal spacing, in pixels, of bumps felt when mouse is traveling in positive direction.
lNegBumpMag
Magnitude of damping effect felt when the mouse is traveling in negative direction over a bump. Must be in the range -10000 to 10000.
dwNegBumpWidth
Width, in pixels, of bumps felt when the mouse is traveling in negative direction.
dwNegBumpSpacing
Center-to-Center horizontal spacing, in pixels, of bumps felt when mouse is traveling in negative direction.